12 Api And Integration Analysis

Trường kiểm soát	Giá trị
Tên tệp được kiểm soát	`/02-handbook/12-api-and-integration-analysis.md`
Trạng thái	`IN_REVIEW`
Phiên bản	`v0.9.0`
Ngày cập nhật	`2026-08-07`
Múi giờ quản trị	`Asia/Ho_Chi_Minh`
Locale	`vi-VN`
Bối cảnh quốc gia	Việt Nam
Đơn vị tiền tệ mô phỏng	`VND`
Case study	Nova Foods Trading & Manufacturing — mô phỏng giáo dục, chỉ dùng dữ liệu tổng hợp
Owner	Principal IT Business Analyst / Technical Curriculum Author
Thẩm quyền Owner	Duy trì cấu trúc, metadata, traceability và lịch sử thay đổi; không tự baseline, không ghi nhận approval, không quyết định nghiệp vụ, kiến trúc, pháp lý, kế toán, bảo mật hoặc production
Baseline reference	Chưa có baseline reference tại `v0.9.0`
Approval reference	Chưa có approval reference tại `v0.9.0`
Nguồn chính	OpenAPI Specification, OAS 3.1.1, nguồn normative cho mô tả HTTP API: https://spec.openapis.org/oas/v3.1.1.html
Nguồn bổ trợ	BABOK Guide Version 3, nguồn chính cho thuật ngữ và thực hành BA: https://www.iiba.org/career-resources/a-business-analysis-professionals-foundation-for-success/babok/
Ngày truy cập nguồn	`2026-08-07`

1. Concept l? g??

Core

API là viết tắt của Application Programming Interface, nghĩa là giao diện để phần mềm trao đổi với phần mềm. Con người không cần nhập dữ liệu trực tiếp vào API. Một hệ thống gửi yêu cầu theo cấu trúc đã thống nhất; hệ thống khác kiểm tra yêu cầu, xử lý và trả kết quả. API vì vậy là điểm tiếp xúc có kiểm soát giữa các hệ thống.

Integration, nghĩa là tích hợp, là khả năng nhiều hệ thống phối hợp để hoàn thành một mục tiêu nghiệp vụ. API là một cách thực hiện integration, không phải toàn bộ integration. Tích hợp còn cần xác định dữ liệu nào được gửi, lúc nào gửi, hệ thống nào là nguồn dữ liệu đáng tin, lỗi được xử lý ra sao, và kết quả nào chứng minh giao dịch đã hoàn tất. Lý do: hai hệ thống có thể gọi được API nhưng vẫn gây sai lệch nếu cùng sửa một mã hàng hoặc hiểu khác nhau về trạng thái đơn hàng.

Trong phân tích BA, API and Integration Analysis là hoạt động làm rõ hợp đồng trao đổi giữa các hệ thống. “Hợp đồng” ở đây không phải hợp đồng pháp lý; nó là mô tả có thể kiểm tra về yêu cầu gửi vào, dữ liệu trả ra, quy tắc xử lý, lỗi, bảo mật, thời điểm và trách nhiệm từng bên. BA không mặc định một API đang tồn tại là phù hợp. BA cần nối mục tiêu nghiệp vụ với dữ liệu, hành vi hệ thống và bằng chứng kiểm thử.

12-api-and-integration-analysis — diagram 1

Source mermaid — có thể chỉnh sửa

flowchart LR
    ERP[Nova Foods ERP<br/>mô phỏng] -->|HTTP API request| WMS[Warehouse System<br/>mô phỏng]
    WMS -->|HTTP API response| ERP
    ERP -->|Trạng thái giao dịch| User[Người dùng nghiệp vụ]

Sơ đồ cho thấy luồng kỹ thuật tối thiểu. Nó chưa chứng minh ai được quyền gọi API, dữ liệu nào hợp lệ, hay giao dịch có được ghi nhận thành công. Các điều kiện đó phải được phân tích riêng vì chúng quyết định tính đúng của tích hợp.

Phạm vi khái niệm chương này: phân tích giao tiếp hệ thống-với-hệ thống qua API hoặc cơ chế tích hợp tương đương, gồm mục đích trao đổi, dữ liệu, hành vi, lỗi và ranh giới trách nhiệm. Loại trừ: thiết kế chi tiết mã nguồn, cấu hình hạ tầng production, lựa chọn nhà cung cấp, phê duyệt kiến trúc, xác nhận tuân thủ pháp lý và quyết định vận hành thực tế của Nova Foods. Nova Foods trong tài liệu này là case study mô phỏng; mọi dữ liệu là dữ liệu tổng hợp.

Core

Thuật ngữ	Nghĩa chính xác trong phân tích API và tích hợp	Câu hỏi BA phải làm rõ
API (Application Programming Interface)	Giao diện để một phần mềm yêu cầu hoặc nhận dữ liệu, chức năng từ phần mềm khác theo quy ước xác định. API không tự là quy trình nghiệp vụ; nó là điểm giao tiếp kỹ thuật phục vụ quy trình.	Hệ thống nào gọi, gọi khi nào, gửi gì, nhận gì, lỗi xử lý ra sao?
Integration	Tích hợp: kết nối có kiểm soát giữa ít nhất hai hệ thống để truyền dữ liệu hoặc kích hoạt hành động.	Mục tiêu nghiệp vụ nào cần kết nối này, thay vì nhập tay hoặc dùng hệ thống hiện có?
Actor	Tác nhân khởi tạo, nhận, xử lý hoặc chịu trách nhiệm cho một tương tác. Actor có thể là người dùng, ERP, ứng dụng bán hàng, dịch vụ tích hợp hoặc hệ thống bên thứ ba.	Actor nào bắt đầu tương tác? Actor nào là nguồn dữ liệu và nguồn quyết định?
Action	Hành động hệ thống thực hiện, ví dụ tạo đơn hàng, tra cứu tồn kho, cập nhật trạng thái giao hàng. Action phải dùng động từ kiểm chứng được.	Hành động đọc, tạo, sửa, hủy hay gửi thông báo?
Object	Đối tượng nghiệp vụ hoặc dữ liệu bị tác động, ví dụ `SalesOrder`, `Customer`, `InventoryItem`, `DeliveryStatus`. Object không đồng nghĩa bảng DB; một object có thể gồm nhiều trường từ nhiều nơi lưu trữ.	Đối tượng nào được đọc hoặc thay đổi? Định danh nào nhận diện duy nhất đối tượng?
Outcome	Kết quả quan sát được sau action, gồm thành công, từ chối hoặc lỗi. Outcome phải có ý nghĩa nghiệp vụ và trạng thái kỹ thuật tương ứng.	Ai dùng kết quả? Kết quả nào cho phép bước tiếp theo?
Request	Yêu cầu gửi từ bên gọi đến API, thường gồm phương thức HTTP, URL, header, tham số và nội dung dữ liệu.	Dữ liệu tối thiểu nào bên gọi phải gửi?
Response	Phản hồi API trả về cho bên gọi, gồm mã trạng thái và dữ liệu hoặc lỗi.	Phản hồi nào chứng minh action hoàn tất, chưa hoàn tất, hoặc bị từ chối?
HTTP (Hypertext Transfer Protocol)	Giao thức web thường dùng để truyền request và response. Các phương thức phổ biến: `GET` đọc, `POST` tạo hoặc gửi yêu cầu xử lý, `PUT` thay toàn bộ, `PATCH` sửa một phần, `DELETE` xóa. Ý nghĩa cụ thể vẫn phải được đặc tả API xác nhận.	Phương thức có phản ánh đúng action và rủi ro thay đổi dữ liệu không?
Endpoint	Điểm truy cập API cụ thể, thường là tổ hợp HTTP method và URL path, ví dụ `POST /sales-orders`.	Endpoint phục vụ một năng lực nghiệp vụ rõ ràng nào?
Payload	Dữ liệu trong thân request hoặc response, thường ở dạng JSON.	Trường nào bắt buộc, trường nào tùy chọn, kiểu dữ liệu và quy tắc kiểm tra là gì?
JSON (JavaScript Object Notation)	Định dạng văn bản có cấu trúc để biểu diễn dữ liệu theo cặp tên–giá trị và danh sách. JSON là cách đóng gói dữ liệu, không tự bảo đảm dữ liệu đúng nghiệp vụ.	Tên trường, kiểu dữ liệu, giá trị rỗng và định dạng ngày giờ đã thống nhất chưa?
System of Record	Hệ thống nguồn có thẩm quyền ghi nhận cho một loại dữ liệu trong phạm vi đã định. Ví dụ, ERP có thể là nguồn ghi nhận đơn bán; điều này phải được xác định, không suy đoán từ việc ERP gửi dữ liệu.	Hệ thống nào được phép tạo, sửa, và quyết định bản ghi cuối cùng?
Synchronous	Đồng bộ: bên gọi chờ response trong cùng phiên giao tiếp để biết kết quả. Phù hợp khi bước sau cần kết quả ngay.	Người dùng hoặc hệ thống có cần biết kết quả trước khi tiếp tục không?
Asynchronous	Bất đồng bộ: bên gọi nhận xác nhận đã nhận yêu cầu, còn xử lý hoàn tất sau. Phù hợp khi xử lý lâu hoặc cần chống gián đoạn giữa hệ thống.	Cần trạng thái theo dõi nào khi chưa có kết quả cuối?
Idempotency	Tính lặp an toàn: gửi lại cùng một yêu cầu không tạo thêm tác động nghiệp vụ ngoài lần hợp lệ đầu tiên. Ví dụ, gửi lại yêu cầu tạo cùng đơn không được sinh hai đơn.	Nếu mạng lỗi và request bị gửi lại, object có bị tạo trùng không?

Công thức phân tích tối thiểu: Actor thực hiện Action lên Object để đạt Outcome. Ví dụ mô phỏng: ứng dụng bán hàng là actor, gửi action tạo đơn bán lên ERP Nova Foods, object là SalesOrder, outcome là ERP trả mã đơn hoặc lý do từ chối. Cầu nối suy luận: thiếu bất kỳ thành phần nào thì BA không xác định được ai chịu trách nhiệm, dữ liệu nào đổi, hoặc kết quả nào cần kiểm thử.

Phân biệt ranh giới: API mô tả cách hệ thống giao tiếp; integration mô tả luồng kết nối và tác động giữa hệ thống. API không tự quyết định quy tắc giá, thẩm quyền phê duyệt, chính sách tồn kho, pháp lý, kế toán hay cấu hình production. Các nội dung Nova Foods trong chương này là mô phỏng giáo dục, dữ liệu tổng hợp, trạng thái IN_REVIEW, phiên bản v0.9.0, ngày 2026-08-07; không phải xác nhận vận hành hay phê duyệt.

Applied

Nova Foods Trading & Manufacturing là case study mô phỏng giáo dục; mọi ID, tên hệ thống và dữ liệu dưới đây là dữ liệu tổng hợp.

Mục	Nội dung
Facts	ERP Nova Foods cần gửi thông tin đơn hàng đã xác nhận sang cổng giao hàng mô phỏng `Nova Delivery Hub`. Đơn hàng tổng hợp `SO-SIM-00017` có tổng tiền `1.250.000 VND`.
Current Behavior	Nhân viên kho xem đơn trên ERP, rồi nhập tay mã đơn, địa chỉ giao và số lượng sang `Nova Delivery Hub`. Cùng một dữ liệu bị nhập ở hai nơi.
Underlying Need	Khi ERP xác nhận đơn, hệ thống giao hàng phải nhận đủ dữ liệu giao để tạo yêu cầu giao hàng, không cần nhập lại. Nhu cầu là trao đổi dữ liệu giữa hai hệ thống, không phải thay màn hình ERP.
Options	(1) Nhập tay. (2) ERP xuất tệp CSV để nhân viên tải lên. (3) ERP gọi HTTP API của `Nova Delivery Hub` để gửi đơn tự động.
Decision Criteria	Đủ dữ liệu; giảm nhập lặp; có phản hồi thành công hoặc lỗi; truy vết được `SO-SIM-00017`; không tạo quyết định cấu hình production.
Decision	Dùng ví dụ API đồng bộ: ERP gửi yêu cầu tạo giao hàng khi trạng thái đơn là `Confirmed`; Hub trả về mã giao hàng mô phỏng. Đây là quyết định minh họa học liệu, không phải quyết định kiến trúc.
Authority	Business Owner xác nhận thời điểm nghiệp vụ cần tạo giao hàng. Solution Architect xác nhận kiểu tích hợp và bảo mật. Security Owner xác nhận kiểm soát truy cập. BA ghi nhận nhu cầu, dữ liệu và truy vết; không tự phê duyệt các quyết định này.
Artifact	Bản ghi phân tích tích hợp cho luồng `ERP Order Confirmation` sang `Nova Delivery Hub`, gắn với `SO-SIM-00017`; trạng thái corpus `IN_REVIEW`, version `v0.9.0`, ngày `2026-08-07`.
Consequence if Wrong	Gửi sai mã đơn có thể tạo giao trùng. Thiếu địa chỉ giao có thể làm Hub từ chối yêu cầu. Không lưu phản hồi làm nhân viên không biết đơn đã được gửi hay chưa.

12-api-and-integration-analysis — diagram 2

Source mermaid — có thể chỉnh sửa

sequenceDiagram
    autonumber
    participant ERP as Nova Foods ERP
    participant Hub as Nova Delivery Hub

    ERP->>ERP: Xác nhận SO-SIM-00017
    ERP->>Hub: POST /deliveries<br/>orderId, deliveryAddress, items
    Note over ERP,Hub: orderId sai có thể tạo giao trùng
    alt Dữ liệu hợp lệ
        Hub-->>ERP: 201 Created<br/>deliveryId DL-SIM-00421
        ERP->>ERP: Lưu deliveryId<br/>trạng thái gửi thành công
    else Thiếu deliveryAddress
        Hub-->>ERP: Lỗi<br/>thiếu deliveryAddress
        ERP->>ERP: Lưu lỗi<br/>trạng thái gửi thất bại
    end

Ranh giới khái niệm: API (Application Programming Interface, giao diện để phần mềm gọi chức năng hoặc trao đổi dữ liệu) là điểm tiếp xúc có quy ước giữa ERP và Hub. Trong ví dụ, actor là Nova Foods ERP, tức bên khởi tạo giao tiếp; action là gửi yêu cầu POST /deliveries; object là dữ liệu yêu cầu giao của SO-SIM-00017; outcome là Hub trả deliveryId hoặc lỗi. “Integration” (tích hợp) rộng hơn API: nó gồm luồng dữ liệu, thời điểm gửi, ánh xạ trường, xử lý lỗi và trách nhiệm giữa các hệ thống.

Ngoài phạm vi ví dụ này: thiết kế API đầy đủ theo OpenAPI Specification, xác thực, phân quyền, mã hóa, cơ chế thử lại, hàng đợi, giám sát, SLA, cấu hình ERP, quyết định nhà cung cấp, dữ liệu cá nhân thật, nghĩa vụ pháp lý, kế toán và vận hành production. Các nội dung đó cần artifact và vai trò có thẩm quyền riêng; không được suy ra từ ví dụ mô phỏng này.

2. T?i sao concept n?y t?n t?i?

Core

Phân tích API và tích hợp tồn tại để biến nhu cầu “hệ thống này gửi dữ liệu cho hệ thống kia” thành cam kết có thể kiểm tra: hệ thống nào khởi tạo, gửi dữ liệu gì, khi nào gửi, bên nhận phản hồi gì, lỗi được ghi nhận ở đâu, ai chịu trách nhiệm xử lý. Nếu thiếu phân tích này, cùng một câu nghiệp vụ có thể bị hiểu thành nhiều cách kỹ thuật khác nhau. Đội ERP có thể hiểu “gửi đơn giao hàng” là gửi khi đơn được tạo; đội nhận hàng có thể hiểu là chỉ nhận khi đơn đã xác nhận. Hai bên đều phát triển đúng theo cách hiểu riêng, nhưng luồng thật không chạy đúng.

Rủi ro chính là mơ hồ tại ranh giới hệ thống. Ranh giới này gồm dữ liệu, thời điểm, trạng thái, giao thức và quyền sở hữu lỗi. Một trường thiếu định nghĩa như orderId có thể là mã đơn ERP, mã đơn khách hàng hoặc mã giao hàng. Một phản hồi HTTP 201 Created chỉ cho biết bên nhận đã tạo tài nguyên; nó không tự chứng minh ERP đã lưu kết quả hoặc nhân viên có thể tra cứu lại. BA cần phân tích ranh giới trước khi đội kỹ thuật xây dựng, vì sửa hợp đồng tích hợp sau khi hai hệ thống đã phát triển thường tạo rework cho ánh xạ dữ liệu, kiểm thử, vận hành và tài liệu.

12-api-and-integration-analysis — diagram 3

Source mermaid — có thể chỉnh sửa

flowchart TB
    NEED["Nhu cầu tích hợp cần xác nhận"]

    NEED --> WHEN{"Điều kiện gửi đã thống nhất?"}
    WHEN -->|"Không"| REWORK["Sửa hợp đồng tích hợp"]
    WHEN -->|"Có"| ORDER_ID{"Hai hệ thống diễn giải orderId giống nhau?"}

    ORDER_ID -->|"Không"| REWORK
    ORDER_ID -->|"Có"| FIELDS{"Trường bắt buộc tương thích?"}

    FIELDS -->|"Không"| REJECT_RISK["Yêu cầu có thể bị từ chối"]
    REJECT_RISK --> REWORK
    FIELDS -->|"Có"| PROTOCOL{"Giao thức truyền đã thống nhất?"}

    PROTOCOL -->|"Không"| REWORK
    PROTOCOL -->|"Có"| ERROR_RULE{"Nơi ghi lỗi và bên xử lý đã thống nhất?"}

    ERROR_RULE -->|"Không"| REWORK
    ERROR_RULE -->|"Có"| READY["ERP khởi tạo yêu cầu theo điều kiện đã thống nhất"]

    READY --> SEND["ERP gửi payload qua API"]
    SEND --> HUB["Hệ thống nhận tiếp nhận yêu cầu"]
    HUB --> RESPONSE{"Phản hồi từ hệ thống nhận"}

    RESPONSE -->|"HTTP 201 Created"| CREATED["Tài nguyên đã được tạo tại hệ thống nhận"]
    CREATED --> SAVED{"ERP đã lưu kết quả và nhân viên tra cứu được?"}
    SAVED -->|"Có"| DONE["Kết quả tích hợp kiểm tra được"]
    SAVED -->|"Không"| INCOMPLETE["Chưa chứng minh ERP đã lưu và tra cứu được"]

    RESPONSE -->|"Phản hồi lỗi"| LOG["Ghi lỗi tại nơi đã thống nhất"]
    LOG --> OWNER["Bên ERP hoặc bên nhận đã được hai bên thống nhất tiếp nhận lỗi"]
    OWNER --> HANDLED["Bên chịu trách nhiệm xử lý và ghi nhận kết quả"]

Applied

Trong Nova Foods Trading & Manufacturing mô phỏng, yêu cầu “ERP gửi đơn đã xác nhận sang Nova Delivery Hub” không đủ để lập trình an toàn. Câu này chưa nêu sự kiện kích hoạt, trường dữ liệu tối thiểu, cách xác định gửi thành công, hay cách xử lý khi Hub không phản hồi. Phân tích tích hợp ngăn dự án biến khoảng trống đó thành quyết định ngầm của từng lập trình viên.

Rủi ro bị ngăn	Nếu không phân tích	Tác động quan sát được	Phần cần làm rõ trong artifact tích hợp
Sai thời điểm gửi	ERP gửi khi tạo đơn, Hub chờ đơn xác nhận	Hub nhận đơn chưa sẵn sàng giao	Sự kiện kích hoạt và trạng thái nguồn
Sai định danh	Hai bên dùng khác nghĩa cho mã đơn	Không đối chiếu được đơn ERP với yêu cầu giao	Chủ sở hữu, định dạng, tính duy nhất của `orderId`
Thiếu dữ liệu	ERP không gửi địa chỉ hoặc dòng hàng	Hub từ chối hoặc tạo yêu cầu không đủ thông tin	Trường bắt buộc, trường tùy chọn, quy tắc ánh xạ
Mất dấu lỗi	Hub trả lỗi nhưng ERP không lưu phản hồi	Nhân viên không biết cần gửi lại hay xử lý tay	Mã phản hồi, trạng thái lỗi, nơi tra cứu
Trùng giao dịch	Nhân viên hoặc hệ thống gửi lại cùng đơn	Hub có thể tạo nhiều yêu cầu giao	Khóa chống trùng và quy tắc gửi lại

Senior Lens

Phân tích API không nhằm chọn công nghệ trước. Nó nhằm giảm rủi ro quyết định sai vì dữ liệu và trách nhiệm chưa rõ. OpenAPI Specification OAS 3.1.1 là chuẩn mô tả HTTP API; nó có thể ghi rõ endpoint, request, response và schema. Nhưng OAS không tự quyết định quy tắc nghiệp vụ như “đơn nào được phép gửi” hoặc “ai xử lý giao dịch thất bại”. BA phải làm rõ nhu cầu và bằng chứng trước; Architect, Security và đội kỹ thuật quyết định phần thuộc thẩm quyền kỹ thuật.

Không được coi trạng thái IN_REVIEW của corpus Nova Foods là bằng chứng rằng luồng tích hợp đã được baseline, phê duyệt hoặc sẵn sàng production. Nova Foods là case study mô phỏng giáo dục; mọi mã đơn, hệ thống và dữ liệu trong ví dụ là dữ liệu tổng hợp. Yêu cầu liên quan dữ liệu cá nhân, bảo mật, kế toán, hóa đơn, an toàn thực phẩm hoặc truy xuất nguồn gốc cần xác minh với owner có thẩm quyền và nguồn chính thức phù hợp.

Quick Reference

Quy tắc	Lý do
Không viết “đồng bộ đơn hàng” như một yêu cầu hoàn chỉnh	Cụm này không xác định hệ thống nguồn, đích, dữ liệu, thời điểm hay kết quả
Không suy diễn phản hồi thành thành công nghiệp vụ	Phản hồi kỹ thuật cần được liên kết với trạng thái nghiệp vụ và bản ghi ERP
Không để lỗi chỉ nằm trong log kỹ thuật	Vận hành cần biết đơn nào lỗi, lỗi gì, ai xử lý
Không dùng ví dụ mô phỏng làm cấu hình thật	`SO-SIM-00017` và Nova Delivery Hub chỉ phục vụ học liệu
Không biến giả định thành quy tắc	Mỗi quyết định phải có nguồn, owner và artifact truy vết phù hợp

Applied

Nova Foods Trading & Manufacturing là case mô phỏng giáo dục, dùng dữ liệu tổng hợp. API (giao diện lập trình ứng dụng) tồn tại để hệ ERP và hệ khác trao đổi dữ liệu theo hợp đồng rõ: ai gửi, gửi gì, khi nào, kết quả nào, lỗi xử lý ra sao. Không có phân tích tích hợp, cùng từ “đồng bộ đơn hàng” có thể bị các bên hiểu khác nhau.

Mục	Trước khi phân tích API	Sau khi phân tích API	Hệ quả quan sát được
Facts	ERP nhận đơn bán qua thao tác nhập tay. Kênh bán hàng gửi mã đơn, mã khách, dòng hàng.	Luồng ghi rõ kênh bán gọi API tạo đơn; ERP trả kết quả nhận hoặc từ chối.	Người vận hành biết đơn nào đã vào ERP, thay vì suy từ email hoặc bảng tính.
Current Behavior	Kênh bán gửi lại đơn khi chưa thấy phản hồi. ERP có thể nhận cùng mã đơn nhiều lần.	Hợp đồng API yêu cầu `externalOrderId` duy nhất; ERP kiểm tra trước khi tạo đơn.	Tránh tạo nhiều đơn ERP cho cùng một đơn nguồn.
Underlying Need	Nghiệp vụ cần một đơn nguồn tương ứng tối đa một đơn ERP.	Nhu cầu được biểu diễn thành quy tắc xử lý trùng và phản hồi HTTP.	Dev, QA, vận hành có cùng đối tượng kiểm tra.
Options	Nhận mọi lần gửi; chặn trùng theo mã đơn nguồn; chặn trùng theo toàn bộ nội dung đơn.	So sánh theo `externalOrderId`.	Thay đổi số lượng hoặc địa chỉ không vô tình tạo đơn mới.
Decision Criteria	Chưa có tiêu chí chung.	Mã định danh phải ổn định từ kênh bán; ERP phải tra cứu được; lỗi phải phản hồi được cho bên gửi.	Lựa chọn kỹ thuật gắn trực tiếp nhu cầu nghiệp vụ.
Decision	Chưa có quyết định được ghi trong artifact kiểm soát.	Quyết định cần được ghi trong API contract và traceability tương ứng; trạng thái hiện tại vẫn `IN_REVIEW`, `v0.9.0`.	Không diễn giải nội dung học liệu là cấu hình ERP hay quyết định production.
Authority	Dev hoặc vận hành có thể tự hiểu cách xử lý.	Business Owner quyết định ý nghĩa đơn; Architect quyết định hợp đồng và tích hợp; QA xác minh hành vi.	BA không tự thay thẩm quyền quyết định.
Artifact	Email, bảng tính, trao đổi miệng.	API contract liên kết `/01-curriculum/TRACEABILITY_ID_REGISTRY.md`, `/01-curriculum/CANONICAL_DATA_DICTIONARY.md`, `/01-curriculum/CANONICAL_BUSINESS_RULES.md`.	Có nguồn để truy vết thay đổi và lập test basis.
Consequence if Wrong	Đơn trùng có thể đi vào xử lý kho, giao hàng hoặc hóa đơn.	Nếu `externalOrderId` không thật sự duy nhất, kiểm tra trùng vẫn sai.	Cần xác minh với owner kênh bán trước khi dùng cho production.

12-api-and-integration-analysis — diagram 4

Source mermaid — có thể chỉnh sửa

sequenceDiagram
    autonumber
    participant Sales as Kênh bán
    participant API as API tích hợp
    participant ERP as Nova Foods ERP

    Note over Sales,ERP: externalOrderId phải duy nhất và ổn định từ kênh bán
    Sales->>API: POST đơn với externalOrderId
    API->>ERP: Kiểm tra externalOrderId

    alt externalOrderId thiếu hoặc không hợp lệ
        ERP-->>API: Phản hồi HTTP từ chối, lý do
        API-->>Sales: Phản hồi HTTP từ chối, lý do
    else externalOrderId chưa tồn tại
        ERP->>ERP: Tạo một đơn ERP
        ERP-->>API: Phản hồi HTTP nhận đơn, erpOrderId
        API-->>Sales: Phản hồi HTTP nhận đơn, erpOrderId
    else externalOrderId đã tồn tại
        ERP-->>API: Phản hồi HTTP đơn đã có, erpOrderId
        API-->>Sales: Phản hồi HTTP không tạo đơn mới, erpOrderId
    end

    Note over Sales,ERP: Nếu externalOrderId không duy nhất hoặc không ổn định, kiểm tra trùng vẫn sai

Core

Trước phân tích, “đồng bộ” là nhãn mơ hồ. Sau phân tích, nó thành chuỗi hành vi kiểm chứng được: gửi định danh nguồn, kiểm tra trùng, tạo hoặc không tạo đơn, trả kết quả. Khác biệt này ngăn rework khi Dev đã xây nhận đơn nhưng QA mới phát hiện cần chống gửi lặp.

Senior Lens

Không dùng số liệu bịa để chứng minh rủi ro. Bằng chứng quan sát đủ là: có lần gửi lại, có thể có mã đơn lặp, và không có artifact nói rõ xử lý trùng. Suy luận: thiếu hợp đồng xử lý trùng tạo khả năng nhiều hệ diễn giải khác nhau; vì vậy cần quyết định có thẩm quyền và kiểm thử tương ứng.

Quick Reference

Trước	Sau
“Đồng bộ đơn hàng”	Hợp đồng API có định danh, phản hồi, xử lý trùng
Hỏi người vận hành khi lỗi	API trả kết quả cho hệ gửi
Dev tự chọn hành vi	Authority quyết định, artifact lưu traceability

Core

Trong phân tích API và tích hợp, năm nhãn sau ngăn BA biến một câu nói, một suy đoán hoặc một lựa chọn chưa có thẩm quyền thành yêu cầu bắt buộc. Mỗi nhãn phải ghi cùng nguồn, ngày ghi nhận 2026-08-07, người cung cấp hoặc vai trò cung cấp, và bằng chứng liên kết.

Nhãn	Nghĩa từ gốc	Bằng chứng tối thiểu	Có thể viết thành yêu cầu chưa?	Xử lý
Verified fact	Sự kiện đã đối chiếu với artifact hoặc nguồn kiểm soát	URL chính thức, log, hợp đồng giao diện, cấu hình được phép xem, hoặc artifact canonical	Có, nhưng vẫn kiểm tra phạm vi áp dụng	Trích đúng nguồn và giới hạn nguồn
Stakeholder input	Ý kiến, nhu cầu hoặc mô tả từ người liên quan	Tên vai trò, thời điểm, biên bản hoặc ticket	Chưa	Phân tích, làm rõ, đối chiếu
Project assumption	Điều tạm coi đúng để lập kế hoạch khi chưa đủ bằng chứng	Lý do thiếu dữ liệu, rủi ro, chủ sở hữu cần xác minh	Không	Gắn nhãn `Project assumption`; đặt điểm kiểm tra
Decision	Lựa chọn giữa phương án theo tiêu chí và thẩm quyền xác định	Phương án, tiêu chí, authority, artifact quyết định	Chỉ khi authority được ghi nhận	Không suy diễn approval từ trạng thái `IN_REVIEW`
Verification-required claim	Phát biểu có thể ảnh hưởng pháp lý, kế toán, bảo mật, vận hành hoặc thiết kế nhưng chưa có xác minh đủ	Nguồn cần kiểm, vai trò xác minh, điều kiện dừng	Không	Giữ nguyên nhãn đến khi có bằng chứng phù hợp

IN_REVIEW tại v0.9.0 chỉ nói artifact đang được xem xét. Nó không là fact rằng Nova Foods đã cấu hình ERP, không là decision vận hành, không là baseline, không là approval.

Applied

Nova Foods Trading & Manufacturing là case mô phỏng giáo dục; mọi dữ liệu dưới đây là dữ liệu tổng hợp.

Mục	Ghi nhận artifact-ready
Facts	`CHAPTER_MANIFEST` và `TRACEABILITY_ID_REGISTRY` có trạng thái `IN_REVIEW`, version `v0.9.0`, ngày `2026-08-07`. Metadata nêu chưa có baseline reference và chưa có approval reference. Đây là verified fact vì có artifact nguồn được chỉ định.
Current Behavior	Nhóm tích hợp nhận câu: “ERP phải tự gửi đơn bán hàng sang hệ thống giao nhận.” Câu này chưa nêu endpoint, sự kiện kích hoạt, dữ liệu gửi, xử lý lỗi, hay authority. Đây là stakeholder input, không phải API requirement.
Underlying Need	Cần phân biệt nhu cầu giảm nhập liệu lặp với cơ chế kỹ thuật. Lý do: cùng nhu cầu có thể dùng API, nhập tệp, hoặc thao tác thủ công có kiểm soát.
Options	(1) REST API đồng bộ khi tạo đơn; (2) gửi tệp theo lô; (3) chưa tích hợp, giữ nhập liệu thủ công.
Decision Criteria	Khả năng hệ thống đích nhận dữ liệu; dữ liệu tối thiểu; xử lý đơn trùng; bảo mật; vận hành khi lỗi; thẩm quyền Architect và Business Owner.
Decision	Chưa có decision. Chọn REST API lúc này sẽ là project assumption vì chưa có bằng chứng giao diện hệ thống đích và chưa ghi nhận authority.
Authority	Architect xác nhận phương án kỹ thuật; Business Owner xác nhận ưu tiên nghiệp vụ; Security xác nhận kiểm soát dữ liệu; Legal/Compliance xác minh nghĩa vụ dữ liệu cá nhân nếu payload có dữ liệu cá nhân.
Artifact	Ghi vào `/02-handbook/12-api-and-integration-analysis.md` với nhãn nguồn; liên kết canonical tới `CHAPTER_MANIFEST`, `TRACEABILITY_ID_REGISTRY`, `CANONICAL_DATA_DICTIONARY` khi artifact sau có nội dung phù hợp.
Consequence if Wrong	Gọi stakeholder input là fact có thể khiến đội viết endpoint sai. Gọi assumption là decision có thể khóa thiết kế trước khi Architect đánh giá. Gọi `IN_REVIEW` là approval tạo rủi ro governance và traceability.

12-api-and-integration-analysis — diagram 5

Source mermaid — có thể chỉnh sửa

