328 lines
15 KiB
Markdown
328 lines
15 KiB
Markdown
# v0.4 — Notebooks + Lifecycle Simplification Design
|
||
|
||
**작성일:** 2026-05-14
|
||
**선행 문서:**
|
||
|
||
- `docs/superpowers/specs/2026-04-25-dogfood-feedback.md` F25 (raw idea)
|
||
- `docs/superpowers/specs/2026-05-09-v032-cut-g-design.md` (v0.3.2 Cut G — **deprecate**, 본 문서로 승격)
|
||
- `docs/superpowers/strategy/v028plus-roadmap.md` Cut G position
|
||
|
||
---
|
||
|
||
## 1. 정체성
|
||
|
||
inbox 분류 layer 도입 + lifecycle 단순화. 단일 cut 으로 묶음 — 두 변경이 같은 UI 영역 (헤더 탭 + status 모델) 을 동시 손대므로 분리 시 중간 상태가 어색.
|
||
|
||
- **분류 (notebook)**: cross-cutting 컨텍스트. "회사" / "개인" / "학습" 같은 공간 구분. 단일 DB 안 `notebook_id` 컬럼 (옵션 B — Cut G 결정 승계).
|
||
- **lifecycle 단순화**: status 4분기 → 3분기. `archived` 제거.
|
||
|
||
---
|
||
|
||
## 2. dogfood 근거 (왜 이 시점에 이 cut)
|
||
|
||
2026-04-25 ~ 2026-05-14 (19일) telemetry + DB:
|
||
|
||
| 신호 | 수치 | 의미 |
|
||
|------|------|------|
|
||
| `archived` 노트 | 0건 | 4분기 lifecycle 중 1차원 dead — 사용자가 한 번도 사용 안 함 |
|
||
| `active` 노트 | 10건 | 사용 중 |
|
||
| `completed` 노트 | 8건 | 적극 사용 |
|
||
| `trashed` 노트 | 20건 | 적극 사용 |
|
||
| top tag `mlx-ops` | 6건 | 단일 tag 가 사실상 "MLX팀 메모" 컨텍스트 그룹 역할 — tag 의 분류 욕구 명확 |
|
||
| tag vocab 적중률 | 32.8% (19/58) | 새 tag 빈번 생성 — 분류 욕구 일관성 부족, grouping UI 필요 |
|
||
|
||
→ **archived 는 제거 안전** (마이그레이션 영향 0건). **분류 욕구는 데이터로 확인**되었으나 tag 만으로 충족 어려움 (적중률 낮음).
|
||
|
||
사용자 우려 ("분류 × lifecycle 햇갈림") 의 대응: archived 제거로 한 차원 줄임. 결과 layer = (notebook × 3분기 × tag) — 3차원이지만 archived 0건 빼서 정신 부담 줄음.
|
||
|
||
---
|
||
|
||
## 3. 범위
|
||
|
||
| 항목 | 결정 |
|
||
|------|------|
|
||
| **분류 모델** | 옵션 B — `notebook_id` 카테고리, 단일 DB. 옵션 A (다중 profile + 비밀번호 잠금) 는 v0.5+ 후보. |
|
||
| **lifecycle 차원** | 3분기 — `active` (inbox) / `completed` (완료) / `trashed` (휴지통). `archived` 제거. |
|
||
| **default notebook** | 마이그레이션 시 "기본" 1개 자동 생성. 모든 기존 노트 배치. |
|
||
| **사이드바 가시성** | 사용자 토글 + last state (`settings.sidebar_visible`). Cmd+B / Ctrl+B 단축키. |
|
||
| **사이드바 내용** | 상단 notebook 목록 + 하단 메모 list (compact view, current notebook + current view 필터). |
|
||
| **사이드바 폭** | default 240px, `settings.sidebar_width` 조정 가능 (180-400). |
|
||
| **notebook 삭제** | FK RESTRICT — 메모 잔류 시 throw. UI 가 "메모 N건 이동 후 재시도" 안내. |
|
||
| **search scope** | 기본 current notebook, 사용자가 dropdown 으로 "모든 노트북" 전환 가능. |
|
||
| **새 capture 의 notebook** | current `selectedNotebookId`. 사용자가 다른 notebook 에 있으면 거기 저장. |
|
||
|
||
---
|
||
|
||
## 4. Schema 마이그레이션 (m008)
|
||
|
||
```sql
|
||
-- 1. notebooks 테이블 생성
|
||
CREATE TABLE notebooks (
|
||
id TEXT PRIMARY KEY,
|
||
name TEXT NOT NULL,
|
||
color TEXT,
|
||
created_at TEXT NOT NULL,
|
||
updated_at TEXT NOT NULL
|
||
);
|
||
CREATE UNIQUE INDEX idx_notebooks_name ON notebooks(name);
|
||
|
||
-- 2. notes.notebook_id 추가 (FK, NOT NULL — default 통해 보장)
|
||
ALTER TABLE notes ADD COLUMN notebook_id TEXT
|
||
REFERENCES notebooks(id) ON DELETE RESTRICT;
|
||
|
||
-- 3. default notebook "기본" 생성
|
||
INSERT INTO notebooks (id, name, created_at, updated_at)
|
||
VALUES ('<uuidv7>', '기본', '<now>', '<now>');
|
||
|
||
-- 4. 모든 기존 노트를 default notebook 에 배치
|
||
UPDATE notes SET notebook_id = '<default-id>' WHERE notebook_id IS NULL;
|
||
|
||
-- 5. NOT NULL 제약 추가 (마이그레이션 후)
|
||
-- SQLite ALTER 제약: 새 테이블 만들고 복사 패턴 사용 (better-sqlite3 표준)
|
||
|
||
-- 6. archived → completed 정리 (실제 0건이라 no-op, 안전 위해 명시)
|
||
UPDATE notes SET status = 'completed' WHERE status = 'archived';
|
||
|
||
-- 7. status CHECK constraint 갱신: archived 제거
|
||
-- 마찬가지로 새 테이블 만들고 복사 패턴
|
||
```
|
||
|
||
마이그레이션 안전성: 기존 archived 노트 0건 확인 (telemetry + DB query). default notebook 자동 생성으로 기존 사용자 영향 없음.
|
||
|
||
---
|
||
|
||
## 5. NotebookRepository
|
||
|
||
```ts
|
||
interface Notebook {
|
||
id: string;
|
||
name: string;
|
||
color: string | null;
|
||
createdAt: string;
|
||
updatedAt: string;
|
||
noteCount: number; // active 노트만 (trashed 제외)
|
||
}
|
||
|
||
class NotebookRepository {
|
||
list(): Notebook[]; // count 포함, name ASC
|
||
findById(id: string): Notebook | null;
|
||
create(input: { name: string; color?: string }): Notebook;
|
||
rename(id: string, name: string): void; // UNIQUE name violation throw
|
||
setColor(id: string, color: string | null): void;
|
||
delete(id: string): { ok: true } | { ok: false; reason: 'has_notes' };
|
||
// 메모 잔류 시 FK RESTRICT throw → ok:false 변환
|
||
|
||
moveNote(noteId: string, notebookId: string): void;
|
||
countByNotebook(): Map<string, number>; // 한번 호출로 전체 count
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6. UI — 사이드바
|
||
|
||
```
|
||
┌───────────────┬─────────────────────────────────────┐
|
||
│ [≡] Inkling │ [Inbox(N) 완료(N) 휴지통(N)] [🔍] [⚙] │
|
||
├───────────────┼─────────────────────────────────────┤
|
||
│ ● 기본 (5) │ │
|
||
│ ● 회사 (12) │ NoteCard list (main pane) │
|
||
│ ● 학습 (3) │ │
|
||
│ + 새 노트북 │ │
|
||
│ ───── │ │
|
||
│ 메모 빠른 list │ │
|
||
│ ・제목1 │ │
|
||
│ ・제목2 #tag │ │
|
||
│ ・제목3 │ │
|
||
└───────────────┴─────────────────────────────────────┘
|
||
```
|
||
|
||
- 좌측, 폭 240px (사용자 조정 가능)
|
||
- 헤더 좌측 `≡` 클릭 → 토글. 단축키 `Cmd+B` / `Ctrl+B`
|
||
- 상단: notebook 목록 (active 노트 count badge). 클릭 → `selectedNotebookId` 변경
|
||
- "+ 새 노트북" 클릭 → NotebookCreateModal (name + optional color)
|
||
- 노트북 우클릭 / hover icon → rename / color 변경 / delete
|
||
- 하단: 메모 list — `selectedNotebookId` + `selectedView` (status 탭) 필터 결과의 compact view. 클릭 → main pane 의 noteCard 로 scroll.
|
||
|
||
---
|
||
|
||
## 7. UI — lifecycle 단순화
|
||
|
||
| 변경 | 내용 |
|
||
|------|------|
|
||
| 헤더 탭 | "Inbox / 완료 / 보관 / 휴지통" → **"Inbox / 완료 / 휴지통"** (3탭) |
|
||
| MoveStatusModal | "보관" 옵션 제거. 사용자 선택지: "완료" / "휴지통" (또는 "복원" — trash mode 에서) |
|
||
| countsByStatus IPC | `archived` 필드 제거. 기존 호출자 (헤더 badge) 적용 |
|
||
| NoteRepository.setStatus | `archived` 인자 받으면 throw (defensive). 마이그레이션 후 호출자 없음 |
|
||
| 데이터 호환성 | 기존 archived 노트 0건이라 마이그레이션 단계에서 `completed` 로 일괄 이동 |
|
||
|
||
---
|
||
|
||
## 8. store / IPC
|
||
|
||
```ts
|
||
interface InboxStore {
|
||
notebooks: Notebook[];
|
||
selectedNotebookId: string | null; // null = "모든 노트북" 검색 결과 등 특수 모드
|
||
sidebarVisible: boolean;
|
||
sidebarWidth: number;
|
||
loadNotebooks: () => Promise<void>;
|
||
selectNotebook: (id: string) => void;
|
||
createNotebook: (name: string, color?: string) => Promise<{ ok: boolean; reason?: string }>;
|
||
renameNotebook: (id: string, name: string) => Promise<{ ok: boolean; reason?: string }>;
|
||
setNotebookColor: (id: string, color: string | null) => Promise<void>;
|
||
deleteNotebook: (id: string) => Promise<{ ok: boolean; reason?: string }>;
|
||
moveNoteToNotebook: (noteId: string, notebookId: string) => Promise<void>;
|
||
toggleSidebar: () => void;
|
||
}
|
||
```
|
||
|
||
IPC channels (신설):
|
||
- `notebook:list` / `notebook:create` / `notebook:rename` / `notebook:set-color` / `notebook:delete`
|
||
- `notebook:move-note`
|
||
|
||
기존 변경:
|
||
- `inbox:list` / `inbox:list-by-status` 에 `notebookId?` 옵션 추가 (없으면 모든 노트북)
|
||
- `inbox:counts-by-status` 도 `notebookId?` 옵션 + `archived` 필드 제거
|
||
|
||
---
|
||
|
||
## 9. search 통합
|
||
|
||
- 기본 scope: `selectedNotebookId` 안 검색
|
||
- search box 옆 dropdown: "이 노트북" / "모든 노트북"
|
||
- `inbox:search` 에 `notebookId?` 옵션 추가
|
||
- search 결과 NoteCard 가 notebook 표시 (모든 노트북 검색 시) — 작은 색 chip + 이름
|
||
|
||
---
|
||
|
||
## 10. sync 영향 (Cut E 이후)
|
||
|
||
- export 시 frontmatter 에 `notebook` 필드 추가 (이름 — 다기기 간 id 충돌 회피)
|
||
- import 시 notebook 이름이 없으면 생성, 있으면 reuse
|
||
- 충돌: 같은 이름 + 다른 id 면 import side 의 id 우선 (deterministic)
|
||
|
||
---
|
||
|
||
## 11. AI × Notebook 통합
|
||
|
||
### 11-1. fit 매칭 (매 capture)
|
||
|
||
- `buildPrompt` 가 현재 notebooks 목록 (이름) 을 prompt 에 포함
|
||
- AI 응답 JSON 에 `notebook_match` 필드 (기존 notebook 이름 또는 null) 추가
|
||
- schema (Zod) 갱신: `notebook_match: z.string().nullable().optional()`
|
||
- 매치 성공 시 자동 배치 (Zero-Effort 가치 우선). NoteCard 의 notebook chip 클릭으로 1-click 변경 가능
|
||
- 매치 실패 / null → default "기본" notebook
|
||
|
||
prompt 추가 라인 예시 (한국어 자연어):
|
||
|
||
```
|
||
사용 가능한 노트북: 기본, 회사, 학습
|
||
이 노트가 위 노트북 중 하나에 명확히 속하면 그 이름을 "notebook_match" 에 반환. 그렇지 않으면 null.
|
||
새 노트북 이름을 만들지 말 것 — 기존 목록 안에서만 선택.
|
||
```
|
||
|
||
### 11-2. promotion 제안
|
||
|
||
**trigger** — 같은 tag 가 **active 노트 안 3건 이상** 누적되고 그 노트들이 모두 default "기본" notebook 에 있을 때 (`active` + `notebook_id = default` + 동일 tag).
|
||
|
||
분석 timing — inbox 열릴 때 lazy. 단순 SQL aggregation 이라 cost 무시 가능.
|
||
|
||
```sql
|
||
SELECT t.name, COUNT(DISTINCT n.id) AS cnt
|
||
FROM tags t
|
||
JOIN note_tags nt ON nt.tag_id = t.id
|
||
JOIN notes n ON n.id = nt.note_id
|
||
WHERE n.status = 'active'
|
||
AND n.notebook_id = '<default-id>'
|
||
GROUP BY t.id
|
||
HAVING cnt >= 3
|
||
```
|
||
|
||
매치 발생 시 InboxStore 에 `promotionCandidate: { tag, noteIds, suggestedName }` 채움. banner 가 표시.
|
||
|
||
**v0.4 first release 는 rule only** — LLM 의 semantic cluster 분석은 cost 큼. dogfood 결과 보고 v0.5+ 검토.
|
||
|
||
### 11-3. UI — PromotionBanner
|
||
|
||
- Inbox 상단, RecallBanner / ExpiryBanner 와 같은 위치
|
||
- 문구 예: "💡 `mlx-ops` 관련 노트 6개가 모였어요. 새 노트북 **MLX Ops** 로 분리할까요?"
|
||
- 액션: `[수락]` `[나중에]` `[숨기기]`
|
||
- 수락 → 작은 modal 띄움 (이름 inline 수정 + color 선택) → notebook 생성 + 해당 noteIds 일괄 이동 + 사이드바 자동 열어 새 notebook 가시화
|
||
- 나중에 → 24h snooze (RecallBanner 패턴)
|
||
- 숨기기 → 해당 tag 영구 dismiss (`settings.promotion_dismissed_tags` array)
|
||
|
||
### 11-4. notebook 이름 generation
|
||
|
||
- default: tag 이름을 Title Case 변환 (예: `mlx-ops` → `MLX Ops`, `user-management` → `User Management`)
|
||
- 사용자가 수락 modal 에서 inline 수정 가능
|
||
|
||
### 11-5. promotion 후 status 보존
|
||
|
||
- 이동된 노트의 `status` 그대로 유지 (active → active, completed → completed)
|
||
- `notebook_id` 만 변경
|
||
|
||
### 11-6. 새 노트의 자동 fit 매칭이 promoted notebook 도 인식
|
||
|
||
- promotion 후 notebooks 목록에 새 notebook 포함 → 다음 capture 의 prompt 에 자동 반영
|
||
- 그 후 같은 주제 노트는 자동으로 새 notebook 에 들어감
|
||
|
||
---
|
||
|
||
## 12. 테스트 전략
|
||
|
||
| 영역 | 케이스 |
|
||
|------|--------|
|
||
| NotebookRepository | CRUD + count + delete RESTRICT |
|
||
| migration m008 | default notebook 생성 + 기존 노트 마이그레이션 + archived → completed |
|
||
| store actions | 토글 + 선택 변경 + create/rename/delete 흐름 |
|
||
| UI 사이드바 | notebook 목록 render + 클릭 selectedNotebookId 변경 + count badge |
|
||
| 메모 list 필터 | notebook + view 필터 combination |
|
||
| search scope | current / all 옵션별 결과 |
|
||
| MoveStatusModal | archived 옵션 부재 |
|
||
| 헤더 탭 | 3탭 + count |
|
||
| AI prompt notebook_match | prompt 에 notebooks 목록 포함 + AI 응답 schema 의 notebook_match 필드 |
|
||
| capture 자동 fit | AI 응답 notebook_match 매치 시 자동 배치, 미매치 시 default |
|
||
| promotion query | tag 3건 이상 + default notebook 클러스터 검출 |
|
||
| PromotionBanner | 수락 → notebook 생성 + 일괄 이동 / 나중에 → 24h snooze / 숨기기 → tag dismiss 영구 저장 |
|
||
|
||
---
|
||
|
||
## 13. risks
|
||
|
||
| risk | 대응 |
|
||
|------|------|
|
||
| migration 의 status check constraint 갱신 실패 | SQLite 새 테이블 복사 패턴 + 검증 query 후 commit |
|
||
| 좁은 화면 (1280×720) 에서 사이드바 부담 | settings.sidebar_visible default false (사용자가 켜야 보임) |
|
||
| notebook 삭제 시 RESTRICT error UX | "메모 N건 이동 후 다시 시도" + 이동 dialog 제공 |
|
||
| sync (Cut E) 와 결합 시 notebook 정합성 | frontmatter notebook 이름 기반 — 다기기 간 ID 충돌 회피 |
|
||
| tag 와 notebook 의미 혼동 | UI text 명시: "노트북 = 컨텍스트 (회사 / 개인)", "태그 = 주제 키워드 (mlx-ops, keycloak)" — 설정 페이지 도움말에 안내 |
|
||
| 사용자가 다중 notebook 실제 안 만들면 default 1개 + 사이드바 = noise | default sidebar hidden + 사용자가 2번째 notebook 만들 때 자동 reveal hint |
|
||
| AI 가 notebook_match 에 새 이름 ad-hoc 생성 시도 | prompt 에 "기존 목록 안에서만 선택, 새 이름 만들지 말 것" 명시 + schema 검증 단계에서 notebooks 목록과 매치 안 되는 값은 null 로 coerce |
|
||
| 같은 tag 의 promotion 이 반복 노출되어 사용자 피로 | "숨기기" → 영구 dismiss (settings 의 array). RecallBanner 의 24h snooze 와 별개 영구 저장소 |
|
||
|
||
---
|
||
|
||
## 14. 게이트
|
||
|
||
- 단위 테스트 — notebook CRUD + migration + UI 사이드바 + 메모 list 필터 + status 3분기 회귀 + AI fit/promotion 분기
|
||
- 마이그레이션 verify — fresh DB + 기존 DB 두 시나리오에서 default notebook 생성 + archived 정리
|
||
- dogfood — 2-3 일 후 (1) 사이드바 열려있는 비율, (2) notebook 갯수 (수동 vs promoted), (3) notebook 간 메모 이동 빈도, (4) promotion 수락률 측정
|
||
|
||
---
|
||
|
||
## 15. 작업 분해 (writing-plans 입력)
|
||
|
||
1. **m008 마이그레이션** — notebooks 테이블 + notes.notebook_id + archived 정리 + status enum
|
||
2. **NotebookRepository** + IPC 핸들러
|
||
3. **NoteRepository** 변경 — notebook_id 필터, list/search/counts 옵션 확장
|
||
4. **store** — notebooks state + actions + promotionCandidate state
|
||
5. **AI prompt 변경** — buildPrompt 에 notebooks 목록 주입, schema 의 notebook_match 필드, AiWorker 가 응답 매치하여 자동 배치 (또는 default 로 coerce)
|
||
6. **promotion 분석** — NoteRepository.findPromotionCandidates 쿼리 + store action (inbox open 시 lazy)
|
||
7. **PromotionBanner UI** — Inbox 상단, 수락 modal, 24h snooze, 영구 dismiss
|
||
8. **사이드바 UI** — Sidebar.tsx + NotebookList + NotebookCreateModal
|
||
9. **헤더 / MoveStatusModal** — archived 제거
|
||
10. **search** — scope 옵션 통합
|
||
11. **sync (옵션 deferred)** — frontmatter notebook 필드. v0.4 본체 머지 후 별도 작업으로 가능
|
||
12. **CHANGELOG + release notes** — dogfood 근거 명시
|