d3ro-voice/docs/REFACTOR_WAVE5_REPORT.md

87 lines
13 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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 눈 확인은 사용자 데스크톱 세션에서 수행한다.