flowchart TB
    A[Phát biểu về tích hợp] --> B{Là lựa chọn hoặc phương án?}

    B -- Có --> C{Authority theo phạm vi đã xác nhận?}
    C --- C1[Architect: phương án kỹ thuật]
    C --- C2[Business Owner: ưu tiên nghiệp vụ]
    C --- C3[Security: kiểm soát dữ liệu]
    C --- C4[Legal/Compliance: chỉ khi payload có dữ liệu cá nhân hoặc nghĩa vụ liên quan]
    C -- Có --> D{Có approval reference<br/>và trạng thái APPROVED<br/>hoặc được phê duyệt hợp lệ?}
    D -- Có --> E[Decision]
    D -- Không --> F[Verification-required claim<br/>Chưa có phê duyệt hợp lệ]
    C -- Không --> G[Project assumption<br/>Tạm thời, chưa phê duyệt,<br/>không phải Decision]

    B -- Không --> H{Claim được artifact hoặc nguồn<br/>kiểm soát chỉ định hỗ trợ?}
    H -- Có --> I[Verified fact]
    H -- Không --> J{Là ý kiến hoặc nhu cầu<br/>từ stakeholder?}
    J -- Có --> K[Stakeholder input]
    J -- Không --> L{Có ảnh hưởng pháp lý, kế toán,<br/>bảo mật hoặc vận hành?}
    L -- Có --> M[Verification-required claim<br/>Cần reviewer phù hợp hoặc escalation]
    L -- Không --> N[Verification-required claim<br/>Thiếu evidence cần xác minh]

    K -. Gọi input là fact .-> R1[Nguy cơ: thiết kế endpoint sai]
    G -. Gọi assumption là decision .-> R2[Nguy cơ: khóa thiết kế sớm]
    F -. Gọi IN_REVIEW là approval .-> R3[Nguy cơ: governance và traceability]

Senior Lens

Không nâng nhãn theo độ tự tin của người nói. Nâng nhãn chỉ khi bằng chứng mới đáp ứng đúng câu hỏi. Ví dụ, OpenAPI Specification OAS 3.1.1 là verified fact về đặc tả mô tả HTTP API; nó không chứng minh Nova Foods có REST API, không quyết định trường dữ liệu, và không xác nhận hệ thống đích hỗ trợ OAS 3.1.1.

Câu “dữ liệu khách hàng phải mã hóa vì luật Việt Nam” là verification-required claim. Bằng chứng có thể bắt đầu từ Luật 91/2025/QH15 và Nghị định 356/2025/NĐ-CP, nhưng requirement cụ thể vẫn cần Legal Owner và Security xác minh phạm vi dữ liệu, biện pháp, hệ thống áp dụng. Không biến nguồn pháp lý thành clause tự viết.

Quick Reference

Nếu gặp câu này	Nhãn đúng hiện tại	Viết tiếp thế nào
“Kho giao nhận cần nhận đơn ngay.”	Stakeholder input	Làm rõ “ngay” là sự kiện, thời gian, kênh, dữ liệu và xử lý lỗi nào.
“`CHAPTER_MANIFEST` là `IN_REVIEW`.”	Verified fact	Giữ link nguồn; không suy ra approved.
“Hệ thống giao nhận có API REST.”	Project assumption nếu chưa có tài liệu giao diện	Yêu cầu tài liệu API hoặc xác nhận từ owner hệ thống đích.
“Dùng REST API thay gửi tệp.”	Decision chỉ khi authority và artifact quyết định đã ghi nhận	Nếu thiếu, giữ Options và tiêu chí; không đóng requirement.
“Payload chứa dữ liệu cá nhân phải tuân thủ luật.”	Verification-required claim	Chuyển Legal Owner và Security xác minh trước khi viết kiểm soát bắt buộc.

3. V? tr? trong Lifecycle

Core

Phân tích API và tích hợp đi xuyên suốt Lifecycle: từ phát hiện nhu cầu đến vận hành. API (Application Programming Interface) là giao diện để hệ thống trao đổi dữ liệu hoặc lệnh. Tích hợp là luồng phối hợp có kiểm soát giữa Nova Foods ERP mô phỏng và hệ thống khác. Mỗi giai đoạn chỉ tạo mức chi tiết phù hợp; không được coi một giả định ở Discovery là đặc tả sẵn sàng lập trình.

12-api-and-integration-analysis — diagram 6

Source mermaid — có thể chỉnh sửa

flowchart TB
    D[Discovery] -->|Problem, stakeholder input, boundary recorded| A[Analysis]
    A -->|Interface requirements, rules, data mapping, open risks recorded| DE[Delivery]
    DE -->|Build artifact and test basis available| T[Testing]
    T -->|Test evidence, unresolved defects, residual risk recorded| G{Release decision recorded<br/>by correct authority?}

    G -->|Approved| R[Release]
    G -->|Rejected| X[Release rejected]
    G -->|Pending| P[Release pending]

    X -->|Build finding| DE
    X -->|Verification required| T
    X -->|New requirement issue| A

    P -->|Decision updated| G
    P -->|Build finding| DE
    P -->|Verification required| T
    P -->|New requirement issue| A

    R -->|Release record and operational handover available| O[Operations]
    O -->|Incident or change signal recorded| D
    O -->|Change needs analysis| A

Giai đoạn	Entry gate: được bắt đầu khi	Công việc phân tích API/tích hợp	Exit gate: được chuyển tiếp khi
Discovery	Có vấn đề nghiệp vụ hoặc nhu cầu trao đổi dữ liệu được ghi nhận.	Xác định hệ thống nguồn, hệ thống đích, sự kiện nghiệp vụ, dữ liệu cần trao đổi và giả định.	Problem, phạm vi sơ bộ, stakeholder input và điểm chưa biết được ghi nhận; chưa kết luận giao thức hay kiến trúc.
Analysis	Discovery đã nêu rõ vấn đề và ranh giới sơ bộ.	Làm rõ request, response, dữ liệu, quy tắc, lỗi, bảo mật, tần suất, truy vết; đối chiếu `CANONICAL_BUSINESS_RULES`, `CANONICAL_DATA_DICTIONARY` khi nội dung đã tồn tại.	Requirement, acceptance criteria, mapping dữ liệu, traceability và rủi ro mở được ghi nhận; nội dung chưa xác minh giữ nhãn project assumption hoặc Verification required.
Delivery	Analysis có đầu vào đủ rõ để đội kỹ thuật ước lượng và xây dựng.	BA giải thích ý nghĩa nghiệp vụ của contract giao diện; kiểm soát thay đổi làm lệch rule, dữ liệu hoặc acceptance criteria.	Build artifact có thể kiểm tra tồn tại; mọi sai khác so với phân tích được ghi nhận, không tự sửa ngầm requirement.
Testing	Có build artifact và test basis từ requirement, rule, mapping, acceptance criteria.	Đối chiếu hành vi thực tế với contract; kiểm tra dữ liệu hợp lệ, không hợp lệ, lỗi tích hợp và khả năng truy vết. ISTQB CTFL dùng cho thuật ngữ kiểm thử; không suy ra Nova Foods đã đạt chất lượng production.	Test evidence, defect và residual risk được ghi nhận; defect chưa đóng vẫn là thông tin release, không bị xóa khỏi traceability.
Release	Có bằng chứng testing và quyết định release thuộc đúng thẩm quyền được ghi nhận ở artifact kiểm soát.	Xác nhận gói phát hành tham chiếu đúng phiên bản requirement và contract; kiểm tra kế hoạch rollback hoặc xử lý lỗi nếu phạm vi yêu cầu.	Release record và thông tin bàn giao vận hành có sẵn; `IN_REVIEW` không đồng nghĩa approved hay production-ready.
Operations	Tích hợp đã được đưa vào phạm vi theo dõi vận hành mô phỏng.	Theo dõi lỗi, độ trễ, dữ liệu thất bại, thay đổi hệ thống đích và phản hồi người dùng để tạo tín hiệu thay đổi.	Incident hoặc change signal được ghi nhận đủ để quay lại Discovery hoặc Analysis; không tự biến sự cố thành business rule mới.

Applied

Facts: Nova Foods Trading & Manufacturing là case mô phỏng giáo dục, chỉ dùng dữ liệu tổng hợp. Một nhu cầu mô phỏng yêu cầu ERP gửi trạng thái đơn giao hàng sang hệ thống giao nhận; chưa có tài liệu giao diện của hệ thống đích.

Current Behavior: Discovery chỉ biết sự kiện “đơn sẵn sàng giao”. Không biết hệ thống đích nhận HTTP API, tệp hay hàng đợi thông điệp; vì vậy không có cơ sở kết luận REST API, endpoint, payload hoặc thời gian đồng bộ.

Underlying Need: Giảm nhập lại trạng thái đơn và giữ khả năng truy vết khi trao đổi thất bại.

Options: Giữ giả định có kiểm soát để tiếp tục phân tích; yêu cầu owner hệ thống đích cung cấp contract giao diện; hoặc dừng Delivery cho đến khi contract được xác minh.

Decision Criteria: Chỉ chuyển từ Analysis sang Delivery khi có định dạng trao đổi, trường bắt buộc, quy tắc lỗi, định danh liên kết, tần suất và bằng chứng owner hệ thống đích xác nhận phạm vi kỹ thuật.

Decision: Giữ “hệ thống đích có HTTP API” là project assumption. Không tạo OpenAPI document, endpoint hay mapping trường vì chưa có bằng chứng đầu vào.

Authority: BA được ghi nhận khoảng trống, nhãn bằng chứng và exit gate. BA không có thẩm quyền chọn giao thức, xác nhận bảo mật, hoặc cho phép release.

Artifact: Ghi traceability trong TRACEABILITY_ID_REGISTRY; đối chiếu rule tại CANONICAL_BUSINESS_RULES và dữ liệu tại CANONICAL_DATA_DICTIONARY nếu các artifact đó đã có nội dung phù hợp. Các artifact hiện có trạng thái IN_REVIEW, phiên bản v0.9.0, ngày 2026-08-07.

Consequence if Wrong: Nếu Delivery giả định REST API rồi build trước, contract thật có thể dùng cơ chế khác. Kết quả là build không dùng được, test không có test basis đúng, và release mang rủi ro dữ liệu thất lạc hoặc trạng thái đơn sai.

Senior Lens

Entry gate kiểm tra “đã biết đủ để bắt đầu giai đoạn này chưa”. Exit gate kiểm tra “đã tạo bằng chứng đủ để giai đoạn sau làm việc chưa”. Hai gate không phải phê duyệt ngầm định. Ví dụ, exit gate Analysis có mapping dữ liệu không chứng minh mapping đúng nghiệp vụ; nó chứng minh mapping đã được ghi nhận để Delivery và Testing kiểm tra.

Không đẩy câu hỏi chưa rõ xuống Testing. Thiếu trường bắt buộc, định danh bản ghi, xử lý trùng lặp hoặc lỗi truyền là thiếu Analysis. Testing có thể phát hiện hậu quả, nhưng không có quyền tự viết ý nghĩa nghiệp vụ thay Business Owner hoặc owner hệ thống đích.

Quick Reference

Dấu hiệu	Giai đoạn quay lại	Lý do
Chưa biết hệ thống đích nhận dữ liệu bằng cách nào	Discovery hoặc Analysis	Chưa đủ boundary để chọn contract kỹ thuật.
Mapping có trường nhưng chưa rõ ý nghĩa nghiệp vụ	Analysis	Data mapping chưa là test basis đáng tin cậy.
Build trả lỗi khác contract đã ghi nhận	Delivery và Analysis	Cần ghi sai khác, quyết định thay đổi hoặc sửa build.
Test phát hiện dữ liệu trùng nhưng rule chưa nói cách xử lý	Analysis	Thiếu rule về idempotency, tức xử lý lặp mà không tạo kết quả sai.
Sau release xuất hiện lỗi đồng bộ mới	Operations rồi Discovery/Analysis	Sự cố là tín hiệu thay đổi, không tự là requirement hoàn chỉnh.

Core

Trong Nova Foods Trading & Manufacturing mô phỏng, tích hợp ERP không do BA tự quyết. BA giữ luồng thông tin, bằng chứng và truy vết; từng owner quyết nội dung thuộc thẩm quyền mình. Lý do: một thay đổi API có thể đồng thời ảnh hưởng quy tắc bán hàng, dữ liệu khách hàng, bảo mật và vận hành. Corpus đang IN_REVIEW, phiên bản v0.9.0, ngày 2026-08-07; không có baseline hay phê duyệt ngầm định.

Handoff	Upstream owner gửi	Downstream owner nhận	Vật chuyển giao	Giới hạn thẩm quyền
Nghiệp vụ sang BA	Business Owner	BA	Mục tiêu, sự kiện nghiệp vụ, ngoại lệ, ưu tiên	Business Owner không tự chốt giao thức API hay kiểm soát bảo mật
BA sang Architect	BA	Solution Architect	Luồng tích hợp, trường dữ liệu logic, quy tắc cần áp dụng, câu hỏi mở	BA không chọn kiến trúc, endpoint, cơ chế xác thực
Architect sang Delivery	Solution Architect	Delivery Lead, Developer	Quyết định kỹ thuật được ghi nhận, hợp đồng tích hợp, ràng buộc phi chức năng	Developer không đổi quy tắc nghiệp vụ vì tiện mã hóa
BA và Architect sang QA	BA, Solution Architect	QA Lead	Traceability, acceptance criteria, API contract, dữ liệu kiểm thử tổng hợp	QA không tự diễn giải thiếu sót thành requirement mới
Delivery sang Operations	Delivery Lead	Operations Owner	Cấu hình triển khai, runbook, quan sát lỗi, rollback plan	Operations Owner không tự sửa contract nghiệp vụ trong production
Security hoặc pháp lý chuyên môn	Security Owner, Legal/Compliance Owner	BA, Architect, Business Owner	Kết luận phạm vi chuyên môn và điều kiện kiểm soát	Không vai trò nào suy diễn kết luận pháp lý từ source map

Applied

Facts: Nova Foods mô phỏng cần đồng bộ trạng thái đơn bán SO-NF-24001 từ ERP sang hệ thống giao nhận. Payload chứa customerName, deliveryAddress, orderStatus; toàn bộ dữ liệu là tổng hợp. customerName và deliveryAddress vẫn là loại dữ liệu cần Security Owner và Legal/Compliance Owner xem xét khi thiết kế sử dụng thực tế.

Current Behavior: Business Owner yêu cầu “gửi đơn khi đã xác nhận”, nhưng chưa nêu trạng thái canonical, người sở hữu lỗi gửi lại, hay trường nào bắt buộc. Evidence bridge: câu mô tả chỉ xác định thời điểm nghiệp vụ gần đúng; không đủ để Developer tạo HTTP contract không mơ hồ.

Underlying Need: Cần xác định owner của trạng thái nguồn, owner của mapping dữ liệu, owner của xác thực API, và owner xử lý khi giao nhận trả lỗi. Nếu không tách ownership, cùng một lỗi có thể bị Business, IT và Operations chuyển vòng.

Mục	Nội dung
Options	1. BA tự chốt mapping và retry. 2. Business Owner chốt nghiệp vụ, Architect chốt contract, Security Owner chốt kiểm soát, Operations Owner chốt xử lý lỗi.
Decision Criteria	Đúng thẩm quyền; truy vết được về nguồn; không biến giả định thành quyết định production; có owner cho lỗi sau release.
Decision	Chọn Option 2. BA lập và duy trì liên kết giữa nhu cầu, câu hỏi, quyết định và artifact; không thay vai trò chuyên môn.
Authority	Business Owner quyết ý nghĩa `orderStatus`; Solution Architect quyết endpoint, schema và cơ chế tích hợp; Security Owner quyết kiểm soát truy cập; QA Lead quyết bằng chứng kiểm thử; Operations Owner quyết quy trình xử lý sự cố.
Artifact	`/02-handbook/12-api-and-integration-analysis.md`; tham chiếu quản trị `TRACEABILITY_ID_REGISTRY`, `CANONICAL_BUSINESS_RULES`, `CANONICAL_DATA_DICTIONARY`. Các artifact này đều `IN_REVIEW` tại `v0.9.0`, không phải baseline.
Consequence if Wrong	BA tự gán `CONFIRMED` là trạng thái gửi có thể làm đơn chưa đủ điều kiện bị giao; Architect tự đổi quy tắc có thể lệch ý nghĩa nghiệp vụ; Operations tự sửa payload có thể phá contract và mất khả năng truy vết.

Senior Lens

Escalation xảy ra ngay khi câu hỏi vượt một trong các ranh giới sau:

Điểm escalation	Owner nhận escalation	BA phải cung cấp	Không được làm
Trạng thái ERP có nhiều nghĩa hoặc xung đột rule	Business Owner	Ví dụ trạng thái, tác động từng cách hiểu, nguồn artifact	Tự chọn trạng thái “hợp lý”
Endpoint, version API, idempotency, retry, timeout	Solution Architect	Luồng lỗi, volume giả định, dependency	Tự thiết kế kiến trúc thành quyết định cuối
Token, quyền truy cập, dữ liệu cá nhân, log chứa dữ liệu nhạy cảm	Security Owner; Legal/Compliance Owner khi cần	Loại dữ liệu, nơi truyền, bên nhận, rủi ro	Gọi thiết kế là tuân thủ pháp luật
Giá trị hóa đơn, hạch toán, thuế, chứng từ	Accounting Owner; Legal Owner khi cần	Trường dữ liệu, thời điểm ghi nhận, source classification	Diễn giải luật kế toán hoặc thuế
Test fail vì acceptance criteria thiếu	Business Owner và BA; QA Lead điều phối test evidence	Requirement, test case, actual result, expected result	Sửa expected result để test pass
Lỗi sau release gây mất hoặc nhân bản đơn	Operations Owner, Delivery Lead, Solution Architect	Mã lỗi, thời điểm `Asia/Ho_Chi_Minh`, correlation ID nếu có, tác động	Tự chạy lại dữ liệu không có quyết định xử lý

12-api-and-integration-analysis — diagram 7

Source mermaid — có thể chỉnh sửa

flowchart TB
    BA[BA] -->|Escalation package và traceability| ROUTE{Điểm escalation}

    ROUTE -->|Trạng thái ERP có nhiều nghĩa hoặc xung đột rule| ERP[Ví dụ trạng thái<br/>Tác động từng cách hiểu<br/>Nguồn artifact]
    ERP --> BO[Business Owner]

    ROUTE -->|Endpoint, version API, idempotency, retry hoặc timeout| API[Luồng lỗi<br/>Volume giả định<br/>Dependency]
    API --> SA[Solution Architect]

    ROUTE -->|Token, quyền truy cập, dữ liệu cá nhân hoặc log nhạy cảm| DATA[Loại dữ liệu<br/>Nơi truyền<br/>Bên nhận<br/>Rủi ro]
    DATA --> SEC[Security Owner]
    DATA -->|Khi cần| LEG[Legal/Compliance Owner]

    ROUTE -->|Giá trị hóa đơn, hạch toán, thuế hoặc chứng từ| FIN[Trường dữ liệu<br/>Thời điểm ghi nhận<br/>Source classification]
    FIN --> ACC[Accounting Owner]
    FIN -->|Khi cần| LEG

    ROUTE -->|Test fail vì acceptance criteria thiếu| TEST[Requirement<br/>Test case<br/>Actual result<br/>Expected result]
    TEST -->|Xử lý requirement| BO
    TEST -->|Xử lý requirement| BA
    TEST -->|Điều phối test evidence| QA[QA Lead]

    ROUTE -->|Lỗi sau release gây mất hoặc nhân bản đơn| INCIDENT[Mã lỗi<br/>Thời điểm Asia/Ho_Chi_Minh<br/>Correlation ID nếu có<br/>Tác động]
    INCIDENT --> OPS[Operations Owner]
    INCIDENT --> DL[Delivery Lead]
    INCIDENT --> SA

    BA -.-> BOUNDARY["Sơ đồ chỉ mô tả routing escalation<br/>BA không tự chọn trạng thái ERP<br/>Không tự quyết định kiến trúc API<br/>Không kết luận tuân thủ<br/>Không diễn giải luật kế toán hoặc thuế<br/>Không sửa expected result để test pass<br/>Không tự chạy lại dữ liệu"]

Quick Reference

BA sở hữu tính đầy đủ của handoff, không sở hữu quyết định chuyên môn ngoài thẩm quyền.
Handoff tối thiểu phải nêu: người gửi, người nhận, artifact, quyết định cần có, điều kiện chuyển tiếp, điểm escalation.
“Đã gửi cho Architect” không phải quyết định kiến trúc; “QA đã test” không phải chấp thuận nghiệp vụ.
Dùng Verification required cho chi tiết pháp lý, kế toán, thuế, dữ liệu cá nhân, an toàn thực phẩm chưa được owner có thẩm quyền xác minh.
Không đổi canonical ID, filename, source classification hoặc rule để giải quyết nhanh xung đột integration.

Core

Bản đồ vòng đời giúp thấy luồng giao tiếp API từ lúc phát hiện nhu cầu đến vận hành. API (Application Programming Interface) là giao diện để hai hệ thống trao đổi dữ liệu theo quy tắc đã công bố. Sơ đồ này là ví dụ học liệu cho Nova Foods Trading & Manufacturing, mô phỏng, chỉ dùng dữ liệu tổng hợp; không xác nhận cấu hình ERP thực tế.

12-api-and-integration-analysis — diagram 8

Source mermaid — có thể chỉnh sửa

flowchart TB
    D[Discovery<br/>Phát hiện nhu cầu dữ liệu]
    A[Analysis<br/>Phân tích luồng, dữ liệu, quy tắc]
    DV[Delivery<br/>Xây hoặc cấu hình tích hợp]
    T[Testing<br/>Kiểm thử hợp đồng và luồng]
    R[Release<br/>Phát hành có kiểm soát]
    O[Operations<br/>Giám sát, xử lý lỗi, cải tiến]

    D --> A --> DV --> T --> R --> O
    O -->|Phản hồi: sự cố hoặc thay đổi| D

    D -.-> H1[/Bàn giao: nhu cầu trao đổi dữ liệu/] -.-> A
    A -.-> H2[/Bàn giao: API contract, mapping,<br/>quy tắc và mã lỗi/] -.-> DV
    DV -.-> H3[/Bàn giao: bản triển khai kiểm thử/] -.-> T
    T -.-> H4[/Bàn giao: bằng chứng kiểm thử/] -.-> R
    R -.-> H5[/Bàn giao: phiên bản đã phát hành/] -.-> O

Sơ đồ dùng mũi tên liền cho thứ tự công việc và mũi tên nét đứt cho vật bàn giao giữa các pha. Lý do: đội nhận việc không thể kiểm thử chỉ từ mô tả nhu cầu; họ cần API contract, tức hợp đồng API mô tả endpoint, dữ liệu vào-ra, mã lỗi và quy tắc trao đổi. OpenAPI Specification OAS 3.1.1 là nguồn chuẩn cho mô tả HTTP API, nhưng sơ đồ không khẳng định Nova Foods đã dùng OAS.

Applied

Mục	Nội dung mô phỏng
Facts	ERP Nova Foods cần nhận trạng thái giao hàng từ hệ thống logistics mô phỏng.
Current Behavior	Nhân viên nhập trạng thái thủ công sau khi nhận thông báo.
Underlying Need	Đồng bộ trạng thái có kiểm soát để giảm chậm trễ và sai khác nhập liệu.
Options	Giữ nhập thủ công; gửi tệp định kỳ; tích hợp HTTP API theo sự kiện.
Decision Criteria	Độ kịp thời, khả năng truy vết lỗi, chất lượng dữ liệu, năng lực hệ thống nhận và rủi ro vận hành.
Decision	Chưa chọn phương án. Sơ đồ xác định trình tự đánh giá, không thay Business Owner hoặc Architect quyết định.
Authority	Business Owner xác nhận giá trị nghiệp vụ; Architect xác nhận kiến trúc; Security xác nhận kiểm soát; QA xác nhận bằng chứng kiểm thử; Release Owner quyết định phát hành.
Artifact	API contract, data mapping, error catalogue, test evidence và release record phải thuộc artifact kiểm soát phù hợp; không tự tạo ID mới trong sơ đồ.
Consequence if Wrong	Bỏ qua Analysis có thể làm Delivery dùng sai mã trạng thái. Bỏ qua Testing có thể phát hành luồng không xử lý được lỗi trùng bản tin hoặc dữ liệu thiếu.

Senior Lens

Không đọc sơ đồ như quy trình phê duyệt. Nó chỉ biểu diễn phụ thuộc công việc. Bằng chứng là metadata corpus đang IN_REVIEW, phiên bản v0.9.0, ngày 2026-08-07; trạng thái này không phải baseline, approval hay quyền production. Nếu tích hợp chứa dữ liệu cá nhân, dữ liệu kế toán, hóa đơn hoặc truy xuất thực phẩm, phải chuyển vấn đề cho Legal Owner, Accounting Owner, Security hoặc domain owner. Lý do: nguồn seed chỉ cho phép dùng luật và chuẩn trong ranh giới xác minh; handbook không thay thẩm quyền chuyên môn.

Quick Reference

Ký hiệu	Nghĩa dùng trong sơ đồ
Discovery	Nhận diện vấn đề và nhu cầu trao đổi dữ liệu.
Analysis	Làm rõ API contract, mapping dữ liệu, quy tắc và lỗi.
Delivery	Xây, cấu hình hoặc chuẩn bị thành phần tích hợp.
Testing	Đối chiếu hành vi thực tế với test basis và API contract.
Release	Đưa phiên bản đã qua kiểm soát vào môi trường được phép.
Operations	Giám sát, đối soát, xử lý sự cố và đưa thay đổi quay lại Discovery.

4. Input c?n thi?t

Core

Phân tích API và tích hợp cần đầu vào trước khi viết yêu cầu. API (Application Programming Interface) là giao diện để hai hệ thống trao đổi dữ liệu theo quy tắc xác định. Tích hợp là việc kết nối các hệ thống để dữ liệu hoặc sự kiện đi qua đúng nơi, đúng nghĩa. Người mới không cần biết lập trình, nhưng phải phân biệt: dữ liệu nào cần trao đổi, nguồn nào nói điều đó, và ID nào giữ liên kết không đổi.

Bằng chứng không phải ý kiến ghi nhớ. Bằng chứng là artifact có nguồn, định danh, đường dẫn và ranh giới sử dụng rõ. Ví dụ, CANONICAL_DATA_DICTIONARY mô tả nghĩa dữ liệu logic; không tự biến nó thành schema cơ sở dữ liệu hay JSON API. CANONICAL_BUSINESS_RULES là nơi tham chiếu quy tắc; không chép lại rồi sửa nghĩa trong tài liệu tích hợp.

12-api-and-integration-analysis — diagram 9

Source mermaid — có thể chỉnh sửa

flowchart TB
    N[Nhu cầu trao đổi dữ liệu] --> E

    subgraph E[Nguồn bằng chứng]
        A[Artifact nguồn]
        P[Nguồn · định danh artifact · đường dẫn · ranh giới sử dụng]
        A --- P
        D[CANONICAL_DATA_DICTIONARY<br/>Nghĩa dữ liệu logic]
        R[CANONICAL_BUSINESS_RULES<br/>Nguồn tham chiếu quy tắc]
        A --> D
        A --> R
    end

    D --> M[Phân tích nghĩa dữ liệu]
    R --> M
    P --> M

    M --> I{Cần giữ liên kết<br/>giữa dữ liệu?}
    I -- Có --> K[Xác định ID liên kết dữ liệu<br/>giữ không đổi]
    I -- Không --> O[API contract hoặc data mapping]
    K --> O

    D -. Không phải .-> X[Schema DB hoặc JSON API]
    R -. Không sao chép, không sửa nghĩa .-> O

Applied

Mục	Nội dung mô phỏng Nova Foods
Facts	Nova Foods Trading & Manufacturing là case study mô phỏng giáo dục. Dữ liệu chỉ là dữ liệu tổng hợp. Corpus có trạng thái `IN_REVIEW`, phiên bản `v0.9.0`, ngày `2026-08-07`.
Current Behavior	Chưa có API contract, data mapping hay xác nhận cấu hình ERP production trong đầu vào được cung cấp.
Underlying Need	BA cần biết nguồn nào định nghĩa dữ liệu, quy tắc và ID trước khi mô tả trao đổi giữa ERP và hệ thống khác.
Options	Dùng ghi chú không kiểm soát; hoặc dùng artifact canonical đã đăng ký trong corpus.
Decision Criteria	Liên kết phải truy ngược được tới artifact kiểm soát; ID và filename phải giữ nguyên; không suy diễn chi tiết nghiệp vụ ngoài nguồn.
Decision	Dùng artifact canonical làm đầu vào phân tích. Giữ nguyên ID, filename, trạng thái và ranh giới nguồn.
Authority	Principal IT Business Analyst / Technical Curriculum Author duy trì quản trị artifact. Business Owner, Architect, Security, Legal Owner, Accounting Owner và domain owner giữ thẩm quyền chuyên môn tương ứng.
Artifact	`/01-curriculum/TRACEABILITY_ID_REGISTRY.md`, `/01-curriculum/CANONICAL_BUSINESS_RULES.md`, `/01-curriculum/CANONICAL_DATA_DICTIONARY.md`, `/00-research/00_SOURCE_MAP.md`.
Consequence if Wrong	Sai nguồn hoặc đổi ID làm data mapping mất truy vết, API contract có thể dùng sai nghĩa trường dữ liệu, và đội Delivery hoặc QA không xác định được nguồn cần đối chiếu.

Senior Lens

Danh mục đầu vào tối thiểu không phải danh sách tài liệu để “đọc cho đủ”. Mỗi artifact trả lời một câu hỏi riêng: nguồn nghiên cứu trả lời “dựa vào chuẩn hoặc luật nào”; registry trả lời “ID nào là canonical”; rule catalog trả lời “quy tắc nằm ở đâu”; data dictionary trả lời “trường dữ liệu có nghĩa gì”. Suy luận này dựa trên tên, phạm vi và metadata của từng artifact, không dựa trên giả định rằng chúng đã được phê duyệt.

Không dùng IN_REVIEW làm bằng chứng rằng nội dung đã đúng cho vận hành Nova Foods. Bằng chứng: metadata upstream nêu rõ IN_REVIEW không phải APPROVED, BASELINED, production-ready hay user-approved. Vì vậy, BA chỉ được ghi nhận đầu vào và liên kết truy vết; không được tự xác nhận yêu cầu, quy tắc, tuân thủ hay cấu hình production.

Quick Reference

Loại đầu vào	Canonical ID	Filename kiểm soát	Dùng để làm gì	Không được suy diễn
Bản đồ nguồn	`00_SOURCE_MAP`	`/00-research/00_SOURCE_MAP.md`	Xác định nguồn chuẩn, luật, tổ chức phát hành và safe use boundary.	Điều khoản chi tiết của tài liệu có bản quyền hoặc nghĩa vụ pháp lý chưa xác minh.
Kiến trúc curriculum	`01_CURRICULUM_ARCHITECTURE`	`/01-curriculum/01_CURRICULUM_ARCHITECTURE.md`	Xác định phạm vi học liệu và liên kết giữa các phần corpus.	Quyết định ERP hoặc quy trình vận hành thực.
Manifest chương	`CHAPTER_MANIFEST`	`/01-curriculum/CHAPTER_MANIFEST.md`	Giữ title, thứ tự section và dependency chương.	Baseline hoặc approval nội dung.
Registry truy vết	`TRACEABILITY_ID_REGISTRY`	`/01-curriculum/TRACEABILITY_ID_REGISTRY.md`	Tra cứu và giữ nguyên persistent canonical ID, tức ID không đổi qua liên kết artifact.	Tạo ID mới ngoài registry.
Catalog quy tắc	`CANONICAL_BUSINESS_RULES`	`/01-curriculum/CANONICAL_BUSINESS_RULES.md`	Tham chiếu vị trí quy tắc nghiệp vụ khi phân tích dữ liệu và hành vi API.	Tự diễn giải thành quy tắc pháp lý, kế toán hoặc vận hành thực.
Từ điển dữ liệu	`CANONICAL_DATA_DICTIONARY`	`/01-curriculum/CANONICAL_DATA_DICTIONARY.md`	Tham chiếu nghĩa logic của thực thể, thuộc tính và dữ liệu trao đổi.	Schema kỹ thuật, kiểu dữ liệu JSON hoặc cấu hình DB chưa được cung cấp.

Core

Input là thông tin BA nhận trước khi phân tích API và tích hợp. Chất lượng input quyết định chất lượng kết luận: nguồn sai, cũ, thiếu owner hoặc không truy được ID thì không đủ để viết yêu cầu, mapping dữ liệu hay quyết định tích hợp.

Phân loại nguồn trước khi dùng:

Phân loại	Dùng khi	Ví dụ Nova Foods mô phỏng	Giới hạn
Nguồn primary	Tổ chức phát hành chịu trách nhiệm nội dung	OAS 3.1.1 từ OpenAPI Initiative; Luật 91/2025/QH15 từ cổng Chính phủ	Không suy diễn điều khoản chưa kiểm tra
Nguồn controlled nội bộ corpus	Kiểm soát ID, phạm vi, trạng thái artifact	`CHAPTER_MANIFEST`, `TRACEABILITY_ID_REGISTRY`, `CANONICAL_DATA_DICTIONARY`	`IN_REVIEW` không phải baseline hay approval
Bằng chứng hệ thống mô phỏng	Mô tả hành vi hiện tại	JSON request/response tổng hợp, ảnh chụp log đã che dữ liệu	Không chứng minh ERP production
Giả định dự án	Lấp khoảng trống tạm thời để phân tích lựa chọn	“Đồng bộ đơn hàng mỗi 15 phút”	Không được đổi thành business rule
Verification required	Điểm chưa đủ bằng chứng hoặc cần thẩm quyền khác xác nhận	Nghĩa vụ lưu hóa đơn, dữ liệu cá nhân, truy xuất thực phẩm	Dừng quyết định bắt buộc đến khi owner phù hợp xác minh

