# v0.2.3 #6 리마인드 1 spike — Design Spec

> 작성: 2026-05-02 · v0.2.3 dogfood feedback roadmap §3 #6 (7번째 / 마지막 cut)

## 1. Goal

Inbox 상단에 "오늘 회상해볼 노트" 1건 추천 배너 (`RecallBanner`) 도입. 7일 이상 안 본 노트 중 가장 오래된 1건을 제시하여 사용자가 자기 기록을 재방문할 기회 제공. 4종 telemetry (`recall_shown` / `recall_opened` / `recall_dismissed` / `recall_snoozed`) 로 효과 측정 인프라 마련.

## 2. Decisions (mini-brainstorm 합의)

| # | 질문 | 선택 | 이유 |
|---|---|---|---|
| Q1 | 다음에 snooze 영속화 | **A** in-memory | `expiredSnoozeUntilMs` 패턴 일관, schema migration v4 회피, dogfood telemetry 보고 v0.2.4 영속화 결정 |
| Q2 | `ageDays` 의미 | **B** `last_recalled_at ?? created_at` 기준 | algo 의 "7일 안 본 노트" trigger 와 동일 axis, 재추천 분포 측정 가치 |

자명 결정 (질문 없이 패턴 따름):
- Banner 위치: `ExpiryBanner` 다음 (stack 끝, 시간 민감도 가장 낮음)
- 0건 시: `null` return (`ExpiryBanner` 패턴)
- Snooze duration: KST 다음 자정 (`snoozeExpired` 패턴)
- "열어보기" 동작: `scrollIntoView` (NoteCard 항상 expanded — expand 동작 X)

## 3. Architecture & data flow

```
Inbox 마운트 시:
  loadInitial() → recallCandidate fetch (별도 fetch, 단일 노트 또는 null)

RecallBanner render (recallCandidate !== null && !snoozed):
  ┌─ "오늘 회상해볼 노트" + 노트 제목 + (N일 전)
  ├─ [열어보기] → scrollIntoView(noteCardRef) + markRecallOpened(id)
  │              → telemetry: recall_opened
  ├─ [다음에] → store.snoozeRecall() (KST 다음 자정까지 in-memory)
  │            → telemetry: recall_snoozed
  └─ [더 이상] → dismissRecall(id) (DB: recall_dismissed_at = now)
                 → telemetry: recall_dismissed

Banner 첫 렌더 시 자동 emit: recall_shown { noteId, ageDays }

다음 fetch 트리거:
  - markRecallOpened / dismissRecall 후 store 가 자동 다음 후보 fetch
  - refreshMeta (focus / inbox:noteUpdated) 도 fetch
```

### 3.1 Invariants

