@trungtamcongnghedigital/vsaf 1.0.0

package/skills/NTAPP/.agent/skills/NTAPP-srs-to-confluence/references/confluence-server-publish.md

@@ -0,0 +1,142 @@
+# REFERENCE: Publish lên Confluence **Server** — cơ chế thật + template fidelity
+
+> Tổng hợp bài học vận hành thật khi publish SRS lên host `.35` (Confluence **Server**, space `TDOV`). Đọc khi tới §8/§9 (EXECUTE). Bổ sung cho `../NTAPP-dd-to-confluence/references/storage-format.md`.
+
+## 0. Vàng: MCP KHÔNG upload attachment được — dùng REST qua auth file
+
+- `mcp__atlassian*__confluence_upload_attachment` **và** `_upload_attachments` **luôn FAIL** trên Confluence Server này (`success:false` / "Failed to upload attachment"), kể cả trang nhỏ, kể cả file có đuôi chuẩn (`.png`). Đây KHÔNG phải lỗi hard-limit — body-only `update_page` vẫn chạy.
+- ⇒ **Mọi attachment (draw.io mxfile, PNG, HTML tải về…) phải upload qua REST multipart.** Skill có script sẵn: [`../scripts/confluence-publish.ps1`](../scripts/confluence-publish.ps1).
+- **Agent tự chạy script** (qua shell/PowerShell tool) — user KHÔNG gõ lệnh. Token đọc từ file `.confluence-auth` (gitignored) ở repo root:
+
+  ```
+  CONFLUENCE_BASE_URL=http://10.254.136.35:8090
+  CONFLUENCE_PAT=<Personal Access Token>
+  ```
+
+  Setup 1 lần: copy `.confluence-auth.example` → `.confluence-auth`, dán PAT. Nếu thiếu file / PAT còn placeholder → script throw, DỪNG báo user setup (Confluence → avatar → Settings → Personal Access Tokens → Create token).
+- **Cách gọi** (một lệnh làm cả upload attachment + PUT body, atomic — trang không kẹt macro rỗng):
+
+  ```
+  powershell -ExecutionPolicy Bypass -File <skill>/scripts/confluence-publish.ps1 -Manifest <feature>/confluence-publish.manifest.json
+  ```
+
+  Manifest mô tả pageId + titleFile/title + storageFile + versionMessage + danh sách attachment `{path,name,contentType,label,comment}` (path tương đối thư mục manifest). Xem mẫu `srs/BE-RP-17/confluence-publish.manifest.json`. Script tự đọc version live +1.
+
+- **Body vẫn có thể đi MCP** `update_page(content_format="storage")` NẾU không có attachment (trang nhỏ). Nhưng khi có draw.io/ảnh → dùng luôn script để atomic. Trang **mature lớn** (>~150KB body) thì cả body cũng phải PUT REST (MCP cắt output) — xem storage-format.md.
+
+## 1. Checkbox = `ac:task-list` (KHÔNG dùng `☑ / ☐` unicode)
+
+Template SRS (api/tiến trình/web) dùng **task-list chọn được**, không phải ký tự unicode (user sẽ chê "không tích được"). Mọi ô tích trong SRS phải render bằng `ac:task-list` — **KHÔNG có ngoại lệ**, gồm: bảng Đơn vị phê duyệt cột ĐVYC/ĐVLQ · §1 Loại chức năng · §3 Loại dữ liệu · **§5 cột Trạng thái (Thành công/Chưa rõ/Thất bại)**. ⚠️ **§5 Trạng thái RẤT hay bị bỏ sót thành unicode `☑ Thành công ☐ Chưa rõ ☑ Thất bại`** (BE-RP-18 mắc lần đầu, phải sửa v4) — luôn dùng task-list 3 task, phần giải thích (vd "— fail ngay, báo Ops") để text NGAY SAU `</ac:task-list>` cùng ô. Render:
+
+```html
+<ac:task-list>
+<ac:task><ac:task-id>NNN</ac:task-id><ac:task-status>incomplete</ac:task-status><ac:task-body>  Nhãn</ac:task-body></ac:task>
+<ac:task><ac:task-id>NNN+1</ac:task-id><ac:task-status>complete</ac:task-status><ac:task-body>  Nhãn 2</ac:task-body></ac:task>
+</ac:task-list>
+```
+
+- `ac:task-status` = `incomplete` (chưa tích) | `complete` (đã tích). `ac:task-body` = nhãn (rỗng ` ` cho ô chỉ-tích như ĐVYC/ĐVLQ).
+- **`ac:task-id` phải DUY NHẤT toàn trang.** Đặt dải riêng cho tài liệu sinh mới (vd 201+, 231+, 241+) tránh trùng id template gốc.
+- Map mặc định Đơn vị phê duyệt (theo template `199113677`): hàng 1-3 (P.KTDV/CSKH/Trải nghiệm KH) `ĐVLQ=complete` + ghi chú "Bắt buộc approved tài liệu"; các hàng còn lại `incomplete`. Đơn vị nghiệp vụ chính của feature → tích `ĐVYC=complete`.
+
+## 2. Ngày = date macro (chip lịch), không phải text
+
+Cột ngày trong "Bảng ghi nhận thay đổi" render bằng inline date macro để ra chip 📅 (giống các trang mature):
+
+```html
+<td><div class="content-wrapper"><p><time datetime="2026-07-14"></time></p></div></td>
+```
+
+KHÔNG để `<td>2026-07-14</td>` (text trần, xuống dòng xấu).
+
+## 3. §2.1 Biểu đồ activity = draw.io (không phải sequence)
+
+Template API/tiến trình đặt tên mục **"2.1. Biểu đồ activity diagram"** → dùng **activity diagram vẽ draw.io** (editable), KHÔNG phải sequence PlantUML.
+
+**Single-source-of-truth generator:** [`../scripts/build-activity-diagram.mjs`](../scripts/build-activity-diagram.mjs).
+- Input: 1 file `<feature>-activity.model.json` (mảng `nodes` {id,type,x,y,w,h,t} + `edges` {f,t,k,l}). Xem mẫu `srs/BE-RP-17/BE-RP-17-activity.model.json`.
+- Output (1 lệnh): `<base>` (mxfile draw.io) **+** `<base>.png` (Chrome headless screenshot @2x, khớp toạ độ mxfile 100% vì cùng model).
+
+  ```
+  node <skill>/scripts/build-activity-diagram.mjs <feature>-activity.model.json <out_dir> <base_name>
+  # base_name = tên diagram, vd BE-RP-17-activity-flow (mxfile KHÔNG đuôi)
+  ```
+- node types: `action`(rounded) `decision`(rhombus) `term`(ellipse start/end) `bar`(nhãn vòng lặp) `group`(**khung nét đứt bao vòng lặp** — nhãn góc trên-trái, vẽ SAU cùng nên nằm dưới) `lane`(**swimlane dọc theo actor** — dải tiêu đề cao 40 + thân, vẽ dưới cùng; node nằm trong lane thuần bằng toạ độ `x/y` của chính nó) `outcome`(hộp phải xanh: tiếp tục/loop-back) `abort`(hộp phải đỏ: dừng lỗi). edge `k`: `v`(dọc — **tự bẻ khuỷu xuống/ngang/xuống khi hai node khác lane**, thẳng khi cùng tâm-x) `R`(rẽ phải tới hộp cạnh) `L`(rẽ **trái** tới hộp cạnh — gương của `R`, dùng khi hộp nhánh nằm ở lane bên trái) `join`(hộp phải quay về node chính) `end`(hộp cạnh → **bus dọc phải `endRail`** → node Kết thúc) `loopL`/`loopR`(**mũi tên nét đứt xanh quay lại đầu vòng lặp**, rail chỉ định qua `edge.rail`; với `loopR` thì rail **phải** nằm bên phải cạnh phải của node đích, không thì đoạn cuối cắt xuyên qua node).
+- **🎯 CHIA LANE THEO ACTOR LÀ MẶC ĐỊNH** (user chốt: "activity diagram chưa chia lane"). Mỗi actor/hệ thống tham gia = 1 node `lane` (cột dọc, tiêu đề = **tên actor/tên service thật**, khớp cột *Đối tượng* của bảng §2.2/§3.3). Mỗi node nghiệp vụ đặt vào đúng lane của đối tượng thực hiện nó; hộp `abort`/`outcome` cũng thuộc lane của đối tượng thực hiện, đặt ở **cột phụ bên phải trong chính lane đó** (lane có nhánh → chừa bề rộng cho 2 cột). Chỉ bỏ lane khi toàn luồng do đúng **một** đối tượng thực hiện.
+- **Quy ước vẽ activity (đã chốt qua review — model.json phải tuân đủ 7 quy ước):**
+  1. **Đánh số MỌI hình = một bước, tuần tự theo thứ tự đọc** — action, **ô quyết định**, VÀ hộp nhánh (abort/outcome) đều mang số `B1…Bn` liên tục (user chê "ô chữ nhật có số, ô [quyết định] thì không → khó mô tả"). KHÔNG để hình nào không số, KHÔNG dùng số vòng tròn rời. §2.2 tách **1 dòng / 1 hình**, cột Bước khớp số trên sơ đồ 1-1. (Terminal Bắt đầu/Kết thúc không cần số.)
+  2. **Nhánh dừng phải nối tới Kết thúc** — mọi hộp `abort` (và outcome kết thúc như file-rỗng) dùng edge `end` gộp về **một** node `term` "Kết thúc" qua bus dọc bên phải (`endRail`), KHÔNG để hộp lơ lửng.
+  3. **Vòng lặp = khung bao + mũi tên quay lại** — mỗi vòng lặp bọc bằng 1 node `group` (nhãn "⟳ Vòng lặp: …") **và** 1 edge `loopL`/`loopR` từ điểm quyết định cuối vòng quay lại đầu vòng. Rõ hơn hẳn `bar` nhãn suông (user chê "vẽ vòng lặp k rõ nghĩa"). Nhãn group để 1 dòng (tránh đè node dưới).
+  4. **Nhãn node = NGÔN NGỮ NGHIỆP VỤ, không phải DD** — mô tả *việc nghiệp vụ đang xảy ra* ("Xin mã truy cập từ hệ thống trung gian", "Kiểm tra chữ ký số của VIB để đảm bảo dữ liệu đáng tin"), KHÔNG bê tên class/method/factory/endpoint/biến kỹ thuật vào nhãn (`RetrievalMethodFactory`, `isRunAble`, `POST /switching/...`, `saveCheckpoint`). Chi tiết kỹ thuật đó thuộc §4 (đặc tả API) + DD — user chê "câu chữ như mô tả DD, chưa mô tả nghiệp vụ gì". Quy ước này áp cho **cả nhãn sơ đồ §2.1 và ô mô tả §2.2**.
+  5. **🎯 Spine (trục dọc) CÙNG TÂM X trong PHẠM VI MỘT LANE** — các node liên tiếp cùng lane đặt sao cho `x + w/2` bằng nhau (vd BE-RP-17 cx=370) để edge `v` ra **thẳng đứng**. Khi luồng **nhảy sang lane khác** thì tâm-x lệch là đúng: generator tự bẻ edge `v` thành khuỷu xuống/ngang/xuống (chỉnh cao độ đoạn ngang bằng `edge.rail`), KHÔNG được kéo node ra khỏi lane của nó để "cho thẳng trục".
+  6. **🎯 Hộp cạnh (abort/outcome) CĂN THẲNG TÂM-Y với ô quyết định nguồn** — đặt `side.y = decision.cy − side.h/2` để edge `R` thành **đường ngang thuần, KHÔNG cần waypoint**. Đây là geometry đơn giản nhất, không renderer nào routing sai (generator tự bỏ waypoint khi `|Δy|<1`). *(Đừng để hộp cạnh lệch tâm-y → sinh waypoint elbow thừa, dễ glitch bộ render server-side.)*
+  7. **🎯 CÁC LANE PHẢI DÙNG CHUNG VIỀN — KHÔNG hở khe giữa hai lane.** Lane kề nhau phải khít tuyệt đối: `lane[i].x + lane[i].w == lane[i+1].x` (và mọi lane cùng `y` + cùng `h`). Chỉ cần hở vài pixel là trang render ra **mấy khối chữ nhật rời**, đọc không còn ra swimlane — user chê ngay: *"phần activity diagram từng lane đang tách ra, k khớp vào nhau"* (case thật SCR-COMPOSE 2026-08-07: lane để hở 10px ở `290→300` và `860→870`, phải publish lại). Chuẩn đúng đang chạy ở SCR-EMBED-PMT (pageId `199112222`): `20..340 | 340..960 | 960..1580 | 1580..1830`.
+     - **Cách bố cục an toàn:** chọn trước các mốc biên (vd `40, 300, 870, 1430`) rồi tính `w = biên_sau − biên_trước`; ĐỪNG đặt `w` tròn số rồi cộng thêm khoảng cách trang trí giữa các lane.
+     - **Lane rộng bao nhiêu:** lane có nhánh (`abort`/`outcome` ở cột phụ) phải đủ chứa **cả** cột spine lẫn cột phụ — nới `w` của chính lane đó, KHÔNG đẩy hộp nhánh tràn sang lane bên cạnh.
+     - 🎯 **LANE PHẢI BAO CẢ HAI BUS DỌC — `endRail` và rail của `loopL`/`loopR` nằm TRONG lane, KHÔNG được chạy ở lề trang.** User chốt: *"đường nối từ B5, B11, B15, B21, B24, B27 tới Kết thúc hay đường từ B18 về B17 đang bị chờm ra khỏi lane → chỉnh cho lane rộng hơn bao các đường đó nữa"* (case thật SCR-COMPOSE 2026-08-07, phải publish lại lần 3). Nhìn ảnh thấy nét vẽ nằm ngoài khung lane là sai, dù sơ đồ vẫn "đúng logic".
+       - `endRail` phải thoả `lane_cuối.x < endRail < lane_cuối.x + w` → nới `w` lane cuối (chừa ~25px từ rail tới viền lane).
+       - rail của `loopL` phải nằm trong **lane đầu** → nới lane đầu sang trái (giảm `x`, cộng bù vào `w` để biên phải không đổi, giữ nguyên quy tắc khít lane).
+       - `canvasW` phải lớn hơn biên phải của lane cuối (chừa lề ~25px), nếu không lane bị cắt.
+       - Cấu hình đúng đang chạy ở SCR-COMPOSE: lane `10..300 | 300..870 | 870..1475`, `endRail=1450`, rail vòng lặp `=30`, `canvasW=1500`.
+     - Generator tự kiểm và **cảnh báo** (không chặn) khi phát hiện khe hở / lane chồng nhau / lane lệch `y`-`h` / node nằm ngoài mọi lane / **`endRail` hoặc rail vòng lặp nằm ngoài dải lane** — thấy dòng `LANE WARN:` thì sửa model rồi gen lại trước khi publish.
+- Nhúng vào storage: macro `ac:name="drawio"` param `diagramName` = **đúng tên attachment mxfile** (không đuôi), `diagramWidth` = `canvasW`, `revision` = **version attachment mxfile** (script tự set — xem cảnh báo 🔴 cuối §3; hand-set số bất kỳ, script ghi đè đúng):
+
+  ```html
+  <ac:structured-macro ac:name="drawio" ac:schema-version="1"><ac:parameter ac:name="border">true</ac:parameter><ac:parameter ac:name="diagramName">BE-RP-17-activity-flow</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">1100</ac:parameter><ac:parameter ac:name="revision">2</ac:parameter></ac:structured-macro>
+  ```
+- Attach 2 file (qua confluence-publish.ps1 manifest): mxfile (`contentType application/vnd.jgraph.mxfile`, `label drawio`) + PNG (`contentType image/png`, `comment "<base> exported to image"`).
+- ⚠️ **Bẫy Chrome "stale PNG"**: nếu Chrome đang mở, `--headless` cũ **attach vào instance sẵn có rồi return NGAY mà KHÔNG ghi PNG** → để lại file cũ (timestamp không đổi). Generator đã fix: `--headless=new` + `--user-data-dir` profile tạm riêng + đường dẫn PNG **tuyệt đối** (headless=new ghi path tương đối theo cwd của Chrome) + check `existsSync` sau khi chạy. Luôn **xem lại PNG** (Read image) trước khi publish để chắc đã đổi.
+- ℹ️ **Cơ chế hiển thị trên .35**: macro draw.io render mxfile **sống bằng mxGraph** (đúng engine draw.io) theo `revision` (xem 🔴 cuối §3). PNG export đính kèm (comment "exported to image") là bản tĩnh dự phòng (dùng khi export PDF/email hoặc JS tắt). *(Note cũ "license hết hạn → watermark" là suy đoán SAI hướng — thủ phạm thật của mọi lần "diagram chưa update" là revision lệch version, KHÔNG phải watermark.)* Title để NGOÀI svg (generator tự làm) tránh đè node start.
+- ⚠️ **draw.io PHẢI là nguồn hiển thị (macro editable), KHÔNG chèn ảnh PNG riêng.** User chốt: "phải theo draw.io, k phải mỗi ảnh; mũi tên vẽ đúng như ảnh gen". ⇒ ĐỪNG thêm `<ac:image>` cạnh macro — chỉ để **1 macro draw.io** trong §2.1.
+- ⚠️ **mxfile edge PHẢI dùng `edgeStyle=none` + waypoint + port — KHÔNG dùng `orthogonalEdgeStyle`.** (Đã bake trong `build-activity-diagram.mjs`.)
+  - `edgeStyle=none` → draw.io vẽ **đoạn thẳng nối qua đúng waypoint** (tái tạo path SVG chính xác). `orthogonalEdgeStyle` (dù có waypoint) vẫn **tự re-route, kéo mũi tên chụm vào giữa** → user chê "mũi tên dính hết vào giữa".
+  - mỗi edge emit `exitX/exitY/entryX/entryY` (đúng cạnh nối như SVG: `end`=right→right, `loopL`=left→left, `loopR`=left→right, `R`=right→left, `join`=bottom→right, `v`=bottom→top) + `<Array as="points">` góc rail/elbow (END_RAIL cho `end`, `edge.rail` cho loop). Điểm axis-aligned với port ⇒ đoạn thẳng = orthogonal sắc nét, trùng PNG.
+  - **Bỏ waypoint thừa/suy biến** (điểm trùng `(585,234)(585,234)` / zero-length segment) — glitch bộ render. Nhờ **quy ước 5 (spine cùng cx)** + **quy ước 6 (hộp cạnh căn tâm-y)** thì edge `v` không cần waypoint và edge `R` chỉ còn đường ngang thuần → geometry sạch nhất.
+- 🔴 **ROOT CAUSE cả loạt "diagram chưa update" + lỗi 404 (BE-RP-17 v3→v12): `revision` PHẢI BẰNG ĐÚNG version của attachment mxfile.** Plugin SEIBERT dùng `revision` để chọn **đúng version attachment** cần render:
+  - `revision` **< version** → macro hiển thị **bản render CŨ** của revision đó (mxfile mới đã upload nhưng KHÔNG hiện) → user chê "diagram chưa update / vẫn chưa được". *(Đây là bug ẩn suốt v3–v10: mỗi publish re-upload mxfile → version +1, nhưng revision hand-set lệch thấp hơn → luôn kẹt render cũ.)*
+  - `revision` **> version** → **404** (không có revision đó). *(v11 nhảy revision=12 khi attachment mới version 9 → §2.1 404.)*
+  - `revision` **= version** → hiển thị đúng bản mới nhất. ✓
+- ✅ **Script `confluence-publish.ps1` giờ TỰ đồng bộ**: sau khi upload attachment `drawio`, đọc version vừa lên rồi ghi đè `<ac:parameter ac:name="revision">` trong macro (khớp `diagramName`) = version đó, và ghi lại vào file storage (repo == live). ⇒ **KHÔNG hand-set revision nữa** — cứ để script lo. (Điều kiện: macro có `diagramName` khớp `name` attachment, và param `revision` nằm SAU `diagramName` trong macro — generator emit đúng thứ tự này.) PNG "exported to image" (`<base>.png`) là preview tĩnh dự phòng, cũng cập nhật theo lần re-upload.
+
+**✅ Checklist mỗi lần vẽ/sửa activity diagram (chạy tuần tự, đừng bỏ bước):**
+1. model.json tuân đủ **7 quy ước vẽ** ở trên (đặc biệt **5 spine cùng cx** + **6 hộp cạnh căn tâm-y** + **7 lane dùng chung viền, không hở khe**).
+2. `node build-activity-diagram.mjs <model.json> <out_dir> <base>` → sinh mxfile + PNG.
+3. **Read lại PNG** (image) xác nhận mũi tên đúng **và các lane khít thành một khối liền** (quy ước 7 — nhìn ảnh là thấy ngay có hở khe hay không) — PNG khớp mxfile 100% (cùng model), nên PNG chuẩn ⇒ mxfile chuẩn.
+4. Publish qua `confluence-publish.ps1 -Manifest ...` (script tự sync revision, không hand-set).
+5. **Verify sau publish**: `get_attachments` → **version attachment mxfile == `revision` trong macro** (log script in "revision auto-synced: … -> N"). Đây là điều kiện SỐNG CÒN để trang hiển thị đúng bản mới (không 404, không kẹt render cũ).
+6. Báo user hard-refresh (Ctrl+F5). Nếu user vẫn thấy sai → **xin screenshot render hiện tại** (đừng blind-fix; so ngay `revision` vs `version` trước tiên).
+
+## 4. Template fidelity — bám ĐÚNG khung template, đừng thêm mục lạ
+
+Fetch template (§3 workflow) rồi map **đúng thứ tự + tên mục**, KHÔNG chèn mục ngoài template. Với **Template API nghiệp vụ** (`199113677`):
+
+1. **Bảng "XÁC ĐỊNH ĐƠN VỊ YÊU CẦU VÀ ĐƠN VỊ LIÊN QUAN"** (10 dòng đơn vị, task-list ĐVYC/ĐVLQ — §1 trên).
+2. **Bảng ghi nhận thay đổi** đúng 8 cột: Ngày (date macro) · Vị trí · A/M/D · Nguồn gốc · Link CR · Mô tả · Phiên bản confluence · Phiên bản mới.
+   - 🎯 **Cột phiên bản = SỐ VERSION TRANG CONFLUENCE sau khi cập nhật** (vd `7`), **KHÔNG** đánh số riêng cho tài liệu kiểu `1.0` / `2.0` (user chốt: "phiên bản cần theo version sau update confluence, k lấy 2.0"). Publish làm version trang `N → N+1` thì dòng mới ghi `N+1`. Thêm 1 dòng ghi chú ngay dưới bảng: *"Cột Phiên bản = số phiên bản trang Confluence sau khi cập nhật."*
+2b. 🎯 **BẤT KỲ ĐOẠN TEXT NÀO CÓ NHIỀU Ý ĐỀU PHẢI TÁCH DÒNG + GẠCH ĐẦU DÒNG — KHÔNG VIẾT DỒN 1 ĐOẠN.**
+   - User chốt 2 lần: *"cần trình bày xuống dòng từng ý, có gạch đầu dòng rõ ràng, k viết chung 1 dòng gây khó nhìn"* → và sau đó: *"cần áp dụng cho **mọi** đoạn text nào có nhiều ý, ví dụ mục 2.2/3.3 cột Mô tả, cột Ghi chú mỗi ô từng bước"*.
+   - **Phạm vi = TOÀN TÀI LIỆU, không chỉ §1**: ô bảng ở **mọi** mục (bảng bước §2.2/§3.3 cột *Mô tả* + *Ghi chú* + *Bảng/Thực thể*, bảng control cột *Mô tả*, bảng mã lỗi, bảng chức năng ảnh hưởng, bảng thực thể, ô *Mô tả thay đổi* của bảng ghi nhận thay đổi) **và** đoạn văn ngoài bảng, kể cả text trong macro `note`/`warning`/`info`.
+   - **Ngưỡng máy móc để khỏi tranh luận:** ô/đoạn có **≥ 2 câu** và **≥ 80 ký tự** → chuyển thành `<ul><li>`, mỗi câu (hoặc mỗi vế `<br />` sẵn có) là một `<li>`. Ô 1 câu hoặc quá ngắn thì để nguyên. Ý có thứ tự → `<ol>`; ý phụ → lồng `<ul>` cấp 2; mỗi nhóm mở đầu bằng `<strong>Nhãn:</strong>`.
+   - Trong **file markdown nguồn** (ô bảng markdown không chứa list thật): dùng `<br>• ` cho cấp 1 và `<br>&nbsp;&nbsp;– ` cho cấp 2.
+   - Việc này **làm lúc sinh nội dung**, đừng để review xong mới đi vá.
+3. **§1 Mô tả chung**: Mục đích · Loại chức năng (task-list Web/Mobile/Tiến trình/API) · Đối tượng sử dụng · Pre/Post-condition · **Chính sách & ràng buộc** ← dồn **NFR/bảo mật/config** vào đây (KHÔNG tách §7 NFR riêng).
+4. **§2 Luồng nghiệp vụ**: 2.1 activity draw.io · 2.2 bảng bước **đúng 5 cột của template** (fetch template `199113677` xác nhận): `Bước · Đối tượng · Mô tả · Ghi chú · Bảng/Thực thể liên quan`. Chi tiết từng cột:
+   - **Mô tả** = ngôn ngữ nghiệp vụ (KHÔNG class/method/endpoint — §3 quy ước 4) **và gộp luôn kết quả/rẽ nhánh vào ô này** (vd "… → Ngoài khung giờ thì bỏ qua, kết thúc"). KHÔNG tách cột "Kết quả/rẽ nhánh" riêng (không có trong template).
+   - **Đối tượng** = **TÊN SERVICE thực hiện** (vd `reconciliation-process`, `reconciliation-external-data-service`), KHÔNG ghi chung chung "hệ thống" (user chê "để tên service ấy, đừng chung chung"). Chỉ **hệ thống ngoài** mới để tên đối tác chung (vd "Core Transfer", "VIB") — kèm chú "(hệ thống ngoài)". Bước gọi ra ngoài: `<service> ↔ <đối tác ngoài>`.
+   - **Bảng/Thực thể liên quan** = **TÊN BẢNG DB THẬT** (`configuration_retrieval_data`, `config_business_list`, `detail_retrieval_data`, `statistic_retrieval_data`, hoặc "MinIO (file tạm)") + loại (truy vấn/insert/update) — **KHÔNG dịch sang tên tiếng Việt** (user chê "để đúng tên bảng/thực thể trong DB đi").
+   - **Bước ghi DB → KHÔNG viết câu lệnh SQL/WHERE/SET**; đặt **NGAY trong ô Mô tả của chính bước đó** (user chê "để dưới khó theo dõi, đưa luôn vào tại bước"). ⚠️ **Bài học 2026-08-11 (HUB-02 v5):** tôi đặt bảng ánh xạ ở mục 4.2 rồi ở bước chỉ ghi *"thêm một dòng vào bảng hồ sơ tổng hợp"* + câu trỏ "chi tiết tại mục 4.2" — user bác ngay: *"B16 cụ thể ghi như nào, trường nào, với giá trị như nào, đừng chỉ ghi chung chung"*. Cross-reference KHÔNG thay được bảng lồng tại bước. Áp cho **MỌI** bước ghi: ghi nghiệp vụ, **ghi log**, và cả **bước ghi khi thất bại** (vd ghi log lần tạo thất bại ở nhánh 409): dòng **`Điều kiện thực hiện/truy vấn:`** (điều kiện chọn bản ghi, WHERE bằng lời) + **bảng lồng 3 cột** `Trường nghiệp vụ | Cột trong CSDL | Giá trị ghi vào` (UPDATE: `Trường nghiệp vụ | Cột trong CSDL | Giá trị mới`) — cột giữa là **tên cột thật** trong DB, và câu dẫn trước bảng phải nêu **tên bảng schema-qualified** (vd "Giá trị ghi vào bảng `bms_hub.composite_requests`:"). Bảng lồng chỉ có tên trường thuần Việt là **CHƯA ĐẠT** (case thật SCR-COMPOSE 2026-08-07 — xem `srs-mapping.md`, mục "Tên trường thuần Việt KHÔNG BAO GIỜ đứng một mình"). **Mỗi bảng bị ghi = 1 bảng lồng riêng**, kể cả bảng nhật ký/audit. Bảng lồng `<table>` trong `<td>` — Confluence Server render OK (đã verify v6).
+   §3 (bảng thực thể) trỏ về các bước này cho **giá trị ghi**, nhưng vẫn phải có bảng lồng `Cột trong CSDL | Ý nghĩa` liệt kê **cấu trúc cột** của từng entity do hệ thống own (không mô tả cấu trúc bảng bằng prose).
+   - **🔗 Crosslink luồng xử lý (process-flow) — BẮT BUỘC nếu feature là một mắt trong chuỗi tiến trình.** Nếu feature được **một tiến trình cha gọi tới** (upstream) và/hoặc **bàn giao sang tiến trình kế tiếp** (downstream), chèn dòng **`Refer`** hyperlink vào ô **Ghi chú** của đúng bước giáp ranh (không tạo mục/section mới):
+     - Bước **entry** (nơi cron/tiến trình cha kích hoạt, thường B1) → `<strong>Refer</strong> (tiến trình cha điều phối): <a href="…viewpage.action?pageId=<UP>">NN. <tên trang tiến trình cha></a>.`
+     - Bước **hand-off/persist cuối** (nơi bàn giao downstream, vd bước gộp file + tạo bản ghi thống kê) → `<strong>Refer</strong> (tiến trình kế tiếp): <a href="…pageId=<DOWN>">NN. <tên trang kế tiếp></a>.`
+     - Đây là convention **có sẵn ở các trang anh em cũ** (vd họ partner-pull `05.01–05.03` đều `Refer: 01. KBNV tiến trình download file dữ liệu đối soát từ đối tác` → pageId `63738338`; downstream = `02. KBNV tiến trình gửi yêu cầu đọc dữ liệu từ file để xử lý đối soát` → `63739095`). **Tìm pageId thật** bằng `confluence_search`/`get_page_children` trên đúng host (KHÔNG bịa link, KHÔNG cross-host). Contract `INT-EXT-*` đã pair-merge (§4) là "gọi ra ngoài" nội trang → KHÔNG cần link ngoài, chỉ trỏ "§4".
+     - Chèn crosslink vào trang có sẵn = **body-only `update_page(content_format="storage")` qua MCP** (không đụng attachment/diagram) — nhanh, không cần chạy `confluence-publish.ps1`.
+5. **§3 Bảng/thực thể**: STT·Bảng·Mô tả·Phát sinh mới·Ý nghĩa·**Loại dữ liệu (task-list Truy vấn/Update/Insert)**. Cột-giá-trị runtime trỏ về §2.2 (đừng lặp bảng riêng).
+6. **§4 Thông tin dữ liệu API — gộp đầu vào + đầu ra THEO TỪNG API**: mỗi API/hop một mục con (vd `4.1 API Hop-1 …`, `4.2 API Hop-2 …`), trong đó **đầu vào (request) rồi đầu ra (response) liền nhau**. KHÔNG tách "4.1 Thông tin đầu vào / 4.2 Thông tin đầu ra" gộp mọi API (user chê "mô tả đầu vào đầu ra cho cùng 1 API luôn"). Bảng field: Thông tin·Require·Maxlength·Mặc định·Mô tả·Ràng buộc (đầu vào), Thông tin·Require·Maxlength·Mô tả (đầu ra). Pair-merge contract INT-EXT vào đây; endpoint phụ (thủ công) + config-driven để mục con cuối.
+7. **§5 Danh sách trường hợp lỗi**: Trường hợp·Mã·**Trạng thái (BẮT BUỘC `ac:task-list` 3 task Thành công/Chưa rõ/Thất bại — KHÔNG unicode ☑/☐, xem §1)**; giải thích để text sau task-list cùng ô.
+
+**Bỏ** các mục skill từng tự thêm ngoài template (§2 "Yêu cầu chức năng" riêng, §7 NFR riêng, §8 "Tài liệu liên quan" đứng riêng) — nội dung gộp vào mục template tương ứng (NFR→§1; tài liệu nguồn→info macro cuối §5).
+
+## 5. XML escaping (nhắc lại — bẫy 400 hay gặp)
+
+Ngoài CDATA, mọi text node tự chèn phải escape `&`→`&amp;`, `<`→`&lt;`, `>`→`&gt;`. Trước khi PUT quét raw `&` bằng `&(?![a-zA-Z]+;|#\d+;|#x[0-9a-fA-F]+;)`. Ưu tiên `→`/`·` thay `>`/`&` trong câu văn. Bên trong `<![CDATA[...]]>` (code/plantuml) thì literal an toàn.