Kiểm tra từng input theo năm câu: đúng nguồn nào, ai sở hữu, cập nhật khi nào, ID nào nối được, kết luận nào được phép rút ra. Không có đủ năm câu, input chỉ là tham khảo.

12-api-and-integration-analysis — diagram 10

Source mermaid — có thể chỉnh sửa

flowchart TB
    A[Nhận input] --> B{Nguồn truy được?}
    B -- Không --> R[Chỉ tham khảo:<br/>không viết yêu cầu, mapping<br/>hay quyết định tích hợp]
    B -- Có --> C{Có owner chịu trách nhiệm?}
    C -- Không --> R
    C -- Có --> D{Cập nhật khi nào?}
    D -- Không rõ hoặc đã cũ --> V[Verification required]
    D -- Còn dùng được --> E{ID và phạm vi khớp?}
    E -- Không --> R
    E -- Có --> K{Kết luận nào<br/>được phép rút ra?}
    K -- Không rõ --> V
    K -- Đủ bằng chứng --> F[Đủ điều kiện phân tích]

    V --> G{Owner xác minh?}
    G -- Có --> E
    G -- Không --> H{Ghi giả định dự án?}
    H -- Không --> R
    H -- Có --> I[Chỉ phân tích lựa chọn tạm thời:<br/>không thành business rule<br/>hoặc quyết định bắt buộc]

Applied

Facts: Nova Foods Trading & Manufacturing là case mô phỏng giáo dục, chỉ dùng dữ liệu tổng hợp, locale vi-VN, múi giờ Asia/Ho_Chi_Minh, tiền tệ mô phỏng VND. Corpus ở IN_REVIEW, v0.9.0, ngày 2026-08-07.

Current Behavior: BA nhận một tài liệu mô tả endpoint và một yêu cầu “gửi đơn hàng sang kho”. Tài liệu không có OpenAPI file, không nêu owner kỹ thuật, không có thời điểm cập nhật, không nối tới ID dữ liệu canonical.

Underlying Need: Xác định input có đủ độ tin cậy để phân tích giao diện tích hợp giữa ERP mô phỏng và hệ thống kho mô phỏng hay phải dừng.

Input	Phân loại	Freshness	Owner	ID/traceability	Kiểm tra chất lượng	Trạng thái
`/01-curriculum/TRACEABILITY_ID_REGISTRY.md`	Controlled nội bộ corpus	`2026-08-07`	Principal IT Business Analyst / Technical Curriculum Author	`TRACEABILITY_ID_REGISTRY`	Đường dẫn, status, version, ID khớp metadata	Dùng được cho kiểm soát ID
`/01-curriculum/CANONICAL_DATA_DICTIONARY.md`	Controlled nội bộ corpus	`2026-08-07`	Principal IT Business Analyst / Technical Curriculum Author	`CANONICAL_DATA_DICTIONARY`	Chỉ dùng phạm vi logical data dictionary; không suy ra schema production	Dùng có điều kiện
OAS 3.1.1	Primary	`2024-10-24`	OpenAPI Initiative	URL chính thức	Xác nhận đặc tả mô tả HTTP API; không xác nhận endpoint Nova Foods	Dùng cho thuật ngữ
Payload `NF-SIM-ORDER-001` tổng hợp	Bằng chứng hệ thống mô phỏng	`2026-08-07`	Chưa xác định	Không có canonical ID registry reference	Có dữ liệu tổng hợp nhưng thiếu nguồn tạo và mapping	Verification required
Yêu cầu “gửi đơn hàng sang kho”	Giả định dự án	`2026-08-07`	Chưa xác định Business Owner	Không có requirement ID	Không có phạm vi, tần suất, lỗi, quyền truy cập	Verification required
Luật 91/2025/QH15	Primary pháp lý	`2026-08-07` truy cập URL	Quốc hội Việt Nam	URL chính thức	Có hiệu lực từ `2026-01-01`; diễn giải hệ thống cần Legal Owner xác minh	Verification required

Options:
1. Viết mapping API từ payload NF-SIM-ORDER-001.
2. Ghi giả định có nhãn và chỉ phân tích cấu trúc minh họa.
3. Dừng phân tích tích hợp đến khi có owner, ID và bằng chứng cập nhật.

Decision Criteria: Chọn phương án chỉ khi input có nguồn truy được, owner chịu trách nhiệm, freshness phù hợp, ID canonical hoặc liên kết registry, phạm vi không mâu thuẫn.

Decision: Chọn phương án 3 cho yêu cầu tích hợp. Chỉ dùng OAS 3.1.1 và artifact controlled để dạy phương pháp. Không tạo endpoint, mapping, SLA hay business rule Nova Foods.

Authority: Business Owner xác nhận nhu cầu và ưu tiên; Architect xác nhận kiến trúc, giao thức, lỗi và bảo mật; Data Owner xác nhận mapping; Legal Owner xác nhận nghĩa vụ dữ liệu cá nhân; Principal IT Business Analyst / Technical Curriculum Author duy trì traceability, không thay các thẩm quyền này.

Artifact: Ghi input register trong /02-handbook/12-api-and-integration-analysis.md, tham chiếu nguyên dạng TRACEABILITY_ID_REGISTRY và CANONICAL_DATA_DICTIONARY.

Consequence if Wrong: Mapping từ input chưa xác minh có thể gửi sai đơn hàng, nhân bản giao dịch, lộ dữ liệu hoặc biến giả định học liệu thành quyết định vận hành.

Senior Lens

Freshness không có một ngưỡng chung. Chọn ngưỡng theo rủi ro thay đổi. Đặc tả API cần version và ngày phát hành; log cần timestamp; quy tắc pháp lý cần kiểm tra nguồn chính thức hiện hành; dữ liệu master cần owner xác nhận thời điểm trích xuất. “Mới” nhưng không biết nguồn vẫn không đạt.

Dừng ngay khi có một điều kiện: nguồn không truy được; ID mâu thuẫn registry; owner không xác định; tài liệu IN_REVIEW bị gọi là approved hoặc baselined; yêu cầu pháp lý, kế toán, an toàn thực phẩm, bảo mật bị suy diễn không có owner chuyên môn; payload chứa dữ liệu thật; hoặc hai nguồn canonical cho kết luận trái nhau. Dừng không phải thất bại. Dừng ngăn BA hợp thức hóa thông tin chưa đủ chứng cứ.

Quick Reference

Quy tắc	Hành động BA
Có URL chính thức nhưng không có điều khoản đã kiểm tra	Dùng để định vị nguồn; không diễn giải chi tiết
Có file nhưng thiếu owner	Gắn `Verification required`; không dùng làm quyết định
Có owner nhưng không có ID hoặc version	Yêu cầu liên kết `TRACEABILITY_ID_REGISTRY` hoặc artifact canonical
Có dữ liệu thật hoặc không rõ nguồn dữ liệu	Không chép vào corpus; dừng và escalation
Input là giả định	Gắn nhãn giả định, nêu lý do, không gọi là fact hay rule
Artifact là `IN_REVIEW`	Dùng cho phân tích có kiểm soát; không gọi approved, baselined hay production-ready

Core

Bảng đầu vào là danh mục bằng chứng BA cần đọc trước khi mô tả API hoặc tích hợp. Mỗi dòng phải giữ ID canonical, tệp nguồn, trạng thái và giới hạn sử dụng. Nova Foods Trading & Manufacturing là case mô phỏng giáo dục; mọi giá trị dưới đây là dữ liệu tổng hợp, không phản ánh ERP thật.

Input ID	Nhóm nguồn	Artifact/tệp canonical	Giá trị mô phỏng cần dùng	Owner ghi nhận	Freshness tại 2026-08-07	Trạng thái xác minh
`SRC-API-001`	Nguồn nội bộ mô phỏng	`/01-curriculum/TRACEABILITY_ID_REGISTRY.md`	`TRACEABILITY_ID_REGISTRY`; Status `IN_REVIEW`; Version `v0.9.0`	Principal IT Business Analyst / Technical Curriculum Author	Cùng ngày	Đã ghi nhận metadata; không phải baseline
`SRC-API-002`	Nguồn nội bộ mô phỏng	`/01-curriculum/CANONICAL_DATA_DICTIONARY.md`	Logical entity giả định: `SalesOrder`, `Customer`, `InventoryBalance`, `DispatchNote`	Principal IT Business Analyst / Technical Curriculum Author	Cùng ngày	Verification required: trường, kiểu dữ liệu, khóa nghiệp vụ chưa được xác nhận
`SRC-API-003`	Nguồn nội bộ mô phỏng	`/01-curriculum/CANONICAL_BUSINESS_RULES.md`	Catalog quy tắc canonical, Status `IN_REVIEW`, Version `v0.9.0`	Principal IT Business Analyst / Technical Curriculum Author	Cùng ngày	Verification required: không suy diễn rule vận hành từ catalog kế hoạch
`SRC-API-004`	Nguồn chuẩn kỹ thuật	OpenAPI Specification 3.1.1	Mô tả HTTP API, operation, request, response, security scheme	OpenAPI Initiative	Published 2024-10-24	Đã xác minh URL; chưa có OpenAPI Nova Foods
`SRC-API-005`	Nguồn good practice bảo mật	OWASP API Security Top 10 2023	Dùng nhận diện rủi ro API; không phải luật Việt Nam	OWASP Foundation	2023 edition	Đã xác minh URL; Verification required: kiểm soát cụ thể do Security Owner xác nhận
`SRC-API-006`	Nguồn pháp lý	Luật 91/2025/QH15	Bối cảnh bảo vệ dữ liệu cá nhân tại Việt Nam	Quốc hội Việt Nam	Effective 2026-01-01	Verification required: Legal Owner xác minh yêu cầu hệ thống
`SRC-API-007`	Bằng chứng vận hành mô phỏng	`NF-INT-ORDER-001`	Đơn bán `SO-SIM-20260807-001`; khách `CUS-SIM-001`; tổng tiền `12500000 VND`	Sales Operations Owner giả định	2026-08-07 09:00 `Asia/Ho_Chi_Minh`	Chỉ minh họa dữ liệu trao đổi
`SRC-API-008`	Bằng chứng kỹ thuật mô phỏng	`NF-INT-API-001`	`POST /api/v1/sales-orders`; JSON; HTTPS; response dự kiến `202 Accepted`	Solution Architect giả định	2026-08-07 09:15 `Asia/Ho_Chi_Minh`	Verification required: endpoint, xác thực, mã phản hồi chưa được phê chuẩn
`SRC-API-009`	Bằng chứng lỗi mô phỏng	`NF-INT-ERR-001`	Cùng `externalOrderId` gửi hai lần trong 30 giây	Integration Owner giả định	2026-08-07 09:20 `Asia/Ho_Chi_Minh`	Verification required: quy tắc chống trùng và xử lý retry
`SRC-API-010`	Quyết định còn mở	`NF-INT-DEC-001`	Chưa rõ hệ đích là ERP core hay middleware trước ERP	Business Owner và Architect	2026-08-07	Chưa giải quyết; không được viết contract triển khai

Applied

Facts: Nova Foods mô phỏng cần chuyển đơn bán từ cổng đặt hàng sang ERP. Bằng chứng SRC-API-007 có externalOrderId giả định SO-SIM-20260807-001; SRC-API-008 chỉ là phác thảo kỹ thuật chưa xác minh.

Current Behavior: Chưa có bằng chứng canonical chứng minh hệ thống nhận đơn, trường bắt buộc, cơ chế xác thực, xử lý đơn trùng, hay hệ đích cuối.

Underlying Need: Cần đủ đầu vào để BA mô tả trao đổi dữ liệu mà không biến giả định thành yêu cầu ERP.

Options: Dùng phác thảo NF-INT-API-001 làm contract; hoặc dừng phân tích contract đến khi Owner có thẩm quyền xác minh.

Decision Criteria: Contract chỉ được viết khi xác định được hệ nguồn, hệ đích, ID chống trùng, chủ sở hữu dữ liệu, bảo mật và lỗi nhận đơn.

Decision: Dừng tại mức inventory đầu vào. Giữ NF-INT-API-001 và NF-INT-DEC-001 là Verification required.

Authority: Business Owner xác nhận mục tiêu nghiệp vụ; Solution Architect xác nhận topology và contract; Security Owner xác nhận xác thực, phân quyền và bảo vệ dữ liệu; Legal Owner xác nhận nghĩa vụ dữ liệu cá nhân nếu áp dụng.

Artifact: Bảng input này trong /02-handbook/12-api-and-integration-analysis.md, liên kết SRC-API-001 đến SRC-API-010.

Consequence if Wrong: Chọn sai hệ đích gây contract sai; thiếu ID chống trùng có thể tạo hai đơn; coi nguồn pháp lý là rule kỹ thuật đã chốt có thể vượt thẩm quyền.

12-api-and-integration-analysis — diagram 11

Source mermaid — có thể chỉnh sửa

flowchart TB
    A7["SRC-API-007<br/>externalOrderId giả định:<br/>SO-SIM-20260807-001"] --> B["Inventory đầu vào<br/>NF-INT-API-001<br/>Verification required"]
    A8["SRC-API-008<br/>phác thảo kỹ thuật<br/>chưa xác minh"] --> B
    AN["SRC-API-001 đến SRC-API-006,<br/>SRC-API-009 đến SRC-API-010<br/>nguồn tham chiếu"] --> B

    B --> G["Mục tiêu nghiệp vụ<br/>cần xác nhận"]
    B --> S["Hệ nguồn<br/>cần xác minh"]
    B --> T["Hệ đích<br/>cần xác minh"]
    B --> X["ID chống trùng<br/>cần xác minh"]
    B --> O["Chủ sở hữu dữ liệu<br/>cần xác minh"]
    B --> SEC["Xác thực, phân quyền,<br/>bảo vệ dữ liệu<br/>cần xác minh"]
    B --> E["Lỗi nhận đơn<br/>cần xác minh"]
    B --> P{"Có dữ liệu cá nhân?"}

    P -->|Có| LEG["Nghĩa vụ dữ liệu cá nhân<br/>cần Legal Owner xác nhận"]
    P -->|Không| D{"Đủ đầu vào để<br/>mô tả contract?"}
    LEG --> D

    G --> D
    S --> D
    T --> D
    X --> D
    O --> D
    SEC --> D
    E --> D

    D -->|Chưa đủ| I["Dừng ở inventory<br/>NF-INT-API-001 và NF-INT-DEC-001<br/>Verification required"]
    D -->|Đủ sau xác minh| J["Đủ điều kiện<br/>mô tả contract"]
    D -->|Bỏ qua tiêu chí,<br/>vẫn viết contract| R["Rủi ro: contract sai,<br/>tạo đơn trùng hoặc vượt thẩm quyền"]

    BO["Business Owner"] -. "xác nhận mục tiêu nghiệp vụ" .-> G
    SA["Solution Architect"] -. "xác nhận topology" .-> S
    SA -. "xác nhận topology" .-> T
    SA -. "xác nhận ID chống trùng" .-> X
    SA -. "xác nhận lỗi contract" .-> E
    SA -. "xác nhận contract" .-> J
    DO["Owner có thẩm quyền về dữ liệu"] -. "xác nhận chủ sở hữu dữ liệu" .-> O
    SO["Security Owner"] -. "xác nhận kiểm soát bảo mật" .-> SEC
    LO["Legal Owner"] -. "xác nhận nếu có dữ liệu cá nhân" .-> LEG

Senior Lens

Không dùng tên endpoint, mã HTTP, entity hoặc trường dữ liệu như bằng chứng đủ. POST /api/v1/sales-orders chỉ mô tả giả định kỹ thuật; nó không chứng minh ERP có endpoint đó. Cầu nối suy luận là: nguồn có trạng thái Verification required thiếu xác nhận từ Owner đúng thẩm quyền, nên BA chỉ được ghi nhận khoảng trống, không được nâng thành requirement hay quyết định.

externalOrderId là ví dụ về persistent canonical ID: một giá trị ổn định dùng nhận diện cùng đơn xuyên hệ thống. Giá trị SO-SIM-20260807-001 chỉ là synthetic test value. Chưa có bằng chứng xác nhận quy tắc tạo ID, phạm vi duy nhất, thời hạn lưu, hay hành vi khi gửi lại.

Quick Reference

Điều kiện	Nhãn dùng	Hành động BA
Nguồn có ID, tệp, Owner, ngày và nội dung khớp nhau	Đã ghi nhận	Dùng làm đầu vào có truy vết
Nguồn chuẩn mô tả khái niệm nhưng không mô tả Nova Foods	Nguồn tham chiếu	Không suy diễn cấu hình Nova Foods
Nguồn cần Legal, Security, Accounting, Business Owner hoặc Architect xác nhận	Verification required	Giữ câu hỏi mở và Owner tương ứng
Hệ đích, ID chống trùng, quyền truy cập hoặc dữ liệu cá nhân chưa rõ	STOP	Không viết API contract hay acceptance criteria

5. Step-by-step BA Activities

Core

API (Application Programming Interface) là giao diện để hai hệ thống trao đổi dữ liệu theo quy ước xác định. BA không tự quyết kiến trúc hay bảo mật. BA biến nhu cầu nghiệp vụ thành gói phân tích có nguồn, giả định, câu hỏi, quyết định cần thẩm quyền và tiêu chí kiểm tra.

Applied

Nova Foods Trading & Manufacturing là case mô phỏng giáo dục; mọi dữ liệu dưới đây là synthetic. Tình huống dùng để thực hành: cần phân tích khả năng gửi đơn bán từ cổng đặt hàng mô phỏng sang ERP mô phỏng. Không có xác nhận hệ đích, endpoint, quyền truy cập hay quy tắc chống gửi trùng.

Thành phần	Nội dung
Facts	`SRC-API-007` ghi nhận cổng đặt hàng mô phỏng; `NF-INT-API-001` là điểm tích hợp chưa xác minh; `NF-INT-DEC-001` là quyết định hệ đích chưa xác minh.
Current Behavior	Cổng đặt hàng mô phỏng có thể tạo đơn. Chưa có bằng chứng đơn đi vào ERP core mô phỏng hay middleware mô phỏng.
Underlying Need	Cần biết đơn nào được gửi, dữ liệu nào được truyền, hệ nào chịu trách nhiệm nhận và cách xử lý gửi lại.
Options	Gửi trực tiếp ERP core mô phỏng; gửi qua middleware mô phỏng; dừng thiết kế contract đến khi Architect xác minh hệ đích.
Decision Criteria	Bằng chứng hệ đích; phân loại dữ liệu; quyền truy cập; xử lý lỗi; khả năng chống trùng; Owner có thẩm quyền.
Decision	`STOP` tại thiết kế API contract. Chỉ lập gói câu hỏi và traceability.
Authority	Business Owner xác nhận nhu cầu; Architect xác nhận hệ đích; Security Owner xác nhận kiểm soát dữ liệu và truy cập.
Artifact	Bản ghi phân tích trong `/02-handbook/12-api-and-integration-analysis.md`, tham chiếu `SRC-API-007`, `NF-INT-API-001`, `NF-INT-DEC-001`.
Consequence if Wrong	Chọn sai hệ đích có thể tạo đơn trùng, mất đơn, lộ dữ liệu hoặc tạo tích hợp không thể kiểm thử.

BA chuẩn bị phạm vi. Actor: BA. Action: đọc /01-curriculum/TRACEABILITY_ID_REGISTRY.md, /01-curriculum/CANONICAL_DATA_DICTIONARY.md và nguồn SRC-API-007; tách факт đã ghi nhận khỏi giả định. Object: nhu cầu tích hợp đơn bán mô phỏng. Evidence produced: danh sách nguồn, phạm vi và giả định có nhãn Verification required. Decision rule: không có nguồn canonical hoặc Owner xác nhận thì không mô tả nó là hành vi ERP. Quality gate: mỗi phát biểu có nguồn hoặc nhãn giả định. Escalation route: Principal IT Business Analyst / Technical Curriculum Author khi ID hoặc nguồn mâu thuẫn.
BA xác định trigger và kết quả nghiệp vụ. Actor: BA cùng Business Owner. Action: hỏi điều kiện bắt đầu, dữ liệu tối thiểu và kết quả mong muốn của việc gửi đơn. Object: luồng “đơn bán được tạo tại cổng đặt hàng mô phỏng”. Evidence produced: bảng trigger, outcome và câu hỏi mở. Decision rule: outcome phải mô tả giá trị nghiệp vụ, không chỉ mô tả POST hay endpoint. Quality gate: trigger, actor khởi tạo và kết quả có thể quan sát đều rõ. Escalation route: Business Owner khi mục tiêu nghiệp vụ hoặc ngoại lệ chưa rõ.
BA lập biên dữ liệu. Actor: BA cùng Data Owner và Security Owner. Action: liệt kê trường ứng viên như mã đơn ngoài, khách hàng, dòng hàng, số lượng và tổng tiền VND; phân loại từng trường là cần thiết, chưa cần hoặc chưa xác minh. Object: payload logic, không phải payload triển khai. Evidence produced: mapping dữ liệu có nguồn và trạng thái xác minh. Decision rule: chỉ giữ dữ liệu phục vụ outcome; dữ liệu cá nhân hoặc nhạy cảm cần Security Owner xem xét. Quality gate: không có trường nào thiếu mục đích, nguồn hoặc Owner. Escalation route: Security Owner với dữ liệu cá nhân; Data Owner khi định nghĩa trường mâu thuẫn.
BA phân tích luồng thành công và lỗi. Actor: BA cùng Architect và QA. Action: mô tả gửi thành công, từ chối dữ liệu, lỗi kết nối, gửi lại và nguy cơ gửi trùng ở mức logic. Object: trạng thái trao đổi đơn. Evidence produced: bảng trạng thái và điều kiện chuyển trạng thái. Decision rule: không suy diễn retry, timeout, mã HTTP hay cơ chế idempotency khi chưa có xác nhận kỹ thuật. Quality gate: mọi lỗi có chủ thể phát hiện, thông tin ghi nhận và điểm xử lý. Escalation route: Architect với cơ chế kỹ thuật; QA với khả năng kiểm thử.
BA so sánh phương án tích hợp. Actor: BA. Action: đối chiếu gửi trực tiếp ERP core mô phỏng, qua middleware mô phỏng và dừng chờ xác minh. Object: NF-INT-DEC-001. Evidence produced: decision log gồm phương án, bằng chứng, rủi ro và tiêu chí. Decision rule: phương án thiếu bằng chứng hệ đích không được chọn làm quyết định triển khai. Quality gate: tiêu chí áp dụng nhất quán cho mọi phương án. Escalation route: Architect xác nhận kiến trúc; Security Owner xác nhận rủi ro đường truyền và quyền.
BA viết yêu cầu có thể review. Actor: BA. Action: chuyển facts, need, dữ liệu, luồng và giới hạn thành requirement draft; giữ rõ nhãn “project assumption” hoặc “Verification required”. Object: gói yêu cầu tích hợp mô phỏng. Evidence produced: requirement draft liên kết SRC-API-007, NF-INT-API-001, NF-INT-DEC-001. Decision rule: requirement phải nêu chủ thể, hành vi, điều kiện và kết quả; không chứa quyết định thuộc thẩm quyền Owner khác. Quality gate: reviewer lần ngược được mỗi requirement về nguồn hoặc giả định. Escalation route: Business Owner, Architect, Security Owner theo loại quyết định.
BA điều phối review. Actor: BA, Business Owner, Architect, Security Owner, QA. Action: trình gói phân tích, ghi nhận nhận xét theo từng ID và phân biệt xác nhận, từ chối, câu hỏi mở. Object: requirement draft và decision log. Evidence produced: review record có người góp ý, thời điểm Asia/Ho_Chi_Minh, nội dung và hành động tiếp theo. Decision rule: IN_REVIEW không phải approval; ý kiến không đúng thẩm quyền không thay thế xác nhận chuyên môn. Quality gate: không còn mâu thuẫn nguồn chưa được gắn nhãn hoặc chuyển escalation. Escalation route: Owner đúng thẩm quyền của điểm còn tranh chấp.
BA handoff có kiểm soát. Actor: BA. Action: bàn giao gói chỉ khi traceability, giả định, câu hỏi mở, rủi ro và Owner xử lý còn lại được ghi rõ. Object: gói phân tích cho Architect và QA. Evidence produced: handoff checklist, liên kết artifact và trạng thái IN_REVIEW. Decision rule: thiếu xác nhận hệ đích, bảo mật hoặc quy tắc nghiệp vụ thì handoff chỉ phục vụ phân tích tiếp, không cho thiết kế production. Quality gate: người nhận xác định được đầu vào, giới hạn và việc không được suy diễn. Escalation route: trả gói về BA khi thiếu traceability; chuyển Owner phù hợp khi cần quyết định.

Senior Lens

Cầu nối suy luận phải thấy được: nguồn nói gì, nguồn chưa nói gì, ai có quyền xác nhận phần thiếu. Ví dụ, SRC-API-007 chỉ hỗ trợ kết luận có cổng đặt hàng mô phỏng; không hỗ trợ kết luận ERP có endpoint nhận đơn. Vì thiếu bằng chứng hệ đích, quyết định đúng là STOP, không phải chọn phương án “có vẻ hợp lý”.

Quick Reference

Kiểm tra trước handoff	Đạt khi
Nguồn	Mỗi fact có ID nguồn hoặc artifact canonical
Giả định	Mỗi giả định có nhãn `Verification required` hoặc `project assumption`
Thẩm quyền	Business, Architect, Security, QA nhận đúng câu hỏi
Trạng thái	Giữ `IN_REVIEW`, không gọi là baseline hay approval
Rủi ro	Gửi trùng, mất dữ liệu, lộ dữ liệu và sai hệ đích có route escalation

Core

Mỗi bước phân tích API và tích hợp phải tạo bằng chứng kiểm tra được. BA không kết luận từ trao đổi miệng đơn lẻ; BA ghi nguồn, đối tượng, quy tắc quyết định, cổng chất lượng và tuyến escalation. Nova Foods là case mô phỏng giáo dục; mọi dữ liệu dưới đây là dữ liệu tổng hợp, trạng thái corpus IN_REVIEW, phiên bản v0.9.0, ngày 2026-08-07, locale vi-VN, múi giờ Asia/Ho_Chi_Minh, tiền tệ VND.

Bước	Actor	Action	Object	Evidence produced	Decision rule	Quality gate	Escalation route
1. Chuẩn bị phạm vi	BA	Lập ranh giới luồng tích hợp cần phân tích	Tên luồng, hệ thống gửi/nhận, mục tiêu nghiệp vụ, owner	Phiếu phạm vi tích hợp có ngày, nguồn và giả định	Chỉ đưa vào phạm vi khi có mục tiêu nghiệp vụ và hệ thống đầu-cuối xác định được	Không mâu thuẫn với artifact canonical, không gọi giả định là fact	Mâu thuẫn phạm vi chuyển Business Owner; mâu thuẫn hệ thống chuyển Architect
2. Thu thập fact	BA	Ghi nhận hành vi hiện tại từ tài liệu, log mô phỏng, demo hoặc owner	Trigger, payload, endpoint, trạng thái, lỗi	Bảng fact kèm phân loại nguồn: verified source, project assumption, Verification required	Fact chỉ là fact khi truy được nguồn; thiếu nguồn phải gắn `Verification required`	Mỗi fact có nguồn, ngày truy cập hoặc người cung cấp, không có suy diễn lẫn trong fact	Nguồn mâu thuẫn chuyển Principal IT Business Analyst / Technical Curriculum Author để lập gói vấn đề; nội dung kỹ thuật chuyển Architect
3. Phân tích dữ liệu và hợp đồng	BA	Đối chiếu trường dữ liệu, định danh, kiểu dữ liệu, bắt buộc, trạng thái và lỗi	Request, response, mapping logic, mã lỗi HTTP	Ma trận mapping và danh sách khoảng trống hợp đồng API	Không chấp nhận mapping nếu định danh nguồn-đích, chủ sở hữu dữ liệu hoặc xử lý giá trị rỗng chưa rõ	Không trùng semantic; trường bắt buộc có xử lý khi thiếu; dữ liệu cá nhân được phân loại	Rủi ro dữ liệu cá nhân chuyển Legal/Privacy Owner và Security; conflict canonical ID chuyển `TRACEABILITY_ID_REGISTRY`
4. Xác định quy tắc và ngoại lệ	BA	Tách quy tắc nghiệp vụ khỏi cơ chế kỹ thuật	Điều kiện gửi, chống trùng, retry, timeout, lỗi nghiệp vụ và lỗi kỹ thuật	Danh sách rule, exception và câu hỏi mở có traceability	Rule chưa có nguồn canonical là project assumption hoặc `Verification required`, không là yêu cầu bắt buộc	Mỗi ngoại lệ có chủ sở hữu xử lý, trạng thái kết thúc và bằng chứng dự kiến	Quy tắc nghiệp vụ chuyển Business Owner; kế toán chuyển Accounting Owner; pháp lý chuyển Legal Owner; retry/idempotency chuyển Architect
5. Đánh giá phương án	BA	So sánh phương án giao tiếp và kiểm soát lỗi theo need đã xác minh	Đồng bộ/asynchronous, API/file, xác thực, retry, monitoring	Bảng options, tiêu chí, hệ quả và decision record dự thảo	Chọn phương án chỉ khi đáp ứng need, rủi ro, vận hành và thẩm quyền; BA không tự quyết kiến trúc	Tiêu chí có trọng số hoặc lý do rõ; không dùng “best practice” thay bằng chứng	Quyết định kiến trúc chuyển Architect; rủi ro bảo mật chuyển Security; chi phí hoặc ưu tiên chuyển Business Owner
6. Review và handoff có kiểm soát	BA	Chạy walkthrough, ghi issue, cập nhật traceability và bàn giao gói review	Sơ đồ, mapping, rule, giả định, open issue, test basis	Biên bản walkthrough và handoff package gắn trạng thái `IN_REVIEW`	Chỉ handoff khi mỗi item có owner, source classification và trạng thái; không gọi là approved hoặc baselined	Liên kết nguồn hoạt động; ID giữ nguyên; open issue không bị che; artifact ghi đúng version `v0.9.0`	Defect hợp đồng API chuyển delivery lead/Architect; thiếu test basis chuyển QA; issue chưa quyết định giữ `IN_REVIEW` và chuyển owner có thẩm quyền

Applied

Nova Foods Trading & Manufacturing là case mô phỏng giáo dục, dùng dữ liệu tổng hợp. Bảng sau minh họa BA phân tích tích hợp API giữa ERP và cổng bán hàng mô phỏng khi đơn hàng cần đi vào ERP. “API” là giao diện để hai hệ thống trao đổi dữ liệu qua HTTP; API không tự xác nhận đúng nghiệp vụ.

Thành phần	Nội dung thực thi
Facts	Cổng bán hàng mô phỏng gửi `orderNumber`, `customerCode`, `orderDate`, `totalAmount` và danh sách dòng hàng. ERP cần tạo đơn bán trước khi kho xử lý. Dữ liệu tiền tệ mô phỏng dùng `VND`; thời gian theo `Asia/Ho_Chi_Minh`.
Current Behavior	Nhân viên xuất tệp bảng tính, nhập lại đơn vào ERP. Một đơn có thể bị nhập hai lần khi gửi lại tệp. Không có bằng chứng máy đọc được về phản hồi tạo đơn.
Underlying Need	ERP phải nhận đơn duy nhất, kiểm tra dữ liệu tối thiểu, trả kết quả xử lý, giữ được liên kết giữa `orderNumber` nguồn và mã đơn ERP.
Options	1. Nhập tay từ tệp. 2. Cổng bán hàng gọi API ERP đồng bộ. 3. Cổng bán hàng gửi hàng đợi bất đồng bộ.
Decision Criteria	Đơn trùng phải bị chặn; lỗi phải truy vết được; phản hồi phải đủ cho cổng bán hàng; phương án không tự suy diễn kiến trúc production; chi phí vận hành mô phỏng phải phù hợp phạm vi học liệu.
Decision	Chọn API đồng bộ cho ví dụ phân tích. `orderNumber` là khóa chống trùng ở mức yêu cầu logic. Đây là quyết định học liệu, không phải quyết định kiến trúc production.
Authority	Architect xác nhận kiểu tích hợp, bảo mật và khả năng vận hành. Business Owner xác nhận quy tắc nhận đơn. Security xác nhận kiểm soát truy cập. Principal IT Business Analyst / Technical Curriculum Author giữ traceability, không tự phê duyệt.
Artifact	Bản nháp hợp đồng API, ma trận ánh xạ dữ liệu, danh sách lỗi, traceability tới `CANONICAL_DATA_DICTIONARY`, `CANONICAL_BUSINESS_RULES` và `TRACEABILITY_ID_REGISTRY`; tất cả giữ trạng thái `IN_REVIEW`, phiên bản `v0.9.0`, ngày `2026-08-07`.
Consequence if Wrong	Không chặn trùng có thể tạo hai đơn bán. Ánh xạ sai `totalAmount` có thể làm sai tổng tiền. Không ghi phản hồi có thể khiến cổng bán hàng báo thành công khi ERP từ chối đơn.

