From f50cabcc62146da9b773a90cd6fb972a27ae152e Mon Sep 17 00:00:00 2001 From: altair823 Date: Sat, 2 May 2026 03:00:49 +0900 Subject: [PATCH] =?UTF-8?q?docs(spec):=20v0.2.3=20#2=20AI=20retry=20/=20?= =?UTF-8?q?=EC=88=98=EB=8F=99=20trigger=20design?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit mini-brainstorm 결정 3개: - Q1=A unreachable backoff cap 15분 (30s→60s→120s→240s→480s→900s) - Q2=A timeout 도 unreachable 동일 (무한 retry, attempts 증가 안 함) - Q3=A retry-all 만 (per-note 버튼 v0.2.4) AiWorker unreachable/timeout 무한 retry + schema/other max 3 유지 + retryAllFailed atomic + FailedBanner (Inbox stack 4번째) + tray '지금 AI 처리 (실패 N건)' 9th callback + ai_retry_manual telemetry. roadmap §3 #2 deviation 1건 (timeout) 의식적 — v0.2.4 dogfood 데이터로 영구 hang 케이스 식별 후 가다듬기. T1-T8 작업 순서 + 단위 ≥ 17개. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../specs/2026-05-01-v023-ai-retry-design.md | 352 ++++++++++++++++++ 1 file changed, 352 insertions(+) create mode 100644 docs/superpowers/specs/2026-05-01-v023-ai-retry-design.md diff --git a/docs/superpowers/specs/2026-05-01-v023-ai-retry-design.md b/docs/superpowers/specs/2026-05-01-v023-ai-retry-design.md new file mode 100644 index 0000000..72b5a09 --- /dev/null +++ b/docs/superpowers/specs/2026-05-01-v023-ai-retry-design.md @@ -0,0 +1,352 @@ +# v0.2.3 #2 AI retry / 수동 trigger 설계 + +**작성일:** 2026-05-01 +**저자:** 김태현 (dlsrks0734@gmail.com) +**문서 성격:** v0.2.3 cut 7항목 중 5번째 항목 (#2 AI retry) 의 mini-brainstorm 결정 + design. roadmap §3 #2 의 In/Out 위에서 §8 미결정 3항목 (unreachable backoff cap / reason 분류 정밀도 / per-note retry) 결정. + +**선행 문서:** +- `docs/superpowers/specs/2026-05-01-v023-feedback-roadmap-design.md` §3 #2, §8 +- 선행 cut: #7 telemetry (PR #13), #4 trash (PR #14), #5 expiry (PR #15), #1 ollama 회복 (PR #16) + +--- + +## 1. 결정 요약 + +| Q | 결정 | 근거 | +|---|------|------| +| Q1 unreachable backoff cap | **A 15분 exponential** | 30s → 60s → 120s → 240s → 480s → 900s cap. 회복 latency 짧으면서 오래 꺼지면 부하 미미. | +| Q2 timeout 분류 | **A unreachable 동일** (무한 retry) | timeout 99% 는 임시 (gemma cold start, 큰 입력). 영구 hang 케이스는 v0.2.4 dogfood 후 식별. roadmap §3 #2 In 과 deviation — 의식적. | +| Q3 per-note retry | **A retry-all 만** | UI 노이즈 회피. NoteCard 단건 버튼은 v0.2.4 dogfood 마찰 발생 시 추가. | + +--- + +## 2. AiWorker.processJob 정책 변경 + +### 2.1 분기 로직 + +`classifyReason(err)` 결과로 분기: + +```ts +const reason = classifyReason(err); +if (reason === 'unreachable' || reason === 'timeout') { + // 무한 retry 경로: attempts 증가 안 함, in-job loop 안에서 sleep + retry + const sleepMs = nextBackoffMs(this.unreachableBackoffStep); + this.unreachableBackoffStep = Math.min(this.unreachableBackoffStep + 1, 5); + this.repo.setNextRunAt(job.noteId, new Date(Date.now() + sleepMs).toISOString(), msg); + await this.sleep(sleepMs); + // for 루프의 attempt 인덱스 그대로 — 다음 try 도 같은 attempt 번호로 재시도 + attempt -= 1; // for 루프의 attempt++ 상쇄 + continue; +} else { + // schema / other: 기존 max 3 retry 정책 그대로 + this.repo.incrementJobAttempt(job.noteId, nextRunAt, msg); + if (isLast) { + this.repo.markAiFailed(job.noteId, msg); + if (this.telemetry) { + await this.telemetry.emit({ kind: 'ai_failed', payload: { ... } }).catch(() => {}); + } + this.emit(job.noteId); + return; + } + await this.sleep(this.backoffsMs[attempt + 1] ?? 0); +} +``` + +성공 시 `unreachableBackoffStep = 0` 으로 reset. + +### 2.2 backoff schedule + +```ts +private readonly UNREACHABLE_BACKOFFS_MS = [30_000, 60_000, 120_000, 240_000, 480_000, 900_000]; +private nextBackoffMs(step: number): number { + return this.UNREACHABLE_BACKOFFS_MS[Math.min(step, 5)]; +} +``` + +기존 `backoffsMs = [0, 30_000, 120_000]` 은 schema/other 전용 그대로. + +### 2.3 invariants + +- unreachable/timeout: `markAiFailed` 절대 호출 안 함. `ai_failed` telemetry emit 안 함. +- schema/other: 기존 동작 (max 3 후 markAiFailed + emit). +- 결과: `ai_failed.reason` 통계에는 schema/other 만 누적 (Q2 = A 의 자연 결과). + +--- + +## 3. NoteRepository 확장 + +```ts +// src/main/repository/NoteRepository.ts + +findFailedIds(): string[]; + // SELECT id FROM notes WHERE ai_status='failed' AND deleted_at IS NULL ORDER BY updated_at DESC + +countFailed(): number; + // SELECT COUNT(*) FROM notes WHERE ai_status='failed' AND deleted_at IS NULL + +retryAllFailed(now: string): { ids: string[] }; + // 단일 transaction 안에서: + // UPDATE notes SET ai_status='pending', ai_error=NULL, updated_at=now WHERE id IN (...) + // INSERT OR IGNORE INTO pending_jobs (note_id, attempts, next_run_at) VALUES (?, 0, now) + // (이미 pending_jobs row 가 있으면 OR IGNORE — race 가드) + +setNextRunAt(noteId: string, nextRunAt: string, lastError: string): void; + // UPDATE pending_jobs SET next_run_at=?, last_error=? WHERE note_id=? + // attempts 변경 없음 — unreachable/timeout 무한 retry 용 +``` + +--- + +## 4. CaptureService + IPC + +### 4.1 CaptureService 메서드 + +```ts +async retryAllFailed(): Promise<{ count: number }> { + const { ids } = this.repo.retryAllFailed(new Date().toISOString()); + for (const id of ids) { + await this.deps.enqueue(id); + } + if (this.deps.telemetry && ids.length > 0) { + await this.deps.telemetry.emit({ + kind: 'ai_retry_manual', + payload: { failedCount: ids.length } + }).catch(() => {}); + } + return { count: ids.length }; +} +``` + +빈 배열 시 telemetry emit 안 함 — 사용자가 "재시도" 클릭해도 N=0 이면 noise. + +### 4.2 IPC 채널 신규 2 + +| 채널 | 입력 | 출력 | +|------|------|------| +| `inbox:retryAllFailed` | (없음) | `{ count: number }` | +| `inbox:failedCount` | (없음) | `number` | + +confirm dialog 불필요 — destructive 아님 (단순 재처리 큐 등록, 데이터 손실 없음). + +--- + +## 5. Tray + Banner UI + +### 5.1 Tray 메뉴 + +기존 (#1 cut 후): +``` +- 사용 로그 내보내기... +- Ollama 재확인 (status.ok=false 시 enabled) +``` + +신규 (본 cut): +``` +- 사용 로그 내보내기... +- Ollama 재확인 (status.ok=false 시 enabled) +- 지금 AI 처리 (실패 N건) (failedCount > 0 시 enabled, label dynamic with N) +``` + +`refreshTrayFailedCount(count: number)` setter — `refreshTrayOllama` 와 동일 패턴. `_failedCount` module-level state + 메뉴 rebuild. + +`createTray` 의 9번째 callback `runRetryAllFailed`. 8 → 9 positional. v0.2.4 backlog #4 (TrayCallbacks object refactor) trigger 더 강화. + +AiWorker.onUpdate 시점에 `refreshTrayFailedCount(repo.countFailed())` 호출. + +### 5.2 FailedBanner + +`src/renderer/inbox/components/FailedBanner.tsx` (신규): + +```tsx +import React from 'react'; +import { useInbox } from '../store.js'; + +export function FailedBanner(): React.ReactElement | null { + const count = useInbox((s) => s.failedCount); + const retryAllFailed = useInbox((s) => s.retryAllFailed); + if (count === 0) return null; + return ( +
+ ❌ AI 처리 실패 {count}건 + +
+ ); +} +``` + +스타일: warn variant 색상은 PendingBanner 와 다른 차별 (#fff7e6 / #d99500 의 ExpiryBanner 와도 다름) — 본 banner 는 빨강 톤 (#fce4e4 / #a33). 사용자 주의 필요한 영구 실패 신호. + +### 5.3 Inbox 상단 stack 갱신 + +``` +1. OllamaBanner (system - down) +2. RecoveryToast (회복 toast) +3. PendingBanner (AI 처리 N건 - 일시) +4. FailedBanner (AI 실패 N건 - 영구 - 신규) +5. ExpiryBanner (만료) +6. tagFilter chip +7. notes +``` + +위치 근거: system status > 진행 (transient) > 영구 실패 (actionable) > 트리아지 (expiry, also actionable but lower urgency) > filter > content. + +--- + +## 6. zustand store + +```ts +// InboxState 확장 +failedCount: number; +retryAllFailed: () => Promise; +``` + +initial: `failedCount: 0`. + +`loadInitial` / `refreshMeta` 의 `Promise.all` 에 `inboxApi.getFailedCount()` 합류 → `set({ failedCount })`. + +`retryAllFailed` action: +```ts +async retryAllFailed() { + const r = await inboxApi.retryAllFailed(); + // 낙관적 갱신: failedCount = 0 으로 reset (worker 처리 진행 중) + // 실제 카운트는 AiWorker.onUpdate 트리거된 refreshMeta 에서 자연 동기. + // PendingBanner 가 처리 중 N 건 노출. + set({ failedCount: 0 }); + // r.count 는 telemetry/log 정보용 +} +``` + +--- + +## 7. Telemetry + +### 7.1 신규 1 event + +| event | payload | 발화 | +|-------|---------|------| +| `ai_retry_manual` | `{ failedCount: number }` (≥1) | retryAllFailed 시 ids.length>0 일 때만 | + +빈 배열 시 emit 안 함 — sentinel. + +### 7.2 zod schema + +```ts +const AiRetryManualPayload = z.object({ + failedCount: z.number().int().positive() // ≥1 enforced — 0 emit 자체가 invariant violation +}).strict(); +``` + +### 7.3 stats.md 집계 + +신규 행 (수동 recheck 사용량 다음): +- AI 수동 재시도 사용량: `count` 회 / 누적 `Σfailedcount` 건 + +`DailyRow` 에 1 카운터 + sum 누적기 추가. + +### 7.4 기존 `ai_failed` 영향 + +변경 없음. unreachable/timeout 가 markAiFailed 안 부르므로 자연히 reason 분포에서 제외. 결과: `ai_failed.reason` 분포 = schema + other 만. dogfood 통계 의미 명확화. + +--- + +## 8. 테스트 + +| 영역 | 케이스 | 검증 | +|------|--------|------| +| AiWorker | unreachable 무한 retry | attempts 증가 안 함, markAiFailed 안 호출, ai_failed emit 안 함 | +| AiWorker | timeout 무한 retry (Q2=A) | unreachable 와 동일 경로 | +| AiWorker | schema fail max 3 | attempts 증가, 마지막에 markAiFailed + ai_failed emit | +| AiWorker | other fail max 3 | schema 와 동일 | +| AiWorker | unreachable backoff step | 1차 30s, 2차 60s, ..., 6차 900s cap | +| AiWorker | success 시 unreachableBackoffStep reset | 다음 unreachable 발생 시 30s 부터 | +| Repo | findFailedIds — failed + active 만 | trashed 또는 pending/done 제외 | +| Repo | countFailed | 정확 | +| Repo | retryAllFailed atomic | ai_status reset + pending_jobs 재투입 | +| Repo | retryAllFailed empty | `{ ids: [] }` | +| Repo | retryAllFailed pending_jobs 이미 존재 | OR IGNORE — race 안전 | +| Repo | setNextRunAt | attempts 변경 없이 next_run_at + last_error 만 | +| CaptureService | retryAllFailed — telemetry emit + worker.enqueue 호출 | per-id enqueue + ai_retry_manual emit | +| CaptureService | retryAllFailed 빈 결과 emit 없음 | count=0 sentinel | +| TelemetryEvents | zod parse `ai_retry_manual` | happy + extra field reject + 0 reject (≥1 invariant) | +| TelemetryStats | AI 수동 재시도 집계 | count + sum | +| Store | retryAllFailed action — failedCount=0 reset | 낙관적 갱신 | + +총 ≥ 17 단위. + +--- + +## 9. 작업 순서 (writing-plans 시 task 분할 가이드) + +T1. Repo: findFailedIds + countFailed + retryAllFailed + setNextRunAt + 단위 5개 +T2. AiWorker: unreachable/timeout 무한 retry 로직 + 단위 6개 +T3. Telemetry: ai_retry_manual 1 event + stats + 단위 3개 +T4. CaptureService.retryAllFailed + IPC 2 채널 + preload + 단위 2개 +T5. shared/types InboxApi + store retryAllFailed + failedCount + 단위 1개 +T6. FailedBanner 컴포넌트 + App.tsx mount +T7. Tray "지금 AI 처리 (실패 N건)" 메뉴 + 9th callback + refreshTrayFailedCount + main wiring +T8. closure (gates + roadmap mark + memory backlog) + +--- + +## 10. roadmap In/Out 일치 + +### 10.1 roadmap §3 #2 In 매핑 + +| roadmap | design | +|---------|--------| +| AiWorker unreachable 무한 retry, attempts 증가 안 함 | §2 ✓ | +| schema fail / invalid response / timeout 만 attempts 증가 (max 3 유지) | §2 — **timeout 은 deviation (Q2=A)**, schema/other 만 attempts 증가 | +| markAiFailed 한 노트 수동 re-enqueue | §3 retryAllFailed | +| 트레이 + Inbox "지금 AI 처리 (실패 N건)" | §5 ✓ | +| FailedBanner | §5.2 ✓ | +| IPC `inbox:retryAllFailed`, `inbox:failedCount` | §4 ✓ | +| Telemetry `ai_retry_manual {failedCount}` | §7 ✓ | +| 단위 테스트 | §8 ≥ 17 | + +### 10.2 Out 유지 + +- per-note retry 버튼 (Q3=A) — Out +- failed reason 별 차등 정책 — Out (모두 동일 max 3, telemetry 통계만 분리) +- retry progress UI — Out (PendingBanner 가 자연 표현) +- retry rate-limit — Out + +### 10.3 roadmap deviation + +§3 #2 In 의 "timeout 만 attempts 증가" 와 본 design 의 Q2=A "timeout 무한 retry" 가 충돌. 의식적 변경 — `ai_failed.reason='timeout'` 통계가 부족할 수 있음. dogfood 데이터로 검증 후 v0.2.4 에서 hang 케이스 분리 가능. + +--- + +## 11. 위험 / 완화 + +| 위험 | 완화 | +|------|------| +| unreachable 무한 retry 큐 폭주 | sleep await sequential. 같은 job 안 in-place loop, 새 job 추가 0. cap 15분. | +| retryAllFailed 가 큰 N (예: 100+) | enqueue in-memory queue push. AiWorker 가 sequential 처리 — provider 호출 1개씩. 폭주 0. | +| timeout 분류 잘못 — 영구 hang 노트가 무한 retry | telemetry markAiFailed 시점만 emit → timeout 무한 retry 노트 stats 안 보임. v0.2.4 dogfood 시 ai_status='pending' 의 attempts 분포로 영구 hang 식별. 필요 시 timeout cap 도입. | +| unreachableBackoffStep 이 process restart 시 reset | 의도. next_run_at 가 미래면 sleep, 과거면 즉시 retry — 자연. | +| schema 후 unreachable 발생 — backoff step 이 unreachableBackoffStep 와 별개 인덱스 | unreachableBackoffStep 은 unreachable/timeout 전용. schema 의 attempts 와 독립. 단위 테스트 회귀 가드. | +| retryAllFailed 와 AiWorker 큐의 race (이미 처리 중인 노트 재투입) | retryAllFailed SQL 이 ai_status='failed' 만 → 처리 중 ('pending') 노트는 자연 제외. atomic transaction. | +| pending_jobs 재투입 시 이미 pending_jobs row 존재 (예: race) | INSERT OR IGNORE — duplicate ignored. attempts/next_run_at 그대로 유지. 안전. | + +--- + +## 12. 게이트 (PR 머지 조건) + +- `npm run typecheck` 0 errors +- `npm test` — 344 + 17 = 361+ +- `npm run test:e2e` 1/1 +- main 머지 + +머지 후: +- roadmap §3 #2 ✓ 완료 마커 +- v0.2.4 backlog 누적 + +--- + +## 13. 변경 이력 + +| 일자 | 변경 | +|------|------| +| 2026-05-01 | 초안 — Q1=A (15분 cap), Q2=A (timeout=unreachable), Q3=A (retry-all only). AiWorker unreachable/timeout 무한 retry + retryAllFailed atomic + FailedBanner + tray "지금 AI 처리" + ai_retry_manual telemetry. roadmap §3 #2 deviation 1건 (timeout) 의식적. |