Files

altair823 1104a8c666 docs(plan): v0.2.11 Cut D — FTS5 search + 회고 view (spec m006→m007 정정 + ai_title/ai_summary + note_tags JOIN)

2026-05-10 00:11:12 +09:00

11 KiB

Raw Blame History

v0.2.11 — Cut D Design (FTS5 search + 회고 view)

작성일: 2026-05-09 선행 문서:

docs/superpowers/specs/2026-04-25-dogfood-feedback.md (F19)
docs/superpowers/strategy/v028plus-roadmap.md Cut D

Cut 라벨: v0.2.11

1. Cut 정체성

recall 핵심 가치 도달 — search + 회고 view. F19 의 6 옵션 중 A (FTS5 search) + D (회고 view) 2개. B/C/E/F 는 v0.3+ deferred.

2. 범위

항목	결정
F19-A	SQLite FTS5 인덱스 + inbox 헤더 search box
F19-D	일/주/월 회고 라우트 — aggregate query + N건 list + tag distribution + due 진행

3. F19-A 디테일 (FTS5)

3-1. Schema 마이그레이션 (m007)

메모: 본 스펙 작성 시점에는 m006 로 예상했으나 Cut C (v0.2.10) 에서 m006 (note_revisions) 가 선점됨 → 실제 번호는 m007.

실제 schema 정정:

notes.title/notes.summary 컬럼 없음 → 실제 notes.ai_title/notes.ai_summary 사용
notes.tags_csv 컬럼 없음 → tags 는 note_tags join (note_tags.note_id ↔ tags.id)
notes.status (Cut B m004 도입) 사용 가능 — status != 'trashed' 필터

CREATE VIRTUAL TABLE notes_fts USING fts5(
  note_id UNINDEXED,
  raw_text,
  ai_title,
  ai_summary,
  tags,
  tokenize='unicode61'
);

-- 기존 notes (active/completed/archived 만 — trashed 제외) 모두 인덱스.
-- tags 는 note_tags+tags JOIN 후 GROUP_CONCAT 으로 csv 구성.
INSERT INTO notes_fts (note_id, raw_text, ai_title, ai_summary, tags)
  SELECT
    n.id,
    n.raw_text,
    COALESCE(n.ai_title, ''),
    COALESCE(n.ai_summary, ''),
    COALESCE((SELECT GROUP_CONCAT(t.name, ' ')
                FROM note_tags nt JOIN tags t ON t.id = nt.tag_id
               WHERE nt.note_id = n.id), '')
  FROM notes n
  WHERE n.status != 'trashed';

tokenize='unicode61' — 한국어 partial tokenize 가능 (단어 boundary). 향후 tokenize='porter unicode61' 또는 한국어 전용 tokenizer (예: mecab-ko-fts5) 검토 가능 — Cut D 는 unicode61 default.

tags 컬럼 = note_tags JOIN 결과 csv (예: "기획 회의 결재"). note_tags 변경 시 NoteRepository 에서 명시적 헬퍼 (rebuildFtsTagsForNote(noteId)) 호출 — trigger 로 sync 어려움 (note_tags INSERT/DELETE 가 다른 노트 row 재계산 트리거하기 부담). 단일 write path 패턴 (Cut C 확립) 으로 강제.

3-2. Trigger — auto-sync (notes 컬럼 한정)

notes INSERT/UPDATE/DELETE 시 notes_fts 자동 sync (raw_text/ai_title/ai_summary 만; tags 는 별도 헬퍼):

CREATE TRIGGER notes_ai AFTER INSERT ON notes BEGIN
  INSERT INTO notes_fts (note_id, raw_text, ai_title, ai_summary, tags)
    VALUES (NEW.id, NEW.raw_text, COALESCE(NEW.ai_title, ''), COALESCE(NEW.ai_summary, ''), '');
END;

CREATE TRIGGER notes_ad AFTER DELETE ON notes BEGIN
  DELETE FROM notes_fts WHERE note_id = OLD.id;
END;

CREATE TRIGGER notes_au AFTER UPDATE ON notes BEGIN
  UPDATE notes_fts
     SET raw_text   = NEW.raw_text,
         ai_title   = COALESCE(NEW.ai_title, ''),
         ai_summary = COALESCE(NEW.ai_summary, '')
   WHERE note_id = NEW.id;
END;

Cut C 의 updateRawText 가 notes.raw_text UPDATE → trigger 자동 발동 → FTS5 갱신.

tags 갱신 path:

NoteRepository.updateAiResult (AI tags) / updateUserAiFields (사용자 tags) 모두 note_tags 변경 후 동일 transaction 안에서 rebuildFtsTagsForNote(noteId) 호출.