Lượt thực thi	Actor	Action trên object	Evidence tạo ra	Decision rule	Quality gate	Escalation route
1	BA	Đối chiếu trường nguồn với thực thể đơn bán trong `CANONICAL_DATA_DICTIONARY`	Ma trận ánh xạ: `orderNumber`, `customerCode`, `orderDate`, `totalAmount`, dòng hàng	Mỗi trường bắt buộc phải có nguồn, kiểu dữ liệu, quy tắc rỗng và nơi nhận	Không còn trường ERP không có nguồn hoặc trường nguồn không có xử lý	Data Owner khi nghĩa trường mâu thuẫn
2	BA	Mô tả yêu cầu gửi đơn `POST /sales-orders` cho API mô phỏng	Bản nháp request, response, mã lỗi	`orderNumber` đã tồn tại phải không tạo đơn mới	Có ví dụ thành công, trùng, thiếu trường và lỗi định dạng	Business Owner khi quy tắc đơn trùng chưa rõ
3	Architect	Rà soát luồng đồng bộ và điểm tin cậy giữa hai hệ thống	Ghi nhận ranh giới cổng bán hàng, API ERP, kho dữ liệu ERP	Không mô tả cơ chế xác thực như đã quyết định khi chưa có xác nhận Architect và Security	Luồng có điểm nhận, kiểm tra, phản hồi, nhật ký lỗi	Security hoặc Architect khi có dữ liệu cá nhân, token, quyền truy cập
4	QA reviewer	Kiểm tra khả năng kiểm thử từ hợp đồng API	Tập tình huống kiểm thử hộp đen	Request hợp lệ tạo một đơn; request trùng trả kết quả xác định; request lỗi không tạo đơn	Mỗi nhánh Mermaid có kết quả quan sát được	BA khi thiếu tiêu chí chấp nhận; Architect khi lỗi thuộc giao thức
5	BA	Đóng gói bản nháp để review có kiểm soát	Liên kết artifact, giả định, câu hỏi mở và người nhận review	Không đổi trạng thái thành `APPROVED` hay `BASELINED`	Tên artifact, trạng thái, phiên bản, ngày giữ đúng nguồn canonical	Principal IT Business Analyst / Technical Curriculum Author khi traceability đứt hoặc nguồn canonical mâu thuẫn

12-api-and-integration-analysis — diagram 12

Source mermaid — có thể chỉnh sửa

flowchart TB
    A[Cổng bán hàng mô phỏng gửi POST /sales-orders] --> B[API ERP kiểm tra trường bắt buộc]
    B -->|Thiếu hoặc sai định dạng| C[Trả lỗi 400; không tạo đơn; ghi bằng chứng lỗi]
    B -->|Hợp lệ| D[Kiểm tra orderNumber]
    D -->|Đã tồn tại| E[Trả phản hồi trùng xác định; không tạo đơn mới]
    D -->|Chưa tồn tại| F[Tạo đơn bán ERP mô phỏng]
    F -->|Không thể tạo đơn| G[Trả kết quả lỗi xử lý xác định; ghi bằng chứng lỗi]
    F -->|Tạo đơn thành công| H[Ghi liên kết orderNumber nguồn với mã đơn ERP]
    H -->|Ghi liên kết thành công| I[Trả mã đơn ERP và trạng thái nhận]
    H -->|Ghi liên kết thất bại| J[Chuyển xử lý ngoại lệ; không xác nhận đơn đã nhận; ghi bằng chứng lỗi]

Bằng chứng chọn API đồng bộ: cổng bán hàng cần biết ngay đơn được nhận, bị từ chối dữ liệu, hay bị chặn trùng. Suy luận này chỉ đủ cho ví dụ học liệu; tải cao, xử lý lại, độ sẵn sàng, xác thực và lưu nhật ký production cần Architect, Security và vận hành xác minh.

6. Output thu ???c

Core

Output là artifact, tức vật phẩm có kiểm soát dùng để chuyển kết quả phân tích sang người review tiếp theo. Với API và integration, BA không giao “ý tưởng kết nối”; BA giao cấu trúc đủ để người khác biết hệ thống nào trao đổi dữ liệu gì, khi nào, lỗi ra sao và giả định nào còn mở. Nova Foods Trading & Manufacturing là case mô phỏng giáo dục; mọi dữ liệu dưới đây là tổng hợp.

Artifact ID canonical	Tệp kiểm soát	Artifact tạo hoặc cập nhật	Owner	Status	Nội dung tối thiểu
`API-INT-CTX-001`	`/02-handbook/12-api-and-integration-analysis.md`	Integration Context Map, sơ đồ ngữ cảnh tích hợp	Principal IT Business Analyst / Technical Curriculum Author	`IN_REVIEW`	Hệ thống nguồn, hệ thống đích, mục tiêu trao đổi, hướng dữ liệu, trigger, dữ liệu chính, giả định và điểm cần xác minh
`API-INT-CON-001`	`/02-handbook/12-api-and-integration-analysis.md`	API Contract Draft, bản nháp hợp đồng API	Principal IT Business Analyst / Technical Curriculum Author	`IN_REVIEW`	HTTP method, URL path, request, response, mã lỗi, quy tắc trùng, correlation ID, giới hạn không thuộc thẩm quyền BA
`API-INT-MAP-001`	`/02-handbook/12-api-and-integration-analysis.md`	Data Mapping Draft, bản nháp ánh xạ dữ liệu	Principal IT Business Analyst / Technical Curriculum Author	`IN_REVIEW`	Trường nguồn, trường đích, kiểu dữ liệu, bắt buộc, quy tắc biến đổi, xử lý null, owner xác minh
`API-INT-ERR-001`	`/02-handbook/12-api-and-integration-analysis.md`	Error and Exception Catalogue, danh mục lỗi và ngoại lệ	Principal IT Business Analyst / Technical Curriculum Author	`IN_REVIEW`	Điều kiện lỗi, phản hồi quan sát được, tác động tạo dữ liệu, xử lý lại, bên cần nhận lỗi
`API-INT-TRC-001`	`/02-handbook/12-api-and-integration-analysis.md`	Integration Traceability Record, bản ghi truy vết tích hợp	Principal IT Business Analyst / Technical Curriculum Author	`IN_REVIEW`	Liên kết nhu cầu, luồng, hợp đồng, ánh xạ, lỗi, giả định, câu hỏi mở và artifact nguồn

IN_REVIEW nghĩa là đang xem xét có kiểm soát. Nó không nghĩa APPROVED, BASELINED, production-ready, compliant, hay đã được người dùng chấp thuận. Owner giữ ID, version, trạng thái, lịch sử thay đổi và liên kết; Owner không thay Architect quyết định kiến trúc, không thay Security xác nhận xác thực, không thay Business Owner xác nhận quy tắc nghiệp vụ.

Mỗi artifact phải có change history. Một dòng lịch sử tối thiểu gồm: version, ngày 2026-08-07, múi giờ Asia/Ho_Chi_Minh, người ghi nhận, thay đổi, lý do, artifact bị ảnh hưởng. Không sửa im lặng. Khi thay đổi contract làm đổi mapping hoặc lỗi, cập nhật cả API-INT-CON-001, API-INT-MAP-001, API-INT-ERR-001, rồi ghi liên kết trong API-INT-TRC-001.

12-api-and-integration-analysis — diagram 13

Source mermaid — có thể chỉnh sửa

flowchart TB
    subgraph INITIAL["Controlled artifacts and traceability"]
        A["Business need"]
        O["Owner: Principal IT Business Analyst / Technical Curriculum Author<br/>Maintains IDs, versions, statuses, change history, and links"]
        P["Authority boundary<br/>Architect decides architecture<br/>Security confirms authentication<br/>Business Owner confirms business rules"]

        B["API-INT-CTX-001<br/>Integration Context Map<br/>IN_REVIEW"]
        C["API-INT-CON-001<br/>API Contract Draft<br/>IN_REVIEW"]
        D["API-INT-MAP-001<br/>Data Mapping Draft<br/>IN_REVIEW"]
        E["API-INT-ERR-001<br/>Error and Exception Catalogue<br/>IN_REVIEW"]
        F["API-INT-TRC-001<br/>Integration Traceability Record<br/>IN_REVIEW"]

        A -->|artifact dependency| B
        B -->|artifact dependency| C
        C -->|artifact dependency| D
        C -->|artifact dependency| E

        A -->|traceability link| F
        B -->|traceability link| F
        C -->|traceability link| F
        D -->|traceability link| F
        E -->|traceability link| F

        O -.->|maintains| B
        O -.->|maintains| C
        O -.->|maintains| D
        O -.->|maintains| E
        O -.->|maintains| F
        O -.->|does not replace| P
    end

    subgraph CHANGE["Contract change control"]
        G["Contract change"]
        H{"Affects mapping<br/>or error handling?"}

        I["Update API-INT-CON-001,<br/>API-INT-MAP-001, and<br/>API-INT-ERR-001"]
        J["Record links to changed contract,<br/>mapping, and error artifacts<br/>in API-INT-TRC-001"]

        K["Update API-INT-CON-001"]
        L["Record link to changed contract<br/>in API-INT-TRC-001"]

        M["Record mandatory change history<br/>version; 2026-08-07; Asia/Ho_Chi_Minh;<br/>recorder; change; reason; affected artifacts"]
        N["Updated artifacts remain IN_REVIEW<br/>Not APPROVED, BASELINED, production-ready,<br/>compliant, or user-accepted"]

        G --> H
        H -->|Yes: mapping or error handling affected| I
        I --> J
        J --> M
        H -->|No| K
        K --> L
        L --> M
        M --> N
    end

    C -->|when contract change occurs| G
    O -.->|controls records| M
    F -.->|updated by| J
    F -.->|updated by| L

Applied

Facts: Cổng bán hàng mô phỏng gửi đơn bán vào ERP Nova Foods qua POST /sales-orders. Dữ liệu tổng hợp gồm orderNumber, customerCode, orderDate, currencyCode, totalAmount.

Current Behavior: Nếu cổng gửi lại cùng orderNumber, ERP mô phỏng có nguy cơ tạo hai đơn nếu không có kiểm tra trùng. Bằng chứng là orderNumber là mã đơn từ nguồn; một lần gửi lại phải còn nhận diện cùng giao dịch nguồn.

Underlying Need: ERP cần nhận đơn, trả kết quả quan sát được và tránh tạo đơn trùng. Nhu cầu này tạo ra contract, mapping và lỗi; không tự suy ra cơ chế token, mã hóa, hàng đợi hay cấu hình production.

Options: Gọi API đồng bộ; hoặc gửi sự kiện bất đồng bộ qua hàng đợi. API đồng bộ cho kết quả nhận ngay. Hàng đợi phù hợp khi cần tách thời điểm gửi và xử lý, nhưng cần quyết định Architect.

Decision Criteria: Cổng cần biết ngay đơn được nhận, dữ liệu sai, hay đơn trùng; ví dụ không có bằng chứng về tải lớn hoặc xử lý nền.

Decision: Dùng API đồng bộ cho case học liệu. Quyết định chỉ áp dụng mô phỏng, trạng thái IN_REVIEW.

Authority: Architect xác minh mẫu tích hợp, độ sẵn sàng và xử lý lại. Security xác minh xác thực, phân quyền, nhật ký. Business Owner xác minh quy tắc đơn trùng.

Artifact:

ID	Giá trị điền cho Nova Foods mô phỏng
`API-INT-CTX-001`	Nguồn: Sales Portal mô phỏng. Đích: Nova ERP mô phỏng. Trigger: khách gửi đơn. Hướng dữ liệu: Sales Portal sang Nova ERP.
`API-INT-CON-001`	`POST /sales-orders`; request chứa `orderNumber`, `customerCode`, `orderDate`, `currencyCode`, `totalAmount`; thành công trả mã đơn ERP; dữ liệu sai trả `400`; mã đơn đã tồn tại không tạo đơn mới.
`API-INT-MAP-001`	`orderNumber` sang mã tham chiếu đơn nguồn; `customerCode` sang mã khách hàng; `orderDate` sang ngày đơn; `currencyCode` nhận `VND`; `totalAmount` sang tổng tiền đơn.
`API-INT-ERR-001`	Thiếu `customerCode`: trả `400`, không tạo đơn. `orderNumber` đã tồn tại: trả kết quả nhận diện trùng, không tạo đơn mới.
`API-INT-TRC-001`	Nhu cầu tránh đơn trùng liên kết `API-INT-CON-001` và `API-INT-ERR-001`; giả định `VND` là tiền tệ mô phỏng corpus.

Consequence if Wrong: Nếu mapping sai totalAmount, ERP mô phỏng nhận sai tổng tiền. Nếu quy tắc trùng sai, một đơn nguồn có thể thành nhiều đơn ERP. Đây là rủi ro dữ liệu; không phải kết luận về hệ thống Nova Foods thực tế.

Senior Lens

ID artifact không phải nhãn trang trí. ID giữ cùng một đối tượng qua review, đổi version và truy vết. Tên “API spec” không đủ vì có thể chỉ hợp đồng kỹ thuật, mapping, hay tài liệu kiến trúc. Tách artifact theo câu hỏi: contract trả lời giao thức; mapping trả lời dữ liệu; error catalogue trả lời hành vi lỗi; traceability trả lời vì sao tồn tại.

Không gắn điều khoản pháp lý, thuế, kế toán, bảo vệ dữ liệu cá nhân hoặc an toàn thực phẩm vào API output khi chưa có nguồn và owner thẩm quyền xác minh. Nếu request chứa dữ liệu cá nhân, ghi “Verification required” và chuyển Security, Legal/Compliance Owner xem xét. Không diễn giải OWASP, luật Việt Nam hay chuẩn kỹ thuật thành cấu hình bắt buộc cho Nova Foods mô phỏng.

Quick Reference

Quy tắc	Áp dụng
Một artifact, một mục đích chính	Không gộp API contract và data mapping thành bảng không truy vết được
Giữ nguyên ID sau sửa nhỏ	Tăng version và thêm change-history; không đổi ID để che lịch sử
Tạo ID mới khi ý nghĩa artifact đổi	Ví dụ đổi từ luồng tạo đơn sang luồng hủy đơn
Ghi owner thẩm quyền đúng	BA giữ quản trị artifact; Architect, Security, Business Owner giữ quyết định chuyên môn tương ứng
Giữ `IN_REVIEW`	Không gọi output là đã phê duyệt, baseline hay sẵn sàng production

Bản giải phẫu đầu ra tích hợp hoàn chỉnh

Core

Đầu ra tích hợp không phải một sơ đồ đơn lẻ. Nó là bộ artifact cùng mô tả một cam kết trao đổi dữ liệu: hệ thống nào gọi, gọi khi nào, gửi trường nào, nhận kết quả nào, xử lý lỗi nào. Mỗi artifact phải liên kết cùng Interface ID; nếu ID khác nhau, BA không chứng minh được yêu cầu, dữ liệu, API và kiểm thử nói về cùng một luồng.

Thành phần đầu ra	Nội dung bắt buộc	Liên kết canonical
Interface Summary	Mục tiêu, hệ thống nguồn/đích, hướng truyền, trigger, dữ liệu nghiệp vụ	`INT-NF-001`
API Contract	HTTP method, URL, request, response, mã lỗi, xác thực	`INT-NF-001`, OpenAPI 3.1.1
Data Mapping	Trường nguồn, trường đích, kiểu dữ liệu, biến đổi, bắt buộc, xử lý null	`INT-NF-001`, `CANONICAL_DATA_DICTIONARY`
Business Rule Mapping	Rule áp dụng trước khi gửi hoặc sau khi nhận	`CANONICAL_BUSINESS_RULES`
Error Handling Matrix	Điều kiện lỗi, HTTP status, hành động caller, hành động receiver, log	`INT-NF-001`
Traceability Record	Requirement, rule, field, API operation, acceptance criterion, test basis	`TRACEABILITY_ID_REGISTRY`

12-api-and-integration-analysis — diagram 14

Source mermaid — có thể chỉnh sửa

sequenceDiagram
    autonumber
    participant ERP as Nova Foods ERP
    participant API as Partner API

    Note over ERP,API: Interface ID: INT-NF-001

    ERP->>API: POST /v1/purchase-orders
    alt Thành công
        API-->>ERP: 201 Created + partnerOrderId
    else Validation error
        API-->>ERP: 400 Validation error
    else Duplicate request
        API-->>ERP: 409 Duplicate purchaseOrderNo
    else Unauthorized
        API-->>ERP: 401 Unauthorized
    end

Applied

Facts: Nova Foods Trading & Manufacturing là case mô phỏng giáo dục, dữ liệu tổng hợp. ERP cần gửi đơn mua nguyên liệu tổng hợp sang Partner API sau khi đơn đạt trạng thái APPROVED_FOR_TRANSMISSION.

Current Behavior: Nhân viên mô phỏng nhập lại số đơn, nhà cung cấp và số lượng vào cổng đối tác. Nhập lại tạo rủi ro sai mã nguyên liệu và không có liên kết kỹ thuật để đối soát.

Underlying Need: Tạo đầu ra đủ chi tiết để nhóm API, QA và BA truy về cùng một đơn mua, cùng trường dữ liệu, cùng lỗi dự kiến.

Options: Xuất CSV thủ công; gửi email PDF; dùng REST API. CSV và PDF không trả mã nhận đơn có cấu trúc. REST API trả response machine-readable, tức phản hồi máy đọc được.

Decision Criteria: Cần xác nhận nhận đơn tự động, phát hiện gửi trùng, ghi lỗi theo từng request và liên kết dữ liệu sang test basis.

Decision: Dùng REST API POST /v1/purchase-orders cho INT-NF-001. Đây là quyết định mô phỏng học liệu, không phải cấu hình production.

Authority: Technical Architect quyết định kiến trúc; Business Owner xác nhận ý nghĩa nghiệp vụ; Security Owner xác nhận cơ chế xác thực; QA dùng artifact làm test basis. BA ghi nhận và liên kết, không thay các thẩm quyền này.

Artifact: Ví dụ hoàn chỉnh cho INT-NF-001.

Trường	Giá trị mô phỏng
Interface ID	`INT-NF-001`
Tên interface	Purchase Order Outbound to Partner API
Source system	Nova Foods ERP
Target system	Partner API
Direction	Outbound
Trigger	Purchase order chuyển `APPROVED_FOR_TRANSMISSION`
Operation	`POST /v1/purchase-orders`
Authentication	`Authorization: Bearer <access-token>`
Correlation ID	`NF-PO-20260807-0001`
Request business key	`purchaseOrderNo`
Duplicate rule	Cùng `purchaseOrderNo` trả `409 Conflict`
Success response	`201 Created`
Failure responses	`400 Bad Request`, `401 Unauthorized`, `409 Conflict`, `500 Internal Server Error`
Currency	`VND`
Case-data boundary	Dữ liệu tổng hợp, Nova Foods mô phỏng giáo dục

Mapping ID	ERP source field	API target field	Kiểu	Bắt buộc	Quy tắc biến đổi	Giá trị mẫu tổng hợp
`MAP-NF-001-01`	`PurchaseOrder.PurchaseOrderNo`	`purchaseOrderNo`	string	Có	Giữ nguyên	`PO-NF-20260807-001`
`MAP-NF-001-02`	`PurchaseOrder.SupplierCode`	`supplierCode`	string	Có	Giữ nguyên	`SUP-ALPHA-001`
`MAP-NF-001-03`	`PurchaseOrder.OrderDate`	`orderDate`	date	Có	ISO 8601 `YYYY-MM-DD`	`2026-08-07`
`MAP-NF-001-04`	`PurchaseOrder.CurrencyCode`	`currencyCode`	string	Có	Phải là `VND` trong case mô phỏng	`VND`
`MAP-NF-001-05`	`PurchaseOrderLine.MaterialCode`	`lines[].materialCode`	string	Có	Một dòng ERP thành một phần tử mảng	`RM-SUGAR-001`
`MAP-NF-001-06`	`PurchaseOrderLine.OrderedQuantity`	`lines[].quantity`	number	Có	Phải lớn hơn `0`	`500`
`MAP-NF-001-07`	`PurchaseOrderLine.UnitCode`	`lines[].unitCode`	string	Có	Giữ nguyên	`KG`
`MAP-NF-001-08`	`PurchaseOrderLine.UnitPrice`	`lines[].unitPrice`	number	Có	Không âm; đơn vị VND	`18500`

{
  "purchaseOrderNo": "PO-NF-20260807-001",
  "supplierCode": "SUP-ALPHA-001",
  "orderDate": "2026-08-07",
  "currencyCode": "VND",
  "lines": [
    {
      "materialCode": "RM-SUGAR-001",
      "quantity": 500,
      "unitCode": "KG",
      "unitPrice": 18500
    }
  ]
}

Điều kiện	HTTP response	Ý nghĩa nghiệp vụ	Hành vi cần ghi nhận
Request hợp lệ, đơn được nhận	`201 Created`	Đối tác đã tạo bản ghi nhận đơn	Lưu `partnerOrderId` và correlation ID
Thiếu `supplierCode`	`400 Bad Request`	Dữ liệu không đủ để nhận đơn	Ghi lỗi trường, không đánh dấu đã gửi
Access token không hợp lệ	`401 Unauthorized`	Caller chưa được xác thực	Ghi lỗi bảo mật, không lộ token
`purchaseOrderNo` đã tồn tại	`409 Conflict`	Ngăn tạo đơn trùng	Đối soát correlation ID trước khi gửi lại
Lỗi nội bộ phía đối tác	`500 Internal Server Error`	Chưa xác định đối tác có nhận đơn hay chưa	Giữ trạng thái cần đối soát, không tự kết luận thất bại

Consequence if Wrong: Sai mapping quantity có thể làm đối tác nhận sai lượng nguyên liệu. Sai xử lý 409 Conflict có thể tạo đơn mua trùng. Sai kết luận khi gặp 500 có thể dẫn tới gửi lặp dù đối tác đã nhận request.

Senior Lens

Phân biệt business key và correlation ID. purchaseOrderNo nhận diện đơn mua theo nghiệp vụ. NF-PO-20260807-0001 nhận diện một lần trao đổi kỹ thuật. Cùng một đơn có thể cần gửi lại sau lỗi mạng; vì vậy QA phải kiểm tra cả hai giá trị, không dùng correlation ID thay mã đơn.

Trường dữ liệu không có trong CANONICAL_DATA_DICTIONARY không được tự gán ý nghĩa canonical. Nếu supplierCode chưa có định nghĩa canonical, artifact phải ghi khoảng trống truy vết và đưa việc xác nhận cho Data Owner. Không suy diễn mã nhà cung cấp, quy tắc làm tròn VND, thời gian lưu log, hay nghĩa vụ pháp lý từ ví dụ mô phỏng.

Quick Reference

Kiểm tra anatomy	Kết quả cần thấy
Có một `Interface ID` xuyên suốt	`INT-NF-001` xuất hiện ở summary, API, mapping, lỗi và traceability
Mỗi trường request có nguồn và biến đổi	Tám dòng mapping có nguồn, đích, kiểu, bắt buộc và ví dụ
Mỗi response có nghĩa nghiệp vụ	`201`, `400`, `401`, `409`, `500` đều có hành vi tiếp theo
Dữ liệu mẫu an toàn	Nova Foods mô phỏng, dữ liệu tổng hợp, tiền tệ `VND`
Ranh giới thẩm quyền rõ	BA ghi nhận artifact; vai trò chuyên môn xác nhận phần thuộc thẩm quyền

Core

Quality gate là cổng kiểm tra chất lượng trước downstream review: reviewer nhận artifact đủ để đối chiếu, đặt câu hỏi và ghi nhận nhận xét mà không phải suy đoán. Gate không phải approval, baseline, xác nhận tuân thủ, production readiness hay quyết định triển khai.

Output API/integration	Điều kiện ready for downstream review	Bằng chứng phải có	Điều kiện fail
API contract	Mỗi endpoint có method, URL, mục đích, request, response, HTTP status, lỗi và quy tắc xác thực	Liên kết requirement, data field và error case	Thiếu status lỗi, field bắt buộc hoặc nguồn dữ liệu
Integration flow	Có source, target, trigger, hướng dữ liệu, tần suất, cơ chế lỗi và owner xử lý	Sơ đồ luồng đọc được; giả định gắn nhãn	Không xác định điểm bắt đầu, điểm kết thúc hoặc nơi xử lý lỗi
Data mapping	Mỗi field nguồn có field đích, kiểu dữ liệu, biến đổi, mandatory flag và xử lý giá trị rỗng	Mapping không có dòng trống; dùng tên field nhất quán	Field đích không rõ, biến đổi không giải thích hoặc thiếu xử lý null
API requirement hoặc business rule cập nhật	Có liên kết tới nguồn canonical; phân biệt fact, assumption và Verification required	Canonical ID hoặc đường dẫn canonical hiện có	Diễn đạt assumption như quy tắc đã xác nhận
Test basis integration	Có scenario thành công, lỗi nghiệp vụ, lỗi kỹ thuật và expected result	API contract, mapping hoặc flow được tham chiếu	Expected result không kiểm chứng được từ artifact nguồn

12-api-and-integration-analysis — diagram 15

Source mermaid — có thể chỉnh sửa

stateDiagram-v2
    direction TB

    [*] --> Draft
    Draft --> Quality_gate_check: kiểm tra điều kiện và bằng chứng
    Quality_gate_check --> Ready_for_downstream_review: đủ điều kiện ready và bằng chứng bắt buộc
    Quality_gate_check --> Rework: thiếu bằng chứng hoặc mâu thuẫn
    Rework --> Draft: cập nhật bằng chứng, giải quyết mâu thuẫn, lưu lịch sử
    Ready_for_downstream_review --> IN_REVIEW: bàn giao downstream review
    IN_REVIEW --> Rework: reviewer phát hiện lỗi

    note right of Ready_for_downstream_review
        Đủ đầu vào review.
        Không phải approval, baseline,
        compliance, production readiness
        hay quyết định triển khai.
    end note

Ready_for_downstream_review chỉ nói artifact đủ đầu vào review. Status corpus vẫn IN_REVIEW, version v0.9.0, ngày 2026-08-07, timezone Asia/Ho_Chi_Minh.

Applied

Nova Foods Trading & Manufacturing là case mô phỏng giáo dục; mọi dữ liệu dưới đây là synthetic.

Mục	Nội dung
Facts	ERP mô phỏng gửi sales order sang warehouse service qua `POST /warehouse/orders`.
Current Behavior	Warehouse service cần `salesOrderId`, `requestedDeliveryDate`, `customerCode` và danh sách item để tạo yêu cầu xuất kho.
Underlying Need	Reviewer cần kiểm tra ERP có gửi đủ dữ liệu, warehouse có trả lỗi dùng được và BA không suy diễn rule chưa xác minh.
Options	Option 1: review flow narrative. Option 2: review API contract, mapping và lỗi cùng nhau.
Decision Criteria	Đủ traceability, kiểm tra được field bắt buộc, thấy được lỗi và không biến assumption thành fact.
Decision	Chọn Option 2. API contract chỉ ready khi mapping và error behavior cùng nhất quán.
Authority	Principal IT Business Analyst / Technical Curriculum Author duy trì artifact. Business Owner, Architect, Security và QA giữ thẩm quyền review theo chuyên môn.
Artifact	API contract và data mapping thuộc `/02-handbook/12-api-and-integration-analysis.md`; trạng thái `IN_REVIEW`, version `v0.9.0`.
Consequence if Wrong	Thiếu `requestedDeliveryDate` có thể tạo yêu cầu kho không lập kế hoạch được; trả HTTP status không rõ làm test team không xác định expected result.

Ví dụ gate: salesOrderId được mapping từ nguồn sang đích; kiểu dữ liệu, mandatory flag và lỗi khi thiếu giá trị phải xuất hiện nhất quán trong contract và mapping. Suy luận: warehouse cần định danh đơn để liên kết yêu cầu xuất kho, nên contract thiếu field này không đủ review. Đây là reasoning từ Current Behavior, không phải xác nhận cấu hình ERP thật.

Senior Lens

Gate tốt đo khả năng review, không đo độ đúng cuối cùng. BA không tự kết luận endpoint an toàn, rule hợp pháp hay mapping đúng vận hành. Nếu artifact chạm dữ liệu cá nhân, kế toán, hóa đơn, truy xuất thực phẩm hoặc bảo mật API, ghi Verification required và chuyển reviewer có thẩm quyền. Nguồn OWASP API Security Top 10 là industry good practice, không phải luật Việt Nam.

Mỗi lần sửa để qua gate phải ghi change history: ngày 2026-08-07, version v0.9.0, người ghi nhận, phần thay đổi, lý do, artifact nguồn bị ảnh hưởng. Không sửa im lặng. Không đổi canonical ID, filename, source classification hoặc traceability link để làm artifact trông hoàn chỉnh.

Quick Reference

Check cuối	Pass khi	Không được suy diễn thành
Completeness	Không thiếu input, output, lỗi, owner hoặc link traceability cần review	Approval
Consistency	Flow, contract, mapping và test basis không mâu thuẫn	Production readiness
Evidence	Fact có nguồn; assumption và `Verification required` có nhãn	Compliance confirmation
Change control	Sửa đổi có version và change history	Baseline
Authority boundary	Reviewer chuyên môn được chỉ rõ khi cần	Owner có quyền quyết định thay họ

7. Who consumes those outputs?

Core

Đầu ra phân tích API và tích hợp không phải tài liệu để BA “bàn giao xong”. Mỗi đầu ra là bằng chứng làm việc cho một vai trò khác. Nova Foods Trading & Manufacturing là case study mô phỏng; mọi tên luồng và dữ liệu dưới đây là dữ liệu tổng hợp.

Consumer	Đầu ra họ dùng	Cách họ dùng trong công việc
Developers	API contract, data mapping, error catalogue, sequence flow	Xây endpoint, validate request, map dữ liệu nguồn-đích, trả HTTP response và xử lý lỗi đúng contract
QA	API contract, business rule reference, error catalogue, traceability	Tạo test basis, kiểm tra request/response, test dữ liệu biên, lỗi và liên kết test với requirement
Architect	Context diagram, sequence flow, API contract, non-functional notes	Kiểm tra ranh giới hệ thống, protocol, ownership dữ liệu, khả năng tích hợp và rủi ro kiến trúc
PM/Product Owner	Scope map, dependency list, acceptance-facing summary	Xếp ưu tiên, lập kế hoạch delivery, nhận diện dependency và quyết định phần nào cần làm trước
Business Owner	Process flow, business rule reference, field meaning, exception flow	Kiểm tra tích hợp có giữ đúng ý nghĩa nghiệp vụ, như đơn bán nào được phép gửi yêu cầu xuất kho
Operations	Runbook-facing error flow, retry rule, monitoring fields	Nhận biết lỗi vận hành, tra transaction, xử lý retry hoặc chuyển sự cố cho đội phù hợp
Specialist owners	Data classification, rule reference, exception flow	Review phần thuộc chuyên môn: Accounting Owner xem số tiền; Security Owner xem access; Food Safety Owner xem truy xuất; Legal/Privacy Owner xem dữ liệu cá nhân

12-api-and-integration-analysis — diagram 16

Source mermaid — có thể chỉnh sửa

flowchart TB
    CONTRACT[API contract]
    MAPPING[Data mapping]
    ERRORS[Error catalogue]
    SEQUENCE[Sequence flow]
    RULES[Business rule reference]
    TRACE[Traceability]
    CONTEXT[Context diagram]
    NFR[Non-functional notes]
    SCOPE[Scope map]
    DEPENDENCIES[Dependency list]
    ACCEPT[Acceptance-facing summary]
    PROCESS[Process flow]
    FIELD[Field meaning]
    EXCEPTION[Exception flow]
    RUNBOOK[Runbook-facing error flow]
    OPSNOTES[Retry rule and monitoring fields]
    CLASSIFY[Data classification]

    DEV[Developers — build integration]
    QA[QA — create test basis]
    ARC[Architect — review architecture]
    PO[PM/Product Owner — plan delivery]
    BUS[Business Owner — review business meaning]
    OPS[Operations — retry, trace, escalate]
    SPO[Specialist owners — review domain]

    CONTRACT --> DEV
    CONTRACT --> QA
    CONTRACT --> ARC

    MAPPING --> DEV

    ERRORS --> DEV
    ERRORS --> QA

    SEQUENCE --> DEV
    SEQUENCE --> ARC

    RULES --> QA
    RULES --> BUS
    RULES --> SPO

    TRACE --> QA
    CONTEXT --> ARC
    NFR --> ARC

    SCOPE --> PO
    DEPENDENCIES --> PO
    ACCEPT --> PO

    PROCESS --> BUS
    FIELD --> BUS
    EXCEPTION --> BUS
    EXCEPTION --> SPO

    RUNBOOK --> OPS
    OPSNOTES --> OPS
    CLASSIFY --> SPO

Applied

Facts: Luồng mô phỏng Sales Order gửi yêu cầu xuất kho từ ERP Nova Foods sang warehouse service. Đầu ra BA gồm process flow, API contract, data mapping và error catalogue.

