Add read-only production runtime audit

2026-08-17 11:17:40 +07:00
parent 057d4ed9dc
commit a1de4715a4
106 changed files with 6869 additions and 1782 deletions
@@ -0,0 +1,117 @@
+# Cách chạy test và evaluation
+
+## Phân loại
+
+**Loại tài liệu:** How-to.
+
+**Reader job:** kiểm tra một thay đổi bằng các suite phù hợp và lưu bằng chứng
+không nói quá phạm vi test.
+
+## Điều kiện tiên quyết
+
+- Python 3.12 khuyến nghị.
+- Dependencies của `apps/ai-service` và `ingestion` đã cài.
+- Node 20, pnpm 9 cho web.
+- Không cần AWS cho unit test mặc định.
+
+## Bước 1 — Chạy AI-service checks
+
+```powershell
+Set-Location apps/ai-service
+ruff check .
+python -m pytest tests -q
+```
+
+`tests/conftest.py` mặc định đặt `EMBEDDING_PROVIDER=disabled` trước collection,
+nên unit suite không cần Qdrant. `test_live_datastores.py` tự skip trừ khi bật
+integration.
+
+## Bước 2 — Chạy ingestion suite
+
+```powershell
+Set-Location ../../ingestion
+python -m pytest tests -q
+```
+
+Suite này kiểm tra extraction, segmentation, chunking, validation, provider
+adapters và loader bằng doubles/in-memory store; nó không gọi Bedrock thật.
+
+## Bước 3 — Chạy web checks
+
+```powershell
+Set-Location ..
+pnpm --filter @duoc-thu/web lint
+pnpm --filter @duoc-thu/web build
+```
+
+Hiện chưa có frontend test runner. Lint/build xanh không chứng minh request
+timeout, citation grouping, middleware rate limit hoặc state UI không regression.
+
+## Bước 4 — Chạy integration datastore khi cần
+
+Khởi động PostgreSQL và Qdrant trước, rồi:
+
+```powershell
+Set-Location apps/ai-service
+$env:RUN_INTEGRATION='1'
+python -m pytest tests/test_live_datastores.py -q
+Remove-Item Env:RUN_INTEGRATION
+```
+
+Ghi rõ integration environment và version Qdrant/PostgreSQL trong test record.
+
+## Bước 5 — Chạy production/manual battery
+
+Battery gọi endpoint thật và có thể phát sinh Bedrock cost:
+
+```powershell
+Set-Location apps/ai-service
+python scripts/run_manual_battery.py `
+  --base-url http://localhost:3000 `
+  --target web `
+  --output output/manual-battery.jsonl
+```
+
+Script là HTTP recorder với invariant checks, không phải LLM judge. Review các
+failure và đối chiếu citation với PDF. Không ghi đè record cũ; tên output nên có
+timestamp/commit SHA.
+
+Để thử một subset, dùng `--start`, `--limit` hoặc `--ids` theo `--help`.
+
+## Bước 6 — Ghi kết quả đúng phạm vi
+
+Một test record tối thiểu gồm:
+
+```text
+commit SHA
+ngày/giờ
+command
+environment/provider mode
+passed / failed / skipped
+evaluation cases đã chạy
+artifact output
+known exclusions
+```
+
+Không cộng `skipped` vào `passed`. Không dùng unit suite để tuyên bố chất lượng
+lâm sàng hoặc live provider reliability.
+
+## Verify
+
+- AI-service ruff và pytest pass.
+- Ingestion pytest pass.
+- Web lint/build pass.
+- Integration/manual result được ghi riêng nếu đã chạy.
+- Không có cloud call ngoài ý muốn.
+
+## CI hiện tại
+
+`.github/workflows/ci.yml` chạy AI-service ruff/pytest, ingestion pytest và web
+lint/build trên push và pull request. `deploy.yml` vẫn trigger độc lập; CI đỏ
+không tự động chặn production deploy ở cấp workflow.
+
+## Liên quan
+
+- [Testing reference](../18-testing.md)
+- [RAG evaluation](../19-rag-evaluation.md)
+- [CI/CD](../22-ci-cd.md)