checkflow/AGENTS.md

CheckFlow — Agent Handbook & Project History

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

---

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

사용자의 핵심 요구사항:

1. TickTick 스타일 To-Do 리스트 독립 웹앱:
   • 체크리스트는 메인 - 하위(Sub-task) 2단계 계층 구조를 갖추며, 양쪽 패널 간 1:1 실시간 동기화.
   • 적응형(Adaptive) 와이드 메모장: 우측 패널의 대부분을 메모장이 차지하며, 작성한 마크다운이 실제 웹 문서처럼 미려한 GUI 형태로 렌더링(Preview & Interactive Checkbox) 지원.
   • 인라인 즉시 수정 UX: 상단 프로젝트 제목 및 태스크 제목을 더블클릭/클릭으로 즉시 수정 가능.
2. 셀프호스팅 & 프라이버시 중심 멀티유저:
   • SNS 형태가 아닌 개인별 프라이버시가 완벽히 보장되는 독립 멀티유저 플랫폼.
   • Docker 배포 지원 (PostgreSQL 16 포함, Dockerfile & docker-compose.yml 완비).
3. 외부 플랫폼 연동 & Import:
   • TickTick 등 외부 플랫폼에서 내보내기한 CSV 및 ICS(iCalendar) 파일 Import 지원 (하단 프로필 메뉴 내 배치).
   • Galaxy(Android) 폰 연동: DAVx⁵ 앱을 통한 CalDAV/CardDAV (/api/dav) 동기화 지원.
4. PWA (Progressive Web App):
   • 모바일/데스크톱 설치 가능 및 오프라인 캐싱 지원.
5. 디자인 시스템 & 반응형 웹앱 UX:
   • TickTick / OneUI / Vercel 디자인 언어.
   • 네이티브 웹앱 느낌의 커스텀 우클릭 컨텍스트 메뉴(ContextMenu) 지원.
   • 부드러운 사이드바 애니메이션 및 화면 테마/언어 컨트롤 잘림 방지.

---

2. 주요 컴포넌트 구조

src/
├── app/
│   ├── layout.tsx / page.tsx / providers.tsx
│   ├── demo/page.tsx                  ← DB 연결 없이 LocalStorage 기반으로 구동되는 완전한 데모 페이지
│   ├── login/page.tsx / register/page.tsx
│   └── api/ (auth, lists, tasks, import, dav)
├── components/
│   ├── layout/
│   │   ├── AppShell.tsx               ← 3-Panel 메인 컨테이너 (실시간 하위 태스크 & 인라인 동기화)
│   │   └── Sidebar.tsx                ← 프로젝트 목록, 언어 셀렉터, 테마 토글, 유저 프로필 팝오버(Import 내장)
│   ├── tasks/
│   │   ├── TaskList.tsx               ← 중앙 체크리스트 (인라인 제목 수정, 하위 태스크 추가, 우클릭 메뉴)
│   │   ├── TaskDetail.tsx             ← 우측 상세 패널 (TickTick 스타일 메타바 + 와이드 메모장 + 하단 하위할일)
│   │   └── MarkdownNoteEditor.tsx     ← 👁️ Preview / ✏️ Edit 탭, 마크다운 툴바, 인터랙티브 체크박스
│   └── ui/
│       ├── LanguageSelector.tsx       ← OneUI/Vercel 스타일 커스텀 글래스모피즘 언어 팝오버
│       └── ContextMenu.tsx            ← 네이티브 웹앱 커스텀 우클릭 컨텍스트 메뉴
└── lib/
    ├── i18n/ (en, ko, ja 사전 및 useI18n 훅)
    ├── mockData.ts                    ← Demo 모드용 LocalStorage Store
    ├── auth.ts / prisma.ts

---

3. 롤백 포인트 (Checkpoints)

• checkpoint-v1.0: 기본 Full-Stack 기반 시점
• checkpoint-v2.0: i18n(EN/KO/JA), 3-Way Theme(System/Light/Dark), Demo Mode 탑재
• checkpoint-v2.1: 리치 마크다운 GUI 렌더러(MarkdownNoteEditor), 적응형 와이드 메모장
• checkpoint-v2.2: 하위 태스크 실시간 동기화 & 인라인 즉시 수정 UX
• checkpoint-v3.0: (현재 최신) 부드러운 사이드바 애니메이션, 테마 버튼 잘림 완벽 해결, Import 기능 프로필 메뉴 이동, 커스텀 웹앱 우클릭 컨텍스트 메뉴, TickTick 스타일 우측 상세 탭 완비

---

4. 개발 규칙 및 주의사항

1. 메모장 우선 원칙: 우측 상세 탭에서 메모장은 항상 메인 영역(flex: 1)을 차지하도록 유지할 것.
2. 웹앱 인터랙션: 브라우저 기본 컨텍스트 메뉴 대신 ContextMenu.tsx를 통해 앱스러운 UX를 유지할 것.
3. i18n 무결성: 텍스트 추가 시 src/lib/i18n의 en, ko, ja 사전에 모두 추가할 것.