Current Behavior: API contract nêu salesOrderId, requestedDeliveryDate, items; data mapping nêu nguồn của từng field; error catalogue nêu lỗi khi thiếu salesOrderId.

Underlying Need: Developers cần biết field nào phải gửi. QA cần biết lỗi nào phải test. Business Owner cần biết yêu cầu xuất kho còn giữ liên kết với đơn bán. Operations cần biết cách tra lỗi theo salesOrderId.

Options: Một tài liệu mô tả tự do; hoặc bộ đầu ra tách rõ flow, contract, mapping và lỗi.

Decision Criteria: Consumer phải tìm được thông tin cần dùng mà không tự đoán ý nghĩa field, nguồn dữ liệu hoặc hành vi lỗi.

Decision: Dùng bộ đầu ra tách rõ. API contract mô tả giao tiếp. Data mapping mô tả biến đổi dữ liệu. Error catalogue mô tả lỗi. Process flow mô tả thứ tự nghiệp vụ.

Authority: BA duy trì liên kết giữa đầu ra. Developers, QA, Architect, Business Owner, Operations và specialist owners dùng đầu ra trong phạm vi vai trò. Case study không ghi nhận approval, baseline hay quyết định production.

Artifact: API contract, data mapping, process flow, error catalogue và traceability link thuộc /02-handbook/12-api-and-integration-analysis.md ở trạng thái IN_REVIEW, version v0.9.0, ngày 2026-08-07.

Consequence if Wrong: Developer có thể gửi field sai nguồn. QA có thể bỏ test lỗi. Operations không tra được transaction. Business Owner có thể hiểu sai trạng thái xuất kho. Hệ quả này là rủi ro mô phỏng, không xác nhận hành vi ERP thực tế.

Senior Lens

Cùng một output có nhiều consumer, nhưng không cùng mục đích. API contract cho Developer là bản xây dựng giao tiếp; cho QA là test basis; cho Architect là bằng chứng về boundary; cho Operations là dữ liệu để tra sự cố. Suy luận: nếu contract chỉ đủ cho một vai trò đọc, handoff chưa đủ vì consumer khác phải tự suy diễn.

Specialist owner chỉ nhận phần thuộc thẩm quyền. Ví dụ field chứa dữ liệu cá nhân cần Privacy/Legal Owner review; field tiền tệ VND hoặc trạng thái hóa đơn cần Accounting Owner review; token và quyền truy cập cần Security Owner review. Các nội dung này giữ nhãn Verification required khi chưa có kết luận từ owner có thẩm quyền.

Quick Reference

Output	Consumer chính	Mục đích tiêu thụ
Process flow	Business Owner, PM/Product Owner, Operations	Hiểu điểm bắt đầu, bước xử lý, ngoại lệ và phụ thuộc
API contract	Developers, QA, Architect	Build, test và review giao tiếp HTTP
Data mapping	Developers, QA, specialist owners	Xác định nguồn, đích, kiểu và biến đổi dữ liệu
Error catalogue	Developers, QA, Operations	Build lỗi, test lỗi và xử lý sự cố
Traceability link	QA, PM/Product Owner, BA	Theo từ requirement đến contract, mapping và test basis

Core

Đầu ra phân tích API và tích hợp chỉ có giá trị khi người nhận biết phạm vi quyết định của mình. Nova Foods Trading & Manufacturing là case mô phỏng giáo dục; mọi dữ liệu là tổng hợp, trạng thái corpus IN_REVIEW, phiên bản v0.9.0, ngày 2026-08-07. Không người nhận nào được suy diễn artifact đang review thành baseline, phê duyệt, cấu hình ERP thật, kết luận pháp lý hay quyết định production.

Người nhận	Có thể quyết định	Bằng chứng phải đọc	Phải escalation khi
Developers	Cách hiện thực endpoint, kiểm tra dữ liệu đầu vào, xử lý lỗi, retry và mapping kỹ thuật	API contract, ví dụ request/response tổng hợp, data mapping, error catalogue, acceptance criteria, traceability	Contract mâu thuẫn rule nghiệp vụ; thiếu owner trường dữ liệu; yêu cầu làm lộ dữ liệu cá nhân; thay đổi phá vỡ consumer
QA	Test basis, phạm vi test tích hợp, test dữ liệu biên, expected result	Acceptance criteria, API contract, error catalogue, mapping, traceability	Không xác định được expected result; rule mâu thuẫn; môi trường hoặc dữ liệu test không an toàn
Architect	Pattern tích hợp, ranh giới hệ thống, giao thức, versioning, khả năng chịu lỗi	Context diagram, sequence diagram, interface inventory, NFR, rủi ro bảo mật	Thay đổi kiến trúc; dữ liệu vượt trust boundary; SLA, throughput, disaster recovery chưa có owner
PM/Product Owner	Ưu tiên phạm vi, trade-off thời gian/chi phí, chấp nhận rủi ro sản phẩm trong thẩm quyền	Scope, dependency, impact assessment, decision log, traceability	Quyết định đổi business rule; rủi ro pháp lý, kế toán, an toàn thực phẩm hoặc ngân sách vượt thẩm quyền
Business Owner	Ý nghĩa nghiệp vụ, outcome, quy tắc vận hành, ngoại lệ nghiệp vụ	Process, business rule, ví dụ dữ liệu tổng hợp, acceptance criteria, impact assessment	Quy tắc liên quan pháp lý, kế toán, thuế, hóa đơn, dữ liệu cá nhân hoặc recall cần owner chuyên môn
Operations	Quy trình giám sát, cảnh báo, xử lý lỗi vận hành, runbook và quyền hỗ trợ	Error handling, monitoring requirement, support model, reconciliation rule	Không có cách phát hiện mất bản ghi; retry tạo trùng; yêu cầu quyền production hoặc thay đổi quy trình vận hành
Specialist owners: Security, Legal, Accounting, Food-safety	Kết luận chuyên môn thuộc lĩnh vực	Data classification, data flow, rule impact, nguồn chính thức còn hiệu lực	Requirement được diễn đạt như nghĩa vụ bắt buộc nhưng chưa được chủ sở hữu chuyên môn xác minh

12-api-and-integration-analysis — diagram 17

Source mermaid — có thể chỉnh sửa

flowchart TB
    BA[BA output package<br/>IN_REVIEW v0.9.0<br/>Review date: 2026-08-07<br/>Synthetic case data] --> BOUNDARY[Review boundary<br/>Not baseline, ERP configuration,<br/>legal conclusion, or production decision]

    BOUNDARY --> DEV[Developers]
    BOUNDARY --> QA[QA]
    BOUNDARY --> ARC[Architect]
    BOUNDARY --> PO[PM/Product Owner]
    BOUNDARY --> BO[Business Owner]
    BOUNDARY --> OPS[Operations]
    BOUNDARY --> SPO[Security, Legal, Accounting,<br/>Food-safety]

    DEV -->|Contract conflict; missing field owner;<br/>personal-data exposure; breaking consumer change| ESC[Escalation package]
    QA -->|Expected result unclear; rule conflict;<br/>unsafe test environment or data| ESC
    ARC -->|Architecture change; data crossing a trust boundary;<br/>unowned SLA, throughput, or disaster recovery| ESC
    PO -->|Business-rule change; legal, accounting,<br/>food-safety, or budget beyond PM/Product Owner authority| ESC
    BO -->|Legal, accounting, tax, invoice,<br/>personal-data, or recall rule| ESC
    OPS -->|Cannot detect lost records; duplicate retry;<br/>production access or operating-process change| ESC
    SPO -->|Mandatory requirement lacks<br/>specialist verification| ESC

    ESC --> BA
    ESC -->|Business rule or outcome| BO
    ESC -->|Security, legal, accounting,<br/>or food-safety conclusion| SPO

Applied

Facts: API đồng bộ phiếu giao hàng mô phỏng gửi deliveryStatus sang ERP Nova Foods. Current Behavior: contract mô tả DELIVERED nhưng không nêu xử lý khi cùng deliveryId gửi lại. Underlying Need: tránh tạo hai lần cập nhật kho hoặc doanh thu. Options: reject bản ghi trùng; chấp nhận idempotent bằng cùng khóa; xử lý thủ công. Decision Criteria: bảo toàn dữ liệu, khả năng audit, tác động consumer, bằng chứng rule nghiệp vụ. Decision: Developers không tự chọn rule tài chính; Architect đánh giá cơ chế idempotency; Business Owner xác nhận ý nghĩa nghiệp vụ; Accounting Owner phải xác minh nếu cập nhật ảnh hưởng ghi nhận kế toán. Authority: BA tổng hợp câu hỏi và traceability, không cấp kết luận. Artifact: API contract, data mapping, error catalogue, decision log đều giữ IN_REVIEW. Consequence if Wrong: retry mạng có thể tạo cập nhật trùng; reconciliation vận hành không phát hiện đủ nếu thiếu khóa và log.

Senior Lens

Escalation không phải chuyển trách nhiệm. Nó là gói bằng chứng gồm: quyết định cần chốt, artifact bị ảnh hưởng, facts quan sát được, nguồn canonical, các phương án, rủi ro và owner cần kết luận. Cầu nối suy luận: contract thiếu quy tắc bản ghi trùng; retry HTTP có thể xảy ra; cập nhật nghiệp vụ có thể lặp; vì vậy cần owner xác nhận semantics trước khi code hay test expected result.

Không dùng nguồn pháp lý trong corpus để tự kết luận nghĩa vụ Nova Foods. Luật Bảo vệ dữ liệu cá nhân, Luật Kế toán, Nghị định 123/2020/NĐ-CP và Luật An toàn thực phẩm chỉ là nguồn cần specialist owner xác minh khi requirement chạm phạm vi tương ứng.

Quick Reference

Hiểu nhầm handoff	Câu hỏi làm rõ chính xác
“API trả `200` là nghiệp vụ thành công.”	“HTTP `200` xác nhận xử lý kỹ thuật nào, và trường nào xác nhận kết quả nghiệp vụ?”
“QA tự suy ra expected result từ JSON.”	“Quy tắc nghiệp vụ hoặc acceptance criterion nào xác định kết quả cho từng error code?”
“Developer tự map trường vì tên gần giống.”	“Owner nào xác nhận `customerCode` nguồn và `customerId` đích có cùng định nghĩa, độ dài, lifecycle?”
“Retry luôn an toàn.”	“Khóa idempotency là gì, thời hạn lưu khóa bao lâu, và bản ghi trùng phải trả response nào?”
“Dữ liệu cá nhân chỉ là field kỹ thuật.”	“Trường nào là dữ liệu cá nhân, ai xác minh mục đích xử lý và quyền truy cập?”
“PM có thể chốt mọi ngoại lệ.”	“Ngoại lệ này có đổi business rule, kế toán, pháp lý, bảo mật hay vận hành không; owner chuyên môn nào phải kết luận?”

Core

Handoff là bàn giao đầu ra giữa vai trò. Lỗi thường không nằm ở tệp thiếu, mà ở cùng một câu nhưng mỗi bên hiểu khác. Với Nova Foods Trading & Manufacturing mô phỏng, dữ liệu tổng hợp, BA phải biến điểm mơ hồ thành câu hỏi có thể trả lời, bằng chứng có thể kiểm tra, và nơi cần escalation.

Hiểu nhầm khi bàn giao	Rủi ro	Câu hỏi làm rõ chính xác
Developer hiểu trường `status` là trạng thái đơn hàng; QA hiểu là trạng thái đồng bộ API.	Test sai đối tượng, ghi đè trạng thái nghiệp vụ.	"`status` trong payload này biểu diễn trạng thái nào, nguồn dữ liệu canonical là đâu, và giá trị nào được phép ghi ngược vào ERP?"
QA coi HTTP `200` là tích hợp thành công; Operations coi thành công khi dữ liệu xuất hiện trong ERP.	Lỗi xử lý bất đồng bộ không bị phát hiện.	"Tiêu chí thành công là API nhận yêu cầu, xử lý hoàn tất, hay bản ghi đích được tạo? Bằng chứng nào xác nhận từng mốc?"
Developer dùng mã sản phẩm hiển thị; Business Owner mong mã hàng canonical.	Trùng hoặc sai sản phẩm khi đồng bộ.	"Trường nào là khóa định danh ổn định giữa hai hệ thống: mã hiển thị, mã ERP, hay khóa tích hợp? Ai sở hữu quy tắc tạo và đổi mã?"
Architect coi retry là chi tiết kỹ thuật; Operations cần biết retry có tạo giao dịch trùng hay không.	Nhân đôi phiếu, tồn kho hoặc chứng từ.	"Endpoint có idempotency không? Khi gửi lại cùng một yêu cầu, hệ thống phải từ chối, trả kết quả cũ, hay tạo bản ghi mới?"
PM/Product Owner hiểu lỗi là phải hiện thông báo; Developer chỉ ghi log.	Người dùng không biết cần xử lý lại.	"Lỗi nào phải hiện cho người dùng, lỗi nào chỉ ghi log, và ai nhận cảnh báo khi vượt ngưỡng xử lý?"

12-api-and-integration-analysis — diagram 18

Source mermaid — có thể chỉnh sửa

flowchart TD
    START["Handoff payload, rule và acceptance criteria"] --> CHECK{"Các vai trò hiểu giống nhau và có bằng chứng?"}
    CHECK -->|"Có"| READY["Cơ sở phát triển, kiểm thử và vận hành truy vết được"]
    CHECK -->|"Không"| TYPE{"Điểm mơ hồ hoặc ngoại lệ"}

    TYPE -->|"Nghĩa status"| R1["Rủi ro test sai đối tượng hoặc ghi đè trạng thái nghiệp vụ"]
    TYPE -->|"Khóa định danh"| R2["Rủi ro sai hoặc trùng sản phẩm"]
    TYPE -->|"HTTP 200 và kết quả xử lý"| R3["Rủi ro bỏ sót lỗi bất đồng bộ"]
    TYPE -->|"Retry và idempotency"| R4["Rủi ro tạo giao dịch hoặc bản ghi trùng"]
    TYPE -->|"Hiển thị lỗi, log và cảnh báo"| R5["Rủi ro người dùng không biết cần xử lý lại"]
    TYPE -->|"Kết quả nghiệp vụ"| R6["Operations phát hiện thiếu kết quả hoặc bản ghi trùng"]

    R1 --> QUESTION["BA ghi câu hỏi chính xác, rủi ro và bằng chứng cần kiểm tra"]
    R2 --> QUESTION
    R3 --> QUESTION
    R4 --> QUESTION
    R5 --> QUESTION
    R6 --> QUESTION

    QUESTION --> OWNER{"Đã xác định đúng owner trả lời?"}
    OWNER -->|"Không"| ESC["Escalate để xác định owner và ghi điểm đang chờ"]
    ESC --> OWNER

    OWNER -->|"Nguồn canonical hoặc quy tắc nghiệp vụ"| BO["Gửi owner nguồn dữ liệu hoặc Business Owner"]
    OWNER -->|"Kết quả nghiệp vụ hoặc cách báo lỗi"| PO["Gửi PM hoặc Product Owner"]
    OWNER -->|"API, retry hoặc idempotency"| TECH["Gửi Developer hoặc Architect"]
    OWNER -->|"Bằng chứng xử lý thực tế"| OPS["Gửi Operations"]

    BO --> CONFIRM{"Có câu trả lời và bằng chứng kiểm tra được?"}
    PO --> CONFIRM
    TECH --> CONFIRM
    OPS --> CONFIRM

    CONFIRM -->|"Không"| FOLLOW["BA làm rõ lại với owner hoặc escalate khi thiếu owner hay bằng chứng"]
    FOLLOW --> OWNER
    CONFIRM -->|"Có"| RECORD["Ghi diễn giải, owner, quyết định, acceptance criteria và nguồn bằng chứng"]

    RECORD --> EVIDENCE["Bằng chứng: API nhận yêu cầu, xử lý hoàn tất, bản ghi trong ERP, log hoặc cảnh báo"]
    EVIDENCE --> UPDATE["Cập nhật cơ sở phát triển, kiểm thử và vận hành"]
    UPDATE --> VERIFY{"Developer, QA hoặc Operations phát hiện cách hiểu khác?"}
    VERIFY -->|"Có"| TYPE
    VERIFY -->|"Không"| READY

Applied

Mục	Nội dung
Facts	API đồng bộ đơn bán mô phỏng trả HTTP `202 Accepted`. Payload có `externalOrderId`, nhưng chưa nêu khi nào ERP tạo đơn.
Current Behavior	Developer hiểu `202` là hoàn tất. QA chuẩn bị test kiểm tra mã HTTP. Operations cần tra cứu đơn trong ERP sau xử lý.
Underlying Need	Phân biệt “đã nhận yêu cầu” với “đã tạo đơn ERP”, để không báo thành công trước khi có kết quả nghiệp vụ.
Options	1. HTTP `202` là thành công cuối. 2. HTTP `202` là đã nhận, client tra cứu trạng thái xử lý. 3. API chờ xử lý xong rồi trả kết quả cuối.
Decision Criteria	Thời gian xử lý, khả năng lỗi sau khi nhận, khả năng tra cứu, tránh tạo đơn trùng, nhu cầu vận hành xử lý lỗi.
Decision	Chưa quyết định. Cần xác nhận nghĩa của `202`, nguồn trạng thái xử lý, và cơ chế chống trùng.
Authority	Architect quyết định mẫu tích hợp; Business Owner xác nhận mốc thành công nghiệp vụ; Operations xác nhận bằng chứng vận hành; QA xác nhận test basis.
Artifact	Đối chiếu đặc tả API với `/01-curriculum/CANONICAL_DATA_DICTIONARY.md`, `/01-curriculum/CANONICAL_BUSINESS_RULES.md` và `TRACEABILITY_ID_REGISTRY`; các artifact đều `IN_REVIEW`, `v0.9.0`, ngày `2026-08-07`.
Consequence if Wrong	Đơn mô phỏng có thể không tồn tại trong ERP dù client báo thành công; retry có thể tạo đơn trùng; QA bỏ sót lỗi xử lý nền.

Câu hỏi cần gửi nguyên văn: “HTTP 202 Accepted xác nhận hệ thống đã nhận yêu cầu hay đã tạo đơn ERP? Nếu xử lý sau đó thất bại, consumer tra cứu trạng thái bằng trường nào, trong thời hạn nào, và retry với cùng externalOrderId phải cho kết quả gì?”

Senior Lens

Không tự chuyển câu trả lời kỹ thuật thành quy tắc nghiệp vụ. Bằng chứng “API trả 202” chỉ chứng minh phản hồi giao thức HTTP; không chứng minh đơn ERP đã tồn tại. Muốn kết luận thành công nghiệp vụ cần bằng chứng đích, như mã đơn được tạo hoặc trạng thái xử lý được định nghĩa trong artifact canonical.

Escalate khi một câu trả lời ảnh hưởng đồng thời dữ liệu, kiến trúc, kiểm soát trùng lặp, bảo mật, kế toán, pháp lý hoặc vận hành. Ví dụ, yêu cầu lưu externalOrderId lâu bao nhiêu không chỉ là lựa chọn database; có thể ảnh hưởng truy vết và dữ liệu cá nhân. Gắn nhãn Verification required nếu cần diễn giải pháp lý, kế toán, an toàn thực phẩm hoặc bảo vệ dữ liệu cá nhân.

Quick Reference

Khi nghe câu này	Hỏi lại
“API thành công rồi.”	“Thành công theo HTTP, xử lý kỹ thuật, hay kết quả nghiệp vụ?”
“QA test theo spec.”	“Spec nào là nguồn canonical, version nào, và acceptance criteria nào liên kết với test?”
“Retry được.”	“Retry nhận diện yêu cầu cũ bằng khóa nào và kết quả khi trùng là gì?”
“Ops tự xử lý lỗi.”	“Ops có quyền sửa dữ liệu, gửi lại giao dịch, hay chỉ mở escalation? Bằng chứng đóng lỗi là gì?”
“Trường này là mã đơn.”	“Mã này do hệ thống nào cấp, có đổi được không, và có phải khóa tích hợp không?”

8. Detailed Worked Example

Core

Ví dụ này dùng Nova Foods Trading & Manufacturing, doanh nghiệp mô phỏng giáo dục; mọi dữ liệu là tổng hợp, locale vi-VN, múi giờ Asia/Ho_Chi_Minh, tiền tệ VND. Tình huống tập trung tích hợp API giữa cổng bán hàng B2B và ERP để nhận đơn đặt hàng đại lý.

Applied

Phạm vi tình huống: INT-SCN-ORD-001 — Cổng B2B gửi đơn bán hàng vào ERP Nova Foods. API là giao diện lập trình cho phép hai hệ thống trao đổi dữ liệu theo hợp đồng xác định. ERP là hệ thống quản trị nguồn lực doanh nghiệp, nơi đơn cần tồn tại để kho, kế toán và vận hành tiếp tục xử lý.

Facts

Thành phần	Giá trị mô phỏng	Bằng chứng hoặc ranh giới
Mã tình huống	`INT-SCN-ORD-001`	Định danh học liệu cục bộ cho ví dụ này
Hệ thống gửi	`NOVA-B2B-PORTAL`	Cổng đặt hàng đại lý mô phỏng
Hệ thống nhận	`NOVA-ERP`	ERP Nova Foods mô phỏng
API nhận đơn	`POST /api/v1/sales-orders`	Endpoint mô phỏng trong phạm vi tình huống
Khách hàng	`CUS-DL-00128` — Đại lý Minh Phát	Dữ liệu tổng hợp, không phải khách hàng thật
Mã hàng	`SKU-NF-RAU-500G` — Rau củ sấy 500 g	Danh mục mô phỏng
Kho giao	`WH-HCM-01` — Kho TP.HCM	Địa điểm mô phỏng
Số lượng	`120` gói	Số nguyên dương
Đơn giá	`85000` VND/gói	Giá trị mô phỏng
Tổng trước thuế	`10200000` VND	`120 × 85000`
Thời điểm gửi	`2026-08-07T10:15:00+07:00`	Theo `Asia/Ho_Chi_Minh`
Khóa chống gửi trùng	`externalOrderId: B2B-20260807-000481`	Mã đơn do hệ thống gửi cấp
Dữ liệu cá nhân	`contactName`, `contactPhone`	Có thể là dữ liệu cá nhân; Verification required với Legal/Privacy Owner trước dùng production

Payload gửi hiện tại:

{
  "externalOrderId": "B2B-20260807-000481",
  "customerCode": "CUS-DL-00128",
  "orderDate": "2026-08-07",
  "currency": "VND",
  "warehouseCode": "WH-HCM-01",
  "contactName": "Nguyễn An",
  "contactPhone": "0900000128",
  "lines": [
    {
      "lineNo": 1,
      "itemCode": "SKU-NF-RAU-500G",
      "quantity": 120,
      "unitPrice": 85000
    }
  ]
}

Current Behavior

Cổng NOVA-B2B-PORTAL gửi payload đến NOVA-ERP. ERP trả HTTP 202 Accepted trong thời gian ngắn, rồi chuyển payload sang tiến trình nền. HTTP 202 Accepted nghĩa là máy chủ đã nhận yêu cầu để xử lý sau; mã này không tự chứng minh đơn ERP đã được tạo.

ERP hiện kiểm tra cấu trúc JSON và sự tồn tại sơ bộ của customerCode, rồi đặt bản ghi vào hàng đợi xử lý. Tiến trình nền kiểm tra tồn kho, trạng thái khách hàng và tạo đơn. Khi tiến trình nền lỗi, cổng B2B không nhận mã đơn ERP, không có API tra cứu trạng thái, và không nhận thông báo lỗi nghiệp vụ.

Bước hiện tại	Hành vi quan sát được	Kết quả
1	B2B gửi `POST /api/v1/sales-orders`	Payload tới ERP
2	ERP kiểm tra JSON hợp lệ	JSON hợp lệ tiếp tục xử lý
3	ERP trả `202 Accepted`	B2B hiển thị “Đã gửi đơn”
4	ERP xử lý nền kiểm tra kho	Có thể thành công hoặc thất bại sau phản hồi HTTP
5	ERP tạo đơn hoặc ghi lỗi nội bộ	B2B không biết kết quả cuối
6	Người dùng B2B gửi lại khi chưa thấy đơn	Có nguy cơ tạo hai đơn nếu ERP chưa nhận diện đúng giao dịch cũ

12-api-and-integration-analysis — diagram 19

Source mermaid — có thể chỉnh sửa

sequenceDiagram
    autonumber
    participant B2B as NOVA-B2B-PORTAL
    box NOVA-ERP — ranh giới nội bộ
        participant API as API
        participant JOB as Tiến trình nền
    end

    B2B->>API: POST /api/v1/sales-orders
    API->>API: Kiểm tra cấu trúc JSON

    alt JSON không hợp lệ
        Note over B2B,API: Kết quả hoặc phản hồi không được artifact nguồn mô tả
    else JSON hợp lệ
        API->>API: Kiểm tra sơ bộ customerCode

        alt customerCode không tồn tại
            Note over B2B,API: Kết quả hoặc phản hồi không được artifact nguồn mô tả
        else customerCode tồn tại
            API->>JOB: Đặt payload vào hàng đợi
            API-->>B2B: HTTP 202 Accepted
            JOB->>JOB: Kiểm tra tồn kho và trạng thái khách hàng

            alt Xử lý thành công
                JOB->>JOB: Tạo đơn ERP
            else Xử lý thất bại
                JOB->>JOB: Ghi lỗi nội bộ
            end

            Note over B2B,JOB: B2B không nhận mã đơn ERP, trạng thái cuối hoặc lỗi nghiệp vụ

            opt Người dùng chưa thấy đơn và gửi lại
                B2B->>API: Gửi lại cùng externalOrderId
                Note over B2B,JOB: Suy luận: có nguy cơ tạo hai đơn vì chưa rõ ERP nhận diện externalOrderId trùng
            end
        end
    end

Ranh giới факт và suy luận: facts chứng minh API hiện trả 202 Accepted, xử lý nền tồn tại, và B2B thiếu kết quả cuối. Suy luận “có nguy cơ đơn trùng” dựa trên hai bằng chứng: người dùng có thể gửi lại cùng externalOrderId, còn hành vi nhận diện giao dịch trùng chưa được ghi nhận trong artifact nguồn. Suy luận này chưa là quy tắc nghiệp vụ, quyết định kiến trúc, hay kết luận đã được phê chuẩn.

Senior Lens

Không gọi 202 Accepted là “tạo đơn thành công”. Thành công giao thức khác thành công nghiệp vụ. Bằng chứng thành công nghiệp vụ cần mã đơn ERP hoặc trạng thái cuối có thể tra cứu.

externalOrderId là dữ liệu tích hợp cần truy vết nguồn cấp và quy tắc duy nhất. Chưa có artifact canonical xác nhận khóa này là duy nhất, thời gian lưu, hay hành vi retry. Giữ nhãn IN_REVIEW, v0.9.0, ngày 2026-08-07; không diễn giải ví dụ thành cấu hình production.

Quick Reference

Mục	Giá trị
Artifact liên quan	`/02-handbook/12-api-and-integration-analysis.md`
Tình huống	`INT-SCN-ORD-001`
Luồng	`NOVA-B2B-PORTAL` đến `NOVA-ERP`
Kết quả HTTP hiện tại	`202 Accepted`
Khoảng trống hiện tại	Thiếu kết quả xử lý cuối cho B2B
Phân loại dữ liệu	Dữ liệu tổng hợp; `contactName`, `contactPhone` cần Verification required trước production

Applied

Bối cảnh mô phỏng: Nova Foods Trading & Manufacturing là case học liệu, toàn bộ dữ liệu dưới đây là tổng hợp. Kịch bản: ERP cần nhận xác nhận giao hàng từ hệ thống vận tải mô phỏng NovaLogistics.

Bước phân tích	Nội dung và cầu nối lập luận
Facts	Đơn bán `SO-NF-20260807-001` có tổng tiền `12.500.000 VND`, khách `CUS-NF-001`, trạng thái ERP `READY_TO_SHIP`. Kho `WH-HCM-01` đã xuất lô `LOT-NF-260807-A`. `NovaLogistics` gửi HTTP `POST` đến API ERP khi giao hàng hoàn tất.
Current Behavior	Nhân viên kho nhận ảnh giao hàng qua email, rồi tự đổi trạng thái đơn. Bằng chứng: cùng một đơn có thể được nhập lại nhiều lần khi email bị chuyển tiếp; ERP không lưu mã sự kiện vận tải. Vì không có khóa chống trùng, một sự kiện giao hàng có thể tạo nhiều lần cập nhật.
Underlying Need	ERP cần ghi nhận giao hàng một lần duy nhất, có thời điểm, mã vận đơn và bằng chứng tham chiếu. Nhu cầu này khác “nhận JSON”: nghiệp vụ cần trạng thái đơn tin cậy để kho, CSKH và kế toán mô phỏng dùng cùng dữ liệu.
Options	O1: Nhân viên tiếp tục nhập tay từ email. O2: API nhận callback từ `NovaLogistics`, kiểm tra định danh đơn và `eventId`, rồi cập nhật trạng thái. O3: API nhận callback nhưng luôn tạo bản ghi mới, không kiểm tra trùng.
Decision Criteria	Đánh giá theo: giảm nhập tay; không cập nhật nhầm đơn; chống gửi trùng; có dấu vết kiểm tra; lỗi không làm mất sự kiện; không tự diễn giải nghĩa vụ kế toán hay pháp lý.
Decision	Khuyến nghị BA: chọn `O2`. API dùng `eventId` làm khóa idempotency, nghĩa là cùng một sự kiện gửi lại không tạo tác động nghiệp vụ lần hai. Chỉ nhận đơn đang ở `READY_TO_SHIP`; trạng thái đích là `DELIVERED`.
Authority	Quyết định kỹ thuật endpoint, xác thực và cơ chế lưu chống trùng cần Technical Architect xác nhận. Quy tắc chuyển trạng thái cần Business Owner xác nhận. Việc dùng trạng thái giao hàng cho ghi nhận kế toán cần Accounting Owner xác minh. Chưa có approval hay baseline tại `IN_REVIEW`, `v0.9.0`, ngày `2026-08-07`.
Artifact	Phân tích này tham chiếu `CANONICAL_BUSINESS_RULES`, `CANONICAL_DATA_DICTIONARY`, `TRACEABILITY_ID_REGISTRY`; artifact nguồn đều `IN_REVIEW`. API contract đề xuất được ghi trong `/02-handbook/12-api-and-integration-analysis.md`, không thay thế OpenAPI triển khai hay cấu hình production.
Consequence if Wrong	Nếu không chống trùng, một lần giao hàng có thể bị xử lý nhiều lần. Nếu cho phép `READY_TO_SHIP` chuyển thẳng sang `DELIVERED` mà không kiểm tra đơn, dữ liệu đơn khác có thể bị cập nhật sai. Nếu coi callback là bằng chứng kế toán, hệ thống có thể dùng dữ liệu vận hành chưa được Accounting Owner xác minh.

12-api-and-integration-analysis — diagram 20

Source mermaid — có thể chỉnh sửa

flowchart TB
    NL["NovaLogistics mô phỏng<br/>Gửi callback giao hàng"]
    API["ERP Delivery API<br/>Nhận eventId, eventType, occurredAt,<br/>salesOrderId, trackingNumber, proofReference"]
    TYPE{"eventType là<br/>DELIVERY_COMPLETED?"}
    CHECK["Nova Foods ERP mô phỏng<br/>Kiểm tra eventId, salesOrderId<br/>và trạng thái đơn"]
    RESULT{"Kết quả kiểm tra"}

    NL --> API
    API --> TYPE
    TYPE -->|"Có"| CHECK
    TYPE -->|"Không"| TYPE_SCOPE["Contract chưa xác định:<br/>mã phản hồi HTTP và xử lý vận hành<br/>chờ Technical Architect xác nhận"]
    CHECK --> RESULT

    RESULT -->|"eventId đã tồn tại"| DUP["API trả 200 OK<br/>Không đổi trạng thái<br/>Không tạo bản ghi giao hàng mới"]

    RESULT -->|"salesOrderId không tồn tại"| NOT_FOUND["Lưu lỗi kỹ thuật<br/>để xử lý vận hành"]
    NOT_FOUND --> ERR_ORDER["API trả 422 Unprocessable Content"]

    RESULT -->|"Đơn không ở READY_TO_SHIP"| WRONG_STATE["Không cập nhật trạng thái"]
    WRONG_STATE --> ERR_STATE["API trả 422 Unprocessable Content"]

    RESULT -->|"Sự kiện mới, đơn READY_TO_SHIP"| ATOMIC["Yêu cầu nguyên tử:<br/>lưu đủ dữ liệu và cập nhật DELIVERED,<br/>không cập nhật dở dang,<br/>không mất khả năng retry"]
    ATOMIC --> PROCESS{"Xử lý thành công?"}

    PROCESS -->|"Có"| ACCEPT["API trả 202 Accepted"]
    PROCESS -->|"Không"| SERVER_ERROR["Phản hồi lớp 5xx, nơi lưu bền<br/>và trách nhiệm retry<br/>chờ Technical Architect xác nhận"]

    TECH["Technical Architect xác nhận:<br/>endpoint và xác thực;<br/>response code;<br/>cơ chế lưu chống trùng;<br/>cơ chế nguyên tử, persistence và retry"]
    OWNER["Business Owner xác nhận quy tắc<br/>READY_TO_SHIP sang DELIVERED"]
    ACCOUNTING["Callback là dữ liệu vận hành<br/>Không phải bằng chứng ghi nhận kế toán<br/>khi chưa được Accounting Owner xác minh"]

    TECH -.-> API
    TECH -.-> TYPE_SCOPE
    TECH -.-> CHECK
    TECH -.-> ATOMIC
    TECH -.-> ACCEPT
    TECH -.-> SERVER_ERROR
    OWNER -.-> ATOMIC
    ACCOUNTING -.-> ACCEPT

