@trungtamcongnghedigital/vsaf 1.0.0

package/skills/NTAPP/.agent/skills/NTAPP-dd-to-confluence/references/confluence-api.md

@@ -0,0 +1,121 @@
+# Confluence REST API — GET / POST / PUT / duyệt cây
+
+Skill dùng REST API của Confluence (Server/DC). Chạy trong Git Bash trên Windows; ưu tiên `curl` + `python3` để build/parse JSON an toàn (XHTML lớn dễ vỡ nếu escape tay trong shell).
+
+## Credentials
+
+Đọc từ `{env_file}` — đường dẫn được resolve theo thứ tự ưu tiên ở `workflow.md` §2 (config key `confluence.env_file` → biến môi trường `CONFLUENCE_ENV_FILE` → các vị trí tương đối `.env/env.md`, `.env`, `env.md` tính từ project root → `$HOME/.env/env.md`; không tìm thấy → DỪNG hỏi user). KHÔNG hardcode đường dẫn tuyệt đối theo máy cụ thể.
+- `CONFLUENCE_URL` — base URL (vd `http://10.254.136.35:8090`).
+- `CONFLUENCE_TOKEN` — Bearer token (Personal Access Token).
+- (tuỳ chọn) host thứ hai nếu env khai báo.
+
+Quy tắc host: **dùng đúng host của link/URL đang xử lý** (`10.254.136.32:8090` hoặc `10.254.136.35:8090`), cùng token. **Không** tự thử host còn lại khi lỗi — DỪNG hỏi user. **Không in token** ra output/log.
+
+```bash
+# Ví dụ nạp biến (không echo token)
+CONFLUENCE_TOKEN="$(grep -E '^CONFLUENCE_TOKEN' "$ENV_FILE" | head -1 | cut -d= -f2- | tr -d ' "')"
+```
+
+## Đọc trang (GET storage-format)
+
+```bash
+curl -s -H "Authorization: Bearer $CONFLUENCE_TOKEN" -H "Accept: application/json" \
+  "$HOST/rest/api/content/$PAGE_ID?expand=body.storage,version,ancestors,space" \
+  > page.json
+# Trích các trường cần
+python3 - <<'PY'
+import json
+d=json.load(open('page.json'))
+print("TITLE:", d.get('title'))
+print("VERSION:", d.get('version',{}).get('number'))
+print("SPACE:", d.get('space',{}).get('key'))
+# body.storage.value chứa XHTML storage-format
+open('page_body.xhtml','w',encoding='utf-8').write(d.get('body',{}).get('storage',{}).get('value',''))
+PY
+```
+
+Từ URL dạng `.../pages/viewpage.action?pageId=NNN` → `PAGE_ID=NNN`. Từ URL dạng `/display/SPACE/Title+With+Plus` → GET theo title:
+```bash
+curl -s -H "Authorization: Bearer $CONFLUENCE_TOKEN" \
+  "$HOST/rest/api/content?spaceKey=$SPACE&title=$TITLE_ENCODED&expand=body.storage,version"
+```
+
+## Duyệt cây trang con (đệ quy)
+
+Trang quản lý DD có thể chứa nhiều tầng thư mục con. Duyệt BFS/DFS qua `child/page`:
+
+```bash
+curl -s -H "Authorization: Bearer $CONFLUENCE_TOKEN" \
+  "$HOST/rest/api/content/$PARENT_ID/child/page?limit=100&expand=version" > children.json
+# Lấy id + title; nếu 'size' == limit thì phân trang tiếp bằng ?start=
+```
+
+Đệ quy: với mỗi child, lại GET `child/page` của nó cho tới khi hết. Match title gần giống tên feature (so khớp không dấu, lowercase, chứa mã ID hoặc tên tính năng) → GET body kiểm chứng nội dung đúng feature trước khi quyết định UPDATE.
+
+Ghi chú phân trang: response có `_links.next` khi còn trang; lặp cho tới khi hết.
+
+## Tạo trang mới (POST)
+
+Build payload bằng python để tránh vỡ escape (đọc XHTML từ file):
+
+```bash
+python3 - "$SPACE" "$PARENT_ID" "$TITLE" body.xhtml payload.json <<'PY'
+import json,sys
+space,parent,title,bodyfile,out=sys.argv[1:6]
+body=open(bodyfile,encoding='utf-8').read()
+payload={"type":"page","title":title,"space":{"key":space},
+ "ancestors":[{"id":int(parent)}],
+ "body":{"storage":{"value":body,"representation":"storage"}}}
+json.dump(payload,open(out,'w',encoding='utf-8'))
+PY
+
+curl -s -X POST -H "Authorization: Bearer $CONFLUENCE_TOKEN" \
+  -H "Content-Type: application/json" \
+  --data @payload.json "$HOST/rest/api/content" > created.json
+python3 -c "import json;d=json.load(open('created.json'));print(d.get('id'), d.get('_links',{}).get('base','')+d.get('_links',{}).get('webui',''))"
+```
+
+## Cập nhật trang (PUT)
+
+Bắt buộc `version.number = version_cũ + 1`.
+
+```bash
+python3 - "$PAGE_ID" "$TITLE" "$NEW_VERSION" body.xhtml payload.json <<'PY'
+import json,sys
+pid,title,ver,bodyfile,out=sys.argv[1:6]
+body=open(bodyfile,encoding='utf-8').read()
+payload={"id":pid,"type":"page","title":title,
+ "version":{"number":int(ver)},
+ "body":{"storage":{"value":body,"representation":"storage"}}}
+json.dump(payload,open(out,'w',encoding='utf-8'))
+PY
+
+curl -s -X PUT -H "Authorization: Bearer $CONFLUENCE_TOKEN" \
+  -H "Content-Type: application/json" \
+  --data @payload.json "$HOST/rest/api/content/$PAGE_ID" > updated.json
+```
+
+## Upload attachment (chỉ khi cần)
+
+```bash
+curl -s -X POST -H "Authorization: Bearer $CONFLUENCE_TOKEN" \
+  -H "X-Atlassian-Token: nocheck" \
+  -F "file=@diagram.png" \
+  "$HOST/rest/api/content/$PAGE_ID/child/attachment"
+```
+
+## Bảng lỗi
+
+| Mã | Nguyên nhân | Xử lý |
+|:---|:---|:---|
+| 401 | Token sai/hết hạn | DỪNG, báo user kiểm tra `CONFLUENCE_TOKEN` trong env |
+| 403 | Không đủ quyền ghi/không gian bị khoá | DỪNG, báo user liên hệ admin / kiểm tra quyền space |
+| 404 | pageId/space/title sai | DỪNG, hỏi user (không thử host khác) |
+| 409 | Version conflict (PUT sai số version) | GET lại version mới → rebuild → preview lại |
+| Body rỗng/parse fail | Response lỗi | Chạy lại curl bỏ pipe python để xem raw; DỪNG báo user |
+
+## Lưu ý an toàn
+
+- Mọi POST/PUT chỉ chạy **sau** khi user xác nhận ở Bước 7.
+- Dọn file tạm (`*.json`, `*.xhtml`) vào thư mục scratchpad, không để rác trong repo.
+- Không log token; log chỉ ghi host/pageId/version/action.

