@trungtamcongnghedigital/vsaf 1.0.0

package/skills/NTAPP/.agent/skills/NTAPP-fix-bug/steps/step-03-doc-sync-report.md

@@ -0,0 +1,102 @@
+# Step 03 — Resolve Jira + Report cuối (terminal)
+
+**Persona:** Người đóng gói kết quả cho user review.
+
+**Mục tiêu:** Tổng hợp fix-report các bug (doc-sync đã do engine làm inline ở step-02) → **đóng bug trên Jira** (nếu có, qua 1 HITL gate) → trình báo cáo cuối. KHÔNG commit.
+
+---
+
+## 1. Reconcile doc-sync (chỉ khi cần)
+Doc-sync per-bug đã do engine `NTAPP-bug-fix-engine` làm inline ở step-02 (`doc_sync_mode=inline`, surgical theo bảng doc ứng viên dd/techspec/ui_schema/ds/slice). Ở đây chỉ **rà chéo**: nếu nhiều bug cùng chạm **một doc chung** (techspec / `master_token.json` / ui_schema dùng chung) → xác nhận các cập nhật không mâu thuẫn; lệch → chỉnh surgical cho nhất quán. Không có doc chung bị chạm → bỏ qua.
+
+## 2. Đóng bug trên Jira (chỉ bug có `jira_key` + fix thành công)
+
+Không bug nào có `jira_key` → bỏ qua mục này. Bug BLOCKER / ESCALATE / R5 → **loại khỏi danh sách** (R7): trạng thái Jira giữ nguyên.
+
+### 2.1 — Preview + HITL GATE (bắt buộc, 1 lần cho cả lô)
+In bảng preview rồi DỪNG:
+
+| Bug | Jira | Type | Đường đi trạng thái | Due Date | Người chịu TN | Est. | Assignee cuối (Reporter) | Nguyên nhân | Ảnh hưởng | Giải pháp |
+|---|---|---|---|---|---|---|---|---|---|---|
+
+- Cột **Đường đi trạng thái** là thông tin (`To Do → In Progress → Resolved`), KHÔNG phải câu hỏi — user chỉ duyệt nội dung.
+- Nội dung 3 cột cuối lấy từ step-02 §3 (in đủ, không tóm tắt — user cần đọc đúng thứ sẽ ghi lên Jira).
+- **Type = `Bug` mà thiếu 1 trong 3 nội dung → không được đi tiếp**, phải bổ sung trước (quy định nội bộ, Jira không tự chặn).
+- Type = `Issue` → 3 field không bắt buộc; có thì vẫn ghi, không có thì bỏ.
+**Đường đi trạng thái là quy định cứng của `jira.digital.vn`, KHÔNG hỏi user.** Type = `Bug` bắt buộc đi `To Do → In Progress → Resolved`; Jira chỉ trả transition từ trạng thái hiện tại nên `Resolved` không hiện ra khi đang ở `To Do` — đó là bình thường, cứ đi 2 hop. Đã verify trên project `TTCNSPQT`:
+
+| Trạng thái hiện tại | Đường đi tới `Resolved` |
+|---|---|
+| `To Do` (bug mới log) | 2 hop: `In Progress` → `Resolved` |
+| `In Progress` | 1 hop trực tiếp |
+| `Pending` · `Verifying` | 1 hop trực tiếp |
+| `Cancelled` | ❌ không có đường — báo user, bỏ qua bug đó |
+
+Chỉ dừng hỏi user ở đúng 1 trường hợp: **`Cancelled`** (hoặc trạng thái lạ không có đường tới `Resolved`) → nêu trạng thái hiện tại + transition khả dụng, bỏ qua bug đó. **KHÔNG tự chọn transition khác thay `Resolved`.**
+
+**Hop `To Do → In Progress` bắt 3 field theo quy định nội bộ** (Jira trả `required: false` nên KHÔNG tự chặn — skill phải tự bắt, hệt như 3 field Nguyên nhân/Ảnh hưởng/Giải pháp):
+
+| Field | ID | Giá trị |
+|---|---|---|
+| Due Date | `duedate` | ngày hôm nay `YYYY-MM-DD` |
+| Người chịu trách nhiệm | `customfield_15400` (userpicker) | `{"name":"<assignee đọc ở step-01>"}` — người đang fix, KHÔNG phải reporter |
+| Original Estimate | `timetracking` | `{"originalEstimate":"<Nh>","remainingEstimate":"<Nh>"}` — tự tính ở step-02 §3 |
+
+3 field này nằm trên **edit screen**, không nằm trên transition screen → phải set bằng `update-issue` **trước** khi transition, KHÔNG nhét vào payload của `transition` (Jira sẽ từ chối field không có trên transition screen).
+
+**⛔ GATE:** *"Duyệt ghi các nội dung trên lên Jira (update field + assign lại Reporter + chuyển Resolved)?"*. User chưa duyệt → KHÔNG gọi lệnh ghi nào. User sửa nội dung → cập nhật rồi in lại preview.
+
+### 2.2 — Ghi lên Jira (sau khi duyệt)
+Với mỗi bug, chạy **4 lệnh theo đúng thứ tự dưới**. Thứ tự này bắt buộc: `Người chịu trách nhiệm` phải được set khi assignee **vẫn còn là người fix**, trước khi (c) assign lại cho reporter.
+
+**(a) Set 3 field của hop In Progress** — bỏ qua nếu issue đã ở `In Progress`/`Pending`/`Verifying` **và** 3 field đã có giá trị (đã có thì KHÔNG ghi đè):
+```
+python -X utf8 <jira_helper> update-issue --key <KEY> \
+  --fields-json '{"duedate":"<hôm nay>","customfield_15400":{"name":"<assignee đang fix>"},"timetracking":{"originalEstimate":"<Nh>","remainingEstimate":"<Nh>"}}'
+```
+
+**(b) Hop trung gian** — chỉ khi đang ở `To Do`:
+```
+python -X utf8 <jira_helper> transition --key <KEY> --to "In Progress"
+```
+
+**(c) Set 3 field kết quả fix + assign lại Reporter:**
+```
+python -X utf8 <jira_helper> update-issue --key <KEY> \
+  --assignee <reporter.name> \
+  --fields-json '{"customfield_13406":"<Nguyên nhân>","customfield_15800":"<Ảnh hưởng>","customfield_15801":"<Giải pháp>"}'
+```
+`customfield_13406` = Nguyên nhân · `customfield_15800` = Ảnh hưởng · `customfield_15801` = Giải pháp.
+
+**(d) Hop cuối sang Resolved:**
+```
+python -X utf8 <jira_helper> transition --key <KEY> --to Resolved \
+  --fields-json '{"customfield_13241":{"value":"<Bug Type>"}}'
+```
+Transition screen của `Resolved` bắt lại **Bug Type** (`customfield_13241`). Lấy giá trị đang có từ `extra` ở step-01 §1b và **gửi lại y nguyên**; đang trống → hỏi user chọn trong `allowedValues` mà `get-issue` trả về (`Performance` / `Logic` / `Enviroment` / `Config` / `GUI` / `UI`). Helper tự chặn trước nếu thiếu field bắt buộc, nên đừng đoán.
+
+> Mọi `customfield_*` trên là id đã verify trên `jira.digital.vn`. **Project/instance khác thì id khác** — đọc lại bằng `get-issue --extra-fields` hoặc editmeta rồi map theo tên field, đừng dùng cứng bảng này.
+
+**⚠️ `transition` và `update-issue` GHI THẬT, không auto-undo.** Luôn `--dry-run` trước để validate; chỉ bỏ `--dry-run` sau khi gate §2.1 được duyệt. Hop trung gian cũng là ghi thật — đã nằm trong đường đi user duyệt thì mới chạy, KHÔNG tự hop thêm ngoài đường đi đó.
+
+Lệnh nào trả `ok:false` → **dừng chuỗi của bug đó tại đúng chỗ đó**, ghi lỗi vào report, đi tiếp bug khác. KHÔNG retry vòng lặp. Dừng giữa chuỗi (vd (b) xong mà (d) lỗi) → **nêu rõ trong report issue đang dừng ở trạng thái nào và còn thiếu bước nào** để user xử lý tay — quan trọng vì `Resolved → To Do` KHÔNG revert được.
+
+### 2.3 — Đối chiếu lại file log
+Bug có `bug_file` (lane `file`, hoặc lane `jira` tra ngược thấy entry) → dòng trạng thái đã flip `Fixed` ở step-02; bổ sung mã Jira vào ghi chú fix nếu chưa có. Lane `jira` không có file log → không tạo file mới.
+
+## 3. Báo cáo cuối (in chat — không tạo file mới)
+Trình bảng tổng (gom từ fix-report các bug ở step-02):
+
+| Bug | Trạng thái mới (file) | Jira (key → status → assignee) | Nguyên nhân | File code đã sửa | Ceremony (lane / atdd) | Verify | Doc đã sync |
+|---|---|---|---|---|---|---|---|
+
+Thêm:
+- **Jira lỗi khi ghi:** bug nào `update-issue` / `transition` trả lỗi → nêu mã + thông báo lỗi + việc user cần làm tay trên Jira.
+- **Bug chưa fix (R5 / BLOCKER / ESCALATE):** liệt kê + lý do / câu hỏi cần user — mandatory-ATDD thiếu test xanh (BLOCKER); Tier 3/4 chưa localize; WBS gap phải đặt id mới; file ngoài blast radius.
+- **Cần verify thủ công:** bug UI-style có `verify-level = static-only` → cần so ảnh / chạy app.
+- **Self-review:** engine đã self-review inline mỗi bug (correctness / blast-radius / contract-ripples / regression / Rule 4-6-9); nêu finding còn lại (từ fix-report) đã sửa hay còn tồn.
+- **Bước tiếp theo cho user:** review diff ở code repo + spec repo, rồi **tự commit** theo workflow chuẩn (skill **KHÔNG** commit — R2). Gợi ý: `ntapp-qa-pipeline-bugfix` để sinh regression test chống tái diễn (cho bug `optional` chưa có test).
+
+---
+
+**DONE.** Không thực hiện thêm hành động nào sau report (đặc biệt: không commit/push).

