Yun Chan b1435b0ba5 docs: refactor-wave Wave 2 보고서·현황 (메타)

- docs/REFACTOR_WAVE2_REPORT.md (신규): 정량 산출, 검증, 이월,
  메타 학습 M7-M9, Wave 3 계획, 누적 통계
- memory/project_status.md: Wave 2 섹션 추가

2026-07-22 02:40:08 +09:00

5.5 KiB

Raw Blame History

리팩토링 Wave 2 보고서

일시: 2026-07-22 | 스킬: /refactor-wave | 범위: Wave 1(desktop+packages) → web/admin/site/mobile/ui-native 확장

0. 배경

Wave 1에서 식별된 이월 항목 처리. 핵심 동기: theme.ts amber 별칭 제거는 공유 패키지라 web/admin/site가 amber를 사용 중 → 전체 치환 선행 필요 (P7).

1. 정량 산출물

WS	산출	커밋
WS-AMBER	web 11 + admin 10건 amber→main 치환, theme.ts(packages/ui) deprecated 별칭 4줄 제거(본체 main/dim/glow 유지), 전 모노레포 amber 잔여 0건	`efac690`
WS-NATIVE	ui-native theme.ts accent amber→main/amberDim→dim/amberGlow→glow 개명(case B, 값 보존). mobile 20 + mobile-rn 18 + ui-native 컴포넌트 9 = 47참조 치환	`660e622`
WS-POPUP	4/5 팝업(command/history/result/recording-tip) `_i18n` 주입(WindowManager getPopupI18nStrings + applyI18nToHtml), 한국어/영어 하드코딩→popup.* 17키, theme-vars 11 토큰(--d3-wave-1~9/status-error/success, 6테마), 팝업 CSS hex→var, i18n getI18n() 추가	`00a99e4`
WS-DEPS	미사용 의존성 8종 제거(@mui/icons-material, @d3ro/api-client, fluent-ffmpeg+types, pdf-parse, node-record-lpcm16+,.d.ts, electron-audio-loopback, @electron-toolkit/preload), electron-builder Linux 섹션 삭제	`4c25620`
WS-PATTERN	cloud-sync-handlers 수동 ok/fail→ipcSuccess/ipcError 헬퍼(6핸들러), catch{}→catch(error) 32건(11파일)	`5b6e7aa`

2. 검증 결과

게이트	결과
typecheck (desktop/admin/api-client)	✅ GREEN
typecheck (`@d3ro/web`)	⚠️ pre-existing 1건(teams/[id], Wave 1과 동일 — WS-AMBER amber 치환으로 새 에러 0건 확인)
typecheck (mobile/mobile-rn)	⚠️ pre-existing 환경(Expo tsconfig 미해결, jest 타입) — WS-NATIVE 변경 무관, 소스 파일은 무오류 컴파일
typecheck (ui-native)	✅ EXIT 0
lint (변경 34파일, mobile/site 제외)	✅ 0 errors, 2 warnings(audio-handlers logger unused, voice-handlers params unused — 이월)
test	✅ desktop 41/41 + api-client 19/19
UI 화면 확인	미실행 — 팝업 _i18n/색상 토큰 변경은 `npm run dev` 육안 확인 권장

3. SKIP / 이월 항목

항목	사유	후속
site/src/tokens.ts amber 리터럴	별도 토큰 계통(`color.brand.*`, d3roPalette 비의존)	site 토큰 정리 별도
caption-overlay `_i18n` 주입	별도 IPC 구조(sendToCaptionOverlay 범용)	Wave 3
Led/PhosphorText/Header `color="amber"` prop	의미론적 컴포넌트 API(팔레트 키 아님) — 값은 이미 accent.main 가리킴	별도 API 마이그레이션
theme-vars 평행 SSOT 구조 단일화	P2/P3 회귀 위험	Wave 3 (신중)
wave-bar box-shadow 9단계 보간	opacity 계단으로 단순화(시각 동등)	Wave 3 정밀화
web `teams/[id]` typecheck	pre-existing, 범위外	별도 type wave
mobile/RN lint·typecheck 환경	Expo/jest config 미설치	별도 모바일 인프라 wave
audio/voice-handlers unused (logger/params)	errors 아님, 사소	Wave 3 unused 정리

4. 메타 학습

M7. P7 입증 — 공유 패키지 별칭 제거는 전체 소비 앱 치환 "후"에만

Wave 1에서 theme.ts(packages/ui) amber 별칭 제거를 web/admin 사용으로 미뤘음. Wave 2에서 web/admin 치환 후 별칭 제거 성공 → P7이 정확히 맞음: 부분 치환 + 별칭 제거 불가, 전체 치환 선행 필수. desktop(Wave 1) + web/admin(Wave 2) + ui-native(별도 palette, WS-NATIVE) 전부 치환 후에야 각 패키지에서 amber 제거.

M8. RN 패키지는 palette 구조가 다를 수 있다 — 사전 확인(case A/B)

packages/ui-native은 main/dim/glow가 아예 없고 amber만 존재(case B). blindly 치환하면 undefined. palette 정의를 먼저 Read해 case A(본체 존재→치환) vs B(개명) 판단이 선행. WS-NATIVE가 case B로 정확 분기.

M9. typecheck가 잡지 못하는 팝업(Vanilla JS) 변경 — 별도 검증 경로

팝업 script.js/style.css는 TS가 아님 → typecheck 무관. _i18n 주입·CSS 토큰 변경은 dev 실행 또는 코드 리뷰로만 검증. 팝업 작업 WS는 typecheck GREEN이 부족; "팝업 동작은 메인 작업자가 dev로 확인" 명시 필수.

5. 다음 wave 계획 (Wave 3)

theme-vars 평행 SSOT 구조 단일화(theme.ts RAW 파생) — 신중, 회귀 주의
caption-overlay _i18n 주입
컴포넌트 color prop amber→main API 마이그레이션(ui-native Led/PhosphorText/Header + 호출처)
site/src/tokens.ts 토큰 정리(별도 계통)
unused vars 정리(audio/voice-handlers + Wave 1 잔여 12 warnings)
web teams/[id] Supabase 타입 수정
mobile/RN lint·typecheck 인프라(Expo/jest config)

별도 Phase(Wave 1에서 이월 유지): 서비스-IPC 결합 분리, 타 locale 334키 번역 파이프라인, 전체 lint pre-existing 정리.

6. 누적 통계 (Wave 1+2)

분리 커밋: Wave 1(4) + Wave 2(5) + 메타(1) = 10개
amber 치환: 91(desktop) + 21(web/admin) + 50(ui-native/mobile) = 162건, 별칭 2곳(packages/ui, ui-native) 제거
데드코드: DS 3종 + services/index.ts + 의존성 8종 + .d.ts + i18n 967키 + electron-builder Linux
사용자 노출 버그 해소: 3건(date "TODAY", 팝업 색 충돌, 팝업 한국어 하드코딩)
IPC SSOT: 9그룹/키 추가 + 하드코딩 일원화 + ipcSuccess/ipcError + catch 패턴
AppConfig: 7키 + as never 16건

5.5 KiB Raw Blame History