Stop mislabeling the Compose box as production in read-only audits

docs/operations.md

@@ -1,32 +1,67 @@
 # Vận hành, triển khai và xử lý sự cố
 
 > Loại chính: How-to  
-> Phạm vi: EC2 + Docker Compose hiện hành
+> Phạm vi: k3s + ArgoCD (production kể từ cutover 2026-08-17)
+
+Production (`realvuxbaro.me`) chạy trên k3s, quản lý bởi ArgoCD Application
+**`medical-chatbot-app`** (ai-service + web + observability) và
+**`medical-chatbot-data`** (PostgreSQL + Qdrant, tách release để prune/self-heal
+phía app không bao giờ đụng vào dữ liệu). Cả hai đặt `syncPolicy.automated` với
+`selfHeal` + `prune` — **mọi merge vào `master` áp thẳng vào production, không
+có cổng duyệt thủ công.** EC2 Docker Compose (`52.0.158.61`) không còn nhận
+deploy tự động; xem `coordination/CLAUDE_PLAN_CICD_SAFETY_2026-08-18.md` cho
+lý do và tình trạng hiện tại của máy đó.
 
 ## Deploy
 
-Trước deploy, ghi commit SHA, yêu cầu CI AI/ingestion/web xanh, kiểm tra secret và
-Qdrant manifest tương thích, đồng thời đánh giá migration. Chạy `deploy.yml` theo
-path/branch filter hoặc manual dispatch và theo dõi đến khi reconcile xong.
+Hai loại thay đổi đi hai đường khác nhau:
 
-Sau deploy:
+**Thay đổi code app** (`apps/ai-service/**`, `apps/web/**`, `packages/**`,
+`ingestion/data/verified/drug_entities.json`) — merge vào `master` kích hoạt
+`build-practice-images.yml`: build + push image GHCR gắn tag theo commit SHA,
+sau đó `.github/scripts/sync_practice_argocd.py` ghi tag mới vào Application
+`medical-chatbot-app` và gọi sync. Workflow tự xác nhận
+`readytochat.realvuxbaro.me` đã lên bản mới trước khi báo thành công.
+`ci.yml` (ruff/pytest/lint/build) chạy độc lập trên cùng push — **CI đỏ không
+tự động chặn deploy**, hai workflow không phụ thuộc nhau.
 
-1. xác nhận SHA/image đang chạy đúng bản;
-2. kiểm tra `/health` và `/ready`;
-3. gửi smoke case qua web, gồm answerable có citation và abstain;
-4. quan sát error rate, latency, provider failure và decision distribution;
-5. ghi lại thời điểm, SHA và kết quả.
+**Thay đổi chart/config** (`infra/helm/**`) — `helm-chart.yml` lint + render +
+assert bất biến (Qwen, rerank, TLS, `refute volumeClaimTemplates`...) trên PR.
+Merge xong, ArgoCD tự phát hiện và sync — không qua CI nào chạy trên production
+thật, review ở PR là cổng chắn duy nhất.
 
-CI và deploy độc lập về kỹ thuật; trạng thái CI đỏ không tự động chặn deploy.
+Sau deploy (cả hai loại):
+
+1. xác nhận Application `Synced`/`Healthy` và image tag/chart revision đúng;
+2. gửi smoke case qua web, gồm answerable có citation và abstain;
+3. quan sát error rate, latency, provider failure và decision distribution;
+4. ghi lại thời điểm, SHA/revision và kết quả.
 
 ## Rollback
 
-Workflow `rollback.yml` nhận `target_sha`. Chọn SHA từng deploy thành công và còn
-tương thích với database/corpus. Sau rollback phải xác nhận SHA, health/readiness,
-smoke cases và metric qua đủ cửa sổ để thấy lỗi ban đầu biến mất.
+Không có workflow rollback một-cú-bấm cho k3s hiện tại — đây là phần còn thiếu,
+xem `coordination/CLAUDE_PLAN_CICD_SAFETY_2026-08-18.md` mục PR C.
 
-Rollback code không tự rollback Qdrant corpus hoặc database migration. Với corpus,
-dùng snapshot/migration riêng; không rollback dữ liệu phá huỷ khi chưa có backup.
+**Image bị lỗi (phổ biến nhất):** gọi trực tiếp ArgoCD API bằng logic của
+`sync_practice_argocd.py` nhưng với `IMAGE_TAG=<sha tốt lần trước>` — lấy SHA
+đó từ lần chạy `build-practice-images.yml` thành công gần nhất trước đó
+(`gh run list --workflow=build-practice-images.yml`). Không có nút bấm sẵn cho
+việc này; phải chạy script hoặc gọi API thủ công.
+
+**Chart/config bị lỗi:** `git revert` commit gây lỗi trên `master` qua PR bình
+thường; ArgoCD `selfHeal` tự áp bản revert. Muốn ngay lập tức thay vì chờ chu kỳ
+poll, sync thủ công qua ArgoCD UI/CLI.
+
+**Sự cố nặng ở tầng cluster** (k3s tự nó hỏng, không phải lỗi ở app): trong lúc
+Compose EC2 (`52.0.158.61`) còn tồn tại và chưa bị tắt, đường lui cuối cùng là
+trỏ A record `realvuxbaro.me` về IP đó (TTL 60s) — **chỉ đúng khi Compose đang
+chạy bản tương thích với corpus/schema hiện tại**, không phải đường lui mặc
+định. Một khi Compose bị dừng/xoá theo quyết định giữ 1 EC2, đường lui này
+không còn.
+
+Không có cơ chế nào ở trên tự rollback Qdrant corpus hay database migration.
+Với corpus, dùng snapshot/migration riêng; không rollback dữ liệu phá huỷ khi
+chưa có backup.
 
 ## Theo dấu request