d3ro-voice/docs/REFACTOR_WAVE4_REPORT.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

11 KiB

Refactor Wave 4 Report — 두 번째 모노레포 위생 점검

기준일: 2026-11-04
기준 버전: 1.16.1 (버전 변경 없음)
범위: apps/*, packages/*, server/*, site/, CI/build 설정과 현재 맵
정책: REFACTOR_POLICY.md Wave 4

1. 결론

Wave 4는 공개 API·IPC와 사용자 데이터 계약을 유지하면서, 실제 참조가 없는 코드·의존성·도구 설정을 제거하고 중복된 quota/DB 계약을 정본에 연결했다. 감사 중 드러난 기능 결함은 source-only repair로 분리했으며, 실행 환경이나 외부 시스템 증거가 없는 항목은 완료로 올리지 않았다.

커밋, 푸시, 배포, 릴리스, linked/운영 DB migration 적용, 사용자 데이터 변경은 수행하지 않았다. 런타임 증거는 별도 project id·포트·볼륨의 격리 로컬 Supabase에서 throwaway fixture로만 만들었다.

2. 불변 조건과 감사 방식

  • 공개 IPC, preload, 서비스 singleton, 외부 소비 가능 export는 이름 검색만으로 삭제하지 않았다.
  • 삭제 후보는 정의→생산자→소비자→테스트/문서 순서로 확인하고, 각 묶음 뒤 잔여 참조를 다시 검색했다.
  • 순수 삭제·타입 정리(P1/P2)와 동작을 바꾸는 source repair(P3/P4)를 분리했다.
  • UI 구조·높이·행동은 바꾸지 않았다. site LED shadow는 같은 값을 theme token으로 옮겼다.
  • feature/runtime 상태는 자동화 통과만으로 [x]로 올리지 않았다.

3. Changed

P1 — 순수 삭제와 의존성 위생

  • 참조가 없던 web meeting trend chart 1개와 admin chart 3개를 삭제하고 web/admin의 recharts 및 lockfile 전이 의존성을 제거했다.
  • 참조가 없던 desktop feature-gate.ts와 내부 getter/helper 7종을 삭제했다. 공개 IPC·테스트 seam·singleton API는 유지했다.
  • 사용되지 않던 turbo.json, pnpm-workspace.yaml, api-client의 @d3ro/core 의존성을 제거하고 npm workspaces 하나만 남겼다.
  • api-client 의존성 제거 뒤 mobile의 독립 lockfile도 같은 해상도로 다시 생성해 제거된 @d3ro/core 전이 항목을 남기지 않았다.
  • 현재 실행 규칙과 Claude 보조 스킬에 남은 pnpm/Turbo 명령도 npm workspace 기준으로 교정했다.
  • web login/sidebar의 도달 불가능한 t(...) ?? fallback 15곳을 제거했다.

P2 — 타입과 경계 정리

  • mobile 11개 화면의 useNavigation<any>/useRoute<any>와 임시 route param list를 RootStackParamList 기반 exact type으로 교체했다.
  • TalkScreen의 직접 console.warn을 공용 logger로 이동했다.
  • api-client에 실제 DB와 맞는 PushProvider, PushToken, device-bound register/unregister RPC, consume_quota.p_period 타입을 추가했다.
  • web push는 deviceId를 필수로 하고 RLS/NOT NULL 계약과 충돌하던 직접 push_tokens upsert를 제거했다. 활성 device를 검증하는 register_push_registration RPC만 사용한다. Opt-out은 disabled intent를 먼저 기록하고 서버 unregister와 local unsubscribe를 bounded/parallel로 실행하며, logout의 sign-out은 cleanup을 기다리지 않는다.

P3 — SSOT와 i18n 정합화

  • knowledge_embedding quota를 packages/core/src/plan-catalog.ts의 PLAN_QUOTA에 편입하고 Deno generated contract를 재생성했다. embedding-quota.ts의 수기 tier 상수는 제거했다.
  • updater native dialog 16키를 12 locale catalog에 추가했다. prompt마다 현재 locale translator를 다시 읽어 같은 prompter의 ko→en 변경도 반영한다.
  • site LED의 raw box-shadow 3개를 Tailwind theme token으로 이동했다. 시각 값은 유지했다.

P4 — 분리된 기능/인프라 repair

  • root test:mobile을 mobile test:ci(jest --runInBand)에 고정했다.
  • root build:all과 Forgejo build-validation에 web production build를 추가했다.
  • web/admin typecheck는 clean checkout에서도 Next route/root-param 타입을 먼저 생성하도록 next typegen && tsc --noEmit 순서로 고정했다.
  • Forgejo quality job에 migration checker self-test와 실제 metadata/order 검사를 연결했다. 이 검사는 DB replay나 remote drift 검사가 아니다.
  • pg_cron service credential을 handler에서 검증하는 audio-purge에 verify_jwt = false를 명시해 gateway가 먼저 차단하지 않도록 했다. handler의 fail-closed 인증은 유지했다.
  • Supabase CLI 3.x가 제거한 [inbucket] 설정명을 [local_smtp]로 교체했다. 포트와 메일 동작 계약은 유지했다.
  • Web Push production sidebar를 explicit user-gesture permission → stable active web device → device-bound register RPC로 연결했다. Persistence 실패는 local subscription을 rollback하고, stale local subscription은 서버 재등록이 성공하기 전까지 connected로 표시하지 않으며, missing build-time VAPID key는 unavailable로 fail-closed한다. Standalone Docker 이미지에는 public/sw.js를 명시적으로 포함한다.
  • updater native dialog는 --preview-update-dialogs packaged-QA entry에서 실제 prompter의 네 분기를 updater/feed/download/install/settings 부작용 없이 순서대로 띄울 수 있게 했다. entry/prompt 계약과 12-locale parity는 자동화했고, GUI 외형은 외부 터미널 수동 게이트로 남겼다.
  • packaged native verifier는 실제 uiohook-napi/prebuilds/<platform>-<arch>/uiohook-napi.node를 필수로 검사하고, 누락/존재 fixture self-test와 상대·절대 package 경로를 검증한다. better-sqlite3 ABI repair와 N-API prebuild 존재 계약을 분리했다.

문서와 상태 교정

  • 12개 catalog의 2,742키 parity와 실제 surface 노출을 분리했다. Desktop은 12 locale이지만 web은 selector가 없고 mobile은 ko/en만 노출하므로 SHELL-03의 W/M은 [~]다.
  • Web Push production call site와 build-time public-key 계약을 추가했지만 provider secrets·배포된 drain·실브라우저 수신 증거가 없으므로 ACC-12 W와 GAP-PUSH-03은 [~]로 유지했다.
  • meeting memo의 content 기반 CAS가 A→B→A를 감지하지 못할 수 있는 문제를 GAP-SYNC-08로 등록했다.
  • audio-purge는 격리 로컬 pg_cron/Vault/객체 삭제까지 검증했고, 운영 배포·스케줄 실행만 GAP-OPS-04에 남겼다. surface locale 확대는 GAP-I18N-03으로 남겼다.
  • release SSOT는 현재 1.16.1 / 1160100 / 2026-11-04로, site deploy는 삭제된 GitHub 경로 없이 Forgejo→Cloudflare Pages 정본으로 교정했다. 손상된 INFRA-19 설명도 실제 GitLab/Forgejo native/updater gate에 맞췄다.

4. KEEP / DEFER 결정

  • 공개 IPC/TTS/history/service 메서드는 현재 내부 호출이 적어도 compatibility surface일 수 있어 유지했다.
  • STT driver DTO와 유사 타입은 공급자별 의미가 달라 이번 wave에서 억지로 합치지 않았다.
  • MeetingMemo revision 추가는 DB migration과 동시성 통합 증거가 필요해 구현하지 않고 gap으로 분리했다.
  • Web Push의 provider 설정·실브라우저 수신, locale selector/routing, updater packaged GUI, audio-purge 운영 deploy/cron은 로컬 증거만으로 완료 처리하지 않았다.
  • updater의 ko 이외 신규 키는 기존 locale 정책과 같은 English parity다. 번역 품질 확대는 별도 작업이다.

5. Verification

최종 통합 게이트 결과는 모든 변경을 합친 worktree 기준으로 기록한다.

Gate Result
Root typecheck/test + desktop/admin/web builds (npm run build:all) PASS — 233 files / 3,383 tests; desktop build; admin 18/18; web 18/18
Root lint PASS — warnings 0
Mobile typecheck/lint/test (test:ci) PASS — 87 suites / 599 tests, lint warnings 0
Root/mobile lock install dry-run PASS — npm ci --dry-run --ignore-scripts; removed dependencies do not survive in either lock
Core generated contract + version + design token gates PASS — contract current; 1.16.1 / 1160100; design violations 0
.NET API tests PASS — 28/28, skipped 0
Migration checker self-test/actual PASS — 73 migrations
Isolated Supabase runtime/shadow PASS — empty + reset replay 73/73; pg-delta --strict-coverage diff 0; audio purge direct + pg_cron/Vault HTTP/storage path
Edge CI-equivalent Deno check/test PASS — 24 function entrypoints; Supabase 263 tests; Cloudflare drain 5 tests (268 total)
Site production build PASS — client/SSR + 10 locale prerender and sitemap/robots/llms outputs
git diff --check + residual searches PASS — CRLF→LF notices only; deleted identifiers/dependencies/current toolchain commands 0 residual

이미 묶음별로 확인한 증거:

  • updater preview/startup/i18n 4 files / 7 tests, locale parity 15 tests; native ABI self-test and the current package's relative/absolute --dir verification
  • api-client 4 files / 31 tests
  • web push device/RPC/permission/rollback/reconciliation/logout contract 17 tests
  • core plan quota matrix test와 contract:check
  • mobile route/logger targeted suites, strict typecheck, lint
  • embedding quota/embed/search/audio-purge 표적 31 tests와 전체 Edge CI-equivalent 268 tests
  • web/admin production build, site build, design-token scan
  • migration checker 73 files + self-test
  • 격리 Supabase: missing/non-service key 401, service 200; queue/audio_files/Storage fixture 1|1|1→0|0|0; cron run succeeded, pg_net HTTP 200

6. 검증 경계와 남은 위험

  • Supabase local migration replay, shadow diff, audio-purge direct/pg_cron/object deletion은 격리 stack에서 검증했다. linked remote drift와 배포된 운영 함수·Vault·cron은 실행하거나 변경하지 않았다.
  • Electron GUI를 agent subshell에서 실행하지 않았다. updater dialog의 packaged-app 시각/상호작용 증거는 없다.
  • current-source E2E APK의 state-preserving 설치·cold launch와 제한된 Notifications/status/UIA 경로는 물리 Fold6에서 검증했다. 이것은 fresh first-run, manual TalkBack/focus order, notification permission transition/real FCM, app-wide accessibility, production artifact 또는 iOS/VoiceOver 증거가 아니다. Web Push는 격리 local browser에서 device/token/outbox/drain 및 provider-accepted delivered row까지 확인했지만 service-worker/browser receipt는 확인하지 못했다. Production standalone은 build/serve 후 throwaway login navigation timeout으로 dashboard 전 단계에서 중단돼 production 1440/390, accessibility tree/hit target, permission/subscription journey도 미검증이다.
  • npm install은 현재 Node 23에 대한 React Native engine 경고와 기존 audit 이슈를 보고했다. 범위를 벗어난 npm audit fix는 실행하지 않았다.
  • 빌드 산출물 배포, 버전 변경, 릴리스 publication은 수행하지 않았다.