@trungtamcongnghedigital/vsaf 1.0.0

package/skills/NTAPP/.agent/skills/NTAPP-business-overview-confluence/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: NTAPP-business-overview-confluence
+description: "Đóng vai Business Analyst sinh & XUẤT BẢN tài liệu Tổng quan nghiệp vụ lên Confluence theo TEMPLATE ĐỘNG (fetch template thật rồi bám khung mục), sơ đồ vẽ bằng draw.io. Nguồn: architecture_design (HLD) → project_wbs → PRD/Epics (+ code fallback); dựng Mục đích, Mô hình tổng quan, Quy trình nghiệp vụ, ERD, Trạng thái, Phân rã chức năng; dựng ERD **field-level nhóm theo datastore** (hợp nhất §11 techspec Stage 3 qua sub-agent ERD, từ điển field 2 tầng); Confluence qua MCP (đọc/tạo/body) + REST/PAT cho attachment sơ đồ. Dùng khi người dùng nói 'tạo/cập nhật tài liệu tổng quan nghiệp vụ lên Confluence', 'business overview Confluence theo template', 'vẽ ERD/quy trình/phân rã chức năng lên Confluence', 'đồng bộ tài liệu nghiệp vụ vào wiki'."
+---
+
+# HƯỚNG DẪN SKILL: BA — BUSINESS OVERVIEW → CONFLUENCE
+
+**Version:** 2.1.0
+**Mục tiêu:** Từ tài liệu thiết kế một dự án, dựng **Tài liệu Tổng quan nghiệp vụ** bám **template Confluence động**,
+có **sơ đồ draw.io render được**, rồi **xuất bản** (tạo mới / cập nhật toàn bộ) đúng trang đích tra từ **bảng tổng hợp tài liệu hệ thống**.
+
+> **Nguyên tắc no-silent-defaults:** không bịa số liệu/tên tổ chức/đối tác. Suy ra từ tài liệu → ghi kèm nguồn. Không chắc → `[Cần xác nhận]`.
+> **Portability:** KHÔNG hardcode pageId / space / credential trong logic skill. Mọi giá trị đến từ tham số hoặc config (BƯỚC 0). Cùng skill chạy dự án khác chỉ đổi config.
+> **Kết nối Confluence:** đọc/tạo/body qua **MCP**; **attachment sơ đồ + body-có-sơ-đồ qua REST** (`scripts/confluence-publish.ps1`, vì MCP không upload attachment được trên Server này). Chi tiết: [references/confluence-publish.md](references/confluence-publish.md).
+> **Runbook chi tiết** (HITL gates + changelog continuity + **log lịch sử tác động**): [workflow.md](workflow.md). QUY TRÌNH 7 bước dưới là bản đồ tổng quát; khi EXECUTE bám workflow.md.
+
+---
+
+## THAM SỐ & CONFIG (BƯỚC 0 — resolve lúc runtime)
+
+Lấy theo thứ tự: (a) tham số người dùng truyền → (b) config dự án (`docs/mcp/confluence-connections.md` / `.bo-confluence.yaml` nếu có) → (c) hỏi tương tác 1 lượt. Giá trị **đã biết** cho project reconciliation điền sẵn làm default:
+
+| Khóa | Ý nghĩa | Default đã biết |
+|---|---|---|
+| `mcp_server` | Server MCP đọc/ghi trang đích | `mcp__atlassian` (host `.35`) |
+| `confluence_base` | URL host chứa trang đích | `http://10.254.136.35:8090` |
+| `template_page_id` | Trang **template** Tổng quan nghiệp vụ | `200745079` (space `TDOV`) |
+| `target_space` | Space đích (khi tạo trang mới) | `TDOV` |
+| `summary_table_page_id` | Trang chứa **bảng tổng hợp / index** tài liệu (có link + role BA) | *(resolve — hỏi/tra, đừng bịa)* |
+| `ba_row_label` | Nhãn dòng cần khớp trong bảng tổng hợp | mặc định chứa `"Tổng quan"` + role `BA` |
+| `auth` (REST) | Cho attachment/publish | `.confluence-auth` (PAT) ở repo root — xem confluence-publish.md §1 |
+
+Bảng tổng hợp có thể ở host khác trang đích (link trong bảng trỏ instance nào thì cập nhật trang ở đó). MCP `.32` hay chết token (403) → đọc fallback bằng `scripts/confluence-get.ps1` (Basic).
+
+---
+
+## QUY TRÌNH 7 BƯỚC
+
+### BƯỚC 1 — Thu thập nguồn đầu vào (im lặng)
+Đọc theo thứ tự ưu tiên, dừng khi đủ tín hiệu:
+1. `**/architecture_design.md`** (HLD) — C4 context/container, ERD (§ Global Data Model), security zoning, NFR. Nguồn chính cho **Mô hình tổng quan** + **ERD**.
+2. `**/project_wbs.md`** — **xương sống Phân rã chức năng toàn hệ** (§6 bám cái này). Mọi loại ID: features/screens/widgets/contracts.
+3. **PRD & Epics** (`**/Stage_1_Discovery/prd.md`, `epics.md`) — bối cảnh, vấn đề, mục tiêu kinh doanh (phần code/thiết kế không nói).
+4. (fallback) **Source code** — suy actor/flow/ERD khi tài liệu thiếu. Cách trích: [references/extract-from-code.md](references/extract-from-code.md).
+5. **Stage 3 techspec §11** (`NTAPP-output/Stage_3_Specs/techspec/*_techspec.md`) — nguồn field-level cho ERD; hợp nhất qua Bước 1b (sub-agent `agent_erd_data_architect`). Loại `integration-*` + `observability`.
+6. (tùy chọn, chỉ khi tách phần xây mới) `**/Stage_4_Design/**/feature_design_parts/*/`** — mỗi thư mục con = 1 feature xây mới thật.
+
+> **Phân biệt phạm vi:** WBS TRỘN brownfield AS-IS + phần xây mới. Xem [references/scope-brownfield-vs-newbuild.md](references/scope-brownfield-vs-newbuild.md).
+> **Bước 1b (hợp nhất ERD field-level):** sau khi thu thập nguồn, chạy sub-agent `agent_erd_data_architect` hợp nhất §11 kỹ thuật của tất cả techspec thành từ điển field 2 tầng theo datastore. Chi tiết: [workflow.md](workflow.md) §1b.
+
+### BƯỚC 2 — Hỏi phạm vi (HITL, 1 lượt)
+Hỏi người dùng chọn (mặc định = đầu tiên):
+- **Toàn hệ theo WBS** — bức tranh đầy đủ, cây §6 dựng từ `project_wbs.md`, không phân lớp AS-IS/mới.
+- **Toàn hệ 2 lớp** — thêm tách nhánh A (brownfield, xám) + B (xây mới, màu, từ `feature_design_parts`).
+- **Chỉ phần xây mới** — chỉ feature trong `feature_design_parts`.
+Kèm hỏi nhanh bối cảnh/mục tiêu kinh doanh còn thiếu (nếu PRD không đủ).
+
+### BƯỚC 3 — Fetch template ĐỘNG + lấy bộ mục
+- MCP `confluence_get_page(page_id=template_page_id, convert_to_markdown=false)` → storage XHTML thô. (MCP host chết → `scripts/confluence-get.ps1`.)
+- **Parse các heading `<h1>`** làm bộ mục chuẩn (số lượng/tiêu đề bám template, KHÔNG cứng hoá). Đọc mô tả trong mỗi mục để biết yêu cầu trình bày (vd "bố cục theo vùng", "swimlane", "cây building-block 3 loại", cột bảng).
+- ⚠️ **Template chứa nội dung ví dụ dự án khác** (vd VOUCHER_*, App VTP). Coi template là **khung mục + hướng dẫn**; **thay toàn bộ data ví dụ** bằng dữ liệu reconciliation thật. Giữ lại cấu trúc: bảng Đơn vị phê duyệt (task-list), macro `toc`, bảng ghi nhận thay đổi.
+- Quy ước mặc định nếu template không nói rõ: [references/style-conventions.md](references/style-conventions.md).
+
+### BƯỚC 4 — Dò plugin sơ đồ → xác nhận draw.io render
+- MCP `confluence_search(query='macro="drawio"')` + đọc `body.view` **vài** trang thật dùng macro: có `unknown-macro?name=drawio` → plugin chưa cài. **Rỗng ≠ chưa cài** (chỉ nghĩa chưa ai dùng) → probe chủ động: tạo 1 trang nháp có macro, đọc `body.view`, rồi xoá.
+- Host `.35` đã biết **có draw.io** (SEIBERT) → dùng draw.io. Chi tiết render + `revision`: [references/diagram-drawio.md](references/diagram-drawio.md).
+
+### BƯỚC 5 — Sinh nội dung từng mục (storage format)
+Bám thứ tự mục template. **Văn phong nghiệp vụ chuyên nghiệp — KHÔNG văn nói** ("Dễ hiểu", "Tóm lại", "bóc tách", "làm được gì", "chạy ngầm"…) và **KHÔNG in khối meta** nói về cách làm tài liệu (hộp phạm vi/tiêu chí chọn nội dung · bảng giải nghĩa loại lá · hộp đối chiếu số lượng · hộp "Điểm cần xác nhận" gom cụm). Bảng đối chiếu từ ngữ + blocklist đầy đủ: [references/style-conventions.md](references/style-conventions.md) **§0 — đọc TRƯỚC khi viết**. Quy ước từng mục:
+- **Mô hình tổng quan:** bố cục **vùng trái→phải** (Nguồn dữ liệu · Lõi + bước xử lý/kho dữ liệu · Tích hợp · FE · Actor); actor người que; hệ ngoài xám nét đứt; **ít mũi tên** (chiều in→xử lý→out); bảng `STT | Tên thành phần | Mô tả`.
+- **Quy trình nghiệp vụ:** tùy chọn **1 câu** nêu phạm vi + đầu vào/đầu ra (**không dùng hộp tip**) + sơ đồ **swimlane/3 cột** + bảng bước **5 cột** `STT | Bước | Vai trò thực hiện | Mô tả·Điều kiện·Dữ liệu | Bước tiếp theo`.
+- **ERD:** **2 tầng** — Tầng A: sơ đồ cross-store rút gọn (entity thu gọn + FK bắc cầu giữa các datastore) + bảng `Bảng nguồn | Khoá | Bảng đích | Store↔Store | Nguồn`; Tầng B: mỗi cụm datastore 1 sơ đồ bảng lưới 1:N nội cụm + bảng tổng hợp `STT | Tên bảng | Ý nghĩa | Nguồn` + **expand lồng** từng bảng ra từ điển field 2 tầng (nghiệp vụ + kỹ thuật); tên bảng/trường = **tên DB thật**; nguồn hợp nhất từ Bước 1b, xem [references/erd-consolidation.md](references/erd-consolidation.md).
+- **Trạng thái:** state diagram cho thực thể có vòng đời; xếp `states` theo thứ tự vòng đời thuận (trạng thái kết thúc bất thường để cuối) để phần lớn chuyển tiếp là liền kề.
+- **Phân rã chức năng:** cây building-block **3 loại** (Frontend · Backend-kết nối · Backend-xử lý tự động); full-system → 2 lớp; **ĐÚNG 1 bảng** khớp **từng lá** `STT | Kênh thực hiện | Đối tượng sử dụng | Chức năng | Ý nghĩa` — không bảng giải nghĩa loại lá, không hộp đối chiếu số lượng. Quá ~40 lá / 6 cụm → tách nhiều sơ đồ theo cụm.
+
+Storage XHTML: **escape `& < > "`** ngoài CDATA; **checkbox = `ac:task-list`** (không unicode ☑); **ngày = date macro**; bảng lồng OK; **HTML macro tắt** trên `.35`. Xem [references/confluence-publish.md](references/confluence-publish.md) §2–§4.
+- **Changelog continuity (UPDATE):** đọc bản live lấy version + bảng "Ghi nhận thay đổi" cũ → **giữ dòng cũ**, thêm 1 dòng mới trên đầu, bump version doc +1. Lần đầu → `v1`. Chi tiết: [workflow.md](workflow.md) §4.
+
+### BƯỚC 6 — Sinh sơ đồ + xuất bản
+1. Xác định trang đích: tra `summary_table_page_id` tìm dòng khớp `ba_row_label` (role BA / "Tổng quan nghiệp vụ") → lấy link.
+   - **Chưa có link** → MCP `confluence_create_page(content_format="storage")` tạo skeleton trong `target_space` → lấy `pageId`; sau publish xong cập nhật ô link trong bảng.
+   - **Đã có** → cập nhật **toàn bộ** trang đó (Confluence giữ lịch sử version).
+2. Sinh mxfile từng sơ đồ bằng `scripts/drawio_lib.py` → ghi file (tên = `diagramName`, không đuôi).
+2b. **Soi sơ đồ:** `python scripts/preview.py <tất cả mxfile>` → mở PNG xem từng cái + đọc cảnh báo lint. Còn cảnh báo (mũi tên chồng/xuyên hộp, trang quá rộng) → **sửa data/tách sơ đồ rồi sinh lại**, không publish hình lỗi.
+3. Ghi storage ra `*.storage.xhtml` + `confluence-publish.manifest.json` (pageId, title, storageFile, attachments: mxfile `label drawio` + PNG nếu có).
+4. **Publish** `powershell -File scripts/confluence-publish.ps1 -Manifest <manifest.json>` → upload attachment + **auto-sync `revision`==attachment version** + PUT body version+1 (atomic).
+   - Body-only, KHÔNG sơ đồ (vd cập nhật ô link bảng tổng hợp) → có thể đi MCP `confluence_update_page(content_format="storage")`.
+
+### BƯỚC 7 — Write-back, LOG & báo cáo
+- **Verify:** MCP `get_page` / `get_attachments`: **không còn `unknown-macro`**; **version attachment mxfile == `revision` macro** (điều kiện sống còn — không 404, không kẹt render cũ); số dòng bảng/sơ đồ khớp.
+- **Write-back:** cập nhật ô link trong bảng index (dòng role BA) trỏ tới URL trang — body-only qua MCP.
+- **Log lịch sử tác động:** ghi audit `{bo_dir}/.confluence-sync/{timestamp}.log` + append `{bo_dir}/business-overview-publish-history.md` (`Ngày | Action | Phạm vi | pageId | Version | URL | Người`). Chi tiết: [workflow.md](workflow.md) §10.
+- **Báo:** URL trang, version mới, danh sách sơ đồ + attachment, các điểm `[Cần xác nhận]`, đường dẫn log. Nhắc user hard-refresh (Ctrl+F5).
+
+---
+
+## SCRIPTS KÈM THEO (portable — nhận tham số, không hardcode)
+- [scripts/drawio_lib.py](scripts/drawio_lib.py) — sinh mxfile: `overview_zones` (mô hình tổng quan bố cục vùng) · `process_3col` (quy trình) · **`erd_graph`** (ERD mức bảng — phân tầng + định tuyến qua kênh/máng, dùng cho sơ đồ quan hệ) · `erd` (lưới field-level) · `state_diagram` · `breakdown_tree`.
+- [scripts/preview.py](scripts/preview.py) — **render mxfile ra PNG để SOI + lint hình học** (hộp đè hộp · cạnh xuyên hộp · 2 cạnh chồng trục · tràn khổ · trang quá rộng). **BẮT BUỘC chạy sau khi sinh mxfile, trước preview HITL** — không có bước này thì không ai nhìn thấy sơ đồ trước khi nó lên wiki. `python scripts/preview.py <mxfile...> [-o OUT] [--strict]`; exit 2 = thiếu Chrome, chỉ mất ảnh, KHÔNG chặn publish.
+- [scripts/confluence-publish.ps1](scripts/confluence-publish.ps1) — upload attachment (REST multipart) + PUT body version+1 + **auto-sync drawio `revision`**; đọc PAT từ `.confluence-auth` (walk-up). Agent tự chạy, user không gõ lệnh.
+- [scripts/confluence-get.ps1](scripts/confluence-get.ps1) — đọc trang qua REST Basic (fallback khi MCP host chết / cần đọc host khác).
+
+## RUNBOOK & REFERENCES
+- [workflow.md](workflow.md) — **runbook thực thi** 10 bước: INIT+pre-flight · sources · scope HITL · template động · gen+changelog continuity · review · locate · preview HITL · execute · write-back+**LOG lịch sử**. Sơ đồ quyết định cuối file.
+- [references/confluence-publish.md](references/confluence-publish.md) — cơ chế MCP+REST, auth, storage format, task-list checkbox, date macro, escaping, draw.io macro + revision auto-sync, quy trình publish an toàn.
+- [references/diagram-drawio.md](references/diagram-drawio.md) — cấu trúc mxfile, render trên `.35`, `revision`==version, edge routing.
+- [references/style-conventions.md](references/style-conventions.md) — quy ước trình bày từng mục (canh theo template thật).
+- [references/scope-brownfield-vs-newbuild.md](references/scope-brownfield-vs-newbuild.md) — nguồn arch→WBS→PRD, phân biệt phạm vi toàn hệ vs xây mới.
+- [references/extract-from-code.md](references/extract-from-code.md) — bảng trích actor/ERD/flow/state từ source code (fallback).
+- [agents/agent_erd_data_architect.md](agents/agent_erd_data_architect.md) — sub-agent hợp nhất ERD field-level từ Stage 3 §11.
+- [references/erd-consolidation.md](references/erd-consolidation.md) — quy tắc nhóm store, 2 tầng, cross-store bridge, no-fabrication.