package/skills/NTAPP/.agent/skills/NTAPP-fix-bug/workflow.md

@@ -0,0 +1,110 @@
+# Fix Bug Workflow (NTAPP Self-Contained Orchestrator)
+
+**Goal:** Từ 1 file `BUGS-<SLICE-ID>-<account>.md`, fix mọi bug đang mở ở code repo, flip trạng thái → `Fixed`, rồi đồng bộ tài liệu spec đã lệch so với code mới. KHÔNG tự commit.
+
+**Your Role:** Bạn là **intake adapter cho nguồn file-local** (đối xứng với workflow `bug-fix-batch` — adapter Jira). Điều phối tuần tự 3 step, là điểm chạm duy nhất với user (**1 HITL gate** sau step-01). Việc **fix đúng một bug trên một unit** được ủy quyền cho **engine dùng chung `NTAPP-bug-fix-engine`** (ceremony-adaptive) — skill này KHÔNG tự viết lại logic root-cause/DD/ATDD/pre-commit/verify/doc-sync; chỉ lo parse file, localize, classify, plan (HITL), gọi engine per-bug (`in-place-nocommit`), rồi flip status trong file + report.
+
+---
+
+## WORKFLOW ARCHITECTURE — Progressive disclosure
+
+- File này giữ KHUNG điều phối (INITIALIZATION + pipeline map + global rules). Chi tiết thực thi nằm TRONG từng step file.
+- ⛔ Đọc ĐÚNG MỘT step mỗi lần. Hoàn tất step hiện tại (gồm GATE nếu có) RỒI mới đọc step kế. KHÔNG đọc trước nhiều step. State chuyển qua artifact (bug file + code), không qua việc giữ instruction trong context.
+
+---
+
+## INITIALIZATION (Configuration Resolution)
+
+Trước khi chạy step nào, resolve config theo cascade.
+
+### Bước 0 — Resolve `bug_source` (file hay Jira)
+Đọc input user:
+- Khớp mã Jira (`^[A-Z][A-Z0-9]+-\d+$`) hoặc URL chứa `/browse/<KEY>` → `bug_source = jira`, `jira_keys = [...]` (nhiều mã cách nhau bằng dấu phẩy/space; bỏ tiền tố `jira` nếu user gõ kèm).
+- Còn lại (path `.md`, hoặc file đang mở trong IDE) → `bug_source = file`.
+- Cả 2 đều thiếu → DỪNG, hỏi user.
+
+### Bước 0b — Resolve `{spec_repo_root}` (project-root)
+File bug nằm trong spec repo. Walk up từ thư mục chứa file bug: thấy `_bmad/` → `{spec_repo_root}`; else thấy `NTAPP-output/` → `{spec_repo_root}`; else fallback `cwd` + log warning. `bug_source = jira` (không có file làm mốc) → walk up từ `cwd`.
+
+### Bước 1 — Resolve code repo(s)
+Code không nằm trong spec repo (dual-repo). Code repo là các **thư mục anh em** của spec repo (cùng folder cha), hoặc các additional working directory đang mở. Lập danh sách ứng viên repo từ:
+- Các additional working directory đang mở.
+- Các thư mục anh em chứa source (`src/`, `package.json`, `pom.xml`, `build.gradle`, `go.mod`, ...).
+- `NTAPP-output/Stage_5_Build_Verify/bug-batches/_unit-path-map.yaml` nếu có (`containers[].repo`).
+
+Map **WBS unit → repo** thực hiện ở step-01 (qua mô tả module trong WBS / techspec / detailed_design + grep code). KHÔNG đoán repo ở đây.
+
+### Bước 2 — Paths cố định trong spec repo
+| Biến | Giá trị |
+|---|---|
+| `bug_file` | đường dẫn user cung cấp (`{bugs_dir}/BUGS-<SLICE-ID>-<account>.md`) — user chỉ đưa mã slice thì **KHÔNG glob**: gọi helper, lấy `bug_files` (xem hộp dưới bảng). `bug_source = jira` → resolve qua tra ngược ở step-01 §1b, có thể không có |
+| `bugs_dir` | helper trả về (`bugs_dir`); mặc định `{spec_repo_root}/NTAPP-output/Stage_1_Discovery/Bugs_Issues/` |
+| `jira_helper` | `<skills-dir>/NTAPP-log-bug/jira_bug.py` — skill sibling cùng cấp trong skill dir (Jira client dùng chung với `NTAPP-log-bug`). Chạy `python -X utf8 <jira_helper> <subcommand>`; không tìm thấy → DỪNG nhánh Jira, báo user chạy `./scripts/sync-skills-to-user.sh --skills-only` |
+| `wbs` | `{spec_repo_root}/NTAPP-output/Stage_2_Architecture/project_wbs.md` |
+| `techspec_dir` | `{spec_repo_root}/NTAPP-output/Stage_3_Specs/techspec/` |
+| `dd_dir` | `{spec_repo_root}/NTAPP-output/Stage_4_Design/detailed_design/` |
+| `ui_schema_dir` | `{spec_repo_root}/NTAPP-output/Stage_4_Design/ui_schema/` |
+| `ds_root` | `{spec_repo_root}/NTAPP-output/design-system/` |
+| `build_verify_dir` | `{spec_repo_root}/NTAPP-output/Stage_5_Build_Verify/` |
+| `slices_dir` | helper trả về (`slices_dir`); mặc định `{spec_repo_root}/NTAPP-output/Stage_2_Architecture/slices/` |
+| `date` | ngày hệ thống, `YYYY-MM-DD` |
+
+> ⚠️ **`slices_dir`, `bugs_dir`, `bug_file` KHÔNG được ghép bằng tay.** Gọi:
+>
+> ```
+> python3 {project-root}/hooks/lib/slice_paths.py --resolve <SLICE-ID> --json
+> ```
+> *(Windows: dò `py -3` → `python3` → `python`.)*
+>
+> Trả về `slices_dir`, `bugs_dir`, `assets_dir`, `slice_files[]`, `bug_files[]`, `warnings[]` — đã chuẩn hoá zero-pad và khớp theo **ranh giới**, nhận cả bố cục phẳng lẫn bố cục thư mục feature.
+>
+> Ba lý do, cả ba là lỗi đã xảy ra thật:
+> 1. **Bảng này từng ghi `Stage_5_Build_Verify/slices/` — thư mục không tồn tại.** Slice thật ở `Stage_2_Architecture/slices/`. Sáu file khác trong framework ghi đúng, ba file nhánh bug ghi sai; phe đúng thắng bằng số đông chứ không bằng cơ chế nào.
+> 2. **Glob `BUGS-<SLICE-ID>*.md` khớp theo tiền tố.** `SLICE-2` bắt luôn `SLICE-20`, `SLICE-21`, `SLICE-24` — 4 file thay vì 1, và skill fix nhầm bug của ba slice khác.
+> 3. **Zero-pad không khớp.** Skill viết `SLICE-06`, đĩa có `SLICE-6-…`.
+>
+> **Mã thoát:** `0` = tra được (danh sách có thể rỗng — nghĩa là *thật sự không có*); `3` = **không tra được**, DỪNG và đọc `warnings`; `2` = mã slice sai dạng.
+
+---
+
+## OPEN-STATUS FILTER (bất biến)
+
+Bug "đang mở" = trạng thái ∈ **{`Open`, `In Progress`, `Reopened`}**. Bỏ qua `Fixed` và `Closed`.
+Parse entry theo format `NTAPP-log-bug`: mỗi bug là 1 block `## <SLICE>-<account>-BUG-NN — <title>` với dòng `- **Trạng thái:** <status>`.
+
+**Với `bug_source = jira`** — trạng thái là workflow Jira, không phải 4 giá trị trên. Coi là **đang mở** khi status KHÔNG thuộc {`Resolved`, `Closed`, `Cancelled`, `Done`}. Issue đã đóng → báo user trạng thái hiện tại và hỏi có fix tiếp không, KHÔNG tự bỏ qua im lặng (khác lane file: file thì bỏ qua im lặng vì đang quét cả danh sách).
+
+---
+
+## PIPELINE MAP (neo thường trực — 1 dòng/step)
+
+| # | Step file | Mục tiêu | Output |
+|---|---|---|---|
+| 01 | steps/step-01-triage-plan.md | Parse + filter bug đang mở → map unit→repo → **classify** (severity/atdd_class/lane) → fix plan → **HITL gate** | Plan table (in chat) |
+| 02 | steps/step-02-fix-and-verify.md | Per-bug: **gọi engine `NTAPP-bug-fix-engine`** (in-place-nocommit, doc-sync inline) → flip status `Fixed` | Code đã sửa + doc synced + bug file cập nhật status |
+| 03 | steps/step-03-doc-sync-report.md | Reconcile doc chung → **resolve Jira (HITL gate)** → report tổng cuối | Jira đã Resolved + báo cáo cuối (in chat) |
+
+Chuỗi: **01 → [GATE: user duyệt plan] → 02 → 03 (có [GATE: user duyệt nội dung ghi lên Jira]) → terminal**.
+
+---
+
+## GLOBAL RULES (áp dụng mọi step)
+
+- **R1 — Bug file read-mostly:** chỉ được sửa dòng `- **Trạng thái:**` (+ thêm `- **Ghi chú fix:**`) của đúng bug đang xử lý. KHÔNG sửa mô tả, KHÔNG đụng bug khác (append-only như `NTAPP-log-bug`).
+- **R2 — Không tự commit:** sau khi fix + doc-sync, DỪNG để user review. Không `git commit`, không `git push`.
+- **R3 — Tôn trọng pre-commit hook:** *(engine thực thi)* giữ header `id:`+`dd_version:`, UI dùng design token (không hardcode color/px/font), không emoji unicode — chi tiết ở engine.
+- **R4 — Root-cause trước khi fix:** *(engine thực thi)* tuân `superpowers-systematic-debugging`. Cấm "fix mò" triệu chứng mà chưa xác định nguyên nhân.
+- **R5 — Bug không tự fix được** (mơ hồ / không tái hiện / phụ thuộc ngoài / cần quyết định sản phẩm), hoặc engine trả **BLOCKER / ESCALATE**: GIỮ nguyên trạng thái, ghi lý do vào report, KHÔNG flip `Fixed`, đi tiếp bug khác.
+- **R6 — Code là nguồn sự thật sau fix:** *(engine doc-sync inline thực thi)* tài liệu chỉnh theo code mới (surgical); `*_detailed_design.md` đổi bản chất → bump `dd_version` + đồng bộ header code. step-03 chỉ reconcile doc chung + report.
+- **R7 — Jira là state dùng chung ngoài repo:** mọi lệnh ghi Jira (`update-issue`, `transition`) chỉ được gọi ở step-03 **sau khi user duyệt gate**, và chỉ cho bug engine trả thành công. Bug BLOCKER / ESCALATE / R5 → **KHÔNG đụng Jira**. Không tự comment, không tự đổi priority/label, không đóng issue của người khác ngoài danh sách đang xử lý. Đọc Jira (`get-issue`) thì tự do, không cần gate.
+- ⛔ Đọc đúng một step file mỗi lần.
+
+---
+
+## LAUNCH
+
+Sau INITIALIZATION:
+- `bug_source = file` → xác nhận `bug_file` tồn tại và đọc được. Thiếu → DỪNG, hỏi user đường dẫn file bug.
+- `bug_source = jira` → xác nhận `jira_helper` tồn tại và `get-issue` chạy được cho mã đầu tiên. Lỗi credential (thiếu `env.md`) → DỪNG, hướng dẫn theo `env.example.md` trong skill dir `NTAPP-log-bug`.
+
+**Next:** Read fully and follow `./steps/step-01-triage-plan.md`

