96 lines
15 KiB
Markdown
96 lines
15 KiB
Markdown
# 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`를 수행하지 않으며, 작업 트리 상태로 리뷰 대기한다.
|