CheckFlow — Agent Handbook & Project History

이 문서는 CheckFlow 프로젝트의 전체 개발 내역, 사용자 요구사항, 의사결정 기록, 기술 아키텍처 및 트러블슈팅을 보존하여 향후 작업하는 모든 AI 에이전트와 개발자가 일관되게 작업을 이어갈 수 있도록 작성되었습니다.

1. 프로젝트 개요 & 핵심 요구사항

사용자의 핵심 요구사항:

TickTick 스타일 To-Do 리스트 독립 웹앱:
- 체크리스트는 메인 - 하위(Sub-task) 계층 구조를 갖춤.
- 메인 체크리스트에 귀속된 넓직한 메모장(Markdown 노트) 제공.
셀프호스팅 & 프라이버시 중심 멀티유저:
- SNS 형태가 아닌 개인별 프라이버시가 완벽히 보장되는 독립 멀티유저 플랫폼.
- Docker 배포 지원 (PostgreSQL 포함).
외부 플랫폼 연동 & Import:
- TickTick 등 외부 플랫폼에서 내보내기한 CSV 및 ICS(iCalendar) 파일 Import 지원.
- Galaxy(Android) 폰 연동: DAVx⁵ 앱을 통한 CalDAV/CardDAV (/api/dav) 동기화 지원.
PWA (Progressive Web App):
- 모바일/데스크톱 설치 가능 및 오프라인 캐싱 지원.
디자인 시스템:
- TickTick 급의 심플함 + OneUI / Material You / Vercel 스타일의 직관적이고 미려한 UI.
- 3-Panel 반응형 레이아웃 (사이드바 - 태스크 목록 - 넓은 상세 메모 패널).
추가 요구사항 (Phase 2):
- 다국어 (i18n): 영어(기본) → 한국어 → 일본어 순서 지원.
- 테마 모드: 시스템(System) / 라이트(Light) / 다크(Dark) 3-Way 토글.
- DB 없는 데모/미리보기 모드: 로컬 환경에서 DB 구동 없이도 UI/UX 및 모든 기능을 즉시 시연 및 확인할 수 있는 Demo 모드 지원.
- 인프라: Nginx Proxy Manager (NPM)로 역방향 프록시할 예정이므로 자체 SSL/Nginx 없이 포트 3000 컨테이너로 동작.

2. 기술 스택 (Tech Stack)

Frontend: Next.js 16 (App Router), TypeScript, Vanilla CSS (TailwindCSS 지양, 고품질 CSS Variable 디자인 시스템)
Backend / API: Next.js API Routes (Route Handlers)
ORM / DB: Prisma ORM, PostgreSQL (Production/Docker) + Local/Demo In-Memory/LocalStorage Fallback
Auth: NextAuth.js (Credentials Provider, JWT 전략)
DAV Server: /api/dav/[...path] (iCalendar VTODO 표준 구현, Basic Auth 지원)
PWA: Service Worker (public/sw.js), Web App Manifest (public/manifest.json)
Container: Dockerfile (Node 20 Alpine Standalone), docker-compose.yml (PostgreSQL 16 + Auto migration + App)

3. 주요 결정 및 트러블슈팅 히스토리

[버그 1] Next.js 16 `middleware` Deprecation

현상: Next.js 16 최신 버전에서 src/middleware.ts 빌드 시 오류 발생.
해결: Next.js 16 스펙에 맞춰 src/proxy.ts로 마이그레이션 (export async function proxy(...)).

[버그 2] DAVx⁵ CalDAV/CardDAV 인증 차단 문제

현상: src/proxy.ts에서 미인증 세션을 /login으로 리다이렉트하여, DAVx⁵의 HTTP Basic Auth 요청이 차단됨.
해결: publicPaths에 /api/dav를 추가하여 Basic Auth는 라우트 핸들러 자체에서 검증하도록 예외 처리.

[버그 3] DB 미연결 시 `register/page.tsx` SyntaxError

현상: DB가 닫혀있을 때 서버가 500 에러를 반환하면 프론트엔드의 res.json() 호출 시 JSON 파싱 오류 발생.
해결: 모든 API Route에 try-catch를 씌우고, 클라이언트 res.json() 파싱부를 안전하게 try-catch 처리.

[버그 4] TaskDetail 자동저장 Stale Closure & 타이머 누수

현상: debounce 저장 타이머가 태스크 전환 시 이전 태스크 ID로 저장되거나 언마운트 시 메모리 누수 위험.
해결: useRef(currentTaskId)와 언마운트 cleanup 추가.

4. 롤백 포인트 (Checkpoints)

Git Tag checkpoint-v1.0 / Branch backup-v1.0: 기본 Full-Stack 구조 및 버그픽스 완료 시점.
언제든 문제가 발생하면 git checkout checkpoint-v1.0으로 복구 가능.

5. 향후 작업 가이드 (For Next Agents)

디자인 무결성: 바닐라 CSS 변수(var(--accent), var(--bg-primary) 등)를 준수하고 모바일 반응형(768px 이하)을 항상 고려할 것.
다국어(i18n): 텍스트 추가 시 src/lib/i18n의 en/ko/ja 사전에 키를 반드시 함께 등록할 것.
데모 모드 지원: DB 연결 불가 상태에서도 사용자가 UI를 체험할 수 있는 환경을 유지할 것.

This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ (resolved from this file's directory; in monorepos the next package may not be visible from the repo root) before writing any code. Heed deprecation notices.

This block is written and re-added by next dev — verify at node_modules/next/dist/server/lib/generate-agent-files.js. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.

5.2 KiB Raw Blame History