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,83 @@
+# Catalog tài liệu dự án
+
+## Phân loại
+
+**Loại tài liệu:** Reference.
+
+**Reader job:** tìm nhanh tài liệu đúng cho một vai trò hoặc câu hỏi.
+
+## Theo nhu cầu
+
+| Tôi muốn… | Bắt đầu tại |
+|---|---|
+| Hiểu toàn bộ PDF → chatbot | [`pipeline-tu-pdf-den-chatbot-production.md`](../pipeline-tu-pdf-den-chatbot-production.md) |
+| Chạy một query và theo citation | [`tutorials/first-grounded-query.md`](../tutorials/first-grounded-query.md) |
+| Setup môi trường local | [`23-local-development.md`](../23-local-development.md) |
+| Rebuild và publish corpus | [`how-to/rebuild-and-publish-corpus.md`](../how-to/rebuild-and-publish-corpus.md) |
+| Chạy test/eval | [`how-to/run-tests-and-evals.md`](../how-to/run-tests-and-evals.md) |
+| Deploy hoặc rollback | [`how-to/deploy-and-rollback.md`](../how-to/deploy-and-rollback.md) |
+| Điều tra một request | [`how-to/trace-a-request.md`](../how-to/trace-a-request.md) |
+| Tra API | [`12-api-architecture.md`](../12-api-architecture.md) |
+| Tra biến môi trường | [`15-configuration.md`](../15-configuration.md) |
+| Tra reason code | [`29-glossary.md`](../29-glossary.md) |
+| Xử lý sự cố | [`25-troubleshooting.md`](../25-troubleshooting.md) |
+| Hiểu vì sao không dùng dense-only | [`explanation/why-structured-rag.md`](../explanation/why-structured-rag.md) |
+| Xem giới hạn thật | [`26-known-limitations.md`](../26-known-limitations.md) |
+
+## Theo vai trò
+
+| Vai trò | Lộ trình đọc |
+|---|---|
+| Contributor mới | Tutorial → `01` repository → `23` local → `18` testing |
+| AI/RAG engineer | `08` understanding → `09` retrieval → `10` orchestration → `11` grounding → `19` eval |
+| Ingestion engineer | `04` ingestion → `05` parsing → `06` chunking → `07` indexing |
+| Backend engineer | `12` API → `14` stores → `15` config → `17` observability |
+| Frontend engineer | `13` frontend → `12` API → `16` security |
+| Operator/SRE | Deploy how-to → trace how-to → `24` operations → `25` troubleshooting |
+| Reviewer/mentor | Canonical pipeline → showcase plan → `26` limitations → `27` debt |
+
+## Bộ tài liệu `00–29`
+
+| File | Loại chính | Nội dung |
+|---|---|---|
+| `00` | Explanation | Tổng quan sản phẩm và ranh giới |
+| `01` | Reference | Cấu trúc repository |
+| `02` | Explanation | Kiến trúc runtime |
+| `03` | Explanation | Data flow offline và online |
+| `04` | Explanation | Ingestion pipeline |
+| `05` | Explanation | PDF parsing |
+| `06` | Reference | Document model và chunk schema |
+| `07` | Reference | Qdrant, manifest và storage |
+| `08` | Explanation | Query understanding |
+| `09` | Explanation | Retrieval routes |
+| `10` | Explanation | RAG orchestration |
+| `11` | Explanation | Generation và grounding |
+| `12` | Reference | API contracts |
+| `13` | Explanation | Frontend architecture |
+| `14` | Reference | Datastores |
+| `15` | Reference | Configuration |
+| `16` | Explanation | Security model và gaps |
+| `17` | Reference | Metrics, traces và correlation |
+| `18` | Reference | Test inventory và commands |
+| `19` | Explanation | Evaluation assets và gaps |
+| `20` | Explanation | Deployment topology |
+| `21` | Explanation | Kubernetes/ArgoCD target state |
+| `22` | Explanation | CI/CD design và consequences |
+| `23` | How-to | Local development |
+| `24` | How-to | Production operations |
+| `25` | How-to | Troubleshooting |
+| `26` | Reference | Known limitations |
+| `27` | Explanation | Technical debt |
+| `28` | Explanation | Roadmap derived from code |
+| `29` | Reference | Glossary và reason codes |
+
+## Nguồn sự thật
+
+Thứ tự ưu tiên khi có mâu thuẫn:
+
+1. Runtime code.
+2. Runtime configuration và workflow.
+3. Tests.
+4. Migrations và deployment manifests.
+5. Tài liệu hiện hành.
+6. ADR, progress log và handoff lịch sử.