CheckFlow — Agent Handbook & Project History

이 문서는 CheckFlow 프로젝트의 전체 개발 내역, 사용자 요구사항, 의사결정 기록, 기술 아키텍처를 보존하여 향후 작업하는 모든 AI 에이전트와 개발자가 일관되게 작업을 이어갈 수 있도록 작성되었습니다. 다음 에이전트에게: 반드시 이 파일을 먼저 읽고, 작업 완료 후 업데이트하라.

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

사용자의 핵심 요구사항:

TickTick 스타일 To-Do 리스트 독립 웹앱:
- 체크리스트는 메인 - 하위(Sub-task) N단계 계층 구조를 갖추며, 양쪽 패널 간 1:1 실시간 동기화.
- 적응형(Adaptive) 와이드 메모장: 우측 패널의 대부분을 메모장이 차지하며, 작성한 마크다운이 실제 웹 문서처럼 미려한 GUI 형태로 렌더링(Preview & 안전한 새 탭 링크 지원).
- 인라인 즉시 수정 UX: 상단 프로젝트 제목 및 태스크 제목을 더블클릭/클릭으로 즉시 수정 가능 (Enter 저장, ESC 취소).
셀프호스팅 & 프라이버시 중심 멀티유저:
- 개인별 프라이버시가 완벽히 보장되는 독립 멀티유저 플랫폼.
- Docker 배포 지원 (PostgreSQL 16 포함, Dockerfile & docker-compose.yml 완비).
외부 플랫폼 연동 & Import/Export:
- TickTick 등 외부 플랫폼과의 호환을 위한 CSV 및 ICS(iCalendar) 파일 Import/Export 완벽 지원 (하단 프로필 메뉴 내 배치).
- Formula Injection 방어(sanitizeFormula) 및 Excel 호환 UTF-8 BOM 지원.
- Android 모바일 연동: DAVx⁵ 앱을 통한 CalDAV (/api/dav) 표준 양방향 동기화 지원.
PWA (Progressive Web App):
- 모바일/데스크톱 설치 가능 및 오프라인 캐싱 지원 (manifest.json, sw.js).
모바일 바텀시트 드로어:
- 스마트폰에서 우측 상세 탭이 바텀 시트로 아래서 위로 슬라이드업.
- 아래로 120px 이상 스와이프하면 패널 닫힘.
- 오버레이 클릭으로도 패널 닫힘.
디자인 시스템 & 반응형 커스터마이징:
- VSCode 무채색 다크 테마 및 파스텔 매트 라이트 팔레트 지원.
- 사이드바 및 우측 디테일 패널 마우스 드래그 리사이저.
- 글로벌 UserPrefs 시스템(userPrefs.ts / useUserPrefs.ts) 기반 UI 밀도, 폰트 크기, 모서리 라운드, 테마 색조/채도, 애니메이션 속도 커스터마이징 지원.

2. 주요 컴포넌트 구조

