# 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_POLICY.md), [`REFACTOR_WAVE5_AUDIT.md`](./REFACTOR_WAVE5_AUDIT.md), [`tdd-red/07-revamp-plan.md`](./tdd-red/07-revamp-plan.md) ## 1. 결론 Wave 5 및 이어진 Waves 0–12 통합 작업은 [`REFACTOR_WAVE5_AUDIT.md`](./REFACTOR_WAVE5_AUDIT.md)가 식별한 계약·위생 과제(`G1`~`G7`)와 [`docs/map/11-gap-backlog.md`](./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 2~5)를 전수 구현하고 자동화 검증을 마쳤다. 커밋, 태그, 푸시, 배포, 운영 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`](./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 눈 확인은 사용자 데스크톱 세션에서 수행한다.