1. **단일 후보 fetch** — `LIMIT 1` + `ORDER BY created_at ASC` (가장 오래된 1건)
2. **KST 보정** — SQL 의 `date('now')` 자리 모두 `date('now','+9 hours')`
3. **마감 임박 노트 제외** — `due_date < today` 인 노트는 ExpiryBanner 영역 (#5) 이라 회상 후보에서 빠짐
4. **Snooze in-memory** — `recallSnoozeUntilMs` store 변수, KST 다음 자정 (ExpiryBanner 패턴)
5. **emit 순서** — `recall_shown` (banner 첫 렌더) → `recall_opened/dismissed/snoozed` (사용자 액션)
6. **Snooze 시 `recall_shown` 1회만** — 같은 후보가 다시 보여도 `recall_shown` 재emit 안 함 (notes 1건당 session 1 shown — `recallShownIds: Set<string>` in-memory)

## 4. Components

### 4.1 `NoteRepository`

#### `findRecallCandidate(): Note | null`

```sql
SELECT * FROM notes
WHERE (last_recalled_at IS NULL OR last_recalled_at < date('now','+9 hours','-7 day'))
  AND (recall_dismissed_at IS NULL OR recall_dismissed_at < date('now','+9 hours','-30 day'))
  AND ai_status = 'done'
  AND deleted_at IS NULL
  AND (due_date IS NULL OR due_date >= date('now','+9 hours'))
ORDER BY created_at ASC
LIMIT 1
```

기존 `hydrate(row)` 사용 (이미 `last_recalled_at` / `recall_dismissed_at` 매핑 있음).

#### `markRecallOpened(id: string, now: string): void`

```sql
UPDATE notes SET last_recalled_at = ?, updated_at = ? WHERE id = ?
```

#### `dismissRecall(id: string, now: string): void`

```sql
UPDATE notes SET recall_dismissed_at = ?, updated_at = ? WHERE id = ?
```

### 4.2 `CaptureService` (5 신규 메서드)

```typescript
async listRecallCandidate(): Promise<Note | null> {
  return this.repo.findRecallCandidate();
}

async markRecallOpened(noteId: string): Promise<{ note: Note }> {
  const note = this.repo.findById(noteId);
  if (!note) throw new Error(`note not found: ${noteId}`);
  this.repo.markRecallOpened(noteId, new Date().toISOString());
  if (this.deps.telemetry) {
    await this.deps.telemetry.emit({
      kind: 'recall_opened',
      payload: { noteId }
    }).catch(() => {});
  }
  return { note: this.repo.findById(noteId)! };
}

async dismissRecall(noteId: string): Promise<{ note: Note }> {
  this.repo.dismissRecall(noteId, new Date().toISOString());
  if (this.deps.telemetry) {
    await this.deps.telemetry.emit({
      kind: 'recall_dismissed',
      payload: { noteId }
    }).catch(() => {});
  }
  return { note: this.repo.findById(noteId)! };
}

async emitRecallShown(noteId: string): Promise<void> {
  const note = this.repo.findById(noteId);
  if (!note) return;
  const ageDays = this.computeAgeDays(note);
  if (this.deps.telemetry) {
    await this.deps.telemetry.emit({
      kind: 'recall_shown',
      payload: { noteId, ageDays }
    }).catch(() => {});
  }
}

async emitRecallSnoozed(noteId: string): Promise<void> {
  if (this.deps.telemetry) {
    await this.deps.telemetry.emit({
      kind: 'recall_snoozed',
      payload: { noteId }
    }).catch(() => {});
  }
}

private computeAgeDays(note: Note): number {
  const ref = note.lastRecalledAt ?? note.createdAt;
  const refMs = new Date(ref).getTime();
  const nowMs = Date.now();
  return Math.max(0, Math.floor((nowMs - refMs) / 86_400_000));
}
```

### 4.3 IPC (5 신규 channels)

```typescript
ipcMain.handle('inbox:listRecallCandidate', () => deps.capture.listRecallCandidate());
ipcMain.handle('inbox:markRecallOpened', (_e, id: string) => deps.capture.markRecallOpened(id));
ipcMain.handle('inbox:dismissRecall', (_e, id: string) => deps.capture.dismissRecall(id));
ipcMain.handle('inbox:emitRecallShown', (_e, id: string) => deps.capture.emitRecallShown(id));
ipcMain.handle('inbox:emitRecallSnoozed', (_e, id: string) => deps.capture.emitRecallSnoozed(id));
```

### 4.4 Preload + InboxApi shared type

```typescript
// preload/index.ts
listRecallCandidate: () => ipcRenderer.invoke('inbox:listRecallCandidate'),
markRecallOpened: (id: string) => ipcRenderer.invoke('inbox:markRecallOpened', id),
dismissRecall: (id: string) => ipcRenderer.invoke('inbox:dismissRecall', id),
emitRecallShown: (id: string) => ipcRenderer.invoke('inbox:emitRecallShown', id),
emitRecallSnoozed: (id: string) => ipcRenderer.invoke('inbox:emitRecallSnoozed', id),
```

```typescript
// shared/types.ts InboxApi
listRecallCandidate(): Promise<Note | null>;
markRecallOpened(id: string): Promise<{ note: Note }>;
dismissRecall(id: string): Promise<{ note: Note }>;
emitRecallShown(id: string): Promise<void>;
emitRecallSnoozed(id: string): Promise<void>;
```

### 4.5 `telemetryEvents.ts` zod

```typescript
const RecallShownPayload = z.object({
  noteId: z.string().min(1),
  ageDays: z.number().int().nonnegative()
}).strict();

// recall_opened / recall_dismissed / recall_snoozed → 기존 NoteIdPayload 재사용
```

union 15 → **19** (recall_shown + recall_opened + recall_dismissed + recall_snoozed).

### 4.6 `telemetryStats.ts`

- DailyRow +4 cols (`recall_shown`, `recall_opened`, `recall_dismissed`, `recall_snoozed`)
- accumulators: `recallShownCount`, `recallOpenedCount`, `recallDismissedCount`, `recallSnoozedCount`, `recallAgeDaysSum`
- summary lines:
  ```
  - 회상 추천: shown {N} / opened {O} / dismissed {D} / snoozed {S} (열림율 {O/N}%)
  - 회상 평균 ageDays: {avg}
  ```
  N=0 시 `(데이터 없음)`

### 4.7 `TelemetryService.EmitInput` union 15 → 19

### 4.8 Renderer store (`src/renderer/inbox/store.ts`)

```typescript
interface InboxState {
  // ... existing ...
  recallCandidate: Note | null;
  recallSnoozeUntilMs: number | null;
  recallShownIds: Set<string>;  // session-local, "1 shown per note per session"
  loadRecallCandidate: () => Promise<void>;
  openRecall: (id: string) => Promise<void>;
  dismissRecallNote: (id: string) => Promise<void>;  // store action 명, IPC 와 구별
  snoozeRecall: () => Promise<void>;
}
```

`refreshMeta` + `loadInitial` 가 `loadRecallCandidate` 도 호출.

`openRecall(id)`:
- `inboxApi.markRecallOpened(id)` → DB 갱신
- `loadRecallCandidate()` → 다음 후보 fetch
- (스크롤은 RecallBanner 컴포넌트가 자체 처리)

`dismissRecallNote(id)`:
- `inboxApi.dismissRecall(id)` → DB 갱신
- `loadRecallCandidate()` → 다음 후보 fetch

`snoozeRecall()`:
- `recallSnoozeUntilMs = nextKstMidnight()` (`snoozeExpired` 패턴)
- 현재 candidate noteId 기준 `inboxApi.emitRecallSnoozed(id)`

### 4.9 RecallBanner 컴포넌트

**파일**: `src/renderer/inbox/components/RecallBanner.tsx` (신규)

- 위치: `<ExpiryBanner />` 다음 (App.tsx)
- 첫 렌더 시 `useEffect` 가 `recallShownIds` 체크 후 미emit 시 `inboxApi.emitRecallShown(id)` 호출 + Set 에 추가
- Banner UI: 노트 제목 + ageDays + 3개 버튼 (열어보기 / 다음에 / 더 이상)
- `null` return: candidate=null OR snoozed (Date.now < snoozeUntilMs)
- snoozeUntilMs 만료 시 setTimeout re-render 트리거 (ExpiryBanner 패턴)

### 4.10 NoteCard ref 시스템 (scroll target)

App.tsx 가 `noteRefs: Map<noteId, HTMLDivElement | null>` ref store 보유 + RecallBanner 가 store 의 ref 를 lookup 후 `scrollIntoView({ behavior: 'smooth', block: 'center' })` 호출.

구체 구현:
- `App.tsx` 가 `useRef<Map<string, HTMLDivElement | null>>(new Map())` 보유
- 각 `<NoteCard>` 에 `ref={(el) => { noteRefs.current.set(note.id, el); }}` 전달 (NoteCard 가 ref forwardRef 지원 필요)
- RecallBanner 가 `noteRefs` prop 으로 받아 사용

**대안 (단순)**: `document.getElementById(\`note-${id}\`)` — App.tsx 의 NoteCard 가 `id={\`note-${note.id}\`}` 만 추가하면 됨. **이 spike 에선 이 단순 방식 채택** (ref 시스템 복잡도 회피).

## 5. Privacy invariant

- `recall_shown.payload`: `{ noteId, ageDays }` — noteId 기존 패턴, ageDays 정수
- `recall_opened/dismissed/snoozed.payload`: `{ noteId }` — `NoteIdPayload` 재사용
- `.strict()` zod 가드 + extra field 거부 테스트

## 6. Tests (≥17개)

### NoteRepository.test.ts (5)
1. 빈 db → null
2. last_recalled_at 5일 전 노트 제외 (7일 이내)
3. last_recalled_at 8일 전 노트 후보 (7일 초과)
4. recall_dismissed_at 25일 전 제외, 35일 전 후보
5. deleted_at / ai_status='pending' / due_date < today 모두 제외

### CaptureService.test.ts (4)
6. listRecallCandidate → repo.findRecallCandidate
7. markRecallOpened → repo + recall_opened emit + last_recalled_at 갱신 검증
8. dismissRecall → repo + recall_dismissed emit + recall_dismissed_at 갱신 검증
9. emitRecallShown → ageDays 정확 (last_recalled NULL 시 createdAt 기준)

### telemetryEvents.test.ts (3)
10. recall_shown valid parse (noteId + ageDays)
11. recall_shown extra field 거부 (privacy)
12. recall_opened/dismissed/snoozed valid parse (noteId only)

### telemetryStats.test.ts (2)
13. shown/opened/dismissed/snoozed 누적 + 열림율 계산
14. 평균 ageDays 계산

### store.recall.test.ts (신규, 3)
15. snoozeRecall → snoozeUntilMs KST 다음 자정 + emitRecallSnoozed 호출
16. openRecall → API 호출 + recall_shown 한 번만 emit (recallShownIds set)
17. dismissRecallNote → 후보 다시 fetch

총 신규 단위 **17개**. 기존 단위 386 + 17 = **403** 예상.

## 7. Out of scope

(roadmap §3 #6 + 본 cut 결정)

- 잠금해제 hook (F4-A, strategy.md)
- 무작위 토스트 (F4-D)
- ambient if-then (F4-B)
- 임베딩 유사도 추천 (#3 vocab 후속)
- spaced repetition (Leitner / SM-2)
- 다중 후보 추천 (현재 `LIMIT 1` only)
- snooze 영속화 (Q1=A in-memory)
- 사용자 정의 회상 주기 (7일 hardcoded)
- "회상 history" 보기 (last_recalled_at 만 저장, 이전 history X)
- RecallBanner 컴포넌트 단위 테스트 (Inkling 패턴: store 단위만 테스트)

## 8. Gates (roadmap §3.1)

- typecheck 0
- 단위 386 → 403 (+17), 모두 통과
- e2e 1/1
- 새 SQL: 복합 조건 — `idx_notes_ai_status` + `idx_notes_created_at` 활용. 별도 인덱스 불필요.

## 9. `strategy.md` 갱신 (별도 task)

roadmap §3 #6 In 절: §2.3 / §4.3 / §8 갱신:
- Capitalize 본격 진입 (회상 surface 도입)
- "오늘 회상" surface 정의
- F4-A/B/D deferred 항목의 측정 인프라 마련 명시 (recall_* telemetry 가 그 기반)

## 10. Roadmap relation

- v0.2.3 dogfood feedback #6 (7번째 / 마지막 cut)
- 머지 후 v0.2.3 cut 7/7 완료 → v0.2.3 binary 빌드 + 핸드오프
- v0.2.4 후속: dogfood telemetry 분석 (열림율, 평균 ageDays), F4-A/B/D 본격 진행, snooze 영속화 결정