Payload đề xuất, dữ liệu tổng hợp:

{
  "eventId": "DLE-NF-20260807-0001",
  "eventType": "DELIVERY_COMPLETED",
  "occurredAt": "2026-08-07T14:35:00+07:00",
  "salesOrderId": "SO-NF-20260807-001",
  "trackingNumber": "NL-260807-0001",
  "proofReference": "POD-NF-20260807-0001"
}

Quy tắc đề xuất	Điều kiện	Kết quả
`BR-API-DEL-001`	`eventId` đã được xử lý	Trả `200 OK`; không đổi trạng thái, không tạo bản ghi giao hàng mới.
`BR-API-DEL-002`	`salesOrderId` không tồn tại	Trả `422 Unprocessable Content`; lưu lỗi kỹ thuật để xử lý vận hành.
`BR-API-DEL-003`	Đơn không ở `READY_TO_SHIP`	Trả `422 Unprocessable Content`; không cập nhật trạng thái.
`BR-API-DEL-004`	Sự kiện mới, đơn hợp lệ	Lưu `eventId`, `occurredAt`, `trackingNumber`, `proofReference`; đổi đơn sang `DELIVERED`.

Cầu nối quyết định: Facts cho thấy nhập tay và thiếu khóa sự kiện; Current Behavior giải thích khả năng trùng; Underlying Need xác định dữ liệu nghiệp vụ cần bảo vệ; O2 đáp ứng toàn bộ tiêu chí hơn O1 và O3. Đây là khuyến nghị phân tích, chưa là quyết định được ủy quyền.

Applied

Tình huống mô phỏng: Nova Foods Trading & Manufacturing cần đồng bộ trạng thái phiếu xuất kho từ ERP sang cổng thông tin Nhà phân phối. Dữ liệu tổng hợp, bối cảnh Việt Nam, locale vi-VN, múi giờ Asia/Ho_Chi_Minh, tiền tệ VND. Nội dung thuộc trạng thái IN_REVIEW, phiên bản v0.9.0, ngày 2026-08-07; không phải cấu hình production, baseline hay phê duyệt.

Thành phần	ID/tên cố định	Vai trò
ERP nguồn	`NF-ERP`	Ghi nhận phiếu xuất kho đã xác nhận.
Cổng đích	`NF-DISTRIBUTOR-PORTAL`	Hiển thị trạng thái giao hàng cho Nhà phân phối.
Sự kiện tích hợp	`EVT-WH-ISSUE-CONFIRMED`	Phát sinh khi phiếu xuất kho chuyển `CONFIRMED`.
API đích	`POST /api/v1/warehouse-issues/status`	Nhận trạng thái phiếu xuất.
Định danh phiếu	`warehouseIssueId`	Khóa nghiệp vụ duy nhất trong payload.
Định danh đơn bán	`salesOrderId`	Liên kết phiếu xuất với đơn bán.
Mã Nhà phân phối	`distributorCode`	Xác định bên nhận dữ liệu.
Artifact đề xuất	`INT-SPEC-WH-001`	Đặc tả tích hợp mô phỏng cần review.
Nguồn quản trị ID	`TRACEABILITY_ID_REGISTRY`	Registry canonical; chưa có baseline.
Nguồn quy tắc	`CANONICAL_BUSINESS_RULES`	Catalog quy tắc canonical đang `IN_REVIEW`.
Nguồn dữ liệu	`CANONICAL_DATA_DICTIONARY`	Từ điển dữ liệu logic đang `IN_REVIEW`.

Quy tắc mô phỏng cần ghi trong INT-SPEC-WH-001:

Rule ID	Quy tắc đầy đủ	Bằng chứng và lý do
`BR-INT-WH-001`	`NF-ERP` chỉ gửi sự kiện khi `status` của phiếu xuất là `CONFIRMED`.	Portal chỉ cần biết hàng đã được kho xác nhận xuất; gửi trạng thái trước xác nhận tạo thông tin giao hàng không chắc chắn.
`BR-INT-WH-002`	Mỗi `warehouseIssueId` kết hợp `status` chỉ được Portal xử lý một lần.	Gọi lại HTTP có thể xảy ra khi timeout; xử lý lặp có thể tạo thông báo lặp cho Nhà phân phối.
`BR-INT-WH-003`	`confirmedAt` dùng ISO 8601 có offset `+07:00`.	Corpus dùng `Asia/Ho_Chi_Minh`; offset giữ đúng thời điểm khi hệ thống đích lưu UTC.
`BR-INT-WH-004`	`totalAmount` là số nguyên VND, không có phần thập phân.	Đơn vị tiền tệ mô phỏng của corpus là `VND`; payload tránh khác biệt làm tròn giữa hệ thống.
`BR-INT-WH-005`	API từ chối payload thiếu trường bắt buộc hoặc sai trạng thái.	Điểm vào API là ranh giới tin cậy; cần kiểm tra đầu vào trước khi Portal ghi dữ liệu.

Payload đầy đủ cho một lần gửi thành công:

{
  "eventId": "EVT-WH-ISSUE-CONFIRMED-20260807-0001",
  "eventType": "EVT-WH-ISSUE-CONFIRMED",
  "occurredAt": "2026-08-07T10:15:00+07:00",
  "warehouseIssueId": "WI-20260807-0001",
  "salesOrderId": "SO-20260806-0042",
  "distributorCode": "NFD-HCM-001",
  "status": "CONFIRMED",
  "confirmedAt": "2026-08-07T10:15:00+07:00",
  "currency": "VND",
  "totalAmount": 12500000
}

Trường payload	Kiểu	Bắt buộc	Giá trị ví dụ	Quy tắc
`eventId`	string	Có	`EVT-WH-ISSUE-CONFIRMED-20260807-0001`	Không trùng trong từng sự kiện phát sinh.
`eventType`	string	Có	`EVT-WH-ISSUE-CONFIRMED`	Phải đúng giá trị cố định.
`occurredAt`	datetime	Có	`2026-08-07T10:15:00+07:00`	ISO 8601, offset `+07:00`.
`warehouseIssueId`	string	Có	`WI-20260807-0001`	Khóa đối soát chính.
`salesOrderId`	string	Có	`SO-20260806-0042`	Phải tồn tại trong ngữ cảnh ERP mô phỏng.
`distributorCode`	string	Có	`NFD-HCM-001`	Xác định Nhà phân phối nhận trạng thái.
`status`	string	Có	`CONFIRMED`	Chỉ nhận `CONFIRMED` cho sự kiện này.
`confirmedAt`	datetime	Có	`2026-08-07T10:15:00+07:00`	Không lớn hơn `occurredAt`.
`currency`	string	Có	`VND`	Phải là `VND`.
`totalAmount`	integer	Có	`12500000`	Lớn hơn `0`.

12-api-and-integration-analysis — diagram 21

Source mermaid — có thể chỉnh sửa

sequenceDiagram
    autonumber
    participant ERP as NF-ERP
    participant API as NF-DISTRIBUTOR-PORTAL API
    participant Portal as NF-DISTRIBUTOR-PORTAL

    ERP->>ERP: Xác nhận WI-20260807-0001 (BR-INT-WH-001)

    loop Retry nếu không nhận phản hồi thành công
        ERP->>API: POST /api/v1/warehouse-issues/status (payload)

        Note over API: Xác thực API (Verification required)
        API->>API: Xác thực payload (BR-INT-WH-003, BR-INT-WH-004, BR-INT-WH-005)

        alt Payload hợp lệ
            API->>Portal: Yêu cầu lưu trạng thái CONFIRMED
            Portal->>Portal: Kiểm tra trùng lặp WI+status (BR-INT-WH-002)
            alt Chưa xử lý WI+status
                Portal->>Portal: Lưu trạng thái CONFIRMED
                Portal-->>API: Phản hồi: Đã ghi nhận
            else Đã xử lý WI+status
                Portal-->>API: Phản hồi: Đã ghi nhận (bỏ qua xử lý)
            end
            API-->>ERP: Phản hồi: Xử lý thành công
        else Payload không hợp lệ
            API-->>ERP: Phản hồi: Lỗi xác thực payload
        end
    end

Phương án	Mô tả	Đánh giá theo tiêu chí
`OPT-INT-WH-001`	Portal truy vấn ERP theo lịch mỗi 15 phút.	Dễ triển khai nhưng trạng thái chậm tối đa 15 phút và tạo truy vấn lặp.
`OPT-INT-WH-002`	ERP gửi API khi xác nhận phiếu xuất.	Gần thời gian thực, ít truy vấn thừa, cần kiểm soát gọi lại và xác thực API.

Tiêu chí quyết định	`OPT-INT-WH-001`	`OPT-INT-WH-002`
Portal nhận trạng thái trong 5 phút	Không đảm bảo	Đáp ứng nếu API hoạt động
Tránh dữ liệu trùng	Cần cơ chế đối soát	Có `eventId` và `warehouseIssueId`
Tải lên ERP	Truy vấn định kỳ	Chỉ phát sinh khi có xác nhận
Khả năng xử lý lỗi mạng	Lần sau sẽ truy vấn lại	Cần retry có kiểm soát

Khuyến nghị BA: chọn OPT-INT-WH-002, vì bằng chứng tiêu chí cho thấy sự kiện chỉ phát sinh khi trạng thái đã CONFIRMED, giảm độ trễ và truy vấn không cần thiết. Đây chưa là quyết định được ủy quyền.

Trạng thái thẩm quyền:

Nội dung	Trạng thái	Vai trò có thẩm quyền cần xác nhận
Chọn `OPT-INT-WH-002`	Khuyến nghị trong `INT-SPEC-WH-001`	Business Owner và Solution Architect
Cấu trúc endpoint, xác thực, retry	Verification required	Solution Architect và Security Owner
Giá trị nghiệp vụ của `CONFIRMED`	Verification required	Warehouse Process Owner
Lưu, hiển thị dữ liệu Nhà phân phối	Verification required	Privacy/Compliance Owner nếu có dữ liệu cá nhân
Quy tắc `BR-INT-WH-001` đến `BR-INT-WH-005`	`IN_REVIEW`	Business Owner, Architect, QA Owner

Consequence if Wrong: nếu Portal nhận phiếu chưa xác nhận, Nhà phân phối có thể thấy hàng “đã xuất” khi kho chưa hoàn tất. Nếu không chống xử lý lặp, một lần retry có thể tạo nhiều thông báo cho cùng WI-20260807-0001. Nếu sai +07:00, Portal có thể hiển thị sai giờ xác nhận. Artifact INT-SPEC-WH-001 phải giữ traceability đến TRACEABILITY_ID_REGISTRY, CANONICAL_BUSINESS_RULES và CANONICAL_DATA_DICTIONARY; các artifact này đều IN_REVIEW, chưa là nguồn phê duyệt.

Core

Phân tích API và tích hợp phụ thuộc vào nguồn chân lý (canonical source of truth): artifact được chỉ định giữ nội dung gốc. Chapter này chỉ liên kết đến nguồn gốc, không chép lại rule, định nghĩa trường dữ liệu, ID hay cấu trúc API. Cách này ngăn hai bản cùng mang danh “đúng” nhưng lệch nhau sau một lần sửa.

Nova Foods Trading & Manufacturing là case mô phỏng giáo dục, chỉ dùng dữ liệu tổng hợp. Mọi artifact dưới đây có trạng thái IN_REVIEW, phiên bản v0.9.0, ngày 2026-08-07, chưa là baseline hay phê duyệt.

Hướng	Concept hoặc artifact phụ thuộc	Nguồn canonical	Chapter này dùng để làm gì	Không được chép lại
Upstream	Cấu trúc chapter handbook	`/01-curriculum/CHAPTER_MANIFEST.md` (`CHAPTER_MANIFEST`)	Xác định chapter API thuộc corpus và giữ đúng filename	Danh mục chapter gốc
Upstream	ID traceability	`/01-curriculum/TRACEABILITY_ID_REGISTRY.md` (`TRACEABILITY_ID_REGISTRY`)	Kiểm tra ID như `INT-SPEC-WH-001`, `BR-INT-WH-001` hợp lệ và duy nhất	Danh sách cấp phát ID
Upstream	Business rule	`/01-curriculum/CANONICAL_BUSINESS_RULES.md` (`CANONICAL_BUSINESS_RULES`)	Liên kết rule điều khiển hành vi tích hợp	Nội dung rule canonical
Upstream	Data definition	`/01-curriculum/CANONICAL_DATA_DICTIONARY.md` (`CANONICAL_DATA_DICTIONARY`)	Liên kết nghĩa, kiểu, phân loại dữ liệu của payload	Định nghĩa field canonical
Upstream	API description	`INT-SPEC-WH-001`	Dùng endpoint, event, payload và lỗi đã được đặc tả	Bản sao OpenAPI hay API contract
Downstream	Requirement, acceptance criteria, test	Các artifact chapter requirement và testing tương ứng	Cung cấp liên kết đến API behavior đã phân tích	Rule hay field mới tự suy diễn
Downstream	Template	`/01-curriculum/TEMPLATE_MANIFEST.md` (`TEMPLATE_MANIFEST`)	Xác định template được phép dùng cho integration analysis	Tạo template ID mới ngoài manifest

ID bền vững là mã không đổi khi tên hiển thị thay đổi. Ví dụ INT-SPEC-WH-001 vẫn giữ nguyên nếu tiêu đề đổi từ “Warehouse Issue Notification” sang bản dịch tiếng Việt. Bằng chứng: tên hiển thị phục vụ người đọc, còn ID phục vụ liên kết máy đọc, review và kiểm tra chéo. Không tái dùng ID đã gắn một nghĩa khác.

12-api-and-integration-analysis — diagram 22

Source mermaid — có thể chỉnh sửa

flowchart TB
    STATUS["Trạng thái chung<br/>IN_REVIEW · v0.9.0 · 2026-08-07<br/>chưa baseline / chưa phê duyệt"]

    CM["CHAPTER_MANIFEST<br/>cấu trúc chapter"]
    TR["TRACEABILITY_ID_REGISTRY<br/>ID duy nhất"]
    BR["CANONICAL_BUSINESS_RULES<br/>quy tắc gốc"]
    DD["CANONICAL_DATA_DICTIONARY<br/>nghĩa dữ liệu gốc"]
    API["INT-SPEC-WH-001<br/>API contract"]
    TM["TEMPLATE_MANIFEST<br/>template được phép"]

    CH["/02-handbook/12-api-and-integration-analysis.md"]
    OUT["Artifact downstream<br/>requirement, AC, test"]

    STATUS -.-> CH
    CM -->|liên kết, không sao chép| CH
    TR -->|kiểm tra ID| CH
    BR -->|liên kết rule điều khiển behavior| CH
    DD -->|liên kết nghĩa, kiểu, phân loại payload| CH
    API -->|dùng endpoint, event, payload, lỗi| CH
    TM -->|xác định template được phép| CH
    CH -->|liên kết API behavior| OUT

Applied

Facts: INT-SPEC-WH-001 mô tả tích hợp mô phỏng gửi thông báo phiếu xuất kho đã CONFIRMED. Ví dụ dữ liệu tổng hợp dùng warehouseIssueId là WI-20260807-0001 và thời điểm có offset +07:00.

Current Behavior: chapter API tham chiếu BR-INT-WH-001 đến BR-INT-WH-005 và CANONICAL_DATA_DICTIONARY; chapter không tự ghi lại điều kiện CONFIRMED, nghĩa của eventId, hay kiểu dữ liệu thời gian.

Underlying Need: người đọc cần lần ngược từ API contract đến rule và data definition. Nếu chỉ có mô tả trong handbook, reviewer không biết bản nào kiểm soát khi hai mô tả khác nhau.

Options:

Option	Cách làm	Rủi ro
`OPT-DEP-001`	Chép rule và field vào mọi chapter liên quan	Drift khi nguồn gốc đổi
`OPT-DEP-002`	Ghi ID, đường dẫn canonical, phiên bản và mục đích liên kết	Cần mở nguồn gốc khi cần chi tiết
`OPT-DEP-003`	Chỉ ghi tên tài liệu không có ID	Không kiểm tra được đúng artifact

Decision Criteria: liên kết phải truy được artifact gốc; ID phải giữ nguyên; không tạo nguồn chân lý thứ hai; người review phải thấy giới hạn thẩm quyền; thay đổi phải xác định được nơi bị ảnh hưởng.

Decision: dùng OPT-DEP-002. Chapter này ghi INT-SPEC-WH-001, BR-INT-WH-001 đến BR-INT-WH-005, TRACEABILITY_ID_REGISTRY, CANONICAL_BUSINESS_RULES, CANONICAL_DATA_DICTIONARY và đường dẫn canonical tương ứng. Nội dung chi tiết vẫn nằm tại artifact sở hữu nội dung đó.

Authority: Principal IT Business Analyst / Technical Curriculum Author duy trì liên kết, metadata và tính nhất quán. Business Owner, Solution Architect, Security Owner, QA Owner, Warehouse Process Owner chỉ xác nhận nội dung trong phạm vi thẩm quyền của họ. Không có xác nhận nào được ghi nhận trong micro-batch này.

Artifact: /02-handbook/12-api-and-integration-analysis.md, section 09-dependencies, liên kết với INT-SPEC-WH-001 và registry/canonical catalog nêu trên.

Consequence if Wrong: nếu một chapter tự đổi CONFIRMED thành POSTED nhưng CANONICAL_BUSINESS_RULES không đổi, API consumer có thể gọi hoặc hiển thị sai trạng thái. Nếu đổi eventId trong data dictionary nhưng không rà INT-SPEC-WH-001, cơ chế chống xử lý lặp có thể hỏng. Nếu đổi filename hoặc ID không kiểm soát, traceability đứt dù nội dung nhìn vẫn hợp lý.

Senior Lens

Dependency không phải danh sách link. Dependency là quan hệ mà thay đổi ở nguồn A có thể làm artifact B sai, mơ hồ hoặc không kiểm tra được. BA phải ghi quan hệ ở mức đủ để reviewer trả lời ba câu: nguồn gốc nào sở hữu sự thật, artifact nào tiêu thụ sự thật, và thay đổi nào bắt buộc phải rà soát.

Không suy diễn rằng registry, catalog hay manifest xác nhận tính đúng nghiệp vụ. Bằng chứng từ metadata của các artifact này: chúng đều là planning artifact IN_REVIEW; Owner chỉ duy trì quản trị, không thay Business Owner, Architect, Legal, Accounting, Security hay QA quyết định nội dung.

Quick Reference

Quy tắc	Áp dụng
Một fact có một nguồn canonical	Rule ở `CANONICAL_BUSINESS_RULES`; data definition ở `CANONICAL_DATA_DICTIONARY`; ID ở `TRACEABILITY_ID_REGISTRY`
Liên kết bằng ID và path	Ghi `INT-SPEC-WH-001` cùng artifact/path sở hữu khi cần
Không copy để “tiện đọc”	Tóm tắt mục đích được; không tạo bản rule, schema hay API contract thứ hai
Giữ ID khi đổi tên	Đổi title không đổi ID, trừ khi registry kiểm soát thay thế
Rà khi dependency đổi	Rà API contract, handbook consumer, requirement, acceptance criteria và test artifact liên quan
Giữ nhãn thẩm quyền	`IN_REVIEW` không phải baseline, approval hay production-ready

Core

Ma trận truy vết (traceability matrix) nối nhu cầu với yêu cầu, quy tắc, tiêu chí chấp nhận, dữ liệu/API và kiểm thử. Mỗi liên kết dùng ID đã đăng ký; không tạo lại nội dung canonical trong handbook. Nova Foods Trading & Manufacturing là case mô phỏng, dữ liệu tổng hợp, trạng thái corpus IN_REVIEW, phiên bản v0.9.0, ngày 2026-08-07.

Loại liên kết	Ý nghĩa từ gốc	Nguồn canonical phải tham chiếu	Điều không được làm
`NEED`	Nhu cầu giải quyết vấn đề hoặc đạt kết quả nghiệp vụ	Requirement artifact đã đăng ký trong `/01-curriculum/TRACEABILITY_ID_REGISTRY.md`	Đổi nhu cầu thành yêu cầu kỹ thuật khi chưa có quyết định
`REQ`	Yêu cầu có thể kiểm tra, mô tả hệ thống phải làm gì	Requirement artifact và registry ID	Chép nhiều bản yêu cầu vào API specification
`BR`	Business Rule, quy tắc nghiệp vụ, giới hạn quyết định	`CANONICAL_BUSINESS_RULES` tại `/01-curriculum/CANONICAL_BUSINESS_RULES.md`	Nhét quy tắc vào code, payload hoặc test mà không giữ nguồn canonical
`AC`	Acceptance Criteria, điều kiện chấp nhận kết quả yêu cầu	Requirement/acceptance artifact đã đăng ký	Gọi ví dụ API là AC nếu chưa nêu điều kiện kiểm tra
`DATA/API`	Hợp đồng dữ liệu hoặc giao diện lập trình giữa hệ thống	`CANONICAL_DATA_DICTIONARY` và API artifact đã đăng ký	Tự cấp tên field, endpoint, schema ID trong handbook
`TC`	Test Case, ca kiểm thử xác minh yêu cầu hoặc quy tắc	Test artifact và registry ID	Suy diễn expected result khi BR hoặc AC chưa rõ

Applied

Facts: Corpus chỉ xác nhận các artifact canonical TRACEABILITY_ID_REGISTRY, CANONICAL_BUSINESS_RULES, CANONICAL_DATA_DICTIONARY; seed không cấp NEED, REQ, BR, AC, DATA/API hoặc TC cụ thể cho luồng ERP Nova Foods.

Current Behavior: BA có thể mô tả chuỗi liên kết, nhưng không có quyền tự phát hành ID nghiệp vụ, ID API hay ID kiểm thử.

Underlying Need: Đủ liên kết để reviewer phát hiện yêu cầu không có nhu cầu gốc, API không có dữ liệu định nghĩa, hoặc test không chứng minh AC.

Options: (1) tự tạo ID ví dụ; (2) dùng tên tự do; (3) tham chiếu registry và ghi trạng thái chưa đăng ký.

Decision Criteria: Giữ nguồn chân lý duy nhất, không bịa ID, không ngụ ý baseline hay approval, vẫn cho phép kiểm tra khoảng trống.

Decision: Chọn phương án (3).

Authority: Principal IT Business Analyst / Technical Curriculum Author duy trì truy vết; Business Owner, Architect, QA Owner xác nhận nội dung thuộc thẩm quyền tương ứng. Không có approval được ghi nhận.

Artifact: Bảng dưới là mẫu liên kết cho case mô phỏng; các ô “chưa đăng ký” là phát hiện governance, không phải ID.

Consequence if Wrong: ID tự tạo có thể khiến QA test nhầm requirement, Architect xây API sai schema, hoặc Business Owner tin rule chưa xác nhận là quyết định Nova Foods.

Chuỗi truy vết cần kiểm tra	ID/nguồn hiện có	Trạng thái tại `v0.9.0`	Bằng chứng và hành động
`NEED` → `REQ`	Không có ID `NEED` hoặc `REQ` được seed cấp	Chưa đăng ký	Không lập liên kết giả. Đăng ký trước tại `TRACEABILITY_ID_REGISTRY`.
`REQ` → `BR`	`CANONICAL_BUSINESS_RULES`	Catalog canonical tồn tại; rule cụ thể chưa được seed cấp	Liên kết chỉ sau khi BR có ID registry và owner phù hợp xác nhận nội dung.
`REQ` → `AC`	Không có ID `AC` được seed cấp	Chưa đăng ký	AC phải kiểm tra được; không dùng mô tả endpoint thay AC.
`REQ` → `DATA/API`	`CANONICAL_DATA_DICTIONARY`	Dictionary canonical tồn tại; API contract cụ thể chưa được seed cấp	Data field, schema, endpoint phải tham chiếu artifact canonical khi được đăng ký.
`AC` → `TC`	Không có ID `TC` được seed cấp	Chưa đăng ký	QA tạo TC từ AC và BR; không tạo expected result từ giả định BA.
`DATA/API` → `TC`	Không có API ID, schema ID, TC ID được seed cấp	Chưa đăng ký	Test tích hợp phải chứng minh request, response, lỗi và bảo vệ dữ liệu theo contract đã đăng ký.

12-api-and-integration-analysis — diagram 23

Source mermaid — có thể chỉnh sửa

flowchart TB
    subgraph S["Bằng chứng canonical tại v0.9.0"]
        BC["CANONICAL_BUSINESS_RULES<br/>Catalog canonical tồn tại"]
        DC["CANONICAL_DATA_DICTIONARY<br/>Dictionary canonical tồn tại"]
        X["TRACEABILITY_ID_REGISTRY<br/>Nơi phải đăng ký ID trước khi liên kết"]
    end

    subgraph C["Chuỗi cần kiểm tra — liên kết chưa được thiết lập"]
        direction TB
        N["NEED<br/>Chưa có ID được seed cấp"] -.-> R["REQ<br/>Chưa có ID được seed cấp"]
        R -.-> B["BR cụ thể<br/>Chưa có ID được seed cấp"]
        R -.-> A["AC<br/>Chưa có ID được seed cấp"]
        R -.-> D["DATA/API cụ thể<br/>Chưa có API ID, schema ID hoặc endpoint được seed cấp"]
        B -.-> A
        A -.-> T["TC<br/>Chưa có ID được seed cấp"]
        D -.-> T
    end

    BC -. "không chứng minh BR cụ thể đã đăng ký" .-> B
    DC -. "không chứng minh API contract cụ thể đã đăng ký" .-> D

    L["Liên kết ứng viên trong chuỗi"] --> I{"Mỗi artifact đã có ID trong<br/>TRACEABILITY_ID_REGISTRY?"}
    X --> I
    I -- "Có" --> O{"Nội dung đã được owner phù hợp xác nhận?"}
    I -- "Không" --> W["Dừng lập liên kết; ghi nhận khoảng trống governance<br/>Không lập liên kết giả, giảm nguy cơ liên kết sai"]
    O -- "Có" --> E["Lập và duy trì liên kết truy vết"]
    O -- "Không" --> W
    E -. "áp dụng cho chuỗi" .-> N

    I -. "nếu vẫn tự tạo ID hoặc lập liên kết" .-> F["Vi phạm điều kiện truy vết"]
    O -. "nếu vẫn lập liên kết" .-> F
    F --> K["Nguy cơ: QA test nhầm requirement;<br/>Architect xây API sai schema;<br/>Business Owner tin rule chưa xác nhận"]

    subgraph H["Ranh giới thẩm quyền"]
        BA["Principal IT Business Analyst / Technical Curriculum Author<br/>Duy trì truy vết"]
        OWN["Business Owner, Architect, QA Owner<br/>Xác nhận nội dung thuộc thẩm quyền tương ứng"]
        P["Không có approval được ghi nhận"]
    end

    BA -. "duy trì" .-> E
    OWN -. "cung cấp xác nhận" .-> O
    P -. "trạng thái chung; không thay thế xác nhận" .-> O

Senior Lens

Liên kết không chứng minh nội dung đúng; liên kết chỉ chứng minh nguồn, phạm vi và đường kiểm tra. Suy luận: REQ cần AC vì yêu cầu không có điều kiện quan sát được thì QA không thể kết luận đạt; AC cần TC vì điều kiện không có ca kiểm thử thì chưa có bằng chứng thực thi; DATA/API cần data dictionary vì payload không định nghĩa field thì bên gửi và nhận có thể hiểu khác nhau.

Rule kiểm tra tối thiểu: mỗi TC phải truy ngược ít nhất một AC; mỗi AC phải truy ngược REQ; mỗi BR ảnh hưởng hành vi phải liên kết REQ hoặc AC; mỗi field API phải có định nghĩa trong CANONICAL_DATA_DICTIONARY. Liên kết nhiều-nhiều hợp lệ, nhưng mỗi liên kết phải ghi lý do tác động thay vì chỉ ghi danh sách ID.

Quick Reference

Kiểm tra	Đạt khi	Không đạt khi
ID bền vững	ID khớp `TRACEABILITY_ID_REGISTRY`	ID tự đặt trong chapter, bảng API hoặc test
Nguồn BR	Chỉ tham chiếu `CANONICAL_BUSINESS_RULES`	Sao chép hoặc sửa câu rule ở artifact phụ
Nguồn dữ liệu	Field tham chiếu `CANONICAL_DATA_DICTIONARY`	API tự định nghĩa khác kiểu dữ liệu hoặc ý nghĩa field
Test basis	`TC` nối tới `AC`, `REQ`, và `BR` khi áp dụng	TC chỉ kiểm tra endpoint thành công
Trạng thái quản trị	Ghi `IN_REVIEW`, `v0.9.0`, `2026-08-07`	Diễn giải artifact là baseline, approved hoặc production-ready

Core

Lan truyền thay đổi là chuỗi tác động khi một dependency, tức thành phần mà artifact khác phụ thuộc, đổi ý nghĩa, cấu trúc hoặc hành vi. Với Nova Foods Trading & Manufacturing mô phỏng, dữ liệu đều tổng hợp. Một thay đổi chỉ an toàn khi nguồn canonical ghi nhận thay đổi, artifact phụ thuộc được rà soát, và bằng chứng kiểm tra được cập nhật. IN_REVIEW, v0.9.0, ngày 2026-08-07 không phải baseline hay approval.

12-api-and-integration-analysis — diagram 24

Source mermaid — có thể chỉnh sửa

flowchart TB
    A[Canonical source thay đổi] --> B[Đánh giá tác động]
    B --> C[Rà soát artifact phụ thuộc]
    C --> D[Cập nhật artifact nguồn và consumer]
    D --> E[Cập nhật bằng chứng kiểm tra]
    E --> F[Ghi version, lý do, phạm vi tác động, consumer bị ảnh hưởng và timestamp theo Asia/Ho_Chi_Minh]
    F --> G[Hoàn tất ghi nhận thay đổi<br/>không tự động là baseline hoặc approval]

Thay đổi im lặng là thay đổi không ghi nhận version, lý do, phạm vi tác động hoặc consumer bị ảnh hưởng. Nó phá traceability vì người đọc vẫn tham chiếu ý nghĩa cũ, còn hệ thống hoặc tài liệu dùng ý nghĩa mới. Không suy diễn rằng thay đổi đã được phê duyệt chỉ vì artifact đã được sửa.

Applied

Mục	Nội dung
Facts	`/01-curriculum/CANONICAL_DATA_DICTIONARY.md` đổi định nghĩa logic của trường mã lô hàng mô phỏng.
Current Behavior	API consumer vẫn gửi định dạng cũ; test case vẫn kiểm tra định dạng cũ.
Underlying Need	Đồng bộ nghĩa dữ liệu giữa nguồn canonical, hợp đồng API và kiểm tra.
Options	Giữ tương thích định dạng cũ; hoặc đổi consumer cùng lúc với nguồn canonical.
Decision Criteria	Có consumer nào nhận dữ liệu cũ; thay đổi có mất dữ liệu hay sai truy xuất lô; Architect và QA có cần đánh giá.
Decision	Không cho phép đổi im lặng. Ghi tác động, xác định consumer, cập nhật kiểm tra trước khi dùng nghĩa mới.
Authority	Principal IT Business Analyst / Technical Curriculum Author duy trì traceability; Architect quyết định tương thích API; QA xác nhận bằng chứng kiểm tra.
Artifact	`/01-curriculum/CANONICAL_DATA_DICTIONARY.md`, `/01-curriculum/TRACEABILITY_ID_REGISTRY.md`, `/02-handbook/12-api-and-integration-analysis.md`.
Consequence if Wrong	API có thể từ chối dữ liệu, ghi nhầm lô, hoặc làm chuỗi truy xuất thực phẩm mô phỏng không nhất quán. Đây là rủi ro học liệu; không phải kết luận tuân thủ thực tế.

Lý do phải rà soát cả chuỗi: từ điển dữ liệu là nguồn định nghĩa, API diễn đạt dữ liệu trao đổi, test case kiểm chứng hành vi. Nếu chỉ sửa API, consumer vẫn hiểu dữ liệu theo định nghĩa cũ; nếu chỉ sửa test, kiểm tra có thể xác nhận sai hành vi.

Senior Lens

Phân biệt thay đổi cú pháp và ngữ nghĩa. Đổi tên trường có thể là cú pháp, nhưng vẫn gây lỗi tích hợp nếu consumer đọc đúng tên cũ. Đổi “mã lô” từ một lô sản xuất sang một lô giao hàng là ngữ nghĩa; payload vẫn hợp lệ nhưng nghiệp vụ và truy xuất có thể sai. Nguy hiểm lớn hơn nằm ở thay đổi ngữ nghĩa vì kiểm tra kỹ thuật đơn thuần có thể không phát hiện.

