252 lines
14 KiB
Markdown
252 lines
14 KiB
Markdown
<div align="center">
|
||
|
||
# ⚡ CheckFlow
|
||
|
||
**프라이버시 중심의 독립형 스마트 태스크 & 마크다운 워크스페이스**
|
||
*A modern, self-hosted, privacy-first task management & note workspace built for focus, speed, and open-standard freedom.*
|
||
|
||
<br/>
|
||
|
||
[](https://nextjs.org/)
|
||
[](https://reactjs.org/)
|
||
[](https://www.typescriptlang.org/)
|
||
[](https://www.postgresql.org/)
|
||
[](https://www.prisma.io/)
|
||
[](https://www.docker.com/)
|
||
[](https://tools.ietf.org/html/rfc4791)
|
||
[](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는 사전 빌드된 컨테이너 레지스트리 이미지와 자동 DB 마이그레이션 진입점(`docker-entrypoint.sh`)을 제공하므로, **Git 소스 코드 복제(clone) 없이 `docker-compose.yml`과 `.env` 파일 단 2개만으로 즉시 배포**할 수 있습니다.
|
||
|
||
### 1. 배포 디렉터리 준비 및 설정 파일 다운로드
|
||
서버의 원하는 디렉터리에서 설정 파일 2개를 내려받습니다:
|
||
|
||
```bash
|
||
mkdir checkflow && cd checkflow
|
||
|
||
# docker-compose.yml 다운로드
|
||
curl -O https://git.nrh.kr/Neru_Han/checkflow/raw/branch/master/docker-compose.yml
|
||
|
||
# .env.example 다운로드 후 .env 생성
|
||
curl -O https://git.nrh.kr/Neru_Han/checkflow/raw/branch/master/.env.example
|
||
cp .env.example .env
|
||
```
|
||
|
||
### 2. 환경 변수(`.env`) 설정
|
||
`.env` 파일을 열어 사용자 환경에 맞게 수정합니다:
|
||
|
||
```env
|
||
# [필수] 데이터베이스 비밀번호 (안전한 난수로 지정)
|
||
POSTGRES_PASSWORD=your_secure_password
|
||
|
||
# [필수] 서비스 접속 URL (리버스 프록시 도메인 또는 IP)
|
||
NEXTAUTH_URL=https://todo.yourdomain.com
|
||
|
||
# [필수] NextAuth 세션 암호화 키 (openssl rand -base64 32 등으로 생성)
|
||
NEXTAUTH_SECRET=your_generated_random_secret_string
|
||
|
||
# [선택] 외부 노출 포트 (기본값: 3000)
|
||
PORT=3000
|
||
|
||
# [선택] Gitea / Docker 컨테이너 레지스트리 이미지 주소
|
||
CHECKFLOW_IMAGE=git.nrh.kr/neru_han/checkflow:latest
|
||
```
|
||
|
||
### 3. 서비스 실행 및 자동 마이그레이션
|
||
최신 패키지 이미지를 다운로드하고 서비스를 실행합니다:
|
||
|
||
```bash
|
||
# 최신 공개 이미지 다운로드
|
||
docker compose pull
|
||
|
||
# 백그라운드 서비스 시작
|
||
docker compose up -d
|
||
```
|
||
> 💡 **자동 DB 마이그레이션**: 컨테이너 구동 시 `docker-entrypoint.sh`가 PostgreSQL 데이터베이스 연결을 확인한 후 `prisma migrate deploy`를 자동 실행하므로 수동 DB 마이그레이션 작업이 필요하지 않습니다.
|
||
|
||
### 🔄 Watchtower 기반 자동 업데이트 (선택 사항)
|
||
`docker-compose.yml`에는 `com.centurylinklabs.watchtower.enable=true` 라벨이 구성되어 있습니다.
|
||
Watchtower를 사용하면 새로운 릴리즈 이미지가 배포되었을 때 컨테이너를 자동으로 감지하여 최신 버전으로 갱신할 수 있습니다:
|
||
|
||
```bash
|
||
docker run -d \
|
||
--name watchtower \
|
||
--restart unless-stopped \
|
||
-v /var/run/docker.sock:/var/run/docker.sock \
|
||
containrrr/watchtower --interval 300 --cleanup --label-enable
|
||
```
|
||
|
||
브라우저에서 설정한 주소(`https://todo.yourdomain.com` 또는 `http://서버IP: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.
|