fix: version neural audio requests for v0.1.1

2026-10-14 07:31:47 +00:00
parent a92b2ba1e9
commit c92660b514
38 changed files with 3400 additions and 42 deletions
@@ -144,3 +144,46 @@ Codex가 새로 작성한 입력 문서가 아니다. 전체 파일 목록은
 - 원자 교체는 Linux와 해당 파일시스템의 지원이 필요하다. SIGKILL/전원 손실 때 임시
  숨김 폴더는 남을 수 있고 전원 손실 내구성까지 보장하지 않는다. 일반 실패·Ctrl-C는 정리한다.
 - 실제 모바일 Safari/물리적 오디오 장치 청취는 이번 Chrome 검증 범위 밖이다.
+
+## 2026-10-14 추가 — 배포 후 오디오 캐시 회귀 수정
+
+제품 버전 **0.1.1**을 유지하면서 intro와 목표 100개 WAV 모두
+`?v=0.1.1`을 붙이도록 수정했다. `src/audio/assets.ts`의
+`AUDIO_ASSET_VERSION`과 `audioAssetUrl`을 출제·오디오 엔진이 함께 사용한다.
+WAV/manifest 및 package/lock은 변경하지 않았다.
+
+발견 원인은 **음성 내용 교체 후에도 요청 URL이 같았던 것**이다. 사용자 보고의
+배포 Nginx `/audio` 7일 캐시에서 기존 사용자는 이전 음성을 계속 받을 수 있었다.
+기존 배포 문서의 재검증 가정과 실제 설정이 달랐으며, 브라우저 테스트의
+전체 URL `.endsWith('.wav')`와 404 glob도 query string을 놓쳤다.
+원격 서버에는 접속하지 않고 소스·로컬 production build에서 재현했다.
+
+앱 구현을 수정하기 전에 unit/browser 계약을 작성하고 실제 RED를 확인했다.
+RED 때 앱 소스가 그대로였다는 기록은 [04-red-state.json](evidence-v0.1.1/cache-regression/04-red-state.json)에 있다.
+
+| 계약/검증 | 결과 | 새 evidence |
+| --- | --- | --- |
+| 목표 100개 버전·intro/target fetch·각각 404 retry·query pathname 판정 | RED 5 failed / 12 passed → GREEN 17 passed | [RED](evidence-v0.1.1/cache-regression/01-unit-red.log), [GREEN](evidence-v0.1.1/cache-regression/05-unit-green.log) |
+| 실제 브라우저 요청/정답 mapping·intro/target 404·101개 URL | 구현 전 desktop RED 4 failed → 전체 desktop/mobile GREEN 16 passed (2.6m) | [RED](evidence-v0.1.1/cache-regression/03-browser-red.log), [GREEN](evidence-v0.1.1/cache-regression/09-browser-green.log) |
+| `npm run lint` | PASS | [로그](evidence-v0.1.1/cache-regression/06-lint.log) |
+| `npm test` | 12 files / 65 passed, skip 0; Python 18개 계약 포함 | [로그](evidence-v0.1.1/cache-regression/07-full-test.log) |
+| `npm run build` | PASS, 101개 WAV·notice 검증 | [로그](evidence-v0.1.1/cache-regression/08-build.log) |
+| 실제 Chrome sandbox | Namespace·PID·Network·Seccomp-BPF 활성, `--no-sandbox` 없음 | [로그](evidence-v0.1.1/cache-regression/11-sandbox-green.log) |
+| query URL 전수 Chrome 해시·bytes·24kHz mono 디코드·duration·RMS·peak | 두 viewport 각각 101/101, 외부 요청 0·JS 예외 0 | [desktop](evidence-v0.1.1/cache-regression/artifacts/desktop-browser-audio-integrity.json), [mobile](evidence-v0.1.1/cache-regression/artifacts/mobile-browser-audio-integrity.json) |
+| 과거 evidence·자산·제품 버전 파일 보존 및 HEAD·diff 검사 | 254개 해시 동일, 과거 evidence 149개 포함 | [최종 무결성](evidence-v0.1.1/cache-regression/13-final-integrity.json) |
+
+전체 브라우저 명령은
+`env -u PLAYWRIGHT_NO_SANDBOX CHROME_PATH=/usr/bin/google-chrome DEBUG=pw:browser npm run test:browser`이다.
+실제 재생·재청취·10문제 완주·404 복구 후 정답·접근성 검증을 유지했다.
+101개 query URL 검사를 `tests/browser/audio.spec.ts`로 정규 suite에 편입했고,
+URL 판정 helper의 query 순서·가짜 WAV 접미사도 단위 테스트로 고정했다.
+런타임 외부 요청이나 manifest 조회는 추가하지 않았다.
+
+브라우저 스크린샷은 이제 `test-results/`를 사용하며 이번 결과는
+[새 artifacts 경로](evidence-v0.1.1/cache-regression/artifacts/)에 복사했다.
+과거 evidence와 기존 이 보고서 본문은 보존하고 이번 기록만 추가했다.
+보조 sandbox probe의 최초 라벨 판정 오류와 수정 결과도
+[원인·RED/GREEN·최종 결과 로그](evidence-v0.1.1/cache-regression/12-cache-regression-result.log)에 기록했다.
+
+README·ARCHITECTURE·DEPLOYMENT에 자산 버전 갱신 규칙과 7일 캐시 예시를 반영했다.
+이 변경의 검증 대상은 로컬 build이며 **Git commit/push/tag/merge와 서버 배포는 실행하지 않았다.**