운영 안정화와 화면 회귀 검증을 반영
Some checks failed
API contract / OpenAPI type drift (push) Failing after 6m2s

This commit is contained in:
Yun Chan 2026-10-20 16:33:48 +09:00
parent 6e3123091a
commit aeddaa6972
69 changed files with 3178 additions and 424 deletions

View file

@ -55,6 +55,10 @@ powershell -NoProfile -ExecutionPolicy Bypass -File scripts\start-local-whisper-
- `-NoGateway`/`-NoWeb`를 쓰면 해당 컴포넌트의 stale 정리도 건너뛰고, API 정리는 지정한 `-ApiPort` listener만 대상으로 한다. public `8001`, Tailnet `8010`, local `8000`을 나눠 띄운 상태에서 API-only 재기동할 때 다른 포트를 건드리지 않는다.
- `dev-down.ps1`은 기본적으로 DB 컨테이너를 보존한다. 컨테이너도 멈추려면 `-Db`를 명시한다.
DB를 `dev-up.ps1`이 관리하는 경로에서는 API를 띄우기 전에 TCP `pg_isready`가 통과해야 하며, 새 DB와 기존 `vignette-dev-db` 재시작 모두 이 순서를 따른다. 기동 뒤에는 `/health`의 `db=true`를 확인한다. `-NoDb` 또는 Docker 부재에서의 `db=false` degraded는 허용된 개발 모드지만, DB readiness 성공을 뜻하지 않는다. 2026-10-19에는 managed 경로의 socket 0/TCP 2 → TCP 0 재초기화 재현과 strict API health를 수용했다. [closeout 보고서](../ops/backlog-closeout-2026-10-19.md)를 따른다.
returned-practice G4/G5 폐루프는 기존 dev DB를 재사용하지 않는다. `scripts/run-periodic-learner-e2e.py --execute`는 clean source snapshot의 전용 disposable engine/DB/API/Web를 loopback 포트에서만 올린다. 2026-10-19 receipt는 same-learner 실제 추천·브라우저 회기·SSE·review·G4/G5 `0→1→1`, returned desktop/mobile 4 passed와 route mock 0을 확인했고, 종료 뒤 container·volume·network·listener 잔여는 모두 0이었다. [receipt](../ops/backlog-closeout-2026-10-19.md#e2e-001-현행-경계)를 따른다.
DB나 배포 경로를 바꾸기 전에는 custom-format dump와 SHA-256 manifest를 먼저 만든다. 스크립트는
DB 내용을 stdout에 흘리지 않고 container 내부 임시 파일을 `pg_restore --list`로 검증한 뒤에만
로컬 백업을 원자 게시한다. 기존 container나 volume을 제거하는 경로는 없다.
@ -372,16 +376,16 @@ powershell -NoProfile -ExecutionPolicy Bypass -File scripts\install-health-sampl
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\install-health-sampler-task.ps1 -IntervalMinutes 5 -RunNow
```
쌓인 원시 헬스 샘플은 명시 기간을 준 maintenance 스크립트로 일별 rollup에 먼저 집계한 뒤 정리한다.
기본은 dry-run이며, 실제 삭제는 `--apply`를 붙였을 때만 수행한다. non-dev 환경에서는
`--allow-non-dev-apply`가 없으면 apply가 차단된다.
쌓인 원시 헬스 샘플은 `--rollup-days`를 반드시 지정한 maintenance 스크립트로 일별 rollup에 먼저 집계한 뒤 정리한다.
raw 보존 기본값은 90일, daily rollup 보존 기본값은 365일이다. 기본은 dry-run이며, 실제 삭제는 `--apply`를 붙였을 때만 수행한다. non-dev 환경에서는
`--allow-non-dev-apply`가 없으면 apply가 차단된다. 2026-10-19 로컬 격리 DB 수용은 migration 25를 그 proof에만 적용한 결과이며, 기존 dev/prod 적용이나 운영 스케줄 등록을 뜻하지 않는다.
```powershell
# 영향 범위 확인
C:\Users\encep\AppData\Local\Programs\Python\Python311\python.exe scripts\maintain-admin-health-events.py --rollup-days 2 --retention-days 30 --json
# 영향 범위 확인: --rollup-days 2는 이 예시의 집계 시점일 뿐 보존 기간이 아니다.
C:\Users\encep\AppData\Local\Programs\Python\Python311\python.exe scripts\maintain-admin-health-events.py --rollup-days 2 --retention-days 90 --rollup-retention-days 365 --json
# dev DB에서만 실제 적용
C:\Users\encep\AppData\Local\Programs\Python\Python311\python.exe scripts\maintain-admin-health-events.py --rollup-days 2 --retention-days 30 --apply --json
C:\Users\encep\AppData\Local\Programs\Python\Python311\python.exe scripts\maintain-admin-health-events.py --rollup-days 2 --retention-days 90 --rollup-retention-days 365 --apply --json
```
---
@ -507,6 +511,8 @@ Invoke-RestMethod -Method Post `
현재 sync 경로는 active `kb.document`의 hash/version을 먼저 읽고, hash가 바뀐 pack만 다음 document version으로 색인한다.
임베딩 모델이 없으면 `degraded=true`로 BM25-only 색인이 되지만, 라이브 코칭 기본 로컬 근거는 계속 동작한다.
2026-10-19 로컬 교정에서는 workbook data C/D 다섯 항목의 외부 사용을 명시적으로 막고, 관리자 sync 두 경로가 RLS role/user id를 함께 전달하도록 맞췄다. 검증 당시 별도 API `8014`와 현재 기본 `.env`의 실DB에서 unauthenticated `401`, learner `403`, admin `202`, 후속 retrieval `200`을 확인했고, 같은 admin sync를 두 번 실행해 매번 `sources=7`, `items=7`, `chunks=0`, `skipped_unchanged=7`, `embedded=false`, `degraded=false`를 확인했다. 이후 `8000`은 최종 소스로 재시작해 `db=true`·`engine=true`지만 Jev `live_verified=false`는 유지한다. 모두 로컬 증거이며 dev/prod 또는 운영 배포를 갱신하지 않는다.
API 서버 없이 DB에 직접 비교/적용하려면 저장소 루트에서 runner를 쓴다. 기본은 DB-backed dry-run이라 write하지 않고, `--apply`에서만 `kb.source` upsert와 `kb.document/kb.chunk` 색인을 수행한다.
```powershell