13 KiB
13 KiB
CheckFlow — Agent Handbook & Project History
이 문서는 CheckFlow 프로젝트의 전체 개발 내역, 사용자 요구사항, 의사결정 기록, 기술 아키텍처를 보존하여 향후 작업하는 모든 AI 에이전트와 개발자가 일관되게 작업을 이어갈 수 있도록 작성되었습니다. 다음 에이전트에게: 반드시 이 파일을 먼저 읽고, 작업 완료 후 업데이트하라.
1. 프로젝트 개요 & 핵심 요구사항
사용자의 핵심 요구사항:
- TickTick 스타일 To-Do 리스트 독립 웹앱:
- 체크리스트는 메인 - 하위(Sub-task) N단계 계층 구조를 갖추며, 양쪽 패널 간 1:1 실시간 동기화.
- 적응형(Adaptive) 와이드 메모장: 우측 패널의 대부분을 메모장이 차지하며, 마크다운이 GUI로 렌더링됨.
- 인라인 즉시 수정 UX: 프로젝트 제목 및 태스크 제목을 클릭으로 즉시 수정 가능.
- 셀프호스팅 & 프라이버시 중심 멀티유저:
- SNS 형태가 아닌 개인별 프라이버시가 완벽히 보장되는 독립 멀티유저 플랫폼.
- Docker 배포 지원 (PostgreSQL 16 포함, Dockerfile & docker-compose.yml 완비).
- 외부 플랫폼 연동 & Import:
- TickTick CSV/ICS Import 지원 (프로필 메뉴 내 배치).
- Galaxy(Android) 폰 연동: DAVx⁵ 앱을 통한 CalDAV (
/api/dav) 동기화 지원.
- 모바일 바텀시트 드로어:
- 스마트폰에서 우측 상세 탭이 바텀 시트로 아래서 위로 슬라이드업.
- 아래로 120px 이상 스와이프하면 패널 닫힘.
- 오버레이 클릭으로도 패널 닫힘.
2. 주요 컴포넌트 구조
src/
├── app/
│ ├── demo/page.tsx ← DB 없이 LocalStorage 기반 데모 페이지
│ ├── admin/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 탭, 툴바, URL 클릭 지원
│ ├── settings/
│ │ └── SettingsModal.tsx ← Profile/Preferences/Sync/Admin 4탭
│ └── ui/
│ ├── LanguageSelector.tsx ← 글래스모피즘 언어 팝오버
│ ├── ContextMenu.tsx ← 커스텀 우클릭 메뉴
│ └── CommandPalette.tsx ← Ctrl+K 글로벌 검색
└── lib/
├── i18n/ (en, ko, ja + useI18n 훅)
└── mockData.ts ← Demo LocalStorage Store (trash, tags, settings)
3. 롤백 포인트 (Git Tags)
| Tag | 내용 | 날짜 |
|---|---|---|
checkpoint-v0.1.0 |
기본 Full-Stack 기반 | 초기 |
checkpoint-v0.2.0 |
i18n, 3-Way Theme, Demo Mode | - |
checkpoint-v0.2.1 |
리치 마크다운 렌더러, 적응형 메모장 | - |
checkpoint-v0.2.2 |
하위 태스크 실시간 동기화 & 인라인 수정 | - |
checkpoint-v0.3.0 |
사이드바 애니메이션, Import 이동, 커스텀 메뉴, TickTick 스타일 | - |
checkpoint-v0.3.2 |
N-depth 재귀 체크리스트, 태그, 휴지통, 설정 모달, 타임스탬프 | - |
checkpoint-v0.4.0 |
모바일 바텀시트, 스와이프 닫기, 오버레이 | 2026-08-20 |
checkpoint-v0.5.0 |
(현재 최신) VSCode 스타일 무채색 다크 테마, 에디터 조잡한 툴바 제거 & 순수 캔버스 전환, 모듈형 블록 커스텀 (서브태스크 ↔ 노트 순서 스왑 및 스플릿 리사이저 높이 조절), CheckFlow Labs (3컬럼 칸반 보드 뷰), 기본값 복원(Reset to Defaults), 보안 패치 완료 | 2026-08-21 |
4. 구현 완료 기능
- i18n 3개국어 (영어 기본, 한국어, 일본어 사전 100% 무결성)
- VSCode 스타일 무채색 다크 테마 (
#181818,#1e1e1e,#252526,#2d2d2d) - 에디터 툴바 제거 & 심플 캔버스 (조잡한
- [ ]툴바 제거, 순수한 텍스트/마크다운 에디팅) - 모듈형 상세 패널 (Custom Blocks):
- 서브태스크 ↔ 노트 블록 위치 스왑(⇄ Swap)
- 마우스 드래그로 높이 비율(15%~85%)을 실시간 조절하는 스플릿 리사이저(Split Resizer)
- 각 블록별 독립적인 접기/펼치기 및 100% 풀스크린 확장
- 🧪 CheckFlow Labs (실험실 기능):
- 📋 리스트 뷰 ↔ 📊 3컬럼 칸반 보드 뷰 (To Do / In Progress / Done) 원클릭 전환
- 언제든 초기 순정 상태로 되돌리는 기본값 복원 (Reset to Defaults)
- Demo 모드 (LocalStorage 기반 완전한 로컬 구동)
- N단계 재귀 체크리스트 (RecursiveTaskItem)
- 인라인 제목 수정 (더블클릭/엔터/ESC)
- 커스텀 우클릭 컨텍스트 메뉴 (전체 트리)
- Created / Edited 타임스탬프
- 커스텀 태그 (색상 자동 부여)
- 휴지통 (복원/영구삭제/보관 기간 설정)
- 설정 모달 (Profile/Preferences/Labs/Sync/Admin)
- 어드민 대시보드 (
/admin- ADMIN 롤 및 권한 통제 게이트) - 정식 라우트 보호 미들웨어 (
src/middleware.ts인증 & 역할 검증) - API IDOR 및 소유권 교차 검증 (서브태스크 및 리스트 이동)
- CSV / ICS Import Formula Injection 방어
- Ctrl+K 글로벌 명령 팔레트
- TickTick CSV/ICS 임포트
- CalDAV 동기화 안내 (DAVx⁵)
- TickTick 스타일 스마트 퀵애드 툴바 (날짜, 우선순위 프리셋)
- 상단 프로젝트 브레드크럼 & 리스트 이동기 (
📁 프로젝트명 ▾) - 모바일 바텀시트 드로어 (Y축 스와이프, 오버레이)
- FAB 버튼 (모바일 태스크 추가)
5. 개발 규칙 및 보안 원칙
- 최상위 원칙 - 보안, 프라이버시, 안정성:
- 모든 API 요청은 세션 소유권(
userId === session.user.id)을 철저히 검증할 것. - 사용자 입력(마크다운, CSV/ICS 등)은 DOMPurify 및 Formula Sanitize를 반드시 통과할 것.
- 어드민 전용 라우트는
role === "ADMIN"을 서버/미들웨어 레벨에서 필터링할 것.
- 모든 API 요청은 세션 소유권(
- 사용자 주도 커스터마이징 & 공간 효율성:
- 모든 블록과 뷰(리스트/칸반, 서브태스크/노트 스플릿 비율 등)는 사용자가 원하는 대로 직관적으로 조절 가능해야 함.
- 불필요한 조잡한 툴바를 배제하고 심플하고 직관적인 조작성 유지.
- 컨텍스트 메뉴:
ContextMenu.tsx사용, 브라우저 기본 메뉴 비활성화. - i18n 무결성: 새 텍스트는 en/ko/ja 사전에 모두 추가.
- 모바일 CSS 규칙:
detail-panel mobile-open클래스가 바텀시트를 제어.- 모바일:
translateY(100%) → translateY(0)애니메이션. - 데스크탑:
detail-panel이 flex 방향 측면 패널.
- 언어: 사용자 응답 및 에이전트 간 소통은 한국어를 기본으로 할 것.
6. 모델 변경 이력
| 시점 | 모델 |
|---|---|
| 초기 ~ Checkpoint v2.x | Claude Sonnet 4.6 |
| Checkpoint v2.x ~ v3.x | Gemini 2.5 Flash |
| Checkpoint v4.0 | Gemini (현재) |
7. 개발 환경
- 프레임워크: Next.js 15 + Turbopack
- DB: PostgreSQL 16 + Prisma (Demo에서는 LocalStorage 대체)
- 스타일: Vanilla CSS (CSS Variables 디자인 토큰)
- 인증: NextAuth.js
- 배포: Docker + docker-compose.yml
- 로컬 실행:
npm run dev(포트 3000) - Demo 페이지:
http://localhost:3000/demo
1. 프로젝트 개요 & 핵심 요구사항
사용자의 핵심 요구사항:
- TickTick 스타일 To-Do 리스트 독립 웹앱:
- 체크리스트는 메인 - 하위(Sub-task) 2단계 계층 구조를 갖추며, 양쪽 패널 간 1:1 실시간 동기화.
- 적응형(Adaptive) 와이드 메모장: 우측 패널의 대부분을 메모장이 차지하며, 작성한 마크다운이 실제 웹 문서처럼 미려한 GUI 형태로 렌더링(Preview & Interactive Checkbox) 지원.
- 인라인 즉시 수정 UX: 상단 프로젝트 제목 및 태스크 제목을 더블클릭/클릭으로 즉시 수정 가능.
- 셀프호스팅 & 프라이버시 중심 멀티유저:
- SNS 형태가 아닌 개인별 프라이버시가 완벽히 보장되는 독립 멀티유저 플랫폼.
- Docker 배포 지원 (PostgreSQL 16 포함, Dockerfile & docker-compose.yml 완비).
- 외부 플랫폼 연동 & Import:
- TickTick 등 외부 플랫폼에서 내보내기한 CSV 및 ICS(iCalendar) 파일 Import 지원 (하단 프로필 메뉴 내 배치).
- Galaxy(Android) 폰 연동: DAVx⁵ 앱을 통한 CalDAV/CardDAV (
/api/dav) 동기화 지원.
- PWA (Progressive Web App):
- 모바일/데스크톱 설치 가능 및 오프라인 캐싱 지원.
- 디자인 시스템 & 반응형 웹앱 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
├── userPrefs.ts ← 글로벌 사용자 설정 스토어 (v0.6+)
├── useUserPrefs.ts ← 반응형 prefs 훅 + CSS var 인젝터
├── 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: 하위 태스크 실시간 동기화 & 인라인 즉시 수정 UXcheckpoint-v3.0: 부드러운 사이드바 애니메이션, 테마 버튼 잘림 완벽 해결, Import 기능 프로필 메뉴 이동, 커스텀 웹앱 우클릭 컨텍스트 메뉴, TickTick 스타일 우측 상세 탭 완비checkpoint-v0.5.0: 버전 체계 0.x.x 전환, VSCode 무채색 다크 테마, 미니멀 에디터(툴바 제거), 모듈형 블록 스왑/리사이저, 칸반 보드 Labs, 설정 Labs 탭 신설checkpoint-v0.6.0(현재 최신): 글로벌UserPrefs시스템(userPrefs.ts/useUserPrefs.ts) 도입, 사이드바 드래그 리사이저, 디테일 패널 드래그 리사이저, Labs 탭 확장(밀도/폰트/라운드/애니메이션/색조/채도/패널 너비), 뷰 전환(리스트↔칸반) 페이지 리로드 없이 반응, 파스텔 매트 라이트 팔레트 적용
4. 개발 규칙 및 주의사항
- 메모장 우선 원칙: 우측 상세 탭에서 메모장은 항상 메인 영역(
flex: 1)을 차지하도록 유지할 것. - 웹앱 인터랙션: 브라우저 기본 컨텍스트 메뉴 대신
ContextMenu.tsx를 통해 앱스러운 UX를 유지할 것. - i18n 무결성: 텍스트 추가 시
src/lib/i18n의 en, ko, ja 사전에 모두 추가할 것.
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.