Không sao chép định nghĩa vào chapter để “đồng bộ”. Chapter chỉ nêu tác động và trỏ về /01-curriculum/CANONICAL_DATA_DICTIONARY.md; registry canonical tại /01-curriculum/TRACEABILITY_ID_REGISTRY.md giữ ID và liên kết kiểm soát. Bản sao tạo hai nguồn chân lý, rồi thay đổi một bên sẽ thành thay đổi im lặng ở bên còn lại.

Khi dependency là nguồn pháp lý, kế toán, thuế, dữ liệu cá nhân hoặc an toàn thực phẩm, mọi diễn giải mới cần nhãn Verification required và owner có thẩm quyền. Ví dụ nguồn chính thức có thể đổi trạng thái hoặc được sửa đổi; BA không được tự biến thay đổi nguồn thành rule vận hành Nova Foods.

Quick Reference

Tín hiệu	Điều bị vỡ nếu không xử lý	Hành động tối thiểu
Đổi tên hoặc kiểu dữ liệu API	Consumer lỗi parse, request bị từ chối	Rà soát contract và kiểm tra tích hợp
Đổi nghĩa trường dữ liệu	Báo cáo, quyết định nghiệp vụ, truy xuất sai	Rà soát định nghĩa canonical và scenario test
Đổi business rule	AC và test kiểm tra quy tắc cũ	Đánh giá tác động tới requirement, AC, TC
Đổi nguồn pháp lý hoặc chuẩn	Claim tuân thủ dựa trên giả định cũ	Gắn `Verification required`; escalation đúng owner
Sửa artifact không có lịch sử	Không xác định được ai dùng nghĩa nào	Ghi thay đổi, phạm vi, consumer, thời điểm `Asia/Ho_Chi_Minh`

10. Common Mistakes & Anti-patterns

Core

Anti-pattern là cách làm lặp lại tạo lỗi dự đoán được. Trong phân tích API và tích hợp, lỗi không nằm riêng ở payload JSON hay endpoint HTTP. Lỗi thường bắt đầu khi BA ghi nhận nhu cầu nhưng không biến nó thành hợp đồng tích hợp có thể kiểm tra.

Sai lầm	Red flag quan sát được	Nguyên nhân gốc	Hành động sửa
Chỉ ghi “ERP gửi đơn hàng sang kho”	Không có trigger, endpoint, dữ liệu tối thiểu, phản hồi lỗi	Nhầm mô tả nghiệp vụ với contract kỹ thuật	Ghi event, producer, consumer, request, response, lỗi, retry và owner
Gọi API “real-time” nhưng không định nghĩa thời gian	Tài liệu dùng “ngay”, “nhanh”, “kịp thời”	Không có tiêu chí đo được	Ghi SLA hoặc project assumption có đơn vị đo, ví dụ phản hồi dưới 5 giây
Không mô tả idempotency	Consumer có thể nhận cùng `orderId` nhiều lần nhưng chưa rõ xử lý	Chỉ xét luồng thành công một lần	Xác định khóa chống trùng, hành vi gửi lại và trạng thái kết quả
Dùng dữ liệu hiển thị làm khóa tích hợp	Payload dùng tên khách hàng hoặc mã hiển thị có thể đổi	Không phân biệt identifier ổn định với label	Dùng ID canonical đã đăng ký; đối chiếu `/01-curriculum/TRACEABILITY_ID_REGISTRY.md`
Bỏ qua luồng lỗi	Chỉ có HTTP 200 trong ví dụ	Delivery team tối ưu demo happy path	Liệt kê lỗi xác thực, dữ liệu sai, timeout, trùng lặp và hành vi phục hồi
Ghi “hệ thống tự đồng bộ”	Không rõ ai gọi ai, lúc nào, dữ liệu nào là nguồn chân lý	Không phân rã ownership dữ liệu	Chỉ rõ producer, consumer, trigger, hệ thống ghi chính và trạng thái đồng bộ
Để developer tự suy diễn business rule	Rule nằm trong ticket kỹ thuật, không có nguồn nghiệp vụ	BA chuyển giao câu mơ hồ	Tách rule, điều kiện, ngoại lệ, bằng chứng nguồn và vai trò xác nhận
Đổi payload nhưng không kiểm tra consumer	Schema mới có trường bắt buộc hoặc đổi kiểu dữ liệu	Không có impact analysis	Lập danh sách consumer, kiểm tra backward compatibility, ghi kế hoạch versioning

Applied

Nova Foods là case mô phỏng giáo dục; mọi ID và dữ liệu dưới đây là tổng hợp.

Mục	Nội dung
Facts	ERP mô phỏng gửi yêu cầu tạo phiếu xuất tới WMS mô phỏng qua `POST /shipments`. Payload chứa `shipmentId`, `orderId`, `warehouseCode` và danh sách dòng hàng.
Current Behavior	Tài liệu delivery ghi: “Khi đơn bán được xác nhận, ERP gọi WMS. Nếu lỗi thì gọi lại.” Không có mã lỗi, số lần gọi lại, timeout hay khóa chống trùng.
Underlying Need	Kho cần tạo đúng một phiếu xuất cho mỗi `shipmentId`; ERP cần biết yêu cầu được nhận, bị từ chối hay đang xử lý.
Options	1. Gọi lại vô hạn khi không nhận phản hồi. 2. Gọi lại có giới hạn, dùng `shipmentId` làm khóa idempotency, ghi trạng thái chờ đối soát khi vượt giới hạn.
Decision Criteria	Không tạo phiếu xuất trùng; không mất yêu cầu khi timeout; vận hành biết bản ghi nào cần đối soát; consumer không phải đoán hành vi.
Decision	Chọn phương án 2 trong artifact phân tích: WMS trả `202 Accepted` khi nhận hợp lệ; WMS chỉ tạo một phiếu xuất cho cùng `shipmentId`; ERP dừng retry sau giới hạn được xác nhận và đánh dấu bản ghi cần đối soát. Giới hạn retry là Verification required vì chưa có quyết định vận hành mô phỏng được ghi nhận.
Authority	Business Owner xác nhận quy tắc tạo phiếu xuất; Architect xác nhận retry và idempotency; vận hành kho xác nhận quy trình đối soát. BA ghi nhận, không tự xác nhận các quyết định này.
Artifact	Contract API, sequence diagram, bảng lỗi, mapping dữ liệu và liên kết ID trong `/01-curriculum/TRACEABILITY_ID_REGISTRY.md`.
Consequence if Wrong	Retry vô hạn có thể tạo phiếu xuất trùng hoặc che mất lỗi kéo dài. Không có trạng thái đối soát khiến ERP và WMS cùng báo “thành công” hoặc “thất bại” theo hai cách khác nhau.

Cảnh báo: Timeout không chứng minh WMS chưa xử lý request. Request có thể đã tới WMS nhưng phản hồi bị mất. Không được tự gửi lại với mã phiếu mới; giữ cùng shipmentId để WMS nhận biết request lặp.

Ranh giới phục hồi an toàn: BA mô tả trạng thái “cần đối soát”, dữ liệu cần tra và owner xử lý. BA không tự xóa giao dịch, không tự đánh dấu phiếu xuất hoàn tất, không tự suy diễn tồn kho đã giảm. Các thao tác đó có thể gây mất dấu vết nghiệp vụ.

Senior Lens

Senior BA tìm red flag trước khi viết chi tiết. Câu “API hoạt động bình thường” không có giá trị kiểm tra vì thiếu điều kiện đầu vào, kết quả và bằng chứng. Câu thay thế phải chỉ ra: ai gửi, gửi cái gì, lúc nào, hệ thống nào là nguồn chân lý, lỗi nào có thể xảy ra và ai xử lý ngoại lệ.

Delivery team hay tạo contract sau khi code đã tồn tại. Dấu hiệu là Swagger hoặc OpenAPI Specification chỉ phản ánh endpoint hiện có, nhưng không giải thích rule nghiệp vụ, ownership dữ liệu hay hậu quả khi retry. OpenAPI Specification là đặc tả mô tả HTTP API; nó không tự xác nhận quy tắc Nova Foods đúng hay đã được phê duyệt.

Không dùng sơ đồ hoạt động PlantUML hoặc Mermaid rồi gọi là BPMN. Mermaid ở trên là sequence diagram mô tả trao đổi thông điệp, không phải BPMN. Nếu artifact yêu cầu BPMN chuẩn, dùng ký pháp BPMN 2.0.2 theo OMG và ghi rõ loại sơ đồ.

Quick Reference

Kiểm tra trước handoff	Đạt khi
Trigger	Có event hoặc điều kiện bắt đầu cụ thể
Ownership	Có producer, consumer và nguồn chân lý dữ liệu
Contract	Có request, response, mã lỗi và validation
Retry	Có timeout, retry boundary, idempotency và đối soát
Dữ liệu	ID ổn định, định nghĩa trường và mapping có liên kết canonical
Khả năng kiểm tra	QA có thể tạo test cho thành công, lỗi, trùng lặp và timeout
Thẩm quyền	Quyết định nghiệp vụ, kiến trúc, bảo mật hoặc pháp lý được gắn đúng owner; chưa có xác nhận thì giữ `Verification required`

Core

Cảnh báo chỉ dùng khi lỗi có thể gây mất dữ liệu, tạo giao dịch sai, lộ dữ liệu, hoặc làm hệ thống không thể khôi phục an toàn. Cảnh báo không dùng cho khác biệt trình bày, câu chữ chưa đẹp, hoặc ý kiến chưa được chọn. Trong tích hợp API, lỗi nguy hiểm thường nằm ở trạng thái giao dịch: bên gửi đã ghi nhận thành công nhưng bên nhận chưa xử lý, hoặc bên nhận đã xử lý nhưng phản hồi bị mất.

Cảnh báo — rủi ro dữ liệu kép: Không tự gửi lại yêu cầu tạo chứng từ khi chưa kiểm tra idempotency key hoặc mã giao dịch nguồn. Gửi lại có thể tạo hai đơn bán hàng, hai phiếu nhập, hoặc hai dòng công nợ.

12-api-and-integration-analysis — diagram 26

Source mermaid — có thể chỉnh sửa

sequenceDiagram
    autonumber
    participant Sender as Bên gửi
    participant Receiver as Bên nhận
    Sender->>Receiver: POST tạo với sourceTransactionId và idempotency key
    Note over Sender: Không nhận được phản hồi
    Sender->>Receiver: GET trạng thái bằng sourceTransactionId
    alt Bên nhận xác nhận đã xử lý
        Receiver-->>Sender: Đã xử lý
        Sender->>Sender: Đối soát, không gửi lại
    else Bên nhận xác nhận chưa xử lý
        Receiver-->>Sender: Chưa xử lý
        Sender->>Receiver: Gửi lại với cùng idempotency key
    else GET timeout, thất bại hoặc trạng thái không xác định
        Receiver-->>Sender: Không xác định
        Sender->>Sender: Không gửi lại, chuyển đối soát thủ công
    end
    Note over Sender,Receiver: Gửi lại sai có thể tạo chứng từ hoặc giao dịch trùng

Applied

Trường	Nội dung
Facts	Nova Foods Trading & Manufacturing là case mô phỏng giáo dục; dữ liệu tổng hợp. ERP gửi thông tin lô giao hàng `SYN-SHP-20260807-001` sang Partner API. Sau 30 giây, ERP nhận timeout.
Current Behavior	Nhóm giao hàng đề xuất bấm gửi lại ngay vì chưa thấy phản hồi thành công.
Underlying Need	Xác định Partner API đã tạo giao dịch hay chưa trước khi retry. Timeout chứng minh không nhận được phản hồi, không chứng minh Partner chưa xử lý.
Options	1. Gửi lại ngay với mã mới. 2. Tra cứu trạng thái bằng mã nguồn ổn định. 3. Chờ xử lý thủ công không giới hạn thời gian.
Decision Criteria	Không tạo dữ liệu kép; giữ được đối soát; có bằng chứng trạng thái; thời gian phục hồi hữu hạn.
Decision	Dùng `sourceTransactionId` ổn định và `idempotency key`; tra cứu trạng thái trước retry. Chỉ retry khi Partner xác nhận không tìm thấy giao dịch.
Authority	Business Owner xác nhận tác động nghiệp vụ của giao dịch kép. Architect xác nhận cơ chế idempotency và endpoint tra cứu. QA xác nhận kịch bản timeout, retry, đối soát. Không có approval hay baseline được suy ra từ `/01-curriculum/TRACEABILITY_ID_REGISTRY.md`, đang `IN_REVIEW`, `v0.9.0`.
Artifact	Ghi quyết định và bằng chứng liên kết trong `/01-curriculum/TRACEABILITY_ID_REGISTRY.md`; dữ liệu trường phải đối chiếu `/01-curriculum/CANONICAL_DATA_DICTIONARY.md`.
Consequence if Wrong	Có thể xuất trùng hàng mô phỏng, ghi nhận sai tồn kho hoặc công nợ, rồi phải điều chỉnh bằng chứng từ đảo.

Cảnh báo — rủi ro khôi phục sai: Không xóa, sửa trực tiếp, hoặc tạo bản ghi bù trừ tự động khi chưa xác định hệ thống nào là nguồn dữ liệu gốc cho giao dịch lỗi. Hành động này có thể phá dấu vết đối soát.

Ranh giới phục hồi an toàn: dừng retry tự động khi vượt số lần đã được Architect xác nhận; giữ nguyên payload, thời điểm Asia/Ho_Chi_Minh, mã giao dịch nguồn và phản hồi lỗi; đối soát trạng thái hai hệ thống; chỉ tạo giao dịch đảo hoặc điều chỉnh sau quyết định của Business Owner và vai trò chuyên môn liên quan. Nếu dữ liệu có thể là dữ liệu cá nhân, phải chuyển Legal/Compliance Owner xác minh theo nguồn pháp lý hiện hành; handbook không tự kết luận nghĩa vụ pháp lý.

Senior Lens

Lỗi timeout cần được ghi là sự kiện kỹ thuật, không phải kết luận nghiệp vụ. Bằng chứng cần có: request ID, sourceTransactionId, idempotency key, HTTP status hoặc lỗi mạng, thời điểm gửi, kết quả tra cứu, và quyết định phục hồi. Thiếu bất kỳ bằng chứng nào thì chỉ được gắn trạng thái cần điều tra, không được kết luận giao dịch thất bại hay thành công.

Quick Reference

Dấu hiệu	Hành động an toàn
Timeout sau `POST` tạo giao dịch	Tra cứu theo mã nguồn trước retry
Nhận lỗi `5xx`	Giữ payload và mã idempotency; retry theo chính sách đã xác nhận
Không tra cứu được trạng thái	Dừng tự động; chuyển đối soát thủ công có bằng chứng
Phát hiện giao dịch kép	Khóa retry; xác định nguồn dữ liệu gốc; chỉ điều chỉnh có thẩm quyền

Core

Trong phân tích API và tích hợp, năm lỗi khác nhau phải tách riêng vì cách sửa khác nhau. Mơ hồ là câu có nhiều cách hiểu. Thiếu hoàn chỉnh là thiếu dữ kiện để xây dựng hoặc kiểm thử. Khẳng định thẩm quyền không được hỗ trợ là gọi một quyết định là “đã phê duyệt”, “bắt buộc pháp lý” hoặc “chuẩn production” khi artifact không có bằng chứng thẩm quyền. Dùng sai ký pháp là gắn nhãn BPMN, UML, OpenAPI hoặc HTTP sai nghĩa. Đứt truy vết là không nối được nhu cầu, dữ liệu, quy tắc, API, kiểm thử và nguồn canonical.

Loại lỗi	Red flag quan sát được	Gốc lỗi	Hành động sửa
Mơ hồ	“Đồng bộ đơn hàng nhanh”, không có ngưỡng thời gian, điểm bắt đầu hoặc kết quả lỗi	Dùng ngôn ngữ nghiệp vụ thay hợp đồng kỹ thuật	Tách trigger, payload, SLA giả định, mã lỗi, retry và owner xác nhận
Thiếu hoàn chỉnh	API có `POST` nhưng không nêu trường bắt buộc, khóa chống gửi trùng, phân trang hoặc xử lý timeout	Chỉ mô tả luồng thành công	Lập bảng request, response, validation, idempotency, lỗi và dữ liệu tối thiểu
Thẩm quyền không hỗ trợ	“Theo luật phải lưu X năm” nhưng không có legal-owner verification	BA biến nguồn tham khảo thành quyết định	Gắn `Verification required`; chuyển Legal Owner hoặc Accounting Owner xác nhận
Sai ký pháp	Sơ đồ PlantUML activity được gọi là BPMN; OpenAPI được dùng như chứng cứ business approval	Nhầm công cụ biểu diễn với thẩm quyền	Đặt đúng nhãn sơ đồ; phân biệt specification, decision record và approval record
Đứt truy vết	Trường `customerCode` xuất hiện trong API nhưng không nối tới `/01-curriculum/CANONICAL_DATA_DICTIONARY.md`	Thiết kế API tách khỏi nguồn canonical	Gắn liên kết tới `CANONICAL_DATA_DICTIONARY`, `CANONICAL_BUSINESS_RULES` và `TRACEABILITY_ID_REGISTRY`; không tự tạo ID

Warning: Sai xử lý gửi trùng có thể tạo hai lệnh bán hàng hoặc hai yêu cầu xuất kho trong Nova Foods mô phỏng. Chỉ khôi phục bằng cách dừng gửi lại tự động, giữ request và response tổng hợp làm bằng chứng, rồi để Business Owner và Architect quyết định xử lý bản ghi. Không tự xóa hoặc tự đảo giao dịch.

12-api-and-integration-analysis — diagram 27

Source mermaid — có thể chỉnh sửa

flowchart TB
    N[Nhu cầu nghiệp vụ] --> BR[Quy tắc canonical]
    BR --> DD[Dữ liệu canonical]
    DD --> A[OpenAPI contract]
    A --> T[Cơ sở kiểm thử]

    N --> TR[Traceability record]
    BR --> TR
    DD --> TR
    A --> TR
    T --> TR
    ID[TRACEABILITY_ID_REGISTRY] --> TR

    A --> Q1{Request có thể được gửi lại?}
    T --> Q1

    Q1 -- Không --> NR[Không phát sinh gửi lại]
    Q1 -- Có --> Q2{Gửi lại có thể tạo hiệu ứng nghiệp vụ trùng?}

    Q2 -- Không --> ND[Không tạo hiệu ứng nghiệp vụ trùng]
    Q2 -- Có --> Q3{Khóa chống gửi trùng có tồn tại?}

    Q3 -- Không --> MK[Thiếu khóa chống gửi trùng]
    Q3 -- Có --> Q4{Khóa chống gửi trùng xử lý đúng?}

    Q4 -- Không --> WK[Khóa chống gửi trùng xử lý sai]
    Q4 -- Có --> Q5{Kiểm thử xác nhận không tạo hiệu ứng nghiệp vụ trùng?}

    Q5 -- Có --> S[Gửi lại được kiểm soát]
    Q5 -- Không --> V[Thiếu bằng chứng / Verification required]

    MK --> R[Nguy cơ hai lệnh bán hàng hoặc hai yêu cầu xuất kho]
    WK --> R
    R --> H[Dừng gửi lại tự động; giữ request và response tổng hợp làm bằng chứng]
    H --> W[Không tự xóa hoặc tự đảo giao dịch]
    W --> O[Business Owner và Architect quyết định xử lý bản ghi]

Sơ đồ trên là Mermaid flowchart, không phải BPMN hay UML. Bằng chứng là Mermaid chỉ biểu diễn quan hệ phụ thuộc; nó không xác nhận semantics BPMN 2.0.2 hoặc UML 2.5.1.

Applied

Facts: Nova Foods là case mô phỏng, dùng dữ liệu tổng hợp. Đội giao nhận đề xuất API gửi trạng thái giao hàng với trường orderNo, status, updatedAt.

Current Behavior: Bản nháp ghi: “Khi giao thành công, ERP cập nhật ngay đơn hàng.” Câu này mơ hồ vì “ngay” chưa có thời lượng; thiếu hoàn chỉnh vì không nêu trạng thái gửi lại; đứt truy vết vì orderNo chưa liên kết nguồn dữ liệu canonical.

Underlying Need: ERP cần nhận một sự kiện giao hàng duy nhất, xác định được đơn hàng, thời điểm và trạng thái, đồng thời không tạo cập nhật kép khi đối tác gửi lại do timeout.

Thành phần	Nội dung cần ghi	Lý do
Ambiguity	Định nghĩa event trigger, múi giờ `Asia/Ho_Chi_Minh`, nghĩa của từng `status`	Người xây và người test phải hiểu cùng một kết quả
Completeness	Nêu schema, trường bắt buộc, mã lỗi, timeout, retry, idempotency key, bản ghi audit	Luồng lỗi cũng là hành vi hệ thống
Authority	Ghi “project assumption” cho SLA; ghi `Verification required` cho lưu giữ dữ liệu hoặc nghĩa vụ pháp lý	BA không có quyền biến giả định thành nghĩa vụ
Notation	Dùng OpenAPI Specification OAS 3.1.1 cho HTTP contract; gắn Mermaid là flowchart	Mỗi ký pháp có phạm vi riêng
Traceability	Liên kết trường và rule tới artifact canonical, giữ nguyên ID và filename	Thay đổi sau này tìm được điểm ảnh hưởng

Options: (1) Chấp nhận câu mô tả hiện tại. (2) Bổ sung hợp đồng API nhưng tự ghi “đã Business Owner phê duyệt”. (3) Bổ sung hợp đồng API, giữ nhãn IN_REVIEW, ghi giả định và chuyển điểm thẩm quyền đúng owner.

Decision Criteria: Phương án phải cho developer xây được, QA tạo test basis được, không gán authority sai, và không tạo ID hoặc rule Nova Foods chưa có nguồn canonical.

Decision: Chọn phương án 3. Lý do: phương án 1 không test được; phương án 2 tạo claim không có bằng chứng; phương án 3 giữ được tiến độ phân tích và ranh giới thẩm quyền.

Authority: Principal IT Business Analyst / Technical Curriculum Author chỉ quản trị artifact. Không được tự xác nhận Business Owner approval, legal compliance, accounting interpretation, kiến trúc production hoặc baseline. IN_REVIEW tại v0.9.0 ngày 2026-08-07 không phải approval.

Artifact: Ghi liên kết tới /01-curriculum/CANONICAL_DATA_DICTIONARY.md, /01-curriculum/CANONICAL_BUSINESS_RULES.md và /01-curriculum/TRACEABILITY_ID_REGISTRY.md. Các artifact này là kế hoạch canonical đang IN_REVIEW; không suy diễn field definition, business rule hay ID chưa được ghi nhận.

Consequence if Wrong: Nếu gọi một flowchart là BPMN, đội vận hành có thể hiểu nhầm event, gateway và message semantics. Nếu gọi giả định lưu dữ liệu là yêu cầu pháp lý, đội delivery có thể xây cơ chế lưu trữ sai chi phí và sai thẩm quyền. Nếu mất traceability, thay đổi status không xác định được API, mapping và test nào phải sửa.

Senior Lens

Senior BA không “làm rõ” bằng cách tự chọn nghĩa thuận tiện. Senior BA biến mỗi điểm chưa rõ thành câu hỏi có owner, bằng chứng cần có và giới hạn quyết định. Ví dụ: “Trạng thái DELIVERED có cho phép cập nhật lại không?” không phải câu hỏi API thuần túy. Nó cần Business Owner xác nhận nghĩa vận hành, Architect xác nhận cơ chế idempotency, QA xác định test gửi trùng.

Nguồn chuẩn không tự tạo authority dự án. OpenAPI Specification OAS 3.1.1 mô tả HTTP API; nó không phê duyệt payload Nova Foods. BPMN 2.0.2 chuẩn hóa ký pháp BPMN; nó không xác nhận quy trình mô phỏng đúng. Luật và nghị định Việt Nam là nguồn pháp lý chính thức, nhưng mọi requirement áp dụng vào Nova Foods mô phỏng vẫn cần Legal Owner hoặc owner chuyên môn xác minh. Cầu nối suy luận là: nguồn nói phạm vi chuẩn hoặc pháp luật; owner có thẩm quyền quyết định cách áp dụng; artifact ghi bằng chứng quyết định.

Ranh giới khôi phục an toàn: có thể sửa wording, thêm nhãn project assumption, thêm Verification required, sửa tên ký pháp và phục hồi liên kết artifact. Không được tự đổi business rule, tự cấp approval, tự tuyên bố compliance, tự tạo canonical ID, hoặc xóa dữ liệu tích hợp để che lỗi.

Quick Reference

Kiểm tra trước khi bàn giao	Đạt khi
Một câu có một nghĩa kiểm thử được	Có trigger, điều kiện, dữ liệu, kết quả và lỗi
API đủ cho luồng lỗi	Có validation, timeout, retry, idempotency và response lỗi
Claim có thẩm quyền	Có artifact, owner, trạng thái và bằng chứng phù hợp
Ký pháp đúng tên	BPMN chỉ khi dùng BPMN; Mermaid flowchart không gọi BPMN
Truy vết không đứt	Nhu cầu, rule, data, contract và test basis nối được tới artifact canonical
Governance đúng	Giữ `IN_REVIEW`, `v0.9.0`, ngày `2026-08-07`; không gọi baseline hoặc approval

11. Senior BA Notes & Rules of Thumb

Senior Lens

Nova Foods Trading & Manufacturing là case mô phỏng giáo dục, chỉ dùng dữ liệu tổng hợp. Senior BA không chọn API chỉ vì đội kỹ thuật thích đồng bộ thời gian thực. Quyết định phải nối được từ nhu cầu vận hành, bằng chứng, rủi ro, tiêu chí và người có thẩm quyền. Ví dụ, đồng bộ đơn hàng tức thời giảm độ trễ tồn kho, nhưng tăng phụ thuộc vào độ sẵn sàng API nguồn; đồng bộ theo lô giảm phụ thuộc thời gian thực, nhưng tạo nguy cơ dữ liệu chậm. Cầu nối suy luận: nếu nghiệp vụ cần chặn xuất kho dựa trên tồn khả dụng tức thời thì độ trễ là rủi ro nghiệp vụ; nếu chỉ làm báo cáo ngày thì đồng bộ theo lô có thể đủ. Đây là giả định dự án cho Nova Foods, không phải rule đã phê duyệt.

12-api-and-integration-analysis — diagram 28

Source mermaid — có thể chỉnh sửa

flowchart TB
    N["Nhu cầu vận hành"] --> E["Thu thập bằng chứng<br/>payload được phép; contract có kiểm soát;<br/>log có thời điểm; canonical rule/data; quyết định đúng owner"]
    E --> Q{"Nguồn, quyền sử dụng,<br/>khả năng kiểm soát và độ tin cậy<br/>đủ hỗ trợ khuyến nghị?"}

    Q -->|Không| V["Verification required<br/>Ghi câu hỏi, giả định và rủi ro<br/>Không tuyên bố field, rule, SLA hoặc compliance"]
    V --> E

    Q -->|Có| C["Xác định tiêu chí từ nhu cầu<br/>và hậu quả nghiệp vụ"]
    C --> P["So sánh phương án tích hợp<br/>độ trễ; tải hệ thống; retry; xử lý trùng;<br/>tính khả dụng; hậu quả nghiệp vụ"]
    P --> I["Ghi trạng thái và mức chắc chắn hiện tại<br/>Recommendation / Assumption / IN_REVIEW<br/>không phải approval"]
    I --> S{"Có dấu hiệu phải escalation?<br/>Thiếu contract/version; ownership xung đột;<br/>retry thiếu idempotency; thiếu xác minh pháp lý;<br/>nguy cơ đơn trùng, sai chứng từ, lộ dữ liệu<br/>hoặc mất traceability"}

    S -->|Có| X["Escalation trước Decision"]
    X -->|Thiếu bằng chứng hoặc xác minh| V
    X -->|Cần quyết định hoặc xác nhận owner| O
    S -->|Không| O

    O["Xác định owner quyết định<br/>và mọi owner bắt buộc xác nhận"]
    O --> M["Routing không độc quyền theo loại quyết định<br/>Business Owner: mức dịch vụ, nghĩa nghiệp vụ<br/>Architect: khả thi, mapping và cơ chế kỹ thuật<br/>Security Owner: rủi ro dữ liệu và bảo mật<br/>Accounting Owner: tính toàn vẹn chứng từ<br/>Legal Owner: xác minh áp dụng pháp lý"]
    M --> A{"Owner có thẩm quyền đã quyết định<br/>và mọi owner bắt buộc đã xác nhận?"}

    A -->|Chưa| U["Giữ Recommendation / Assumption / IN_REVIEW<br/>Lấy quyết định hoặc xác nhận còn thiếu"]
    U --> O

    A -->|Đủ| R["Decision đã phê duyệt<br/>Ghi owner, căn cứ, trade-off và phạm vi"]
    R --> T["Traceability và test basis chính thức"]

Chất lượng bằng chứng quyết định mức chắc chắn của khuyến nghị. Bằng chứng mạnh gồm payload API thật từ môi trường được phép, OpenAPI contract được kiểm soát, log lỗi có thời điểm, quy tắc trong CANONICAL_BUSINESS_RULES, định nghĩa trường trong CANONICAL_DATA_DICTIONARY, và quyết định được ghi bởi đúng owner. Bằng chứng yếu gồm lời kể không có artifact, ảnh chụp không rõ nguồn, ví dụ đào tạo, hoặc suy luận từ hệ thống khác. Senior BA có thể dùng bằng chứng yếu để lập câu hỏi và nêu rủi ro, không dùng nó để tuyên bố field, rule, SLA hoặc compliance là sự thật.

Tình huống xung đột	Trade-off cần phân tích	Thẩm quyền quyết định	Cách ghi nhận phòng thủ được
Sales muốn gửi đơn ngay; Warehouse muốn gom đơn mỗi 15 phút	Tốc độ cập nhật so với tải hệ thống, retry và xử lý trùng	Business Owner quyết định mức dịch vụ nghiệp vụ; Architect xác nhận khả thi	Ghi hai phương án, độ trễ giả định, tác động tồn kho, trạng thái `Verification required`
Finance muốn sửa hóa đơn đã truyền; hệ thống nguồn chỉ cho tạo chứng từ thay thế	Tiện sửa dữ liệu so với tính toàn vẹn chứng từ	Accounting Owner và Legal Owner	Không tự diễn giải luật; tham chiếu nguồn chính thức, nêu cần xác minh áp dụng
Security yêu cầu không đưa dữ liệu cá nhân vào URL; vận hành muốn URL dễ tra cứu	Khả năng truy vết so với rủi ro lộ dữ liệu	Security Owner; Architect thiết kế cơ chế	Ghi loại dữ liệu, điểm truyền, rủi ro, quyết định hoặc điểm chưa quyết
Product Owner muốn đổi mã sản phẩm nguồn; đội ERP muốn giữ mã hiện hữu	Dễ dùng nguồn so với ổn định khóa tích hợp và lịch sử	Business Owner quyết định nghĩa nghiệp vụ; Architect quyết định mapping kỹ thuật	Không tự tạo canonical ID; đối chiếu `TRACEABILITY_ID_REGISTRY` và artifact nguồn

Quy tắc thường dùng là mỗi hệ thống chỉ có một nguồn chân lý cho một thuộc tính tại một thời điểm. Không áp dụng máy móc khi thuộc tính có vòng đời khác nhau. Ví dụ, hệ thống bán hàng có thể sở hữu địa chỉ giao do người mua nhập, còn ERP có thể sở hữu trạng thái xuất kho. Nếu hai hệ thống cùng sửa cùng một trường mà chưa có rule phân xử, Senior BA không chọn “last write wins” để đóng issue. Lý do: quy tắc đó có thể che mất dữ liệu đúng và tạo tranh chấp trách nhiệm. Cần escalation tới Business Owner và Architect, rồi ghi owner dữ liệu, trigger cập nhật, quy tắc xung đột và hành vi khi lỗi vào artifact kiểm soát.

Dấu hiệu đỏ cần dừng kết luận gồm: API không có version hoặc contract; trường tiền tệ không nêu VND hay quy tắc làm tròn; mã lỗi chỉ là thông báo tự do; retry không có idempotency key; bên gửi và bên nhận đều nhận là owner cùng một field; yêu cầu “tuân thủ pháp luật” không có Legal Owner xác minh; hoặc luồng lỗi xóa dữ liệu để đồng bộ lại. Khi một lỗi có thể tạo đơn trùng, xuất kho sai, sai chứng từ, lộ dữ liệu cá nhân, hoặc mất khả năng truy vết thực phẩm, Senior BA phải escalation trước khi ghi Decision. IN_REVIEW và v0.9.0 ngày 2026-08-07 không phải approval, baseline hay quyền triển khai production.

Khuyến nghị không chắc chắn phải nói rõ phần biết, phần suy luận và phần cần xác minh. Mẫu ghi nhận: “Dựa trên OpenAPI Specification OAS 3.1.1 về mô tả HTTP API và payload tổng hợp được cung cấp cho case Nova Foods, khuyến nghị dùng idempotency key cho POST tạo đơn để giảm rủi ro gửi trùng. Chưa có bằng chứng về hành vi retry của hệ thống nguồn. Verification required: Architect xác nhận cơ chế lưu khóa; Business Owner xác nhận hậu quả nghiệp vụ của đơn trùng.” Cách ghi này bảo toàn traceability nhưng không bịa độ chắc chắn, không bịa approval, không biến good practice của OWASP thành nghĩa vụ pháp lý.