package/skills/NTAPP/.agent/skills/NTAPP-integration-inspection/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: ntapp-integration-inspection
+description: "Trợ lý BA phân tích & đặc tả tích hợp hệ thống với đối tác/bên thứ ba, end-to-end. Hỗ trợ 2 chiều tích hợp (mình gọi đối tác / đối tác gọi mình / hai chiều) và đa loại tích hợp (REST API, File-based SFTP/CSV, Message Queue Kafka/RabbitMQ, SOAP). Sinh bộ tài liệu 14 mục: tổng quan, mapping dữ liệu, danh sách thay đổi thực thể, luồng E2E, sequence diagram (Mermaid), đặc tả API/file/message chi tiết, ERD đa đối tác, NFR, rủi ro, bộ câu hỏi elicitation và HTML prototype. Sử dụng khi người dùng nói 'phân tích tích hợp đối tác', 'đặc tả integration', 'integration spec', 'tích hợp API bên thứ ba', 'phân tích tích hợp hệ thống'."
+---
+
+# NTAPP Integration Inspection Skill (Stage 1 sub-step)
+
+Sinh bộ tài liệu phân tích & đặc tả tích hợp end-to-end với đối tác — forcing function buộc BA chốt rõ **dữ liệu** (mapping, ERD), **luồng** (E2E 3 giai đoạn, sequence) và **giao kèo kỹ thuật** (đặc tả API, NFR, go-live) trước khi dev/SA vào việc. Điều khiển qua 2 tham số `direction` + `mode`.
+
+Chạy trong **Stage 1 Discovery** khi xuất hiện nhu cầu tích hợp đối tác/bên thứ ba — làm input cho contract surface của HLD/Module 0 (Stage 2).
+
+## Instructions
+
+Read fully and follow: `./workflow.md`

