현재 작업 전체 반영

docs/guides/testing.md

@@ -15,8 +15,9 @@ Vignette 저장소의 모든 검증 수단(백엔드 단위 테스트, 웹 타
 
 | 검증 | 작업 디렉터리 | 명령 | DB | API(8000) | 웹(5173) | 엔진GW(9099) | 브라우저 | 현재 통과 |
 |---|---|---|---|---|---|---|---|---|
-| 백엔드 단위 테스트 | `apps/api` | `python -m pytest app/ -q` | 불필요 | 불필요 | 불필요 | 불필요 | 불필요 | 98 pass |
+| 백엔드 단위 테스트 | `apps/api` | `python -m pytest app/ -q` | 불필요 | 불필요 | 불필요 | 불필요 | 불필요 | 113 pass |
 | 엔진 게이트웨이 테스트 | `apps/api` | `python -m pytest engine_gateway/ -q` | 불필요 | 불필요 | 불필요 | 불필요 | 불필요 | 7 pass |
+| API 타입 생성 체크 | `apps/web` | `npm run check:api-types` | 불필요 | 불필요 | 불필요 | 불필요 | 불필요 | pass |
 | 웹 타입체크 | `apps/web` | `npm run typecheck` | 불필요 | 불필요 | 불필요 | 불필요 | 불필요 | — |
 | 웹 빌드 | `apps/web` | `npm run build` | 불필요 | 불필요 | 불필요 | 불필요 | 불필요 | — |
 | Playwright E2E(전체) | `apps/web` | `npm run e2e` | **필요(+시드)** | **필요** | 자동기동 | 일부만 | **필요** | 102 tests / 17 files |
@@ -41,14 +42,14 @@ Vignette 저장소의 모든 검증 수단(백엔드 단위 테스트, 웹 타
 
 ```sh
 # apps/api
-python -m pytest app/ -q              # 앱 단위 테스트 (현재 98 pass)
+python -m pytest app/ -q              # 앱 단위 테스트 (현재 113 pass)
 python -m pytest engine_gateway/ -q   # 게이트웨이 단위 테스트 (현재 7 pass)
 ```
 
 수집만 빠르게 확인하려면:
 
 ```sh
-python -m pytest app/ --collect-only -q            # → "98 tests collected"
+python -m pytest app/ --collect-only -q            # → "113 tests collected"
 python -m pytest engine_gateway/ --collect-only -q # → "7 tests collected"
 ```
 
@@ -84,6 +85,8 @@ python -m pytest engine_gateway/ --collect-only -q # → "7 tests collected"
 
 - 작업 디렉터리: `apps/web`
 - `package.json` 스크립트(실측):
+  - `generate:api-types` → FastAPI OpenAPI export 후 `src/lib/api.gen.ts` 재생성
+  - `check:api-types` → FastAPI OpenAPI export 후 생성 타입 stale 여부 확인
   - `typecheck` → `tsc -b`
   - `lint` → `tsc -b` (현재 lint는 타입체크와 동일)
   - `build` → `tsc -b && vite build`
@@ -96,10 +99,18 @@ python -m pytest engine_gateway/ --collect-only -q # → "7 tests collected"
 ```sh
 # apps/web
 npm install        # 최초 1회 (devDependencies: typescript, vite, @playwright/test 등)
+npm run check:api-types  # FastAPI OpenAPI ↔ src/lib/api.gen.ts 동기화 확인
 npm run typecheck  # tsc -b — 타입 오류 0 확인
 npm run build      # tsc -b && vite build — 프로덕션 번들 생성까지 확인
 ```
 
+API DTO를 바꿨다면 먼저 생성 산출물을 갱신한다.
+
+```sh
+# apps/web
+npm run generate:api-types
+```
+
 ---
 
 ## 3. Playwright E2E (풀스택)
@@ -263,7 +274,7 @@ cd apps/web && npm run e2e
 검증 결과는 **실제로 실행해 통과한 명령**만 근거로 보고한다.
 
 - "통과했다/완료다"라고 말하려면 그 자리에서 **실행 가능한 검증 명령과 관측된 결과(통과 개수)**를
-  함께 제시한다. 예: `python -m pytest app/ -q` → `98 passed`.
+  함께 제시한다. 예: `python -m pytest app/ -q` → `100 passed`.
 - 의존을 갖춘 검증을 우회하지 않는다. E2E를 DB/API 없이 돌려 놓고 "그린"이라고 보고하지
   않는다. 풀스택을 못 띄웠으면 **"E2E 미실행"**이라고 명시한다.
 - 인메모리 degraded 기동(`db:false`)에서 페르소나 헬퍼가 실패하는 것은 환경 문제이지 코드가