package/skills/NTAPP/.agent/skills/NTAPP-business-overview-confluence/agents/agent_erd_data_architect.md

@@ -0,0 +1,30 @@
+# Agent — ERD Data Architect
+
+**Role:** Data Architect. Hợp nhất mô hình dữ liệu toàn hệ từ `§11` các techspec Stage 3 thành 1 artifact ERD nhóm theo datastore, trace lại nguồn.
+
+**Bắt buộc đọc trước:** `references/erd-consolidation.md` — tuân thủ 100% (nguồn nhận/loại, datastore key, trích entity, cross-store bridge, 2 tầng, format output).
+
+## Input (chỉ đọc, cite nguồn)
+- `{techspec_dir}/*_techspec.md` §11 (canonical; bỏ `archive/` + `*.ts_parts/`; loại `integration-*` + `observability`).
+- `{arch_file}` §ERD mức cao — đối chiếu quan hệ tổng.
+- Module 0 (`architecture_design_parts/part_06_module0_draft.md`) §3.3/§6 — Global Data/State Registry, phát hiện drift.
+
+## Nhiệm vụ (tuần tự)
+1. Liệt kê techspec nhận được sau khi áp bộ lọc; log techspec bị skip + lý do.
+2. Với mỗi techspec: xác định datastore sở hữu (reference §2); trích entity + quan hệ từ §11.1 (reference §3); lấy từ điển field từ §11.2.
+3. Nhóm entity theo datastore → cluster. Bảng cùng tên ở nhiều techspec → hợp nhất, gộp danh sách nguồn; field mâu thuẫn → `[Cần xác nhận]` liệt kê các biến thể.
+4. Dựng cross-store bridge (reference §4) — chỉ nối khi có xác nhận khoá.
+5. Với mỗi bảng: sinh từ điển 2 tầng (reference §5).
+6. Ghi `{bo_dir}/erd-consolidated.md` đúng format reference §6, mở đầu có dòng `> Sinh bởi ... Nguồn: ...`, kết bằng mục "Điểm cần xác nhận".
+   - ⚠️ Mục "Điểm cần xác nhận" là **artifact nội bộ**, phục vụ HITL review + báo cáo cuối. **KHÔNG được publish thành hộp cảnh báo trên trang Confluence** (style-conventions §0.2) — trên trang chỉ đánh dấu `[Cần xác nhận]` tại đúng ô field/dòng quan hệ liên quan.
+
+## Guardrail (no-fabrication)
+- KHÔNG suy field/bảng ngoài nguồn. Không có dữ liệu → ghi rõ, không bịa.
+- Mỗi bảng + mỗi cross-store bridge phải kèm `Nguồn: <techspec>#<section>`.
+- Drift code-vs-Module 0 (đã ghi ở §11) → giữ trong Tầng 2, KHÔNG đưa lên Tầng 1; drift chưa resolve → `[Cần xác nhận]`.
+- Bảng schema-less (không có `@Document`) → giữ nguyên field từ constant registry + ghi chú "schema-less".
+- Nếu bảng §11.2 của một techspec có shape cột KHÁC `Field | Type | Constraints | Storage | Description` (thiếu cột, thêm cột, đổi tên cột) → map các cột THỰC SỰ có mặt vào Tầng 2, ghi chú rõ sự khác biệt shape (ví dụ "thiếu cột Storage — không có ghi chú lưu trữ"); KHÔNG giả định đủ 5 cột rồi để trống hoặc suy diễn giá trị.
+
+## Output
+- File: `{bo_dir}/erd-consolidated.md` (độc lập, tái dùng cho skill khác, trace về Stage 3).
+- Trả về (cho orchestrator): số cluster, số bảng, danh sách techspec skip, số điểm `[Cần xác nhận]`.

