49 lines
2.2 KiB
Markdown
49 lines
2.2 KiB
Markdown
# Chính sách và nguồn kiểm chứng tài liệu
|
|
|
|
> Loại chính: Governance
|
|
> Đối tượng: người viết và duyệt tài liệu
|
|
|
|
## Nguồn sự thật
|
|
|
|
Khi thông tin mâu thuẫn, dùng thứ tự:
|
|
|
|
1. hành vi được test tự động xác nhận;
|
|
2. code và migration đang thực thi;
|
|
3. cấu hình deploy/workflow đang hoạt động;
|
|
4. tài liệu chuẩn trong `docs/`;
|
|
5. README cục bộ và `docs-legacy/`;
|
|
6. ghi chú, kế hoạch và slide.
|
|
|
|
## Nguồn kiểm chứng theo chủ đề
|
|
|
|
| Chủ đề | Nguồn chính |
|
|
|---|---|
|
|
| HTTP API | `apps/ai-service/main.py`, `api/routes.py`, `api/dto.py` |
|
|
| Runtime wiring | `bootstrap.py`, `config.py` |
|
|
| RAG/guardrail | `rag/agent.py`, `rag/service.py`, `rag/answer.py` |
|
|
| Retrieval | `rag/routing.py`, `rag/sections.py`, `adapters/qdrant.py` |
|
|
| Persistence | `adapters/postgres.py`, `migrations/*.sql` |
|
|
| Web/BFF | `apps/web/app/api/chat/route.ts`, shared types |
|
|
| Ingestion | `ingestion/ingestion/cli.py`, chunk và load modules |
|
|
| Infrastructure | `infra/docker`, production Compose, Caddy, Helm/ArgoCD |
|
|
| CI/CD | `.github/workflows/*.yml` |
|
|
| Hành vi | test suites và `evals/production_manual_60.jsonl` |
|
|
|
|
## Quy tắc cập nhật
|
|
|
|
- Không biến kế hoạch thành tính năng hoàn tất.
|
|
- Phân biệt “có code”, “được test”, “đã deploy” và “đang phục vụ traffic”.
|
|
- Mỗi thay đổi interface phải cập nhật file chuẩn liên quan trong cùng pull request.
|
|
- Lệnh trong tài liệu phải được chạy thử hoặc đánh dấu rõ phụ thuộc cloud/hạ tầng.
|
|
- Không ghi số test, corpus hoặc benchmark không có ngày/model/hash.
|
|
- Mỗi file giữ một công việc đọc chính dù có section hỗ trợ loại Diátaxis khác.
|
|
- Kiểm tra toàn bộ relative links sau khi đổi tên hoặc di chuyển.
|
|
|
|
## Vòng đời
|
|
|
|
`docs/` là nguồn tài liệu chuẩn. `docs-legacy/` chỉ để tra lịch sử và raw notes;
|
|
không được dùng để kết luận hành vi hiện tại nếu chưa đối chiếu code. Tài liệu hết
|
|
hiệu lực phải được xoá hoặc ghi deprecated kèm link thay thế; không để hai file cùng
|
|
tự nhận là canonical.
|
|
|