diff --git a/docs/REFACTOR_POLICY.md b/docs/REFACTOR_POLICY.md new file mode 100644 index 0000000..d092bc1 --- /dev/null +++ b/docs/REFACTOR_POLICY.md @@ -0,0 +1,105 @@ +# D3RO-VOICE 리팩토링 정책 (SSOT) + +> 마지막 갱신: 2026-07-22 — Wave 1 정책 수립 +> 적용 범위: `apps/desktop` + `packages/{core,ui,i18n}` (web/admin/site/server/mobile은 별도 wave) + +## 0. 전제: 기존 3계층 규칙 SSOT와의 관계 + +D3RO는 이미 3계층 강제 규칙 체계를 가진다. 본 정책은 이를 **재정의하지 않고 인용**한다. + +| 계층 | 위치 | 성격 | +|------|------|------| +| L1 코딩 규칙 | `CLAUDE.md` | 사람이 읽는 규칙 (헌법) | +| L2 강제 규칙 훅 | `.claude/settings.json` (UserPromptSubmit) | 매 프롬프트마다 자동 주입 | +| L3 피드백 | `memory/*.md` | 사용자 피드백 축적 | + +**본 문서(L0)** 는 리팩토링 Wave 한정 **의사결정 기록(decision log)** 역할. L1/L2와 충돌 시 L1/L2가 우선하고 본 문서를 갱신한다. (`harness-gate` 스킬이 이 충돌을 감시.) + +--- + +## 1. 8개 결정포인트 (표준) + +### DP1. 디자인 토큰 SSOT — `packages/ui/src/theme.ts` +- 색상 = `d3roPalette`, 그림자 = `d3roShadow`(CSS var), 타이포 = `d3roTypo`, 라디우스 = `d3roRadius` +- **금지**: `theme.ts`/`theme-vars.ts` 제외 모든 `.ts/.tsx`에서 hex 하드코딩 (`#3b82f6` 등). L1/L2 강제. +- 매직 넘버: 화면 1개에 고유한 수치(`WAVE_BAR_COUNT = 9` 등)는 토큰화 **금지**, file-private 명명상수로 격리. (이식 인사이트 P4) + +### DP2. IPC 채널·타입 SSOT — `packages/core/src/ipc-channels.ts` + `types.ts` + `errors.ts` +- 채널명 = `IPC_CHANNELS` 객체, 형식 `${feature}:${action}`. 설계서 02 준수. +- 에러 = `D3ROError` + `ErrorCode` enum (errors.ts). `throw new Error()` 금지. +- 새 채널/타입은 SSOT 파일에 먼저 추가 → apps가 import. + +### DP3. i18n — `packages/i18n` + t() 함수 +- UI 문자열은 반드시 `t('key')`. 12 locale(ko/en/ja/zh/zh-TW/es/fr/de/pt/ru/vi/th). L1/L2 강제. +- 서비스/유틸/팝업이 한국어·영어 **리터럴을 반환**하면 다국어 불가 → 함수는 **i18n 키**(또는 enum)를 반환, 렌더링 시점에 t()로 풀이. 메인 프로세스 문자열(팝업/트레이 메뉴)도 동일. (이식 인사이트 P5) +- 고아 locale 키(코드에서 미사용)는 정리 대상. + +### DP4. 서비스 경계 — 싱글톤 + EventEmitter +- 모든 서비스: `getInstance()` 싱글톤 + `EventEmitter`. 설계서 01 인터페이스 준수. +- `apps/desktop/src/main/services/`에 **32개 서비스** 존재 (CLAUDE.md 명시분보다 다수 — 감사에서 실제 목록 정합). + +### DP5. 상태 관리 — RecognitionState(9) + AudioState(4) 이중 상태머신 +- VoiceModeService 오케스트레이터. 설계서 01 준수. (이번 wave는 상태머신 재설계 X, 정합 점검만) + +### DP6. packages ↔ apps 의존 방향 — 단방향 (apps → packages) +- packages는 apps에 의존 금지. (이미 구조적으로 보장.) +- **주의**: `packages/ui`, `packages/i18n`은 web/admin/site/mobile도 공유 → 변경 시 **영향 받는 모든 앱 typecheck** 필수 (R3 모노레포). 이번 wave는 desktop+packages라도, ui/i18n/core 변경은 모노레포 전체 typecheck로 검증. + +### DP7. DRY 임계치 — **3회 (제안)** +- 동일 로직/상수/매직스트링이 **3곳 이상** 중복 → 추출(SSOT로). (사례: PREMIUM_MODEL_LIMITS 3곳 → `@d3ro/core/constants` 통합 완료.) +- 2곳 중복은 맥락에 따라 판단(강제 X). 임계치 아래는 의도적 중복 허용. +- **확정: 3회** (2026-07-22 합의) + +### DP8. 자동화 — typecheck + lint + test + 강제 규칙 훅 +- WS 통합 후 반드시 GREEN: `npm run typecheck`(turbo) · `npm run lint` · `npm run test` · `npm run build`(빌드 영향 WS). +- UI 변경: `npm run dev`로 화면 1회 확인. (WS3은 화면별 즉시) + +--- + +## 2. 본 Wave 한정 추가 결정 (감사 후 확정 가능) + +### DP9. 미사용/데드코드 처리 강도 — **공격적 (제안)** +- R2 공격적 모드: "false negative > false positive". export/컴포넌트/서비스/의존성 미사용은 DELETE 우선. +- 단, 외부 API(라이브러리 entry, IPC handler)로 노출된 export는 KEEP. 감사에서 `grep references`로 확인 후 판정. +- 알려진 잔여: `MetalDial`(CLAUDE 명시 미사용), `@mui/icons-material` 의존성(lucide 전환 후 잔여), LemonSqueezy 코드 잔존(LicenseService activate/deactivate). +- **확정: 공격적 DELETE** (2026-07-22 합의) — 단 외부 API 노출 export는 grep references 후 KEEP. + +### DP10. 워크스트림 분할 (R3) — 파일 영역 비충돌 +| WS | 영역 | 의존 | +|----|------|------| +| WS1 | 토큰/SSOT 정의 — `packages/ui/src/{theme,theme-vars}.ts`, DS 컴포넌트 | — | +| WS2 | 메인 프로세스 — `apps/desktop/src/main/`, preload, `packages/core` 타입/IPC | — | +| WS3 | 렌더러 UI — `apps/desktop/src/renderer/` (화면별 분담 가능) | **WS1 의존** | +| WS4 | i18n — `packages/i18n/src/`, t() 키 정리 | — | +| WS5 | 빌드/설정/팝업 — `package.json`, `electron.vite.config`, `electron-builder.yml`, Vanilla JS 팝업 | — | + +- 1차 wave: WS1/WS2/WS4/WS5 병렬. WS3는 WS1 완료 후 발사. +- 워크스트림당 **1 커밋** (R5). `git add -A` 금지, 정밀 add. + +### DP11. SKIP / 이월 기준 +- "복잡해서 SKIP" 금지 (안티패턴 A6). SKIP은 **기술적 제약 + 별도 Phase 필요** 명시. +- 대규모 재설계(상태머신 재구성, 서비스 쪼개기)는 이번 wave에서 **순수 이동(P3)** 먼저 시도, 진짜 재설계는 압력(props 20+개 등)이 명백할 때만. + +--- + +## 3. 이식 검증 인사이트 (HaramLog wave 1~10) + +- **P1**: HIGH 확신도 보고도 착수 전 30초 재검증(Read/Grep). false positive 기록. +- **P2**: "순수 이동" 분할에도 동작 변경이 숨는다. diff 1:1 대조(훅 체인, useEffect deps, 구독/해제). +- **P3**: 거대 파일 분할은 순수 이동이 90%. 재설계는 분리 후 남는 압력에서만. +- **P4**: 화면 고유 수치는 토큰화 금지, file-private 상수. +- **P5**: 비컴포넌트 함수의 한국어 반환은 i18n 키 반환으로 전환. +- **P6**: 이름 충돌은 역할 접미어 예방(`RecordingState` enum vs `RecordingStateColor` 토큰). + +--- + +## 4. 합의 이력 + +| 항목 | 결정 | 일시 | +|------|------|------| +| Wave 1 범위 | Desktop + 공유 packages | 2026-07-22 | +| Wave 1 초점 | 데드코드/토큰SSOT/i18n/타입-IPC-아키텍처 전부 | 2026-07-22 | +| 커밋 주기 | WS별 분리 커밋 + 즉시 검증 (R5/R7) | 2026-07-22 | +| DP7 DRY 임계치 | 3회 | 2026-07-22 | +| DP9 데드코드 강도 | 공격적 DELETE (외부 API 노출 export는 grep 후 KEEP) | 2026-07-22 | +| DP6 typecheck 범위 | 전체 모노레포 typecheck 강제 (ui/i18n/core 공유) | 2026-07-22 | diff --git a/docs/REFACTOR_WAVE1_REPORT.md b/docs/REFACTOR_WAVE1_REPORT.md new file mode 100644 index 0000000..65db029 --- /dev/null +++ b/docs/REFACTOR_WAVE1_REPORT.md @@ -0,0 +1,110 @@ +# 리팩토링 Wave 1 보고서 + +> 일시: 2026-07-22 | 스킬: `/refactor-wave` | 범위: `apps/desktop` + `packages/{core,ui,i18n}` + +## 0. 합의 사항 (정책) + +| 결정 | 값 | +|------|-----| +| 범위 | desktop + 공유 packages (web/admin/site/server/mobile 이월) | +| 초점 | 데드코드/토큰SSOT/i18n/타입-IPC-아키텍처 전부 | +| 커밋 주기 | WS별 분리 커밋 + 즉시 검증 (R5/R7) | +| DP7 DRY 임계치 | 3회 | +| DP9 데드코드 강도 | 공격적 DELETE (외부 API 노출 export는 grep 후 KEEP) | +| DP6 typecheck 범위 | 전체 모노레포 강제 | + +정책 문서: `docs/REFACTOR_POLICY.md` (신규 작성) + +## 1. 정량 산출물 + +| WS | 산출 | 커밋 | +|----|------|------| +| **WS1 토큰/DS** | theme-vars dark/light 5변수 SSOT 정합(v1 주황→파랑), DS 미사용 3종 삭제(MetalDial/ButtonGroup/CrtDisplay, -324행), StatRing hex 10색→토큰 | `b820c78` | +| **WS2 메인/IPC/AppConfig** | ipc-channels SSOT 9그룹/키 추가, 하드코딩 채널 SSOT 교체(불일치 4건 preload 재검증), AppConfig 7키 추가, `as never` 16건 제거, require 3건→static, services/index.ts 데드 제거 | `aef4428` | +| **WS3 렌더러** | `accent.amber`→`main` 91건/34파일, 매직 리터럴→d3roTypo/d3roRadius 37건 | `078304d` | +| **WS4 i18n** | date.today/yesterday 중복 버그 수정(ko/en), 고아 키 967건 삭제(109+858) | `87f2dac` | + +**사용자 노출 버그 2건 해소**: (a) 한국어 날짜 "TODAY"/"YESTERDAY" 표시 → "오늘"/"어제", (b) 팝업=주황/렌더러=파랑 색상 충돌 → 정합. + +## 2. 검증 결과 + +| 게이트 | 결과 | +|--------|------| +| typecheck (desktop/core/ui/i18n/admin/api-client) | ✅ GREEN | +| typecheck (`@d3ro/web`) | ⚠️ pre-existing 1건 (`teams/[id]/page.tsx` Supabase 쿼리 타입) — web은 범위 외, 이월 | +| lint (내 변경 영역 45파일) | ✅ **0 errors** (12 warnings = pre-existing unused vars, 이월) | +| lint (전체 `eslint .`) | ⚠️ pre-existing — `apps/mobile-rn/.eslintrc.js`가 `@react-native` extends(패키지 미설치)로 전체 붕괴 + pre-existing 23 errors. 별도 lint 정리 wave 필요 | +| test | ✅ desktop 41/41 + api-client 19/19 | +| build | 미실행 (빌드 영향 WS 없음 — 패키지 의존성 제거는 WS5 2차) | +| UI 화면 확인 | 미실행 — UI 변경(amber/토큰)은 시각 동등(별칭 동일값 치환), 팝업 색 정합은 typecheck로 검증. 권장: `npm run dev`로 1회 육안 확인 | + +## 3. SKIP / 이월 항목 (명확한 사유) + +| 항목 | 사유 | 후속 | +|------|------|------| +| theme.ts `accent.amber` 별칭 제거 | `accent.amber`가 web/admin/site/mobile/ui-native에서 수십 곳 사용 → 공유 패키지 토큰 제거 시 전체 깨짐 (DP6 위반) | **Wave 2**: 전체 모노레포 amber→main 치환 | +| theme-vars 평행 SSOT 구조 단일화 (theme.ts RAW에서 파생) | 값 정합만으로 버그 해소됨. 구조 재설계는 회귀 위험 | Wave 2 | +| B6 팝업 `_i18n` 주입 + 색상 토큰화 | WS1(토큰)/WS4(i18n키) 산출물 소비 → 2차 wave (사용자 합의) | **WS5 2차** | +| B5 AppConfig SSOT 잔여 (CloudSyncService Supabase `as never`) | PK/컬럼 타입 구조 이해 선행 필요 | Wave 2 | +| B8 서비스-IPC 결합 분리(11서비스 webContents.send→EventEmitter 역전) | 아키텍처 재설계, 반나절~하루 | **별도 Phase** | +| 타 locale 334키 누락 (번역 파이프라인) | 번역 자동화(DeepL/AI) 별도 구축 | **별도 Phase** | +| `ipcSuccess/ipcError` 헬퍼 통일, `catch {}` 패턴 | 시간 관계 | Wave 2 | +| web `teams/[id]` typecheck 에러, 전체 lint pre-existing 부채 | 범위 외 | 별도 lint/type wave | + +## 4. 메타 학습 (이번 wave에서 습득) + +### M1. 공유 패키지 토큰 변경은 모든 소비 앱에 영향 — "부분 치환 + 별칭 제거" 불가 +`packages/ui/src/theme.ts`의 `accent.amber` deprecated 별칭을 제거하려 했으나, web/admin/site/mobile/ui-native가 수십 곳에서 `d3roPalette.accent.amber`를 import 사용. **desktop만 치환해도 별칭은 공유 패키지에 남겨야 함**. → 이식 인사이트 P7 신설. + +### M2. typecheck GREEN이 고아 키 검증의 충분조건이 아니다 (P1 재검증 가치 입증) +WS4에서 camelCase `license.feature.*` 15키를 고아로 오팅할 뻔. 그러나 `LicenseService.getTierComparison()`이 `featureLabel: 'license.feature.llmProcess'`(camelCase)를 할당하고 `t(row.featureLabel)`로 **프로퍼티 패스스루** 참조. `featureLabel: string`(느슨한 타입) + `as Parameters[0]` 캐스트가 TranslationKey strict를 우회 → **typecheck가 잡지 못함**. grep 동적/변수 보간 + 프로퍼티 할당 검증이 상호보완적으로 작동. 런타임 버그(라이선스 비교표 빈 라벨) 15건 예방. → P1 강화. + +### M3. 감사·구현 에이전트는 typecheck를 회피하는 경향 — 프롬프트에 "EXIT 0 직접 확인" 강제 +WS1·WS3이 "메인 작업자가 통합 후 수행" / "PowerShell이라 로컬 실행" 핑계로 typecheck를 돌리지 않음. 통합 단계 재검증으로 cover했으나, **에이전트 프롬프트에 "typecheck는 본인이 직접 EXIT 0까지 확인하고, 안 되면 원인 보고"를 hard requirement로 박아야**. → SKILL R7 강화. + +### M4. lint 게이트의 pre-existing 부채 — "내 영역 errors 0"으로 재해석 +전체 `eslint .`가 `apps/mobile-rn` config 문제로 붕괴 + pre-existing 23 errors. codebase가 원래 lint GREEN이 아니었음. "통합 후 lint GREEN"(R7)이 비현실적. **"내가 건드린 영역의 lint errors 0" + "pre-existing은 별도 wave"**로 게이트 재해석. → SKILL R7 명시 갱신. + +### M5. 병렬 WS에서 같은 토큰을 다른 파일이 참조하면 동시 진행 OK +WS1(theme.ts 정의)과 WS3(렌더러 참조)이 동시 진행 가능 — 서로 다른 파일. 단, "별칭 제거"는 참조 치환(WS3) 완료 후 순차. 파일 영역 분할(R3)만으로 충분; 토큰 의존성은 참조/정의 파일 분리로 해소. + +### M6. JSON duplicate-key 버그는 grep/count로 잡기 어렵다 → CI 체크 권장 +`date.today` 중복 정의(JSON last-wins)가 한국어 "TODAY" 표시 버그를 낳음. 정적 분석으로 탐지 어려움. `jq -r 'keys' file | sort | uniq -d` 또는 duplicate-key-detector CI 단계 권장. (Agent C 제안 채택) + +## 5. 다음 wave 계획 + +**Wave 2 (후속)**: +1. WS5 2차: 팝업 5종 `_i18n` 주입 + CSS 색상 토큰화(`--d3-wave-*`, `--d3-status-*`) — WS1/WS4 산출물 소비 +2. 전체 모노레포 `accent.amber`→`main` 치환 (web/admin/site/mobile/ui-native) → theme.ts 별칭 제거 +3. theme-vars 평행 SSOT 구조 단일화 (theme.ts RAW 파생) +4. AppConfig SSOT 잔여 (CloudSyncService Supabase 타입) +5. 미사용 의존성 8종 제거 (package.json) + electron-builder Linux 섹션 +6. ipcSuccess/ipcError 헬퍼 통일 + catch 패턴 + +**별도 Phase**: +- 서비스-IPC 결합 분리 (아키텍처) +- 타 locale 334키 번역 파이프라인 +- 전체 lint pre-existing 부채 정리 (mobile-rn config 포함) +- web `teams/[id]` Supabase 타입 수정 + +## 6. 워크스트림별 세부 + +### WS1 (b820c78) +- theme-vars.ts: `--d3-accent-main`(dark #f25b29→#3b82f6, light→#2563eb), `--d3-bg-card`(dark #242427→#111a30), `--d3-text-dimLabel`(dark #5c2615→#4e5f85, light #b07040→#5a6f96). nord/solarized/catppuccin/dracula는 이미 정합(변경 없음). +- DS 3종 삭제: 렌더러 import 0건 재검증 후 barrel export 제거 + 파일 삭제. +- StatRing: RING_COLORS hex → `var(--d3-gradient-wave1-4)` + `d3roPalette.tag.*`. + +### WS2 (aef4428) +- ipc-channels.ts SSOT 추가: INSTRUCTION(GET_ALL/GET_BY_ID/CREATE/UPDATE/DELETE/REORDER), SYSTEM_AUDIO(ENABLE/DISABLE_LOOPBACK), POPUP_RESULT(PREPARE/MEASURED/SHOW), POPUP_HISTORY(7), POPUP_COMMAND(6), POPUP_CAPTION(HIDE), VOICE_PARTIAL(PARTIAL_TRANSCRIPT), CLIPBOARD(COPY), APP(DATA_CHANGED), VOICE_CONVERSATION.FINISH_LISTENING +- AppConfig 7키: customInstructions(CustomInstruction[]), llmChains(LLMChain[]), voiceCommandRules(VoiceCommandRule[]), voiceCommandsEnabled(boolean), activeInstructionId(string), activeChainId(string|null), captionAudioSource(mic|system|both) +- IPC 불일치 재검증: preload에서 result:prepare/show/measured, voice:partialTranscript 미사용 확인 → 안전하게 SSOT 통일 + +### WS3 (078304d) +- amber 91건: 27파일에서 accent.main 사용으로 전환 +- 토큰 37건: d3roTypo(label/small/body/heading/value/compact/engrave), d3roRadius(small/xs/inner) +- P4 제외: DashboardPage 스탯 fontSize(34/26/30px), 레이아웃 width, 토큰 미존재 값(10px, fontWeight 800, letterSpacing 다수) + +### WS4 (87f2dac) +- date 버그: ko/en 두 번째 정의(uppercase 잔해) 삭제 +- 고아 967건 삭제 (네임스페이스별: meeting 27, onboarding 26, license UI 9, dashboard 8, voiceAction 7, voiceCommand 7, chain 6, memo 6, context 3, mobile 3, *.loading 3, status/common 4) +- KEEP 20건: camelCase license.feature 15(`featureLabel` 패스스루), nav 5(`labelKey` 패스스루) diff --git a/memory/project_status.md b/memory/project_status.md index b575a7a..1953f1c 100644 --- a/memory/project_status.md +++ b/memory/project_status.md @@ -1,5 +1,25 @@ # D3RO-VOICE 프로젝트 현황 +## 리팩토링 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` 신규. + +**산출** (b820c78/aef4428/078304d/87f2dac): +- WS1 토큰/DS: theme-vars dark/light SSOT 정합(v1 주황→파랑, 팝업 색 충돌 해소), DS 미사용 3종 삭제(MetalDial/ButtonGroup/CrtDisplay), StatRing 토큰화 +- WS2 메인/IPC: ipc-channels SSOT 9그룹 추가, 하드코딩 채널 SSOT 교체(불일치 4건 preload 재검증), AppConfig 7키 추가 + as never 16건 제거, require 3건→static, services/index.ts 데드 제거 +- WS3 렌더러: accent.amber→main 91건/34파일, 매직 리터럴→d3roTypo/d3roRadius 37건 +- WS4 i18n: date.today/yesterday 중복 버그 수정(ko/en), 고아 키 967건 삭제 + +**사용자 노출 버그 2건 해소**: 한국어 날짜 "TODAY"→"오늘", 팝업=주황/렌더러=파랑 색 충돌 정합. + +**검증**: desktop/core/ui/i18n typecheck 0, 내 영역 lint 0 errors, test 41+19 GREEN. (web typecheck pre-existing 1건, 전체 lint mobile-rn config 붕괴 — 별도 wave.) + +**메타 학습**: (1) 공유 패키지 토큰 변경은 전체 소비 앱 영향 — theme.ts amber 별칭은 web/admin/site 사용으로 제거 불가 → 전체 치환 wave 이월. (2) typecheck GREEN이 고아 키 검증 충분조건 아님 — WS4 camelCase license.feature 15키가 featureLabel 프로퍼티 패스스루로 typecheck 우회, P1 grep 재검증이 런타임 버그 15건 예방. (3) 감사/구현 에이전트는 typecheck 회피 — 프롬프트에 EXIT 0 강제(SKILL P7/P8/P9 갱신). + +**다음 Wave 2**: WS5 팝업(2차) + 전체 amber 치환 + theme-vars 구조 단일화 + 미사용 의존성 8종 제거 + ipcSuccess/catch 패턴. 별도 Phase: 서비스-IPC 분리, 타 locale 번역 파이프라인, lint pre-existing 정리. + +--- + > 마지막 갱신: 2026-07-22 (TiltCard 3D 틸트 + 빛 반사 효과) ## TiltCard — 3D 틸트 + 커서 추종 빛 반사 효과 (2026-07-22 /design-taste-frontend + /refactor-wave) ✅