d3ro-voice/docs/REFACTOR_WAVE5_REPORT.md

13 KiB
Raw Blame History

Refactor Wave 5 Report — 전 표면 최적화 · 소스 위생 · 잔여 백로그 전수 해소 (Waves 0–12)

기준일: 2026-11-13
기준 버전: 1.16.5 (버전 변경 없음)
범위: apps/*, packages/*, server/supabase, site/, scripts/ci/*, .forgejo/workflows/*, 아키텍처 맵(docs/map/*)
선행 감사·정책: REFACTOR_POLICY.md, REFACTOR_WAVE5_AUDIT.md, tdd-red/07-revamp-plan.md

1. 결론

Wave 5 및 이어진 Waves 0–12 통합 작업은 REFACTOR_WAVE5_AUDIT.md가 식별한 계약·위생 과제(G1G7)와 docs/map/11-gap-backlog.md에 남아 있던 모든 저장소 내 코드·게이트 백로그(GAP-PERF-01 잔여, GAP-PERF-02, GAP-PERF-03, GAP-HYGIENE-01, GAP-I18N-03, GAP-UX-08, GAP-SYNC-08, GAP-MTG-02, GAP-QA-06, TDD v2.0 Phase 25)를 전수 구현하고 자동화 검증을 마쳤다.

커밋, 태그, 푸시, 배포, 운영 DB supabase db push는 수행하지 않았다. 물리 기기 시각 확인(Fold6/Tab S11 펼침·접힘, 비-한/영 로케일 실기기 렌더)과 대화형 Windows 데스크톱 GUI 눈 확인(run-desktop.bat)이 필요한 항목은 코드·자동화 검증 완료 사실을 기록하되 AGENTS.md §4 규칙에 따라 [~] 경계를 유지했다.

2. 불변 조건과 실행 원칙

  • 보호 수용 여정 6종(apps/desktop/tests/e2e/{navigation,settings,onboarding,customer-support,records}.spec.ts, apps/web/e2e/smoke.spec.ts)은 한 줄도 수정·약화하지 않았다(check:protected-tests GREEN).
  • 신규 동작·계약은 실패 조건을 먼저 확인한 뒤(TDD RED → GREEN) 행동 기반 단정으로 고정했다.
  • test:quality 래칫 기준선(약한 단정 128, ambient 시계/난수 203) 증가 0건을 유지했으며, scripts/ci/lib/test-files.mjs가 미추적 신규 테스트 파일(git ls-files --cached --others --exclude-standard)까지 스캔하도록 보강했다.
  • 에이전트 서브셸에서 Electron GUI를 백그라운드 실행하지 않았다(AGENTS.md §3).

3. Changed

3-1. 번들 다이어트 · 런타임/SQLite 최적화 · 저장소 위생 (Waves 0–5)

  • 번들 & 로케일 분리 (GAP-PERF-02): @d3ro/i18n을 동적 로케일 청크(index.tsx), 무-React 동기 로더(@d3ro/i18n/main), 모바일 Metro inlineRequires 엔트리(index.native.tsx)로 분리하고, 데스크톱 AppLayout.tsx(7페이지·6모달 React.lazy), 모바일 App.tsx(20+ 보조 화면 getComponent), 웹 MarkdownPreview(next/dynamic + 다이어그램 존재 시에만 mermaid 임포트)를 적용했다. 데스크톱 초기 부팅 JS가 **8.79 MB → 3.63 MB(main 2,085.73 KB + renderer 1,549.25 KB, -58.6%)**로 감소했다.
  • 데스크톱 SQLite · 프로세스 · 메모리 (GAP-PERF-01 잔여, GAP-PERF-03):
    • SQLite WAL 성능 PRAGMA(synchronous=NORMAL, mmap_size=64MB, cache_size=-16000), FTS5 tokenize = 'trigram' 전문 검색(history_fts, meeting_sessions_fts, meeting_memos_fts), SqliteChunkStore Float32Array 바이너리 embedding_blob + WeakMap 캐시, PersonalGraphService 단일 트랜잭션 배치 처리.
    • Windows koffi SendInput 일원화(NutKeyboardPort, ScreenContextService), 기본 모드 1,000Hz mousemove/wheel 훅 미구독, 부팅 시 4개 팝업 선생성 제거, LocalSTTService.releasePrimaryModel(클라우드 전환·15분 유휴 시 주 Whisper 모델 언로드, UIA 브리지 유지).
    • 장시간 회의 녹음 PCM을 메모리에 누적하지 않고 44바이트 WAV 헤더 스풀로 디스크에 직접 스트리밍하는 DiskWavAudioSink(O(1) RAM) 배선.
  • 패키징 · 스크립트 · 모바일 R8 · .NET 정리 (GAP-HYGIENE-01):
    • 루트 중복 resources/sox/(5.21 MB) 및 불필요 바이너리 10종 제거, 미구현 데스크톱 광고 어댑터 9종 단일화(UNAVAILABLE_AD_NETWORK_SPECS), scripts/local/ 109개 및 루트 미참조 스크립트 16개 삭제 + scripts/ci/clean-deep.mjs(npm run clean:deep) 추가.
    • apps/mobile-rn 루트 순환 의존성(d3ro-voice-monorepo)·NTFS 정션 제거, Android 릴리스 R8(enableProguardInReleaseBuilds=true) + shrinkResources + 12개 로케일 localeFilters 및 proguard-rules.pro 보강(verify-mobile-build-config.mjs 검증).
    • .NET SttController 무호출 레거시 라우트(GET /api/stt/providers, POST /api/stt/test) 제거.

3-2. 코어 SSOT 공용화 & PII/ZDR 프로덕션 배선 (Wave 6 — G3, G4)

  • G3 (W5-01): @d3ro/core의 redactPII/redactPIIMessages/rehydrateText를 데스크톱 OnlineLLMService(클라우드 LLM 전송 전 PII 마스킹 및 응답 복원)와 support-handlers.ts(진단 번들 내보내기 마스킹)에 배선하고, secureWipeAudioChunks/secureZeroBuffer를 VoiceModeService·AudioCaptureService 오디오 버퍼 정리 경로에 연결했다(pii-zdr-wiring.test.ts 4/4 PASS).
  • G4 (W5-05..07): packages/core/src/{guards,csv,format,unified-search,admin-roles}.ts를 추출해 앱·서버 간 중복 검증/파서/포매터/검색 스니펫·랭킹/관리자 권한 계층을 단일 SSOT로 통합하고 core-contract.generated.ts를 동기화했다(contract:check GREEN).

3-3. i18n 고아 키 정리 · 계약 게이트 · 전 표면 12개 로케일 노출 (Wave 7 — G5, GAP-I18N-03)

  • 코드 전체 정적/동적 참조 감사를 거쳐 미참조 죽은 키 253개를 제거해 2,500키 × 12로케일로 정리하고, scripts/ci/sync-i18n-locales.mjs의 하드코딩 번역값을 모두 제거해 --check 전용 검증기로 전환했다.
  • scripts/ci/check-i18n-contract.mjs(npm run check:i18n[:test])와 packages/i18n/__tests__/locale-contract.test.ts(15/15 PASS)를 추가했다.
  • 웹(LocaleSwitcher, I18nProvider, locale-switcher.test.tsx 3/3 PASS)과 모바일(index.native.tsx 12개 로케일 ESM + Metro inlineRequires, OnboardingScreen/SettingsScreen/AccountScreen 12개 언어 선택기, Android 12개 localeFilters, mobile-i18n-locales.test.tsx) 전 표면에 12개 언어 선택을 개방했다.

3-4. site/ 정적·CI 게이트 편입 & Web 팀원 수 집계 (Wave 8 — G6)

  • .eslintignore에서 site/ 제외를 해제하고 typecheck:site·lint:site(--max-warnings=0)·CI site 프로덕션 빌드를 루트 verify:all 및 .forgejo/workflows/ci.yml에 편입했다.
  • 웹 apps/web/src/lib/team-client.ts 및 team-card-grid.tsx를 통해 team_members 실제 인원수(member_count)를 집계·렌더링하도록 수정했다(team-client.test.ts 3/3 PASS).

3-5. 모바일 대화면 반응형 · 메모 revision CAS · 전 표면 화자 분리 · 대형 파일 분리 (Waves 9–11)

  • GAP-UX-08 (태블릿·폴더블 >=600dp): packages/ui-native/src/responsive.tsx(resolveResponsiveLayout, useResponsiveLayout, useContentWidth, ContentColumn) 및 FreeTierBanner 90dp 슬롯 예약을 추가하고 모바일 10개 주요 화면에 2열 그리드·본문 폭 상한(880dp/520dp)·인라인 액션 버튼 폭 제한을 적용했다(responsive-layout.test.tsx 4/4 PASS).
  • GAP-SYNC-08 (meeting_memos.revision CAS): 74번째 마이그레이션 server/supabase/migrations/20261113000001_meeting_memos_revision_cas.sql로 단조 증가 revision 컬럼·트리거를 추가하고 @d3ro/api-client, 모바일 meetings-service.ts(A→B→A 충돌 차단), 데스크톱 SQLite 스키마·sync-adapters.ts를 갱신했다.
  • GAP-MTG-02 (전 표면 화자 분리): 데스크톱 사이드카 POST /diarize(pyannote.audio + 무의존 음향 에너지 VAD 폴백, Python unittest 30/30 PASS)를 LocalSTTService.sidecarBaseUrl → MeetingModeService._diarizeTranscript에 배선하고, @d3ro/core/meeting-transcript 화자 추출/필터 유틸과 화자 배지·다중 화자 필터 칩을 데스크톱(TranscriptTab/EditableSegment), 웹(live-transcript-list.tsx), 모바일(MeetingDetailScreen.tsx)에 일관되게 구현했다.
  • G7 (W5-11 대형 파일 분해): SettingsModal.tsx(951 → 349줄)에서 GeneralSettingsTab·AudioSettingsTab·LlmSettingsTab·AboutSettingsTab·settings-model-helpers.ts를 추출하고, SuggestionService에서 순수 정책 헬퍼 suggestion-policy-helpers.ts를 분리했다.

3-6. TDD v2.0 Phase 2~5 완결 & 설치 산출물 스모크 (Wave 12 — GAP-QA-06)

  • @d3ro/core/ports(Clock, FakeClock, Random, createFakeClock, createSeededRandom) 추가 (ports.test.ts 4/4 PASS).
  • packages/ui SegmentControl ARIA 탭 계약(role="tablist", role="tab", aria-selected, 키보드 Enter/Space) 보강 및 ds-contract.test.tsx(4/4 PASS) + scripts/ci/check-ds-contract.mjs(check:ds-contract[:test]) 추가.
  • scripts/ci/run-affected-tests.mjs(test:affected[:test]) 및 scripts/ci/verify-desktop-installer-smoke.mjs(release:installer:smoke[:test], 음성 케이스 8종) 작성 후 package.json, release-desktop.mjs, verify-release-metadata.mjs, .forgejo/workflows/{ci,release}.yml에 배선.
  • 최신 테스트 포트폴리오 지표를 docs/tdd-red/metrics/2026-11-13.md에 기록했다(422 스위트 파일 / 3,558 케이스 / 9,224 단정).

4. KEEP / DEFER 결정

  • Stryker 뮤테이션 러너 미설치 유지: @d3ro/core/ports 결정성 포트는 도입했으나, Stryker 패키지 설치는 모노레포 lockfile 비대화 및 네이티브 모듈 트리에 영향을 주므로 설치하지 않고 선택적 외부 실험으로 남겼다.
  • 대화형 데스크톱 GUI 수용 테스트(test:acceptance:desktop): Forgejo Linux 러너에는 Windows/X 디스플레이 세션이 없으므로 CI에서는 release:installer:smoke(산출물·서명·ASAR·렌더러 번들·네이티브 ABI 무결성)를 강제하고, 실제 창 렌더링 E2E는 로컬/Windows 릴리스 전 실행으로 유지한다.
  • 외부 계정·콘솔 차단(EXT-*): Authenticode 코드 서명 인증서, Payple 가맹점 계약·키, Firebase google-services.json, AdMob 콘솔 승인, Google Play 비공개 테스트(12명×14일), macOS 러너는 저장소 밖 조건이므로 [!] 상태를 유지한다.

5. Verification

Gate Result
CI --self-test 16종 (test:hygiene:test, check:protected-tests:test, test:quality:test, check:i18n:test, check:ds-contract:test, test:affected:test, check:design:test, check:desktop-renderer:test, check:migrations:test [74], security:secrets:test, release:metadata:test [18], release:installer:smoke:test [1+8], release:mobile:*:test 4종) PASS (16/16)
정적·계약 게이트 17종 (test:hygiene [415], check:protected-tests, test:quality [434, weak 128 / ambient 203], check:i18n [2,500×12], check:ds-contract [13], check:design [0], check:migrations [74], security:secrets, version:check [1.16.5], contract:check, sync-i18n-locales --check, typecheck, typecheck:mobile, typecheck:site, lint, lint:mobile, lint:site) PASS — 0 errors, 0 warnings
워크스페이스 전체 Vitest (npm run test) PASS — 254 files / 3,525 tests, 0 failed (desktop 204/2,825 · core 38/618 · web 6/32 · api-client 4/31 · i18n 1/15 · ui 1/4)
모바일 전체 Jest (npm run test:mobile) PASS — 89 suites / 605 tests, 0 failed
.NET API 서버 (dotnet test) PASS — 28/28, 0 failed, 0 skipped
데스크톱 Python 사이드카 (python -m unittest) PASS — 30/30 OK
프로덕션 빌드 (apps/desktop + check:desktop-renderer + site) PASS — desktop main 2,085.73 kB + renderer 1,549.25 kB (7 pages verified on disk); site 10 locales + sitemap/robots/llms

6. 검증 경계와 남은 수동/운영 단계

  1. 운영 Supabase 마이그레이션 반영: 신규 20261113000001_meeting_memos_revision_cas.sql(74번)은 정적 검증 및 클라이언트 하위 호환 폴백이 검증되었으나, 운영 DB 반영(supabase db push)은 배포 시점에 수행해야 한다.
  2. 실기기 모바일 눈 확인: GAP-UX-08(>=600dp 2열 그리드·배너 슬롯 고정) 및 GAP-I18N-03(모바일 12개 로케일 전환)은 Jest·빌드 설정 검증을 마쳤으며, 실제 Fold6/태블릿 open/closed Maestro 시각 확인이 남아 있다.
  3. 대화형 Windows Electron 실행 확인: run-desktop.bat을 통한 다중 화자 실음성 회의 녹음(DiskWavAudioSink + POST /diarize) 및 UI 눈 확인은 사용자 데스크톱 세션에서 수행한다.