13 KiB
13 KiB
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가 식별한 계약·위생 과제(G15)를 전수 구현하고 자동화 검증을 마쳤다.G7)와 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 2
커밋, 태그, 푸시, 배포, 운영 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-testsGREEN). - 신규 동작·계약은 실패 조건을 먼저 확인한 뒤(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), 모바일 MetroinlineRequires엔트리(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), FTS5tokenize = 'trigram'전문 검색(history_fts,meeting_sessions_fts,meeting_memos_fts),SqliteChunkStoreFloat32Array바이너리embedding_blob+WeakMap캐시,PersonalGraphService단일 트랜잭션 배치 처리. - Windows
koffiSendInput일원화(NutKeyboardPort,ScreenContextService), 기본 모드 1,000Hzmousemove/wheel훅 미구독, 부팅 시 4개 팝업 선생성 제거,LocalSTTService.releasePrimaryModel(클라우드 전환·15분 유휴 시 주 Whisper 모델 언로드, UIA 브리지 유지). - 장시간 회의 녹음 PCM을 메모리에 누적하지 않고 44바이트 WAV 헤더 스풀로 디스크에 직접 스트리밍하는
DiskWavAudioSink(O(1)RAM) 배선.
- SQLite WAL 성능 PRAGMA(
- 패키징 · 스크립트 · 모바일 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검증)..NETSttController무호출 레거시 라우트(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.ts4/4 PASS).G4(W5-05..07):packages/core/src/{guards,csv,format,unified-search,admin-roles}.ts를 추출해 앱·서버 간 중복 검증/파서/포매터/검색 스니펫·랭킹/관리자 권한 계층을 단일 SSOT로 통합하고core-contract.generated.ts를 동기화했다(contract:checkGREEN).
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.tsx3/3 PASS)과 모바일(index.native.tsx12개 로케일 ESM + MetroinlineRequires,OnboardingScreen/SettingsScreen/AccountScreen12개 언어 선택기, 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)·CIsite프로덕션 빌드를 루트verify:all및.forgejo/workflows/ci.yml에 편입했다.- 웹
apps/web/src/lib/team-client.ts및team-card-grid.tsx를 통해team_members실제 인원수(member_count)를 집계·렌더링하도록 수정했다(team-client.test.ts3/3 PASS).
3-5. 모바일 대화면 반응형 · 메모 revision CAS · 전 표면 화자 분리 · 대형 파일 분리 (Waves 9–11)
GAP-UX-08(태블릿·폴더블>=600dp):packages/ui-native/src/responsive.tsx(resolveResponsiveLayout,useResponsiveLayout,useContentWidth,ContentColumn) 및FreeTierBanner90dp슬롯 예약을 추가하고 모바일 10개 주요 화면에 2열 그리드·본문 폭 상한(880dp/520dp)·인라인 액션 버튼 폭 제한을 적용했다(responsive-layout.test.tsx4/4 PASS).GAP-SYNC-08(meeting_memos.revisionCAS): 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 폴백, Pythonunittest30/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.ts4/4 PASS).packages/uiSegmentControlARIA 탭 계약(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 가맹점 계약·키, Firebasegoogle-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. 검증 경계와 남은 수동/운영 단계
- 운영 Supabase 마이그레이션 반영: 신규
20261113000001_meeting_memos_revision_cas.sql(74번)은 정적 검증 및 클라이언트 하위 호환 폴백이 검증되었으나, 운영 DB 반영(supabase db push)은 배포 시점에 수행해야 한다. - 실기기 모바일 눈 확인:
GAP-UX-08(>=600dp2열 그리드·배너 슬롯 고정) 및GAP-I18N-03(모바일 12개 로케일 전환)은 Jest·빌드 설정 검증을 마쳤으며, 실제 Fold6/태블릿open/closedMaestro 시각 확인이 남아 있다. - 대화형 Windows Electron 실행 확인:
run-desktop.bat을 통한 다중 화자 실음성 회의 녹음(DiskWavAudioSink+POST /diarize) 및 UI 눈 확인은 사용자 데스크톱 세션에서 수행한다.