# InsuWiki 프로젝트 기획서

> 보험 지식을 정리하는 위키 서비스 (나무위키 스타일)
> 
> 작성일: 2026-02-07 | 최종 수정: 2026-02-08

---

## 📑 목차

| # | 섹션 | 설명 |
|---|------|------|
| 1 | [프로젝트 개요](#1-프로젝트-개요) | 서비스 컨셉, 목표 |
| 2 | [사용자 & 권한](#2-사용자--권한) | 인증, 권한, 화이트리스트 |
| 3 | [콘텐츠 기능](#3-콘텐츠-기능) | Reflect/Obsidian 기능, BYOK |
| 4 | [기술 스택](#4-기술-스택) | Firebase, Cloudflare, 비용 |
| 5 | [결제 시스템](#5-결제-시스템-모듈화-향후-개발) | 향후 개발 예정 |
| 6 | [저장소 전략](#6-저장소-전략) | Google Drive 활용 |
| 7 | [모듈화 아키텍처](#7-모듈화-아키텍처) | Core + Plugins 구조 |
| 8 | [폴더 구조](#8-폴더-구조) | 프로젝트 디렉토리 |
| 9 | [개발 로드맵](#9-개발-로드맵) | Phase 1~5 일정 |
| 10 | [멀티에이전트 시스템](#10-멀티에이전트-시스템-구성) | 9개 전문 에이전트 |
| 11 | [설계 원칙](#11-설계-원칙) | 아키텍처 철학 |
| 12 | [초기 콘텐츠 전략](#12-초기-콘텐츠-전략) | 런칭 콘텐츠 계획 |
| 13 | [법적 요구사항](#13-법적-요구사항-️) | 개인정보, 면책조항 |
| 14 | [MVP 체크리스트](#14-mvp-체크리스트-) | 필수/선택 기능 |
| 15 | [데이터 스키마](#15-데이터-스키마-) | DB 테이블 정의 |
| 16 | [API 명세](#16-api-명세-) | REST 엔드포인트 |
| 17 | [화면 구성](#17-화면-구성-️) | 데스크톱/모바일 UI |
| 18 | [보안 전략](#18-보안-전략-) | 인증, 암호화, 테스트 |
| 19 | [사용자 온보딩](#19-사용자-온보딩-추가-) | 신규 사용자 안내 |
| 20 | [CI/CD 자동화](#20-cicd-자동화-) | GitHub Actions, Pre-commit |

---

## 1. 프로젝트 개요

| 항목 | 내용 |
|------|------|
| **서비스명** | InsuWiki (보험위키) |
| **컨셉** | 나무위키 스타일의 보험 지식 정리 플랫폼 |
| **목표** | 사내 보험 지식 체계화 + 향후 유료 서비스 확장 |

---

## 2. 사용자 & 권한

| 유형 | 권한 | 결제 |
|------|------|------|
| 사내 직원 | 편집 + 열람 | 무료 |
| 외부 사용자 | 열람만 | 유료 (향후 개발) |

### 인증 방식
- **Google OAuth** 사용
- 관리자가 **승인한 사용자만** 접근 가능 (화이트리스트)
- 유료/무료 구분은 **모듈화**하여 향후 연동

### 편집 정책
- 누구나 편집 가능
- 모든 편집에 **작성자 태그** 기록
- **버전 히스토리** 관리 (Git 스타일)

### 데이터 영역 분리 (Private/Shared 이중 구조)

> 하나의 서비스에서 **개인 메모**와 **공용 위키**를 분리 운영

```
┌─────────────────────────────────────────┐
│           InsuWiki 서비스               │
├───────────────────┬─────────────────────┤
│    🔒 내 메모      │    🌐 인슈위키       │
│  (Private Zone)   │   (Shared Zone)     │
├───────────────────┼─────────────────────┤
│ - 고객 상담 기록   │ - 보험 상품 정보     │
│ - 개인 할일       │ - 약관 해설         │
│ - 비공개 메모     │ - 공유 노하우       │
└───────────────────┴─────────────────────┘
         ↓ 버튼 하나로 ↓
    [내 메모 → 인슈위키로 공유하기]
```

| 구분 | 개인 영역 (Private) | 공유 영역 (InsuWiki) |
|------|---------------------|----------------------|
| **용도** | 고객 상담 메모, 개인 체크리스트 | 지점 공용 보험 지식 |
| **접근** | 본인만 | 지점원 전체 |
| **데이터 구분** | `visibility: private` | `visibility: shared` |
| **UI** | "내 메모" 탭 | "인슈위키" 탭 |
| **검색** | 내 메모만 / 전체 선택 가능 | 공용 문서 전체 |

**핵심 기능**:
- 🔄 **공유 전환**: 개인 메모 → 클릭 한 번으로 인슈위키에 게시
- 🔗 **크로스 링크**: 내 메모에서 인슈위키 문서 링크 가능 (역방향도 지원)
- 🔍 **통합 검색**: "내 메모만" vs "전체" 검색 토글

---

## 3. 콘텐츠 기능

### 기본 콘텐츠
- ✅ 텍스트 (마크다운/리치 에디터)
- ✅ 표 (비교표, 보험료 표 등)
- ✅ 이미지 (다이어그램, 스크린샷)
- ✅ 계산기 위젯 (보험료 계산, 세금 시뮬레이션)

### Reflect AI 스타일 기능 (Reflect Memo 영감)

#### 핵심 기능 (AI-First)
- 💬 **AI 대화** ("이 약관 요약해줘", "이 보험의 보장 범위는?")
- 🔗 **양방향 링크 (Frictionless Backlinking)**: 관련 문서 자동 감지 및 연결
- 🎙️ **음성 및 영상 요약 (AI Whispers)**: 상담 녹음/유튜브 영상 자동 텍스트화 및 요약
- 📊 **그래프 뷰**: 지식 네트워크 기반의 보험 상품 데이터 시각화
- 🔍 **시맨틱 검색 (Semantic Retrieval)**: 키워드 검색을 넘어선 "의미 기반" 정보 인출
- ⚡ **AI 워크플로우**: 메모 작성 시 관련 양식 자동 추천 및 정리

#### Zero Friction 기능 (추가)
- 📅 **Daily Notes**: 매일 자동 생성되는 데일리 노트 (상담 기록용)
- ⚡ **Quick Capture**: `Ctrl+N` 앱 어디서든 즉시 메모 입력창
- ✨ **자동 완성**: `[[` 입력 시 문서 자동 추천, `#` 입력 시 태그 추천
- 📋 **템플릿 시스템**: 상황별 메모 템플릿 (상담 기록, 고객 요약, 보험 비교)
- 🌐 **Web Clipper**: 브라우저 확장으로 외부 자료 수집 (금감원 공시 등)

#### 템플릿 예시
| 템플릿 | 용도 | 자동 항목 |
|--------|------|----------|
| 상담 기록 | 고객 상담 후 정리 | 날짜, 고객명, 상품, 요약 |
| 고객 요약 | 고객별 히스토리 | 계약 현황, 상담 이력 |
| 보험 비교 | 상품 비교표 | 보장 항목, 보험료, 특약 |

#### 단축키 정의
| 단축키 | 기능 |
|--------|------|
| `Ctrl+N` | Quick Capture (즉시 메모) |
| `Ctrl+K` | 명령 팔레트 |
| `[[` | 문서 링크 삽입 |
| `#` | 태그 추가 |
| `Ctrl+Shift+D` | 오늘 Daily Note 열기 |

### Obsidian 스타일 기능 (Obsidian 영감)

> **범용 활용**: 아래 기능들은 보험 도메인에 한정되지 않고, **모든 종류의 작업**에 활용 가능합니다.

#### Properties (메타데이터 시스템)
문서에 구조화된 속성을 부여하여 체계적 관리:
```yaml
---
status: draft | review | published
category: 자유 분류
priority: high | medium | low
assignee: 담당자
due_date: 마감일
tags: [태그1, 태그2]
---
```

#### Dataview 스타일 동적 목록
조건에 맞는 문서를 자동으로 필터/정렬하여 표시:
| 쿼리 예시 | 결과 |
|----------|------|
| `status = "draft"` | 작성 중인 문서 목록 |
| `updated > 7days` | 최근 7일 수정된 문서 |
| `category = "상담"` | 특정 분류 문서만 |
| `assignee = me` | 내가 담당한 문서 |

#### Canvas 뷰 (무한 캔버스)
- 노트, 이미지, 링크를 **무한 캔버스**에 자유 배치
- 활용 예시: 브레인스토밍, 마인드맵, 관계도, 프로젝트 계획
- 그룹핑, 연결선, 색상 지정, 카드 내 마크다운 지원

#### 마크다운 내보내기
- **전체 데이터** 마크다운 파일로 백업 다운로드
- 다른 시스템으로 이관 가능 (데이터 소유권 보장)
- 단일 문서 / 폴더 / 전체 내보내기 옵션

### AI 설정 (BYOK - Bring Your Own Key)

> **비용 분산 모델**: 각 사용자가 본인의 AI API 키를 등록하여 사용. 서비스 운영자 비용 부담 최소화.

#### 설정 메뉴 (로그인 후 접근)
```
⚙️ 설정 > 🤖 AI 연동

┌─────────────────────────────────────────────┐
│  🔑 AI API 키 설정                          │
│                                             │
│  Gemini API Key                             │
│  ┌─────────────────────────────────────┐   │
│  │ [AI-xxxxxxxxxxxxxxxxxxxxx        ] │   │
│  └─────────────────────────────────────┘   │
│  📎 발급받기: https://aistudio.google.com   │
│                                             │
│  Whisper API Key (선택)                     │
│  ┌─────────────────────────────────────┐   │
│  │ [sk-xxxxxxxxxxxxxxxxxxxxx        ] │   │
│  └─────────────────────────────────────┘   │
│  📎 발급받기: https://platform.openai.com    │
│                                             │
│  [💾 저장]                                  │
└─────────────────────────────────────────────┘
```

#### 지원 AI 서비스
| 서비스 | 용도 | 무료 티어 |
|--------|------|----------|
| **Gemini** | AI 대화, 요약, 검색 | 15 RPM, 100만 토큰/일 |
| **Whisper** | 음성→텍스트 변환 | - (유료, $0.006/분) |

#### 동작 방식
```
사용자 요청 → AI 기능 호출
    ↓
┌─ 사용자 API 키 등록됨?
│   YES → 사용자 본인 키로 API 호출
│   NO  → ⚠️ "AI 키를 설정해주세요" 안내
└────────────────────────────────────────
```

#### 보안
| 항목 | 처리 방식 |
|------|----------|
| 키 저장 | 🔐 AES-256 암호화 (Firestore) |
| 키 전송 | HTTPS Only, 프론트엔드 노출 없음 |
| 키 사용 | 백엔드에서만 복호화 후 API 호출 |

---

## 4. 기술 스택

### 메인 스택 (50명 무료 운영 가능)

| 영역 | 기술 | 무료 티어 | 비용 |
|------|------|----------|------|
| **Frontend** | Next.js + TailwindCSS | - | - |
| **호스팅** | Cloudflare Pages | 무제한 대역폭, 무제한 요청 | **$0** |
| **DB** | Firebase Firestore | 1GB 저장, 5만 읽기/일 | **$0** |
| **Auth** | Firebase Auth | 5만 MAU | **$0** |
| **미디어 저장** | Google Drive API | 5TB (관리자 계정) | **$0** |
| **CDN/보안** | Cloudflare | DDoS 보호, 캐싱 | **$0** |
| **검색** | Firestore 쿼리 / Algolia | 1만 검색/월 | **$0** |

### 예상 비용: **월 $0** (50명 사용자 기준) 🎉

### 비용 비교 (이전 vs 현재)

| 구성 | 월 비용 | 비고 |
|------|--------|------|
| ~~Supabase + Vercel~~ | $25~45/월 | 7일 비활성 시 중지 문제 |
| **Firebase + Cloudflare** | **$0/월** | 자동 중지 없음, 상업용 가능 |

### 무료 티어 제한 (50명 기준 충분)

| 서비스 | 제한 | 50명 예상 | 여유율 |
|--------|------|----------|--------|
| Firestore 저장 | 1GB | ~100MB | 900% |
| Firestore 읽기 | 5만/일 | ~5천/일 | 1000% |
| Firebase Auth | 5만 MAU | 50명 | 1000배 |
| Cloudflare 대역폭 | 무제한 | - | ∞ |

### 확장 시 비용 (참고)

| 사용자 수 | 예상 비용 |
|----------|----------|
| ~50명 | $0/월 |
| 50~500명 | $0~25/월 |
| 500명+ | 종량제 (Blaze 플랜)

---

## 5. 결제 시스템 (모듈화, 향후 개발)

| 결제 수단 | 상태 |
|-----------|------|
| 토스페이먼츠 | 인터페이스만 정의 |
| 카카오페이 | 인터페이스만 정의 |

---

## 6. 저장소 전략

```
┌─────────────────────────────────────────────────┐
│              Google Drive (5TB)                 │
│  - 이미지/PDF 미디어 저장                        │
│  - 문서 버전 백업                               │
└───────────────────┬─────────────────────────────┘
                    │ Google Drive API
                    ▼
┌─────────────────────────────────────────────────┐
│            InsuWiki 메인 서버                    │
│  - 문서 메타데이터 (Supabase/PostgreSQL)         │
│  - 검색 인덱스                                  │
└─────────────────────────────────────────────────┘
```

---

## 7. 모듈화 아키텍처

```
┌─────────────────────────────────────────────────────────┐
│                    InsuWiki Core                        │
│  - 문서 CRUD + 버전관리                                  │
│  - Google OAuth 인증                                    │
│  - 기본 검색                                            │
│  - 마크다운 에디터                                       │
└───────────────────────┬─────────────────────────────────┘
                        │ Plugin Interface
        ┌───────┬───────┼───────┬───────┬───────┐
        ▼       ▼       ▼       ▼       ▼       ▼
    ┌──────┐┌──────┐┌──────┐┌──────┐┌──────┐┌──────┐
    │결제  ││AI대화││음성  ││그래프││백링크││계산기│
    │모듈  ││모듈  ││입력  ││뷰    ││모듈  ││위젯  │
    └──────┘└──────┘└──────┘└──────┘└──────┘└──────┘
```

---

## 8. 폴더 구조

```
insuwiki/
├── core/                    # 핵심 기능
│   ├── auth/               # 인증 모듈
│   ├── documents/          # 문서 CRUD
│   ├── search/             # 검색
│   └── editor/             # 기본 에디터
├── plugins/                 # 플러그인들
│   ├── payment/            # 결제 (비활성)
│   ├── ai-chat/            # AI 대화 (비활성)
│   ├── voice-input/        # 음성 (비활성)
│   ├── graph-view/         # 그래프 (비활성)
│   ├── backlinks/          # 백링크 (비활성)
│   └── calculator/         # 계산기 (비활성)
├── shared/                  # 공유 유틸리티
└── config/                  # 설정 파일
    └── plugins.json        # 플러그인 ON/OFF 설정
```

---

## 9. 개발 로드맵

| Phase | 모듈 | 우선순위 | 예상 기간 | 상태 |
|-------|------|----------|----------|------|
| **Phase 1** | Core (문서/인증/검색) | 🔴 필수 | 2-3주 | MVP |
| **Phase 2** | 리치 에디터 (표/이미지) | 🟠 높음 | 1-2주 | 예정 |
| **Phase 3** | AI 대화 (Reflect 스타일) | 🟡 중간 | 2주 | 예정 |
| **Phase 4** | 양방향 링크 (백링크) | 🟡 중간 | 1-2주 | 예정 |
| **Phase 5** | 결제 (토스/카카오) | 🟢 낮음 | 1주 | 예정 |
| **Phase 6** | 음성 입력 | 🟢 낮음 | 1주 | 예정 |
| **Phase 7** | 그래프 뷰 | 🟢 낮음 | 1-2주 | 예정 |
| **Phase 8** | 계산기 위젯 | 🟢 낮음 | 1주 | 예정 |

**총 예상 개발 기간**: 10-14주 (MVP 2-3주 + 확장 기능 8-11주)

---

## 10. 멀티에이전트 시스템 구성

```
┌──────────────────────────────────────────────────┐
│            PM Agent (Orchestrator)               │
│     - 작업 분배, 코드 리뷰, 통합 관리             │
└───────────────────────┬──────────────────────────┘
                        │
    ┌───────┬───────┬───┼───┬───────┬───────┬───────┐
    ▼       ▼       ▼   ▼   ▼       ▼       ▼       ▼
┌──────┐┌──────┐┌──────┐┌──────┐┌──────┐┌──────┐┌──────┐┌──────┐
│Back- ││Front-││ Data ││  QA  ││  UX  ││Legal ││Plann-││Reflec│
│end   ││end   ││      ││      ││      ││      ││er    ││t     │
└──────┘└──────┘└──────┘└──────┘└──────┘└──────┘└──────┘└──────┘
```

| 에이전트 | 역할 |
|----------|------|
| **PM Agent** | 작업 분배, 코드 리뷰, 결과 통합 |
| **Backend Expert** | API/DB 개발, 버전 관리, 검색 엔진 |
| **Frontend Expert** | React/Next.js UI, 마크다운 에디터 |
| **Data Expert** | DB 스키마, 문서 연결 관계, 검색 최적화 |
| **QA Expert** | 테스트 작성, 버그 검출, 보안 검토 |
| **UX Expert** | 사용자 경험 설계, 와이어프레임, 사용성 테스트 |
| **Legal Expert** | 보험 법률 검토, 약관 해석, 컴플라이언스 |
| **Planner Expert** | 기획/로드맵, 기능 우선순위, 스프린트 관리 |
| **Reflect Expert** | 🆕 지식 관리, Frictionless 철학, 시맨틱 검색, AI 워크플로우 |

---

## 11. 설계 원칙

| 원칙 | 설명 |
|------|------|
| **독립성** | 각 모듈은 Core 없이 단독 테스트 가능 |
| **인터페이스** | 명확한 API 규약 (입력/출력 정의) |
| **설정 기반** | 환경변수/설정 파일로 ON/OFF |
| **느슨한 결합** | 모듈 간 직접 의존 금지, Core를 통해서만 통신 |
| **저비용 + 보안** | 무료 티어 최대 활용, 보안은 타협 없음 |

---

## 12. 초기 콘텐츠 전략

- **NotebookLM 연동**: 기존 수집된 보험 데이터를 NotebookLM MCP를 통해 InsuWiki로 자동 공급/정리
- **Reflect 스타일 도입**: 메모 마찰을 최소화하는 UX와 인공지능 기반의 지식 연결 강화
- **수동 입력 병행**: 관리자(본인)가 직접 입력하며 초기 위키 데이터 구축

---

## 13. 법적 요구사항 ⚖️

> **Legal Expert 권고**: 서비스 런칭 전 필수 법적 문서

### 필수 문서
| 문서 | 상태 | 비고 |
|------|------|------|
| **개인정보처리방침** | ❌ 미작성 | PIPA 준수 필수 |
| **이용약관** | ❌ 미작성 | 서비스 범위, 책임 한계 |
| **보험정보 면책조항** | ❌ 미작성 | 금융소비자보호법 |

### 면책 문구 (초안)
> ⚠️ **면책 조항**: 본 서비스의 정보는 일반적인 참고용이며, 법적 효력이 없습니다. 구체적인 보험 가입 및 상담은 공인된 보험설계사와 상담하시기 바랍니다. 본 서비스는 보험 상품 판매를 목적으로 하지 않습니다.

### 개인정보 수집 항목
- **필수**: 이메일(Google OAuth), 닉네임
- **선택**: 프로필 이미지
- **자동 수집**: 편집 이력, 접속 로그

---

## 14. MVP 체크리스트 ✅

> **Phase 1 (Core)** 상세 기능 목록

### Must Have (필수)
- [x] Google OAuth 로그인
- [ ] 화이트리스트 기반 접근 제어
- [ ] 문서 생성/수정/삭제 (CRUD)
- [ ] 마크다운 에디터
- [ ] 문서 버전 히스토리
- [ ] 기본 검색 (제목/본문)
- [ ] 작성자 태그 자동 기록

### Should Have (권장)
- [ ] 문서 목차 자동 생성
- [ ] 최근 변경 목록
- [ ] 문서 즐겨찾기

### Won't Have (MVP 제외)
- AI 대화
- 양방향 백링크
- 그래프 뷰
- 결제 시스템

### 성공 지표 (KPI)
| 지표 | 목표 | 측정 방법 |
|------|------|----------|
| 문서 수 | 50개 (1개월) | DB 카운트 |
| 활성 편집자 | 5명 | 주간 편집 1회 이상 |
| 평균 로딩 속도 | < 2초 | Lighthouse |

---

## 15. 데이터 스키마 📊

> **Data Expert 설계**: 핵심 테이블 정의

### ERD 개요
```
┌─────────────┐       ┌─────────────┐
│    User     │       │  Document   │
├─────────────┤       ├─────────────┤
│ id (PK)     │◄──────│ author_id   │
│ email       │       │ id (PK)     │
│ name        │       │ title       │
│ role        │       │ content     │
│ created_at  │       │ visibility  │
└─────────────┘       │ created_at  │
                      │ updated_at  │
                      └──────┬──────┘
                             │
                      ┌──────▼──────┐
                      │   Version   │
                      ├─────────────┤
                      │ id (PK)     │
                      │ doc_id (FK) │
                      │ content     │
                      │ editor_id   │
                      │ created_at  │
                      └─────────────┘
```

### 테이블 정의

#### User
| 컬럼 | 타입 | 설명 |
|------|------|------|
| id | UUID | PK |
| email | VARCHAR | Google OAuth 이메일 |
| name | VARCHAR | 표시 이름 |
| role | ENUM | admin, editor, viewer |
| created_at | TIMESTAMP | 가입일 |

#### Document
| 컬럼 | 타입 | 설명 |
|------|------|------|
| id | UUID | PK |
| title | VARCHAR | 문서 제목 |
| content | TEXT | 마크다운 본문 |
| visibility | ENUM | **private, shared** |
| author_id | UUID | FK → User |
| created_at | TIMESTAMP | 생성일 |
| updated_at | TIMESTAMP | 수정일 |

#### Version
| 컬럼 | 타입 | 설명 |
|------|------|------|
| id | UUID | PK |
| document_id | UUID | FK → Document |
| content | TEXT | 해당 버전 본문 |
| editor_id | UUID | FK → User |
| created_at | TIMESTAMP | 버전 생성일 |

#### Tag (추가)
| 컬럼 | 타입 | 설명 |
|------|------|------|
| id | UUID | PK |
| name | VARCHAR | 태그 이름 |
| document_id | UUID | FK → Document |
| created_at | TIMESTAMP | 생성일 |

#### Link (추가 - 백링크용)
| 컬럼 | 타입 | 설명 |
|------|------|------|
| id | UUID | PK |
| source_doc_id | UUID | FK → Document (출발 문서) |
| target_doc_id | UUID | FK → Document (도착 문서) |
| created_at | TIMESTAMP | 링크 생성일 |

---

## 16. API 명세 🔌

> **Backend Expert 설계**: 핵심 REST API

### 인증 (Auth)
| Method | Endpoint | 설명 |
|--------|----------|------|
| GET | `/api/auth/login` | Google OAuth 시작 |
| GET | `/api/auth/callback` | OAuth 콜백 |
| POST | `/api/auth/logout` | 로그아웃 |
| GET | `/api/auth/me` | 현재 사용자 정보 |

### 문서 (Documents)
| Method | Endpoint | 설명 |
|--------|----------|------|
| GET | `/api/documents` | 문서 목록 (visibility 필터) |
| POST | `/api/documents` | 문서 생성 |
| GET | `/api/documents/:id` | 문서 상세 |
| PUT | `/api/documents/:id` | 문서 수정 |
| DELETE | `/api/documents/:id` | 문서 삭제 |
| GET | `/api/documents/:id/versions` | 버전 히스토리 |

### 검색 (Search)
| Method | Endpoint | 설명 |
|--------|----------|------|
| GET | `/api/search?q=&page=1&limit=20` | 전체 검색 (페이지네이션) |
| GET | `/api/search?q=&scope=private` | 내 메모만 검색 |

### 사용자 (Users) - 추가
| Method | Endpoint | 설명 |
|--------|----------|------|
| GET | `/api/users` | 화이트리스트 목록 |
| POST | `/api/users` | 사용자 승인 (관리자) |
| DELETE | `/api/users/:id` | 사용자 제거 (관리자) |

### 공유 (Share) - 추가
| Method | Endpoint | 설명 |
|--------|----------|------|
| POST | `/api/documents/:id/share` | Private → Shared 전환 |
| POST | `/api/documents/:id/unshare` | Shared → Private 전환 |

---

## 17. 화면 구성 🖥️

> **Frontend Expert 설계**: 주요 화면 목록

### 화면 목록
| 화면 | 경로 | 설명 |
|------|------|------|
| 홈 | `/` | 최근 문서, 인기 문서 |
| 로그인 | `/login` | Google OAuth 버튼 |
| 문서 목록 | `/docs` | 전체 문서 (검색, 필터) |
| 문서 상세 | `/docs/:id` | 본문 렌더링, 목차 |
| 문서 편집 | `/docs/:id/edit` | 마크다운 에디터 |
| **버전 히스토리** | `/docs/:id/history` | 버전 타임라인, 비교 (추가) |
| 내 메모 | `/my` | Private 문서 목록 |
| 설정 | `/settings` | 프로필, 알림 설정 |
| **관리자** | `/admin` | 화이트리스트 관리, 통계 (추가) |
| **온보딩** | `/onboarding` | 신규 사용자 가이드 (추가) |

### 레이아웃 구조 (데스크톱)
```
┌─────────────────────────────────────────────┐
│  Header (로고, 검색바, 사용자 메뉴)          │
├──────────────┬──────────────────────────────┤
│              │                              │
│   Sidebar    │         Main Content         │
│  (네비게이션) │        (문서/에디터)          │
│              │                              │
├──────────────┴──────────────────────────────┤
│  Footer (법적고지, 연락처)                   │
└─────────────────────────────────────────────┘
```

### 모바일 레이아웃 (추가)
```
┌─────────────────────────┐
│  Header (로고, 햄버거)   │
├─────────────────────────┤
│                         │
│      Main Content       │
│      (문서/에디터)       │
│                         │
├─────────────────────────┤
│  Bottom Nav             │
│  [홈][검색][내메모][설정] │
└─────────────────────────┘
```

### UI 컴포넌트 (shadcn/ui 기반)
- `DocumentCard` - 문서 미리보기 카드
- `MarkdownEditor` - 편집기 (TipTap 기반)
- `VersionHistory` - 버전 타임라인
- `SearchBar` - 검색 입력 + 필터
- `PrivateToggle` - Private/Shared 전환 버튼

---

## 18. 보안 전략 🔐

> **QA Expert 설계**: OWASP Top 10 기반 보안 체크리스트

### 인증/인가 보안
| 항목 | 구현 방법 | 상태 |
|------|----------|------|
| OAuth 2.0 | Google OAuth + PKCE | ⬜ 예정 |
| 세션 관리 | HTTP-Only Cookie + SameSite | ⬜ 예정 |
| 화이트리스트 | DB 기반 이메일 승인 | ⬜ 예정 |
| 역할 기반 접근 | admin/editor/viewer RBAC | ⬜ 예정 |

### 데이터 보안
| 위협 | 방어 | 상태 |
|------|------|------|
| **SQL Injection** | Parameterized Query (Supabase ORM) | ⬜ 예정 |
| **XSS** | HTML 이스케이프 + CSP 헤더 | ⬜ 예정 |
| **CSRF** | SameSite Cookie + CSRF 토큰 | ⬜ 예정 |
| **데이터 유출** | Row Level Security (RLS) | ⬜ 예정 |

### Row Level Security (RLS) 정책
```sql
-- Private 문서는 작성자만 접근
CREATE POLICY "Users can view own private docs"
ON documents FOR SELECT
USING (
  visibility = 'shared' 
  OR author_id = auth.uid()
);

-- Shared 문서는 인증된 사용자만 접근
CREATE POLICY "Authenticated users can view shared docs"
ON documents FOR SELECT
USING (
  visibility = 'shared' 
  AND auth.role() = 'authenticated'
);
```

### API 보안
- ✅ HTTPS 강제 (Cloudflare)
- ⬜ Rate Limiting (100 req/min)
- ⬜ Input Validation (Zod 스키마)
- ⬜ 에러 메시지 최소화 (정보 노출 방지)

### 민감 정보 관리
| 항목 | 저장 위치 | 비고 |
|------|----------|------|
| API 키 | `.env.local` (Git 제외) | Vercel 환경변수 |
| OAuth 시크릿 | Supabase Vault | 암호화 저장 |
| 사용자 데이터 | Supabase (암호화) | AES-256 |

### 보안 테스트 계획
- [ ] OWASP ZAP 스캔 (배포 전)
- [ ] 펜테스트 (MVP 완료 후)
- [ ] 정기 의존성 취약점 검사 (`npm audit`)

### 테스트 커버리지 목표 (추가)
| 영역 | 목표 | 도구 |
|------|------|------|
| 단위 테스트 | 80% | Jest/Vitest |
| API 테스트 | 100% (핵심 엔드포인트) | Supertest |
| E2E 테스트 | 핵심 플로우 3개 | Playwright |

### 핵심 E2E 시나리오 (추가)
1. 로그인 → 문서 생성 → 저장 → 확인
2. 문서 검색 → 상세 보기 → 편집
3. Private 문서 → Shared로 전환 → 공유 확인

---

## 19. 사용자 온보딩 (추가) 🎯

> **UX Expert 설계**: 신규 사용자 가이드

### 온보딩 플로우
```
[첫 로그인]
     ↓
┌─────────────────────────────────┐
│  1단계: 환영 화면               │
│  "InsuWiki에 오신 것을 환영합니다!" │
└────────────────┬────────────────┘
                 ↓
┌─────────────────────────────────┐
│  2단계: 핵심 기능 투어           │
│  - 내 메모 vs 인슈위키 설명      │
│  - 마크다운 단축키 안내          │
└────────────────┬────────────────┘
                 ↓
┌─────────────────────────────────┐
│  3단계: 첫 문서 작성 유도        │
│  "첫 번째 메모를 작성해 보세요!"  │
└─────────────────────────────────┘
```

### 제공 리소스
| 리소스 | 형태 | 위치 |
|--------|------|------|
| 마크다운 치트시트 | 모달 | 에디터 툴바 ? 버튼 |
| 문서 템플릿 | 드롭다운 | 새 문서 생성 시 |
| 튜토리얼 영상 | 링크 | 설정 > 도움말 |

### 스킵 옵션
- [ ] "다시 보지 않기" 체크박스
- [ ] 진행률 표시 (1/3, 2/3, 3/3)

---

## 20. CI/CD 자동화 🔄

> **QA Expert 설계**: 코드 품질 자동화 파이프라인

### GitHub Actions 워크플로우
```yaml
# .github/workflows/ci.yml
name: CI Pipeline
on: [push, pull_request]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npm run lint          # ESLint
      - run: npm run type-check    # TypeScript
      - run: npm test              # Jest/Vitest
      - run: npm audit             # 보안 취약점
```

### Pre-commit Hooks (Husky + lint-staged)
```json
// package.json
{
  "lint-staged": {
    "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
    "*.{json,md}": ["prettier --write"]
  }
}
```

### 자동화 체크 항목
| 단계 | 도구 | 실패 시 |
|------|------|--------|
| 린트 | ESLint | 커밋 차단 |
| 타입 | TypeScript | 커밋 차단 |
| 테스트 | Jest/Vitest | PR 차단 |
| 보안 | npm audit | 경고 |

### 리뷰 프로세스
```
코드 작성 → Pre-commit Hook → Push → GitHub Actions → PR 리뷰 → Merge
    ↓           ↓              ↓          ↓            ↓
  ESLint      자동 수정      자동 검사    통과 필수    QA 승인
```

---

*이 문서는 전문가별 상세 검토 결과를 반영하여 2026-02-08에 업데이트되었습니다.*
*추가된 섹션: Phase 기간, Tag/Link 테이블, Users/Share API, 모바일 레이아웃, 테스트 커버리지, E2E 시나리오, 사용자 온보딩, CI/CD 자동화*