package/skills/NTAPP/.agent/skills/NTAPP-srs-to-confluence/references/srs-mapping.md

@@ -0,0 +1,157 @@
+# SRS Mapping — spec (Stage 4 DD + Stage 5) → khung SRS Confluence
+
+Ưu tiên khung **fetch được từ template Confluence** (workflow §3). Bảng dưới là *cách map nội dung spec vào từng mục* + **fallback khi fetch template lỗi**.
+
+## Khung SRS fallback theo type
+
+**Chung (mọi type):**
+1. Thông tin tài liệu (tên, mã ID, hệ thống, version, lịch sử thay đổi)
+2. Mục tiêu & phạm vi
+3. Actor / đối tượng sử dụng
+4. Thuật ngữ & viết tắt
+5. Yêu cầu chức năng
+6. Luồng nghiệp vụ (sequence)
+7. Yêu cầu dữ liệu
+8. Yêu cầu phi chức năng
+9. Tài liệu liên quan
+
+**type=api — thêm:** Đặc tả API (endpoint, method, request schema, response schema, mã lỗi, config/secret redacted).
+**type=consumer — thêm:** Trigger (scheduler/listener/queue), tần suất, input source, xử lý idempotent/retry, output.
+**type=web — thêm:** Đặc tả màn hình (HTML nhúng), danh sách control, mapping control ↔ API.
+
+## Map nguồn → mục
+
+| Mục SRS | Nguồn spec |
+|:---|:---|
+| Mục tiêu & phạm vi | DD §overview blockquote + story "so that" |
+| Actor | story "As a" + DD actor |
+| Yêu cầu chức năng | DD §logic + story Acceptance Criteria (mỗi AC → 1 yêu cầu) |
+| Luồng nghiệp vụ | DD sequence / `feature_design_parts/{id}/f3_sequence_diagrams_part.md` |
+| Crosslink luồng xử lý | DD §context/entrypoint (tiến trình cha gọi tới = upstream) + bước hand-off downstream → dòng `Refer` hyperlink trong ô Ghi chú §2.2. Chi tiết + cách tìm pageId: `confluence-server-publish.md §4 điểm 4` |
+| Yêu cầu dữ liệu | DD §data (§8.1 field-level) |
+| Đặc tả API | DD contract `INT-EXT-*` (request/response/URL/header/error) — pair-merge nếu chọn merge |
+| Phi chức năng | DD §NFR |
+
+**Redact secret:** User/Pass/ClientId/CIF/account/private-key → chỉ ghi config key + nơi nạp (không ghi giá trị thật).
+
+## Nhúng HTML màn hình (type=web) — HTML macro
+
+> 🔴 **KHÔNG được thay bản mô phỏng HTML bằng bản vẽ draw.io** — kể cả khi các trang SRS anh em trong space đang dùng macro draw.io cho màn hình. Lần SCR-EMBED-PMT đã đi đường tắt này và user bác: *"các màn hình cần vẽ html và đính kèm vào tài liệu, hiện đang vẽ draw.io là k đúng yêu cầu"*. Server `.35` tắt HTML macro ⇒ đi đúng nhánh **fallback** ở cuối mục này: upload `p_screen*.html` làm attachment + chèn **ảnh screenshot inline** (`<ac:image><ri:attachment/>`) + link `<ac:link><ri:attachment/>` để tải bản HTML. Chụp ảnh bằng Chrome headless (`--headless=new --force-device-scale-factor=2 --window-size=W,H --screenshot=...`), cắt sát nội dung, và **Read lại ảnh** trước khi publish.
+
+**Nguồn `p_screen.html`:** SRS skill TỰ render (không delegate) — 1 file HTML self-contained (inline CSS) từ `ui_schema_{id}.json` (layout/component/control) + `{id}-full-screen.md` (mô tả filter/cột/nút/tab/luồng) + DD §UI. `NTAPP-ui-generation` chỉ sinh `ui_schema` khi thiếu (KHÔNG render HTML). Render chưa sát thực tế → tham chiếu code FE thật `*.component.html`/`.ts` render lại.
+
+**Fidelity — BẮT BUỘC bám code FE thật khi màn hình ĐÃ được code (brownfield):** `ui_schema`/story hay drift so với UI thật (màu nút, màu header bảng, layout nhãn/ô). Nếu component đã tồn tại trong repo FE, dựng mock TỪ chính `*.component.html` + file theme (`common.css`/`btn.css`/`style.css`) + nhãn i18n (`vi.json`) — KHÔNG đoán màu/nhãn từ ui_schema. Rút đúng token: class nút thật (vd `btn-blue-green`), màu `thead th`, count, `form-control`, thứ tự + tên cột bảng, thứ tự trường modal. Đối chiếu screenshot mock với UI thật trước khi publish.
+
+**⚠️ DD/Story CŨNG có thể stale — không dừng lại ở "đối chiếu ui_schema", phải đối chiếu tới tận code khi có sẵn.** Case thật (SCR-COMPOSITE-DETAIL, 2026-08-06): SRS v1 dựng đúng theo DD §2.3 + tiêu đề Story ("4 tab Info/Sub-links/Timeline/Sync") — nhưng CẢ HAI nguồn này đã lag so với code đang chạy (CR gỡ tab Sync thành nút header, đổi tên 2 tab còn lại, và 1 AC — "Xác nhận quyết định hàng loạt" — thực ra CHƯA từng được code). User phải tự phát hiện qua ảnh chụp màn hình thật rồi yêu cầu sửa lại. Bài học — khi màn đã có code (brownfield):
+- Tên tab/nhãn control: lấy trực tiếp từ file i18n (`vi.json`/`en.json`) đang được template `{{ 'key' | translate }}` trỏ tới — KHÔNG lấy từ tên biến/AC trong Story (tên biến thường đặt theo ý đồ thiết kế ban đầu, có thể khác nhãn hiển thị thật hoặc đã đổi mà Story quên cập nhật).
+- Mỗi control/button liệt kê trong bảng §2.x PHẢI trỏ được tới đúng dòng code (`*ngIf`, `(click)`, method) đang tồn tại trong `*.component.html`/`.ts` — nếu không tìm thấy, đó là control CHƯA code (hoặc đã gỡ), phải bỏ khỏi bảng dù DD/Story có nhắc tới.
+- Modal vs inline-panel/expand: đọc đúng cơ chế mở (`ModalDynamicService.open(...)` = modal thật; `*ngIf="xPanelOpen"` toggle bằng biến local = inline panel, KHÔNG phải modal) — đặt sai tên mục (vd "Modal Thêm ..." khi thực ra là panel) khiến user đọc xong thao tác trên UI thật không khớp.
+- Khi nghi ngờ 1 mục có vẻ "không đúng thực tế" (user báo hoặc tự thấy lệch) → luôn quay lại đọc code gốc (`.component.html/.ts` + entity BE nếu cần xác nhận tên bảng/cột) trước khi sửa câu chữ — đừng chỉ diễn đạt lại theo DD/Story một lần nữa (2 nguồn đó chính là nguồn gây lệch).
+
+**Bảng ĐVYC/ĐVLQ ("XÁC ĐỊNH ĐƠN VỊ YÊU CẦU...") — không phải lúc nào cũng cần:** mục này chỉ áp cho SRS gốc/độc lập cần quy trình phê duyệt riêng. Nếu target page là **trang con nằm trong 1 cây trang có sẵn** (không do skill này tạo mới từ đầu, ví dụ trang do user chỉ định thủ công nằm trong hierarchy KBNV/nghiệp vụ cũ) và user yêu cầu bỏ mục này (hoặc trang cha/trang anh em cùng cây đã có quy trình phê duyệt riêng ở nơi khác) → bỏ hẳn cả heading + bảng, không giữ lại dạng rút gọn. Mặc định (chưa có chỉ định khác) vẫn giữ theo template gốc.
+
+**Bảng ghi nhận thay đổi tài liệu — GIỮ ĐỦ CỘT theo template gốc (8-10 cột, kèm Link PYC/Story/CR), KHÔNG rút gọn.** Ở lần **tạo mới (A)**, mô tả 1-2 câu tóm tắt phạm vi — KHÔNG liệt kê chi tiết từng control/AC (đó là việc của §2).
+- Dòng mới thêm lên ĐẦU bảng, giữ nguyên toàn bộ dòng cũ, version +1. Sửa câu chữ/lỗi chính tả không đổi nội dung nghiệp vụ thì không chạm bảng này.
+
+**🚫 KHÔNG chèn ghi chú META/NỘI BỘ vào trang — trang phải đọc được như một tài liệu nghiệp vụ độc lập:** mọi câu nói về *cách tài liệu được sinh ra* (tên file spec trong workspace, version spec, role sinh ra nó, tên template đã bám theo, quy ước đánh version của skill) là thông tin vận hành của skill → thuộc **report + log**, TUYỆT ĐỐI không đưa lên trang. Người đọc là cán bộ nghiệp vụ, không truy cập được workspace spec và không cần biết quy trình nội bộ. Hai dạng đã lọt trong case thật (SCR-EMBED-PMT, pageId 199112222, 2026-08-07 — user chỉ ra "2 phần này không mô tả trọn tài liệu"):
+- **info-macro mở đầu trang** kiểu "Kịch bản nghiệp vụ chi tiết (role BA) cho chức năng giao diện ... Theo Template Chức năng FE. Nguồn: tên file detailed design, phiên bản 1.5" → **BỎ HẲN cả macro**, không giữ lại dạng rút gọn. Trang bắt đầu thẳng bằng bảng ghi nhận thay đổi (hoặc mục 1 Mô tả chung theo template).
+- **Câu chú thích in nghiêng dưới bảng ghi nhận thay đổi** kiểu "Cột Phiên bản là số phiên bản trang Confluence sau khi cập nhật, không đánh số riêng cho tài liệu" → **BỎ HẲN**. Quy ước đánh version là chuyện của skill, ghi trong reference này là đủ; đưa lên trang chỉ làm nhiễu người đọc.
+- Nhu cầu truy vết nguồn spec ĐÃ được đáp ứng bằng cột **Nguồn gốc** trong chính bảng ghi nhận thay đổi — không cần nhắc lại ở bất kỳ chỗ nào khác trên trang.
+- Rà soát trước mỗi lần publish: quét toàn bộ storage.xhtml, hễ gặp câu chứa tên file `.md`, chữ "detailed design", "template", "role BA/skill", "spec version", hay giải thích ý nghĩa cột của chính bảng đang hiển thị → xóa. Đây là quy ước **hồi tố** (theo nguyên tắc đã ghi ở mục xuống dòng tách ý): phát hiện 1 chỗ thì quét cả trang, kể cả các trang SRS đã publish trước đó khi có dịp đụng lại.
+
+**Tô màu header mọi bảng — áp dụng THỐNG NHẤT, không phân biệt có trang gốc hay không:** dùng `<th data-highlight-colour="#DEEBFF">` (thay `<td><strong>` mặc định) cho MỌI hàng header của MỌI bảng trong SRS (chuẩn storage-format "Cell background colour", render đúng Server lẫn Cloud). Kể cả khi user chỉ định 1 trang Confluence làm "gốc"/"template chuẩn" mà trang đó đang dùng `<th>` trơn không tô màu → VẪN tô màu theo quy ước này, không cần bám theo trang gốc ở điểm trình bày header.
+
+**Mọi ô mô tả (§1 Mục đích/Precondition/Post-condition, §2.x cột Mô tả chi tiết, §3.3 cột Mô tả chi tiết & Quy tắc xử lý, §4-§6) — xuống dòng tách ý, KHÔNG dồn nhiều ý vào 1 đoạn văn dài:** hễ 1 ô có ≥2 ý độc lập (≥2 điều kiện, ≥2 trường hợp, ≥2 hành động nối tiếp, danh sách liệt kê...) → BẮT BUỘC tách dòng, không viết thành 1 câu/đoạn nối bằng dấu phẩy hoặc chấm phẩy chạy dài. Chọn đúng cách tách theo bản chất nội dung:
+- **Nhiều bước/ý tuần tự nhưng KHÔNG cần rẽ nhánh riêng** (vd 1 câu mô tả 3 API gọi đồng thời, hoặc nhiều điều kiện cộng dồn) → `<ul><li>...</li></ul>` (bullet không đánh số) trong storage-format, mỗi `<li>` 1 ý trọn vẹn.
+- **Có thứ tự bắt buộc / đánh số tham chiếu được** (Precondition 1-2-3, Post-condition 1-2-3-4) → numbered text nội dòng `"1. ...<br/>2. ..."` (đúng phong cách gốc 200765940) hoặc `<ol><li>` nếu template không dùng numbered-inline.
+- **Rẽ nhánh điều kiện (nếu X thì A, nếu Y thì B)** → `<ul><li><strong>Nếu X:</strong> A</li><li><strong>Nếu Y:</strong> B</li></ul>`, bôi đậm điều kiện để dễ quét mắt (đã áp dụng ở B4 case thật SCR-COMPOSITE-DETAIL, 2026-08-06).
+- **⚠️ Không nhét "nếu X thì Y" vào GIỮA 1 bullet bằng dấu gạch ngang "—"** (vd `<li>Truy vấn ... theo id — không thấy dòng nào thì trả 404.</li>` là VẪN SAI dù đã ở trong `<ul>`, vì 1 `<li>` vẫn đang gánh 2 ý: hành động + điều kiện lỗi). Mọi bullet có dạng "làm X — nếu/không Y thì Z" phải tách thành 2 `<li>` riêng: 1 bullet hành động chính + 1 bullet `<strong>Nếu ...:</strong>` cho nhánh điều kiện/lỗi, đúng mẫu đã áp cho "Nếu thành công/Nếu lỗi" ở trên — áp dụng NHẤT QUÁN cho toàn bộ bullet trong `<ul>`, không chỉ bullet đầu/cuối. (Case thật SCR-COMPOSITE-DETAIL 2026-08-06: bullet mô tả Backend Hub xác thực/truy vấn/kiểm tra quyền ở B4 đều nhét điều kiện lỗi bằng "—" dù đã bullet hóa — vẫn bị user chê phải tách tiếp.)
+- **Case thật đã sai (SCR-COMPOSITE-DETAIL v1, 2026-08-05):** mô tả B2 ban đầu viết dồn "Giao diện gọi đồng thời: chi tiết hồ sơ tổng + danh sách yêu cầu thành phần; nếu là Admin, gọi thêm lịch sử thao tác..." thành 1 câu — user phải yêu cầu tách bullet + nêu rõ "là gì" từng phần mới đạt yêu cầu. Bài học: PHẢI tự rà mọi ô mô tả TRƯỚC khi publish, đếm số ý độc lập trong ô — ≥2 ý là phải tách, không chờ user chỉ ra.
+- Áp dụng cả cho nội dung trong `ac:structured-macro ac:name="expand"` (luồng nghiệp vụ chi tiết §3.4) — không viết văn xuôi liền mạch trong đó, ưu tiên bảng bước hoặc `<ul>`/`<ol>` tùy ngữ cảnh (xem quy ước bảng bước ngay trên).
+- **Ngoại lệ — không cần bullet:** cột đã compact theo bản chất bảng (vd cột "Hướng xử lý & Phản hồi FE" trong bảng mã lỗi §5 — nhiều dòng, mỗi ô cố tình ngắn gọn 1-2 mệnh đề) thì để nguyên câu ngắn, KHÔNG ép bullet — bullet hóa mọi ô của 1 bảng dày đặc (10+ dòng) làm bảng phình to, phản tác dụng. Chỉ áp rule này cho các khối mô tả "prose" (§1 Mô tả chung, §2.x cột Mô tả chi tiết, §3.x mô tả bước/luồng, §4.2 mô tả tác động dữ liệu) — nơi 1 ô/đoạn thường gánh nhiều câu dài.
+- **⚠️ Bài học quan trọng (SCR-COMPOSITE-DETAIL, 2026-08-06) — viết rule vào skill KHÔNG tự động sửa nội dung ĐÃ xuất bản trước đó:** lần đầu thêm rule này vào skill, tôi chỉ áp dụng cho nội dung MỚI viết thêm sau đó (B2, B4 ở §3.3) mà quên quét lại toàn bộ tài liệu đã có từ trước (§1 Mục đích/Đối tượng sử dụng/Đường dẫn chức năng, §2.1.2 huy hiệu trạng thái, §2.4 intro, §4.2 bảng thực thể — tất cả đều đang dồn 2-5 ý vào 1 đoạn văn/1 câu dài mà không ai phát hiện tới khi user hỏi lại). **Quy tắc bắt buộc từ nay: mỗi khi thêm 1 convention MỚI vào skill (bất kỳ convention nào, không riêng bullet), phải NGAY LẬP TỨC quét lại toàn bộ file storage.xhtml đang có (đọc hết, không đọc lướt) đối chiếu với convention mới — sửa hết chỗ vi phạm cũ rồi mới coi là xong, không chỉ áp dụng cho phần viết thêm về sau.** Ghi convention vào skill mà không hồi tố lại = nửa vời, user sẽ phải chỉ ra lần 2.
+
+**Header cột "Mô tả chi tiết" ở bảng control §2.x — KHÔNG thêm đuôi "& Quy tắc nghiệp vụ":** control table (§2.1-2.6) mô tả 1 phần tử UI tĩnh (button/badge/field/panel), không phải 1 bước xử lý có "quy tắc nghiệp vụ" riêng → header chỉ để **"Mô tả chi tiết"**. Đuôi "& Quy tắc xử lý"/"& Quy tắc nghiệp vụ" CHỈ giữ cho bảng bước §3.3/§3.4/entity §4.2 — nơi mỗi dòng đúng là 1 bước xử lý có rule/điều kiện thật (case thật SCR-COMPOSITE-DETAIL, 2026-08-07: user chỉ ra header control-table "Mô tả chi tiết & Quy tắc nghiệp vụ" là thừa/sai chỗ).
+
+**Cột "Giá trị mặc định" — CHỈ điền khi control là input thật có default value, còn lại → N/A (nhất quán với cột Require/Maxlength):** không tự chế ra giá trị cho control không có khái niệm "mặc định":
+- **Button** (mọi loại — primary/secondary/icon-button, kể cả disabled/ẩn-hiện theo điều kiện) → LUÔN **N/A**. "enabled"/"ẩn/hiện theo điều kiện" không phải "giá trị mặc định" — đó là hành vi runtime, đã mô tả đủ ở cột Mô tả, nhắc lại ở đây là thừa/gây hiểu lầm (case thật, 2026-08-07: user chỉ ra "button không có giá trị mặc định để N/A chứ").
+- **Badge/banner/table/panel/display-only** (không nhận input) → **N/A**. Nếu có 1 thông tin đáng giữ (vd banner mặc định ẩn, danh sách giới hạn 50 bản ghi) thì DỜI câu đó sang cột Mô tả, KHÔNG để lại "—" hay câu mô tả trong cột Giá trị mặc định.
+- **Input control thật** (textarea, dropdown, date-picker, tab mặc định chọn, checkbox-list mặc định không chọn gì) → giữ giá trị mặc định thật (`""`, `"Tất cả loại sự kiện"`, tab mặc định, "không chọn gì"...).
+- **KHÔNG dùng "—"** cho cột này ở bất kỳ trường hợp nào — chỉ 2 dạng hợp lệ: giá trị thật hoặc `N/A`.
+
+**KHÔNG dùng ký hiệu "§" khi tham chiếu số mục trong văn xuôi SRS (Mô tả/Ghi chú/info-macro/note) — viết "mục X.Y" hoặc thẳng số "X.Y":** case thật (2026-08-07): user chỉ ra "§3.4 là cái gì, 3.4 thôi chứ" — "§" là ký hiệu văn bản luật/quy chuẩn, không tự nhiên với văn phong SRS đang dùng. Áp dụng cho MỌI cross-reference dạng "xem §X", "→ §Y", kể cả trong heading nếu heading có ghi kèm — thay bằng "xem mục X.Y" hoặc "→ mục X.Y" (heading tự thân đã là số thuần "3.4 Luồng nghiệp vụ...", không cần đổi). Đây là quy ước hồi tố — khi user chỉ ra 1 chỗ dùng "§" là sai thì phải quét TOÀN BỘ tài liệu thay hết, không chỉ sửa đúng chỗ được chỉ ra (áp dụng cùng nguyên tắc "viết rule không tự hồi tố" đã ghi ở trên).
+
+**Mapping Nhãn ↔ trường dữ liệu — bảng lồng BẮT BUỘC ở CẢ HAI vị trí: §2.x control table VÀ §3.3/§2.2 bảng bước.** Quy tắc chung, không phụ thuộc vị trí: **hễ 1 ô Mô tả nhắc tới ≥2 field dữ liệu thì ô đó phải nhúng 1 bảng con, KHÔNG liệt kê bằng câu văn.** Tên bảng/cột/trường lấy từ **code thật** (entity / type định nghĩa cột / response DTO — như quy ước Fidelity ở trên), KHÔNG bịa/dịch.
+
+| Vị trí | Loại ô cần bảng lồng | Bảng lồng 3 cột (điển hình) |
+|:---|:---|:---|
+| **§2.x control table** | Control hiển thị ≥2 field (bảng dữ liệu, thẻ thông tin, danh sách…) | `Nhãn cột trên giao diện \| Trường dữ liệu nguồn \| Mô tả` |
+| **§3.3 bước HIỂN THỊ** | Bước "Hiển thị biểu mẫu / bảng / khu vực kết quả …" liệt kê ≥2 field | `Nhãn trên giao diện \| Giá trị khi mở màn \| Mô tả`; bảng kết quả nhiều nhóm → thêm cột nhóm dùng `rowspan` (`Bảng kết quả \| Nhãn cột \| Trường dữ liệu nguồn`) |
+| **§3.3 bước NHẬP** | Bước "Người dùng nhập A và B …" (kể cả ô lọc) | `Nhãn trên giao diện \| Bắt buộc \| Ràng buộc giá trị` |
+| **§3.3 bước GHI** | Bước tạo/cập nhật/ghi nhật ký bản ghi (mỗi bảng bị ghi = 1 bảng lồng riêng, kể cả bảng audit) | `Trường nghiệp vụ \| Cột trong CSDL \| Giá trị ghi vào` (xem `confluence-server-publish.md` §4 điểm 4, mục "Bước ghi DB") |
+| **§4.2 bảng thực thể** | Ô Mô tả của mỗi entity do hệ thống own | `Cột trong CSDL \| Ý nghĩa` — liệt kê cột, KHÔNG viết prose "gồm mã hồ sơ, tên, mô tả…" |
+
+**🔴 Tên trường thuần Việt KHÔNG BAO GIỜ đứng một mình — luôn kèm tên bảng + tên cột THẬT trong CSDL:** bảng lồng chỉ có `Trường | Giá trị ghi vào` (hoặc `Trường | Ý nghĩa`) là **CHƯA ĐẠT** — người đọc không biết dữ liệu nằm ở bảng/cột nào để tra. Bắt buộc:
+- **Tên bảng ghi dạng schema-qualified** (`bms_hub.composite_requests`), nêu ngay ở câu dẫn trước bảng lồng ("Giá trị ghi vào bảng `<schema>.<table>`:") và ở cột "Bảng/thực thể liên quan" của bảng bước — không để trần tên bảng thiếu schema. Schema lấy từ migration SQL / javadoc entity / `V*__create_*.sql`, KHÔNG suy đoán.
+- **Mỗi dòng có đúng 1 cột DB** — không gộp kiểu "Người tạo và thời điểm tạo", "Mã đối tác và mã sản phẩm"; tách thành các dòng riêng để cột `Cột trong CSDL` map 1-1.
+- **Giá trị enum/hằng ghi nguyên văn giá trị lưu xuống** (`InProgress`, `COMPOSITE_CREATED`, `WEB_UI`, `version` = 0, `created_by_partner` = false) — không chỉ dịch nghĩa tiếng Việt. Lấy từ converter/enum thật, không đoán từ tên Java.
+- **Nêu tên ràng buộc/khoá thật khi có** (`uk_subsystem_subid` trên cặp `sub_system` + `sub_id`) thay vì chỉ nói "ràng buộc duy nhất theo cặp phân hệ và mã yêu cầu".
+- **Màn/luồng KHÔNG own DB** (dữ liệu từ API phân hệ khác) — **KHÔNG được dừng ở tên field API.** Bảng lồng thêm cột thứ 3 **"Bảng và cột gốc trong CSDL"**, điền theo thứ tự ưu tiên sau:
+  1. **Repo phân hệ nguồn CÓ trong workspace (multi-root / additional working directories) → BẮT BUỘC truy tới bảng gốc**, không được ghi chung chung. Cách truy (mất ~5 phút, luôn làm được): lấy **base-url + path** của leg từ `application.yml`/`.properties` của service gọi → grep path đó trong repo phân hệ nguồn để ra **controller** → **service impl** → **mapper** (chỗ này cho biết field API lấy từ property nào của entity, kể cả field nối bảng kiểu `merchantTmp.code`) → **entity** (`@Table` + `@Column`, thường qua hằng `TABLE_NAME`/`COLUMN_*`) → **schema** lấy từ `jdbc:` URL trong config. Ghi ra dạng `<table>.<column>` + 1 bullet nêu lược đồ, bảng chính và các cột nối (`@JoinColumn`).
+  2. **Repo KHÔNG có sẵn → ghi tên dịch vụ sở hữu + giao diện gom dữ liệu thật** (vd "Thuộc dịch vụ `product-catalog-cms-be`; HUB-01 gom qua `/private/hubint/pending-requests`") — lấy từ config base-url/path, dùng `rowspan` cho cả nhóm. Chỉ khi đó mới được nói "tên bảng và cột gốc do tài liệu phân hệ đó mô tả".
+  - Tuyệt đối KHÔNG bịa tên bảng của hệ thống khác để lấp cột, và cũng KHÔNG được dùng câu "bảng gốc thuộc tài liệu `<FEATURE-ID>`" như cách thoát khi repo nguồn đang nằm ngay trong workspace.
+  - Nhân đây kiểm luôn **trạng thái thật của từng leg** trong config (vd `enabled-systems`, cờ mock): leg đang chạy dữ liệu mẫu là thông tin nghiệp vụ người đọc cần biết → ghi 1 bullet, đừng mô tả như đã nối thật.
+
+Bước hiển thị ở §3.3 KHÔNG được thay bảng lồng bằng dòng tham chiếu kiểu *"Cấu trúc cột từng bảng nêu ở control số 9 đến 11 mục 2.1"* — cross-reference chỉ được dùng để trỏ **mô tả chi tiết/ràng buộc**, còn bản thân mapping nhãn ↔ trường phải đọc được ngay tại bước. Lặp lại mapping ở 2 chỗ (§2.1 và §3.3) là **có chủ đích**, không tính là trùng lặp: §2.1 đọc theo control, §3.3 đọc theo luồng.
+
+Cột thứ 2 đổi theo **nguồn dữ liệu thật của màn hình** — đây là chỗ dễ hiểu sai nhất, xem đúng 2 biến thể:
+
+| Màn hình | Bảng lồng 3 cột | Khi nào |
+|:---|:---|:---|
+| **Đọc thẳng CSDL** (màn có DB của chính hệ thống) | `Nhãn trên giao diện \| Bảng DB tương ứng \| Trường DB tương ứng & Mô tả` | Tên bảng/cột lấy từ `@Entity`/`@Table`/`@Column` hoặc migration SQL. Đã áp dụng SCR-COMPOSITE-DETAIL §2.1.2 dòng 6. |
+| **FE consumer, KHÔNG own DB** (render field từ response API) | `Nhãn cột trên giao diện \| Trường dữ liệu nguồn (API nào trả về) \| Bảng và cột gốc trong CSDL \| Mô tả` | Tên trường lấy từ type/DTO FE thật (vd hằng định nghĩa cột bảng). **Cột 3 bắt buộc** — truy tới bảng gốc nếu repo phân hệ nguồn có trong workspace, nếu không thì ghi dịch vụ sở hữu + endpoint (xem 2 bước ưu tiên ở trên). Đã áp dụng SCR-COMPOSE §2.1 control 9/10/11 + B16. |
+
+⚠️ **Bài học (SCR-COMPOSE, 2026-08-07 — user phải chỉ ra):** bản v11–v13 để 3 control bảng kết quả ở dạng prose `"Cột: Mã đối tác · Tên đối tác · Tên dịch vụ · Người tạo · Thời gian tạo."` đúng kiểu rule cấm, trong khi bảng lồng thì lại chỉ xuất hiện ở bước ghi dữ liệu §3.3. **Nguyên nhân là lỗ hổng của rule, không phải người viết bỏ qua rule:** rule cũ chỉ nói "field đọc thẳng từ **CSDL**" + cột 2 là "**Bảng DB** tương ứng", nên với màn FE consumer (không own DB, không có bảng nào để điền vào cột 2) thì rule đọc như **không áp dụng** → rơi về prose. Từ nay: **trigger là "control hiển thị ≥2 field", KHÔNG phụ thuộc nguồn là DB hay API**; không có bảng DB thì điền trường của response API, tuyệt đối không hạ xuống prose.
+⚠️ **Bài học lần 2 (SCR-COMPOSE, 2026-08-07 — user lại phải chỉ ra):** ngay sau khi sửa xong 3 control §2.1, §3.3 vẫn còn nguyên các bước hiển thị/nhập viết prose (B2 *"Hiển thị biểu mẫu gồm tên hồ sơ, mô tả và hai ô lọc…"*, B3, B6, và B16 chỉ trỏ *"cấu trúc cột nêu ở control 9 đến 11 mục 2.1"*), trong khi bảng lồng ở §3.3 lại chỉ có ở **bước ghi** B22. **Nguyên nhân lại là lỗ hổng phạm vi của rule:** rule cũ neo vào **vị trí** (`§2.x control`) và ở §3.3 chỉ nói tới **"bước ghi DB"** ⇒ bước *hiển thị*/*nhập* ở §3.3 không thuộc nhánh nào của rule → rơi về prose. Từ nay rule neo vào **bản chất ô** (ô nhắc ≥2 field) áp cho **cả 3 loại bước** (hiển thị / nhập / ghi) ở mọi vị trí.
+- Hai lần liên tiếp cùng một dạng lỗi ⇒ khi sửa 1 vi phạm mapping field, **BẮT BUỘC quét cả tài liệu ở mọi mục có bảng** (§2.x, §3.3, §3.4, §4.2), không sửa xong đúng mục user chỉ rồi dừng.
+⚠️ **Bài học lần 3 (SCR-COMPOSE, 2026-08-07 — user chỉ ra lần thứ ba):** *"phần mô tả này đang chỉ mô tả tên trường, ý nghĩa, chưa rõ bảng lưu db có tên gì"*. Sau khi đã có đủ bảng lồng ở cả §2.1 và §3.3, các bảng lồng của **bước ghi** vẫn chỉ có `Trường | Giá trị ghi vào` với tên trường **thuần Việt** ("Mã hồ sơ", "Người tạo và thời điểm tạo") — không có cột nào cho tên cột DB, tên bảng thì để trần thiếu schema, và §4.2 vẫn mô tả cấu trúc bảng bằng prose. **Nguyên nhân:** rule chỉ yêu cầu *"tên bảng/cột lấy từ code thật, không bịa"* nhưng KHÔNG yêu cầu **phải xuất hiện** tên bảng/cột trong bảng lồng ⇒ bảng lồng đúng hình thức mà vẫn không tra được về DB. Từ nay áp mục "Tên trường thuần Việt không bao giờ đứng một mình" ở trên như điều kiện xuất bản.
+- **Tự kiểm trước khi publish (áp cho MỌI bảng, không riêng control table):** quét mọi ô Mô tả, hễ gặp mẫu `"Cột: A · B · C"` / `"gồm các trường X, Y, Z"` / `"Hiển thị … gồm A, B và C"` / `"Nhập A và B"` / dòng tham chiếu `"cấu trúc cột nêu ở …"` / liệt kê ≥2 tên field trong một câu → phải chuyển thành bảng lồng.
+⚠️ **Bài học lần 4 (SCR-COMPOSE, 2026-08-07 — user rà lại và chỉ ra tiếp):** sau khi vá xong lần 3, **3 bảng kết quả ở §2.1 (control 9/10/11) và bảng lồng B16 vẫn không có tên bảng/cột DB nào** — chỉ có field API + câu "bảng và cột gốc ở phân hệ nguồn thuộc tài liệu HUB-01". **Nguyên nhân KHÔNG phải rule sai mà là do người viết dừng quá sớm:** rule cho phép "không own DB thì trỏ sang tài liệu feature BE", và tôi coi đó là đủ — trong khi **repo phân hệ nguồn (`merchant-profile-service`) đang nằm ngay trong workspace multi-root**, chỉ cần đi 4 bước config → controller → mapper → entity là ra `merchant_profile_service.merchant_service_tmp` + `merchant_tmp.code` / `service.name`. Câu "thuộc tài liệu HUB-01" biến thành **đường thoát hợp lệ hoá việc không tra**. Từ nay: rule bắt buộc thử bước 1 (truy repo trong workspace) TRƯỚC, chỉ rơi xuống bước 2 khi repo thật sự không có.
+- **Nhắc lại nguyên tắc hồi tố:** lần 3 đã sửa bảng lồng ở §3.3/§4.2 mà không quét §2.1 — đúng lỗi "viết rule không hồi tố" đã ghi ở trên, lặp lại lần thứ hai. Khi bổ sung 1 loại thông tin (vd tên cột DB), phải quét **mọi bảng lồng trong tài liệu**, kể cả bảng vừa tạo ở vòng trước.
+- **Tự kiểm bổ sung (lần 3):** quét mọi bảng lồng đã có — nếu bảng nào **không có cột nào chứa tên cột DB thật** (hoặc tên field API thật với màn không own DB), hoặc câu dẫn trước bảng **không nêu tên bảng schema-qualified**, thì bảng đó chưa đạt. Grep nhanh: tên cột DB thường ở dạng `snake_case` trong `<code>` — bảng lồng của bước ghi/entity mà không có `<code>` nào là dấu hiệu vi phạm.
+
+**§3.3/§2.2 bảng bước — mô tả luồng truy vấn/ghi CSDL khi user cần xem (áp dụng cả template FE lẫn API):** mô tả bằng lời, tên bảng/cột DB **thật** lấy từ entity code (`@Entity`/`@Table`/`@Column` Java, hoặc migration SQL) — KHÔNG bịa/dịch sang tiếng Việt, KHÔNG viết SQL. Chọn 1 trong 2 vị trí đặt nội dung này tuỳ theo có trang gốc chỉ định hay không:
+- **Không có trang gốc chỉ định (mặc định):** thêm 1 cột riêng "Luồng CSDL" ngay trong bảng bước §3.3/§2.2 (hoặc dòng riêng trong ô Ghi chú nếu template không cho thêm cột).
+- **Có trang gốc chỉ định và trang đó gộp chi tiết CSDL vào bảng thực thể riêng (case 200765940, §4.2 "Bảng tác động dữ liệu"):** dồn hết chi tiết điều kiện CSDL vào cột Mô tả của bảng thực thể §4.2, KHÔNG tách cột riêng ở §3.3 — giữ bảng bước gọn theo đúng gốc, mọi query/update detail nằm ở đúng 1 chỗ (§4.2) tránh lặp 2 nơi.
+
+**HTML tương tác — wire ĐỦ mọi modal/popup:** khi file HTML mô phỏng cho tải về (interactive), phải liệt kê MỌI `ng-template`/modal trong component thật và nối MỌI nút mở popup (`onShowModal`, `open*.emit()`, ...) tới đúng modal của nó. Nút bấm không hiện popup = mock lỗi. Mỗi modal dựng đủ trường + nhãn i18n như code; test bằng cách bấm từng nút (hoặc chụp từng modal ở trạng thái mở) trước khi publish.
+
+Lấy nội dung trong `<body>...</body>` của `p_screen.html`, bọc vào macro:
+
+```xml
+<ac:structured-macro ac:name="html">
+  <ac:plain-text-body><![CDATA[
+  <!-- nội dung <body> của p_screen.html, inline CSS -->
+  ]]></ac:plain-text-body>
+</ac:structured-macro>
+```
+
+**Fallback** (HTML macro bị admin chặn → update/create lỗi macro, hoặc user báo trắng — server `.35` TẮT HTML macro): upload `p_screen.html` làm attachment **qua REST script `scripts/confluence-publish.ps1`** (MCP `confluence_upload_attachment` FAIL trên Confluence Server — xem `confluence-server-publish.md` §0) + chèn link "📎 Tải HTML màn hình" + (nếu render được) ảnh screenshot inline. Ghi rõ fallback trong report + log.
+
+## Map changelog spec → SRS
+
+Cấu trúc 1 dòng bảng "LỊCH SỬ THAY ĐỔI"/"Bảng ghi nhận thay đổi tài liệu": Ngày · Vị trí · Loại (A khi tạo mới / M khi update / D khi xóa) · Nguồn gốc (spec version DD+story) · Mô tả (tóm tắt delta) · Phiên bản (số version trang Confluence sau khi cập nhật). Giữ nguyên dòng cũ, dòng mới thêm lên đầu.
+
+Mỗi lần publish có thay đổi nội dung nghiệp vụ → thêm 1 dòng tương ứng.
+
+### KHÔNG thêm dòng khi publish chỉ là sửa cách trình bày
+
+Bảng ghi nhận thay đổi chỉ ghi **thay đổi nghiệp vụ** — thứ làm người đọc phải đọc lại và làm QA phải test lại. Publish thuộc các loại dưới đây **KHÔNG được thêm dòng**, chỉ ghi vào `versionMessage` + log sync:
+
+- Chuẩn hóa thuật ngữ theo `terminology.md` (đổi cách gọi, nghiệp vụ y nguyên).
+- Làm rõ / chi tiết hóa mô tả sẵn có (vd bước ghi dữ liệu từ mô tả chung chung → bảng lồng đủ bảng + cột + giá trị), khi hành vi hệ thống không đổi.
+- Sửa lỗi chính tả, format, bố cục, vẽ lại sơ đồ mà luồng không đổi, sửa lỗi tự gây ở lần publish trước.
+
+> **Bài học 2026-08-11 (HUB-01 v13 / HUB-02 v8):** tôi thêm 1 dòng "Chuẩn hóa thuật ngữ..." vào bảng cho đợt rà soát chữ nghĩa; user bác — *"việc điều chỉnh này k tạo thành 1 thay đổi ở bảng ghi nhận thay đổi"*. Phải gỡ dòng rồi publish lại. Hệ quả bình thường và chấp nhận được: version trang Confluence chạy tiếp (12→13) trong khi dòng mới nhất của bảng vẫn dừng ở version cũ (11) — cột phiên bản ghi version **tại thời điểm thay đổi nghiệp vụ đó**, không phải version hiện hành của trang.
+
+Không chắc thuộc loại nào → hỏi user trước khi thêm dòng, đừng mặc định thêm.

package/skills/NTAPP/.agent/skills/NTAPP-srs-to-confluence/references/terminology.md

@@ -0,0 +1,50 @@
+# REFERENCE: Từ điển thuật ngữ SRS — dùng từ nào, KHÔNG tự dịch thuần Việt
+
+> **BẮT BUỘC đọc trước khi sinh nội dung SRS** (workflow §4) và **quét lại trước khi publish** (§9).
+> Lý do tồn tại: user bác 2 lần vì skill tự dịch thuật ngữ kỹ thuật sang tiếng Việt lạ tai —
+> *"Khóa lạc quan là gì vậy? nếu là version thì cứ để là version"*, *"Nhật ký là việc lưu log đúng k → để là 'lưu log' k cần chuyển thuần việt như vậy"* (2026-08-11).
+
+## Nguyên tắc
+
+**Thuật ngữ mà đội dự án vốn nói bằng tiếng Anh thì GIỮ tiếng Anh.** Chỉ dịch sang tiếng Việt khi
+từ tiếng Việt đó là cách đội đang thật sự gọi. Người đọc là BA/QA/PO trong đội — họ quen `version`,
+`log`, `cache`; họ KHÔNG quen "khóa lạc quan", "nhật ký kiểm toán", "bộ nhớ đệm".
+
+Tự kiểm: đọc câu ra thành tiếng, nếu nghe như bản dịch sách giáo khoa chứ không như lời một
+người trong đội nói → dùng từ tiếng Anh.
+
+## Bảng chuẩn hóa (áp dụng cho MỌI trang SRS)
+
+| ❌ KHÔNG dùng | ✅ Dùng | Ghi chú |
+|:---|:---|:---|
+| khóa lạc quan · optimistic lock (dịch) | **version** | Nói thẳng "version dùng để chống ghi đè khi hai người sửa cùng lúc" |
+| nhật ký · nhật ký kiểm toán | **log** | "ghi log", "bảng log", "log lần tạo thất bại" |
+| bộ nhớ đệm | **cache** | "tra cache", "ghi cache", "cache giữ 30 giây" |
+| mã nối vết | **trace id** | |
+| giao dịch (theo nghĩa DB transaction) | **transaction** | ⚠️ Bắt buộc: hệ thống này là hệ tài chính, "giao dịch" nghĩa là giao dịch tiền → dùng "giao dịch" cho DB transaction gây hiểu sai nghiệp vụ |
+| ảnh chụp trạng thái | **snapshot** | |
+| cờ suy giảm | **cờ degraded** | Giữ "cờ" + từ tiếng Anh |
+| bản ghi mồ côi | **bản ghi rác** | Hoặc diễn đạt lại bằng lời |
+
+## Giữ nguyên tiếng Việt (KHÔNG đổi sang tiếng Anh)
+
+`bảng` · `cột` · `trường` · `khóa chính` · `khóa ngoại` · `ràng buộc duy nhất` · `phân vùng` ·
+`đối tác` · `sản phẩm` · `chính sách phí` · `hồ sơ tổng hợp` · `yêu cầu thành phần` · `phân hệ` ·
+`phiên đăng nhập` · `thẻ đăng nhập` — đây là từ đội đang dùng thật, dịch ngược sang tiếng Anh mới là sai.
+
+## Quy tắc hồi tố
+
+Bảng này **áp cho cả trang đã publish**: khi bổ sung một dòng mới vào bảng, phải quét lại các trang
+SRS đã xuất bản và sửa luôn (cùng nguyên tắc "viết rule không tự hồi tố" ở `srs-mapping.md`).
+Bổ sung dòng mới mỗi khi user chỉ ra một từ dịch không tự nhiên — đừng chỉ sửa đúng chỗ được chỉ.
+
+## Phạm vi quét — nhớ cả file model sơ đồ
+
+Khi áp bảng này, quét **4 loại file** của mỗi feature ID, không chỉ file chữ:
+
+1. `{id}_srs.md`
+2. `{id}_srs_confluence.storage.xhtml`
+3. **`{id}-activity.model.json`** — nhãn node/edge của sơ đồ hoạt động
+4. `p_screen.html` (nếu là SRS web) — nhãn trên bản mô phỏng màn hình
+
+> **Bài học 2026-08-13 (HUB-01/HUB-02):** đợt chuẩn hóa thuật ngữ 2026-08-11 chỉ quét mục 1 và 2. Hai ngày sau user mở trang và thấy sơ đồ vẫn ghi "bộ nhớ đệm", "mã nối vết", "nhật ký kiểm toán", "suy giảm" — nhãn sơ đồ là thứ người đọc thấy trước cả bảng mô tả. Sửa model xong phải **chạy lại** `build-activity-diagram.mjs` rồi publish lại, nếu không attachment trên trang vẫn là bản cũ.