d3ro-voice/docs/REFACTOR_WAVE6_REPORT.md

96 lines
15 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.

# Refactor Wave 6 Report — 전 표면 코드 위생 · 최적화 · 버그 헌팅 (WS1–WS4 병렬)
> 기준일: 2026-11-14
> 기준 버전: 1.16.5 (`1160500`, 버전 변경 없음)
> 범위: `apps/{desktop,web,mobile-rn,admin,api-server}`, `packages/{core,i18n,ui,ui-native,api-client}`, `server/{supabase,cloudflare-worker}`, `site/`
> 정책: [`REFACTOR_POLICY.md`](./REFACTOR_POLICY.md) Wave 6
---
## 1. 결론
Wave 6는 4개 파일 소유 경계(`WS1`–`WS4`)를 겹치지 않게 분할하여 병렬로 **코드 위생(중복 SSOT 통합)**, **성능/메모리/리소스 누수 최적화**, **동시성·보안·비동기 경합 버그 헌팅 및 회귀 테스트 고정**을 완료했다.
- **전 표면 자동화 게이트 GREEN:** `npm run verify:all`, `npm run version:check`, `npm run contract:check`, `npm run check:migrations`, `npm run security:secrets`, `dotnet test`, Python `unittest`, Deno `server/supabase/functions` + `server/cloudflare-worker`, `npm run build` + `npm run check:desktop-renderer`가 모두 통과했다.
- **실행하지 않은 경계 유지:** `git commit`/`push`/`tag`/`publish`, Electron GUI 백그라운드 기동, 실기기 Android(`Fold6`)/iOS Maestro, 운영 Supabase `db push`는 수행하지 않았으며 `docs/map/*` 및 `docs/v3/MOBILE_APP_COMPLETION_SSOT.md`의 `[~]`·`[!]`·`RED` 판정을 유지했다.
---
## 2. 워크스트림별 변경 요약
### WS1 — Desktop Main & Sidecar (`apps/desktop/src/main/**`, `apps/desktop/sidecar/**`)
- **IPC 브로드캐스트 SSOT 통합:** 9개 IPC/부트스트랩 파일의 중복 전송 로직을 `apps/desktop/src/main/ipc/renderer-broadcast.ts` (`safeSendToRenderer`, `broadcastToAllWindows`)로 단일화했다.
- **온라인 LLM 스트림 취소/예외 방어 (`OnlineLLMService.ts`):** `_postOnlineRequest` 추출, `this._abortController`를 `chatStream`에 연결(`cancelGeneration()`/`dispose()` 시 진행 중인 스트림 중단), `401` 수신 시 토큰 초기화, 빈/누락 `data.text` 가드, fetch/JSON/abort 예외의 `D3ROError` 래핑, `resetOnlineLLMServiceForTests()` 내 `instance.dispose()` 호출을 적용했다.
- **통합 검색 정확도·FTS5 폴백 (`UnifiedSearchService.ts`, `db/index.ts`, `db/schema.ts`):** `anyMeetingWhere`로 회의/메모 조건 통합, 메모 스니펫 `createdAt desc`·회의 `startedAt desc` 정렬 일관화, `meetingTotal` 이중 집계 버그 수정, `hasAllFtsTables` + 런타임 FTS5→`LIKE` 폴백 추가, `idx_meeting_sessions_started_at` 및 `idx_meeting_memos_created_at` 인덱스를 추가했다.
- **RAG 벡터 캐시 메모리·정합성 (`services/rag/chunk-store.ts`, `retrieval.ts`, `sync/sync-adapters.ts`, `db/index.ts`):** `invalidateEmbeddedChunksCache`를 내보내 `knowledgeAdapter.applyRemote`/`deleteLocal`, DB close/import/테스트 바인드 헬퍼 및 변경 `try/finally` 경로에 연결했다. `Float32Array` `vector` 디코드 이후 캐시된 `StoredChunk`의 중복 `embedding` JSON 문자열을 제거하고, `decodeFloat32Buffer`/`resolveChunkVector`에서 손상/비유한 JSON 행을 방어했다.
- **회의 WAV 싱크·타이머/윈도우 누수 (`services/meeting/disk-wav-audio-sink.ts`, `AdMediationEngine`, `AudioCaptureService`, `LocalLLMService`, `audio-handlers`, `bootstrap.ts`, `WindowManager.ts`):** `MAX_WAV_DATA_BYTES = 0xffffffff - 36` uint32 오버플로 상한 내보내기 및 가드, `openSync` 직후 44B 헤더 write 실패 시 `_fd`와 `.wav.part` cleanup을 추가했다. 광고 경매/오디오 테스트/로컬 LLM 서버 폴링/종료 핸들러 타이머 누수 및 팝업 `hide`/`show`/`alwaysOnTop` 경합을 수정했다.
- **Python 사이드카 (`apps/desktop/sidecar/main.py`):** `finally`에서 `UploadFile.close()` 보장, `<2`바이트(HTTP 400)·홀수 바이트 PCM 절단 방지, `_watch_disconnect` 취소 처리, `/shutdown` 시 `_download_thread` join을 추가했다.
- **회귀 테스트:** `online-llm-service.test.ts` (10), `rag-chunk-store-cache.test.ts` (8), `renderer-broadcast.test.ts` (2), `bug-hunt-timer-cleanup.test.ts` (3), `popup-hide-show-race.test.ts` (2), `apps/desktop/sidecar/tests/test_transcribe_hygiene.py` (3) 추가 및 `UnifiedSearchService.test.ts` (17), `disk-wav-audio-sink.test.ts` (6) 보강.
### WS2 — Shared Packages & Desktop Renderer (`packages/*`, `apps/desktop/src/renderer/**`)
- **Deno 동기화 계약 무변경:** `packages/core/src/{plan-catalog,web-urls,guards,admin-roles}.ts` 미변경(`contract:check` GREEN).
- **`@d3ro/i18n` 비동기 레이스 차단 (`packages/i18n/src/{shared.ts,index.tsx,index.native.tsx}`):** `I18nStorage`, `noopI18nStorage`, `safeLoadStoredLocale`, `safeSaveStoredLocale`, 비유한 날짜 가드를 `shared.ts`로 통합하고, `cancelled` + `userChangedLocaleRef` + `localeRevisionRef` 가드로 지연된 `storage.load()`가 사용자 `setLocale()` 선택을 덮어쓰거나 언마운트 후 상태를 갱신하는 경합을 차단했다 (`__tests__/i18n-provider.test.tsx` 10).
- **`@d3ro/core`, `@d3ro/ui`, `@d3ro/ui-native`, `@d3ro/api-client`:** `utils/pii-redactor.ts` 플레이스홀더 충돌 회피·정규식 인덱스 리셋·길이 정렬 단일 패스 `rehydrateText`, `csv.ts` UTF-8 BOM + `\r` 이스케이프, `unified-search.ts`, `utils/meeting-markdown.ts`, `meeting-transcript.ts`(`formatDurationClockFromMs` 재사용·유한 날짜 가드) 보강 (`__tests__/pii-redactor.test.ts` 5, `__tests__/shared-utilities.test.ts` 10). `@d3ro/ui` `wave-math.ts` 분리 + `AudioVisualizerBar.tsx`/`GradientWave.tsx` 캔버스 `LinearGradient` 캐싱(`__tests__/wave-visualizer.test.tsx` 3), `@d3ro/ui-native` `resolveContentMaxWidth` 및 `WaveBars.tsx` 비유한 가드, `@d3ro/api-client/src/transcribe.ts` 음수 지연 클램핑.
- **데스크톱 렌더러 & Vanilla JS 팝업 6종:** `utils/error-message.ts` (`toErrorMessage`) 신설, `meeting-format.ts`/`meeting-documents-model.ts`/`meeting-transcript-model.ts`/`ollamaModelPullController.ts` 정리, `formatters.ts`/`UnifiedSearchPage.tsx` 비유한 날짜 가드, 주요 페이지·모달·훅(`App.tsx`, `AppLayout.tsx`, `SettingsModal.tsx`, `HomePage.tsx`, `MeetingModePage.tsx`, `MeetingDetailTabs.tsx`, `MeetingChatPanel.tsx`, `VoiceConversationPage.tsx`, `KnowledgeBasePage.tsx`, `CloudSyncSection.tsx`, `TemplateSection.tsx`, `AdBanner.tsx`, `RewardedQuotaModal.tsx`, `TitleBar.tsx`, `FileDropZone.tsx`, `OnboardingModal.tsx`, `OllamaGuideModal.tsx`, `CodexOAuthGuideModal.tsx`, `InputConsentPanel.tsx`, `useLicenseState`, `useKeyBindingMap`, `useAppUpdateStatus`)의 언마운트/시퀀스/리스너/타이머를 정리했다. 6개 팝업(`beforeunload` 리스너·타이머 해제, `textContent = ''`, `result-popup` `prepareVersion`/`isVisible`/rAF 취소, `caption-overlay` 라인별 `fadeTimer`, `recording-tip`·`suggestion-overlay` 클램핑)과 `renderer-popups-and-helpers.test.ts` (7) 추가.
### WS3 — Mobile RN (`apps/mobile-rn/src/**`, `apps/mobile-rn/__tests__/**`)
- **서비스 가드·오류·음성 태그 SSOT 통합:** `features/shared/service-guards.ts`, `features/shared/owned-cache-files.ts`, `features/import/abort-guard.ts`, `lib/locale-speech.ts`(`toSpeechLanguageTag` 12개 로케일), `features/meetings/meeting-error-message.ts`를 신설하고, 26개 이상 서비스/화면의 `requireUuid`(14회), `requireUserId`(8회), `client()`(5회), `uuid`/`toServiceError`(각 4회), `record`/`stringValue`/`nonNegativeInteger`/`throwIfCancelled`(각 3회), 소유 캐시 정리(4회), `formatDuration`(`@d3ro/core/format` `formatDurationClockFromMs` 재사용)을 도메인 오류 클래스·코드·메시지 보존 상태로 단일화했다.
- **라이프사이클·동시성·UI 결함 수정:**
- `FreeTierBanner.tsx`: 광고 슬롯 변경(`90dp`->`50dp`) 시 `measuredHeight` 고착 초기화.
- `durable-processing-queue.ts`: `FileSystem.exists` 대기 전 `AbortController` 등록 및 `try/finally` 정리로 조기 폐기 경합 차단.
- `RecordScreen.tsx`: 권한/세션 전환 중 녹음 세션 리스 누수 차단.
- `TalkScreen.tsx`: 12개 로케일 TTS 언어 태그 및 실시간 인사말 로케일 동기화.
- `HistoryDetailScreen.tsx`, `SettingsScreen.tsx`, `OnboardingScreen.tsx`, `AccountScreen.tsx`, `MeetingDetailScreen.tsx`: 언마운트 시 오디오 정지, 지연 비동기 응답 차단, 로케일 동기화 바운스 방지 및 `try/finally` 저장 잠금, 타이머/요청 시퀀스/임시 내보내기 정리.
- **회귀 테스트:** 9개 Jest 스위트 추가(`durable-queue-early-discard.test.ts`, `free-tier-banner-resize.test.tsx`, `history-detail-unmount-regression.test.tsx`, `meeting-detail-unmount-regression.test.tsx`, `onboarding-locale-regression.test.tsx`, `record-permission-session-regression.test.tsx`, `service-guards.test.ts`, `settings-locale-sync-regression.test.tsx`, `talk-locale-recorder-regression.test.tsx`) → `98` suites / `625` tests 통과.
### WS4 — Web, Admin, Site, Supabase Edge, Cloudflare Worker, .NET API
- **Supabase Edge (`server/supabase/functions`):** `_shared/json-response.ts`(`jsonResponse`/`json`/스트리밍 바이트 상한 `readJsonBody`)를 20개 Edge 핸들러에 CORS/`Cache-Control`/헤더 계약 유지 상태로 적용하고 비보호 `req.json()` 예외를 400/413 fail-closed로 전환했다. `account-delete`(`SAFE_INTERNAL_CODES`), `llm-proxy`(비정상 프로바이더 JSON 시 502 + 쿼터 환불), `_shared/payple.ts`(`postPaypleJson` `AbortSignal.timeout`), `realtime-token/openai-provider.ts`(`AbortSignal.timeout`) 보강 및 `_shared/json-response.test.ts` 외 단위 테스트 추가.
- **.NET API (`apps/api-server/**`, `apps/api-server.Tests/**`):** `SttProxyService.DecodeAudioBase64`에서 `Convert.FromBase64String` 이전 `MaxAudioBytes = 26 * 1024 * 1024` `MaxBase64Length` 상한을 강제하고, `SttController`/`LlmController`/`AdminController` → `SttProxyService`/`LlmProxyService` → EF/HTTP/AssemblyAI 폴링까지 `HttpContext.RequestAborted` (`CancellationToken`)를 전파해 클라이언트 중단 시 유료 failover를 즉시 중단하도록 수정(`SttControllerSecurityTests.cs`, `SttFailClosedTests.cs` 보강).
- **Cloudflare Worker (`server/cloudflare-worker/src/`):** `resolveBackendTargetUrl`로 `//host`/`\host` SSRF 차단, `/worker-health`에서 `backendOrigin` 제거, `Host`/hop-by-hop 헤더 제거, `redirect: 'manual'`, `AbortSignal.timeout(30_000)`, 502/504 JSON 정리, `console.log` 제거, `push-drain.ts` `!response.ok` 본문 취소 및 `index.test.ts` 테스트 4건 추가.
- **Web (`apps/web`):** `markdown-preview.tsx` (`useId()` + 시퀀스 + `replaceChildren` `<pre>`로 `innerHTML` XSS 제거, `isConnected` 확인, 로드 실패 시 `mermaidReady` 재설정), `web-push-control.tsx` (`mountedRef`/`activeUserIdRef`/`activeToggleSeqRef` + `runWebPushToggle`), `web-push.ts`/`web-push-session.ts` (`withWebPushTimeout`), `dashboard/page.tsx` (`mountedRef`+`requestSeqRef`), `team-client.ts` (`teamIds` 중복 제거, `memberCountError` fail-closed) + `apps/web/tests/{markdown-preview,web-push-control,team-client-edge}.test.ts` 추가.
- **Admin (`apps/admin`):** `lib/request-security.ts` (`isSameOriginRequest`, `ADMIN_UUID_PATTERN`, 바이트 상한 JSON 리더) 및 `components/detail-row.tsx` (`Row` SSOT) 신설, `logout`(`sameSite: 'strict'`, CSRF, `no-store`), `license`/`login`/`backend`/`supabase` 라우트, `users/[id]`·`subscriptions/[id]` (`requireManager()` + UUID `notFound()`), `payment-history`/`checksum-copy`/`license-issuer-dialog`/`models/page.tsx` (언마운트 가드, 타이머 정리, `sttMemo` 리셋, `NaN`/음수 비용 거부) 보강.
- **Site (`site/`):** `AppLoopDemo.tsx` `isHidden`/`isOutOfViewport` 분리 + `IntersectionObserver` 가드, `Download.tsx`·`Footer.tsx` `rel="noopener noreferrer"` 상향.
---
## 3. 전 표면 검증 결과 (실측)
### 통합 검증 (`npm run verify:all` 및 부속 게이트)
| 게이트 / 스위트 | 결과 | 비고 |
|---|---|---|
| `npm run test:hygiene` | 통과 (`438 test files`) | `.only`/무사유 `.skip`/`waitForTimeout` 0건 |
| `npm run check:protected-tests` | GREEN (`변경된 보호 파일 0개`) | base `HEAD` 대비 |
| `npm run test:quality` | GREEN (`457 test files`) | 기준선(약한 단정 `128`, ambient `203`) 대비 증가 0 |
| `npm run check:i18n` | GREEN (`2500 keys × 12 locales`, `unreferenced=8/35`) | 카탈로그 정합 |
| `npm run check:ds-contract` | GREEN (`13 components`) | 디자인 시스템 계약 |
| `npm run check:design` | 통과 (`design-token violations: 0`) | 하드코딩 토큰/스타일 0 |
| `npm run contract:check` | GREEN | `core-contract.generated.ts` 일치 |
| `npm run check:migrations` | GREEN (`count: 74, errors: []`) | 마이그레이션 정합 |
| `npm run version:check` | GREEN (`1.16.5 (1160500/1160500)`) | 버전 SSOT 일치 |
| `npm run security:secrets` | 통과 | 런타임 파일 하드코딩 시크릿 0 |
| `typecheck` / `typecheck:mobile` / `typecheck:site` | exit `0` | 전 표면 TS strict |
| `lint` / `lint:mobile` / `lint:site` | exit `0` (`--max-warnings=0`) | 경고 0건 |
| `@d3ro/desktop` Vitest | `210` files / `2865` tests passed | main + unit + red |
| `@d3ro/web` Vitest | `9` files / `42` tests passed | SSR/컴포넌트/팀/푸시 |
| `@d3ro/api-client` Vitest | `4` files / `31` tests passed | |
| `@d3ro/core` Vitest | `39` files / `626` tests passed | PII/CSV/포맷/검색 포함 |
| `@d3ro/i18n` Vitest | `2` files / `25` tests passed | 비동기 레이스 포함 |
| `@d3ro/ui` Vitest | `2` files / `7` tests passed | 파형 캐싱 포함 |
| `@d3ro/mobile-rn` Jest | `98` suites / `625` tests passed (`21.171 s`) | 9개 회귀 스위트 추가 |
| `.NET` xUnit (`D3ROVoice.Api.Tests.csproj`) | `전체: 32, 통과: 32, 실패: 0, 건너뜀: 0` | Base64·CancellationToken 포함 |
| Desktop Sidecar Python (`unittest`) | `Ran 33 tests in 2.131s`, `OK` | `test_transcribe_hygiene.py` 포함 |
| Supabase Edge Deno (`deno test`) | `ok \| 270 passed \| 0 failed` | `_shared/json-response` 등 포함 |
| Cloudflare Worker Deno (`deno check` + `deno test`) | `ok \| 9 passed \| 0 failed` | SSRF·타임아웃 포함 |
| `npm run build` + `check:desktop-renderer` | exit `0` (`✓ built in 4.73s`, `7 page(s)`) | 프로덕션 렌더러 에셋 무결 |
### TDD v2.0 정적 메트릭 (`docs/tdd-red/metrics/2026-11-14.md`)
- 합계: `445 files` / `3655 cases` / `9549 assertions` / 약한 단정 `128` / ambient `203` / skip·todo `3` / `2500 keys × 12 locales` (생성: `npm run test:metrics:write`, 게이트 아님).
---
## 4. SKIP 및 잔여 위험
- **런타임 GUI / 실기기 경계 유지 (`[~]`/`RED`):** Electron 실앱 `Ctrl+K`/팝업/오버레이 확인, Android Fold6 `open`/`closed` 실기기 Maestro·TalkBack·신규 설치(first-run)·비한/영 로케일 눈 확인, Play/Firebase/AdMob/Payple 외부 자격증명·운영 `supabase db push`는 이번 Wave 범위 밖으로 `[~]`/`[!]`/`RED`를 유지했다.
- **문서·맵 동기화:** [`docs/map/00-index.md`](./map/00-index.md), [`docs/map/03`](./map/03-shared-packages.md)–[`11`](./map/11-gap-backlog.md), [`MOBILE_APP_COMPLETION_SSOT.md`](./v3/MOBILE_APP_COMPLETION_SSOT.md), [`REFACTOR_POLICY.md`](./REFACTOR_POLICY.md), [`.claude/skills/refactor-wave/SKILL.md`](../.claude/skills/refactor-wave/SKILL.md)에 Wave 6 변경과 최신 테스트 수치를 반영했다.
- **미커밋 작업 트리:** 사용자 명시 전까지 `git commit`/`push`/`release`를 수행하지 않으며, 작업 트리 상태로 리뷰 대기한다.