REFACTOR WAVE 5 — 감사(AUDIT) 결과와 실행 계획
작성: 2026-11-05 · 상태: 감사 완료 / 실행 전 (소스 무변경)
정책 정본: docs/REFACTOR_POLICY.md(DP1DP11, W3-, W4-) 계승. 본 문서는 Wave 5의 입력이며,
실행 후 docs/REFACTOR_WAVE5_REPORT.md로 결과를 남긴다.
하네스: .claude/skills/refactor-wave/SKILL.md (R1R8, P1~P12)
0. 기준선 (감사 시점에 실제로 돌린 게이트)
| 게이트 |
결과 |
비고 |
npm run typecheck (전 워크스페이스) |
GREEN |
desktop/web/admin/packages 전부 |
npm run lint |
GREEN (--max-warnings=0) |
desktop/web/admin/packages |
npm run test:hygiene |
GREEN (400 test files) |
.only/무근거 skip/항상참 단정/waitForTimeout 없음 |
npm run contract:check · version:check · check:design |
GREEN |
드리프트 0 |
any · console.log · TODO/FIXME |
0건 |
표면 위생은 이미 포화 |
해석: 표면 규칙(any/console/토큰/i18n 리터럴)은 Wave 1~4에서 소진됐다. Wave 5의 수확은
계약 드리프트 · 테스트만 통과하는 코드 · 3회 이상 중복 · 게이트 공백에 있다.
측정 재현(로컬 스크립트, scratch/는 gitignore):
node scratch/dead-exports.mjs # 928 export 중 dead 43 / test-only 12
node scratch/dead-modules.mjs # app 레이어 미import 모듈 8 (엔트리 5 제외 → 2~3 실 후보)
node scratch/dupe-audit.mjs # 앱 간 동명 함수 80쌍, 최장 함수(컴포넌트) 목록
node scratch/i18n-audit.mjs # 2753 키 × 12 로케일, 고아 후보 798
1. 발견 (판정: DELETE / REWIRE / REFACTOR / KEEP)
P0 — 사용자 약속·보안 (문서가 주장하는데 코드에 호출자가 없음)
| ID |
확신도 |
판정 |
근거 |
왜 지금 |
| W5-01 |
HIGH |
REWIRE(불가 시 DELETE+주장 철회) |
packages/core/src/utils/pii-redactor.ts:1-3("클라우드 전송 전 민감 데이터 자동 마스킹"), packages/core/src/utils/secure-memory.ts, 재export packages/core/src/index.ts:18. 프로덕션 호출 0 — 유일 참조는 apps/desktop/tests/red/pii-redactor.usecase.test.ts (grep -rn redactPII apps server → 0) |
테스트는 "ZDR/마스킹 동작"을 초록으로 증명하는데 실제 전송 경로엔 배선이 없다. 컴플라이언스 주장과 코드가 불일치 |
| W5-02 |
HIGH |
DELETE |
packages/core/src/ipc-channels.ts:60-73(TTS 채널 9개), packages/core/src/types.ts:247-292(TTS 타입 7개). preload에 TTS 네임스페이스 없음, apps/desktop/src/main/ipc/에 tts 핸들러 없음. 실제 재생은 TTSPlaybackService가 자체 표면으로 처리 |
죽은 IPC 계약이 SSOT에 남아 있으면 "이 채널로 붙이면 된다"는 오해를 만든다 |
P1 — 계약 드리프트 (타입은 SSOT에 있는데 소비자가 안 씀)
| ID |
확신도 |
판정 |
근거 |
| W5-03 |
HIGH |
채널 살아있음 → REWIRE, 채널 죽음 → DELETE |
packages/core/src/types.ts 데드 27: TTSSpeakParams(270), TTSSpeakResult(276), SetTTSVoiceParams(280), DownloadVoiceParams, TTSStatusChangedEvent(288), SpeakingStateChangedEvent, PullModelParams(356), LLMPullProgressEvent(370), HistoryExportParams(744), ShowRecordingTipParams(825), ShowResultPopupParams(831), TipMeasuredParams(836), TipStateChangedEvent, TipPrepareEvent, TipShowEvent, ActiveAppInfo, ShowNotificationParams, OpenExternalParams, InsertTextParams, InsertTextResult, StatsQueryParams, DailyStats, WeeklyStats, RAGChunk, MeetingGenerateDocResult, DiarizationResult, CreateSupportTicketParams |
실행 규칙(P1 재검증): 각 타입마다 채널/핸들러가 살아있는지 먼저 grep한다.
- 살아있음 → preload/handler가 코어 타입을 import하도록 REWIRE(SSOT 복구). 예:
text:insert는 서비스 내부 호출로 남아 InsertTextParams가 사장 → DELETE.
- 죽음 → 타입 삭제.
Statistics/RAG/support 계열은 실제 IPC 표면 확인 후 결정.
P2 — 데드 모듈·토큰
| ID |
확신도 |
판정 |
근거 |
| W5-04 |
HIGH |
DELETE |
apps/desktop/src/renderer/components/ProBadge.tsx (65줄, 자기 참조만) · apps/admin/src/lib/supabase-server.ts (web 사본과 동일 래퍼, import 0) |
| W5-09 |
MED |
DS 공개 API 여부 확인 후 DELETE |
packages/ui/src/theme.ts: d3roSpace, d3roWeight, d3roMotion, darkTheme, lightTheme, getModePalette / packages/ui-native/src/theme.ts: d3roNativeSpace, d3roNativeWeight, d3roNativeMotion, d3roNativeOverlayShadow, D3roNativePaletteKey — 참조 0 |
| W5-10 |
MED |
REFACTOR |
hex 폴백 10건: packages/ui/src/components/ds/AudioVisualizerBar.tsx:26-33, GradientWave.tsx:30-38 — #60a5fa/#3b82f6/#818cf8/#a78bfa가 테마 값과 이중 정의(DP1 정신 위반) |
KEEP(삭제 금지, 사유 명시): apps/desktop/src/preload/popup.ts(electron-vite entry) · apps/*/src/proxy.ts(Next 미들웨어) · apps/admin/src/instrumentation.ts · *.d.ts · packages/core/src/constants.ts:WAVE_BAR(외부 계약 아님, 화면 고유 수치 P4).
P3 — 3회 이상 중복 (DP7 위반, 실측)
| ID |
확신도 |
판정 |
중복 |
| W5-05 |
HIGH |
REFACTOR → packages/core/src/{guards,csv,format}.ts |
isRecord 27정의 · requireUuid 14 · requireUserId 8 · formatDuration 9 · escapeLikePattern 3(apps/desktop/src/main/db/like-pattern.ts:12, apps/web/src/lib/dictionary-client.ts:109, apps/mobile-rn/src/features/dictionary/dictionary-service.ts:154 — 셋 다 동일 정규식) · csvCell 3 · parseCsv/parseCsvRows/serializeDictionary/parseDictionaryFile 3 |
| W5-06 |
MED |
REFACTOR → packages/core/src/unified-search.ts |
통합검색 랭킹·발췌 이중 구현: apps/desktop/src/main/services/UnifiedSearchService.ts(264줄) vs apps/mobile-rn/src/features/search/unified-search-service.ts(459줄) — includesQuery/recordResult/meetingResult/발췌 생성 동일 규칙, 데이터 접근만 다름 |
| W5-07 |
MED |
REFACTOR(역할 순서만 core로) |
권한 계층 2벌: apps/admin/src/lib/admin-guard.ts(71줄) vs server/supabase/functions/_shared/admin-auth.ts(74줄) — manager<admin<super_admin |
주의(W5-05): 오류 타입이 앱마다 다르므로 throw를 공용화하지 않는다. 판정 함수만 core로 올리고
각 앱은 if (!isUuid(x)) throw new XError(...) 형태로 유지한다(가드의 실패 표면은 앱 소유).
P4 — i18n 위생
| ID |
확신도 |
판정 |
근거 |
| W5-08 |
MED |
REFACTOR |
① scripts/ci/sync-i18n-locales.mjs가 번역 값 40여 개를 스크립트 안에 하드코딩(ko/en) 후 JSON에 주입 — W3 "손으로 옮겨 적은 사본 금지"의 변형 위반. ② 로케일 간 값이 ko와 동일한 키 52~65개(미번역). ③ 고아 후보 798/2753 (정적 t('…') 기준). ④ --check 게이트 부재 → 드리프트가 조용히 통과 |
P5 — 구조(대형 파일) — churn 근거가 있는 것만
| ID |
확신도 |
판정 |
근거 |
| W5-11 |
MED |
REFACTOR (순수 이동 P3) |
apps/desktop/src/renderer/components/SettingsModal.tsx:95 단일 컴포넌트 857줄 · meeting/MeetingDetailTabs.tsx:98 720 · pages/MeetingModePage.tsx:61 672 · input-insights/InputInsightsView.tsx:106 616 · input-insights/InputConsentPanel.tsx:33 584 · 서비스: packages/core/src/typo-correction.ts 2705 · SuggestionService.ts 2392(최근 churn 22회) · InputTelemetryService.ts 2205 |
P6 — 게이트 공백
| ID |
확신도 |
판정 |
근거 |
| W5-12 |
HIGH |
GATE 추가 |
site/는 npm workspace 밖(package.json workspaces에 없음) → 루트 lint/typecheck/test 대상 아님. 마케팅·법률·다운로드 표면인데 정적 게이트 0. site/src/i18n/index.ts(231줄)도 독립 구현 |
2. 패치 그룹 (파일 비충돌 · 순수 정리와 기능 수정 분리)
| 그룹 |
내용 |
파일 영역 |
선행 |
| G1 |
W5-04 데드 모듈 + W5-09 데드 토큰 + W5-10 hex 폴백 |
apps/desktop/src/renderer/components/ProBadge.tsx, apps/admin/src/lib/supabase-server.ts, packages/ui/src/{theme,theme-vars}.ts, packages/ui-native/src/theme.ts, packages/ui/src/components/ds/* |
— |
| G2 |
W5-02 TTS 계약 삭제 + W5-03 타입 27건 REWIRE/DELETE |
packages/core/src/{types,ipc-channels}.ts, apps/desktop/src/preload/index.ts, apps/desktop/src/main/ipc/* |
— |
| G3 |
W5-01 PII/ZDR 배선 (기능 변경, 별도 커밋·별도 검증) |
packages/core/src/utils/{pii-redactor,secure-memory}.ts, apps/desktop/src/main/services/{CloudSTTService,AudioCaptureService}.ts, 클라우드 프록시 경로 |
사용자 결정 필요(배선 vs 주장 철회) |
| G4 |
W5-05/06/07 중복 → core 추출 |
packages/core/src/{guards,csv,format,unified-search,admin-roles}.ts(신규), apps/{desktop,web,mobile-rn}/src/**, server/supabase/functions/_shared/admin-auth.ts |
G2 완료 후(같은 types.ts 접촉 회피) |
| G5 |
W5-08 i18n 스크립트 정리 + --check 게이트 |
scripts/ci/sync-i18n-locales.mjs, packages/i18n/src/locales/*.json, package.json |
— |
| G6 |
W5-12 site 정적 게이트 |
.forgejo/workflows/ci.yml, root package.json, site/tsconfig.json, 가능하면 site eslint config |
— |
| G7 |
W5-11 대형 파일 순수 이동 (위험, 화면별 1커밋) |
renderer 컴포넌트/페이지 단위 |
G1 완료 후(토큰 접촉 회피) |
각 그룹 검증(R7 축약): 잔여 식별자 grep → 변경 파일 lint → 해당 워크스페이스 테스트 →
모노레포 typecheck → (G3/G7은) npm run dev 수동 1회. git add -A 금지, 그룹당 1커밋.
3. 실행 전 사용자 결정이 필요한 4가지
- W5-01: PII 마스킹/ZDR을 실제 전송 경로에 배선할 것인가, 아니면 코드·테스트·주장을 삭제할 것인가? (배선은 기능 변경이므로 Wave 5 범위 밖으로 빼는 선택도 가능)
- W5-03: 살아있는 채널의 타입은 REWIRE(SSOT 복구) vs 타입 삭제(핸들러 인라인 유지) 중 어느 쪽? (권장: REWIRE)
- W5-09:
d3roSpace/Weight/Motion, darkTheme/lightTheme/getModePalette는 외부 소비자를 위한 DS 공개 API로 유지할 것인가? (권장: 참조 0이면 삭제, 재도입은 필요 시)
- W5-11: 대형 파일 분할을 이번 Wave에 포함할 것인가, 아니면 G1~G6만 하고 별도 Wave로 미룰 것인가? (권장:
SuggestionService만, churn 22회 근거로)
4. 실행 순서 (권장)
G1(데드 모듈/토큰) → G2(TTS 계약) → G4(중복 추출) → G5(i18n) → G6(site 게이트) → G7(대형 파일)
↘ G3(PII 배선) — 별도 승인·별도 검증
G3만 "순수 정리 아님"으로 표시해 분리한다(W4-4 규칙). 나머지는 공개 IPC/payload 의미를 바꾸지 않는다.
5. 보고서에 남길 것 (실행 후)
- 그룹별 diff 요약 + 삭제/이동 건수(실측 재측정:
scratch/dead-exports.mjs before/after)
- W5-03 각 타입의 live/dead 판정 표(REWIRE vs DELETE 근거)
- G7 diff 1:1 대조 결과(P2: 훅 체인·구독/해제·useEffect deps)
- false positive 기록(P1): 이번 감사에서 걸러낸 것 — 예:
AppUpdatePhase는 같은 파일 내부 참조, popup.ts는 빌드 엔트리, apps/web 컴포넌트는 @/ 별칭 import
- 남은 부채: i18n 고아 키 798(사용처 재확인 필요),
apps/web 테스트 24건, packages/ui 테스트 0 → TDD 개편(docs/tdd-red/07-revamp-plan.md)으로 이관
6. 하네스 갱신 항목
docs/REFACTOR_POLICY.md에 Wave 5 섹션(W5-1~W5-5) 추가 — 실행 착수 시.
.claude/skills/refactor-wave/SKILL.md 누적 인덱스에 Wave 5 추가.
docs/map/10-feature-catalog.md · 11-gap-backlog.md — G1/G2/G4 완료 시 해당 기능 행 갱신(AGENTS.md §4).