yunchan/d3ro-voice
1
0
Fork 0
Code Issues Pull requests Projects Releases 2 Packages Wiki Activity Actions

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

Browse source 
- docs/REFACTOR_WAVE2_REPORT.md (신규): 정량 산출, 검증, 이월,
  메타 학습 M7-M9, Wave 3 계획, 누적 통계
- memory/project_status.md: Wave 2 섹션 추가
This commit is contained in:
Yun Chan 2026-07-22 02:40:08 +09:00
parent 5b6e7aae6b
commit b1435b0ba5
2 changed files with 95 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

74
docs/REFACTOR_WAVE2_REPORT.md Normal file
View file

@ -0,0 +1,74 @@
# 리팩토링 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)
1. theme-vars 평행 SSOT 구조 단일화(theme.ts RAW 파생) — 신중, 회귀 주의
2. caption-overlay `_i18n` 주입
3. 컴포넌트 color prop `amber`→`main` API 마이그레이션(ui-native Led/PhosphorText/Header + 호출처)
4. site/src/tokens.ts 토큰 정리(별도 계통)
5. unused vars 정리(audio/voice-handlers + Wave 1 잔여 12 warnings)
6. web `teams/[id]` Supabase 타입 수정
7. 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건

21
memory/project_status.md
View file

@ -1,5 +1,26 @@
# D3RO-VOICE 프로젝트 현황
## 리팩토링 Wave 2 (2026-07-22 /refactor-wave) ✅
`/refactor-wave` Wave 2. Wave 1 이월 항목 처리 + 범위 확장(web/admin/site/mobile/ui-native). 5 WS 병렬 → 분리 커밋 5개. 보고서 `docs/REFACTOR_WAVE2_REPORT.md`.
**산출** (efac690/660e622/00a99e4/4c25620/5b6e7aa):
- WS-AMBER: web 11 + admin 10건 amber→main 치환, theme.ts(packages/ui) deprecated 별칭 제거. 전 모노레포 amber 잔여 0건.
- WS-NATIVE: ui-native theme.ts accent amber→main 개명(case B, 값 보존), mobile/mobile-rn/ui-native 47참조 치환.
- WS-POPUP: 4종 팝업 _i18n 주입(WindowManager getPopupI18nStrings + applyI18nToHtml), 한국어/영어→popup.* 17키, theme-vars 11 토큰(--d3-wave-1~9/status), 팝업 CSS 토큰화, i18n getI18n() 추가.
- WS-DEPS: 미사용 의존성 8종 + node-record-lpcm16.d.ts + electron-builder Linux 섹션 제거.
- WS-PATTERN: ipcSuccess/ipcError 헬퍼 통일(6핸들러) + catch(error) 32건(11파일).
**검증**: desktop/admin/api-client/ui-native typecheck 0, 변경 영역 lint 0 errors, test 41+19 GREEN. (web pre-existing 1건, mobile/RN 환경 에러 — 별도.)
**메타 학습**: (1) P7 입증 — 공유 패키지 별칭 제거는 전체 소비 앱 치환 "후"에만 가능(Wave 1 desktop + Wave 2 web/admin 치환 후 theme.ts 별칭 제거 성공). (2) RN 패키지는 palette 구조가 다를 수 있음 — case A(본체 존재→치환) vs B(개명) 사전 판단(WS-NATIVE). (3) 팝업(Vanilla JS)은 typecheck 무관 — dev 육안 확인 필수.
**누적(Wave 1+2)**: 분리 커밋 10개, amber 치환 162건 + 별칭 2곳 제거, 데드코드(DS 3종 + services/index + 의존성 8 + i18n 967키), 사용자 노출 버그 3건 해소(date "TODAY"/팝업 색 충돌/팝업 한국어), IPC SSOT 9그룹+헬퍼+catch, AppConfig 7키 + as never 16건.
**다음 Wave 3**: theme-vars 구조 단일화, caption-overlay i18n, color prop amber API 마이그레이션, site 토큰, unused 정리, web teams 타입, mobile/RN 인프라. 별도 Phase: 서비스-IPC 분리, 타 locale 번역, lint pre-existing.
---
## 리팩토링 Wave 1 (2026-07-22 /refactor-wave) ✅
`/refactor-wave` 스킬 첫 실전 적용. 범위: desktop + 공유 packages. 3 에이전트 공격적 감사(106건) → 4 WS 병렬 → 분리 커밋 4개. 정책 `docs/REFACTOR_POLICY.md` + 보고서 `docs/REFACTOR_WAVE1_REPORT.md` 신규.