trashed 노트 처리 — setStatus(id, 'trashed', ...) 시 trigger AFTER UPDATE 발동되어 FTS row 가 그대로 유지됨. 검색 시 query 단계에서 n.status != 'trashed' 필터로 제외 (별도 FTS row cleanup 안 함 — YAGNI).

3-3. NoteRepository.search

search(query: string, opts: { limit?: number; status?: NoteStatus } = {}): Note[] {
  if (query.trim().length === 0) return [];
  const limit = Math.max(1, Math.min(200, opts.limit ?? 50));
  const ftsQuery = sanitizeFtsQuery(query);  // FTS5 special char escape
  const statusClause = opts.status ? `AND n.status = ?` : `AND n.status != 'trashed'`;
  const sql = `
    SELECT n.* FROM notes n
    JOIN notes_fts f ON n.id = f.note_id
    WHERE notes_fts MATCH ? ${statusClause}
    ORDER BY rank LIMIT ?
  `;
  const args = opts.status ? [ftsQuery, opts.status, limit] : [ftsQuery, limit];
  const rows = this.db.prepare(sql).all(...args) as Record<string, unknown>[];
  return rows.map((r) => this.hydrate(r));
}

hydrate — 기존 패턴 (tags + media join). sanitizeFtsQuery — FTS5 special chars (", *, (, ), :) 이스케이프 및 multi-word AND 결합 (예: 기획 회의 → "기획" AND "회의" 또는 기획 회의 그대로 수용). YAGNI: 다중 토큰을 그대로 FTS5 implicit AND 로 보냄 + 따옴표 제거.

status 미지정 시 default = trashed 제외.

MATCH 쿼리 syntax — FTS5 standard ("기획 회의", 회의 OR 결재, 기획* 등).

기존 헤더 (Inbox/완료/보관/휴지통 탭) 옆에 search input:

<input
  type="search"
  placeholder="검색..."
  value={searchQuery}
  onChange={e => setSearchQuery(e.target.value)}
  style={{ ... }}
/>

debounce 200ms → store action searchNotes(query) → inboxApi.search(query, { status: currentView }) → result list 갱신.

빈 query → 기본 inbox list 복귀.

3-5. IPC

'inbox:search': (query: string, opts: { status?: NoteStatus; limit?: number }) => Promise<Note[]>

4. F19-D 디테일 (회고 view)

4-1. 라우트 추가

useInbox.view enum 에 'review-daily' | 'review-weekly' | 'review-monthly' 추가. 진입점:

헤더 메뉴: "📅 회고" 버튼 → 드롭다운 (일/주/월)
또는 별도 라우트 (Settings 옆)

4-2. 회고 view 컴포넌트

// src/renderer/inbox/components/ReviewView.tsx
export function ReviewView({ period }: { period: 'daily' | 'weekly' | 'monthly' }): ReactElement {
  const data = useReviewData(period);  // store action — aggregate query 결과
  return (
    <div>
      <h2>{periodLabel(period)} 회고</h2>
      <div>총 N건 • 오늘 N건 • 평균 일 N건</div>
      <TagDistributionChart tags={data.tagCounts} />
      <DueProgressChart due={data.dueProgress} />
      <NoteList notes={data.recentNotes} />
    </div>
  );
}

4-3. Aggregate query

NoteRepository:

reviewAggregate(period: 'daily' | 'weekly' | 'monthly', now: Date = new Date()): {
  totalCount: number;
  recentNotes: Note[];
  tagCounts: Array<{ tag: string; count: number }>;
  dueProgress: { total: number; passed: number; pending: number };
} {
  const cutoff = computeCutoff(period, now);  // ISO string — KST 자정 / 7일전 / 30일전
  const todayIso = kstTodayIso(now);  // YYYY-MM-DD
  const totalCount = (this.db
    .prepare(`SELECT COUNT(*) as c FROM notes WHERE created_at >= ? AND status != 'trashed'`)
    .get(cutoff) as { c: number }).c;
  const recentRows = this.db
    .prepare(`SELECT * FROM notes WHERE created_at >= ? AND status != 'trashed'
              ORDER BY created_at DESC, id DESC LIMIT 50`)
    .all(cutoff) as Record<string, unknown>[];
  const recentNotes = recentRows.map((r) => this.hydrate(r));
  // tag counts via note_tags JOIN — period 안 노트의 태그만 집계
  const tagCounts = this.db
    .prepare(`SELECT t.name AS tag, COUNT(*) AS count
              FROM note_tags nt
              JOIN notes n ON n.id = nt.note_id
              JOIN tags t ON t.id = nt.tag_id
              WHERE n.created_at >= ? AND n.status != 'trashed'
              GROUP BY t.id
              ORDER BY count DESC, t.name ASC`)
    .all(cutoff) as Array<{ tag: string; count: number }>;
  // due progress — period 안 created 노트 중 due_date 가 있는 것
  const dueRow = this.db
    .prepare(`SELECT
                COUNT(*) AS total,
                SUM(CASE WHEN due_date < ? THEN 1 ELSE 0 END) AS passed,
                SUM(CASE WHEN due_date >= ? THEN 1 ELSE 0 END) AS pending
              FROM notes
              WHERE created_at >= ?
                AND status != 'trashed'
                AND due_date IS NOT NULL`)
    .get(todayIso, todayIso, cutoff) as { total: number; passed: number | null; pending: number | null };
  const dueProgress = {
    total: dueRow.total,
    passed: dueRow.passed ?? 0,
    pending: dueRow.pending ?? 0
  };
  return { totalCount, recentNotes, tagCounts, dueProgress };
}

computeCutoff('daily', now) = KST 자정 (오늘 시작) ISO. 'weekly' = 7일 전 KST 자정 ISO. 'monthly' = 30일 전 KST 자정 ISO. kstTodayIso 는 src/shared/util/kstDate.ts 에 이미 존재 (Cut B 활용).

period 별 query 는 동일 transaction 으로 wrap 해도 되나, read-only + 단일 호출이라 단순 sequential 호출로 충분 (better-sqlite3 동기 API).

4-4. Tag distribution chart

간단한 bar list (CSS — chart 라이브러리 X):

{data.tagCounts.slice(0, 10).map(t => (
  <div key={t.tag}>
    <span>{t.tag}</span>
    <div style={{ width: `${(t.count / max) * 100}%`, background: '#4ec5b8', height: 8 }} />
    <span>{t.count}</span>
  </div>
))}

4-5. Due progress

완료 (passed): 12 / 25
대기 (pending): 13
이번 주 due: 3건

5. 테스트 전략

영역	단위
m007 마이그레이션	FTS5 virtual table + trigger 3개 + 기존 notes backfill (status != 'trashed' + tags JOIN)
Trigger sync	INSERT/UPDATE/DELETE → notes_fts 자동 sync (raw_text/ai_title/ai_summary)
`rebuildFtsTagsForNote` 헬퍼	note_tags 변경 후 FTS tags 컬럼 재구성
`updateAiResult` / `updateUserAiFields`	tags 변경 path 가 헬퍼 호출하여 FTS sync (회귀)
`updateRawText` (Cut C) FTS sync 회귀	trigger 자동 발동 검증
`search`	한국어 token 매칭 + status filter + trashed 기본 제외 + 빈 query → []
`sanitizeFtsQuery`	FTS5 special char 이스케이프 + multi-word 통과
inbox header search box	debounce + 빈 값 → 기본 list 복귀
ReviewView 단위	aggregate query 결과 렌더 + period 라벨
`reviewAggregate`	period 별 cutoff 정확 + tag count + due progress (passed/pending KST 비교)
`computeCutoff`	daily/weekly/monthly KST 자정 ISO

목표: 단위 569 → 약 595 (+26), typecheck 0.

6. Risk

Risk	대응
FTS5 한국어 token 정확도 (unicode61 가 word boundary 부정확)	dogfood 검증. 부족 시 v0.3+ 에서 mecab-ko 또는 trigram tokenize 검토
FTS5 인덱스 size (notes 수만건 시 DB 크기 ↑)	수만건 도달 전엔 무시. v0.3+ 에서 prune 또는 partial 인덱스
회고 aggregate query latency	LIMIT 50 + index 활용 (`created_at DESC`). 수만건도 sub-second 예상
Cut C revision 추가 시 FTS 영향	revision 은 인덱스 X (latest only). `notes` AFTER UPDATE trigger 가 raw_text 변경 자동 반영
`note_tags` 변경 누락 시 FTS tags stale	NoteRepository 의 tags 변경 path 모두에서 `rebuildFtsTagsForNote` 명시 호출 — single write path 패턴 강제
FTS5 special char crash	`sanitizeFtsQuery` 에서 `"`/`*`/`(`/`)`/`:` 이스케이프 또는 제거

7. v0.2.11 후

Cut E (v0.3.0) — F21 양방향 sync.

dogfood verify:

search 일 사용 빈도 (가설: ≥ 일 1회면 가치 있음)
회고 view 사용 빈도 (월요일 자동 prompt 추가 검토 — v0.3+)
FTS5 한국어 token 정확도 (사용자 query 결과 만족도)

11 KiB Raw Blame History