d3ro-voice/docs/REFACTOR_POLICY.md
Yun Chan 7fe49c437e chore: land in-progress workspace changes before 1.16.2
The tree carried uncommitted work from several areas (web push, mobile
screens, admin charts, test-hygiene cleanup, CI and map docs). It is landed
as one commit so the release pipeline can start from a clean tree; the
desktop transcript-correction behaviour shipped in the previous commit and
is unchanged here.
2026-11-05 21:58:44 +09:00

12 KiB

D3RO-VOICE 리팩토링 정책 (SSOT)

마지막 갱신: 2026-11-04 — Wave 4 전체 모노레포 위생 점검 정책 확정 적용 범위: apps/* + packages/* + server/* + site/ + 빌드·배포 스크립트 (기능 변경은 별도 요청)

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(npm workspaces) · 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

Wave 3 (2026-09-26) — 표면·계약 단일화

사용자 결정: "두 벌씩 만든 것을 전부 하나로." 확정 사항과 정본은 아래와 같다.

# 결정 포인트 정본 파생(자동·검사)
W3-1 요금 packages/core/src/plan-catalog.ts PLAN_PRICE_KRW (Free 0 / Pro 2,900 / Pro+ 8,900, 월). 기존 구독자도 다음 갱신부터 적용 Deno _shared/core-contract.generated.ts (npm run contract:sync, CI contract:check)
W3-2 공개 URL packages/core/src/web-urls.ts — 사이트 /, 웹앱 /app(Next basePath), billingUrl(), SITE_URLS 같은 생성 파일
W3-3 결제 진입 웹앱 /app/billing 하나. 데스크톱·모바일·사이트는 모두 billingUrl(). 결제는 페이지 안 Payple 창에서 끝나므로 복귀 쿼리는 없다(Stripe와 success=1/canceled=1 복귀 쿼리는 2026-09-26 제거) —
W3-4 웹앱 배포 NAS Docker(d3ro_voice_web) → Cloudflare Tunnel 호스트 → 사이트 브리지 워커가 /app/*를 전달 —
W3-5 랜딩·다운로드·법률·초대·assetlinks site/ 한 벌. apps/web·api-server wwwroot 사본 삭제, 웹앱 /download는 사이트로 리다이렉트 —
W3-6 설치 파일 Forgejo feed만. 저장소에 추적된 바이너리 사본 삭제 —
W3-7 CI Forgejo(.forgejo/workflows) 한 벌. .github는 GitHub 원격이 없어 실행된 적이 없으므로 필요한 잡만 옮기고 삭제 —
W3-8 사이트 배포 Cloudflare Pages 한 경로. GitHub Pages·NAS wwwroot 복사 경로 삭제 —

DRY 원칙 보강: Deno처럼 정본을 직접 import할 수 없는 런타임은 생성 사본 + --check 게이트로만 복제를 허용한다(version:sync 패턴과 같음). 손으로 옮겨 적은 사본은 금지.


Wave 4 (2026-11-04) — 두 번째 전체 위생 점검

사용자 지시: "두 번째 소스코드 정리, 대대적인 위생 점검." 기존 DP1~DP11과 Wave 3 정본 결정을 그대로 계승한다.

W4-1. 목표와 비목표

  • 목표: 전체 모노레포에서 증거가 확인된 데드코드·데드 스텁·중복 선언/동작·의존성 잔여물·계약 드리프트·빌드/스크립트 중복을 줄인다.
  • 비목표: 새 기능, UI/UX·문구 변경, DB 마이그레이션, 공개 API/IPC/payload의 breaking 변경, 비밀값·운영 서버 변경, 릴리스·배포는 제외한다. 실제 DB와 어긋난 공유 타입의 additive 정합화는 소비자 전체 typecheck를 조건으로 허용한다.
  • 추측만으로 대형 파일을 쪼개거나 이름을 바꾸지 않는다. 삭제 우선 → 계약 안정화 → 중복 통합 순서를 지키고, 의미 있는 중복 제거 없이는 새 추상화를 만들지 않는다.

W4-2. 유지 불변량

  • 공개 API·IPC 채널, 오류 코드/메시지, 결과 순서, 보안 경계, 저장·동기화 의미, 광고·결제 fail-closed 동작은 유지한다.
  • 화면 상태와 시각 결과는 유지한다. UI 동작 변경이 필요한 발견은 이번 Wave에서 기능 변경 후보로 분리하고 순수 정리와 섞지 않는다.
  • 기존 사용자 변경과 무관한 파일을 되돌리지 않으며, 현재 정책 문서 변경 외에는 감사 단계에서 소스를 수정하지 않는다.

W4-3. 감사와 실행 분리

  • 감사 A: 데스크톱 main/preload + packages/core — 서비스 경계, IPC·타입 SSOT, 데드코드/스텁, 중복 워크플로, any/console, 캐시 소유권.
  • 감사 B: desktop renderer + web/admin/mobile/site + packages/ui/ui-native — 디자인 토큰, i18n, 중복 UI/스타일, 미사용 컴포넌트와 export, any/console.
  • 감사 C: packages/i18n + server + 빌드/CI/의존성/스크립트 — 로케일 정합, 계약 사본, 미사용 의존성, 설정 중복, 문서-코드 드리프트.
  • 모든 후보는 file:line, 참조/호출 증거, HIGH/MED/LOW 확신도, DELETE/REPLACE/REFACTOR/KEEP 판정과 예상 게이트를 가져야 한다. KEEP도 이유를 명시하고, HIGH라도 구현 전에 다시 읽어 false positive를 걸러낸다.

W4-4. 패치 그룹과 검증

  • 파일이 겹치지 않는 P1 삭제/잔여물, P2 중복·SSOT, P3 설정/의존성 그룹으로 나눈다. 순수 리팩토링과 불가피한 기능 수정은 절대 같은 그룹에 두지 않는다.
  • 그룹마다 잔여 식별자 grep, 최소 표적 테스트, 변경 파일 lint를 먼저 실행하고, 통합 후 루트 typecheck·test·lint, 모바일 typecheck·test·lint, 영향받은 빌드와 version:check·contract:check를 실행한다.
  • packages 공유 계약 변경은 모든 소비 앱을 검사한다. UI 시각 변경은 원칙적으로 제외하며, 예외가 생기면 별도 합의와 시각 증거가 필요하다. 에이전트 서브쉘에서 Electron GUI를 백그라운드 실행하지 않는다.
  • 커밋·푸시는 사용자가 별도로 명시할 때만 수행한다. 이번 Wave는 패치 그룹별 diff와 검증 증거를 보존하고, docs/REFACTOR_WAVE4_REPORT.md에 변경/검증/SKIP/잔여 위험을 기록한다.