Senior Lens

Senior BA rà soát tích hợp theo nguyên tắc: bằng chứng mạnh hơn ý kiến, rủi ro nghiệp vụ mạnh hơn tiện lợi kỹ thuật, và quyết định thuộc đúng thẩm quyền. Với Nova Foods Trading & Manufacturing mô phỏng, dữ liệu đều tổng hợp; IN_REVIEW tại v0.9.0 ngày 2026-08-07 không phải baseline, phê duyệt, hay quyền triển khai.

Heuristic rà soát	Kiểm tra cụ thể	Red flag	Ngưỡng escalation	Không áp dụng quy tắc thường khi
Một nguồn chân lý cho mỗi dữ liệu	Xác định hệ thống nào tạo, sửa, và sở hữu từng `CustomerID`, `ProductID`, đơn hàng, tồn kho	Hai hệ thống cùng cho phép sửa một trường mà không có quy tắc ưu tiên	Escalate Architect và Business Owner trước khi chốt mapping	Cần mô hình master-data được phê duyệt; Senior BA không tự chọn hệ thống chủ
Hợp đồng API rõ trước khi build	Đối chiếu endpoint, HTTP method, schema, mã lỗi, idempotency và phiên bản với OpenAPI Specification OAS 3.1.1	Chỉ có ví dụ JSON, thiếu quy tắc lỗi hoặc không nêu trường bắt buộc	Escalate khi API có thể tạo trùng chứng từ, mất dữ liệu, hoặc gọi lại gây thay đổi tài chính	Tích hợp file batch một chiều có thể không cần API; vẫn cần layout, lịch chạy và quy tắc xử lý lỗi
Phân loại dữ liệu trước khi truyền	Xác định có dữ liệu cá nhân, bí mật thương mại, giá bán, hay dữ liệu truy xuất hay không	“Không có dữ liệu nhạy cảm” nhưng payload chứa tên, số điện thoại, địa chỉ	Escalate Security Owner và Legal/Compliance Owner trước khi mô tả kiểm soát bắt buộc	Không suy diễn nghĩa vụ pháp lý từ học liệu; yêu cầu pháp lý phải ghi `Verification required`
Đo được thất bại	Có timeout, retry, retry limit, dead-letter hoặc hàng đợi lỗi, cảnh báo và đối soát	“Hệ thống tự đồng bộ” nhưng không có log, mã tương quan, hay người xử lý lỗi	Escalate khi lỗi không phát hiện trong một chu kỳ đối soát, hoặc không thể xác định bản ghi ảnh hưởng	Luồng tra cứu chỉ đọc, không lưu dữ liệu, có thể dùng kiểm soát nhẹ hơn nếu Security xác nhận
Ưu tiên toàn vẹn hơn tốc độ	Nêu rõ consistency, độ trễ chấp nhận được, và điểm khóa dữ liệu	Cam kết “real-time” nhưng không có tải dự kiến, SLA, hoặc giới hạn API	Escalate Architect khi độ trễ ảnh hưởng phân bổ tồn kho, giá, hóa đơn hoặc giao hàng	Báo cáo quản trị có thể chấp nhận batch nếu Business Owner xác nhận độ trễ chấp nhận được
Tách fact khỏi assumption	Mỗi kết luận có nguồn, ngày, người cung cấp, hoặc nhãn giả định	Requirement viết như fact nhưng chỉ dựa vào trao đổi miệng	Escalate khi assumption làm thay đổi tiền, quyền truy cập, nghĩa vụ pháp lý, hay traceability	Prototype học liệu dùng assumption được phép, nhưng phải ghi rõ là dữ liệu tổng hợp và không dùng production

Dấu hiệu cần dừng review gồm: payload chưa có schema; không xác định được chủ dữ liệu; mapping làm thay đổi ý nghĩa trường; retry có thể tạo đơn hàng hoặc chứng từ trùng; quyền API rộng hơn mục đích sử dụng; hoặc bên nghiệp vụ yêu cầu “đồng bộ ngay” nhưng không xác định độ trễ, khối lượng, giờ cao điểm và hậu quả khi chậm. Dừng không có nghĩa từ chối tích hợp. Dừng nghĩa là chưa đủ bằng chứng để khuyến nghị an toàn.

Ngưỡng escalation phải gắn tác động, không gắn chức danh người nói to hơn. Business Owner xử lý ưu tiên nghiệp vụ, chấp nhận độ trễ và hậu quả vận hành. Architect xử lý ranh giới hệ thống, mẫu tích hợp, năng lực và tính sẵn sàng. Security Owner xử lý xác thực, phân quyền, bí mật và log. Legal/Compliance Owner xác minh yêu cầu liên quan Luật 91/2025/QH15 và Nghị định 356/2025/NĐ-CP. Accounting Owner xử lý ý nghĩa hạch toán, chứng từ và dữ liệu liên quan Luật Kế toán hoặc Nghị định 123/2020/NĐ-CP. Senior BA lập gói bằng chứng và truy vết, không thay các quyết định đó.

Quy tắc “API đồng bộ thời gian thực tốt hơn file batch” không áp dụng khi đối tác chỉ hỗ trợ file, dữ liệu cần đối soát theo ngày, khối lượng lớn làm vượt giới hạn API, hoặc tính nhất quán quan trọng hơn độ trễ. Quy tắc “retry tự động giảm lỗi” không áp dụng cho thao tác tạo hay cập nhật có tác động nếu chưa có idempotency key và cơ chế phát hiện trùng. Quy tắc “ẩn lỗi để người dùng không bị gián đoạn” không áp dụng khi lỗi có thể làm mất traceability, sai tồn kho, sai giá hoặc sai chứng từ.

Khuyến nghị review phải ghi được lý do phản biện. Mẫu ghi nhận: “Khuyến nghị chưa chọn đồng bộ thời gian thực cho luồng đơn hàng Nova Foods mô phỏng. Bằng chứng hiện có: chỉ có mô tả payload tổng hợp, chưa có tải dự kiến, SLA, idempotency hoặc xác nhận chủ dữ liệu. Rủi ro: tạo trùng đơn hàng khi retry. Cần quyết định từ Architect về mẫu tích hợp và từ Business Owner về độ trễ chấp nhận được. Trạng thái: IN_REVIEW; không diễn giải là phê duyệt hoặc baseline.”

Senior Lens

Senior BA không biến khoảng trống bằng chứng thành kết luận. Với Nova Foods là case mô phỏng, dữ liệu tổng hợp, mỗi nhận định tích hợp phải tách rõ: fact (sự kiện có nguồn), inference (suy luận từ fact), assumption (giả định chưa xác minh), và verification required (cần xác minh). Cách tách này giúp người đọc biết phần nào đủ làm quyết định, phần nào chỉ đủ làm phương án tạm.

Trường ghi nhận	Nội dung artifact-ready	Ví dụ Nova Foods mô phỏng
Fact	Quan sát có thể truy về nguồn, tệp, ngày kiểm tra	OAS 3.1.1 mô tả HTTP API; tài liệu nguồn không cung cấp OpenAPI contract của hệ thống kho.
Inference	Kết luận kèm cầu nối lý luận	Chưa thể xác nhận mapping trường `warehouseCode`, vì không có contract nguồn của hệ thống kho để đối chiếu.
Assumption	Điều kiện tạm dùng, phạm vi và hậu quả	Project assumption: kho trả mã kho duy nhất cho mỗi giao dịch xuất; sai giả định có thể hạch toán sai địa điểm tồn kho.
Verification required	Câu hỏi, bằng chứng cần lấy, vai trò trả lời	Cần Architect hoặc owner hệ thống kho cung cấp API contract, mẫu payload đã che dữ liệu và quy tắc mã kho.
Recommendation	Lựa chọn có điều kiện, không khẳng định chắc chắn	Khuyến nghị chưa khóa mapping trường kho trong `/02-handbook/12-api-and-integration-analysis.md` cho đến khi contract được xác minh.
Decision status	Trạng thái quản trị hiện hành	`IN_REVIEW`, `v0.9.0`, ngày `2026-08-07`; không phải baseline hay approval.

Mẫu câu phòng thủ được: “Dựa trên fact X trong nguồn Y, suy luận Z là hợp lý cho phạm vi mô phỏng. Tuy nhiên, bằng chứng chưa xác nhận điều kiện Q. Khuyến nghị chọn phương án R với điều kiện Q được xác minh; nếu không xác minh trước mốc thiết kế chi tiết, giữ trạng thái IN_REVIEW và không chuyển suy luận thành requirement.” Câu này nêu đủ chứng cứ, giới hạn, hành động và hậu quả; không gán ý kiến cho stakeholder, không nói “đã được phê duyệt”.

Khi ghi recommendation, Senior BA lưu liên kết đến nguồn canonical thay vì chép lại hoặc nâng cấp nguồn. Ví dụ, /01-curriculum/CANONICAL_DATA_DICTIONARY.md là kế hoạch từ điển dữ liệu logic, không phải API schema đã xác nhận. Vì artifact có IN_REVIEW và chưa có baseline reference, nó chỉ chứng minh tồn tại kế hoạch quản trị; nó không chứng minh trường API, kiểu dữ liệu hay quy tắc chuyển đổi đã đúng.

Mức tin cậy	Điều kiện bằng chứng	Cách diễn đạt được phép	Điều không được nói
Cao	Contract, payload mẫu tổng hợp và owner xác nhận nhất quán	“Có bằng chứng cho mapping đề xuất.”	“Đã sẵn sàng production.”
Trung bình	Nguồn chính thức có nguyên tắc, thiếu contract hệ thống	“Có thể thiết kế theo hướng này, cần xác minh mapping.”	“API sẽ trả trường này.”
Thấp	Chỉ có mô tả miệng hoặc suy đoán từ tên trường	“Chưa đủ bằng chứng để quyết định.”	“Đây là business rule của Nova Foods.”

Recommendation phòng thủ phải còn truy vết được sau review: nguồn nào được dùng, nguồn nào thiếu, ai có thẩm quyền xác minh, điều kiện thay đổi quyết định, và tác động nếu giả định sai. Với dữ liệu cá nhân, kế toán, hóa đơn, an toàn thực phẩm hoặc traceability, ghi Verification required và chuyển kết luận chuyên môn cho Legal Owner, Accounting Owner, domain owner hoặc Security; handbook giáo dục không thay thế thẩm quyền đó.

12. Associated Template Reference & Completed Artifact

Core

Template là biểu mẫu chuẩn để ghi nhận cùng loại thông tin theo cấu trúc lặp lại. Với phân tích API và integration, template chỉ hữu ích khi đã có template ID và tệp canonical được đăng ký. Bằng chứng hiện có: /01-curriculum/TEMPLATE_MANIFEST.md là manifest kế hoạch template, trạng thái IN_REVIEW, phiên bản v0.9.0; compact dependency không cung cấp template API-specific đã đăng ký. Vì vậy không được tự tạo ID như API_SPEC_TEMPLATE hoặc suy diễn tên tệp completed artifact.

12-api-and-integration-analysis — diagram 29

Source mermaid — có thể chỉnh sửa

flowchart TB
    A[BA cần ghi nhận API hoặc integration] --> B{Template ID và tệp canonical đã đăng ký?}
    B -- Có --> C[Dùng template đúng phạm vi]
    C --> G[Quality gate theo owner]
    B -- Không --> D[Tham chiếu TEMPLATE_MANIFEST]
    D --> E[Manifest chỉ là kế hoạch, trạng thái IN_REVIEW]
    E --> F[Không tự tạo Template ID hoặc suy diễn tên tệp completed artifact]
    F --> H[Ghi khoảng trống và escalation]
    H --> G[Quality gate theo owner]

Applied

Facts: Nova Foods Trading & Manufacturing là case mô phỏng giáo dục, chỉ dùng dữ liệu tổng hợp. Corpus ở IN_REVIEW, v0.9.0, ngày 2026-08-07. Không có template ID hoặc filename chuyên biệt cho API được cung cấp trong source boundary.

Current Behavior: BA có thể cần mô tả endpoint, payload, authentication, mapping và lỗi integration, nhưng chưa có bằng chứng về template canonical tương ứng.

Underlying Need: Cần tránh hai lỗi: dùng template không đúng mục đích và tạo template ID mới làm đứt traceability.

Options: (1) tự tạo template API mới; (2) dùng artifact canonical hiện có làm nguồn tham chiếu; (3) ghi thiếu hụt vào template manifest và chờ quyết định quản trị.

Decision Criteria: ID phải tồn tại trong nguồn canonical; filename phải giữ nguyên; owner phải có thẩm quyền; quality gate phải kiểm được traceability, source boundary và trạng thái xác minh.

Decision: Chọn option (2) và (3). Không có template API-specific được phép dùng hoặc tự đặt tên trong phạm vi bằng chứng hiện có.

Authority: Principal IT Business Analyst / Technical Curriculum Author duy trì manifest và traceability. Architect xác minh contract, authentication và kiến trúc integration. Security xác minh kiểm soát bảo mật. Legal Owner, Accounting Owner hoặc domain owner xác minh nội dung pháp lý, kế toán, hóa đơn, dữ liệu cá nhân, an toàn thực phẩm và traceability khi phát sinh.

Artifact: Dùng /01-curriculum/TEMPLATE_MANIFEST.md để kiểm tra đăng ký template; dùng /01-curriculum/TRACEABILITY_ID_REGISTRY.md để kiểm tra ID; dùng /01-curriculum/CANONICAL_DATA_DICTIONARY.md cho nghĩa dữ liệu logic; dùng /01-curriculum/CANONICAL_BUSINESS_RULES.md cho quy tắc nghiệp vụ canonical.

Consequence if Wrong: Template hoặc ID tự tạo có thể bị hiểu nhầm là artifact đã kiểm soát, làm sai mapping, che mất Verification required, hoặc biến giả định mô phỏng thành yêu cầu ERP thực.

Senior Lens

Không dùng manifest như template điền nội dung. TEMPLATE_MANIFEST chỉ chứng minh kế hoạch quản trị template, không chứng minh template đã tồn tại, đã baseline hoặc được phê duyệt. Tương tự, CANONICAL_DATA_DICTIONARY là kế hoạch từ điển dữ liệu logic; không được suy ra JSON schema, kiểu dữ liệu API hay mapping đã xác nhận.

Quality gate phải kiểm ba lớp. Lớp định danh kiểm ID và filename nguyên dạng. Lớp phạm vi kiểm artifact có đúng chức năng không. Lớp thẩm quyền kiểm vấn đề được chuyển đúng owner trước khi mô tả thành quyết định. Nếu chưa có template canonical, output đúng là khoảng trống được truy vết, không phải biểu mẫu tự phát.

Quick Reference

Template/Artifact ID	Tệp canonical	Dùng khi	Không dùng khi	Owner quản trị	Consumer	Quality gate
`TEMPLATE_MANIFEST`	`/01-curriculum/TEMPLATE_MANIFEST.md`	Kiểm tra template nào đã được lập kế hoạch, ID nào được đăng ký, phạm vi template	Không dùng làm API contract, payload mẫu, approval hoặc baseline	Principal IT Business Analyst / Technical Curriculum Author	BA, curriculum author, reviewer	ID và filename khớp manifest; giữ `IN_REVIEW`; không suy diễn template chưa được cung cấp
`TRACEABILITY_ID_REGISTRY`	`/01-curriculum/TRACEABILITY_ID_REGISTRY.md`	Kiểm tra định danh requirement, rule, data, interface hoặc kiểm soát liên quan	Không dùng để tạo ID mới hoặc xác nhận nội dung nghiệp vụ	Principal IT Business Analyst / Technical Curriculum Author	BA, QA reviewer, Architect	ID nguyên dạng; liên kết nguồn canonical; escalation khi ID chưa đăng ký
`CANONICAL_DATA_DICTIONARY`	`/01-curriculum/CANONICAL_DATA_DICTIONARY.md`	Đối chiếu nghĩa dữ liệu logic trước khi đề xuất field mapping	Không dùng như schema API, database schema hoặc contract đã xác nhận	Principal IT Business Analyst / Technical Curriculum Author; Architect xác minh kỹ thuật	BA, Architect, QA	Tên dữ liệu, nghĩa và phân loại không mâu thuẫn; mapping chưa xác minh gắn `Verification required`
`CANONICAL_BUSINESS_RULES`	`/01-curriculum/CANONICAL_BUSINESS_RULES.md`	Đối chiếu business rule trước khi mô tả validation hoặc xử lý lỗi integration	Không dùng để suy ra rule vận hành thực, pháp lý, kế toán hoặc thuế	Principal IT Business Analyst / Technical Curriculum Author; Business Owner xác minh nghiệp vụ	BA, QA, Business Owner, Architect	Rule ID tồn tại; nguồn và owner rõ; rule nhạy cảm chuyển Legal Owner, Accounting Owner hoặc domain owner
`00_SOURCE_MAP`	`/00-research/00_SOURCE_MAP.md`	Kiểm ranh giới dùng nguồn OpenAPI, OWASP, luật và chuẩn	Không dùng để tuyên bố Nova Foods tuân thủ hoặc đã áp dụng chuẩn	Principal IT Business Analyst / Technical Curriculum Author	BA, Security, Legal Owner, reviewer	URL và source classification giữ nguyên; claim pháp lý gắn `Verification required`
Không có ID đã cung cấp	Không có filename đã cung cấp	Ghi nhận gap template API-specific và escalation	Không tự đặt ID, filename, phiên bản hoặc completed artifact location	Principal IT Business Analyst / Technical Curriculum Author điều phối; Architect/Security xác minh chuyên môn	BA, curriculum reviewer	Gap được ghi rõ; không có fabricated template, fabricated approval hoặc baseline claim

Quick Reference

Nova Foods là case mô phỏng giáo dục, chỉ dùng dữ liệu tổng hợp. Tra cứu chapter này tại /02-handbook/12-api-and-integration-analysis.md. Artifact Nova Foods đã điền hoàn chỉnh chưa có vị trí canonical được xác nhận trong nguồn đầu vào; không suy đoán đường dẫn /03-templates/ hoặc tạo ID mới. Ghi Verification required cho vị trí artifact đến khi TEMPLATE_MANIFEST đăng ký tệp và ID.

12-api-and-integration-analysis — diagram 30

Source mermaid — có thể chỉnh sửa

flowchart TB
    A[Đọc chapter API and Integration] --> B[Tra TEMPLATE_MANIFEST: filename và trạng thái]
    B --> C[Tra TRACEABILITY_ID_REGISTRY: canonical ID]
    C --> D[Đối chiếu canonical business rules, data dictionary, source map]
    D --> E{Có đúng canonical ID, filename và trạng thái trong manifest?}
    E -->|Có đủ ba| F[Liên kết đúng ID và filename]
    E -->|Thiếu bất kỳ điều kiện nào| G[Giữ Verification required]

Mục tra cứu hoàn chỉnh	Cần xác nhận	Vị trí canonical	Kết quả hợp lệ
Phạm vi chapter	Chapter thuộc API và integration analysis, không phải thiết kế production	`/02-handbook/12-api-and-integration-analysis.md`	Nội dung dùng tiếng Việt, vi-VN, Asia/Ho_Chi_Minh, VND mô phỏng
Cấu trúc chapter	Đủ 12 H2 blueprint, H3 `Core`, `Applied`, `Senior Lens`, `Quick Reference`	`CHAPTER_MANIFEST` tại `/01-curriculum/CHAPTER_MANIFEST.md`	Không đổi title, slug, thứ tự section
Trạng thái quản trị	`IN_REVIEW`, `v0.9.0`, ngày `2026-08-07`	`CHAPTER_MANIFEST`	Không gọi approved, baselined, production-ready
ID và liên kết	Chỉ dùng canonical ID đã đăng ký	`/01-curriculum/TRACEABILITY_ID_REGISTRY.md`	Không tự đặt ID cho API, endpoint, event, rule, field
Quy tắc nghiệp vụ	Rule được tham chiếu phải giữ source boundary	`/01-curriculum/CANONICAL_BUSINESS_RULES.md`	Không biến assumption thành quy tắc Nova Foods
Dữ liệu trao đổi	Entity, field, mã, dữ liệu nhạy cảm phải đối chiếu dictionary	`/01-curriculum/CANONICAL_DATA_DICTIONARY.md`	Không tự suy diễn schema ERP hay dữ liệu thật
Mô tả API	HTTP method, URL path, request, response, lỗi, xác thực phải phân biệt requirement với thiết kế	OpenAPI Specification OAS 3.1.1	Không gọi ví dụ JSON là API contract đã phê duyệt
Bảo mật API	Xác thực, phân quyền, lộ dữ liệu, giới hạn truy cập phải có nhãn verification	OWASP ASVS 5.0.0; OWASP API Security Top 10 2023	Không khẳng định Nova Foods tuân thủ bảo mật
Dữ liệu cá nhân	Có dữ liệu cá nhân thì kiểm tra nghĩa vụ pháp lý với owner có thẩm quyền	Luật 91/2025/QH15; Nghị định 356/2025/NĐ-CP	`Verification required`, không diễn giải pháp lý cuối cùng
Kiểm thử tích hợp	Test basis phải truy được requirement, rule, data và expected result	ISTQB CTFL Syllabus v4.0.1	Không gọi test case là bằng chứng pass khi chưa chạy
Nguồn ngoài	Chuẩn và luật chỉ dùng trong safe use boundary	`/00-research/00_SOURCE_MAP.md`	Không bịa clause, page, quotation, nghĩa vụ pháp lý
Template tham chiếu	Template phải có ID và filename đã đăng ký trước khi dùng	`/01-curriculum/TEMPLATE_MANIFEST.md`	Không sao chép toàn bộ registry vào chapter
Artifact đã điền	Kiểm tra ID, filename, version, status và liên kết chapter	`TEMPLATE_MANIFEST`	Hiện trạng: `Verification required`; chưa có vị trí canonical được cung cấp

Quy tắc tra cứu: chapter chỉ liên kết artifact đã điền khi đồng thời thấy đúng ID, filename và trạng thái trong manifest. Bằng chứng là TEMPLATE_MANIFEST là controlled planning artifact cho catalog template, còn TRACEABILITY_ID_REGISTRY giữ canonical identifier. Thiếu một trong ba dữ liệu làm liên kết không đủ căn cứ.

Vị trí hiện có để ghi nhận tham chiếu học liệu là /02-handbook/12-api-and-integration-analysis.md. Vị trí artifact Nova Foods đã điền: Verification required trong /01-curriculum/TEMPLATE_MANIFEST.md; không có filename hoặc artifact ID được xác minh trong nguồn đầu vào.

Senior Lens

Cross-file self-review là kiểm tra chéo giữa chapter, artifact canonical và nguồn đã phân loại. Mục tiêu không phải chứng minh nội dung đã đúng hay đã được phê duyệt. Mục tiêu là phát hiện đứt traceability, suy diễn vượt nguồn, hoặc quyết định vượt thẩm quyền trước handoff. Nova Foods Trading & Manufacturing là case mô phỏng giáo dục; mọi dữ liệu là tổng hợp, status IN_REVIEW, version v0.9.0, ngày 2026-08-07.

Mã kiểm tra	Đối chiếu bắt buộc	Bằng chứng cần thấy	Kết quả hiện tại	Owner escalation khi lỗi
XFR-API-001	Chapter với `/01-curriculum/CHAPTER_MANIFEST.md`	Tên chapter, đường dẫn `/02-handbook/12-api-and-integration-analysis.md`, cấu trúc 12 H2 không đổi	Verification required: dependency trích xuất không cung cấp entry riêng của chapter 12	Principal IT Business Analyst / Technical Curriculum Author
XFR-API-002	Chapter với `/01-curriculum/TRACEABILITY_ID_REGISTRY.md`	Mọi ID được giữ nguyên canonical; không tạo ID không đăng ký	Open issue: cần xác minh ID integration/API nào đã được registry đăng ký	Principal IT Business Analyst / Technical Curriculum Author; Technical Architect nếu ID biểu thị interface hay architecture
XFR-API-003	Chapter với `/01-curriculum/CANONICAL_BUSINESS_RULES.md`	Rule nghiệp vụ không bị đổi thành API rule; tham chiếu giữ source boundary	Verification required: không có rule cụ thể trong dependency trích xuất để đối chiếu	Business Owner cho ý nghĩa nghiệp vụ; Principal IT Business Analyst / Technical Curriculum Author duy trì traceability
XFR-API-004	Chapter với `/01-curriculum/CANONICAL_DATA_DICTIONARY.md`	Tên entity, field, kiểu dữ liệu, phân loại dữ liệu không bị tự suy diễn	Verification required: dependency trích xuất không nêu schema hay field canonical	Data Owner; Technical Architect
XFR-API-005	Chapter với OpenAPI Specification OAS 3.1.1	Chỉ gọi HTTP API description là OpenAPI khi artifact tuân OAS; không suy diễn endpoint production	Open issue: chưa có OpenAPI file canonical để kiểm schema, operation, response và security scheme	Technical Architect; Security Owner
XFR-API-006	Chapter với nguồn privacy, security, accounting, food safety	Mọi nghĩa vụ pháp lý ghi `Verification required`; OWASP chỉ là good practice	Pass về boundary: không có claim tuân thủ Nova Foods	Legal Owner cho privacy/pháp lý; Accounting Owner; Food Safety/Traceability Domain Owner; Security Owner
XFR-API-007	Chapter với governance metadata	Giữ `IN_REVIEW`, `v0.9.0`, `2026-08-07`, `vi-VN`, `Asia/Ho_Chi_Minh`, `VND`; không ghi approval hay baseline	Pass	Principal IT Business Analyst / Technical Curriculum Author

Open issues trước handoff

Mã	Vấn đề	Vì sao chưa thể đóng	Escalation owner	Điều kiện đóng
OI-API-001	Chưa có interface contract canonical cho luồng ERP Nova Foods	Không có URL, endpoint, message schema, mapping hoặc error contract trong nguồn đầu vào	Technical Architect	Cung cấp artifact controlled có định danh, đường dẫn, version và source classification
OI-API-002	Chưa xác minh mapping dữ liệu giữa ERP và hệ thống ngoài	`CANONICAL_DATA_DICTIONARY` chỉ được biết là artifact canonical; dependency không chứa entity hoặc field cụ thể	Data Owner; Technical Architect	Đối chiếu từng field với dictionary và ghi kết quả traceability
OI-API-003	Chưa xác minh điều kiện xử lý dữ liệu cá nhân qua API	Luật và nghị định là nguồn chính thức, nhưng áp dụng vào một data flow cần Legal Owner xác nhận	Legal Owner; Security Owner	Ghi rõ data classification, purpose, access control và kết luận chuyên môn được tham chiếu
OI-API-004	Chưa xác minh rule hóa đơn, kế toán, truy xuất thực phẩm có đi qua integration	Không được suy luận nghĩa vụ từ ví dụ ERP mô phỏng	Accounting Owner; Food Safety/Traceability Domain Owner; Legal Owner	Xác nhận phạm vi nghiệp vụ mô phỏng và nhãn `Verification required` còn hoặc được thay bằng tham chiếu có thẩm quyền

Quy tắc handoff: Principal IT Business Analyst / Technical Curriculum Author chuyển chapter kèm bảng này, không tự đóng OI-API-001 đến OI-API-004, không đổi IN_REVIEW thành baseline hoặc approval. Technical Architect quyết định tính đúng đắn architecture và interface; Security Owner quyết định security control; Legal Owner quyết định diễn giải pháp lý; Accounting Owner và Food Safety/Traceability Domain Owner quyết định nội dung miền nghiệp vụ. Nếu một issue chạm từ hai thẩm quyền, giữ issue mở và escalation đồng thời; vì một kết luận đơn vai trò sẽ không đủ bằng chứng.

ERP gửi yêu cầu giao hàng sau khi xác nhận đơn

Sơ đồ trả lời: khi nào ERP gửi yêu cầu giao hàng cho Hub, và kết quả nào cho phép ERP ghi nhận hoặc xử lý lỗi? Trigger là đơn SO-SIM-00017 chuyển sang trạng thái Confirmed.

ERP gửi yêu cầu giao hàng sau khi xác nhận đơn

Source plantuml — có thể chỉnh sửa

@startuml
!theme plain
skinparam shadowing false
skinparam sequenceMessageAlign center
skinparam responseMessageBelowArrow true

title ERP gửi yêu cầu giao hàng sau khi xác nhận đơn

box "Nova Foods" #EAF2F8
participant ERP as "Nova Foods ERP\nActor: bên khởi tạo"
end box

box "Hệ thống giao hàng" #FEF9E7
participant Hub as "Nova Delivery Hub\nBên nhận API"
end box

ERP -> ERP: Trigger: xác nhận `SO-SIM-00017`
ERP -> Hub: Action: `POST /deliveries`\nObject: yêu cầu giao hàng\n`orderId`, `deliveryAddress`, `items`

alt Hub tạo yêu cầu giao thành công
  Hub --> ERP: Outcome: `201 Created`\n`deliveryId DL-SIM-00421`
  ERP -> ERP: Lưu `deliveryId`\nvà trạng thái gửi
else Hub từ chối hoặc trả lỗi
  Hub --> ERP: Outcome: lỗi hoặc từ chối
  ERP -> ERP: Lưu phản hồi lỗi\nđể tra cứu và xử lý
end

note over ERP, Hub
API là điểm giao tiếp kỹ thuật.
Integration còn gồm thời điểm gửi,
ánh xạ dữ liệu và xử lý lỗi.
end note
@enduml

ERP là actor khởi tạo. ERP chỉ gửi object yêu cầu giao hàng khi đơn đã Confirmed; Hub trả outcome để ERP biết giao dịch đã được tạo hay chưa.

Nhánh thành công lưu deliveryId và trạng thái gửi. Nhánh lỗi hoặc từ chối yêu cầu ERP lưu phản hồi, tránh mất dấu đơn cần xử lý.

Ranh giới: sơ đồ mô tả luồng API đồng bộ giữa ERP và Hub. Nó không quyết định xác thực, phân quyền, thử lại, hàng đợi hay cấu hình production.

Thành phần và ranh giới trách nhiệm

Component diagram làm rõ trách nhiệm, interface và dependency trong phạm vi được mô tả.

Thành phần và ranh giới trách nhiệm

Source plantuml — có thể chỉnh sửa

@startuml
left to right direction
skinparam shadowing false
skinparam componentStyle rectangle
skinparam defaultTextAlignment center

skinparam component {
  BackgroundColor<<source>> #D9EAD3
  BackgroundColor<<integration>> #CFE2F3
  BackgroundColor<<external>> #FCE5CD
  BackgroundColor<<outcome>> #D9EAD3
  BackgroundColor<<failure>> #F4CCCC
  BorderColor #444444
}
skinparam interface {
  BackgroundColor #FFF2CC
  BorderColor #444444
}

title Nova Foods — Phân tích outcome tích hợp giao hàng mô phỏng
caption `201 Created` xác nhận Hub tạo giao hàng. ERP chỉ ghi nhận gửi thành công sau khi lưu được `deliveryId`.

component "Xác nhận đơn\n`SO-SIM-00017`" as Confirmed <<source>>
component "ERP Integration\nGửi yêu cầu và nhận response" as ERPIntegration <<integration>>
interface "POST /deliveries\n`orderId`, `deliveryAddress`, `items`" as DeliveriesAPI
component "Nova Delivery Hub\nTạo yêu cầu giao hàng" as Hub <<external>>
component "Thử ghi nhận\nkết quả gửi" as SaveResult <<integration>>

component "ERP lưu `deliveryId`\nTrạng thái: gửi thành công" as RecordedSuccess <<outcome>>
component "ERP lưu lỗi Hub\nTrạng thái: gửi thất bại" as RecordedFailure <<failure>>
component "ERP không lưu được response\nKhông xác định trạng thái gửi" as SaveFailure <<failure>>

Confirmed --> ERPIntegration : kích hoạt khi đơn\n`Confirmed`
ERPIntegration ..> DeliveriesAPI : gọi HTTP API
DeliveriesAPI - Hub : endpoint Hub cung cấp

Hub --> SaveResult : response `201 Created`\n`deliveryId`
Hub --> SaveResult : response lỗi Hub\nví dụ thiếu `deliveryAddress`

SaveResult --> RecordedSuccess : [response `201 Created`\nvà lưu `deliveryId` được]
SaveResult --> RecordedFailure : [response lỗi Hub\nvà lưu lỗi được]
SaveResult --> SaveFailure : [lỗi lưu kết quả gửi]

note bottom of Hub
`201 Created`: Hub đã tạo giao hàng.
Chưa tự chứng minh ERP đã lưu kết quả.
end note

note bottom of SaveFailure
Không lưu response sau `201 Created`
hoặc response lỗi Hub.
Cần tra cứu trước khi gửi lại;
gửi lại có thể tạo giao trùng.
end note
@enduml

Các quan hệ cho thấy bên cung cấp, bên sử dụng và ranh giới lỗi; sơ đồ không mở rộng ra ngoài bằng chứng của chương.