15 KiB
15 KiB
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.mdWave 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, Pythonunittest, Denoserver/supabase/functions+server/cloudflare-worker,npm run build+npm run check:desktop-renderer가 모두 통과했다. - 실행하지 않은 경계 유지:
git commit/push/tag/publish, Electron GUI 백그라운드 기동, 실기기 Android(Fold6)/iOS Maestro, 운영 Supabasedb 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경로에 연결했다.Float32Arrayvector디코드 이후 캐시된StoredChunk의 중복embeddingJSON 문자열을 제거하고,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 - 36uint32 오버플로 상한 내보내기 및 가드,openSync직후 44B 헤더 write 실패 시_fd와.wav.partcleanup을 추가했다. 광고 경매/오디오 테스트/로컬 LLM 서버 폴링/종료 핸들러 타이머 누수 및 팝업hide/show/alwaysOnTop경합을 수정했다. - Python 사이드카 (
apps/desktop/sidecar/main.py):finally에서UploadFile.close()보장,<2바이트(HTTP 400)·홀수 바이트 PCM 절단 방지,_watch_disconnect취소 처리,/shutdown시_download_threadjoin을 추가했다. - 회귀 테스트:
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:checkGREEN). @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.tsx10).@d3ro/core,@d3ro/ui,@d3ro/ui-native,@d3ro/api-client:utils/pii-redactor.ts플레이스홀더 충돌 회피·정규식 인덱스 리셋·길이 정렬 단일 패스rehydrateText,csv.tsUTF-8 BOM +\r이스케이프,unified-search.ts,utils/meeting-markdown.ts,meeting-transcript.ts(formatDurationClockFromMs재사용·유한 날짜 가드) 보강 (__tests__/pii-redactor.test.ts5,__tests__/shared-utilities.test.ts10).@d3ro/uiwave-math.ts분리 +AudioVisualizerBar.tsx/GradientWave.tsx캔버스LinearGradient캐싱(__tests__/wave-visualizer.test.tsx3),@d3ro/ui-nativeresolveContentMaxWidth및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-popupprepareVersion/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(toSpeechLanguageTag12개 로케일),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/formatformatDurationClockFromMs재사용)을 도메인 오류 클래스·코드·메시지 보존 상태로 단일화했다. - 라이프사이클·동시성·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) →98suites /625tests 통과.
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(postPaypleJsonAbortSignal.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 * 1024MaxBase64Length상한을 강제하고,SttController/LlmController/AdminController→SttProxyService/LlmProxyService→ EF/HTTP/AssemblyAI 폴링까지HttpContext.RequestAborted(CancellationToken)를 전파해 클라이언트 중단 시 유료 failover를 즉시 중단하도록 수정(SttControllerSecurityTests.cs,SttFailClosedTests.cs보강). - Cloudflare Worker (
server/cloudflare-worker/src/):resolveBackendTargetUrl로//host/\hostSSRF 차단,/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>로innerHTMLXSS 제거,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중복 제거,memberCountErrorfail-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(RowSSOT) 신설,logout(sameSite: 'strict', CSRF,no-store),license/login/backend/supabase라우트,users/[id]·subscriptions/[id](requireManager()+ UUIDnotFound()),payment-history/checksum-copy/license-issuer-dialog/models/page.tsx(언마운트 가드, 타이머 정리,sttMemo리셋,NaN/음수 비용 거부) 보강. - Site (
site/):AppLoopDemo.tsxisHidden/isOutOfViewport분리 +IntersectionObserver가드,Download.tsx·Footer.tsxrel="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/ ambient203/ skip·todo3/2500 keys × 12 locales(생성:npm run test:metrics:write, 게이트 아님).
4. SKIP 및 잔여 위험
- 런타임 GUI / 실기기 경계 유지 (
[~]/RED): Electron 실앱Ctrl+K/팝업/오버레이 확인, Android Fold6open/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를 수행하지 않으며, 작업 트리 상태로 리뷰 대기한다.