d3ro-voice/docs/REFACTOR_WAVE7_REPORT.md
Yun Chan 876e72ea2f
Some checks failed
ci / 정본·보안·린트·타입·테스트 (push) Failing after 18s
ci / 워크스페이스 빌드 검증 (push) Has been skipped
ci / 모바일 린트·타입·Jest (push) Successful in 45s
ci / Supabase Edge Functions + Cloudflare Worker (push) Successful in 22s
ci / .NET API 서버 테스트 (push) Successful in 11s
deploy-site / deploy (push) Successful in 44s
docs(wave7): record peer-swarm bug fixes, metrics, and map sync
2026-11-14 15:41:48 +09:00

110 lines
14 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# D3RO Voice — Wave 7 다중 세션 피어 스웜 코드 위생 · 최적화 · 버그 헌팅 보고서
> 일시: 2026-11-14
> 대상 브랜치: `main` (기준 커밋 `a37dd63` -> 통합 커밋 `cc3f746`, 7 commits / 98 files `+7,170 / -597`)
> 실행 토폴로지: Antigravity 네이티브 `swarm` 6개 세션 (`monitor`, `input-core`, `desktop-shell`, `mobile-app`, `cloud-surfaces`, `verifier`) + `@mention`/`#seq` 피어 리뷰 보드(`Run /swarm board (default shortcut alt+s) to open the live board.`)
> 정책 SSOT: `docs/REFACTOR_POLICY.md`, `.claude/skills/refactor-wave/SKILL.md`
---
## 1. 운영 배포 경계와 Wave 7 범위
1. **운영 `v1.17.1` 기준선 (`6c6875b`, 태그 `v1.17.1`)**: 데스크톱(Forgejo `1.17.1/latest.yml`·`.sig`, `runtime-1.17.1`, `portable-1.17.1` HTTP `200`; Human Release #339 ~91MB 바이너리 첨부만 `GAP-REL-16` 예외), Supabase 운영 DB(74개 마이그레이션 동기화)·Edge Functions 24종, 랜딩 사이트(`site/` -> Cloudflare Pages `d3ro`, `https://d3ro.chanpaca.net/release-identity.json`), Cloudflare Worker(`d3ro-voice-api` `--keep-vars`, Version ID `fe6d9532-0052-48f5-b62c-45c86f6aaaa5`), NAS Docker 스택(`api-server` `:5050/health` `200`, `admin` `:3001` / `d3ro-admin.chanpaca.net/login` `200`, `web` `:3002/app/login` / `d3ro.chanpaca.net/app/login` `200`) 배포 완료 후 `a37dd63`에 기록됨.
2. **Wave 7 반영 범위 (`2a009e4..cc3f746`)**: Wave 7 커밋은 **`v1.17.1` 배포 이후**에 `main`으로 통합·검증되었다. 따라서 Wave 7 수정사항은 현재 **`main` 통합 및 모노레포 전 게이트 검증 완료** 상태이며, `v1.17.1` 기배포 바이너리·컨테이너에는 포함되어 있지 않다(차기 릴리스 `v1.17.2` / `v1.18.0` 및 재배포 반영 대상).
3. **Cloudflare Worker 운영 환경변수 경계**: Wave 7(`c68e81e`)이 `server/cloudflare-worker/wrangler.toml`의 `BACKEND_ORIGIN` 기본값을 `https://d3ro.chanpaca.net`으로 수정했으나, `v1.17.1` 배포 당시 `--keep-vars`로 유지된 라이브 Worker `d3ro-voice-api`(`fe6d9532-0052-48f5-b62c-45c86f6aaaa5`)에는 기존 대시보드 변수(`BACKEND_ORIGIN = "http://192.168.0.39:5050"`)가 남아 있어 라이브 `/health`는 Cloudflare Error `1003` (`HTTP 403`) 상태다.
---
## 2. 피어 리뷰(`@verifier`) 바운스 및 해소 이력
1. **#10 `desktop-shell` 바운스 -> `3f9e412` 해소 (`4 files, +103/-3`)**:
- 문제: `LocalLLMService` `/api/pull` 중단 및 `LocalSTTService` 모델 다운로드 `dispose()` 중단 시 raw abort 오류가 `D3ROError`로 래핑되지 않아 계약과 불일치.
- 수정: `LocalLLMService.ts`는 `D3ROError(ErrorCode.LLM_ERROR)`로, `LocalSTTService.ts`는 `D3ROError(ErrorCode.STTModelDownloadCancelled)`로 래핑하고 관련 단위 테스트 보강.
2. **#11 `mobile-app` 바운스 -> `cc3f746` 해소 (`5 files, +376/-45`)**:
- 문제: `durable-processing-queue.ts` cleanup 경로에서 큐 항목 제거와 오디오 파일 삭제 순서·실패 재시도 보장이 미흡했고, 다중 화면에서 계정 전환 후 `busy`/`running` 상태가 섞일 여지가 남아 있었음.
- 수정: `finishCleanupItem(item)`으로 오디오 파일 먼저 삭제 후 큐 항목 제거(삭제 실패 시 60초 재시도 예약), 화면(`Commands`, `HistoryDetail`, `Home`, `Knowledge`, `Meetings`, `Record`, `Teams`)에 `scopeGenerationRef`와 `try/catch/finally` 가드 통일.
3. **#17 `cloud-surfaces` 바운스 -> `4bf0f0d` 해소 (`7 files, +363/-106`)**:
- 문제: `apps/web/src/components/chat/chat-panel.tsx` `executeChatSendTurn`과 `action-runner.tsx`, `payple-manage-button.tsx`, `generate-document-button.tsx`, `invite-member-form.tsx`에서 `createTimedAbortSignal` 타임아웃이 삼켜지거나 await 이후 언마운트(`shouldExitAfterAwait`) 판정이 일관되지 않았음.
- 수정: `edge-fetch.ts` 계약 기준으로 타임아웃·abort·언마운트 가드를 전파하고 `security-and-lifecycle.test.ts` 회귀 보강.
4. **최종 승인**: `@verifier` 재검증 후 `#21` `@coordinator [all-verified]` 수신 -> 전 커밋 `main` 체리픽(`0` 충돌) 및 커밋 메시지 위생 검증(`Co-Authored-By`/AI 문구 0건) 후 워커 종료(`#22`).
---
## 3. 워크스트림별 수정 내역
### 3.1 `input-core` (`2a009e4`, `8 files, +640/-53`) — 문장부호 직후 무공백 영타 오타 라이브 트리거 복구
실사용 중 보고된 `상황 잘 지켜보는중?dbrlgkrhdlTwlsdksgwl?`(기대 변환: `유기하고있진않지`)와 같은 **문장부호(`?`) 직후 공백 없이 이어진 영타·말줄임표 오타**가 라이브 파이프라인에서 누락되던 4가지 원인을 동시에 수정했다:
| 계층 | 파일 | 수정 내용 |
|---|---|---|
| Telemetry | `apps/desktop/src/main/services/InputTelemetryService.ts` | `TYPO_SETTLE_DELAY_MS` (`700ms`) / `_typoSettleTimer` 추가로 제안 기능 비활성·지연·접두사 임계치 미달 구간에서도 `>=650ms` settle 스냅샷 보장; `diffInsertionSpan()`으로 문장부호(`?`) 트리밍을 걸친 `_expectedInserts` 계산 정확화; 만료된 `_programmaticKeys` 정리 및 `_learnFlushTimer.unref()` |
| Typo Service | `apps/desktop/src/main/services/TypoCorrectionService.ts` | 문장부호 경계 정규식(`~…?!。`) 확장; `trailingWordOnly` 패스에서 경계로 닫힌 단일 토큰을 최대 `MAX_INPLACE_DELETE_CHARS` (32)자까지 허용하고 `_markRegionChecked()` 영구 잠금 차단 |
| Core Rules | `packages/core/src/araso-layout.ts`, `typo-correction.ts`, `personal-ngram.ts` | `isUrlOrPathRun()`으로 `domain.tld?` / `file.ext?`는 보호하되 한글+말줄임표(`[가-힣ㄱ-ㆎ][!?~]*\.{2,}$`) 변환 허용(`...props` 유지); `WORD_BOUNDARY_AFTER_RE` 정리; `PersonalNgramModel.next()` 불필요한 `Map` 복사 제거 |
| Regression Tests | `apps/desktop/tests/main/services/typo-live-punctuation.test.ts`, `TypoCorrectionService.test.ts`, `packages/core/__tests__/typo-correction.test.ts` | 문장부호 뒤 한/영 무공백 전환, URL/코드 접두사 비변환, 재입력·트림 복원 회귀 테스트 추가 |
### 3.2 `desktop-shell` (`fc5d453` 19 files + `3f9e412` 4 files) — 메인 서비스 취소 · 해제 · 레이스 하드닝
- `apps/desktop/src/main/windows/WindowManager.ts`: `hideResultPopup()`에서 `pendingResultShow` 타이머를 취소하고 `lastResultCursor = null`로 초기화(`popup-hide-show-race.test.ts`).
- `apps/desktop/src/main/services/CaptionService.ts`: `ensureAuxModel` 성공 뒤 `_captionModelId`를 기록하고 이전 `loadedAuxModelId`를 해제, `_stopPromise`로 동시 `stop()`/`dispose()` 중복 실행 차단, 호출 단위 `AbortController` + `_refineEpoch`/`_refineRunId` 리셋(`caption-lifecycle-refine.test.ts`, `caption-aux-release.test.ts`).
- `apps/desktop/src/main/services/VoiceModeService.ts`, `llm/LlmGateway.ts`, `LocalLLMService.ts`: `run.controller.signal`을 `LocalLLMService.processText`까지 전파, `/api/pull` `AbortController` 등록 및 `dispose()` 시 리더·요청 중단 후 `D3ROError(ErrorCode.LLM_ERROR)` 래핑, dispose 이후 폴링 가용성 복원 차단(`local-llm-service.test.ts`, `llm-limits-routing-redteam-r2-1.test.ts`, `VoiceModeService.test.ts`).
- `apps/desktop/src/main/services/{VoiceConversationService,AudioCaptureService,LocalSTTService}.ts` & `ipc/caption-handlers.ts`: abort 시 `_responseAbortController` 정리, stale 마이크 시작 catch 가드, SoX `'stopping'` 재개 확인 및 `start()` 실패 `_cleanup()`, `dispose()` 시 STT 모델 다운로드 fetch/sleep 중단 + `D3ROError(ErrorCode.STTModelDownloadCancelled)` 래핑, `desktopCapturer.getSources` fail-closed `callback({})`(`VoiceConversationService.test.ts`, `audio-capture-redteam-r2-7.test.ts`, `stt-sidecar-redteam-r2-6.test.ts`, `ipc-redteam-r3-1.test.ts`).
### 3.3 `mobile-app` (`bd3c1a9` 25 files + `cc3f746` 5 files) — 레코더 · 내구성 큐 · 컨텍스트 · 화면 비동기 가드
- 레코더 (`src/lib/audio-recorder.ts`, `src/lib/recorder/{nitro-backend,android-foreground-backend}.ts`): `pendingClaim` + `finally` 해제, `startGeneration`/`sessionGeneration` 세대 가드, `pollTimer` 누수 방지(`recorder-lifecycle-races.test.ts`).
- 큐·히스토리 (`src/features/recording/durable-processing-queue.ts`, `src/features/history/use-history-sync.ts`): `running`/`cleanup` 가드, `suspendedUsers` 재시도 차단, `discardedItems` 재검사, `finishCleanupItem(item)`(오디오 파일 선삭제 -> 큐 항목 제거, 삭제 실패 시 60초 재시도), request-id/scope 가드(`queue-and-history-races.test.ts`).
- 서비스·컨텍스트·화면: `chat-service.ts`, `admin-service.ts`, `device-service.ts`, `llm-stream-service.ts`, 4개 컨텍스트(`mobile-ads`, `billing`, `device`, `entitlement`), 7개 화면(`Commands`, `HistoryDetail`, `Home`, `Knowledge`, `Meetings`, `Record`, `Teams`)에 pre-abort 가드, 세대 헤더 불일치 시 `response.body` 취소, 계정 전환 상태 초기화 및 `scopeGenerationRef` + `try/catch/finally` 적용(`abort-and-stream-guards.test.ts`, `context-lifecycle-guards.test.tsx`, `screen-async-lifecycle.test.tsx`).
### 3.4 `cloud-surfaces` (`c68e81e` 46 files + `4bf0f0d` 7 files) — 엣지 게이트웨이 · .NET SSRF · Supabase · Web/Admin 보안
- **Cloudflare Worker & Site Bridge (`server/cloudflare-worker`, `server/cloudflare-site-bridge`)**: `wrangler.toml` `BACKEND_ORIGIN`을 `https://d3ro.chanpaca.net`으로 교정, `origin-policy.ts`로 비-HTTPS·사설 IP·내부 호스트·프록시 루프(`508`/`503`) 차단, `204`/`205`/`304` null-body 처리, `push-drain.ts` origin 검증; `cloudflare-site-bridge` `508` 루프 가드·경로 스머글링 `400`·`deno.json` 추가.
- **.NET API (`apps/api-server`, `apps/api-server.Tests`)**: `EndpointUrlPolicy.cs` SSRF 검증, `"UpstreamNoRedirect"` 명명 `HttpClient`(`AllowAutoRedirect = false`), query language parameter 인코딩, `EndpointSecurityAndSttProxyTests.cs` 추가.
- **Supabase Edge Functions (`server/supabase/functions`)**: `stt-proxy/handler.ts` `Content-Length` 초과 선차단(`413`), `embed-chunks/handler.ts` 업스트림 프로바이더 오류 시에만 할당량 환불, `_shared/quota.ts` `PGRST116` 외 DB 오류 fail-closed 예외 전파.
- **Web & Admin (`apps/web`, `apps/admin`)**: `safeReturnPath` / `public/sw.js` / `admin-url-safety.ts`로 `//evil`·백슬래시·제어문자 오픈 리다이렉트 차단, OAuth callback 오류 메시지 누출 제거, `apps/admin/src/proxy.ts` `isStaticAssetPath` 정밀화; `apps/web/src/lib/edge-fetch.ts` (`resolveSupabaseFunctionUrl`, `createTimedAbortSignal`, `shouldExitAfterAwait`)를 `chat-panel`, `action-runner`, `payple-*`, `generate-document-button`, `invite-member-form`, `document-editor`, `history` 페이지들에 적용하고 `auth-provider` `bindAuthSession` / `mic-recorder` `acquireGuardedMediaStream` 보강 (`apps/web/tests/security-and-lifecycle.test.ts`, `apps/admin/tests/admin-security.test.ts` + Vitest 구성).
---
## 4. 통합 `main` (`cc3f746`) 전체 검증 결과
### 4.1 Batch 1 (정적 · 계약 · 백엔드 · 사이드카, `task-587`, exit `0`)
| 게이트 / 스위트 | 결과 |
|---|---|
| `version:check` | `1.17.1` (`1170100/1170100`) PASS |
| `contract:check` / `check:migrations` | PASS / `74` files 일치 |
| `security:secrets` / `check:protected-tests` | `0` issues / `0` protected modifications (`HEAD` & `a37dd63`) |
| `test:hygiene` / `test:quality` | `448 test files` PASS / `468 test files`, `0` regression |
| `check:i18n` / `check:ds-contract` / `check:design` | `2500 keys × 12 locales` / `13 components` / `0` violations |
| `dotnet test` (`apps/api-server.Tests`) | **55 passed, 0 failed** |
| Sidecar Python `unittest` | **33 tests in 2.169s, OK** |
| Supabase Edge (`deno check` + `deno test`) | **273 passed \| 0 failed** |
| Cloudflare Worker (`deno check` + `deno test`) | **15 passed \| 0 failed** |
| Cloudflare Site Bridge (`deno check` + `deno test`) | **5 passed \| 0 failed** |
### 4.2 Batch 2 (모노레포 TS · ESLint · Vitest · Jest · 빌드 · 지표, `task-654`, exit `0`)
> **환경 복구 메모**: Windows 환경에서 `swarm kill`로 `share` 워크트리가 삭제되며 루트 `.bin`·`apps/{admin,web}/node_modules` 일부와 `apps/mobile-rn/node_modules/@babel/plugin-transform-runtime` 등이 손상되어, 게이트 실행 전 `npm install --prefer-offline` + `npm --prefix apps/mobile-rn ci --prefer-offline`으로 복구하고 `better_sqlite3.node` (`sqlite_abi=node_ok`)를 확인했다.
| 게이트 / 워크스페이스 | 결과 |
|---|---|
| `typecheck` / `typecheck:mobile` / `typecheck:site` | PASS |
| `lint` / `lint:mobile` / `lint:site` (`--max-warnings=0`) | PASS |
| `@d3ro/desktop` (Vitest) | **212 files / 2,890 tests PASS** |
| `@d3ro/web` (Vitest) | **10 files / 52 tests PASS** |
| `@d3ro/admin` (Vitest) | **1 file / 6 tests PASS** |
| `@d3ro/api-client` (Vitest) | **4 files / 31 tests PASS** |
| `@d3ro/core` (Vitest) | **39 files / 629 tests PASS** |
| `@d3ro/i18n` (Vitest) | **2 files / 25 tests PASS** |
| `@d3ro/ui` (Vitest) | **2 files / 7 tests PASS** |
| `test:mobile` (`@d3ro/mobile-rn` Jest `--runInBand`) | **103 suites / 651 tests PASS** (`24.945 s`) |
| `npm run build` + `check:desktop-renderer` | `electron-vite build` + **7 page(s)** PASS |
| `npm run test:metrics:write` (`docs/tdd-red/metrics/2026-11-14.md`) | **454 files / 3,738 cases / weak 128 / ambient 203 / skip/todo 3 / 12 locales / 2,500 keys** |
---
## 5. 유지된 비코드 / 런타임 / 외부 경계 (`[~]` · `[!]` · `RED`)
- **Desktop runtime (`[~]`)**: `InputTelemetryService` / `TypoCorrectionService` / `CaptionService` / `LocalLLMService` / `LocalSTTService` / `WindowManager` 수정은 단위·서비스 테스트 및 렌더러 번들 게이트까지 검증되었으며, 실제 Windows GUI(예: `상황 잘 지켜보는중?dbrlgkrhdlTwlsdksgwl?` 라이브 타이핑, 오버레이 표시/해제)는 `GAP-INPUT-08/09/10/11` 외부-터미널 `run-desktop.bat` 실행 대상으로 남는다.
- **Mobile runtime & Play Store (`[~]` / `[!]` / `RED`)**: Fold6/iOS 실기기 수동 TalkBack·초회 진입·FCM 수신·AdMob 운영 광고·Play Billing·Play 비공개 테스트(`EXT-*`)는 외부 게이트(`RED`)로 유지한다.
- **Cloudflare Worker live env (`[~]`)**: `wrangler.toml` `BACKEND_ORIGIN` 수정분을 실운영 `d3ro-voice-api`에 반영하려면 대시보드 변수 덮어쓰기 또는 재배포가 필요하다.