package/skills/NTAPP/.agent/skills/NTAPP-integration-inspection/references/api-spec-template.md

@@ -0,0 +1,160 @@
+---
+Version: 1.0.0
+Author: M2MBA
+Last Updated: 2026-06-09
+Description: Template đặc tả API/Message/File chi tiết + ví dụ — cho Mục 8 của NTAPP-integration-inspection
+---
+
+# Template Đặc tả Chi tiết — Tham chiếu cho Mục 8
+
+Đặc tả theo **đúng thứ tự bảng mapping API↔Sequence (Mục 7)**. REST API dùng template đầy đủ dưới đây. File/Message/SOAP dùng bảng đặc tả tương ứng — xem [`integration-types.md`](integration-types.md) §2.
+
+> **Lưu ý theo `direction`:** `inbound` (mình expose API) → cột "Hành động đề xuất cho đối tác" mô tả đối tác nên làm gì với từng status; nhấn data scoping + PII masking. `outbound` (mình gọi đối tác) → mô tả mình xử lý response/lỗi của đối tác thế nào.
+
+---
+
+## Template REST API
+
+### API [#] — [Tên API]
+
+**Thông tin cơ bản**
+
+| Thuộc tính | Giá trị |
+|-----------|--------|
+| Mục đích | *(mô tả nghiệp vụ)* |
+| Method | GET / POST / PUT / PATCH / DELETE |
+| Endpoint | `/api/v1/[resource]` |
+| Authentication | API Key (Header: `X-API-Key`) / Bearer Token / mTLS |
+| Content-Type | `application/json` |
+| Idempotency | Có / Không *(nếu có: header `Idempotency-Key`)* |
+
+**Request Parameters**
+
+*Path Parameters:*
+| Field | Type | Required | Description | Example |
+|-------|------|---------|-------------|---------|
+
+*Query Parameters:*
+| Field | Type | Required | Default | Description | Example |
+|-------|------|---------|---------|-------------|---------|
+
+*Request Body:*
+| Field | Type | Required | Constraints | Description | Example |
+|-------|------|---------|------------|-------------|---------|
+
+**Response 200 OK**
+
+| Field | Type | Nullable | Description | Example |
+|-------|------|---------|-------------|---------|
+
+> Nếu có pagination, bắt buộc thêm meta object:
+> ```json
+> "meta": { "total": 100, "page": 1, "per_page": 20, "total_pages": 5 }
+> ```
+
+**Ví dụ JSON**
+
+```json
+// Request
+{ "field": "value" }
+
+// Response 200 OK
+{ "data": { ... }, "meta": { ... } }
+
+// Response lỗi (error envelope chuẩn)
+{ "error": { "code": "VALIDATION_ERROR", "message": "Mô tả lỗi", "details": [{ "field": "field_name", "issue": "required" }] } }
+```
+
+**HTTP Status Codes**
+
+| Code | Tên | Nguyên nhân | Hành động đề xuất cho đối tác |
+|------|-----|------------|-------------------------------|
+| 200 | OK | Thành công | Xử lý dữ liệu |
+| 201 | Created | Tạo mới thành công | Lưu id trả về |
+| 400 | Bad Request | Sai định dạng / thiếu field | Kiểm tra payload trước khi gọi lại |
+| 401 | Unauthorized | Token sai/hết hạn | Lấy token mới rồi retry |
+| 403 | Forbidden | Không có quyền với resource | Liên hệ để được cấp quyền |
+| 404 | Not Found | Resource không tồn tại | Bỏ qua, tiếp tục với item tiếp |
+| 409 | Conflict | Trùng dữ liệu (idempotency) | Dùng Idempotency-Key |
+| 429 | Too Many Requests | Vượt rate limit | Xem header `Retry-After`, chờ rồi retry |
+| 500 | Server Error | Lỗi hệ thống | Retry sau 60s, tối đa 3 lần; báo nếu kéo dài |
+
+**Rate Limiting** *(nếu có)*
+- Giới hạn: `X request/phút` per API Key.
+- Header trả về: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.
+
+**Security**
+- Xử lý trường PII: *(che/mask thế nào, vd: `"phone": "090****789"`)*
+- Token TTL & refresh: *(mô tả)*
+- Log: *(ghi request/response ở đâu, lưu bao lâu)*
+
+---
+
+*(Lặp lại template trên cho từng API trong bảng mapping Mục 7.)*
+
+---
+
+## Ví dụ minh họa
+
+### Mô tả quy trình (Mục 5) — `outbound`, REST API
+
+```
+Phần 1 — Chuẩn bị đầu vào  [AUTH]
+Đối tác (hệ thống giao vận) cần: API Key onboarding; danh sách order_code / khoảng thời gian; biết endpoint môi trường.
+
+Phần 2 — Xác thực  [AUTH]
+Bước 1 — Gửi API Key: header `X-API-Key: [key]` trong mọi request.
+Bước 2 — Hệ thống xác thực: kiểm tra key, định danh đối tác, kiểm tra partner scope.
+Bước 3 — Từ chối: key sai → 401 + `INVALID_API_KEY`.
+
+Phần 3 — Luồng chính  [DATA MAPPING] → [INTEGRATION FLOWS]
+[DATA MAPPING] Bước 0 — Thiết lập partner scope (lần đầu): admin cấu hình partner_code/scope/rate limit → lưu PartnerConfig.
+[INTEGRATION FLOWS] Bước 1 — GET /api/v1/orders?from_date&to_date&page → danh sách order_id + meta.
+[INTEGRATION FLOWS] Bước 2 — GET /api/v1/orders/{order_id} với từng id từ Bước 1; 404 thì bỏ qua.
+
+Phần 4 — Xử lý lỗi
+401 INVALID_API_KEY → liên hệ admin cấp lại.
+403 FORBIDDEN → đơn ngoài phạm vi, bỏ qua.
+429 RATE_LIMIT_EXCEEDED → xem Retry-After, chờ rồi retry.
+500 SERVER_ERROR → retry sau 60s, tối đa 3 lần exponential backoff; báo nếu > 5 phút.
+```
+
+### Đặc tả API ví dụ — Lấy danh sách đơn hàng
+
+| Thuộc tính | Giá trị |
+|-----------|--------|
+| Mục đích | Trả danh sách đơn hàng trong khoảng thời gian, phân theo đối tác |
+| Method | GET |
+| Endpoint | `/api/v1/orders` |
+| Authentication | API Key (Header: `X-API-Key`) |
+| Idempotency | Không áp dụng (GET) |
+
+*Query Parameters:*
+
+| Field | Type | Required | Default | Description | Example |
+|-------|------|---------|---------|-------------|---------|
+| from_date | string (ISO 8601) | Có | — | Ngày bắt đầu lọc | `2026-01-01` |
+| to_date | string (ISO 8601) | Có | — | Ngày kết thúc lọc | `2026-01-31` |
+| status | string | Không | all | Lọc theo trạng thái đơn | `confirmed` |
+| page | integer | Không | 1 | Trang hiện tại | `1` |
+| per_page | integer | Không | 20 | Số bản ghi/trang (max 100) | `50` |
+
+```json
+// Response 200 OK
+{
+  "data": [
+    { "orderId": "ORD-2026-001", "orderCode": "DH001", "status": "confirmed",
+      "createdAt": "2026-01-15T08:30:00+07:00", "totalAmount": 250000 }
+  ],
+  "meta": { "total": 150, "page": 1, "per_page": 20, "total_pages": 8 }
+}
+
+// Response lỗi
+{
+  "error": {
+    "code": "INVALID_DATE_RANGE",
+    "message": "Khoảng thời gian không hợp lệ. from_date phải nhỏ hơn to_date.",
+    "details": [ { "field": "from_date", "issue": "must be before to_date" } ]
+  }
+}
+```

