d3ro-voice/docs/REFACTOR_WAVE6_REPORT.md

15 KiB
Raw Permalink Blame History

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 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, docs/map/03–11, MOBILE_APP_COMPLETION_SSOT.md, REFACTOR_POLICY.md, .claude/skills/refactor-wave/SKILL.md에 Wave 6 변경과 최신 테스트 수치를 반영했다.
  • 미커밋 작업 트리: 사용자 명시 전까지 git commit/push/release를 수행하지 않으며, 작업 트리 상태로 리뷰 대기한다.