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

111 lines
11 KiB
Markdown

# Refactor Wave 4 Report — 두 번째 모노레포 위생 점검
> 기준일: 2026-11-04
> 기준 버전: 1.16.1 (버전 변경 없음)
> 범위: `apps/*`, `packages/*`, `server/*`, `site/`, CI/build 설정과 현재 맵
> 정책: [`REFACTOR_POLICY.md`](./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은 수행하지 않았다.