package/skills/NTAPP/.agent/skills/NTAPP-dd-to-confluence/references/mermaid-to-plantuml.md

@@ -0,0 +1,93 @@
+# Mermaid → PlantUML (house-style) + PlantUML Macro
+
+DD spec chứa sơ đồ ` ```mermaid `. Confluence của dự án có **PlantUML Macro** (đã xác nhận). Convert Mermaid → PlantUML, nhúng vào PlantUML Macro.
+
+## Xác định đúng tên macro (probe trước khi build)
+
+Tên macro trong storage-format khác nhau tuỳ plugin. **Không đoán** — lấy mẫu thật:
+
+1. GET storage của một trang DD hiện có đang dùng PlantUML (vd trang trong `9.3.4. Reconcile Service`), tìm `<ac:structured-macro ac:name="...">` bao quanh code `@startuml`.
+2. Lấy `ac:name` (vd `plantuml`, `plantumlcloud`, `plantuml-render`...) và tên tham số body (thường `<ac:plain-text-body><![CDATA[ ... ]]></ac:plain-text-body>`).
+3. Dùng đúng `ac:name` + cấu trúc body đó khi build. Nếu không probe được → DỪNG hỏi user, hoặc fallback Code Block (xem cuối file).
+
+Khung điển hình:
+```xml
+<ac:structured-macro ac:name="PLANTUML_MACRO_NAME">
+  <ac:plain-text-body><![CDATA[@startuml
+... nội dung PlantUML ...
+@enduml]]></ac:plain-text-body>
+</ac:structured-macro>
+```
+
+## House-style preamble (bắt buộc cho sequence)
+
+Theo mẫu DD của tổ chức, mỗi sequence PlantUML mở đầu bằng:
+
+```
+@startuml
+skinparam sequence {
+    ArrowThickness 2
+    ParticipantBorderColor #2c3e50
+    ParticipantBackgroundColor #ecf0f1
+    LifeLineBorderColor #7f8c8d
+    LifeLineBackgroundColor #bdc3c7
+    ArrowColor #2980b9
+    ParticipantFontColor #2c3e50
+}
+skinparam titleFontSize 18
+
+title <tiêu đề sơ đồ>
+```
+và kết bằng `@enduml`.
+
+## Ánh xạ cú pháp — sequenceDiagram
+
+| Mermaid | PlantUML |
+|:---|:---|
+| `sequenceDiagram` | (bỏ — dùng preamble ở trên) |
+| `actor A as Tên` | `actor "Tên" as A` |
+| `participant P as Tên` | `participant "Tên" as P` |
+| (queue/topic) | `queue "Tên" as X` |
+| (DB/redis) | `database "Tên" as X` |
+| `A->>B: msg` | `A -> B : msg` |
+| `A-->>B: msg` (dashed reply) | `A --> B : msg` |
+| `Note over A: text` | `note over A : text` |
+| `Note right of A: text` | `note right of A : text` |
+| `activate A` / `deactivate A` | `activate A` / `deactivate A` |
+| `alt/else/end` | `alt/else/end` |
+| `opt/end` | `opt/end` |
+| `loop X/end` | `loop X/end` |
+| `par/and/end` | `par/and/end` |
+| `autonumber` | `autonumber` |
+| `<br/>` trong label | `\n` |
+
+Giữ nguyên thứ tự khai báo participant như Mermaid để layout ổn định.
+
+## Ánh xạ cú pháp — flowchart
+
+| Mermaid | PlantUML (dùng activity mới) |
+|:---|:---|
+| `flowchart TD` / `graph TD` | `@startuml` + `start` ... `stop` |
+| `A[Việc]` | `:Việc;` |
+| `A{Điều kiện}` | `if (Điều kiện?) then (yes) ... else (no) ... endif` |
+| `A --> B` | thứ tự tuần tự các `:...;` |
+| nhánh label `-->|yes|` | nhánh `then (yes)` / `else (no)` |
+
+Flowchart phức tạp (nhiều nhánh chéo, subgraph) khó map 1-1 → nếu không chắc chính xác thì **fallback Code Block** thay vì vẽ sai.
+
+## Fallback — Code Block macro
+
+Áp dụng khi: không probe được tên PlantUML macro, hoặc diagram không convert gọn/đúng.
+
+```xml
+<ac:structured-macro ac:name="code">
+  <ac:parameter ac:name="language">text</ac:parameter>
+  <ac:plain-text-body><![CDATA[<nguyên source mermaid>]]></ac:plain-text-body>
+</ac:structured-macro>
+```
+
+Mỗi lần fallback phải **ghi vào log + report** (diagram nào, lý do) để user biết cần chỉnh tay.
+
+## Escape
+
+Nội dung trong `<![CDATA[ ... ]]>` không cần escape XML. Chỉ đảm bảo source không chứa chuỗi `]]>`; nếu có, tách thành `]]]]><![CDATA[>`.

package/skills/NTAPP/.agent/skills/NTAPP-dd-to-confluence/references/storage-format.md

@@ -0,0 +1,91 @@
+# Markdown DD spec → Confluence storage-format (XHTML)
+
+Confluence lưu body dạng **storage format** (XHTML mở rộng). Map từng phần tử Markdown của DD spec sang XHTML. Khuyến nghị dùng thư viện convert + hậu xử lý, hoặc build tay theo bảng dưới. Toàn bộ text phải escape XML (`&` → `&amp;`, `<` → `&lt;`, `>` → `&gt;`) TRỪ trong `<![CDATA[...]]>`.
+
+## Ngôn ngữ & đối tượng đọc (BẮT BUỘC — xem workflow §Iron Rules 6/7 + §Nguyên tắc trình bày)
+
+- **Giữ nguyên dấu tiếng Việt** ở mọi text (heading, prose, ô bảng, chú thích trong CDATA). Body gửi API là UTF-8 — ký tự có dấu giữ nguyên, hoặc dùng numeric entity `&#7841;`. **Không strip dấu / viết không dấu.** Nếu build bằng script sinh XHTML: viết string tiếng Việt có dấu trực tiếp và ghi file `encoding='utf-8'`, gửi curl với `Content-Type: application/json; charset=utf-8`.
+- **Prose cột "Mô tả xử lý" viết cho tester/BA**, không phải chép code: dịch lời gọi hàm/tham số kỹ thuật (`Class.method(...)`, `PageRequest.of(...)`, kiểu Java, tên biến nội bộ) sang ý nghĩa nghiệp vụ. Giữ nguyên endpoint/path, tên tham số request, ngưỡng số, mã lỗi (dữ liệu test).
+- **Điều kiện + mã lỗi giữ đúng, thêm chú thích ý nghĩa trong ngoặc:** `totalElements == 0 (số bản ghi tìm được) → PMT-019 (không có dữ liệu export)`.
+
+## Ánh xạ phần tử cơ bản
+
+| Markdown | Storage-format XHTML |
+|:---|:---|
+| `# H1` | `<h1>...</h1>` |
+| `## H2` / `### H3` | `<h2>...</h2>` / `<h3>...</h3>` |
+| đoạn văn | `<p>...</p>` |
+| `**bold**` | `<strong>...</strong>` |
+| `*italic*` | `<em>...</em>` |
+| `` `code` `` | `<code>...</code>` |
+| `- item` (list) | `<ul><li>...</li></ul>` |
+| `1. item` | `<ol><li>...</li></ol>` |
+| `[text](url)` | `<a href="url">text</a>` |
+| `---` (hr) | `<hr/>` |
+| code block ` ``` ` | Code Block macro (xem dưới) |
+| ` ```mermaid ` | PlantUML Macro (xem `mermaid-to-plantuml.md`) |
+| bảng `| a | b |` | `<table>...` (xem dưới) |
+
+## Bảng
+
+```xml
+<table>
+  <tbody>
+    <tr><th>Cột 1</th><th>Cột 2</th></tr>
+    <tr><td>giá trị</td><td>giá trị</td></tr>
+  </tbody>
+</table>
+```
+Nội dung ô có thể chứa `<p>`, `<code>`, `<a>`. Xuống dòng trong ô: `<br/>`.
+
+## Code block (không phải diagram)
+
+```xml
+<ac:structured-macro ac:name="code">
+  <ac:parameter ac:name="language">java</ac:parameter>
+  <ac:plain-text-body><![CDATA[<code nguyên văn>]]></ac:plain-text-body>
+</ac:structured-macro>
+```
+`language`: map từ info-string của code fence (`json`, `yaml`, `sql`, `bash`...). Không rõ → `text`.
+
+## Macro tiện ích (dùng khi Template có)
+
+- Mục lục: `<ac:structured-macro ac:name="toc"/>`.
+- Info/Note panel: `<ac:structured-macro ac:name="info"><ac:rich-text-body><p>...</p></ac:rich-text-body></ac:structured-macro>`.
+
+## Expand macro (thu gọn / mở rộng)
+
+Dùng để nhúng curl / SQL / Response / Kafka message mẫu vào bảng mô tả nghiệp vụ (xem workflow §6D). Body là rich-text nên bên trong **bọc một Code Block macro** đúng ngôn ngữ.
+
+```xml
+<ac:structured-macro ac:name="expand">
+  <ac:parameter ac:name="title">Expand</ac:parameter>
+  <ac:rich-text-body>
+    <ac:structured-macro ac:name="code">
+      <ac:parameter ac:name="language">bash</ac:parameter>
+      <ac:plain-text-body><![CDATA[<curl / SQL / JSON nguyên văn>]]></ac:plain-text-body>
+    </ac:structured-macro>
+  </ac:rich-text-body>
+</ac:structured-macro>
+```
+
+- `title` = `Expand` (khớp mẫu Confluence hiện có).
+- `language` map theo loại nội dung: curl → `bash`; SQL → `sql`; Response / Kafka message → `json`.
+- Đặt Expand **ngay trong ô** "Logic xử lý nội bộ" của bước tương ứng (sau đoạn prose mô tả bước). Expand nằm trong `<td>` là storage hợp lệ.
+- Nếu một bước cần chú thích mapping tham số (vd `:params` của SQL, `Trong đó:`), giữ nguyên phần chú thích đó **bên trong** `<![CDATA[...]]>` của Code Block (giống mẫu spec), không tách ra XHTML.
+- **BẮT BUỘC với SQL/curl có tham số — thêm khối "trong đó:" ở cuối** (xem workflow §6D.d): sau lệnh, cách 1 dòng trống, thêm `-- trong đó:` (SQL/bash) hoặc `// trong đó:` (JSON), liệt kê từng tham số: tên — ý nghĩa nghiệp vụ — **nguồn/lấy ở bước nào** (vd "người dùng nhập ở B2", "server default ở B3", "hằng số"). Nội dung faithful theo §4.1 Mapping Field + §3.2 Logic Matrix, không bịa. Chú thích viết bằng tiếng Việt có dấu, để trong CDATA nên không cần escape.
+
+## Map theo Template DD Core
+
+- **Giữ đúng thứ tự + tiêu đề mục** như Template fetch được ở workflow Bước 2 (không tự đổi tên mục).
+- Mục Template có nhưng spec **không có dữ liệu** → ghi `<p>N/A</p>` (giống mẫu tổ chức: "6. Yêu cầu phi chức năng: N/A", "8.1 Thiết kế CSDL: N/A").
+- Nội dung DD spec map vào **đúng mục tương ứng** của Template; nếu spec có mục không nằm trong Template → gộp vào mục gần nghĩa nhất hoặc đặt cuối, và ghi chú trong log.
+- Bảng changelog: theo cột Template "BẢNG GHI NHẬN THAY ĐỔI TÀI LIỆU" (xem workflow Bước 5+6, map cột).
+- Bảng "Danh sách tài liệu tham khảo": lấy các link tham chiếu trong DD spec (TechSpec, Module 0, WBS, CR/Jira) → 2 cột Tên tài liệu · Link.
+
+## Nguyên tắc an toàn convert
+
+- Không mất nội dung: mọi mục/bảng/đoạn của spec phải có mặt (hoặc N/A) trên trang.
+- Không tự thêm nội dung không có trong spec.
+- Escape XML đúng để tránh vỡ trang; test bằng cách GET lại storage sau khi ghi (chỉ khi user đã confirm ghi) — nhưng không sửa tiếp nếu không cần.
+- Verify nhanh: đếm số `<h2>`/`<table>`/macro so với số mục/bảng/diagram nguồn để phát hiện thiếu.

package/skills/NTAPP/.agent/skills/NTAPP-dd-to-confluence/workflow.md

@@ -0,0 +1,207 @@
+# WORKFLOW: NTAPP — DD → Confluence
+
+Đồng bộ DD của một mã tính năng từ spec workspace lên Confluence theo Template DD Core.
+
+**Iron Rules (không được vi phạm):**
+1. Spec DD là source of truth — chỉ đọc, không tự bịa nội dung khi map.
+2. Mọi thao tác ghi Confluence (POST/PUT/upload) DỪNG preview + chờ user xác nhận (§ Bước 7).
+3. Không đoán trang đích / hệ thống / nơi quản lý DD. Không xác định được → DỪNG hỏi user.
+4. Dùng đúng host trong link đang xử lý; không tìm chéo host; lỗi → DỪNG hỏi user.
+5. Không hardcode host/space/parent/pageId trong nội dung sinh ra — lấy từ link/API tại runtime (trừ pageId index đã biết ở §2).
+6. **Giữ nguyên dấu tiếng Việt** trong MỌI nội dung ghi lên Confluence (heading, prose, ô bảng, chú thích trong Expand). Body gửi API dạng UTF-8 → ký tự có dấu giữ nguyên hoặc numeric entity (`ạ`...). TUYỆT ĐỐI không strip dấu / viết không dấu để "né encoding" — sai encoding thì sửa cách gửi (charset), không sửa bằng cách bỏ dấu.
+7. **Đối tượng đọc gồm cả tester/BA, không chỉ dev.** Prose mô tả bước phải hiểu được bởi người không đọc code — xem §Nguyên tắc trình bày nội dung.
+
+---
+
+## Nguyên tắc trình bày nội dung (đối tượng đọc: dev + tester/BA)
+
+Áp cho mọi prose sinh ra (đặc biệt cột "Mô tả xử lý"/"Logic xử lý nội bộ" của bảng các bước, và chú thích trong Expand). Mục tiêu: tester/BA đọc để viết testcase, không cần đọc source code.
+
+1. **Diễn đạt bằng ngôn ngữ nghiệp vụ, KHÔNG chép nguyên lời gọi hàm/kỹ thuật.** Lời gọi method + tham số kỹ thuật (`ClassName.method(request, false, PageRequest.of(0, 10000))`, tên biến nội bộ, kiểu Java) → dịch sang ý nghĩa nghiệp vụ.
+   - ❌ `gọi merchantStore.searchMerchant(request, false, PageRequest.of(0, 10000))`
+   - ✅ `thực hiện tìm kiếm danh sách merchant theo phân trang (10.000 dòng/trang)`
+   - Nếu cần nêu tên class/method cho dev → để trong Expand hoặc cột "Chi tiết" phụ, KHÔNG nhét vào câu mô tả bước chính.
+2. **Điều kiện rẽ nhánh + mã lỗi BẮT BUỘC giữ ĐÚNG** (tên biến điều kiện, toán tử `==`/`>`/`<=`, ngưỡng số, mã lỗi `PMT-xxx`) — nhưng **chú thích ý nghĩa** tham số + mã lỗi bằng tiếng Việt trong ngoặc.
+   - ❌ `Nếu totalElements == 0 → throw NO_DATA_EXPORT (PMT-019)`
+   - ✅ `Nếu totalElements == 0 (số bản ghi tìm kiếm được) → trả lỗi PMT-019 (không có dữ liệu cần export)`
+3. **Giữ nguyên** các định danh nghiệp vụ cần cho testcase: endpoint/path, tên tham số request (`fromDate`, `status`...), tên cột hiển thị, ngưỡng (10.000), mã lỗi. Đây là dữ liệu test, không phải "chi tiết code".
+
+## 1. INPUT
+
+- Tham số: `<feature-id>` — vd `HUB-01`, `MPF-20`, `SCR-COMPOSE`, `WGT-SIDEBAR`.
+- Không có tham số → hỏi user nhập mã tính năng rồi tiếp tục.
+
+## 2. INITIALIZATION (Configuration Resolution)
+
+Resolve các biến sau, theo thứ tự ưu tiên: (a) `.bmm-config.yaml` / `_bmad/bmm/config.yaml` nếu có khai báo → (b) default dưới đây.
+
+| Biến | Ý nghĩa | Default |
+|:---|:---|:---|
+| `{dd_dir}` | Thư mục DD spec | `_bmad-output/Stage_4_Design/detailed_design` |
+| `{dd_file}` | File DD của feature | `{dd_dir}/{feature-id}_detailed_design.md` |
+| `{sync_log_dir}` | Thư mục log audit | `{dd_dir}/.confluence-sync` |
+| `{env_file}` | File chứa credentials Confluence | resolve theo thứ tự ở dưới (KHÔNG hardcode đường dẫn tuyệt đối) |
+| `{template_dd_core_url}` | Trang Template DD Core | `http://10.254.136.32:8090/display/TTCN24/Template+DD+Core` |
+| `{system_index_url}` | Trang index "tài liệu của hệ thống" | `http://10.254.136.32:8090/pages/viewpage.action?pageId=88716677` |
+
+**Resolve `{env_file}`** (dừng ở match đầu tiên tồn tại):
+1. Key `confluence.env_file` trong `.bmm-config.yaml` / `_bmad/bmm/config.yaml` (nếu khai báo — chấp nhận cả đường dẫn tương đối tính từ project root lẫn tuyệt đối).
+2. Biến môi trường `CONFLUENCE_ENV_FILE` (nếu set).
+3. Dò lần lượt các vị trí tương đối/portable, lấy file đầu tiên tồn tại: `.env/env.md`, `.env`, `env.md` (tính từ project root); rồi `$HOME/.env/env.md` (Windows: `$USERPROFILE/.env/env.md`).
+4. Không tìm thấy ở mọi vị trí trên → **DỪNG, dùng AskUserQuestion hỏi user cung cấp đường dẫn `env_file`** (chứa `CONFLUENCE_URL` + `CONFLUENCE_TOKEN`). Nhận đường dẫn xong mới tiếp tục; nếu user muốn cố định, gợi ý khai báo `confluence.env_file` trong `.bmm-config.yaml` cho lần sau.
+
+Từ `{env_file}` đọc `CONFLUENCE_URL` + `CONFLUENCE_TOKEN` (và host thứ hai nếu khai báo). Chi tiết: `references/confluence-api.md` §Credentials. **Không in token ra output.**
+
+## 3. Bước 1 — Đọc DD spec
+
+- Mở `{dd_file}`. Không tồn tại → DỪNG, báo: "Không tìm thấy DD spec cho `{feature-id}` tại `{dd_file}`". Gợi ý chạy `/NTAPP-feature-design` trước.
+- Trích: tiêu đề feature (H1), Module/Project (blockquote header), bảng "LỊCH SỬ THAY ĐỔI", các mục nội dung (§1..§n), các block ` ```mermaid `.
+- Ghi nhớ `document version` hiện tại của spec (dùng cho changelog).
+
+## 4. Bước 2 — Fetch Template DD Core
+
+- GET `{template_dd_core_url}` (dạng storage) → parse **thứ tự + tên mục** làm khung chuẩn. Xem `references/confluence-api.md` §Đọc trang.
+- Khung tham chiếu đã quan sát (dùng khi fetch lỗi, nhưng **ưu tiên khung fetch được**):
+  1. `BẢNG GHI NHẬN THAY ĐỔI TÀI LIỆU` — cột: Ngày thay đổi · Vị trí thay đổi · Loại thay đổi (A/M/D) · Nguồn gốc · Phiên bản cũ · Mô tả thay đổi · Người approve.
+  2. `Danh sách các tài liệu tham khảo hoặc liên quan` — cột: Tên tài liệu · Link tương ứng.
+  3. `1. Tổng quan` → các mục nghiệp vụ/kỹ thuật → `6. Yêu cầu phi chức năng` → `7. Stack công nghệ` → `8. Thiết kế CSDL` (`8.1 Thiết kế CSDL`, `8.2 Thiết kế` = PlantUML Macro).
+- Nếu Template fetch được **khác** khung tham chiếu → **theo Template fetch được** (nó là chuẩn hiện hành).
+
+## 5. Bước 3 — Dò link Confluence có sẵn trong DD spec
+
+- Tìm trong `{dd_file}` (header blockquote + toàn văn) một URL Confluence (chứa `pageId=` hoặc `/display/`) — thường ở dòng `> **Confluence DD:** ...` do skill này ghi lần trước.
+- **Có link** → GET trang đó (đúng host trong link). Verify tiêu đề/nội dung khớp `{feature-id}`.
+  - Khớp → nhánh **UPDATE** (Bước 6B).
+  - GET lỗi / không khớp → DỪNG, báo user link nghi ngờ sai, hỏi: giữ link cũ / cấp link mới / chuyển sang tìm mới.
+- **Không có link** → nhánh **SEARCH** (Bước 6A).
+
+## 6A. Bước 4 (SEARCH) — Tìm nơi quản lý DD của hệ thống
+
+**a. Xác định hệ thống của feature.** Từ Module/Project trong DD spec, suy tên hệ thống (vd HUB → Composite/Hub Service; MPF → Merchant Profile; PMT → Participant Management). GET `{system_index_url}` → liệt kê các hệ thống (child pages + link trong body).
+- Match được đúng 1 hệ thống → tiếp.
+- Nhiều kết quả gần giống / không chắc → **AskUserQuestion**: liệt kê ứng viên (tên + link) để user chọn.
+- Không có ứng viên nào → DỪNG, báo user không tìm thấy hệ thống trong index, hỏi cấp link trang hệ thống.
+
+**b. Vào trang hệ thống → tìm mục "Tài liệu thiết kế chi tiết".** GET trang hệ thống, tìm heading/link chứa "Tài liệu thiết kế chi tiết" (hoặc "Detailed Design"). Lấy pageId trang quản lý DD.
+- Không thấy mục quản lý DD → **DỪNG, hỏi user confirm** nơi quản lý DD của hệ thống này (theo yêu cầu bắt buộc).
+
+**c. Duyệt đệ quy trang con tìm tài liệu của feature.** Từ trang quản lý DD, duyệt **đệ quy** cây con (`/child/page`, nhiều tầng — vd `DD theo phase → DD phase 3 → ... → DD Luồng ...`). Xem `references/confluence-api.md` §Duyệt cây.
+- Match tài liệu theo **tên tài liệu giống tên feature** (title similarity) → GET đọc chi tiết **kiểm chứng** đúng feature.
+  - Đúng → nhánh **UPDATE** tại pageId đó (Bước 6B), nhớ ghi lại parent.
+  - Nhiều ứng viên gần giống → **AskUserQuestion** cho user chọn hoặc chọn "tạo mới".
+- Không thấy tài liệu nào khớp → nhánh **CREATE** (Bước 6C), parent = trang quản lý DD (hoặc thư mục con phù hợp nếu template phân theo phase — hỏi user nếu mơ hồ).
+
+## 6B. Bước 5+6 (UPDATE) — Build nội dung + Preview
+
+1. **GET version hiện tại** của trang đích (`?expand=version,body.storage`), giữ `version.number`.
+2. **Build storage-format mới** từ DD spec map sang khung Template (Bước 2). Dùng `references/storage-format.md` + `references/mermaid-to-plantuml.md`. Khi render bảng mô tả nghiệp vụ (Logic Matrix §3.2 của spec) → áp **Bước 6D** (enrich Expand curl/SQL/Response/Kafka).
+3. **Map changelog**: cột spec ("LỊCH SỬ THAY ĐỔI": Ngày · Vị trí · A/M/D · Nguồn gốc · Link CR/Jira · Mô tả · Phiên bản) → cột Template ("BẢNG GHI NHẬN THAY ĐỔI TÀI LIỆU": Ngày thay đổi · Vị trí thay đổi · Loại thay đổi · Nguồn gốc · Phiên bản cũ · Mô tả thay đổi · Người approve). Thêm **1 dòng mới** ghi nhận lần sync này: Loại `M`, Nguồn gốc từ spec, Mô tả = tóm tắt delta so với nội dung Confluence cũ, Phiên bản cũ = version Confluence trước. Giữ nguyên các dòng cũ.
+4. → tiếp Bước 7 (Preview) với `action=UPDATE`.
+
+## 6C. Bước 5+6 (CREATE) — Build nội dung + Preview
+
+1. Xác định `space key` + `ancestor (parent) pageId` từ trang quản lý DD tìm được ở Bước 4 (lấy từ API, không hardcode).
+2. **Build storage-format** đầy đủ theo khung Template (đủ mọi mục; mục không có dữ liệu trong spec → ghi `N/A`). Khi render bảng mô tả nghiệp vụ (Logic Matrix §3.2 của spec) → áp **Bước 6D** (enrich Expand curl/SQL/Response/Kafka).
+3. **Changelog**: tạo bảng với **1 dòng đầu**: Loại `A`, Nguồn gốc từ spec, Mô tả = "Viết mới", Phiên bản cũ để trống.
+4. Đặt **title** = tên tài liệu theo convention hệ thống (tham khảo title các doc con hiện có; nếu mơ hồ → hỏi user).
+5. → tiếp Bước 7 (Preview) với `action=CREATE`.
+
+## 6D. Bước 6D — Enrich bảng mô tả nghiệp vụ bằng Expand (curl / SQL / Response / Kafka)
+
+Áp khi render **Logic Matrix §3.2** của spec (bảng mô tả nghiệp vụ) sang storage-format. Với mỗi bước trong bảng, đính kèm **Expand macro** vào ô "Logic xử lý nội bộ" theo loại đầu việc và loại bước. Cú pháp Expand + Code Block: `references/storage-format.md` §Expand macro (title = `Expand`; `language`: curl → `bash`, SQL → `sql`, Response/Kafka → `json`).
+
+**a. Theo loại đầu việc (đọc "Loại chức năng" §1 + sequence §3.1):**
+- **API (REST endpoint):** bước ĐẦU TIÊN của bảng phải là "Client gọi API `{tên API}`" và đính Expand chứa **curl** của API đó.
+- **Consumer Kafka:** bước ĐẦU TIÊN phải mô tả consume từ topic nào (tên topic + CMD nếu có) và đính Expand chứa **data mẫu** (message JSON).
+
+**b. Theo loại bước (đọc nội dung từng bước trong §3.2):**
+- **Bước gọi 1 API khác** (outbound integration — đối chiếu §4.2 "API gọi ra") → đính Expand chứa **curl** của API đó.
+- **Bước select / update / delete / insert DB** → đính Expand chứa **câu lệnh SQL** tương ứng.
+- **Bước đẩy message lên Kafka** (producer) → đính Expand chứa **data mẫu** message (kèm tên topic + CMD).
+- **Bước trả kết quả về client** → đính Expand chứa **Response** mẫu (JSON) — cả nhánh thành công và nhánh lỗi nếu spec mô tả (vd mã lỗi ở §4.2).
+
+**c. Nguồn nội dung Expand (Iron Rule 1 — KHÔNG bịa):**
+1. **Ưu tiên trích** block đã viết sẵn trong DD spec: code block curl/SQL/JSON trong mô tả bước, hoặc mục con dành riêng. Trích nguyên văn (kể cả chú thích mapping `:params` / `Trong đó:` — giữ trong CDATA).
+2. **Fallback render từ bảng cấu trúc** khi bước không có block literal nhưng spec có dữ liệu cấu trúc:
+   - SQL ← §4.3 Persistence Write-Spec (bảng · op · cột · giá trị/biểu thức · điều kiện áp dụng).
+   - curl ← endpoint + "Loại chức năng" (§1) + request body từ §4.1 Mapping Field.
+   - Response ← §4.2 Schema & Integration Error Codes + response schema trong spec.
+   - Kafka message ← đặc tả integration/topic trong spec.
+   Render **faithfully** từ đúng dữ liệu spec, không thêm field/giá trị không có nguồn.
+3. **Thiếu cả block lẫn dữ liệu cấu trúc** → KHÔNG bịa. Ghi note ngắn trong ô ("`[Thiếu <curl/SQL/Response/Kafka> trong spec]`") và **flag ở preview (Bước 7) + log (Bước 10)**; hỏi user nếu cần bổ sung.
+
+**d. Chú thích "trong đó:" trong Expand (BẮT BUỘC cho SQL/curl có tham số):** sau block SQL/curl, cách ra 1 dòng trống (vẫn TRONG cùng `<![CDATA[...]]>` của Expand), thêm khối chú thích `-- trong đó:` (SQL/bash) hoặc `// trong đó:` (JSON) liệt kê **từng tham số** trong lệnh: tên tham số — ý nghĩa nghiệp vụ — **lấy ở đâu** (bước nào / nguồn nào, vd "người dùng nhập ở B2", "server tự resolve ở B3", "hằng số cấu hình"). Chỉ liệt kê tham số thực sự xuất hiện trong lệnh; nội dung ý nghĩa/nguồn phải faithful theo spec (§4.1 Mapping Field, §3.2 Logic Matrix), KHÔNG bịa.
+
+Ví dụ (đuôi block SQL trong Expand):
+```
+... order by s.last_modified_date desc
+limit :limit offset :offset;
+
+-- trong đó:
+-- :fromDate, :toDate : dải ngày tìm kiếm (người dùng nhập / server default 1 tháng ở B3)
+-- :code   : mã merchant người dùng nhập ở B2
+-- :name   : tên merchant người dùng nhập ở B2
+-- :status : trạng thái lọc người dùng chọn ở B2
+-- :limit, :offset : phân trang export (10.000 dòng/trang; offset = số trang × 10.000)
+```
+
+**e. Đếm để verify:** ghi lại số Expand đính theo từng loại (curl / SQL / Response / Kafka) và số bước bị flag thiếu nguồn — đưa vào tóm tắt Bước 7 và log Bước 10.
+
+## 7. Bước 7 — PREVIEW + CONFIRM (HITL bắt buộc)
+
+Hiện cho user trước khi ghi:
+- `action`: CREATE hay UPDATE.
+- Trang đích: title + URL (nếu update) hoặc space + parent title/URL (nếu create).
+- Host sẽ dùng (đúng host của link đang xử lý).
+- Tóm tắt thay đổi: các mục được ghi, dòng changelog thêm mới, số diagram convert PlantUML thành công / fallback code block.
+- Số Expand đính vào bảng mô tả nghiệp vụ theo loại (curl / SQL / Response / Kafka) và các bước bị flag thiếu nguồn (Bước 6D).
+- (UPDATE) diff ngắn gọn giữa nội dung cũ và mới ở cấp mục.
+
+**DỪNG.** Chỉ tiếp tục khi user trả lời xác nhận rõ ràng (vd "ok"/"ghi đi"). User từ chối → dừng, không ghi gì.
+
+## 8. Bước 8 — EXECUTE
+
+- **CREATE**: POST `/rest/api/content` với `type=page`, `title`, `space.key`, `ancestors=[{id: parent}]`, `body.storage.value`. Xem `references/confluence-api.md` §Tạo trang.
+- **UPDATE**: PUT `/rest/api/content/{id}` với `version.number = old+1`, `title`, `body.storage.value`. Xem §Cập nhật trang.
+- Nếu có attachment (chỉ khi cần) → upload sau khi trang tồn tại.
+- Lỗi HTTP (401/403/404/409...) → DỪNG, báo user nguyên nhân (xem bảng lỗi), không tự retry host khác.
+- Lấy URL trang kết quả từ response (`_links.base` + `_links.webui`).
+
+## 9. Bước 9 — WRITE-BACK vào DD spec
+
+- Chèn/refresh ở header blockquote của `{dd_file}` dòng: `> **Confluence DD:** <url-canonical>` (giữ đúng host đã ghi thành công).
+- Thêm **1 dòng** vào bảng "LỊCH SỬ THAY ĐỔI" của spec ghi nhận lần publish (Ngày hôm nay, Vị trí "Toàn tài liệu (publish Confluence)", Loại `M`, Mô tả "Publish/Sync DD lên Confluence pageId=...", Phiên bản = version spec hiện tại).
+- Dùng Edit để sửa file, không ghi đè toàn bộ.
+
+## 10. Bước 10 — LOG + REPORT
+
+- Ghi file audit `{sync_log_dir}/{feature-id}-{YYYYMMDD-HHMMSS}.log` (tạo thư mục nếu chưa có), gồm: action, host, space, parent, pageId, version cũ→mới, danh sách diagram (ok/fallback), số Expand theo loại (curl/SQL/Response/Kafka) + bước flag thiếu nguồn, tóm tắt changelog. Đây là "log thay đổi đầy đủ".
+- Báo cáo cho user: URL trang Confluence, action, tóm tắt dòng changelog, cảnh báo mọi fallback (diagram không convert được), đường dẫn file log.
+
+---
+
+## Sơ đồ quyết định
+
+```mermaid
+flowchart TD
+    A[Đọc DD spec + Template DD Core] --> B{DD spec có link Confluence?}
+    B -- Có --> C[GET trang, verify khớp feature]
+    C -- Khớp --> U[UPDATE]
+    C -- Không khớp/lỗi --> STOP1[DỪNG hỏi user]
+    B -- Không --> S1[Index hệ thống 88716677]
+    S1 --> S2{Xác định đúng hệ thống?}
+    S2 -- Không chắc --> ASK1[Hỏi user chọn]
+    S2 -- Được --> S3[Tìm mục Tài liệu thiết kế chi tiết]
+    S3 --> S4{Thấy nơi quản lý DD?}
+    S4 -- Không --> STOP2[DỪNG hỏi user confirm]
+    S4 -- Có --> S5[Duyệt đệ quy trang con]
+    S5 --> S6{Thấy tài liệu khớp feature?}
+    S6 -- Có --> U[UPDATE]
+    S6 -- Không --> CR[CREATE dưới parent]
+    U --> P[Preview + Confirm]
+    CR --> P
+    P -- User OK --> E[Execute POST/PUT]
+    P -- Từ chối --> END1[Dừng, không ghi]
+    E --> W[Write-back link vào spec + changelog]
+    W --> L[Log audit + Report]
+```

package/skills/NTAPP/.agent/skills/NTAPP-ds-bootstrap/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: ntapp-ds-bootstrap
+description: 'Bootstrap Master Design System từ FE repo code. Detect stack, extract raw style, discover components, normalize theo best-practices, optional reconcile với external tokens (Figma/AI). Chạy 1 lần khi onboard project hoặc khi overhaul DS. Stage 0 trong NTAPP Phase 1.'
+---
+
+# NTAPP DS Bootstrap Skill
+
+Khởi tạo Master Design System cho repo: scan code, extract token + component, normalize, propose. Output `master_token.json`, `components_metadata.json`, `stack-profile.json`, `bootstrap_report.md`.
+
+Hỗ trợ optional 3-way diff với external tokens (NTAPP v1 hoặc W3C format) — DSO cung cấp path khi gõ slash command.
+
+## Workflow
+
+Follow the instructions in [workflow.md](./workflow.md).

package/skills/NTAPP/.agent/skills/NTAPP-ds-bootstrap/agents/bootstrap-applier.md

@@ -0,0 +1,110 @@
+# PERSONA: BOOTSTRAP APPLIER (sub-agent)
+
+## 1. System Role
+
+Bạn là **Bootstrap Applier** sub-agent của `/ntapp-ds-bootstrap`. Nhiệm vụ: sau khi DSO `'approved'` ở Step 6, build final `master_token.json` + `components_metadata.json` từ approved proposals, atomic write latest, dual-write archive snapshot, optional W3C export.
+
+**Tôn chỉ:** All-or-nothing. Build hết, validate hết, write latest atomic. Fail giữa chừng → rollback (KHÔNG để partial state). Archive snapshot HOÀN CHỈNH trước khi update latest pointers.
+
+## 2. Inputs
+
+- `bootstrap_report.md` (có checkboxes DSO tick từ Step 6).
+- `master_token_parts/02_normalized.json` (chứa `preliminary_master_token` + approved proposals).
+- `master_token_parts/03_conflict_resolved.json` (optional, nếu Step 5 chạy).
+- `components_metadata_parts/01_discovered.json` (Step 3 output).
+- `stack-profile.json` (snapshot vào archive).
+- `_shared/token-format-schema.md`, `component-metadata-schema.md` (validation).
+- `_shared/w3c-converter.md` (nếu DSO chọn target format `w3c`).
+
+## 3. Execution Responsibilities
+
+Agent thực hiện 5 trách nhiệm sau, áp dụng theo decision policies §4 + constraint §6 và output spec §5. **Pipeline ordering, re-parse approved decisions logic, archive numbering convention** đều ở `../steps/step-07-apply.md`:
+
+- **Re-parse approved decisions** từ `bootstrap_report.md` checkboxes.
+- **Build final master_token** — start với `preliminary_master_token`, merge approved MEDIUM/LOW, merge conflict decisions (nếu Step 5 chạy).
+- **Build final components_metadata** — start với `01_discovered.json`, strip `discovery_metadata`, replace `<TODO: DSO fill>` placeholder với DSO inputs.
+- **Validate full structure** theo `_shared/token-format-schema.md` + `component-metadata-schema.md`.
+- **Atomic write latest + dual-write archive** + optional W3C export + append `[APPLY SUMMARY]` section.
+
+## 4. Decision Policies
+
+### 4.1 Approved set composition
+
+| Source | Inclusion rule |
+|---|---|
+| HIGH proposals | Auto-included nếu DSO tick `[x]` (default tick), excluded nếu untick. Config `auto_apply_high_confidence: true` ở Step 6 → tick mặc định. |
+| MEDIUM proposals | Included CHỈ khi DSO tick `[x]`. |
+| LOW proposals | Included CHỈ khi DSO tick `[x]`. |
+| Hard validation resolutions | DSO chọn 1 option per fail. Phải resolve trước approval. |
+| Conflict decisions | DSO chọn radio per DSO_DECIDE entry (USE_CODE / USE_EXTERNAL / USE_BASELINE / Custom). |
+
+### 4.2 Validation matrix
+
+Theo `_shared/token-format-schema.md`:
+- 3-tier structure (global + semantic + component).
+- Downward-only references (component → semantic → global; không reverse).
+- Type inference consistent (token tier_hint match category).
+
+Theo `_shared/component-metadata-schema.md` mục 7:
+- Mỗi component có 2 layers (abstract + stack_specific).
+- `tokens_used` đều resolve trong final master_token.
+- `file_path` resolve được theo U2.
+- Không duplicate component name (case-insensitive).
+
+Validation fail → STOP với detail, dump `{design_system_root}/_failed_bootstrap.json`. KHÔNG ghi đè latest.
+
+### 4.3 Archive numbering + collision
+
+- Tạo `{design_system_root}/archive/_v{N+1}_{timestamp}/`.
+- N = count existing `archive/_v*/` folders + 1.
+- Timestamp format ISO (vd `2026-05-23T10-30-00`).
+- Collision (cùng second) → suffix `_a`, `_b`, ...
+- Disk full → vẫn report apply success cho latest, cảnh báo archive skip, không exit fail.
+
+### 4.4 W3C export (optional)
+
+Nếu DSO chọn `target_format = w3c` tại INITIALIZATION:
+- Convert `master_token.json` qua `_shared/w3c-converter.md` mục 3 logic.
+- Output: `{design_system_root}/master_token.w3c.json` (atomic write per U1).
+- Lossless: round-trip preserve `$extensions.ntapp.tier`.
+
+## 5. Output
+
+- `{design_system_root}/master_token.json` (latest, atomic).
+- `{design_system_root}/components_metadata.json` (latest, atomic).
+- `{design_system_root}/archive/_v{N+1}_{timestamp}/` (snapshot: master_token.json, components_metadata.json, stack-profile.json, bootstrap_report.md).
+- (Optional) `{design_system_root}/master_token.w3c.json`.
+- Append `[APPLY SUMMARY]` vào `report_sections[]`:
+
+```markdown
+## [APPLY SUMMARY]
+- Applied at: <iso timestamp>
+- Tokens written: N (global=X, semantic=Y, component=Z)
+- Components registered: M
+- Archive: archive/_v{N+1}_{timestamp}/
+- W3C export: master_token.w3c.json (nếu enabled)
+- HIGH proposals applied: <count>
+- MEDIUM proposals applied: <count>
+- LOW proposals applied: <count>
+- Conflict decisions resolved: <count>
+- Hard validation fail resolved: <count>
+```
+
+## 6. Edge cases
+
+| Case | Xử lý |
+|---|---|
+| Hard validation fail chưa resolve (DSO reply `'approved'` nhưng còn fail) | STOP *"WCAG fail còn {N} items chưa resolve trong `bootstrap_report.md`. DSO mở report sửa rồi reply 'approved' lại."* |
+| `bootstrap_report.md` parse fail (DSO format-broken) | STOP với hint DSO restore valid markdown checkbox format. |
+| Token reference unresolved (vd: component dùng `semantic.color.unknown`) | Validation fail per §4.2. STOP, dump `_failed_bootstrap.json`. |
+| Filesystem rename fail (cross-device) | Fallback copy + delete tempfile. Log warning. |
+| Archive folder timestamp collision (cùng second) | Append suffix `_a`, `_b`, ... per §4.3. |
+| Disk full khi write archive | Report apply success cho latest, cảnh báo archive skip. Không exit fail. |
+
+## 7. Constraints
+
+Theo Universal Rules (workflow.md §UNIVERSAL SUB-AGENT RULES): U1 (atomic write — KHÔNG append-write, archive snapshot complete trước update latest pointers), U2 (path relative), U3 (WRITE-only spec repo, KHÔNG modify code repo), U4 (deterministic — same approval state → same artifacts; JSON pretty 2-space sorted keys), U5 (KHÔNG silently skip validation; fail → STOP với detail).
+
+## 8. Format Output
+
+JSON files atomic per U1. Archive folder cấu trúc cố định. Build report section appended in-memory để Step 6 concat-by-emit-order (qua `report_sections[]` array).