Some checks failed
ci / 정본·보안·린트·타입·테스트 (push) Failing after 18s
ci / 워크스페이스 빌드 검증 (push) Has been skipped
ci / 모바일 린트·타입·Jest (push) Successful in 45s
ci / Supabase Edge Functions + Cloudflare Worker (push) Successful in 22s
ci / .NET API 서버 테스트 (push) Successful in 11s
deploy-site / deploy (push) Successful in 44s
110 lines
14 KiB
Markdown
110 lines
14 KiB
Markdown
# D3RO Voice — Wave 7 다중 세션 피어 스웜 코드 위생 · 최적화 · 버그 헌팅 보고서
|
||
|
||
> 일시: 2026-11-14
|
||
> 대상 브랜치: `main` (기준 커밋 `a37dd63` -> 통합 커밋 `cc3f746`, 7 commits / 98 files `+7,170 / -597`)
|
||
> 실행 토폴로지: Antigravity 네이티브 `swarm` 6개 세션 (`monitor`, `input-core`, `desktop-shell`, `mobile-app`, `cloud-surfaces`, `verifier`) + `@mention`/`#seq` 피어 리뷰 보드(`Run /swarm board (default shortcut alt+s) to open the live board.`)
|
||
> 정책 SSOT: `docs/REFACTOR_POLICY.md`, `.claude/skills/refactor-wave/SKILL.md`
|
||
|
||
---
|
||
|
||
## 1. 운영 배포 경계와 Wave 7 범위
|
||
|
||
1. **운영 `v1.17.1` 기준선 (`6c6875b`, 태그 `v1.17.1`)**: 데스크톱(Forgejo `1.17.1/latest.yml`·`.sig`, `runtime-1.17.1`, `portable-1.17.1` HTTP `200`; Human Release #339 ~91MB 바이너리 첨부만 `GAP-REL-16` 예외), Supabase 운영 DB(74개 마이그레이션 동기화)·Edge Functions 24종, 랜딩 사이트(`site/` -> Cloudflare Pages `d3ro`, `https://d3ro.chanpaca.net/release-identity.json`), Cloudflare Worker(`d3ro-voice-api` `--keep-vars`, Version ID `fe6d9532-0052-48f5-b62c-45c86f6aaaa5`), NAS Docker 스택(`api-server` `:5050/health` `200`, `admin` `:3001` / `d3ro-admin.chanpaca.net/login` `200`, `web` `:3002/app/login` / `d3ro.chanpaca.net/app/login` `200`) 배포 완료 후 `a37dd63`에 기록됨.
|
||
2. **Wave 7 반영 범위 (`2a009e4..cc3f746`)**: Wave 7 커밋은 **`v1.17.1` 배포 이후**에 `main`으로 통합·검증되었다. 따라서 Wave 7 수정사항은 현재 **`main` 통합 및 모노레포 전 게이트 검증 완료** 상태이며, `v1.17.1` 기배포 바이너리·컨테이너에는 포함되어 있지 않다(차기 릴리스 `v1.17.2` / `v1.18.0` 및 재배포 반영 대상).
|
||
3. **Cloudflare Worker 운영 환경변수 경계**: Wave 7(`c68e81e`)이 `server/cloudflare-worker/wrangler.toml`의 `BACKEND_ORIGIN` 기본값을 `https://d3ro.chanpaca.net`으로 수정했으나, `v1.17.1` 배포 당시 `--keep-vars`로 유지된 라이브 Worker `d3ro-voice-api`(`fe6d9532-0052-48f5-b62c-45c86f6aaaa5`)에는 기존 대시보드 변수(`BACKEND_ORIGIN = "http://192.168.0.39:5050"`)가 남아 있어 라이브 `/health`는 Cloudflare Error `1003` (`HTTP 403`) 상태다.
|
||
|
||
---
|
||
|
||
## 2. 피어 리뷰(`@verifier`) 바운스 및 해소 이력
|
||
|
||
1. **#10 `desktop-shell` 바운스 -> `3f9e412` 해소 (`4 files, +103/-3`)**:
|
||
- 문제: `LocalLLMService` `/api/pull` 중단 및 `LocalSTTService` 모델 다운로드 `dispose()` 중단 시 raw abort 오류가 `D3ROError`로 래핑되지 않아 계약과 불일치.
|
||
- 수정: `LocalLLMService.ts`는 `D3ROError(ErrorCode.LLM_ERROR)`로, `LocalSTTService.ts`는 `D3ROError(ErrorCode.STTModelDownloadCancelled)`로 래핑하고 관련 단위 테스트 보강.
|
||
2. **#11 `mobile-app` 바운스 -> `cc3f746` 해소 (`5 files, +376/-45`)**:
|
||
- 문제: `durable-processing-queue.ts` cleanup 경로에서 큐 항목 제거와 오디오 파일 삭제 순서·실패 재시도 보장이 미흡했고, 다중 화면에서 계정 전환 후 `busy`/`running` 상태가 섞일 여지가 남아 있었음.
|
||
- 수정: `finishCleanupItem(item)`으로 오디오 파일 먼저 삭제 후 큐 항목 제거(삭제 실패 시 60초 재시도 예약), 화면(`Commands`, `HistoryDetail`, `Home`, `Knowledge`, `Meetings`, `Record`, `Teams`)에 `scopeGenerationRef`와 `try/catch/finally` 가드 통일.
|
||
3. **#17 `cloud-surfaces` 바운스 -> `4bf0f0d` 해소 (`7 files, +363/-106`)**:
|
||
- 문제: `apps/web/src/components/chat/chat-panel.tsx` `executeChatSendTurn`과 `action-runner.tsx`, `payple-manage-button.tsx`, `generate-document-button.tsx`, `invite-member-form.tsx`에서 `createTimedAbortSignal` 타임아웃이 삼켜지거나 await 이후 언마운트(`shouldExitAfterAwait`) 판정이 일관되지 않았음.
|
||
- 수정: `edge-fetch.ts` 계약 기준으로 타임아웃·abort·언마운트 가드를 전파하고 `security-and-lifecycle.test.ts` 회귀 보강.
|
||
4. **최종 승인**: `@verifier` 재검증 후 `#21` `@coordinator [all-verified]` 수신 -> 전 커밋 `main` 체리픽(`0` 충돌) 및 커밋 메시지 위생 검증(`Co-Authored-By`/AI 문구 0건) 후 워커 종료(`#22`).
|
||
|
||
---
|
||
|
||
## 3. 워크스트림별 수정 내역
|
||
|
||
### 3.1 `input-core` (`2a009e4`, `8 files, +640/-53`) — 문장부호 직후 무공백 영타 오타 라이브 트리거 복구
|
||
|
||
실사용 중 보고된 `상황 잘 지켜보는중?dbrlgkrhdlTwlsdksgwl?`(기대 변환: `유기하고있진않지`)와 같은 **문장부호(`?`) 직후 공백 없이 이어진 영타·말줄임표 오타**가 라이브 파이프라인에서 누락되던 4가지 원인을 동시에 수정했다:
|
||
|
||
| 계층 | 파일 | 수정 내용 |
|
||
|---|---|---|
|
||
| Telemetry | `apps/desktop/src/main/services/InputTelemetryService.ts` | `TYPO_SETTLE_DELAY_MS` (`700ms`) / `_typoSettleTimer` 추가로 제안 기능 비활성·지연·접두사 임계치 미달 구간에서도 `>=650ms` settle 스냅샷 보장; `diffInsertionSpan()`으로 문장부호(`?`) 트리밍을 걸친 `_expectedInserts` 계산 정확화; 만료된 `_programmaticKeys` 정리 및 `_learnFlushTimer.unref()` |
|
||
| Typo Service | `apps/desktop/src/main/services/TypoCorrectionService.ts` | 문장부호 경계 정규식(`~…?!。`) 확장; `trailingWordOnly` 패스에서 경계로 닫힌 단일 토큰을 최대 `MAX_INPLACE_DELETE_CHARS` (32)자까지 허용하고 `_markRegionChecked()` 영구 잠금 차단 |
|
||
| Core Rules | `packages/core/src/araso-layout.ts`, `typo-correction.ts`, `personal-ngram.ts` | `isUrlOrPathRun()`으로 `domain.tld?` / `file.ext?`는 보호하되 한글+말줄임표(`[가-힣ㄱ-ㆎ][!?~]*\.{2,}$`) 변환 허용(`...props` 유지); `WORD_BOUNDARY_AFTER_RE` 정리; `PersonalNgramModel.next()` 불필요한 `Map` 복사 제거 |
|
||
| Regression Tests | `apps/desktop/tests/main/services/typo-live-punctuation.test.ts`, `TypoCorrectionService.test.ts`, `packages/core/__tests__/typo-correction.test.ts` | 문장부호 뒤 한/영 무공백 전환, URL/코드 접두사 비변환, 재입력·트림 복원 회귀 테스트 추가 |
|
||
|
||
### 3.2 `desktop-shell` (`fc5d453` 19 files + `3f9e412` 4 files) — 메인 서비스 취소 · 해제 · 레이스 하드닝
|
||
|
||
- `apps/desktop/src/main/windows/WindowManager.ts`: `hideResultPopup()`에서 `pendingResultShow` 타이머를 취소하고 `lastResultCursor = null`로 초기화(`popup-hide-show-race.test.ts`).
|
||
- `apps/desktop/src/main/services/CaptionService.ts`: `ensureAuxModel` 성공 뒤 `_captionModelId`를 기록하고 이전 `loadedAuxModelId`를 해제, `_stopPromise`로 동시 `stop()`/`dispose()` 중복 실행 차단, 호출 단위 `AbortController` + `_refineEpoch`/`_refineRunId` 리셋(`caption-lifecycle-refine.test.ts`, `caption-aux-release.test.ts`).
|
||
- `apps/desktop/src/main/services/VoiceModeService.ts`, `llm/LlmGateway.ts`, `LocalLLMService.ts`: `run.controller.signal`을 `LocalLLMService.processText`까지 전파, `/api/pull` `AbortController` 등록 및 `dispose()` 시 리더·요청 중단 후 `D3ROError(ErrorCode.LLM_ERROR)` 래핑, dispose 이후 폴링 가용성 복원 차단(`local-llm-service.test.ts`, `llm-limits-routing-redteam-r2-1.test.ts`, `VoiceModeService.test.ts`).
|
||
- `apps/desktop/src/main/services/{VoiceConversationService,AudioCaptureService,LocalSTTService}.ts` & `ipc/caption-handlers.ts`: abort 시 `_responseAbortController` 정리, stale 마이크 시작 catch 가드, SoX `'stopping'` 재개 확인 및 `start()` 실패 `_cleanup()`, `dispose()` 시 STT 모델 다운로드 fetch/sleep 중단 + `D3ROError(ErrorCode.STTModelDownloadCancelled)` 래핑, `desktopCapturer.getSources` fail-closed `callback({})`(`VoiceConversationService.test.ts`, `audio-capture-redteam-r2-7.test.ts`, `stt-sidecar-redteam-r2-6.test.ts`, `ipc-redteam-r3-1.test.ts`).
|
||
|
||
### 3.3 `mobile-app` (`bd3c1a9` 25 files + `cc3f746` 5 files) — 레코더 · 내구성 큐 · 컨텍스트 · 화면 비동기 가드
|
||
|
||
- 레코더 (`src/lib/audio-recorder.ts`, `src/lib/recorder/{nitro-backend,android-foreground-backend}.ts`): `pendingClaim` + `finally` 해제, `startGeneration`/`sessionGeneration` 세대 가드, `pollTimer` 누수 방지(`recorder-lifecycle-races.test.ts`).
|
||
- 큐·히스토리 (`src/features/recording/durable-processing-queue.ts`, `src/features/history/use-history-sync.ts`): `running`/`cleanup` 가드, `suspendedUsers` 재시도 차단, `discardedItems` 재검사, `finishCleanupItem(item)`(오디오 파일 선삭제 -> 큐 항목 제거, 삭제 실패 시 60초 재시도), request-id/scope 가드(`queue-and-history-races.test.ts`).
|
||
- 서비스·컨텍스트·화면: `chat-service.ts`, `admin-service.ts`, `device-service.ts`, `llm-stream-service.ts`, 4개 컨텍스트(`mobile-ads`, `billing`, `device`, `entitlement`), 7개 화면(`Commands`, `HistoryDetail`, `Home`, `Knowledge`, `Meetings`, `Record`, `Teams`)에 pre-abort 가드, 세대 헤더 불일치 시 `response.body` 취소, 계정 전환 상태 초기화 및 `scopeGenerationRef` + `try/catch/finally` 적용(`abort-and-stream-guards.test.ts`, `context-lifecycle-guards.test.tsx`, `screen-async-lifecycle.test.tsx`).
|
||
|
||
### 3.4 `cloud-surfaces` (`c68e81e` 46 files + `4bf0f0d` 7 files) — 엣지 게이트웨이 · .NET SSRF · Supabase · Web/Admin 보안
|
||
|
||
- **Cloudflare Worker & Site Bridge (`server/cloudflare-worker`, `server/cloudflare-site-bridge`)**: `wrangler.toml` `BACKEND_ORIGIN`을 `https://d3ro.chanpaca.net`으로 교정, `origin-policy.ts`로 비-HTTPS·사설 IP·내부 호스트·프록시 루프(`508`/`503`) 차단, `204`/`205`/`304` null-body 처리, `push-drain.ts` origin 검증; `cloudflare-site-bridge` `508` 루프 가드·경로 스머글링 `400`·`deno.json` 추가.
|
||
- **.NET API (`apps/api-server`, `apps/api-server.Tests`)**: `EndpointUrlPolicy.cs` SSRF 검증, `"UpstreamNoRedirect"` 명명 `HttpClient`(`AllowAutoRedirect = false`), query language parameter 인코딩, `EndpointSecurityAndSttProxyTests.cs` 추가.
|
||
- **Supabase Edge Functions (`server/supabase/functions`)**: `stt-proxy/handler.ts` `Content-Length` 초과 선차단(`413`), `embed-chunks/handler.ts` 업스트림 프로바이더 오류 시에만 할당량 환불, `_shared/quota.ts` `PGRST116` 외 DB 오류 fail-closed 예외 전파.
|
||
- **Web & Admin (`apps/web`, `apps/admin`)**: `safeReturnPath` / `public/sw.js` / `admin-url-safety.ts`로 `//evil`·백슬래시·제어문자 오픈 리다이렉트 차단, OAuth callback 오류 메시지 누출 제거, `apps/admin/src/proxy.ts` `isStaticAssetPath` 정밀화; `apps/web/src/lib/edge-fetch.ts` (`resolveSupabaseFunctionUrl`, `createTimedAbortSignal`, `shouldExitAfterAwait`)를 `chat-panel`, `action-runner`, `payple-*`, `generate-document-button`, `invite-member-form`, `document-editor`, `history` 페이지들에 적용하고 `auth-provider` `bindAuthSession` / `mic-recorder` `acquireGuardedMediaStream` 보강 (`apps/web/tests/security-and-lifecycle.test.ts`, `apps/admin/tests/admin-security.test.ts` + Vitest 구성).
|
||
|
||
---
|
||
|
||
## 4. 통합 `main` (`cc3f746`) 전체 검증 결과
|
||
|
||
### 4.1 Batch 1 (정적 · 계약 · 백엔드 · 사이드카, `task-587`, exit `0`)
|
||
|
||
| 게이트 / 스위트 | 결과 |
|
||
|---|---|
|
||
| `version:check` | `1.17.1` (`1170100/1170100`) PASS |
|
||
| `contract:check` / `check:migrations` | PASS / `74` files 일치 |
|
||
| `security:secrets` / `check:protected-tests` | `0` issues / `0` protected modifications (`HEAD` & `a37dd63`) |
|
||
| `test:hygiene` / `test:quality` | `448 test files` PASS / `468 test files`, `0` regression |
|
||
| `check:i18n` / `check:ds-contract` / `check:design` | `2500 keys × 12 locales` / `13 components` / `0` violations |
|
||
| `dotnet test` (`apps/api-server.Tests`) | **55 passed, 0 failed** |
|
||
| Sidecar Python `unittest` | **33 tests in 2.169s, OK** |
|
||
| Supabase Edge (`deno check` + `deno test`) | **273 passed \| 0 failed** |
|
||
| Cloudflare Worker (`deno check` + `deno test`) | **15 passed \| 0 failed** |
|
||
| Cloudflare Site Bridge (`deno check` + `deno test`) | **5 passed \| 0 failed** |
|
||
|
||
### 4.2 Batch 2 (모노레포 TS · ESLint · Vitest · Jest · 빌드 · 지표, `task-654`, exit `0`)
|
||
|
||
> **환경 복구 메모**: Windows 환경에서 `swarm kill`로 `share` 워크트리가 삭제되며 루트 `.bin`·`apps/{admin,web}/node_modules` 일부와 `apps/mobile-rn/node_modules/@babel/plugin-transform-runtime` 등이 손상되어, 게이트 실행 전 `npm install --prefer-offline` + `npm --prefix apps/mobile-rn ci --prefer-offline`으로 복구하고 `better_sqlite3.node` (`sqlite_abi=node_ok`)를 확인했다.
|
||
|
||
| 게이트 / 워크스페이스 | 결과 |
|
||
|---|---|
|
||
| `typecheck` / `typecheck:mobile` / `typecheck:site` | PASS |
|
||
| `lint` / `lint:mobile` / `lint:site` (`--max-warnings=0`) | PASS |
|
||
| `@d3ro/desktop` (Vitest) | **212 files / 2,890 tests PASS** |
|
||
| `@d3ro/web` (Vitest) | **10 files / 52 tests PASS** |
|
||
| `@d3ro/admin` (Vitest) | **1 file / 6 tests PASS** |
|
||
| `@d3ro/api-client` (Vitest) | **4 files / 31 tests PASS** |
|
||
| `@d3ro/core` (Vitest) | **39 files / 629 tests PASS** |
|
||
| `@d3ro/i18n` (Vitest) | **2 files / 25 tests PASS** |
|
||
| `@d3ro/ui` (Vitest) | **2 files / 7 tests PASS** |
|
||
| `test:mobile` (`@d3ro/mobile-rn` Jest `--runInBand`) | **103 suites / 651 tests PASS** (`24.945 s`) |
|
||
| `npm run build` + `check:desktop-renderer` | `electron-vite build` + **7 page(s)** PASS |
|
||
| `npm run test:metrics:write` (`docs/tdd-red/metrics/2026-11-14.md`) | **454 files / 3,738 cases / weak 128 / ambient 203 / skip/todo 3 / 12 locales / 2,500 keys** |
|
||
|
||
---
|
||
|
||
## 5. 유지된 비코드 / 런타임 / 외부 경계 (`[~]` · `[!]` · `RED`)
|
||
|
||
- **Desktop runtime (`[~]`)**: `InputTelemetryService` / `TypoCorrectionService` / `CaptionService` / `LocalLLMService` / `LocalSTTService` / `WindowManager` 수정은 단위·서비스 테스트 및 렌더러 번들 게이트까지 검증되었으며, 실제 Windows GUI(예: `상황 잘 지켜보는중?dbrlgkrhdlTwlsdksgwl?` 라이브 타이핑, 오버레이 표시/해제)는 `GAP-INPUT-08/09/10/11` 외부-터미널 `run-desktop.bat` 실행 대상으로 남는다.
|
||
- **Mobile runtime & Play Store (`[~]` / `[!]` / `RED`)**: Fold6/iOS 실기기 수동 TalkBack·초회 진입·FCM 수신·AdMob 운영 광고·Play Billing·Play 비공개 테스트(`EXT-*`)는 외부 게이트(`RED`)로 유지한다.
|
||
- **Cloudflare Worker live env (`[~]`)**: `wrangler.toml` `BACKEND_ORIGIN` 수정분을 실운영 `d3ro-voice-api`에 반영하려면 대시보드 변수 덮어쓰기 또는 재배포가 필요하다.
|