docs(plan): F1 due date 구현 계획 (6 tasks, migration v2)
This commit is contained in:
altair823
355
docs/superpowers/plans/2026-04-26-f1-due-date.md
Normal file
355
docs/superpowers/plans/2026-04-26-f1-due-date.md
Normal file
@@ -0,0 +1,355 @@
|
||||
# F1 Due Date Implementation Plan
|
||||
|
||||
**Goal:** Extract `due_date` (ISO YYYY-MM-DD) from Korean note text. Hybrid: rule parser first (regex + KST), AI fallback in same generate response. Store on notes table, render as inline grey label on Inbox card, editable.
|
||||
|
||||
**Architecture:** Pure rule parser (regex + KST math) → AiWorker injects rule result + TODAY_KST into AI prompt → AI returns `due_date` field; final value = rule match if any else AI value. NoteRepository v2 schema + edited-flag invariant (mirrors title/summary pattern).
|
||||
|
||||
**Tech Stack:** TypeScript, vitest, zod 4, no new deps.
|
||||
|
||||
## File Structure
|
||||
|
||||
**Create:**
|
||||
- `src/main/db/migrations/m002_due_date.ts` — schema migration
|
||||
- `src/main/services/dueDateParser.ts` — pure rule parser
|
||||
- `tests/unit/dueDateParser.test.ts` — golden fixtures
|
||||
- `tests/unit/migrations.due_date.test.ts` — migration test
|
||||
- `docs/superpowers/specs/2026-04-26-f1-due-date.md` — promoted spec
|
||||
|
||||
**Modify:**
|
||||
- `src/main/db/migrations/index.ts` — register m002
|
||||
- `src/main/db/migrations/m001_initial.ts` — version export consistency check (already at 1)
|
||||
- `src/main/repository/NoteRepository.ts` — extend `updateAiResult`, new `setDueDate`, `hydrate` returns dueDate fields
|
||||
- `src/shared/types.ts` — `Note.dueDate`, `Note.dueDateEditedByUser`
|
||||
- `src/main/ai/schema.ts` — zod `due_date` field, AiResponse extends
|
||||
- `src/main/ai/prompt.ts` — inject `{{TODAY_KST}}` + add due_date instruction
|
||||
- `src/main/ai/AiWorker.ts` — call rule parser, merge with AI response
|
||||
- `src/main/ipc/inboxApi.ts` — extend `inbox:updateAi` to accept `dueDate?`, new `inbox:setDueDate`
|
||||
- `src/preload/index.ts` — expose `setDueDate`
|
||||
- `src/renderer/inbox/store.ts` — wire setDueDate
|
||||
- `src/renderer/inbox/components/NoteCard.tsx` — render due_date badge inline next to title
|
||||
- `src/renderer/inbox/components/EditableField.tsx` — reuse for date editing OR add small DateField
|
||||
- `tests/unit/NoteRepository.test.ts` — due_date insertion + edited-flag guard cases
|
||||
- `tests/unit/ai-schema.test.ts` — due_date field validation
|
||||
- `docs/superpowers/specs/2026-04-25-dogfood-feedback.md` — F1 status update
|
||||
|
||||
**Schema change: YES (migration v2). No new dependencies.**
|
||||
|
||||
## Decisions
|
||||
|
||||
| 결정 항목 | 값 | 근거 |
|
||||
|----------|-----|------|
|
||||
| 매칭 우선순위 | 규칙 파서 우선 → 매칭 없으면 AI 응답 사용 | 결정론적 우선 |
|
||||
| 모호 표현 | AI 위임 (e.g., "월말", "주말") | 규칙 파서 false positive 회피 |
|
||||
| 만료된 노트 | 회색 + 취소선 (라벨만, 노트 본문 무수정) | slice §1.1 카피 정책 |
|
||||
| 라벨 슬롯 | 제목 옆 인라인 (`📅 YYYY-MM-DD` 작은 회색) | 시각 노이즈 최소 |
|
||||
| 사용자 편집 | EditableField 재사용 + date input | 일관성 |
|
||||
| 시각 단위 | strip (시간 정보 무시, 날짜만) | F1 spec §Out |
|
||||
| 음력 / 절기 | 미지원 | F1 spec §Out |
|
||||
| 반복 일정 | 미지원 | F1 spec §Out |
|
||||
| 만료 자동 처리 | 없음 (시각 표시만) | dogfood 피드백 후 결정 |
|
||||
| 별도 뷰 / 정렬 | 없음 | 후속 |
|
||||
| Migration v2 backfill | 없음 (NULL 기본값) | 비파괴 |
|
||||
|
||||
## Pre-migration snapshot (F6-L1 follow-up #4)
|
||||
|
||||
`runMigrations()` is invoked inside `openDb()` at startup, BEFORE BackupService is instantiated. To honor the F6-L1 spec's silent invariant ("데이터 손실 0회"), this PR adds a pre-migration snapshot in `openDb`:
|
||||
|
||||
```typescript
|
||||
// Pseudocode (inside openDb after opening, before runMigrations)
|
||||
if (currentVersion < TARGET_VERSION) {
|
||||
// Take a snapshot of the pre-migration state
|
||||
await dbBackupSync(db, `${dbFile}.pre-v${TARGET_VERSION}.bak`);
|
||||
}
|
||||
runMigrations(db);
|
||||
```
|
||||
|
||||
Adjustment: since `openDb` returns sync, use `db.backup()` followed by `await` only inside an async wrapper, OR copy the file with `fs.copyFileSync` BEFORE opening the WAL DB. Choose the simplest path: copy `dbFile` to `dbFile.pre-v2.bak` via `fs.copyFileSync` if `pre-v2.bak` doesn't exist AND `user_version < 2`. Pure sync, no async refactor, no double-WAL concerns.
|
||||
|
||||
## Task Breakdown
|
||||
|
||||
### Task 1: Migration v2 + NoteRepository
|
||||
|
||||
**Files:**
|
||||
- Create `src/main/db/migrations/m002_due_date.ts`:
|
||||
|
||||
```typescript
|
||||
import type Database from 'better-sqlite3';
|
||||
|
||||
export const version = 2;
|
||||
|
||||
export function up(db: Database.Database): void {
|
||||
db.exec(`
|
||||
ALTER TABLE notes ADD COLUMN due_date TEXT;
|
||||
ALTER TABLE notes ADD COLUMN due_date_edited_by_user INTEGER NOT NULL DEFAULT 0
|
||||
CHECK (due_date_edited_by_user IN (0,1));
|
||||
`);
|
||||
}
|
||||
```
|
||||
|
||||
- Modify `src/main/db/migrations/index.ts` to register m002:
|
||||
|
||||
```typescript
|
||||
import * as m001 from './m001_initial.js';
|
||||
import * as m002 from './m002_due_date.js';
|
||||
const migrations = [m001, m002];
|
||||
```
|
||||
|
||||
- Modify `src/main/db/index.ts` to add pre-migration snapshot:
|
||||
|
||||
```typescript
|
||||
import Database from 'better-sqlite3';
|
||||
import { existsSync, copyFileSync } from 'node:fs';
|
||||
import { runMigrations, latestVersion } from './migrations/index.js';
|
||||
|
||||
export function openDb(dbFile: string): Database.Database {
|
||||
// Pre-migration snapshot if upgrading
|
||||
if (existsSync(dbFile)) {
|
||||
const probe = new Database(dbFile, { readonly: true });
|
||||
const cur = (probe.pragma('user_version', { simple: true }) as number) ?? 0;
|
||||
probe.close();
|
||||
if (cur < latestVersion()) {
|
||||
const bak = `${dbFile}.pre-v${latestVersion()}.bak`;
|
||||
if (!existsSync(bak)) {
|
||||
copyFileSync(dbFile, bak);
|
||||
}
|
||||
}
|
||||
}
|
||||
const db = new Database(dbFile);
|
||||
db.pragma('journal_mode = WAL');
|
||||
db.pragma('foreign_keys = ON');
|
||||
runMigrations(db);
|
||||
return db;
|
||||
}
|
||||
```
|
||||
|
||||
Add `latestVersion()` to migrations/index.ts:
|
||||
|
||||
```typescript
|
||||
export function latestVersion(): number {
|
||||
return migrations[migrations.length - 1]!.version;
|
||||
}
|
||||
```
|
||||
|
||||
- Modify `src/main/repository/NoteRepository.ts`:
|
||||
- Hydrate dueDate fields
|
||||
- Extend `updateAiResult` signature to take `{ dueDate?: string | null }` and add to UPDATE SET with edited-flag guard
|
||||
- Add `setDueDate(id: string, date: string | null): void` (mirrors updateUserAiFields pattern, sets `due_date_edited_by_user = 1`)
|
||||
|
||||
```typescript
|
||||
// hydrate addition
|
||||
return {
|
||||
...other fields,
|
||||
dueDate: row.due_date,
|
||||
dueDateEditedByUser: row.due_date_edited_by_user === 1,
|
||||
};
|
||||
|
||||
// updateAiResult signature
|
||||
updateAiResult(id, result: { title; summary; tags; provider; dueDate?: string | null })
|
||||
|
||||
// New SET clause inside UPDATE notes:
|
||||
ai_due_date = CASE WHEN due_date_edited_by_user = 1 THEN due_date ELSE ? END
|
||||
|
||||
// Wait — column name is due_date not ai_due_date. Use due_date directly.
|
||||
|
||||
// New method
|
||||
setDueDate(id, date) {
|
||||
const now = new Date().toISOString();
|
||||
this.db.prepare(
|
||||
`UPDATE notes SET due_date = ?, due_date_edited_by_user = 1, updated_at = ? WHERE id = ?`
|
||||
).run(date, now, id);
|
||||
}
|
||||
```
|
||||
|
||||
- Modify `src/shared/types.ts`:
|
||||
- Add `dueDate: string | null` and `dueDateEditedByUser: boolean` to Note interface
|
||||
|
||||
- Test in `tests/unit/migrations.due_date.test.ts`:
|
||||
1. Fresh DB has user_version = 2 after migrations
|
||||
2. due_date column exists, defaults NULL
|
||||
3. due_date_edited_by_user defaults 0
|
||||
|
||||
- Test additions in `tests/unit/NoteRepository.test.ts`:
|
||||
1. Created note has dueDate=null, dueDateEditedByUser=false
|
||||
2. updateAiResult with dueDate sets due_date when edited flag = 0
|
||||
3. updateAiResult does NOT overwrite due_date when edited flag = 1
|
||||
4. setDueDate sets due_date and edited flag
|
||||
|
||||
Commit Task 1:
|
||||
```
|
||||
feat(db): migration v2 — due_date columns + pre-migration snapshot
|
||||
|
||||
- ALTER TABLE notes ADD due_date TEXT, due_date_edited_by_user INTEGER
|
||||
- openDb takes <dbFile>.pre-v<N>.bak before migrations (F6-L1 follow-up #4)
|
||||
- NoteRepository updateAiResult(dueDate?) + setDueDate + hydrate
|
||||
- Note type extended with dueDate / dueDateEditedByUser
|
||||
|
||||
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
||||
```
|
||||
|
||||
### Task 2: Pure rule parser
|
||||
|
||||
**File:** `src/main/services/dueDateParser.ts`
|
||||
|
||||
```typescript
|
||||
export interface ParseResult {
|
||||
iso: string | null; // YYYY-MM-DD or null if no match
|
||||
confidence: 'high' | 'medium' | null;
|
||||
matchedToken: string | null;
|
||||
}
|
||||
|
||||
export function parseDueDate(text: string, todayKst: Date): ParseResult { ... }
|
||||
```
|
||||
|
||||
`todayKst` is the KST midnight Date (caller computes via `+9h offset` at call site).
|
||||
|
||||
Rules (try in order, first match wins):
|
||||
1. **YYYY-MM-DD literal** — `\d{4}-\d{2}-\d{2}` → high
|
||||
2. **N월 N일** — `(\d{1,2})월\s*(\d{1,2})일` → resolve to current year if same/future, else next year. high.
|
||||
3. **MM/DD** — `(\d{1,2})\/(\d{1,2})` → same logic. high.
|
||||
4. **N일 뒤 / N일 후** — `(\d+)\s*일\s*(뒤|후)` → today + N. high.
|
||||
5. **N주 뒤 / N주 후** — `(\d+)\s*주\s*(뒤|후)` → today + N*7. high.
|
||||
6. **N개월 뒤** — `(\d+)\s*개월\s*(뒤|후)` → calendar add. high.
|
||||
7. **모레** — today + 2. high.
|
||||
8. **내일** — today + 1. high.
|
||||
9. **글피** — today + 3. high.
|
||||
10. **다음 주 X요일** — `다음\s*주\s*([월화수목금토일])요일` → KST Monday of next week + offset. high.
|
||||
11. **이번 주 X요일** — `이번\s*주\s*([월화수목금토일])요일` → KST Monday of current week + offset. high.
|
||||
12. **다음 주말** / **주말** / **월말** — null (defer to AI). medium-tier match info but iso=null.
|
||||
13. **오늘** — today. high. (Yes ambiguous — but regex parser commits to today; user can edit if wrong.)
|
||||
|
||||
Tests in `tests/unit/dueDateParser.test.ts` — golden fixtures (≥ 25):
|
||||
|
||||
```typescript
|
||||
const TODAY_KST = new Date('2026-04-26T00:00:00+09:00');
|
||||
expect(parseDueDate('내일 회의', TODAY_KST).iso).toBe('2026-04-27');
|
||||
expect(parseDueDate('모레 발표', TODAY_KST).iso).toBe('2026-04-28');
|
||||
expect(parseDueDate('3일 뒤 데모', TODAY_KST).iso).toBe('2026-04-29');
|
||||
expect(parseDueDate('5월 1일 휴가', TODAY_KST).iso).toBe('2026-05-01');
|
||||
expect(parseDueDate('다음 주 월요일까지 슬라이드', TODAY_KST).iso).toBe('2026-05-04'); // anchor next Monday
|
||||
expect(parseDueDate('이번 주 일요일', TODAY_KST).iso).toBe('2026-04-26'); // already Sun? actually 04-26 is Sun, so this Sunday = today
|
||||
expect(parseDueDate('다음 달 1일', TODAY_KST).iso).toBe('2026-05-01');
|
||||
expect(parseDueDate('월말 마감', TODAY_KST).iso).toBeNull(); // defer
|
||||
expect(parseDueDate('주말까지', TODAY_KST).iso).toBeNull(); // defer
|
||||
expect(parseDueDate('오늘 PR 리뷰', TODAY_KST).iso).toBe('2026-04-26');
|
||||
expect(parseDueDate('오후 3시 미팅', TODAY_KST).iso).toBeNull(); // time-only, not a date token
|
||||
expect(parseDueDate('퇴근 전', TODAY_KST).iso).toBeNull(); // defer
|
||||
expect(parseDueDate('하루 동안 잘 잤다', TODAY_KST).iso).toBeNull(); // no token
|
||||
expect(parseDueDate('2026-05-15 마감', TODAY_KST).iso).toBe('2026-05-15');
|
||||
expect(parseDueDate('5/3 데모', TODAY_KST).iso).toBe('2026-05-03');
|
||||
expect(parseDueDate('3월 1일 발표', TODAY_KST).iso).toBe('2027-03-01'); // next year (past in current)
|
||||
expect(parseDueDate('2주 뒤 회의', TODAY_KST).iso).toBe('2026-05-10');
|
||||
expect(parseDueDate('1개월 뒤 점검', TODAY_KST).iso).toBe('2026-05-26');
|
||||
expect(parseDueDate('내일도 모레도 바쁨', TODAY_KST).iso).toBe('2026-04-27'); // first match
|
||||
```
|
||||
|
||||
Commit Task 2:
|
||||
```
|
||||
feat(due-date): pure rule parser for Korean date expressions
|
||||
|
||||
Regex + KST math, returns ISO YYYY-MM-DD or null. 13 rule categories,
|
||||
first match wins. Ambiguous tokens (월말, 주말, 퇴근 전) return null
|
||||
to defer to AI. 25+ golden fixtures cover normal + edge cases.
|
||||
|
||||
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
||||
```
|
||||
|
||||
### Task 3: AI schema + prompt
|
||||
|
||||
**Files:** `src/main/ai/schema.ts`, `src/main/ai/prompt.ts`
|
||||
|
||||
- schema.ts: extend RawResponseSchema with `due_date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).nullable().optional()`. Update AiResponse interface to add `dueDate: string | null`.
|
||||
- prompt.ts: add `{{TODAY_KST}}` template + due_date instruction. Add second function or extend signature:
|
||||
|
||||
```typescript
|
||||
export function buildPrompt(rawText: string, todayKst: string): string {
|
||||
return `... existing ...
|
||||
- "due_date": ISO YYYY-MM-DD if you can extract a clear deadline from "${rawText}" relative to today (${todayKst} KST), else null.
|
||||
...`;
|
||||
}
|
||||
```
|
||||
|
||||
Tests in `tests/unit/ai-schema.test.ts` (extend):
|
||||
- due_date null accepted
|
||||
- due_date YYYY-MM-DD accepted
|
||||
- due_date `2026-13-99` rejected (regex fails)
|
||||
- due_date `tomorrow` rejected
|
||||
|
||||
Commit Task 3:
|
||||
```
|
||||
feat(ai): zod due_date field + prompt {{TODAY_KST}} injection
|
||||
|
||||
AiResponse extends with dueDate: string|null. Prompt now takes
|
||||
todayKst arg, instructs ISO YYYY-MM-DD or null. Schema uses regex
|
||||
for round-trip safety.
|
||||
|
||||
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
||||
```
|
||||
|
||||
### Task 4: AiWorker integration
|
||||
|
||||
**Files:** `src/main/ai/AiWorker.ts`, `src/main/ai/LocalOllamaProvider.ts`
|
||||
|
||||
- LocalOllamaProvider.generate accepts `todayKst: string` from caller (or computes internally — but for testability, take it as arg or via injected clock)
|
||||
- AiWorker:
|
||||
1. Compute `todayKst` from `now()` (KST helper inline)
|
||||
2. Run `parseDueDate(rawText, todayKst)` — get rule result
|
||||
3. Call provider.generate(rawText, todayKst) — gets AI response with optional due_date
|
||||
4. Final dueDate: `ruleResult.iso ?? aiResponse.dueDate ?? null`
|
||||
5. Pass to `repo.updateAiResult({ ..., dueDate: finalDueDate })`
|
||||
|
||||
Tests in existing AiWorker.test.ts (mock provider):
|
||||
- Rule match takes precedence over AI
|
||||
- Rule null + AI value → AI used
|
||||
- Rule null + AI null → null
|
||||
|
||||
Commit Task 4:
|
||||
```
|
||||
feat(ai): AiWorker merges rule parser + AI due_date
|
||||
|
||||
Rule parser called first. If matched, override AI's due_date
|
||||
(rule = deterministic). Else use AI's due_date. Always passes
|
||||
todayKst to provider for prompt injection.
|
||||
|
||||
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
||||
```
|
||||
|
||||
### Task 5: Renderer (NoteCard + EditableField + IPC + store)
|
||||
|
||||
Read `src/renderer/inbox/components/NoteCard.tsx` first. Add a `📅 YYYY-MM-DD` badge inline next to the title. Style: small grey text. If `note.dueDate < today`: grey + line-through. Click badge → open inline date input (or open small EditableField).
|
||||
|
||||
IPC:
|
||||
- `inboxApi.ts` `inbox:setDueDate` handler → `repo.setDueDate(noteId, date)`
|
||||
- preload `inkling.inbox.setDueDate(noteId, date|null)`
|
||||
- store `setDueDate(noteId, date|null)` action
|
||||
|
||||
Renderer test: keep minimal. Mostly visual.
|
||||
|
||||
Commit Task 5:
|
||||
```
|
||||
feat(due-date): NoteCard badge + edit + IPC
|
||||
|
||||
Inline 📅 YYYY-MM-DD badge next to title. Click to edit. Past
|
||||
dates show with line-through (회색 + 취소선). New IPC
|
||||
inbox:setDueDate, store action, preload bridge.
|
||||
|
||||
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
||||
```
|
||||
|
||||
### Task 6: Promote F1
|
||||
|
||||
Create `docs/superpowers/specs/2026-04-26-f1-due-date.md` with mini-brainstorm decisions table.
|
||||
|
||||
Update `docs/superpowers/specs/2026-04-25-dogfood-feedback.md` F1 header from `🔬 drafting` → `🚀 promoted`.
|
||||
|
||||
Commit Task 6:
|
||||
```
|
||||
docs(spec): promote F1 due date
|
||||
|
||||
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
||||
```
|
||||
|
||||
## End-state verification
|
||||
|
||||
- typecheck 0 errors
|
||||
- tests 132 → ~170+ (rule parser ~25, schema ~4, repo ~4, migration ~3, AiWorker ~3)
|
||||
- e2e 1/1
|
||||
Reference in New Issue
Block a user