src/
├── app/
│   ├── layout.tsx / page.tsx / providers.tsx
│   ├── demo/page.tsx                  ← DB 연결 없이 LocalStorage 기반으로 구동되는 완전한 데모 페이지
│   ├── login/page.tsx / register/page.tsx
│   ├── admin/page.tsx                 ← 어드민 대시보드 (ADMIN 역할 및 통제 게이트)
│   └── api/ (auth, lists, tasks, import, dav)
├── components/
│   ├── layout/
│   │   ├── AppShell.tsx               ← 3-Panel 메인 컨테이너 (실시간 하위 태스크 & 인라인 동기화, 모바일 오버레이)
│   │   └── Sidebar.tsx                ← 프로젝트 목록, 언어 셀렉터, 테마 토글, 유저 프로필 팝오버(Import 내장)
│   ├── tasks/
│   │   ├── TaskList.tsx               ← 중앙 체크리스트 (N-depth 재귀 트리, 인라인 제목 수정, 우클릭 메뉴)
│   │   ├── TaskDetail.tsx             ← 우측 상세 패널 (모듈형 블록 스왑, 스플릿 리사이저, 바텀시트 터치)
│   │   ├── MarkdownNoteEditor.tsx     ← 👁️ Preview / ✏️ Edit 탭, 심플 캔버스, DOMPurify XSS 방어
│   │   └── KanbanView.tsx             ← CheckFlow Labs 3컬럼 칸반 보드 (To Do / In Progress / Done)
│   ├── settings/
│   │   └── SettingsModal.tsx          ← Profile / Preferences / Labs / Sync / Admin 5탭 모달
│   └── ui/
│       ├── LanguageSelector.tsx       ← 글래스모피즘 언어 팝오버
│       ├── ContextMenu.tsx            ← 커스텀 우클릭 컨텍스트 메뉴
│       └── CommandPalette.tsx         ← Ctrl+K 글로벌 명령 팔레트
└── lib/
    ├── i18n/ (en, ko, ja 사전 및 useI18n 훅)
    ├── mockData.ts                    ← Demo LocalStorage Store (trash, tags, settings)
    ├── userPrefs.ts                   ← 글로벌 사용자 설정 스토어 (v0.6+)
    ├── useUserPrefs.ts                ← 반응형 prefs 훅 + CSS var 인젝터
    ├── auth.ts / prisma.ts

3. 롤백 포인트 (Git Tags & Checkpoints)

