195 lines
10 KiB
Markdown
195 lines
10 KiB
Markdown
# CheckFlow — Agent Handbook & Project History
|
|
|
|
> 이 문서는 CheckFlow 프로젝트의 전체 개발 내역, 사용자 요구사항, 의사결정 기록, 기술 아키텍처를 보존하여 향후 작업하는 모든 AI 에이전트와 개발자가 일관되게 작업을 이어갈 수 있도록 작성되었습니다.
|
|
> **다음 에이전트에게**: 반드시 이 파일을 먼저 읽고, 작업 완료 후 업데이트하라.
|
|
|
|
---
|
|
|
|
## 1. 프로젝트 개요 & 핵심 요구사항
|
|
|
|
사용자의 핵심 요구사항:
|
|
1. **TickTick 스타일 To-Do 리스트 독립 웹앱**:
|
|
- 체크리스트는 **메인 - 하위(Sub-task)** N단계 계층 구조를 갖추며, 양쪽 패널 간 1:1 실시간 동기화.
|
|
- **적응형(Adaptive) 와이드 메모장**: 우측 패널의 대부분을 메모장이 차지하며, 마크다운이 GUI로 렌더링됨.
|
|
- **인라인 즉시 수정 UX**: 프로젝트 제목 및 태스크 제목을 클릭으로 즉시 수정 가능.
|
|
2. **셀프호스팅 & 프라이버시 중심 멀티유저**:
|
|
- SNS 형태가 아닌 개인별 프라이버시가 완벽히 보장되는 독립 멀티유저 플랫폼.
|
|
- Docker 배포 지원 (PostgreSQL 16 포함, Dockerfile & docker-compose.yml 완비).
|
|
3. **외부 플랫폼 연동 & Import**:
|
|
- TickTick CSV/ICS Import 지원 (프로필 메뉴 내 배치).
|
|
- Galaxy(Android) 폰 연동: DAVx⁵ 앱을 통한 CalDAV (`/api/dav`) 동기화 지원.
|
|
4. **모바일 바텀시트 드로어**:
|
|
- 스마트폰에서 우측 상세 탭이 **바텀 시트**로 아래서 위로 슬라이드업.
|
|
- 아래로 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-v1.0` | 기본 Full-Stack 기반 | 초기 |
|
|
| `checkpoint-v2.0` | i18n, 3-Way Theme, Demo Mode | - |
|
|
| `checkpoint-v2.1` | 리치 마크다운 렌더러, 적응형 메모장 | - |
|
|
| `checkpoint-v2.2` | 하위 태스크 실시간 동기화 & 인라인 수정 | - |
|
|
| `checkpoint-v3.0` | 사이드바 애니메이션, Import 이동, 커스텀 메뉴, TickTick 스타일 | - |
|
|
| `checkpoint-v3.2` | N-depth 재귀 체크리스트, 태그, 휴지통, 설정 모달, 타임스탬프 | - |
|
|
| `checkpoint-v4.0` | **(현재 최신)** 모바일 바텀시트, 스와이프 닫기, 오버레이 | 2026-08-20 |
|
|
|
|
---
|
|
|
|
## 4. 구현 완료 기능
|
|
|
|
- [x] i18n 3개국어 (영어 기본, 한국어, 일본어)
|
|
- [x] 시스템/라이트/다크 테마 토글
|
|
- [x] Demo 모드 (LocalStorage 기반)
|
|
- [x] N단계 재귀 체크리스트 (RecursiveTaskItem)
|
|
- [x] 인라인 제목 수정
|
|
- [x] 커스텀 우클릭 컨텍스트 메뉴 (전체 트리)
|
|
- [x] Created / Edited 타임스탬프
|
|
- [x] 커스텀 태그 (색상 자동 부여)
|
|
- [x] 휴지통 (복원/영구삭제/보관 기간 설정)
|
|
- [x] 마크다운 Preview/Edit + URL 새 탭 열기
|
|
- [x] 설정 모달 (Profile/Preferences/Sync/Admin)
|
|
- [x] 어드민 페이지 (/admin)
|
|
- [x] Ctrl+K 글로벌 명령 팔레트
|
|
- [x] TickTick CSV/ICS 임포트
|
|
- [x] CalDAV 동기화 안내
|
|
- [x] **모바일 바텀시트 드로어** (Y축 스와이프, 오버레이)
|
|
- [x] FAB 버튼 (모바일 태스크 추가)
|
|
|
|
---
|
|
|
|
## 5. 개발 규칙 및 주의사항
|
|
|
|
1. **메모장 우선 원칙**: 우측 패널에서 메모장은 항상 `flex: 1`.
|
|
2. **컨텍스트 메뉴**: `ContextMenu.tsx` 사용, 브라우저 기본 메뉴 비활성화.
|
|
3. **i18n 무결성**: 새 텍스트는 en/ko/ja 사전에 모두 추가.
|
|
4. **모바일 CSS 규칙**:
|
|
- `detail-panel mobile-open` 클래스가 바텀시트를 제어.
|
|
- **절대** `task-detail-panel` 클래스로 되돌리지 말 것 (구버전).
|
|
- 모바일: `translateY(100%) → translateY(0)` 애니메이션.
|
|
- 데스크탑: `detail-panel`이 flex 방향 측면 패널.
|
|
5. **터치 제스처**: Y축 아래 방향 120px 이상 스와이프 → `onClose()`.
|
|
6. **언어**: 사용자 응답 및 에이전트 간 소통은 한국어를 기본으로 할 것.
|
|
|
|
---
|
|
|
|
## 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. 프로젝트 개요 & 핵심 요구사항
|
|
|
|
사용자의 핵심 요구사항:
|
|
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 사전에 모두 추가할 것. |