package/skills/NTAPP/.agent/skills/NTAPP-integration-inspection/references/elicitation-questions.md

@@ -0,0 +1,113 @@
+---
+Version: 1.0.0
+Author: M2MBA
+Last Updated: 2026-06-09
+Description: Bộ câu hỏi elicitation (khơi gợi per-mục + nhóm A/B/C) — cho Mục 12 của NTAPP-integration-inspection
+---
+
+# Bộ câu hỏi Elicitation — Tham chiếu cho Mục 12
+
+Hai tầng câu hỏi:
+- **Tầng 1 — Câu hỏi khơi gợi per-mục:** ở `mode: interactive`, hỏi sau mỗi mục để confirm. Ghi nhận câu chưa có câu trả lời.
+- **Tầng 2 — Bộ câu hỏi nhóm A/B/C:** tổng hợp ở Mục 12, dùng cho buổi elicitation chính thức với Biz / Đối tác / 3-way.
+
+---
+
+## Tầng 1 — Câu hỏi khơi gợi theo mục
+
+**Mục 2 (Dữ liệu & mapping)**
+- *Nghiệp vụ:* Trường "Có sẵn" có được cập nhật đầy đủ & nhất quán không? Trường "Chưa có" có thể derive từ dữ liệu sẵn có? Đối tác đặt tên trường khác nội bộ (cần alias mapping)?
+- *Dữ liệu:* Format ngày/tiền tệ/mã vùng có khớp? Trường null/optional đối tác xử lý sao? Enum/lookup đối tác dùng mã nào?
+- *Bảo mật:* Trường PII nào (SĐT/CCCD/địa chỉ/tài chính) cần mask? Đối tác lấy tất cả bản ghi hay chỉ data thuộc scope (data scoping)?
+
+**Mục 3 / 4 (Chức năng & thay đổi thực thể)**
+- *Nghiệp vụ:* Chức năng thay đổi — bên nội bộ nào khác đang dùng (impact)? Ảnh hưởng màn hình/report/export nào? Cần phối hợp team nào?
+- *Dữ liệu:* Dữ liệu lịch sử sau khi thêm trường xử lý sao (null/backfill/default)? Trường mới bắt buộc nhập? Validation? Cần migration script?
+- *Bảo mật:* Cần thêm role/permission nội bộ? Cần audit log (ai sửa, lúc nào, giá trị cũ/mới)?
+
+**Mục 5 / 6 (Luồng & sequence)**
+- Có bước thứ tự thay đổi tùy điều kiện (branching)? Còn luồng ngoài happy path (hủy, token hết hạn, trùng, timeout)?
+- Tích hợp sync (real-time) hay async (webhook/polling)? Token refresh xảy ra ở bước nào?
+- Đối tác cần lưu dữ liệu trung gian (session_id…) để dùng bước tiếp?
+
+**Mục 8 (Đặc tả API)**
+- Response nhiều bản ghi — cần pagination flow? Log/audit ghi ở tầng nào (Gateway/Backend)? Nếu async — webhook hay polling, timeout bao lâu báo lỗi?
+
+---
+
+## Tầng 2 — Nhóm A: Hỏi Stakeholder Biz (Product Owner)
+*Tập trung: tại sao, cái gì, kỳ vọng nghiệp vụ.*
+
+**Mục tiêu & phạm vi:** Tích hợp giải quyết vấn đề gì? KPI kỳ vọng? Phạm vi giai đoạn 1 gồm luồng nào, luồng nào roadmap sau? Nếu thất bại/chậm, nghiệp vụ bị ảnh hưởng thế nào?
+
+**Quy tắc & ngoại lệ:** Có trường hợp xử lý khác luồng thường (VIP, đơn đặc biệt, vùng không phục vụ)? Khi dữ liệu hai bên mâu thuẫn, bên nào là source of truth? Có thứ tự xử lý/điều kiện tiên quyết nào tài liệu API chưa đề cập?
+
+**Hiệu năng & SLA:** Real-time / near-real-time / batch? Tần suất nếu batch? Nếu đối tác downtime, fallback thủ công là gì, ai làm? Delay tối đa chấp nhận được?
+
+**Bảo mật & tuân thủ:** Có PII / dữ liệu tài chính / nhạy cảm? Compliance nào (GDPR, PCI-DSS, Thông tư NH…)? Ai được xem/sửa dữ liệu tích hợp phía nghiệp vụ?
+
+**Vận hành sau go-live:** Ai xử lý incident phía nội bộ? Cần dashboard theo dõi? Quy trình phê duyệt thay đổi cấu hình tích hợp?
+
+---
+
+## Tầng 2 — Nhóm B: Hỏi Đối tác (Technical Team)
+*Câu hỏi đổi theo loại tích hợp đã nhận diện.*
+
+**Chung mọi loại:** Sandbox có không, ai cấp credential, đủ edge case? Breaking change báo trước bao lâu, qua kênh nào? Đầu mối kỹ thuật & SLA hỗ trợ? Encoding/timezone/định dạng ngày chuẩn gì?
+
+**🌐 REST API:** OAuth2/API Key/mTLS? Token expiry & refresh? Rate limit (req/giây hoặc /ngày), quota theo account? Idempotency — gọi trùng xử lý sao? Timeout mặc định, retry do ai? Có webhook/callback? Giá trị null/field thiếu xử lý sao?
+
+**📁 File-based:** Giao thức (SFTP/FTPS/S3/API upload), credential dạng gì? Naming convention cố định, nhiều file cùng ngày? Header row? Encoding (UTF-8/BOM/Windows-1252)? Delimiter & escape char? File lỗi cấu trúc — reject toàn bộ hay partial? Có file acknowledgement? Dọn dẹp thư mục processed/error? Cơ chế báo khi file trễ giờ?
+
+**📨 Message Queue:** Broker gì + version? Delivery guarantee (at-most/at-least/exactly-once)? Ordering đảm bảo (per partition/queue)? Schema format (JSON/Avro/Protobuf), có Schema Registry? Consumer fail — DLQ/retry/thủ công? Retention bao lâu? Tự quản offset? Replay từ offset cụ thể? Throughput dự kiến?
+
+**🔧 SOAP / Web Service:** WSDL endpoint ổn định hay đổi theo môi trường? WS-Security UsernameToken hay Certificate? Giới hạn kích thước SOAP envelope? Fault code/FaultString chuẩn hoá thế nào? Có MTOM/XOP cho attachment?
+
+---
+
+## Tầng 2 — Nhóm C: Confirm cả hai bên (buổi 3-way)
+
+| Chủ đề | Câu hỏi cần confirm |
+|--------|---------------------|
+| **Field mapping** | Tên field biz vs đối tác? Kiểu dữ liệu có khớp? |
+| **Status mapping** | Trạng thái đối tác trả về có map 1-1 với nội bộ? Có trạng thái nào chưa mapping? |
+| **Rollout plan** | Go-live khi nào? Cutover data cũ thế nào? Kế hoạch rollback? |
+| **Data reconciliation** | Nếu dữ liệu hai bên lệch, quy trình đối chiếu & xử lý? Tần suất? |
+| **Ownership incident** | Đầu mối khi có sự cố? Alert gửi đâu? Escalation path? |
+| **Môi trường chuyển đổi** | Khi nào sandbox → production? Điều kiện kiểm tra gì? |
+
+> 💡 **Tip:** Tổ chức ít nhất 2 buổi riêng (Biz, Đối tác) trước buổi 3-way. Buổi 3-way chưa align trước thường tốn thời gian giải thích khái niệm cơ bản thay vì ra quyết định.
+
+---
+
+## Cách sinh câu hỏi ưu tiên (Mục 12)
+
+Sau khi hoàn thành 14 mục, tự động:
+1. **Rà [Giả định]** trong tài liệu → đánh dấu 🔴 (chưa có thông tin) vào câu hỏi liên quan.
+2. **Rà field chưa rõ Source** (Mục 2) → đánh dấu 🟡 (cần confirm) vào nhóm A/B.
+3. **Rà field Persist=Yes nhưng Purpose chưa rõ** → thêm câu hỏi đối soát/tracking vào nhóm C.
+4. In danh sách theo ưu tiên (🔴 trước, 🟡 sau), gom theo nhóm A/B/C.
+
+Bảng tổng hợp Mục 12:
+
+| # | Câu hỏi cần làm rõ | Nhóm | Mục liên quan | Ảnh hưởng nếu không rõ | Ưu tiên |
+|---|-------------------|------|---------------|----------------------|---------|
+| 1 | *(câu hỏi)* | Nghiệp vụ / Dữ liệu / Bảo mật / Vận hành | Mục X | *(rủi ro)* | Cao / TB / Thấp |
+
+*Phân loại ưu tiên:* **Cao** = không rõ thì không thiết kế đúng (block); **Trung bình** = ảnh hưởng chất lượng/độ chính xác; **Thấp** = làm rõ được sau khi bắt đầu triển khai.
+
+**Ví dụ output:**
+```
+📋 BỘ CÂU HỎI ELICITATION — [Tên đối tác]
+
+=== NHÓM A — Stakeholder Biz ===
+🔴 [Mục tiêu] Nếu CreateShipment thất bại, fallback thủ công là gì?
+🟡 [SLA] Thời gian đồng bộ trạng thái đơn tối đa bao lâu?
+
+=== NHÓM B — Đối tác ===
+🔴 [Reliability] API CreateCustomer có idempotency không?
+🟡 [Data] Trường `status` có thể thêm giá trị mới không báo trước không?
+
+=== NHÓM C — Confirm hai bên ===
+🔴 [Status mapping] "RETURNED" của đối tác map sang trạng thái nội bộ nào?
+```