package/skills/NTAPP/.agent/skills/NTAPP-business-overview-confluence/references/confluence-publish.md

@@ -0,0 +1,113 @@
+# Confluence — đọc & xuất bản (cơ chế MCP + REST, bài học thực chiến)
+
+> Áp cho Confluence **Server** nội bộ (vd host `.35` space `TDOV`). Tài liệu Tổng quan nghiệp vụ
+> có draw.io → **phải** dùng đường REST cho attachment (xem §0). Đọc khi tới BƯỚC 4/6/7.
+
+## 0. Vàng: đọc/tạo qua MCP — nhưng attachment & body-có-sơ-đồ đi REST
+
+| Việc | Kênh | Ghi chú |
+|---|---|---|
+| Đọc trang (template, index, bảng tổng hợp) | **MCP** `confluence_get_page(convert_to_markdown=false)` | Lấy storage XHTML thô để parse heading/macro. Nếu host MCP chết (403 token) → fallback `scripts/confluence-get.ps1` (Basic auth). |
+| Tìm trang / dò macro | **MCP** `confluence_search` (CQL) | `macro="drawio"` … (xem §5). |
+| Tạo trang mới (skeleton) | **MCP** `confluence_create_page(content_format="storage")` | Lấy `pageId` để bước sau upload attachment + PUT body. `create_page` KHÔNG nhận `version_comment`. |
+| Cập nhật body **không có** attachment (trang nhỏ) | **MCP** `confluence_update_page(content_format="storage")` | Nhanh, atomic đủ. `update_page` CÓ `version_comment`. |
+| **Upload attachment (draw.io mxfile / PNG / file tải về)** | **REST** `scripts/confluence-publish.ps1` | 🔴 MCP `confluence_upload_attachment` **LUÔN FAIL** trên Server này (`success:false`), kể cả trang nhỏ. |
+| Cập nhật body **có** draw.io/ảnh, hoặc trang **mature lớn** (>~150KB) | **REST** `scripts/confluence-publish.ps1` | Upload attachment + PUT body **atomic** (trang không kẹt macro rỗng). Trang mature lớn: MCP cắt output → buộc REST. |
+
+**Nguyên tắc:** tài liệu Tổng quan nghiệp vụ luôn có ≥1 sơ đồ draw.io ⇒ vòng publish mặc định là
+**MCP create skeleton → sinh mxfile → `confluence-publish.ps1` (upload + body + auto-sync revision)**.
+
+## 1. Auth cho REST (agent tự chạy, user không gõ lệnh)
+
+`confluence-publish.ps1` / `confluence-get.ps1` đọc token từ **`.confluence-auth`** (dotenv, **gitignored**, ở repo root — walk-up tự tìm):
+
+```
+CONFLUENCE_BASE_URL=http://10.254.136.35:8090
+CONFLUENCE_PAT=<Personal Access Token>
+# (tuỳ chọn) host đọc-fallback khác:
+CONFLUENCE_32_BASE_URL=http://10.254.136.32:8090
+CONFLUENCE_32_USER=<user>
+CONFLUENCE_32_PASS=<pass>
+```
+
+Setup 1 lần: copy `.confluence-auth.example` (repo root) → `.confluence-auth`, dán PAT
+(Confluence → avatar → Settings → Personal Access Tokens → Create token). Thiếu file / PAT còn
+placeholder → script throw → **DỪNG, báo user setup**, không tự bịa.
+
+Gọi (agent chạy qua shell tool):
+```
+powershell -ExecutionPolicy Bypass -File scripts/confluence-publish.ps1 -Manifest <feature>/confluence-publish.manifest.json
+```
+
+`manifest.json`: `{ pageId, baseUrl?, title, storageFile, versionMessage, attachments:[{path,name,contentType,label,comment}] }`
+— path tương đối thư mục manifest; script tự đọc version live +1, tự sync revision (§4).
+
+## 2. Storage format (XHTML) — luật cứng
+
+- **Escape mọi text node tự chèn**: `&`→`&amp;`, `<`→`&lt;`, `>`→`&gt;`, `"`→`&quot;`. Bẫy 400 hay gặp:
+  `&` TRẦN trong câu tiếng Việt ("đối tượng & tham chiếu") → `Error parsing xhtml: Unexpected character '&'`.
+  Trước khi PUT quét raw `&` bằng regex `&(?![a-zA-Z]+;|#\d+;|#x[0-9a-fA-F]+;)`. Ưu tiên `→`/`·` thay `>`/`&`.
+- Khối code/diagram trong `<![CDATA[ ... ]]>` (bên trong CDATA KHÔNG cần escape).
+- Bảng: `<table class="wrapped"><tbody><tr><th>…</th></tr><tr><td>…</td></tr></tbody></table>`. Bảng lồng
+  `<table>` trong `<td>` render OK trên Server.
+- Panel: `<ac:structured-macro ac:name="tip|info|note"><ac:rich-text-body><p>…</p></ac:rich-text-body></ac:structured-macro>`.
+- Thu gọn: `<ac:structured-macro ac:name="expand"><ac:parameter ac:name="title">…</ac:parameter><ac:rich-text-body>…</ac:rich-text-body></ac:structured-macro>`.
+- Mục lục: `<ac:structured-macro ac:name="toc"><ac:parameter ac:name="maxLevel">3</ac:parameter></ac:structured-macro>`.
+- ⚠️ **HTML macro (`ac:name="html"`) BỊ TẮT** trên host `.35` → "Unknown macro: 'html'". Đừng nhúng mock bằng
+  HTML macro; dùng markup native (table `wrapped` + `info`).
+
+## 3. Checkbox = `ac:task-list` (KHÔNG dùng `☑ / ☐` unicode)
+
+Template Tổng quan có bảng **"Đơn vị yêu cầu / Đơn vị liên quan"** (ĐVYC/ĐVLQ) dùng checkbox **chọn được**:
+
+```html
+<ac:task-list>
+<ac:task><ac:task-id>NNN</ac:task-id><ac:task-status>incomplete</ac:task-status><ac:task-body> </ac:task-body></ac:task>
+</ac:task-list>
+```
+- `ac:task-status` = `incomplete` (chưa tích) | `complete` (đã tích). `ac:task-body` rỗng ` ` cho ô chỉ-tích.
+- **`ac:task-id` DUY NHẤT toàn trang** — đặt dải riêng cho phần sinh mới (vd 201+) tránh trùng id template gốc.
+- Đơn vị nghiệp vụ chính của hệ thống → tích `ĐVYC=complete`; các đơn vị "Bắt buộc approved" giữ `ĐVLQ=complete`.
+
+## 4. Ngày = date macro (chip lịch), không phải text
+
+Bảng "ghi nhận thay đổi": cột ngày render inline date macro (giống trang mature):
+```html
+<td><div class="content-wrapper"><p><time datetime="2026-07-16"></time></p></div></td>
+```
+KHÔNG để `<td>2026-07-16</td>` (text trần).
+
+## 5. Dò plugin sơ đồ (macro) — probe CHỦ ĐỘNG, đừng suy từ "không ai dùng"
+
+- CQL đếm trang dùng macro: `confluence_search(query='macro="drawio"')` (hoặc `mermaid`/`plantuml`). Có kết quả =
+  từng có người dùng — **CHƯA chắc render**; **rỗng ≠ chưa cài plugin** (chỉ nghĩa chưa ai dùng).
+- **Xác định render được hay không** = đọc `body.view`/`body.storage` của trang thật dùng macro đó (đọc **vài** trang,
+  không chỉ 1); nếu chứa `plugins/servlet/confluence/placeholder/unknown-macro?name=<macro>` → **plugin CHƯA cài**.
+  Không chắc → **tạo 1 trang nháp có đúng macro, đọc `body.view`, rồi xoá** (probe chủ động) thay vì đoán từ trang lạ.
+- Kinh nghiệm host `.35`: **có draw.io** (plugin //SEIBERT/MEDIA) → ưu tiên draw.io. Không có mermaid.
+
+## 6. draw.io — macro + attachment + `revision` (auto-sync bởi script)
+
+Mỗi sơ đồ = 1 attachment mxfile (tên không đuôi, `contentType application/vnd.jgraph.mxfile`, `label drawio`),
+nội dung mxGraph XML **không nén** (xem [diagram-drawio.md](diagram-drawio.md)). Chèn macro:
+```html
+<ac:structured-macro ac:name="drawio" ac:schema-version="1"><ac:parameter ac:name="border">true</ac:parameter><ac:parameter ac:name="diagramName">TEN_SO_DO</ac:parameter><ac:parameter ac:name="simpleViewer">false</ac:parameter><ac:parameter ac:name="links">auto</ac:parameter><ac:parameter ac:name="tbstyle">top</ac:parameter><ac:parameter ac:name="lbox">true</ac:parameter><ac:parameter ac:name="diagramWidth">1200</ac:parameter><ac:parameter ac:name="revision">1</ac:parameter></ac:structured-macro>
+```
+🔴 **`revision` PHẢI = ĐÚNG version của attachment mxfile** (plugin SEIBERT dùng nó để chọn version render):
+- `revision` **< version** → hiển thị **bản CŨ** ("diagram chưa update"). `>` → **404**. `=` → đúng bản mới. ✓
+- Mỗi publish re-upload mxfile → version +1. **KHÔNG hand-set revision** — `confluence-publish.ps1` tự đọc version
+  vừa upload rồi ghi đè `<ac:parameter ac:name="revision">` khớp `diagramName` (điều kiện: param `revision` nằm SAU
+  `diagramName` trong macro — drawio_lib.py emit đúng thứ tự). Với **CREATE** (mxfile version 1) thì `revision=1` là đúng.
+- draw.io = **nguồn hiển thị** (macro editable). ĐỪNG chèn `<ac:image>` PNG riêng cạnh macro. PNG "exported to image"
+  (nếu có) chỉ là backup tĩnh.
+
+## 7. Quy trình an toàn khi publish (draw.io)
+
+1. MCP `create_page` skeleton (trang mới) **hoặc** xác định `pageId` cần update.
+2. Sinh nội dung storage → **validate escape** (không `&` trần ngoài CDATA) → ghi ra file `*.storage.xhtml`.
+3. Sinh mxfile qua `drawio_lib.py` → ghi file (tên = `diagramName`, không đuôi).
+4. Viết `confluence-publish.manifest.json` (pageId + title + storageFile + attachments).
+5. Chạy `confluence-publish.ps1 -Manifest …` → upload attachment + **auto-sync revision** + PUT body version+1 (atomic).
+6. **Verify**: MCP `get_page` / `get_attachments` → **version attachment mxfile == `revision` trong macro**;
+   `body.view` không còn `unknown-macro`; số dòng bảng/sơ đồ khớp. Báo user hard-refresh (Ctrl+F5).
+7. Cập nhật ô link trong bảng tổng hợp tài liệu (body-only qua MCP `update_page` — không đụng attachment).

package/skills/NTAPP/.agent/skills/NTAPP-business-overview-confluence/references/diagram-drawio.md

@@ -0,0 +1,108 @@
+# draw.io — cấu trúc mxfile & cách render trên Confluence
+
+## Nguyên tắc
+- draw.io Confluence plugin (host `.35` = //SEIBERT/MEDIA) render sơ đồ **live bằng mxGraph từ nội dung mxfile** (attachment), KHÔNG cần ảnh PNG.
+- Dùng mxGraph XML **không nén** (đặt thẳng `<mxGraphModel>` trong `<diagram>`) — plugin đọc được, khỏi phải deflate+base64.
+- Sinh mxfile bằng `scripts/drawio_lib.py` (5 hàm: `overview_zones` / `process_3col` / `erd` / `state_diagram` / `breakdown_tree`).
+
+## 🔴 `revision` PHẢI KHỚP version attachment (bài học xương máu)
+Plugin SEIBERT dùng param `revision` của macro để chọn **đúng version attachment mxfile** cần render:
+- `revision` **< version** → hiển thị **bản CŨ** ("diagram chưa update"); `>` → **404**; `=` → đúng bản mới nhất. ✓
+- Mỗi lần publish re-upload mxfile → attachment version +1. **KHÔNG hand-set revision** — `scripts/confluence-publish.ps1`
+  tự đọc version vừa upload rồi ghi đè `<ac:parameter ac:name="revision">` (khớp `diagramName`). Với CREATE (mxfile version 1) → `revision=1`.
+- Điều kiện để auto-sync bắt được: trong macro, param `revision` nằm **SAU** `diagramName` (drawio_lib emit đúng thứ tự).
+- **Verify sau publish**: `get_attachments` → version mxfile == `revision` macro. Đây là điều kiện SỐNG CÒN (không 404, không kẹt render cũ).
+
+## Cạnh (edge) — routing
+
+🔴 **Bài học: `orthogonalEdgeStyle` làm mũi tên CHỒNG NHAU.** draw.io tự re-route và kéo mọi cạnh chụm vào trục giữa;
+với state diagram (có bước nhảy + quay lui) và cây phân rã (nhiều lá dưới cùng một nhóm) thì các đường đè lên nhau và
+cắt xuyên qua hộp — trang xuất bản bị phản hồi "đường dẫn mũi tên bị trùng nhau" (thực tế 2026-08-07).
+
+| Sơ đồ | Routing | Cơ chế |
+|:---|:---|:---|
+| `state_diagram`, `breakdown_tree`, `process_3col`, **`erd_graph`** | **`edgeStyle=none` + port + waypoint** (helper `_edge_px`) | Node đã canh trục sẵn nên toạ độ tính chính xác; draw.io vẽ đúng các đoạn thẳng qua waypoint, không tự bẻ lại |
+| `erd` (lưới field-level) | `entityRelationEdgeStyle` | Ít quan hệ, hộp lớn — để draw.io tự lo |
+| `overview_zones` | `orthogonalEdgeStyle` | Rất ít cạnh cấp cao giữa các vùng liền kề |
+
+**Quy tắc LÀN (rail) — không hai đường nào cùng một trục:**
+- `state_diagram`: chuyển tiếp **liền kề** → thẳng trục chính; **nhảy tiến** + cạnh vào *Kết thúc* → rail bên **phải** (đỏ nếu vào Kết thúc);
+  **quay lui / tự lặp** → rail bên **trái**, nét đứt xanh. Mỗi cạnh rail chiếm một làn riêng, cách nhau 38px; làn trong cùng dành cho bước nhảy ngắn nhất (ít cắt nhau nhất).
+- `breakdown_tree`: gốc → bus ngang → rẽ xuống từng cụm; trong cụm dùng **một trục dọc**, mỗi lá một nhánh ngang vào **cạnh trái** của lá.
+- `erd_graph`: đoạn **ngang** chỉ chạy trong **kênh giữa hai hàng**, đoạn **dọc** chỉ chạy trong **máng giữa hai cột** — cả hai vùng đều không có hộp, nên cạnh không bao giờ cắt hộp. Ba mức chống chồng: (a) mỗi cạnh một làn trong kênh, (b) mỗi cạnh một làn trong máng, (c) **cổng cấp theo (cột, kênh)** chứ không theo hộp — hai đoạn cùng chạy trong một kênh ở cùng một cột (một đi ra từ hộp trên, một đi vào hộp dưới) sẽ trùng x nếu cấp cổng theo hộp.
+- Cạnh chỉ thẳng đứng khi hai node **cùng trục x** — nếu không, bắt buộc phát waypoint gấp khúc, đừng để draw.io tự đoán.
+- Nhãn cạnh đặt `labelBackgroundColor=#ffffff` để chữ không dính vào đường.
+
+Khi thêm loại sơ đồ mới: nếu node đã canh trục → dùng `_edge_px`; chỉ để `orthogonalEdgeStyle` cho bố cục tự do.
+
+**Cấp slot cổng (port slot).** Chia làn rail thôi CHƯA đủ: hai cạnh nối vào cùng một hộp ở cùng độ cao sẽ dùng
+chung đoạn ngang sát mép hộp → vẫn chồng nhau dù rail khác nhau. `state_diagram` vì vậy cấp cho mỗi điểm nối
+trên mỗi cạnh hộp một `exitY`/`entryY` riêng (chia đều theo chiều cao, tự nới cao hộp khi nhiều cổng).
+Chia sẻ điểm nối chỉ chấp nhận khi các cạnh **cùng nguồn** (thân cây dùng chung, có chủ đích — như `breakdown_tree`).
+
+## Soi hình trước khi publish — `scripts/preview.py`
+
+mxfile là XML: không render thì **không ai nhìn thấy sơ đồ cho tới khi nó đã nằm trên Confluence**. Đó chính là
+đường mà lỗi mũi tên trùng nhau đi lên trang. Bắt buộc chạy sau khi sinh mxfile (workflow §7b):
+
+```bash
+python scripts/preview.py <mxfile> [mxfile2 ...] -o <outdir>      # --strict để cảnh báo => exit 1
+```
+
+Ghi `<tên>.preview.svg` + `<tên>.preview.png` (Chrome headless, 2x) và chạy 5 lint: hộp đè hộp · cạnh xuyên hộp
+· hai cạnh chồng trục · node tràn khổ · trang rộng > 2600px. Exit `0` sạch/PNG OK · `2` thiếu Chrome (**không chặn** —
+macro vẫn render live, chỉ mất ảnh soi) · `1` mxfile hỏng hoặc `--strict` mà còn cảnh báo.
+
+Độ trung thực: cạnh `edgeStyle=none` (state/tree/process) vẽ **đúng** đường draw.io sẽ vẽ; cạnh
+`orthogonalEdgeStyle`/`entityRelationEdgeStyle` (overview/erd) chỉ **xấp xỉ** nối tâm — xem bố cục, đừng phán xét
+đường đi, và lint cũng bỏ qua nhóm này để tránh báo động giả.
+
+## Khung mxfile
+```xml
+<mxfile host="<confluence-host>" type="atlas" version="20.8.2">
+  <diagram id="D1" name="Page-1">
+    <mxGraphModel dx="1200" dy="800" grid="1" gridSize="10" page="1" pageScale="1"
+                  pageWidth="{PW}" pageHeight="{PH}" math="0" shadow="0">
+      <root>
+        <mxCell id="0"/><mxCell id="1" parent="0"/>
+        <!-- vertices -->
+        <mxCell id="n1" value="Nhãn" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;"
+                vertex="1" parent="1"><mxGeometry x="40" y="40" width="160" height="40" as="geometry"/></mxCell>
+        <!-- edges -->
+        <mxCell id="e1" value="1 : N" style="edgeStyle=orthogonalEdgeStyle;html=1;endArrow=block;"
+                edge="1" parent="1" source="n1" target="n2"><mxGeometry relative="1" as="geometry"/></mxCell>
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>
+```
+
+## Escape trong mxfile
+- Value là thuộc tính XML → escape `& < > "`.
+- Xuống dòng trong 1 ô: dùng ký tự newline `&#10;` (khi sinh bằng Python: build với `\n` rồi `.replace(chr(10),"&#10;")` **sau khi** đã escape, để không bị escape nhầm `&#10;` thành `&amp;#10;`).
+- Bật `html=1` để dùng `<br>` / định dạng; khi đó `<b>` phải viết `&lt;b&gt;` (drawio tự giải mã).
+
+## Kiểu (style) hay dùng
+| Mục đích | style |
+|---|---|
+| Actor người que | `shape=umlActor;html=1;verticalLabelPosition=bottom;verticalAlign=top;fillColor=#fff2cc;strokeColor=#d6b656;` |
+| Hộp chức năng | `rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;` |
+| Quyết định (hình thoi) | `rhombus;whiteSpace=wrap;html=1;fillColor=#ffe6cc;strokeColor=#d79b00;` |
+| Bắt đầu/Kết thúc | `ellipse;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;` |
+| CSDL | `shape=cylinder3;whiteSpace=wrap;html=1;fillColor=#ffe6cc;strokeColor=#d79b00;` |
+| Vùng/khối bao (container nhìn) | `rounded=0;whiteSpace=wrap;html=1;fillColor=none;strokeColor=#4472c4;strokeWidth=3;verticalAlign=top;fontStyle=1;` |
+| Ô bảng ERD | `rounded=0;whiteSpace=wrap;html=1;fillColor=#ffffff;strokeColor=#b3b3b3;align=left;spacingLeft=4;overflow=hidden;` |
+| Cạnh ERD 1:N | `edgeStyle=entityRelationEdgeStyle;html=1;endArrow=ERmany;startArrow=ERone;` |
+
+## Bảng lưới ERD (mỗi thực thể)
+Không dùng shape=table phức tạp; dựng bằng **ô rectangle tuyệt đối**:
+- 1 ô header (tên bảng, tô màu miền), rộng W.
+- Mỗi trường = 3 ô kề nhau trên 1 hàng: `[kiểu dữ liệu | tên trường | khóa/ghi chú]` (rộng ~64 / ~152 / ~120, cao ~24).
+- Cạnh 1:N nối **ô header** của 2 thực thể.
+→ Xem hàm `erd_grid_entity()` trong `scripts/drawio_lib.py`.
+
+## Bố cục gọn (tránh rối mũi tên)
+- **§2 Mô hình tổng quan = bố cục VÙNG trái→phải** (`overview_zones`): Nguồn dữ liệu đầu vào · Hệ thống lõi · Cơ chế tích hợp · Giao diện (FE) · Actor. Mỗi vùng = 1 khung bao chứa thành phần xếp dọc; **KHÔNG vẽ cạnh nội bộ chằng chịt** — cấu trúc thể hiện bằng phân vùng.
+- Mũi tên **cấp cao** thể hiện chiều dữ liệu **in → xử lý → out** giữa các vùng liền kề (ít thôi); hệ thống ngoài tô **xám nét đứt** để nhận diện.
+- Actor = người que ngoài cùng phải, nối **1 cạnh** tới đúng FE tương tác.
+- Nhiều cạnh giao nhau chỉ chấp nhận ở ERD (bản chất quan hệ).

package/skills/NTAPP/.agent/skills/NTAPP-business-overview-confluence/references/erd-consolidation.md

@@ -0,0 +1,102 @@
+# Reference: Hợp nhất ERD toàn hệ từ Stage 3 (erd-consolidation)
+
+Quy tắc cho `agent_erd_data_architect` + mục ERD của workflow. Nguyên tắc gốc: no-fabrication, cite nguồn, nhóm theo datastore.
+
+## 1. Nguồn nhận & loại trừ
+
+**NHẬN** (chỉ đọc, canonical): `NTAPP-output/Stage_3_Specs/techspec/*_techspec.md` §11 — có `### 11.1 Sơ đồ thực thể logic` và/hoặc `### 11.2 Từ điển dữ liệu`.
+- Bỏ qua mọi file trong `archive/` và mọi `*.ts_parts/` (bản ghép trung gian).
+
+**LOẠI khỏi ERD:**
+- `integration-*_techspec.md` — §11 là event payload schema / contract Kafka-partner, KHÔNG phải bảng datastore. (Để dành skill riêng.)
+- `observability_techspec.md` — không own business entity (§11 đã bỏ).
+- techspec FE / techspec không có §11 backed bởi datastore thật → skip (log lý do).
+
+## 2. Xác định datastore sở hữu (cluster key)
+
+Đọc câu mở đầu §11 của mỗi techspec để lấy datastore + tên logic. Ví dụ tín hiệu:
+- "MongoDB `reconcile_service_staging`" → cluster `MongoDB · RS`.
+- "MariaDB C-34 share schema" → cluster `MariaDB · Config (admin)`.
+- staging/data_raw EDS/IDS → cluster theo store khai báo.
+Một techspec có thể ghi vào >1 store → tách entity theo store, KHÔNG gộp nhầm cluster.
+Store mơ hồ / không khai báo rõ → đặt entity vào cluster `[Cần xác nhận]` + ghi nguồn.
+
+## 3. Trích entity + quan hệ — NGUỒN KÉP (quan hệ ≠ field)
+
+**Nguyên tắc tách nguồn (quan trọng — đừng trộn):**
+- **Quan hệ giữa bảng = HLD `architecture_design.md §3.2` (Global Data Model ERD) — nguồn CHUẨN, ĐẦY ĐỦ.** Bê TRỌN bộ quan hệ mỗi sub-diagram (không rút gọn cạnh song song, không bỏ cạnh). Đây là bộ quan hệ đã review; techspec §11.1 chỉ mô tả góc nhìn per-module nên quan hệ nghèo hơn → KHÔNG dùng §11.1 làm nguồn quan hệ chính.
+- **Từ điển field = techspec §11.2** (per bảng). Bảng nào **có trong HLD ERD nhưng chưa techspec-hoá §11** → vẫn tạo hộp trong sơ đồ + dòng summary, phần field ghi `[Cần bổ sung]` (đừng bỏ bảng khỏi sơ đồ chỉ vì thiếu field).
+
+Từ HLD §3.2 (mỗi ```mermaid erDiagram``` sub-diagram theo store):
+- Mỗi entity khai báo → 1 hộp bảng trong cluster tương ứng store.
+- Mỗi dòng `A ||--o{ B : "label"` → quan hệ nội cluster (A,B cùng store) hoặc **cross-store bridge** (khác store; các entity hậu tố `_ref` = proxy cross-store, map về bảng nguồn thật ở store kia).
+- Nhãn cạnh rút gọn (tên khoá / cụm từ ≤ 3 từ) cho dễ đọc; giữ diacritics tối thiểu, ưu tiên ASCII.
+
+Từ techspec §11.1 (`ENTITY { ... }`) chỉ để **lấy field/PK/FK** map vào từ điển bảng; KHÔNG lấy quan hệ ở đây.
+
+## 4. Cross-store bridge (Tầng A)
+
+**Nguồn bridge = cột FK thật trong ERD chi tiết** (vd `docs/ba-erd-kbnv.md` — nếu có), KHÔNG chỉ dựa HLD §3.2. HLD thường *distil* ERD chi tiết → gộp nhiều bridge vào 1 proxy `_ref` (vd chỉ vẽ `statistic_retrieval_data_ref → data_raw`, bỏ mất `reconcile_bank_service.processRequestId → statistic_retrieval_data`). ⇒ **quét cột FK của mọi bảng đích**: field đánh dấu `FK` + "Liên kết/Tham chiếu tới `<bảng khác store>`" = 1 bridge cross-store.
+
+Quy tắc nối: chỉ nối 2 bảng khác store khi khoá chung là FK/matching/link key xác nhận ở (a) cột FK ERD chi tiết, (b) §11 techspec, (c) arch §ERD, hoặc (d) Module 0 §3.3/§6. Trùng tên field nhưng không có xác nhận ngữ nghĩa → KHÔNG nối, ghi `[Cần xác nhận]`. Bảng đích chưa techspec-hoá vẫn nối bridge (theo FK) + hiện hộp, field `[Cần bổ sung]`.
+
+⚠️ Phân biệt: `reconcile_* → statistic_reconcile_*` (rollup) là **nội cụm MongoDB**, KHÔNG cross-store — đừng nhầm với `statistic_send_data`/`statistic_retrieval_data` (MariaDB).
+
+## 5. Từ điển 2 tầng mỗi bảng
+
+- **Tầng 1 (nghiệp vụ):** `Tên field | Kiểu | Ý nghĩa` — rút từ §11.2 cột Field/Type/Description, bỏ jargon.
+- **Tầng 2 (kỹ thuật, đầy đủ):** bê nguyên bảng §11.2 `Field | Type | Constraints | Storage | Description` + ghi chú code-as-is/drift.
+
+## 6. Format artifact `erd-consolidated.md` (độc lập, trace lại được)
+
+```
+# ERD hợp nhất toàn hệ — <project>
+> Sinh bởi agent_erd_data_architect | <ngày> | Nguồn: <list techspec + arch §ERD + Module 0>
+
+## 0. Cross-store relationship map (Tầng A)
+   - (mô tả sơ đồ cross-store: entity thu gọn + FK bắc cầu)
+   - Bảng: Bảng nguồn | Khoá | Bảng đích | Store↔Store | Nguồn
+
+## <n>. Cụm datastore: <cluster name>
+   ### <n>.1 Danh sách bảng + quan hệ nội cụm (cho sơ đồ erd)
+   ### <n>.2 Bảng tổng hợp: STT | Tên bảng | Ý nghĩa | Nguồn
+   ### <n>.3 Từ điển field từng bảng
+       #### <tên_bảng>   (Nguồn: <techspec>#<section>)
+          Tầng 1: | Tên field | Kiểu | Ý nghĩa |
+          Tầng 2: | Field | Type | Constraints | Storage | Description |
+
+## X. Điểm cần xác nhận
+   - [Cần xác nhận] ...
+```
+
+## 6b. 🔴 GATE BẮT BUỘC — đối chiếu CODE trước khi render ERD
+
+HLD và techspec **liệt kê cả bảng chưa/không bao giờ tồn tại**, và mô tả quan hệ theo ý đồ thiết kế chứ không theo
+hiện trạng. Render thẳng = đưa mô hình dữ liệu sai lên tài liệu bàn giao (thực tế DSTT 2026-08-10: **5/48 bảng
+không có trong code**, **4 quan hệ sai bản chất**). Trước khi render §4 phải:
+
+1. **Xác minh từng bảng** bằng khai báo thật trong code, không bằng tên gọi:
+   - quan hệ (JPA): `@Table(name = "...")`;
+   - tài liệu (MongoDB): `@Document(collection = ...)` **hoặc hằng số tên collection** — nhiều dự án khai báo bằng
+     hằng số + đọc từ config, grep `@Document` ra rỗng và rất dễ kết luận nhầm là "không có collection nào".
+   - ⚠️ Bẫy đã dính: (a) tên chỉ tồn tại trong **DTO báo cáo** — không phải bảng; (b) lớp `*Adapter` mang tên bảng
+     nhưng bên trong đọc bảng khác; (c) literal là **tên trường** trong pipeline tổng hợp; (d) literal là **tên
+     database**. Luôn mở file xem ngữ cảnh trước khi kết luận.
+2. **Xác minh từng quan hệ**: tìm chỗ code thực sự ghép hai bảng (`findBy...`, join JPQL/native, filter, pipeline).
+   Không tìm được chỗ ghép → đó là **luồng xử lý** hoặc quan hệ sai, không phải quan hệ dữ liệu.
+3. **Ghi khoá nối cho MỌI quan hệ** — chỉ có `1:N` là chưa đủ, người đọc cần biết hai bảng ghép nhau *qua thông tin
+   nào*. Phân loại: `Khoá ngoại` (ràng buộc thật ở DB) · `Khoá nghiệp vụ` (không ràng buộc, ứng dụng tra theo mã) ·
+   `Khoá tài liệu` (hai document cùng mang một mã) · `Luồng xử lý` (KHÔNG phải quan hệ — tiến trình đọc bảng này ghi
+   bảng kia) · `Nhật ký`. Nhãn trên sơ đồ = **khoá nối** (ngắn); diễn giải để ở bảng dưới sơ đồ.
+4. **Kết quả đối chiếu ghi thành artifact riêng, mỗi dòng trích dẫn `file:dòng`** (vd `_erd_truth.py` của DSTT), rồi
+   cho bộ render đọc artifact đó để lọc bảng + làm giàu nhãn. KHÔNG sửa tay vào sơ đồ — lần re-run sau sẽ mất.
+5. Bảng/quan hệ bị loại phải **báo cho user kèm lý do + bằng chứng**, không im lặng xoá.
+
+> **NoSQL:** MongoDB không có khoá ngoại. Phần lớn "quan hệ" giữa collection là **luồng xử lý** do job thực hiện
+> (đọc → ghi), không phải liên kết tham chiếu. Trình bày lẫn lộn hai thứ là nguyên nhân điển hình khiến người đọc
+> không hiểu sơ đồ — tách rõ bằng cột *Loại quan hệ* + một đoạn diễn giải ngay dưới sơ đồ.
+
+## 7. Render sang mục ERD Confluence (2 tầng)
+
+- **Tầng A → CHỈ 1 sơ đồ** draw.io `erd(..., collapsed=True)`, quan hệ thể hiện trực tiếp bằng cạnh + nhãn khoá. **KHÔNG render bảng mô tả prose cross-store** (bảng §0 chỉ là nguồn máy để dựng cạnh, không đưa lên Confluence — quan hệ chỉ cần sơ đồ).
+- Tầng B → mỗi cluster 1 sơ đồ `erd()` (đủ mọi cạnh nội cụm HLD) + bảng tổng hợp bảng `STT | Tên bảng | Ý nghĩa | Nguồn`; mỗi bảng 1 macro `expand` chứa Tầng 1, lồng `expand` "Chi tiết kỹ thuật đầy đủ" chứa Tầng 2. Bảng chưa techspec-hoá → expand hiện `[Cần bổ sung]`.

package/skills/NTAPP/.agent/skills/NTAPP-business-overview-confluence/references/extract-from-code.md

@@ -0,0 +1,19 @@
+# Fallback: trích nghiệp vụ từ source code (khi HLD/WBS/PRD thiếu)
+
+Dùng khi tài liệu thiết kế thiếu ERD / actor / flow. **Code là sự thật** — trích rồi **ghi kèm nguồn**
+(`file:line`), phần suy diễn không chắc → `[Cần xác nhận]`. Bảng dưới cho stack Java/Spring (các repo reconciliation);
+điều chỉnh dấu hiệu cho stack khác.
+
+| Cần suy ra | Tìm ở đâu trong code |
+|---|---|
+| **Thực thể ERD** (bảng, trường, khóa) | `@Entity` / `@Table` / `@Id` / `@Column` (JPA); `CREATE TABLE`, migration (Flyway/Liquibase); `@ManyToOne` / `@OneToMany` / `@JoinColumn` = quan hệ 1:N / khóa ngoại |
+| **Actor + quyền** | `@RestController` + endpoint; `@PreAuthorize` / `@Secured` / role guard; header user (vd `X-User`); nhóm endpoint theo controller = nhóm chức năng theo vai trò |
+| **Quy trình nghiệp vụ** | Luồng gọi trong `@Service` (orchestration); `@Scheduled` / cron / job (bước chạy ngầm); `@KafkaListener` / consumer / producer (dòng chảy async); trạng thái rẽ nhánh theo `if`/enum |
+| **Hệ thống ngoài** | `@FeignClient` / `RestTemplate` / `WebClient` base-url; cấu hình SFTP/FTP host đối tác; client OAuth/Keycloak; tên topic Kafka out |
+| **Kho dữ liệu trung gian** | MinIO/S3 client; thư mục file tạm; bảng staging; cache Redis |
+| **Trạng thái (vòng đời)** | enum `*Status` / `*State` + chỗ gán/chuyển; hằng số `Constant.*`; điều kiện `if` trên status trong service |
+| **Phân rã chức năng (§6)** | FE: component/screen/route; BE-kết nối: controller/endpoint/adapter; BE-hạ tầng: job/consumer/producer/scheduler — **soát cả 3 loại, đừng bỏ phần chạy ngầm** |
+
+**Cách làm nhanh:** grep theo dấu hiệu ở trên trong các repo code (reconciliation-service / -process /
+-external-data-service / -internal-service / -admin-service / -fe), đối chiếu với HLD/WBS để lấp chỗ trống, KHÔNG
+thay thế tài liệu thiết kế khi nó đã có. Ưu tiên: HLD → WBS → PRD → code (code chỉ để lấp).

package/skills/NTAPP/.agent/skills/NTAPP-business-overview-confluence/references/scope-brownfield-vs-newbuild.md

@@ -0,0 +1,28 @@
+# Phạm vi: WBS (xương sống toàn hệ) + đánh dấu phần xây mới (tùy chọn)
+
+## Mô hình nguồn (đã chốt)
+Tài liệu Tổng quan nghiệp vụ mô tả **bức tranh toàn hệ**. Nguồn theo thứ tự:
+1. **`architecture_design.md`** (HLD) — C4 context/container, ERD, security zoning, mô hình tổng quan.
+2. **`project_wbs.md`** — **xương sống phân rã chức năng toàn hệ** (§6 cây phân rã bám cái này).
+3. **PRD / Epics** — bối cảnh, vấn đề, mục tiêu kinh doanh (thứ code/thiết kế không nói).
+4. (fallback) **source code** — suy actor/flow/ERD khi tài liệu thiếu; xem [extract-from-code.md](extract-from-code.md).
+
+## Đánh dấu "phần xây mới" (tùy chọn — chỉ khi người dùng chọn xem 2 lớp)
+`project_wbs.md` thường **TRỘN** brownfield AS-IS (đã có) + phần xây mới của dự án hiện tại. Nếu người dùng muốn
+**phân biệt** hai lớp trên cây §6, nguồn xác định phần xây mới **chính xác** là:
+
+`NTAPP-output/Stage_4_Design/detailed_design/feature_design_parts/<ID>/` — **mỗi thư mục con = 1 feature THỰC SỰ
+được thiết kế để build**. Đọc `f0_overview_part.md` mỗi feature lấy tên/loại (backend-service / frontend-app /
+integration-contract)/mục đích. (Có thể tham chiếu thêm slice plan `Stage_2_Architecture/slices/`.)
+
+## Tín hiệu brownfield vs greenfield trong HLD/WBS
+- Bảng phạm vi §1.2 HLD thường có cột "Brownfield/Greenfield".
+- Bảng "Tổng số WBS items" tách theo version (vd v3.0 AS-IS vs v3.1+ bổ sung) và theo `module_type`.
+- Nhãn trong tên cụm / mô tả (vd "service mới", "brownfield extend").
+
+## Cách xử lý trong skill (BƯỚC 2 hỏi phạm vi)
+- **Mặc định — Toàn hệ theo WBS:** cây §6 dựng từ `project_wbs.md` (bức tranh đầy đủ), **không** phân lớp AS-IS/mới. PRD/epic cho bối cảnh.
+- **Tùy chọn — Toàn hệ 2 lớp:** thêm tách nhánh **A** "Nền tảng sẵn có (brownfield)" (tô xám, mức cụm — đọc WBS) + nhánh **B** "Xây mới" (tô màu theo 3 loại, mức feature — đọc `feature_design_parts`). Highlight phần xây mới trên §2 (viền nhấn).
+- **Tùy chọn — Chỉ phần xây mới:** chỉ nhánh B (`feature_design_parts`).
+- Nếu KHÔNG có `feature_design_parts` (dự án chưa tới Stage 4) mà người dùng vẫn muốn 2 lớp → dùng nhãn greenfield trong WBS để suy, **đánh dấu `[Cần xác nhận]`**.
+- Khi mơ hồ giữa các mức → **HỎI**, không mặc định lấy hết hay bỏ sót.