<div align="center">

# ⚡ CheckFlow

**프라이버시 중심의 독립형 스마트 태스크 & 마크다운 워크스페이스**  
*A modern, self-hosted, privacy-first task management & note workspace built for focus, speed, and open-standard freedom.*

<br/>

[![Next.js](https://img.shields.io/badge/Next.js-15.x-black?style=flat-square&logo=next.js)](https://nextjs.org/)
[![React](https://img.shields.io/badge/React-19.x-%2320232a?style=flat-square&logo=react)](https://reactjs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-%233178C6?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)
[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-16.x-%23336791?style=flat-square&logo=postgresql)](https://www.postgresql.org/)
[![Prisma](https://img.shields.io/badge/Prisma-6.x-%232D3748?style=flat-square&logo=prisma)](https://www.prisma.io/)
[![Docker](https://img.shields.io/badge/Docker-Ready-%232496ED?style=flat-square&logo=docker)](https://www.docker.com/)
[![CalDAV](https://img.shields.io/badge/RFC%204791-CalDAV%20VTODO-%234B7BF5?style=flat-square)](https://tools.ietf.org/html/rfc4791)
[![PWA](https://img.shields.io/badge/PWA-Installable-purple?style=flat-square)](https://web.dev/progressive-web-apps/)

<br/>

[✨ 핵심 기능](#-핵심-기능--디자인-철학) •
[🚀 빠른 시작 (Docker)](#-빠른-시작-docker-배포) •
[📱 CalDAV 모바일 연동](#-caldav-모바일-및-외부-앱-동기화) •
[📦 데이터 호환성](#-데이터-가져오기--내보내기) •
[🧪 Labs 커스터마이징](#-checkflow-labs--디자인-시스템) •
[🛠️ 개발 환경](#️-로컬-개발-환경)

</div>

---

## 💡 프로젝트 소개 & 디자인 철학

**CheckFlow**는 상용 클라우드 서비스(TickTick, Notion, Todoist 등)의 복잡성과 구독 모델, 데이터 종속에서 벗어나 **사용자 개인의 완벽한 데이터 주권**과 **군더더기 없는 미니멀리즘 작업 경험**을 제공하기 위해 설계된 독립형 웹 애플리케이션입니다.

- 🎯 **순수한 몰입감**: 산만한 툴바와 불필요한 장식을 배제하고, 에디터 본연의 텍스트 타이핑과 정갈한 마크다운 렌더링에 집중합니다.
- 🌲 **자유로운 계층화**: N단계 재귀적 하위 태스크 트리와 직관적인 인라인 수정을 통해 생각의 흐름을 그대로 구조화합니다.
- 🌐 **열린 표준**: 폐쇄적인 API 대신 **RFC 4791 CalDAV**, **RFC 5545 iCalendar (`.ics`)**, **RFC 4180 CSV** 표준을 준수하여 어떤 플랫폼에서든 자유롭게 동기화하고 백업할 수 있습니다.

---

## ✨ 핵심 기능 & 디자인 철학

### 1. 🌲 N-Depth 재귀 하위 태스크 & 인라인 편집
- **무제한 계층 구조**: 단순 1단계 하위 작업을 넘어 원하는 만큼 서브태스크를 트리 형태로 중첩 확장할 수 있습니다.
- **실시간 양방향 동기화**: 중앙 체크리스트와 우측 상세 패널 간의 상태가 지연 없이 1:1로 실시간 동기화됩니다.
- **인라인 즉시 수정**: 목록 제목 및 태스크 제목을 더블클릭/클릭하여 즉시 인라인 수정할 수 있습니다 (`Enter` 저장, `ESC` 취소).

### 2. 📝 적응형(Adaptive) 와이드 마크다운 노트
- **넓은 캔버스 레이아웃**: 우측 상세 패널의 대부분을 시원한 노트 공간으로 활용할 수 있습니다.
- **뷰 & 에디트 듀얼 모드**: ✏️ 작성 중에는 부드러운 텍스트 에디터로, 👁️ 뷰 모드에서는 웹 문서 수준의 미려한 마크다운 GUI 뷰어로 렌더링됩니다.
- **보안 렌더링**: `DOMPurify` 기반의 철저한 XSS 방어 및 안전한 외부 링크(`rel="noopener noreferrer"`)를 지원합니다.

### 3. 🧪 CheckFlow Labs & 유연한 커스터마이징
- **📋 리스트 뷰 ↔ 📊 3컬럼 칸반 보드 원클릭 전환**: `To Do`, `In Progress`, `Done` 컬럼으로 할 일 상태를 시각적으로 관리합니다.
- **모듈형 블록 스왑 & 스플릿 리사이저**: 서브태스크 목록과 마크다운 메모장의 상하 위치를 원하는 대로 맞바꾸고(⇄), 마우스 드래그로 높이 비율(15%~85%)을 자유롭게 조절할 수 있습니다.
- **개인화 환경설정**: UI 밀도(Compact/Default/Comfortable), 글꼴 크기, 테두리 라운드, 반응형 애니메이션 속도, 액센트 색조(Hue) & 채도(Saturation)를 슬라이더로 조절할 수 있으며, 언제든 초기 순정 상태로 되돌릴 수 있습니다.

### 4. 🎨 VSCode 무채색 다크 테마 & 파스텔 매트 라이트
- 눈의 피로를 최소화하는 **VSCode 스타일 무채색 다크 팔레트** (`#181818`, `#1e1e1e`, `#252526`)와 **매트 파스텔 라이트 테마**, 시스템 동기화 모드를 지원합니다.
- 사이드바 및 우측 패널의 너비를 마우스 드래그로 실시간 리사이징할 수 있습니다.

### 5. 📱 모바일 바텀시트 드로어 & PWA
- 스마트폰 화면에서는 우측 상세 패널이 부드러운 **바텀시트(Bottom Sheet)**로 전환됩니다.
- 화면 아래로 스와이프하거나 백드롭 오버레이를 터치하여 자연스럽게 패널을 닫을 수 있습니다.
- PWA 매니페스트(`manifest.json`)와 서비스워커(`sw.js`)를 통해 앱처럼 홈 화면에 추가하고 오프라인 캐시를 활용할 수 있습니다.

### 6. 🌐 3개국어 다국어(i18n) 지원
- **영어(English)**, **한국어(Korean)**, **일본어(Japanese)** 3개 언어를 완벽하게 지원하며 브라우저 또는 설정에서 즉시 변경할 수 있습니다.

---

## 🚀 빠른 시작 (Docker 배포)

CheckFlow는 프로덕션 컨테이너 이미지와 자동 데이터베이스 마이그레이션을 지원하여 `docker compose` 명령 하나로 즉시 구동됩니다.

### 1. 환경 변수 구성
`.env.example` 파일을 복사하여 환경 변수를 설정합니다:

```bash
cp .env.example .env
```

`.env` 파일 예시:
```env
# 데이터베이스 비밀번호 (프로덕션 환경에서는 안전한 비밀번호로 변경하세요)
POSTGRES_PASSWORD=your_secure_password

# 서비스 도메인 또는 접근 IP
NEXTAUTH_URL=http://localhost:3000

# NextAuth 인증 시크릿 키 (openssl rand -base64 32 등으로 생성)
NEXTAUTH_SECRET=your_generated_random_secret_string

# 외부 노출 포트 (기본값: 3000)
PORT=3000

# (선택사항) 커스텀 레지스트리 이미지를 사용할 경우
# CHECKFLOW_IMAGE=gitea.example.com/username/checkflow:latest
```

### 2. 컨테이너 실행
```bash
docker compose up -d
```
> 💡 컨테이너가 실행될 때 `docker-entrypoint.sh`가 PostgreSQL 헬스체크 후 **Prisma 스키마 마이그레이션을 자동으로 수행**하므로 별도의 수동 DB 설정 명령이 필요하지 않습니다.

브라우저에서 `http://localhost:3000`에 접속하여 첫 관리자/사용자 계정을 생성하세요.

---

## 📱 CalDAV 모바일 및 외부 앱 동기화

CheckFlow는 **RFC 4791 CalDAV 표준 프로토콜**을 완벽하게 지원하여, 모바일 및 데스크톱 기본 캘린더/할 일 앱과 양방향으로 동기화됩니다.

- **CalDAV 기본 엔드포인트 URL**: `https://your-domain.com/api/dav`
- **사용자 이름**: CheckFlow 계정 이메일
- **비밀번호**: CheckFlow 계정 비밀번호

### 🤖 Android (DAVx⁵ + Tasks.org / OpenTasks)
1. F-Droid 또는 Google Play에서 **DAVx⁵** 앱을 설치합니다.
2. DAVx⁵ → 계정 추가(+) → **URL 및 사용자 이름으로 로그인** 선택.
3. 기본 URL(`https://your-domain.com/api/dav`), 이메일, 비밀번호 입력.
4. **VTODO (할 일)** 컬렉션을 활성화하면 **Tasks.org** 또는 **OpenTasks** 앱에서 실시간 양방향 동기화가 이루어집니다.

### 🍎 Apple Reminders (iOS / iPadOS / macOS)
1. 기기 설정 → **미리알림(Reminders)** → **계정** → **계정 추가**.
2. **기타** → **CalDAV 계정 추가** 선택.
3. 서버 주소, 이메일, 비밀번호 입력 후 미리알림 활성화.

### 💻 Mozilla Thunderbird (Windows / Linux / macOS)
1. Thunderbird 실행 → 캘린더 탭 → **새 캘린더** 생성.
2. **네트워크에 저장** → 형식: **CalDAV** 선택.
3. 위치에 기본 URL 입력 및 이메일/비밀번호 인증.

---

## 📦 데이터 가져오기 & 내보내기

언제든 외부 서비스와 자유롭게 데이터를 주고받거나 로컬 백업을 생성할 수 있습니다.

### 📥 TickTick 데이터 가져오기 (Import)
- TickTick 설정 → 데이터 내보내기에서 생성된 **CSV** 또는 **iCalendar (`.ics`)** 파일을 사이드바의 **가져오기** 메뉴에서 업로드하여 기존 할 일, 하위 태스크, 마감일, 우선순위를 그대로 복원합니다.
- Formula Injection 및 XSS 공격을 방어하는 보안 검증 모듈이 내장되어 있습니다.

### 📤 표준 포맷 데이터 내보내기 (Export)
- 사이드바 사용자 메뉴 → **내보내기** 선택.
- **TickTick 호환 RFC 4180 CSV** (Excel 호환 UTF-8 BOM 포함) 또는 **RFC 5545 iCalendar (`.ics` VTODO)** 형식 지원.
- 전체 할 일 또는 특정 목록 필터링, 완료 항목 포함 여부를 자유롭게 선택하여 즉시 다운로드할 수 있습니다.

---

## 🛠️ 로컬 개발 환경

### 필수 요구사항
- Node.js 20+
- npm 또는 pnpm
- PostgreSQL (또는 개발용 SQLite)

```bash
# 1. 저장소 클론 및 패키지 설치
git clone https://git.nrh.kr/Neru_Han/checkflow.git
cd checkflow
npm install

# 2. 환경 변수 설정
cp .env.example .env.local

# 3. Prisma DB 스키마 생성 및 클라이언트 빌드
npx prisma db push
# 또는 SQLite 개발 모드: npm run dev:sqlite

# 4. 로컬 개발 서버 시작 (Turbopack)
npm run dev
```

브라우저에서 `http://localhost:3000` (체험 모드는 `http://localhost:3000/demo`)으로 접속합니다.

---

## 🏗️ 시스템 아키텍처 & 기술 스택

```
src/
├── app/
│   ├── page.tsx                       ← 메인 앱 진입점 (NextAuth 세션 기반)
│   ├── demo/page.tsx                  ← DB 연결 없이 LocalStorage 기반 완전 구동 데모
│   ├── admin/page.tsx                 ← 멀티유저 관리 및 시스템 대시보드 (ADMIN 전용)
│   ├── api/
│   │   ├── auth/                      ← NextAuth 및 회원가입 엔드포인트
│   │   ├── lists/ & tasks/            ← 계층형 태스크 & 리스트 REST API (IDOR 소유권 검증)
│   │   ├── import/ & export/          ← RFC 4180 CSV / RFC 5545 ICS 파서 및 익스포터
│   │   └── dav/[...path]/             ← RFC 4791 CalDAV 프로토콜 엔드포인트
├── components/
│   ├── layout/
│   │   ├── AppShell.tsx               ← 3-Panel 메인 컨테이너, 반응형 리사이저, 모바일 오버레이
│   │   └── Sidebar.tsx                ← 프로젝트 트리, 언어/테마 선택, 프로필 & Import/Export 팝오버
│   ├── tasks/
│   │   ├── TaskList.tsx               ← N-depth 재귀 체크리스트 트리, 스마트 퀵애드, 인라인 수정
│   │   ├── TaskDetail.tsx             ← 상세 패널, 블록 스왑, 마우스 스플릿 리사이저, 바텀시트
│   │   ├── MarkdownNoteEditor.tsx     ← 미니멀 마크다운 에디터 & DOMPurify 보안 프리뷰
│   │   └── KanbanView.tsx             ← CheckFlow Labs 3컬럼 칸반 보드
│   └── settings/
│       └── SettingsModal.tsx          ← Profile / Preferences / Labs / CalDAV / Admin 5탭 모달
└── lib/
    ├── userPrefs.ts                   ← 반응형 개인화 설정 스토어 (CSS 변수 인젝터)
    ├── i18n/                          ← EN/KO/JA 다국어 사전 및 useI18n 훅
    ├── auth.ts & prisma.ts            ← NextAuth 구성 및 Prisma DB 커넥터
    └── mockData.ts                    ← 데모 모드 전용 LocalStorage 스토리지 레이어
```

---

## 🔒 보안 및 개인정보 원칙

1. **엄격한 데이터 격리**: 모든 API 요청은 세션 소유권(`userId === session.user.id`)을 검증하며 리스트/태스크 간 IDOR(비인가 접근)를 원천 차단합니다.
2. **XSS 및 수식 주입 방어**: 모든 사용자 입력과 마크다운 렌더링은 `DOMPurify`를 거치며, CSV 가져오기 시 Formula Injection 방어(`sanitizeFormula`)가 적용됩니다.
3. **독립 멀티유저 & 관리자 통제**: 일반 사용자와 관리자(`ADMIN`) 권한이 분리되어 안전하게 셀프호스팅 환경을 운영할 수 있습니다.

---

## 📄 라이선스 (License)

This project is licensed under the **MIT License** — see the LICENSE file for details.