todo.sori.studio/docs/spec.md

기술 명세

현재 버전

• v0.0.9

스택

• Vue 3 + Vite(SPA)
• Tailwind CSS, Pretendard(변수 폰트, CDN)
• PWA: vite-plugin-pwa(자동 업데이트 등록)
• 데이터: PocketBase(공식 JS SDK)
• 입력 검증: Zod(src/lib/todoSchema.js)

PocketBase 컬렉션: todos

이 앱은 로그인 사용자 기반으로 동작한다. 권한은 “본인 데이터만 접근”을 기본으로 한다.

users (auth collection)

• PocketBase 기본 users 컬렉션을 사용한다.
• 프런트는 authWithPassword 방식으로 로그인한다.

categories

필드	타입	설명
owner	relation -> users	카테고리 소유자
name	text(noempty)	카테고리 이름
order	number	카테고리 정렬 순서(작을수록 위)

todos

필드	타입	설명
owner	relation -> users	할 일 소유자
category	relation -> categories	소속 카테고리
title	text(noempty)	할 일 제목
done	bool	완료 여부
completedAt	date(nullable)	완료 시각(완료 시 set)
order	number	카테고리 내 정렬 순서(작을수록 위)

API Rules(권장)

아래는 “로그인 사용자 본인 데이터만”을 기준으로 한 예시다. (컬렉션/필드 이름은 실제 설정과 동일해야 한다.)

• categories: list/view/create/update/delete
  • @request.auth.id != "" && owner = @request.auth.id
• todos: list/view/create/update/delete
  • @request.auth.id != "" && owner = @request.auth.id

create 규칙은 레코드에 owner를 포함해 저장하는 것을 전제로 한다. 프런트에서 owner를 항상 설정한다.

환경 변수

이름	설명
VITE_POCKETBASE_URL	PocketBase 루트 URL(끝 슬래시 없음). 브라우저가 접근 가능한 주소여야 한다. 운영 예: https://api.todo.sori.studio
VITE_PUBLIC_APP_URL	사용자에게 보이는 웹앱 URL(끝 슬래시 없음). PWA Web App Manifest의 id 등에 사용. 운영 예: https://todo.sori.studio

Docker Compose 기본 호스트 포트

다른 서비스와의 충돌을 줄이기 위해 호스트에 붙는 포트를 4만 번대로 둔다. docker-compose.yaml 상단 주석과 ports 항목을 기준으로 한다.

• 웹(nginx 정적): 호스트 42881 → 컨테이너 80
• PocketBase: 호스트 42917 → 컨테이너 8090

포트를 바꾼 경우 VITE_POCKETBASE_URL·VITE_PUBLIC_APP_URL의 포트·도메인도 동일하게 맞춘 뒤 이미지를 다시 빌드한다.

Compose에서 container_name 을 고정해 두었다: pocketbase-todo, todo-web. NAS에 같은 이름의 컨테이너가 이미 있으면 docker-compose.yaml에서 바꾼다.

PocketBase 데이터는 호스트 바인드 마운트 ./pb_data:/pb_data를 쓴다(저장소에는 디렉터리만 두고 내용은 Git에 포함하지 않음). 기본 Compose에서는 user를 두지 않아 이미지 기본 사용자로 기동한다(SQLite가 pb_data에 쓸 수 있게). UGREEN 등에서 user: "1000:10" 으로 고정하려면 docker-compose.yaml의 해당 줄 주석을 해제하기 전에 호스트에서 mkdir -p pb_data 후 chown -R 1000:10 pb_data로 소유권을 맞춘다.

버전 정책

• 앱 버전은 package.json의 version과 문서의 v0.0.x 형식을 맞춘다.