Tag / Checkpoint	내용	일자
`checkpoint-v0.1.0` (`checkpoint-v1.0`)	기본 Full-Stack 기반 시점	초기
`checkpoint-v0.2.0` (`checkpoint-v2.0`)	i18n(EN/KO/JA), 3-Way Theme(System/Light/Dark), Demo Mode 탑재	-
`checkpoint-v0.2.1` (`checkpoint-v2.1`)	리치 마크다운 GUI 렌더러(MarkdownNoteEditor), 적응형 와이드 메모장	-
`checkpoint-v0.2.2` (`checkpoint-v2.2`)	하위 태스크 실시간 동기화 & 인라인 즉시 수정 UX	-
`checkpoint-v0.3.0` (`checkpoint-v3.0`)	사이드바 애니메이션, Import 기능 프로필 메뉴 이동, 커스텀 우클릭 컨텍스트 메뉴	-
`checkpoint-v0.3.2`	N-depth 재귀 체크리스트, 태그, 휴지통, 설정 모달, 타임스탬프	-
`checkpoint-v0.4.0`	모바일 바텀시트 드로어, Y축 스와이프 닫기, 모바일 백드롭 오버레이	2026-08-20
`checkpoint-v0.5.0`	VSCode 무채색 다크 테마, 에디터 조잡한 툴바 제거 & 순수 캔버스 전환, 모듈형 블록 커스텀 (서브태스크 ↔ 노트 순서 스왑 및 스플릿 리사이저 높이 조절), CheckFlow Labs (3컬럼 칸반 보드 뷰), 기본값 복원(Reset to Defaults), 보안 패치 완료	2026-08-21
`checkpoint-v0.6.0`	글로벌 `UserPrefs` 시스템(`userPrefs.ts` / `useUserPrefs.ts`) 도입, 사이드바 드래그 리사이저, 디테일 패널 드래그 리사이저, Labs 탭 확장(밀도/폰트/라운드/애니메이션/색조/채도/패널 너비), 뷰 전환(리스트↔칸반) 실시간 반응, 파스텔 매트 라이트 팔레트 적용	2026-08-21
`checkpoint-v0.6.1`	CalDAV / DAVx⁵ 양방향 동기화 프로토콜 고도화(OPTIONS, PROPFIND, REPORT, PUT, DELETE), 설정 모달 내 플랫폼별(Android DAVx⁵ / Apple Reminders / Thunderbird) 인터랙티브 가이드 및 실시간 엔드포인트 테스트 핑, 다국어 i18n 동기화	2026-08-21
`checkpoint-v0.6.2`	표준 태스크 내보내기(Export) 기능 구현: TickTick/RFC 4180 호환 CSV (UTF-8 BOM 포함) 및 RFC 5545 iCalendar (`.ics` VTODO), 사이드바 프로필 메뉴 연동, 데모 모드 로컬 Blob 내보내기 지원, 다국어 사전 동기화	2026-08-21
`checkpoint-v0.6.3`	노션 스타일 6도트 드래그 핸들(`⋮⋮`) & DND 태스크 재정렬, F2 단축키 인라인 제목 수정, 우측 호버 서브태스크 추가 버튼, 6초 플로팅 인터랙티브 실행 취소(Undo) 토스트 배너 탑재, 휴지통 및 로컬 스토리지 트리 중복 버그 수정	2026-08-21
`checkpoint-v0.6.4`	i18n 모듈러 사전 아키텍처(`types.ts`, `locales/en.ts`, `locales/ko.ts`, `locales/ja.ts`) 분리 및 번역 완성도 100%, 어드민 콘솔(`/admin`) 데모 프리뷰 및 멀티유저 게이트 연동, 설정 모달 Admin 탭 정보 고도화, 사이드바 프로필 메뉴 내 Admin Console 진입점 추가	2026-08-21
`checkpoint-v0.7.0`	좌측 사이드바 UI/UX 전면 리디자인(브랜드 로고 SVG, 중앙정렬 매트 검색창, 바닥 밀착 프로필), 뷰 전환(리스트/칸반) 미니멀 원터치 토글 및 실험실 연동 버그 수정, 휴지통 카운트 실시간 동기화 & 기본화면 튕김 버그 수정, 첫 가입 계정 자동 ADMIN 승격 및 실시간 Admin API(/api/admin/users, /api/admin/stats) 구축, 서브태스크 인라인 추가 및 체크박스 Optimistic UI 실시간 렌더링, 메모장 기본 Preview 모드 & 원터치 토글, N-depth 계층형 DND 드래그 앤 드롭 재정렬 및 재귀 하위 태스크 캐스케이드 삭제 지원	2026-08-21
`checkpoint-v0.7.1`	설정 모달(5개 탭 및 가이드/프리뷰 전면) i18n 3개국어(EN/KO/JA) 100% 완전 번역 및 언어 로컬스토리지 영구 기억/자동 감지 적용, 태스크 목록 제목 인라인 수정 시 완료항목 토글 버튼 밀림 flexbox 레이아웃 버그 수정, 메모장 프리뷰/에디터 높이 및 플레이스홀더 타이포그래피 일관성 보정, 우측 상세 패널 우선순위 브라우저 기본 드롭다운을 중앙 퀵애드와 동일한 세련된 컬러 팝오버 칩 UI로 통일	2026-08-22
`checkpoint-v0.7.2`	(현재 최신) 태그(Tag) 사용자 계정별 데이터베이스 격리 API 구축(/api/tags), DND 드래그앤드롭 상위 태스크 하위 편입 단일화 및 빈 배경 드롭 1단계 승격 지원, 완료항목 토글 시 로딩 UI 밀림 버그 수정, 인라인 제목 수정 더블클릭 영역 텍스트 한정, 어드민 콘솔 다국어(i18n) 언어 선택기 지원, 친절하고 간결한 톤앤매너 플레이스홀더 전면 적용	2026-08-22

4. 구현 완료 기능 요약