package/skills/NTAPP/.agent/skills/NTAPP-integration-inspection/references/erd-and-mapping.md

@@ -0,0 +1,124 @@
+---
+Version: 1.0.0
+Author: M2MBA
+Last Updated: 2026-06-09
+Description: Bảng mapping dữ liệu, danh sách thay đổi thực thể, và ERD đa đối tác — cho Mục 2, 4, 9 của NTAPP-integration-inspection
+---
+
+# Mapping dữ liệu, Thay đổi thực thể & ERD — Tham chiếu cho Mục 2, 4, 9
+
+---
+
+## A. Mục 2 — Dữ liệu & mapping nội bộ
+
+So sánh từng trường đối tác cần với ERD/model nội bộ. Bảng phân tích trạng thái:
+
+| Tên trường (đối tác) | Tên trường nội bộ | Thực thể | Trạng thái | Kiểu dữ liệu | Ghi chú / Rủi ro |
+|---------------------|------------------|----------|-----------|--------------|-----------------|
+| *(tên đối tác đặt)* | *(tên cột DB)* | *(bảng)* | ✅ Có sẵn / ⚠️ Cần transform / ❌ Chưa có | string/int/... | *(format khác biệt, null risk, PII…)* |
+
+**Chú giải trạng thái:**
+- ✅ **Có sẵn** — trường tồn tại, format khớp, dùng được ngay.
+- ⚠️ **Cần transform** — tồn tại nhưng cần convert format/mapping logic.
+- ❌ **Chưa có** — phải thêm mới vào DB hoặc tính toán từ trường khác.
+
+### Bảng mapping chi tiết IN/OUT (góc nhìn field-level)
+
+Với mỗi API / file / message, sinh bảng đầy đủ (`[IN]` = đầu vào, `[OUT]` = đầu ra):
+
+| Field / Cột | IN/OUT | Type | Required | Source | Default/Rule | Validation | Mapping nội bộ | Persist? | Purpose | Notes |
+|---|---|---|---|---|---|---|---|---|---|---|
+
+- **[IN] Source** đổi theo loại — xem [`integration-types.md`](integration-types.md) §4.
+- **[OUT]**: xác định `Mapping nội bộ` (bảng/trường nào), `Persist?` (Yes/No), `Purpose` (truy vết / đối soát / hiển thị / phục vụ call tiếp / đa đối tác), `Notes` (normalization khi nhiều đối tác dùng field/format khác nhau).
+- **Góc nhìn cấu hình:** field nào cần màn hình cấu hình, bảng master, hard-code per-partner?
+- **Góc nhìn lưu trữ:** field nào bắt buộc lưu, lưu để làm gì, cần bảng mapping status không?
+
+---
+
+## B. Mục 4 — Danh sách thay đổi thực thể dữ liệu *(BẮT BUỘC)*
+
+Với các trường "Chưa có" / "Cần transform", chốt scope dữ liệu bằng 3 phần:
+
+**Phần A — Thực thể thêm mới**
+
+| Thực thể mới | Mục đích nghiệp vụ | Khóa chính | Quan hệ với thực thể hiện có | Ghi chú |
+|-------------|-------------------|-----------|------------------------------|---------|
+
+**Phần B — Thực thể bổ sung trường**
+
+| Thực thể hiện có | Trường bổ sung | Kiểu dữ liệu | Bắt buộc | Giá trị mặc định | Mô tả nghiệp vụ |
+|-----------------|--------------|-------------|---------|-----------------|----------------|
+
+**Phần C — Dataset chi tiết theo từng thực thể thay đổi**
+
+> Convention tên field: xem [`integration-types.md`](integration-types.md) §6.
+
+| Field (DB) | Field (API) | Type | Required | Constraints | Description | Example |
+|-----------|------------|------|---------|-------------|-------------|---------|
+
+**Câu hỏi cần làm rõ ở phần này:**
+- Trường mới phát sinh từ rule nghiệp vụ nào? Có cần lưu lịch sử thay đổi (SCD)?
+- Có cần backfill dữ liệu cũ không? Theo logic gì?
+- Trường nào immutable sau khi duyệt/xác nhận?
+- Có cần unique constraint chống trùng dữ liệu tích hợp (vd: `partner_order_id`)?
+
+---
+
+## C. Mục 9 — ERD tích hợp đa đối tác *(BẮT BUỘC)*
+
+- Chỉ thể hiện thực thể liên quan trực tiếp đến luồng tích hợp.
+- Bao gồm thực thể **thêm mới** (Phần A) và **bổ sung trường** (Phần B).
+- Annotation trên đường quan hệ phải mô tả **nghiệp vụ**, không chỉ ghi "relates".
+
+### Nguyên tắc thiết kế
+
+- Nếu user **CÓ ERD hiện tại**: đọc ERD → chỉ liệt kê field bổ sung trên bảng đã có + bảng mới cần tạo → confirm trước khi vẽ.
+- Nếu user **KHÔNG có ERD**: đề xuất ERD từ đầu, đánh dấu **[Giả định]**.
+- 🔷 **Tư duy đa đối tác (bắt buộc):** có cột `partner_code` hoặc bảng `PartnerConfig`; bảng log/tracking per-partner; bảng mapping chuẩn hoá (status/service/product…); giữ **raw data** để đối soát. KHÔNG hardcode 1 đối tác.
+
+### ERD mẫu — nghiệp vụ mở rộng
+
+```mermaid
+erDiagram
+    ENTITY_A {
+        int id PK
+        string field_1
+        string new_field "thêm mới cho tích hợp"
+    }
+    ENTITY_B {
+        int id PK
+        int entity_a_id FK
+        string field_x
+    }
+    ENTITY_A ||--o{ ENTITY_B : "chứa nhiều"
+    NEW_ENTITY {
+        int id PK
+        string partner_ref_id UK "unique per partner"
+        string partner_code FK "đa đối tác"
+        int entity_a_id FK
+    }
+    ENTITY_A ||--o{ NEW_ENTITY : "phát sinh khi tích hợp"
+    PARTNER_CONFIG {
+        int id PK
+        string partner_code UK
+        string api_key_hash
+        string scope_config
+    }
+    PARTNER_CONFIG ||--o{ NEW_ENTITY : "cấu hình per-partner"
+```
+
+### ERD mẫu — log/audit chung mọi loại
+
+```mermaid
+erDiagram
+    PARTNER { string id string code string type }
+    INTEGRATION_EVENT { string id string partner_id string event_type string status }
+    FILE_TRANSFER_LOG { string id string partner_id string file_name string status int record_count }
+    MESSAGE_INBOUND_LOG { string id string topic string offset string status string payload_raw }
+    PARTNER ||--o{ INTEGRATION_EVENT : triggers
+    PARTNER ||--o{ FILE_TRANSFER_LOG : sends
+    PARTNER ||--o{ MESSAGE_INBOUND_LOG : publishes
+```
+
+Bảng log đặc thù nên thêm theo loại: xem [`integration-types.md`](integration-types.md) §5.