i18n 3개국어 (영어 기본, 한국어, 일본어 사전 100% 무결성)
VSCode 스타일 무채색 다크 테마 (#181818, #1e1e1e, #252526, #2d2d2d) 및 파스텔 라이트 테마
에디터 툴바 제거 & 심플 캔버스 (조잡한 - [ ] 툴바 제거, 순수한 텍스트/마크다운 에디팅)
모듈형 상세 패널 (Custom Blocks):
- 서브태스크 ↔ 노트 블록 위치 스왑(⇄ Swap)
- 마우스 드래그로 높이 비율(15%~85%)을 실시간 조절하는 스플릿 리사이저(Split Resizer)
- 각 블록별 독립적인 접기/펼치기
🧪 CheckFlow Labs (실험실 기능):
- 📋 리스트 뷰 ↔ 📊 3컬럼 칸반 보드 뷰 (To Do / In Progress / Done) 원클릭 전환
- 언제든 초기 순정 상태로 되돌리는 기본값 복원 (Reset to Defaults)
글로벌 UserPrefs 커스터마이징 (v0.6.0):
- 사이드바 너비(160~~420px) 및 디테일 패널 너비(300~~760px) 드래그 리사이징
- UI 밀도 (Compact / Default / Comfortable)
- 폰트 크기, 라운드 스타일, 애니메이션 속도, 액센트 색조(Hue) & 채도(Saturation) 슬라이더
Demo 모드 (LocalStorage 기반 완전한 로컬 구동)
N단계 재귀 체크리스트 (RecursiveTaskItem)
인라인 제목 수정 (더블클릭/엔터/ESC)
커스텀 우클릭 컨텍스트 메뉴 (ContextMenu.tsx, 브라우저 기본 메뉴 비활성화)
Created / Edited 타임스탬프
커스텀 태그 (색상 자동 부여)
휴지통 (복원/영구삭제/보관 기간 설정)
설정 모달 (Profile / Preferences / Labs / Sync / Admin 5탭)
어드민 대시보드 (/admin - ADMIN 롤 및 권한 통제 게이트)
정식 라우트 보호 미들웨어 (src/middleware.ts 인증 & 역할 검증)
API IDOR 및 소유권 교차 검증 (서브태스크 및 리스트 이동)
CSV / ICS Import Formula Injection 방어 (sanitizeFormula)
Ctrl+K 글로벌 명령 팔레트 (CommandPalette.tsx)
TickTick CSV/ICS 임포트 및 내보내기 (Import & Export):
- 표준 RFC 4180 CSV (TickTick 포맷) 및 RFC 5545 iCalendar (.ics VTODO) 완벽 내보내기 (/api/export 및 클라이언트 사이드 데모 Blob 다운로드)
- 목록별 필터링 및 완료 태스크 포함 여부 선택 모달
CalDAV 양방향 동기화 및 가이드 고도화:
- RFC 4791 표준 준수: OPTIONS, PROPFIND (Principal & Collection 탐색), REPORT (VTODO 쿼리), PUT (태스크 업서트), DELETE
- 설정 모달 내 플랫폼별 인터랙티브 가이드 (Android / DAVx⁵, Apple 미리알림, Thunderbird)
- 실시간 엔드포인트 응답 상태 테스트 및 ICS 피드 다운로드 기능
TickTick 스타일 스마트 퀵애드 툴바 (날짜, 우선순위 프리셋)
상단 프로젝트 브레드크럼 & 리스트 이동기 (📁 프로젝트명 ▾)
모바일 바텀시트 드로어 (Y축 120px 스와이프 닫기, 백드롭 오버레이)
FAB 버튼 (모바일 태스크 추가)
PWA 매니페스트 및 서비스워커 지원 (manifest.json, sw.js)

5. 개발 규칙 및 보안 원칙

최상위 원칙 - 보안, 프라이버시, 안정성:
- 모든 API 요청은 세션 소유권(userId === session.user.id)을 철저히 검증할 것.
- 사용자 입력(마크다운, CSV/ICS 등)은 DOMPurify 및 Formula Sanitize를 반드시 통과할 것.
- 어드민 전용 라우트는 role === "ADMIN"을 서버/미들웨어 레벨에서 필터링할 것.
사용자 주도 커스터마이징 & 공간 효율성:
- 모든 블록과 뷰(리스트/칸반, 서브태스크/노트 스플릿 비율, 패널 너비 등)는 userPrefs.ts를 통해 사용자가 직관적으로 조절 가능해야 함.
- 불필요한 조잡한 툴바를 배제하고 심플하고 직관적인 조작성 유지.
컨텍스트 메뉴: 브라우저 기본 메뉴 대신 ContextMenu.tsx를 사용하여 네이티브 웹앱 UX 유지.
i18n 무결성: 새 텍스트 추가 시 src/lib/i18n/translations.ts의 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 / Cline

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

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.

15 KiB Raw Blame History