Tmpl Api 001 Api Specification

1. Tier 1 ? Metadata, Purpose, and Governance

Metadata quản trị artifact

Trường kiểm soát	Giá trị kiểm soát	Diễn giải áp dụng
Artifact ID	`TMPL-API-001`	Định danh canonical của template đặc tả API. Mọi liên kết, lịch sử thay đổi và kiểm tra corpus phải giữ nguyên chuỗi ID này.
Tên tệp được kiểm soát	`/03-templates/TMPL-API-001_api-specification.md`	Đây là vị trí canonical của artifact trong corpus Nova Foods. Bản sao, nội dung trích dẫn hoặc tệp xuất không thay thế tệp được kiểm soát này.
Tiêu đề tài liệu	`Tmpl Api 001 Api Specification`	Tiêu đề H1 được giữ ổn định để đối chiếu với manifest template và các liên kết traceability.
Status	`IN_REVIEW`	Artifact đang được xem xét có kiểm soát. Trạng thái này không đồng nghĩa `APPROVED`, `BASELINED`, production-ready, compliant hoặc đã được người dùng phê duyệt.
Version	`v0.9.0`	Phiên bản đang xem xét tại thời điểm cập nhật. Mọi sửa đổi sau ngày này phải tạo dòng lịch sử thay đổi mới; không được sửa im lặng hoặc gán lại ý nghĩa của phiên bản này.
Owner	Principal IT Business Analyst / Technical Curriculum Author	Owner duy trì định danh, cấu trúc bốn tier, metadata, lịch sử thay đổi và ranh giới dữ liệu của template. Owner không có thẩm quyền tự thiết lập baseline, ghi nhận approval, phê chuẩn API thực tế hoặc cho phép triển khai production.
Last updated date	`2026-08-07`	Ngày cập nhật gần nhất, được diễn giải theo múi giờ quản trị `Asia/Ho_Chi_Minh`.
Locale và tiền tệ mô phỏng	`vi-VN`; Việt Nam; `VND`	Nội dung hướng dẫn dùng tiếng Việt; các giá trị tiền tệ, nếu xuất hiện trong case Nova Foods ở tier hoàn chỉnh, chỉ là dữ liệu tổng hợp bằng VND.
Phân loại artifact	Controlled four-tier template	Template có bốn tầng kiểm soát: Tier 1 thiết lập governance; Tier 2 là mẫu trống; Tier 3 là case Nova Foods đã điền đầy đủ; Tier 4 là kiểm tra chất lượng Senior BA. Phân loại này mô tả cấu trúc học liệu, không xác nhận đặc tả kỹ thuật đã sẵn sàng vận hành.
Baseline reference	Chưa có baseline reference tại `v0.9.0`	Suy luận kiểm soát: status là `IN_REVIEW` và không có mã baseline được ghi nhận, vì vậy không được gọi nội dung này là baseline.
Approval reference	Chưa có approval reference tại `v0.9.0`	Sự tồn tại của Owner, metadata, ví dụ API hoặc nội dung review không tạo ra chấp thuận ngầm định từ Business Owner, Architect, Security, Legal, QA hoặc người dùng.

Lịch sử thay đổi

Version	Ngày	Trạng thái	Người ghi nhận	Nội dung thay đổi
`v0.9.0`	`2026-08-07`	`IN_REVIEW`	Principal IT Business Analyst / Technical Curriculum Author	Khởi tạo metadata quản trị cho `TMPL-API-001`; xác lập tên tệp canonical, trạng thái review, ranh giới dữ liệu tổng hợp Nova Foods và nguyên tắc không suy diễn thành phê duyệt hoặc baseline.

Ranh giới dữ liệu mô phỏng

Nova Foods Trading & Manufacturing là case study mô phỏng phục vụ giáo dục; toàn bộ tên người, mã khách hàng, mã đơn hàng, mã lô, URL, endpoint, payload, khóa truy cập, địa chỉ, số tiền và kết quả xử lý trong artifact này phải là dữ liệu tổng hợp. Dữ liệu tổng hợp nghĩa là dữ liệu được tạo cho mục tiêu minh họa, không được trình bày như dữ liệu lấy từ doanh nghiệp, hệ thống ERP, môi trường production hoặc nguồn cá nhân có thật.

Không được dùng template này để khẳng định Nova Foods là doanh nghiệp có thật, đang vận hành API cụ thể, đã áp dụng cấu hình ERP, đạt tuân thủ bảo mật, đáp ứng nghĩa vụ pháp lý hoặc được bất kỳ bên nào phê duyệt. Nếu một ví dụ cần tham chiếu chuẩn hay nguồn bên ngoài, nguồn đó phải được phân loại đúng theo 00_SOURCE_MAP: nguồn chuẩn như OpenAPI Specification chỉ hỗ trợ diễn đạt đặc tả HTTP API; nguồn pháp lý Việt Nam chỉ được dùng trong phạm vi đã xác minh và mọi diễn giải triển khai phải giữ nhãn Verification required khi chưa có xác nhận của chủ sở hữu thẩm quyền.

Mục đích, điều kiện sử dụng và thẩm quyền của `TMPL-API-001`

TMPL-API-001 là mẫu đặc tả API (Application Programming Interface — giao diện để các hệ thống trao đổi dữ liệu và yêu cầu xử lý theo quy ước kỹ thuật) bốn tầng cho corpus Nova Foods. Mẫu này giúp Business Analyst chuyển một nhu cầu tích hợp đã được xác định thành cấu trúc tài liệu có thể đọc thống nhất bởi nghiệp vụ, phát triển, kiểm thử và vận hành. Mục tiêu là làm rõ ranh giới giao tiếp: hệ thống nào gọi, gọi chức năng nào, dữ liệu nào được trao đổi, điều kiện thành công hoặc lỗi nào cần được kiểm thử, và liên kết nào phải được giữ để truy vết. Nova Foods Trading & Manufacturing chỉ là case study giáo dục; mọi tên, mã, dữ liệu và tình huống trong mẫu phải là dữ liệu tổng hợp, không đại diện cho ERP hoặc tổ chức thực tế.

Nội dung quản trị	Quy định áp dụng
Khi sử dụng	Dùng khi một yêu cầu cần mô tả giao tiếp HTTP API giữa các thành phần trong phạm vi học liệu, ví dụ ERP mô phỏng gửi yêu cầu tạo phiếu giao hàng tổng hợp sang dịch vụ kho mô phỏng. Dấu hiệu tối thiểu là đã biết mục tiêu nghiệp vụ, bên gửi hoặc bên nhận, và sự kiện hoặc thao tác cần hỗ trợ.
Khi không sử dụng	Không dùng mẫu này để thay thế Business Requirements Document, quy trình BPMN, thiết kế cơ sở dữ liệu vật lý, cấu hình ERP, tài liệu vận hành production, hợp đồng với nhà cung cấp, hoặc kết luận pháp lý và bảo mật. Nếu chưa xác định được nhu cầu nghiệp vụ hoặc chủ thể chịu trách nhiệm, phải quay lại artifact yêu cầu hoặc phân tích quy trình thay vì tự tạo endpoint.
Owner	`Principal IT Business Analyst / Technical Curriculum Author` duy trì cấu trúc mẫu, tính nhất quán định danh, traceability và ranh giới dữ liệu mô phỏng. Owner không có thẩm quyền phê duyệt API triển khai, baseline, quyết định kiến trúc, bảo mật, pháp lý, kế toán hoặc vận hành Nova Foods.
Consumers	Business Analyst dùng để đặc tả; Solution Architect và Technical Lead dùng để đánh giá tính khả thi kỹ thuật; Developer dùng làm đầu vào triển khai; QA dùng làm test basis; Security reviewer dùng để xem xét rủi ro giao tiếp và kiểm soát truy cập. Mỗi vai trò chỉ kết luận trong phạm vi thẩm quyền của mình.
Điều kiện tiên quyết	Phải có liên kết đến nhu cầu hoặc requirement nguồn; business rule và định nghĩa dữ liệu liên quan phải được nhận diện hoặc gắn nhãn `Verification required`; chủ sở hữu hệ thống nguồn và đích phải được nêu ở mức mô phỏng; các ID phải đối chiếu với `TRACEABILITY_ID_REGISTRY`. Lý do: đặc tả API không thể quyết định đúng dữ liệu hoặc quyền truy cập nếu chưa có nguồn nghiệp vụ và dữ liệu để truy vết.
Artifact đầu ra phụ thuộc	Mẫu hoàn chỉnh có thể làm đầu vào cho backlog kỹ thuật, thiết kế tích hợp, test case API, ma trận traceability, đánh giá bảo mật và tài liệu vận hành dự thảo. Quan hệ này là quan hệ đầu vào học liệu, không phải lệnh triển khai hay bằng chứng phê duyệt.

Quyền quyết định được phân tách để tránh suy diễn từ một mẫu tài liệu sang quyết định thực tế. Business Owner xác nhận ý nghĩa nghiệp vụ mô phỏng; Solution Architect xác nhận phương án tích hợp và ranh giới hệ thống; Technical Lead xác nhận khả năng thực hiện; QA xác nhận tính kiểm thử; Security reviewer đánh giá kiểm soát bảo mật; Legal, Compliance hoặc Accounting Owner xem xét nội dung có thể liên quan nghĩa vụ pháp lý, dữ liệu cá nhân, kế toán hoặc hóa đơn. Việc tham chiếu OpenAPI Specification chỉ hỗ trợ mô tả HTTP API theo chuẩn; không tự chứng minh rằng thiết kế tuân thủ pháp luật, an toàn hoặc sẵn sàng production.

Phải escalation bằng gói vấn đề có ID, mô tả xung đột, artifact nguồn và tác động truy vết khi xảy ra một trong các điều kiện sau: requirement mâu thuẫn với business rule; trường dữ liệu chưa có định nghĩa trong CANONICAL_DATA_DICTIONARY; ID không có trong TRACEABILITY_ID_REGISTRY; API xử lý dữ liệu cá nhân, thuế, kế toán, hóa đơn hoặc truy xuất nguồn gốc thực phẩm; hoặc lựa chọn xác thực, phân quyền, lưu trữ hay truyền dữ liệu cần quyết định kiến trúc hoặc bảo mật. Owner ghi nhận và bảo toàn liên kết của vấn đề, nhưng không tự đóng vấn đề bằng kết luận ngoài thẩm quyền.

Ánh xạ Manifest, Định danh Canonical, Chương, Nguồn và Nghĩa vụ Kiểm soát Thay đổi

Template này có danh tính được kiểm soát là TMPL-API-001, với tệp canonical /03-templates/TMPL-API-001_api-specification.md. “Canonical” nghĩa là bản tham chiếu chuẩn duy nhất được dùng để liên kết, kiểm tra và quản trị thay đổi trong corpus; bản sao, bản xuất PDF hoặc tên tệp rút gọn không thay thế tệp này. Cơ sở của việc giữ nguyên ID và đường dẫn là TEMPLATE_MANIFEST, nơi quản lý danh mục template dự kiến, cùng TRACEABILITY_ID_REGISTRY, nơi kiểm soát quy tắc dùng định danh xuyên artifact. Không được tự tạo biến thể như API-001, TMPL_API_001 hoặc đổi tên tệp vì sự khác biệt chuỗi ký tự có thể làm đứt liên kết truy vết.

Hạng mục ánh xạ	Giá trị kiểm soát	Lý do và giới hạn sử dụng
Template ID	`TMPL-API-001`	ID canonical của template API Specification; phải giữ nguyên trong liên kết, lịch sử thay đổi và bằng chứng QA.
Tệp canonical	`/03-templates/TMPL-API-001_api-specification.md`	Là vị trí kiểm soát của artifact; không thay bằng đường dẫn cục bộ, URL xuất bản hoặc tên hiển thị.
Manifest nguồn	`/01-curriculum/TEMPLATE_MANIFEST.md` — `TEMPLATE_MANIFEST`	Là nguồn xác định danh mục template và ranh giới governance của thư viện template.
Registry định danh	`/01-curriculum/TRACEABILITY_ID_REGISTRY.md` — `TRACEABILITY_ID_REGISTRY`	Là nguồn kiểm tra cú pháp, tính duy nhất và cách liên kết ID; không suy diễn ID mới ngoài registry.
Kiến trúc học liệu	`/01-curriculum/01_CURRICULUM_ARCHITECTURE.md` — `01_CURRICULUM_ARCHITECTURE`	Cung cấp bối cảnh chuỗi học từ requirement đến traceability và test basis; không phải nguồn quyết định thiết kế API vận hành thực tế.
Manifest chapter	`/01-curriculum/CHAPTER_MANIFEST.md` — `CHAPTER_MANIFEST`	Dùng để đối chiếu template với các chapter handbook đã được lập kế hoạch; chỉ manifest quyết định quan hệ chapter chính thức.
Quy tắc nghiệp vụ	`/01-curriculum/CANONICAL_BUSINESS_RULES.md` — `CANONICAL_BUSINESS_RULES`	Khi Tier 3 minh họa rule Nova Foods, phải liên kết đến rule ID đã đăng ký; không biến ví dụ API thành nguồn chân lý của rule.
Dữ liệu logic	`/01-curriculum/CANONICAL_DATA_DICTIONARY.md` — `CANONICAL_DATA_DICTIONARY`	Khi mô tả field, entity hoặc mã dữ liệu, phải đối chiếu định nghĩa logic canonical; không tự coi payload mẫu là mô hình dữ liệu production.

Phạm vi chương của chính artifact này được cố định theo sáu phần đã công bố: Tier 1 kiểm soát danh tính và ranh giới sử dụng; Tier 2 cung cấp mẫu trống có thể sao chép; Tier 3 thể hiện case Nova Foods đã điền đủ bằng dữ liệu tổng hợp; Tier 4 áp dụng quality gate của Senior BA; phần cuối kiểm tra liên tệp, vấn đề mở và escalation. Cấu trúc bốn tier là cơ chế phân biệt rõ “khung để học” với “ví dụ đã hoàn chỉnh”: placeholder chỉ được phép ở Tier 2; dữ liệu Nova Foods chỉ là mô phỏng giáo dục và không chứng minh endpoint, quyền truy cập, cấu hình ERP hoặc quyết định vận hành có thật.

Nguồn/chuẩn	Phân loại nguồn	Cách dùng được phép trong template	Không được suy diễn
OpenAPI Specification 3.1.1	Nguồn chuẩn kỹ thuật normative cho mô tả HTTP API	Dùng thuật ngữ và cấu trúc mô tả API phù hợp OAS khi nội dung thực sự cần OAS.	Không tuyên bố payload mẫu Nova Foods đã hợp lệ với mọi công cụ hay đã triển khai.
OWASP ASVS 5.0.0; OWASP API Security Top 10 2023	Good practice/industry security reference	Dùng để nhận diện điểm cần xem xét bảo mật và rủi ro API.	Không gọi đây là luật Việt Nam hoặc xác nhận API mô phỏng tuân thủ bảo mật.
ISTQB CTFL Syllabus v4.0.1	Nguồn thuật ngữ và kỹ thuật kiểm thử	Dùng cho traceability từ API behaviour đến test basis và kiểm thử hộp đen.	Không thay thế kế hoạch kiểm thử, bằng chứng test execution hoặc QA sign-off.
ISO/IEC/IEEE 29148:2018	Nguồn tham chiếu requirements engineering	Dùng cho tư duy rõ ràng, nhất quán và kiểm chứng được của yêu cầu.	Không trích dẫn điều khoản chính xác khi chưa kiểm tra văn bản được cấp phép.
BABOK Guide Version 3	Nguồn thuật ngữ và thực hành BA	Dùng cho reasoning về stakeholder, traceability, governance và phân tích yêu cầu.	Không bịa số trang, điều khoản hoặc xác nhận IIBA phê duyệt artifact.
Nguồn pháp lý Việt Nam trong `00_SOURCE_MAP`	Nguồn pháp lý chính thức, cần thẩm quyền chuyên môn khi diễn giải	Chỉ gắn nhãn `Verification required` hoặc giả định dự án cho nội dung privacy, kế toán, hóa đơn, an toàn thực phẩm.	Không biến ví dụ Nova Foods thành nghĩa vụ pháp lý, thuế, kế toán hoặc compliance đã xác nhận.

Mọi thay đổi ảnh hưởng đến TMPL-API-001, tên tệp, ID liên kết, cấu trúc tier, nguồn tham chiếu hoặc ranh giới dữ liệu phải được ghi nhận theo cơ chế change control của corpus: nêu thay đổi, lý do, artifact bị ảnh hưởng, liên kết truy vết, người cần review theo thẩm quyền và phiên bản cập nhật. Lý do là thay đổi một field API có thể tác động đồng thời rule nghiệp vụ, data dictionary, test basis, security review và tài liệu downstream; do đó không được sửa im lặng. Khi thay đổi chạm đến diễn giải pháp lý, hạch toán, bảo mật, kiến trúc tích hợp hoặc quyết định vận hành, Principal IT Business Analyst / Technical Curriculum Author chỉ lập gói escalation và bảo toàn traceability; kết luận thuộc Legal, Accounting, Security, Architect, QA hoặc Business Owner tương ứng. IN_REVIEW và v0.9.0 không tạo baseline, approval hoặc quyền sử dụng production.

2. Tier 2 – Blank Copy-Paste-Ready Template

Mẫu này cung cấp cấu trúc hoàn chỉnh, sẵn sàng để sao chép và điền thông tin cho một đặc tả API mới. Mọi trường trong ngoặc nhọn <...> phải được thay thế bằng thông tin cụ thể của dự án. Mẫu này được thiết kế để một Business Analyst (BA) có thể hoàn thành mà không cần kiến thức lập trình sâu, tập trung vào "cái gì" và "tại sao", thay vì "làm thế nào" về mặt kỹ thuật.

2.1. Metadata và Quản trị API

Bảng này xác định danh tính, mục đích và quyền sở hữu của API.

Trường	Mô tả và Hướng dẫn
Tên API	`<Tên gợi nhớ cho API, ví dụ: "Quản lý Nhà Cung Cấp API">`
ID Đặc tả	`TMPL-API-XXX` (Sẽ được cấp phát từ `TRACEABILITY_ID_REGISTRY` khi tạo artifact mới)
Phiên bản API	`<Phiên bản theo ngữ nghĩa, ví dụ: v1.0.0. Tuân thủ Semantic Versioning MAJOR.MINOR.PATCH>`
Owner Nghiệp vụ	`<Tên vai trò hoặc cá nhân chịu trách nhiệm về mặt nghiệp vụ, ví dụ: "Trưởng phòng Mua hàng">`
Owner Kỹ thuật	`<Tên vai trò hoặc cá nhân chịu trách nhiệm về mặt kỹ thuật/triển khai, ví dụ: "Lead Developer đội ERP Core">`
Trạng thái	`<Chọn một: DRAFT, IN_REVIEW, APPROVED, DEPRECATED, RETIRED>`
Mục đích	`<Mô tả ngắn gọn mục đích nghiệp vụ của API này. Nó giải quyết vấn đề gì? Cho người dùng nào? Thuộc hệ thống/module nào trong ERP của Nova Foods?>`
Liên kết Traceability	- Yêu cầu cấp cao: `<Liệt kê ID yêu cầu, ví dụ: REQ-PROC-001>` - User Story/Feature: `<Liệt kê các ID, ví dụ: US-101, US-102>`

2.2. Tổng quan Endpoints

Một Endpoint là một địa chỉ (URL) cụ thể mà API nhận yêu cầu để thực hiện một chức năng.

Phương thức HTTP	Đường dẫn (Path)	Mô tả ngắn gọn chức năng
`<GET/POST/PUT/PATCH/DELETE>`	`/<tên-resource-số-nhiều>/<tham-số-nếu-có>`	`<Mô tả chức năng của endpoint này trong một câu. Ví dụ: "Lấy danh sách tất cả nhà cung cấp đang hoạt động.">`
`<GET>`	`/<tên-resource-số-nhiều>/{id}`	`<Ví dụ: "Lấy chi tiết một nhà cung cấp theo ID.">`
`<POST>`	`/<tên-resource-số-nhiều>`	`<Ví dụ: "Tạo một nhà cung cấp mới.">`

2.3. Chi tiết Endpoint

Sao chép toàn bộ khối dưới đây cho mỗi endpoint được liệt kê ở bảng trên.

<Đường_dẫn_endpoint>

Mô tả: <Mô tả chi tiết mục đích và hành vi của endpoint. Endpoint này làm gì, khi nào được gọi, và kết quả mong đợi là gì? Ví dụ: "Endpoint này cho phép người dùng có quyền tạo một hồ sơ nhà cung cấp mới trong hệ thống. Dữ liệu đầu vào phải được kiểm tra hợp lệ trước khi lưu vào cơ sở dữ liệu.">
Quy tắc nghiệp vụ (Business Rules) liên quan: <Liệt kê các ID quy tắc từ Catalog Quy tắc Nghiệp vụ Canonical, ví dụ: BR-VEND-001 (Mã số thuế phải là duy nhất), BR-PROC-005 (Nhà cung cấp mới mặc định ở trạng thái 'Chờ duyệt'). Nếu chưa có, ghi "Verification required" và tạo yêu cầu định nghĩa rule mới.>

Request (Yêu cầu)

Tham số đường dẫn (Path Parameters)

Tên tham số	Kiểu dữ liệu	Bắt buộc?	Mô tả
`{<tên-tham-số>}`	`<string (uuid)/integer>`	Có	`<Mô tả ý nghĩa của tham số, thường là ID của một tài nguyên. Ví dụ: "ID duy nhất của nhà cung cấp.">`

Tham số truy vấn (Query Parameters)

Tên tham số	Kiểu dữ liệu	Bắt buộc?	Mô tả
`<tên-tham-số>`	`<string/integer/boolean/date>`	Không	`<Dùng để lọc, sắp xếp, hoặc phân trang. Ví dụ: "lọc nhà cung cấp theo trạng thái ('active', 'inactive')">`

Tiêu đề (Headers)

Tên Header	Bắt buộc?	Mô tả và Giá trị mẫu
`Authorization`	Có	Token xác thực người dùng. Định dạng: `Bearer <JWT>`.
`Content-Type`	Có (cho `POST`/`PUT`/`PATCH`)	Loại nội dung của request body. Luôn là `application/json`.
`Idempotency-Key`	Không (Nên có cho `POST`)	Khóa chống lặp yêu cầu, là một chuỗi UUID v4 duy nhất cho mỗi yêu cầu tạo mới để tránh tạo trùng lặp do lỗi mạng.

Nội dung yêu cầu (Request Body): application/json

Tên trường	Kiểu dữ liệu	Bắt buộc?	Quy tắc kiểm tra hợp lệ (Validation Rules)	Mô tả
`<tên-trường-gốc>`	`object`	Có	`not-null`	`<Đối tượng cha chứa dữ liệu.>`
`.<tên-trường-con>`	`string`	Có	`not-empty`, `maxLength: 255`	`<Mô tả trường con và các ràng buộc của nó.>`
`.<trường-số>`	`number`	Không	`min: 0`, `format: decimal(18,2)`	`<Mô tả trường số, ví dụ: giá trị đơn hàng.>`
`.<trường-ngày>`	`string`	Có	`format: iso-8601-date` (`YYYY-MM-DD`)	`<Ngày theo chuẩn quốc tế ISO 8601.>`
`.<trường-enum>`	`string`	Có	`in: ['VALUE_1', 'VALUE_2']`	`<Trường chỉ chấp nhận một trong các giá trị cho trước.>`

Ví dụ Request Body:

{
  "<tên-trường-gốc>": {
    "<tên-trường-con>": "<giá-trị-ví-dụ>",
    "<trường-số>": 123.45,
    "<trường-ngày>": "2026-08-07",
    "<trường-enum>": "VALUE_1"
  }
}

Response (Phản hồi)

Phản hồi thành công

Mã trạng thái: <200 OK / 201 Created / 204 No Content>
Mô tả: <Mô tả ý nghĩa của phản hồi thành công này. Ví dụ: "Trả về đối tượng nhà cung cấp vừa được tạo thành công, bao gồm ID do hệ thống sinh ra.">
Nội dung phản hồi (Response Body): application/json (nếu có)

Ví dụ Response Body (cho 201 Created):

{
  "id": "<uuid-sinh-ra-bởi-hệ-thống>",
  "createdAt": "2026-08-07T10:00:00Z",
  "<tên-trường-gốc>": {
    "<tên-trường-con>": "<giá-trị-ví-dụ>",
    "<trường-số>": 123.45,
    "<trường-ngày>": "2026-08-07",
    "<trường-enum>": "VALUE_1"
  }
}

Phản hồi lỗi

Mã HTTP	Mã lỗi nội bộ (`code`)	Ý nghĩa và khi nào xảy ra
`400 Bad Request`	`VALIDATION_ERROR`	Yêu cầu không hợp lệ (thiếu trường, sai định dạng, giá trị ngoài phạm vi). Chi tiết lỗi cụ thể cho từng trường nằm trong `details`.
`401 Unauthorized`	`UNAUTHENTICATED`	Yêu cầu thiếu hoặc có `Authorization` token không hợp lệ.
`403 Forbidden`	`PERMISSION_DENIED`	Đã xác thực nhưng không có quyền thực hiện hành động này trên tài nguyên.
`404 Not Found`	`RESOURCE_NOT_FOUND`	Không tìm thấy tài nguyên được yêu cầu qua ID trong URL.
`409 Conflict`	`DUPLICATE_RESOURCE`	Xung đột dữ liệu, ví dụ tạo tài nguyên có mã số thuế đã tồn tại.
`500 Internal Server Error`	`INTERNAL_SERVER_ERROR`	Lỗi không mong muốn từ máy chủ. Không phải lỗi từ phía client.

2.4. Bảo mật

Yêu cầu bảo mật	Chi tiết
Xác thực (Authentication)	`<Mô tả phương thức xác thực. Mặc định là JWT Bearer Token. Token được cấp bởi dịch vụ xác thực trung tâm của Nova Foods.>`
Phân quyền (Authorization)	`<Mô tả logic phân quyền. Vai trò (role) nào được phép gọi endpoint này? Cần quyền (permission) gì cụ thể? Ví dụ: Chỉ vai trò "Kế toán trưởng" với quyền "approve_payment" mới được phép gọi endpoint duyệt chi.>`
Tham chiếu Bí mật	Không bao giờ đưa khóa API, mật khẩu, hay chuỗi kết nối trực tiếp vào đặc tả. Sử dụng tham chiếu đến kho chứa bí mật (vault). Ví dụ: `VAULT::erp-prod/database#password`.
Phân loại dữ liệu	`<Phân loại dữ liệu được truyền qua API theo độ nhạy cảm: PUBLIC, INTERNAL, CONFIDENTIAL, RESTRICTED (theo định nghĩa trong từ điển dữ liệu).>`

2.5. Các vấn đề phi chức năng khác

Loại	Mô tả
Giả định (Assumptions)	`<Liệt kê các giả định đã được đưa ra khi thiết kế API. Ví dụ: "Giả định hệ thống quản lý kho bên thứ ba cung cấp API ổn định.">`
Giới hạn (Constraints)	`<Liệt kê các giới hạn kỹ thuật hoặc nghiệp vụ. Ví dụ: "Tốc độ xử lý: 100 yêu cầu/phút/user".>`
Vấn đề mở (Open Issues)	`<Liệt kê các câu hỏi chưa có lời giải đáp hoặc quyết định đang chờ xử lý. Gắn ID để theo dõi, ví dụ: ISSUE-API-001: Cần làm rõ logic xử lý khi nhà cung cấp có nhiều địa chỉ.>`

Khung bảng kiểm soát bắt buộc cho bản mẫu API mô phỏng Nova Foods

Tài liệu này là khung trống copy-paste cho /03-templates/TMPL-API-001_api-specification.md, dùng trong bối cảnh Nova Foods mô phỏng giáo dục, dữ liệu tổng hợp בלבד. Mục tiêu của phần này là giữ đủ mọi bảng kiểm soát để người soạn không phải tự thêm cấu trúc mới, và để mọi quyết định, ngoại lệ, bằng chứng, truy vết, phiên bản, rà soát và ký xác nhận đều có chỗ ghi nhận rõ ràng ngay từ đầu.

2.x.1. Bảng kiểm soát tài liệu và versioning

Trường kiểm soát	Giá trị mẫu trống phải điền
Document ID	`<TMPL-API-001>`
File path	`</03-templates/TMPL-API-001_api-specification.md>`
Document title	`<Tmpl Api 001 Api Specification>`
Status	`<IN_REVIEW>`
Version	`<v0.9.0>`
Last updated date	`<2026-08-07>`
Timezone	`<Asia/Ho_Chi_Minh>`
Locale	`<vi-VN>`
Currency	`<VND>`
Case study label	`<Nova Foods Trading & Manufacturing - simulated educational case study>`
Data classification	`<synthetic data only>`
Owner	`<Principal IT Business Analyst / Technical Curriculum Author>`
Traceability anchor	`<canonical-document-anchor-or-stable-id>`
Change summary	`<mô tả ngắn thay đổi của bản nháp hiện hành>`

2.x.2. Bảng quyết định nghiệp vụ và quyết định kỹ thuật

Decision ID	Câu hỏi cần quyết định	Phương án	Lý do chọn	Hệ quả nếu không chọn	Người quyết định	Ngày quyết định	Trạng thái
`<DEC-001>`	`<quyết định nghiệp vụ hoặc kỹ thuật đầu tiên>`	`<phương án A>`	`<lý do theo yêu cầu hoặc ràng buộc>`	`<tác động nếu chưa chốt>`	`<vai trò chịu trách nhiệm>`	`<YYYY-MM-DD>`	`<draft/confirmed/rejected>`
`<DEC-002>`	`<quyết định tiếp theo>`	`<phương án B>`	`<lý do>`	`<tác động>`	`<vai trò chịu trách nhiệm>`	`<YYYY-MM-DD>`	`<draft/confirmed/rejected>`

2.x.3. Bảng ngoại lệ, giả định và vấn đề mở

Exception / Assumption / Open Issue ID	Loại	Mô tả	Điều kiện kích hoạt	Tác động	Hướng xử lý dự kiến	Chủ sở hữu xử lý	Trạng thái
`<EXC-001>`	`<exception>`	`<mô tả ngoại lệ cụ thể>`	`<điều kiện xảy ra>`	`<ảnh hưởng đến API/spec>`	`<cách xử lý hoặc leo thang>`	`<vai trò>`	`<open/monitoring/closed>`
`<ASM-001>`	`<assumption>`	`<giả định đang dùng>`	`<điều kiện giả định>`	`<ảnh hưởng nếu giả định sai>`	`<cách kiểm tra lại>`	`<vai trò>`	`<open/validated/revised>`
`<ISS-001>`	`<open issue>`	`<vấn đề cần làm rõ>`	`<điều kiện chưa đủ thông tin>`	`<mức rủi ro>`	`<kế hoạch chốt vấn đề>`	`<vai trò>`	`<open/escalated/resolved>`

2.x.4. Bảng bằng chứng và nguồn tham chiếu

Evidence ID	Loại bằng chứng	Mô tả	Nguồn gốc	Ngày ghi nhận	Liên kết an toàn	Mức tin cậy sử dụng	Ghi chú
`<EVI-001>`	`<source / screenshot / export / log / note>`	`<mô tả bằng chứng>`	`<tên nguồn hoặc artifact>`	`<YYYY-MM-DD>`	`<safe-reference-pattern-or-canonical-link>`	`<high/medium/low>`	`<ghi chú về phạm vi sử dụng>`
`<EVI-002>`	`<source / screenshot / export / log / note>`	`<mô tả bằng chứng>`	`<tên nguồn hoặc artifact>`	`<YYYY-MM-DD>`	`<safe-reference-pattern-or-canonical-link>`	`<high/medium/low>`	`<ghi chú về phạm vi sử dụng>`

2.x.5. Bảng truy vết yêu cầu sang thiết kế và kiểm thử

Trace ID	Requirement source	Requirement statement	Design element	Test basis	Coverage status	Gap / note
`<TRC-001>`	`<nguồn yêu cầu canonical>`	`<câu yêu cầu gốc>`	`<phần thiết kế tương ứng>`	`<điều kiện kiểm thử liên quan>`	`<covered/partial/missing>`	`<ghi chú khoảng trống hoặc phụ thuộc>`
`<TRC-002>`	`<nguồn yêu cầu canonical>`	`<câu yêu cầu gốc>`	`<phần thiết kế tương ứng>`	`<điều kiện kiểm thử liên quan>`	`<covered/partial/missing>`	`<ghi chú khoảng trống hoặc phụ thuộc>`

2.x.6. Bảng lịch sử phiên bản

Version	Date	Author	Change type	Change summary	Reviewer	Review outcome
`<v0.9.0>`	`<2026-08-07>`	`<Principal IT Business Analyst / Technical Curriculum Author>`	`<initial draft / update / correction>`	`<tóm tắt thay đổi>`	`<vai trò rà soát>`	`<in_review / accepted / needs_revision>`
`<v0.9.1>`	`<YYYY-MM-DD>`	`<tên người sửa>`	`<update>`	`<tóm tắt thay đổi tiếp theo>`	`<vai trò rà soát>`	`<in_review / accepted / needs_revision>`

2.x.7. Bảng rà soát và sign-off tracking

Review / Sign-off ID	Vai trò	Họ tên hoặc mã vai trò	Ngày nhận	Ngày phản hồi	Kết quả	Ghi chú
`<REV-001>`	`<reviewer role>`	`<tên hoặc mã vai trò>`	`<YYYY-MM-DD>`	`<YYYY-MM-DD>`	`<approved / rejected / needs_changes>`	`<ghi chú rà soát>`
`<SOF-001>`	`<sign-off role>`	`<tên hoặc mã vai trò>`	`<YYYY-MM-DD>`	`<YYYY-MM-DD>`	`<signed / not_signed>`	`<ghi chú ký xác nhận>`

2.x.8. Bảng kiểm tra đủ cấu trúc trước khi điền nội dung thực

Hạng mục phải có	Đã có trong template	Trạng thái
Bảng kiểm soát tài liệu và versioning	`<yes>`	`<complete>`
Bảng quyết định	`<yes>`	`<complete>`
Bảng ngoại lệ, giả định, vấn đề mở	`<yes>`	`<complete>`
Bảng bằng chứng	`<yes>`	`<complete>`
Bảng truy vết	`<yes>`	`<complete>`
Bảng lịch sử phiên bản	`<yes>`	`<complete>`
Bảng rà soát và sign-off tracking	`<yes>`	`<complete>`

Khi dùng khung này, nguyên tắc là mỗi dòng phải giữ đúng một mục kiểm soát; không gộp nhiều quyết định vào một ô, không xóa dòng vì “chưa có dữ liệu”, và không dùng nội dung mô phỏng Nova Foods để thay thế bằng chứng, sign-off hoặc truy vết thật.

Hướng dẫn điền trường, giá trị hợp lệ, kiểm tra và tham chiếu bí mật

Cách dùng Tier 2: giữ nguyên tên trường và thay toàn bộ chuỗi trong dấu ngoặc nhọn bằng thông tin của API đang được phân tích. Dấu <...> chỉ là hướng dẫn mô tả, không phải giá trị được phép đưa vào đặc tả Tier 3 hay môi trường triển khai. Nếu chưa có bằng chứng đầu vào, ghi <Chưa có bằng chứng; nêu nguồn cần xác minh và vai trò chịu trách nhiệm>; không suy diễn thành quy tắc nghiệp vụ, quyết định kiến trúc hoặc phê duyệt.

Nhóm trường	Mẫu placeholder bắt buộc	Hướng dẫn điền	Giá trị hợp lệ hoặc quy tắc kiểm tra
Định danh API	`<Mã API duy nhất, ví dụ theo quy ước dự án>`	Ghi mã ổn định để liên kết requirement, test và bằng chứng.	Không chứa khoảng trắng; duy nhất trong phạm vi dự án; không đổi mã chỉ vì đổi tiêu đề.
Tên endpoint	`<HTTP method> <Đường dẫn URI tương đối>`	`HTTP method` là phương thức HTTP, tức hành động giao tiếp như đọc hoặc tạo dữ liệu.	Chỉ dùng `GET`, `POST`, `PUT`, `PATCH`, `DELETE` khi có lý do nghiệp vụ và kỹ thuật được nêu; đường dẫn bắt đầu bằng `/`; không đặt bí mật, mã truy cập hoặc dữ liệu cá nhân trên URI.
Phiên bản API	`<Phiên bản hợp đồng API>`	Ghi phiên bản của hợp đồng giao tiếp, tách biệt với phiên bản tài liệu.	Theo mẫu dự án như `v1`; thay đổi phá vỡ tương thích phải có đánh giá tác động và liên kết change record.
Trạng thái tài liệu	`IN_REVIEW`	Phản ánh đúng trạng thái kiểm soát của artifact hiện hành.	Chỉ dùng trạng thái được governance cho phép; `IN_REVIEW` không có nghĩa là đã baseline, đã phê duyệt hoặc sẵn sàng production.
Chủ sở hữu nghiệp vụ và kỹ thuật	`<Vai trò chịu trách nhiệm>`	Ghi vai trò, không tự gán tên cá nhân khi chưa có nguồn quản trị.	Tối thiểu phân biệt Business Owner, Technical Owner và người review; mỗi quyết định phải có vai trò chịu trách nhiệm.
Mục đích	`<Động từ nghiệp vụ> <đối tượng dữ liệu> để <kết quả nghiệp vụ>`	Viết một câu nêu kết quả, không chỉ lặp lại tên endpoint.	Phải trả lời được ai hoặc hệ thống nào dùng API, dữ liệu nào bị tác động và kết quả nào được mong đợi.
Phân loại dữ liệu	`<PUBLIC_INTERNAL_CONFIDENTIAL_RESTRICTED>`	Phân loại theo mức độ cần bảo vệ do dự án quy định.	Chỉ chọn một giá trị: `PUBLIC`, `INTERNAL`, `CONFIDENTIAL`, `RESTRICTED`; nếu có dữ liệu cá nhân, tài chính hoặc bí mật thương mại, gắn `Verification required` cho Security Owner và Legal/Compliance Owner khi phù hợp.
Yêu cầu xác thực	`<Loại cơ chế xác thực>`	Xác thực là kiểm tra danh tính bên gọi; không ghi token thật.	Chỉ dùng giá trị được kiến trúc cho phép, ví dụ `OAuth2`, `mTLS`, `API_KEY`, `NONE`; `NONE` yêu cầu nêu lý do, phạm vi dữ liệu công khai và xác nhận của Security Owner.
Ủy quyền	`<Scope hoặc quyền tối thiểu cần có>`	Ủy quyền là kiểm tra bên đã xác thực được phép làm gì.	Ghi quyền tối thiểu theo nguyên tắc least privilege; mỗi thao tác tạo, sửa, xóa hoặc xem dữ liệu nhạy cảm phải có quyền riêng hoặc lý do gộp quyền.
Đầu vào	`<Tên trường>`; `<kiểu dữ liệu>`; `<bắt buộc hoặc không>`	Mỗi trường request phải có ý nghĩa, kiểu, ví dụ tổng hợp và quy tắc kiểm tra.	Kiểu phải nhất quán với OpenAPI Specification 3.1.1 nếu hợp đồng biểu diễn bằng OAS; trường bắt buộc không được nhận `null`, trừ khi schema quy định rõ.
Đầu ra	`<HTTP status>`; `<Tên trường phản hồi>`	Nêu dữ liệu thành công và lỗi mà bên gọi có thể xử lý.	Status HTTP phải phù hợp kết quả: `200`, `201`, `202`, `204`, `400`, `401`, `403`, `404`, `409`, `422`, `429`, `500`, `503` chỉ được dùng khi có điều kiện nghiệp vụ hoặc kỹ thuật mô tả rõ.
Quy tắc nghiệp vụ	`<BR-ID canonical hoặc tham chiếu cần xác minh>`	Không chép lại quy tắc không có nguồn. Nêu cầu nối: trường nào chịu tác động, API kiểm tra ở đâu, phản hồi gì khi vi phạm.	Dùng đúng ID đã đăng ký trong `/01-curriculum/CANONICAL_BUSINESS_RULES.md`; nếu chưa có ID hoặc nội dung chưa được xác minh, ghi `Verification required`, nguồn cần kiểm tra và owner có thẩm quyền.
Truy vết	`<REQ-ID>`; `<BR-ID>`; `<DATA-ID>`; `<TEST-ID>`; `<EVID-ID>`	Liên kết từng yêu cầu API với yêu cầu, quy tắc, dữ liệu, kiểm thử và bằng chứng.	Dùng đúng ID canonical từ registry; không tạo ID tự phát trong lúc điền template; một liên kết thiếu phải được nêu là khoảng trống truy vết, không được coi là đã đáp ứng.
Ngoại lệ	`<Điều kiện kích hoạt>`; `<Mã lỗi>`; `<Phản hồi an toàn>`	Ngoại lệ là tình huống lệch khỏi luồng thành công nhưng đã được dự kiến.	Không đưa stack trace, token, chuỗi kết nối, dữ liệu cá nhân đầy đủ hoặc chi tiết nội bộ vào phản hồi lỗi; phải chỉ rõ bên gọi có thể thử lại, sửa request hay cần liên hệ hỗ trợ.
Bằng chứng	`<Loại bằng chứng>`; `<Vị trí kiểm soát>`; `<Ngày theo Asia/Ho_Chi_Minh>`	Bằng chứng chứng minh một kiểm tra đã diễn ra, không tự chứng minh phê duyệt.	Cho phép: liên kết test result, log đã che dữ liệu, ảnh chụp cấu hình đã che bí mật, biên bản review; mọi bằng chứng phải ghi nguồn, người tạo theo vai trò và ngày.
Review và sign-off	`<Vai trò reviewer>`; `<Kết quả review>`; `<Ngày>`; `<Tham chiếu quyết định>`	Sign-off là xác nhận của vai trò có thẩm quyền, không được suy ra từ việc có tên trong bảng.	Kết quả chỉ dùng `PENDING`, `ACCEPTED_WITH_COMMENTS`, `REJECTED`, `ESCALATED` nếu governance dự án cho phép; để trống kết quả phê duyệt khi chưa có bằng chứng ghi nhận.

Quy tắc kiểm tra trường dữ liệu: với mỗi request hoặc response field, điền đủ <Tên hiển thị>, <Tên kỹ thuật>, <Kiểu dữ liệu>, <Bắt buộc>, <Nguồn giá trị>, <Quy tắc kiểm tra>, <Xử lý khi không hợp lệ> và <Phân loại dữ liệu>. Nguồn giá trị chỉ được là CLIENT_INPUT, SYSTEM_DERIVED, REFERENCE_DATA hoặc SERVER_GENERATED; nếu chọn SYSTEM_DERIVED, API không được tin giá trị tương ứng do client gửi. Với tiền tệ, ghi <Số tiền VND tổng hợp> và quy tắc làm tròn cần xác minh bởi Accounting Owner; template không tự đặt quy tắc kế toán.

Phần có điều kiện: chỉ thêm bảng phân trang khi endpoint trả danh sách; chỉ thêm idempotency key, tức khóa giúp yêu cầu gửi lặp không tạo tác động lặp ngoài ý muốn, khi thao tác có nguy cơ tạo hoặc cập nhật dữ liệu; chỉ thêm webhook khi API chủ động gửi sự kiện sang hệ thống khác; chỉ thêm tệp đính kèm khi có giới hạn định dạng, dung lượng, quét mã độc và owner bảo mật được xác định. Nếu điều kiện không áp dụng, ghi <Không áp dụng; lý do dựa trên phạm vi endpoint> thay vì xóa tiêu đề kiểm soát.

Mẫu tham chiếu bí mật an toàn: dùng <secretRef: <Tên kho bí mật>/<Tên định danh bí mật>/<Phiên bản hoặc alias>>, ví dụ cấu trúc <secretRef: <approved-secret-store>/<api-client-credential>/<active-alias>>. Không ghi mật khẩu, API key, bearer token, private key, chuỗi kết nối, certificate đầy đủ hoặc giá trị bí mật đã mã hóa vào Markdown, payload ví dụ, log, ảnh chụp hay bằng chứng. Việc chọn kho bí mật, thời hạn xoay vòng và quyền truy cập là quyết định của Architect và Security Owner; nếu chưa có xác nhận, ghi <Verification required: Security Owner xác nhận cơ chế quản lý bí mật>.

3. Tier 3 – Fully Completed Nova Foods Case: Core Record

Phần này điền đầy đủ mẫu đặc tả API cho trường hợp sử dụng mô phỏng tại Nova Foods: tạo Đơn Mua Hàng (Purchase Order - PO) mới. Mọi dữ liệu, ID, tên, ngày và giá trị là giả lập cho mục đích học tập.

API-PO-001: Tạo Đơn Mua Hàng

3.1. Tổng quan Endpoint

Định danh (Endpoint ID): API-PO-001
HTTP Method: POST
Đường dẫn (Path): /api/v1/purchase-orders
Mô tả: Bộ phận Mua hàng gọi endpoint để tạo bản ghi Đơn Mua Hàng mới ở trạng thái PENDING_APPROVAL (Chờ duyệt) cho nhà cung cấp đã được phê duyệt. Hệ thống ERP lưu PO để phục vụ phê duyệt, nhận hàng, quản lý kho và công nợ phải trả.
Owner nghiệp vụ: Trưởng phòng Mua hàng (mô phỏng)
Owner kỹ thuật: ERP Development Team (mô phỏng)
Trạng thái artifact: IN_REVIEW
Kết quả tạo thành công: Server tạo một PO định danh duy nhất, lưu trạng thái PENDING_APPROVAL, trả URI tài nguyên qua header Location.

3.2. Yêu cầu (Request)

3.2.1. Headers

Header	Giá trị ví dụ	Bắt buộc	Diễn giải
`Content-Type`	`application/json`	Có	Client phải gửi `application/json`. Server từ chối kiểu nội dung khác với `415 Unsupported Media Type`.
`Authorization`	`Bearer <JWT>`	Có	Client gửi Bearer token do dịch vụ xác thực Nova Foods cấp. Token phải hợp lệ, chưa hết hạn và chứa `scope` là `purchase_orders:create`.
`Idempotency-Key`	`719a6b1a-0536-4a4a-9284-a1e4f483acb1`	Có	Client gửi khóa UUID v4 để chống tạo PO trùng do gửi lại yêu cầu. Server trả kết quả yêu cầu gốc khi khóa và nội dung giống nhau. Server trả `409 Conflict` khi khóa đã tồn tại nhưng nội dung khác.

3.2.2. Body (Payload)

Ví dụ payload tạo đơn mua Bột Mì Đa Dụng từ nhà cung cấp Công ty TNHH Ngũ Cốc Vàng:

{
  "supplierId": "SUP-VNG-0012",
  "orderDate": "2026-08-07T10:30:00Z",
  "expectedDeliveryDate": "2026-08-21",
  "currency": "VND",
  "items": [
    {
      "sku": "RAW-WHT-FLR-PREM-25KG",
      "quantity": 200,
      "unitPrice": 350000
    }
  ],
  "notes": "Giao hàng trong giờ hành chính. Vui lòng liên hệ Quản lý Kho - anh An (0901234567) trước khi giao."
}

Client tạo PO cho SUP-VNG-0012. Client yêu cầu giao ngày 2026-08-21. Client đặt 200 đơn vị RAW-WHT-FLR-PREM-25KG với đơn giá 350000 VND mỗi đơn vị. Server dùng dữ liệu này để tạo PO chờ duyệt.

3.2.3. Định nghĩa các trường trong Body

Tên trường	Kiểu dữ liệu	Bắt buộc	Quy tắc xác thực (Validation Rule)
`supplierId`	String	Có	Phải là ID hợp lệ trong hệ thống quản lý Nhà cung cấp. Định dạng: `SUP-XXX-NNNN`. Nhà cung cấp phải được phê duyệt.
`orderDate`	String (ISO 8601)	Có	Ngày tạo đơn hàng, định dạng `YYYY-MM-DDTHH:mm:ssZ`. Phải là thời điểm hiện tại hoặc quá khứ gần.
`expectedDeliveryDate`	String (ISO 8601)	Có	Ngày dự kiến nhận hàng, định dạng `YYYY-MM-DD`. Phải sau `orderDate`.
`currency`	String	Có	Đơn vị tiền tệ. Phải là `VND`.
`items`	Array of Objects	Có	Mảng chứa mặt hàng. Không được rỗng.
`items[].sku`	String	Có	Mã định danh sản phẩm (Stock Keeping Unit). Phải tồn tại trong danh mục vật tư Nova Foods.
`items[].quantity`	Integer	Có	Số lượng. Phải lớn hơn 0.
`items[].unitPrice`	Integer	Có	Đơn giá một đơn vị, tính bằng VND. Phải lớn hơn hoặc bằng 0. Đây là giá tại thời điểm đặt hàng.
`notes`	String	Không	Ghi chú cho đơn hàng, tối đa 500 ký tự.

3.3. Phản hồi (Response)

3.3.1. Thành công: `201 Created`

Khi server tạo PO thành công:

Server trả mã 201 Created.
Server trả header Location chứa URI tài nguyên PO mới.
Server trả body chứa ID, trạng thái và thời điểm tạo.
PO được tạo ở trạng thái PENDING_APPROVAL; việc tạo PO không đồng nghĩa PO đã được phê duyệt hoặc gửi nhà cung cấp.

Header Phản hồi:

Location: /api/v1/purchase-orders/PO-2026-08-4719

Body Phản hồi:

{
  "poId": "PO-2026-08-4719",
  "status": "PENDING_APPROVAL",
  "createdAt": "2026-08-07T10:30:05Z"
}

Server cấp poId là PO-2026-08-4719. Bộ phận Mua hàng dùng ID này để truy vết PO trong quy trình phê duyệt, nhận hàng và đối chiếu công nợ.

3.3.2. Lỗi (Errors)

Mã lỗi	Tên lỗi	Nguyên nhân	Ví dụ Body phản hồi
`400 Bad Request`	Yêu cầu không hợp lệ	Client thiếu trường bắt buộc, gửi sai định dạng như `quantity <= 0`, hoặc vi phạm quy tắc nghiệp vụ như `expectedDeliveryDate` trước `orderDate`. Server không tạo PO.	`{ "error": "Validation Error", "details": "Field 'quantity' must be greater than 0." }`
`401 Unauthorized`	Chưa xác thực	Client thiếu `Authorization`, gửi token không hợp lệ hoặc token hết hạn. Server không xử lý yêu cầu tạo PO.	`{ "error": "Unauthorized", "message": "Authentication token is missing or invalid." }`
`403 Forbidden`	Không có quyền	Token hợp lệ nhưng tài khoản không có `scope` là `purchase_orders:create`. Server từ chối tạo PO để bảo vệ quyền tạo chứng từ mua hàng.	`{ "error": "Forbidden", "message": "User does not have permission to create purchase orders." }`
`409 Conflict`	Xung đột	Client gửi `Idempotency-Key` đã dùng cho payload khác. Server không tạo PO thứ hai vì không thể xác định ý định tạo mới hay gửi lại yêu cầu cũ.	`{ "error": "Conflict", "message": "Idempotency key is already used with a different request." }`
`415 Unsupported Media Type`	Kiểu nội dung không hỗ trợ	Client gửi `Content-Type` khác `application/json`. Server từ chối vì không thể áp dụng quy tắc xác thực payload JSON.	`{ "error": "Unsupported Media Type", "message": "Content-Type must be application/json." }`
`500 Internal Server Error`	Lỗi hệ thống	Server gặp lỗi không xác định, ví dụ không thể kết nối cơ sở dữ liệu. Server không cam kết PO đã được tạo; client dùng `traceId` để báo sự cố.	`{ "error": "Internal Server Error", "message": "An unexpected error occurred. Please try again later.", "traceId": "a1b2c3d4-e5f6-7890-1234-567890abcdef" }`

Hoàn thiện Bản ghi Lõi: API Tạo Đơn Mua Hàng

Phần này hoàn thiện đặc tả API (Application Programming Interface - Giao diện Lập trình Ứng dụng) cho kịch bản mô phỏng Nova Foods. Phòng Mua hàng dùng API để tạo PO mới trong hệ thống ERP. Artifact giữ trạng thái IN_REVIEW; các owner được nêu chịu trách nhiệm rà soát, không phải xác nhận phê duyệt.

Thuộc tính API	Giá trị Mô phỏng cho Nova Foods
Tên API	`nova-foods-purchasing-api`
Mục đích	Cung cấp giao diện lập trình để ứng dụng được cấp phép tạo mới Đơn Mua Hàng có kiểm soát.
ID Yêu cầu Nghiệp vụ Gốc	`BRQ-PUR-003`: Tự động hóa việc tạo Đơn Mua Hàng từ hệ thống phụ trợ.
Owner Nghiệp vụ	Trưởng phòng Mua hàng (Nova Foods)
Owner Kỹ thuật	Trưởng nhóm Phát triển ERP
Phiên bản API	`1.0.0`
Trạng thái artifact	`IN_REVIEW`
Môi trường (Servers)	`https://api.simulation.novafoods.com.vn/purchasing`
Cơ chế xác thực	`OAuth 2.0 Client Credentials`. Client phải lấy access token từ máy chủ xác thực Nova Foods trước khi gọi API.
Thẩm quyền gọi	Client chỉ được tạo PO khi token chứa `scope` là `purchase_orders:create`.
Hệ quả kiểm soát	Server từ chối client chưa xác thực với `401 Unauthorized` và client thiếu quyền với `403 Forbidden`.

Điểm cuối (Endpoint): Tạo Đơn Mua Hàng Mới

Thao tác tạo bản ghi Đơn Mua Hàng mới trong ERP. Bản ghi tạo ra chờ phê duyệt trước khi đi tiếp trong quy trình mua hàng.

Thuộc tính	Chi tiết
Mô tả	Tạo Đơn Mua Hàng với thông tin nhà cung cấp và danh sách mặt hàng cần mua.
HTTP Method & Path	`POST /v1/purchase-orders`
Định danh Truy vết	`API-PO-001`
Actor gọi API	Ứng dụng client được Nova Foods cấp quyền.
Object được tạo	Bản ghi Đơn Mua Hàng trong ERP.
Kết quả	PO nhận ID duy nhất và trạng thái `PENDING_APPROVAL`.

Request Body (Payload)

Client gửi JSON để tạo đơn hàng.

Ví dụ Payload:

{
  "supplierId": "NCC-5501-A",
  "requestedDeliveryDate": "2026-11-20",
  "internalNotes": "Đơn hàng gấp cho đợt khuyến mãi cuối năm. Yêu cầu giao hàng đúng hẹn.",
  "lineItems": [
    {
      "productId": "SP-CF-RB-001",
      "quantity": 500,
      "unitPriceVnd": 85000
    },
    {
      "productId": "SP-PK-BOX-012",
      "quantity": 500,
      "unitPriceVnd": 4500
    }
  ]
}

Payload yêu cầu giao hàng ngày 2026-11-20. Client đặt 500 đơn vị SP-CF-RB-001 giá 85000 VND mỗi đơn vị và 500 đơn vị SP-PK-BOX-012 giá 4500 VND mỗi đơn vị. internalNotes ghi nhận mục đích giao gấp cho đợt khuyến mãi.

Chi tiết các trường trong Payload:

Tên trường	Kiểu dữ liệu	Bắt buộc?	Mô tả và Quy tắc	ID Quy tắc liên quan
`supplierId`	String	Có	Mã định danh duy nhất nhà cung cấp trong ERP. Phải tồn tại trong danh mục nhà cung cấp đã được phê duyệt.	`BR-PO-001`
`requestedDeliveryDate`	String (Date `YYYY-MM-DD`)	Có	Ngày mong muốn nhận hàng. Phải là ngày tương lai.	`BR-PO-002`
`internalNotes`	String	Không	Ghi chú nội bộ cho phòng mua hàng hoặc kế toán. Tối đa 1000 ký tự.	`BR-GEN-011`
`lineItems`	Array of Objects	Có	Danh sách mặt hàng cần mua. Mảng không được rỗng.	`BR-PO-003`
`lineItems.productId`	String	Có	Mã sản phẩm hoặc nguyên vật liệu. Phải tồn tại trong danh mục sản phẩm.	`BR-PO-004`
`lineItems.quantity`	Integer	Có	Số lượng. Phải là số nguyên lớn hơn 0.	`BR-PO-005`
`lineItems.unitPriceVnd`	Integer	Có	Đơn giá một đơn vị tính bằng VND. Phải lớn hơn hoặc bằng 0.	`BR-FIN-015`

Responses (Phản hồi)

Phản hồi thành công: 201 Created

Khi PO được tạo thành công, API trả HTTP 201 Created và đối tượng JSON chứa ID, trạng thái, thời điểm tạo PO.

Ví dụ Response Body:

{
  "purchaseOrderId": "PO-2026-08-1138",
  "status": "PENDING_APPROVAL",
  "createdAt": "2026-08-07T14:30:00Z"
}

Các phản hồi lỗi thường gặp

Mã HTTP	Tên Lỗi	Nguyên nhân Kịch bản (Nova Foods)
`400 Bad Request`	Yêu cầu không hợp lệ	Client thiếu trường bắt buộc như `supplierId`, sai định dạng như `requestedDeliveryDate` không phải `YYYY-MM-DD`, hoặc vi phạm quy tắc nghiệp vụ như `quantity` âm.
`401 Unauthorized`	Không được xác thực	Client gọi API không gửi access token hợp lệ.
`403 Forbidden`	Bị từ chối	Client đã xác thực nhưng không có quyền tạo PO, ví dụ tài khoản chỉ có quyền xem.
`404 Not Found`	Không tìm thấy	ID tham chiếu không tồn tại, ví dụ `supplierId` hoặc `productId` không có trong cơ sở dữ liệu.
`500 Internal Server Error`	Lỗi Máy chủ Nội bộ	ERP gặp lỗi không mong muốn khi xử lý yêu cầu. Client phải dùng thông tin truy vết do server trả về để báo sự cố.

Phân tích, Lựa chọn và Quyết định

Phần này ghi nhận phân tích nghiệp vụ dẫn đến đặc tả API tạo PO. Nội dung gồm hiện trạng, nhu cầu, phương án, tiêu chí, quyết định, thẩm quyền và hậu quả.

1. Sự thật và Hiện trạng (Facts & Current Behavior)

Quy trình tạo PO hiện tại hoàn toàn thủ công. Bộ phận Mua hàng dùng email và tệp PROC-F-01_PurchaseRequest.xlsx dùng chung để tạo, theo dõi yêu cầu. Kế toán nhập tay dữ liệu từ Excel vào phần mềm kế toán độc lập.

Vấn đề: Quy trình chậm, dễ nhầm mã hàng, giá và nhà cung cấp; không cung cấp tình trạng mua hàng thời gian thực.
Hậu quả: Việc truy vết và đối chiếu chứng từ cuối kỳ tốn thời gian. Nova Foods khó đánh giá hiệu quả nhà cung cấp, quản lý chi tiêu và duy trì dữ liệu nhất quán.

2. Nhu cầu Nghiệp vụ Cốt lõi (Underlying Need)

Nova Foods cần phương thức có cấu trúc, tự động và kiểm soát để tạo, quản lý PO trong ERP tập trung.

Mục tiêu nghiệp vụ:
Giảm >90% lỗi nhập liệu liên quan đến PO.
Tăng tốc độ xử lý từ yêu cầu đến gửi PO cho nhà cung cấp ít nhất 50%.
Cung cấp dữ liệu đầu vào đáng tin cậy cho Nhận hàng (Goods Receipt), Kho (Inventory) và Kế toán Phải trả (Accounts Payable).
Yêu cầu tuân thủ: Đây là yêu cầu nền tảng cho truy xuất nguồn gốc theo Luật An toàn thực phẩm (Luật 55/2010/QH12), cần liên kết nguyên liệu đầu vào với sản phẩm cuối cùng.

3. Các Phương án, Tiêu chí và Quyết định

Ba phương án được xem xét. Nhóm dự án đánh giá theo tiêu chí có trọng số:

Tiêu chí	Trọng số	Lựa chọn 1: Xây dựng UI đầy đủ trước	Lựa chọn 2: Mua giải pháp SaaS bên thứ ba	Lựa chọn 3: Xây dựng API-first (được chọn)
Tốc độ cung cấp giá trị ban đầu	Cao	Thấp, cần nhiều tháng hoàn thiện UI	Trung bình, cần thời gian tích hợp	Cao, API dùng để nhập liệu ngay
Chi phí ban đầu	Cao	Trung bình, chi phí nhân sự phát triển	Cao, phí bản quyền và triển khai	Thấp, tập trung logic cốt lõi
Tính linh hoạt tích hợp	Trung bình	Trung bình, phụ thuộc thiết kế UI	Thấp, bị khóa bởi nhà cung cấp	Cao, làm nền tảng cho UI và tích hợp
Khả năng kiểm soát dữ liệu	Cao	Cao, dữ liệu on-premise	Thấp, dữ liệu nằm ở bên thứ ba	Cao, dữ liệu on-premise
Phù hợp chiến lược ERP lõi	Thấp	Trung bình, có thể tạo hệ thống biệt lập	Thấp, phá vỡ kiến trúc hợp nhất	Cao, xây dựng năng lực từ lõi

Đề xuất và Thẩm quyền

Quyết định: Triển khai Lựa chọn 3: Xây dựng API-first.
Lý do: Phương án cung cấp giá trị sớm với chi phí ban đầu thấp, chuẩn hóa luồng dữ liệu qua API, hỗ trợ UI hoặc tích hợp tương lai và giảm nguy cơ tạo nợ kỹ thuật.
Người đề xuất: BA Trưởng, Nhóm dự án ERP.
Người quyết định: Trưởng phòng CNTT, Trưởng phòng Mua hàng.
Mã quyết định (giả lập): DEC-API-001-20260807
Trạng thái quyết định trong artifact: IN_REVIEW. Mã quyết định ghi nhận bối cảnh mô phỏng; không thể hiện artifact đã được phê duyệt hoặc Baselined.
Trade-off: API-first giảm chi phí và tăng linh hoạt tích hợp ban đầu, nhưng chưa cung cấp UI hoàn chỉnh cho người dùng nghiệp vụ.
Hệ quả: Nhóm ERP phải duy trì kiểm soát xác thực, phân quyền, xác thực dữ liệu và idempotency trước khi mở rộng tích hợp hoặc xây UI.

4. Hậu quả nếu Quyết định Sai (Consequence if Wrong)

Nếu API thiết kế sai: Dữ liệu đầu vào bị hỏng, gây sai lệch tồn kho và công nợ. Nova Foods phải sửa dữ liệu, làm lại API và có thể trì hoãn lộ trình ERP.
Nếu kiểm soát quyền không đủ: Lỗ hổng Broken Function Level Authorization (OWASP API Security Top 10 - API5:2023) có thể cho phép người không có thẩm quyền tạo hoặc chỉnh sửa PO.
Hậu quả nghiệp vụ: PO không hợp lệ có thể dẫn đến gian lận, thất thoát tài chính, sai lệch cam kết mua hàng và khó truy vết nguyên liệu.
Hành động kiểm soát: Server phải kiểm tra token, scope purchase_orders:create, dữ liệu nhà cung cấp, danh mục vật tư, quy tắc ngày giao, số lượng, đơn giá và Idempotency-Key trước khi tạo PO.

4. Tier 3 ? Fully Completed Nova Foods Case: Evidence and Traceability

Phần này cung cấp bằng chứng, truy vết, và các yếu tố kiểm soát cho đặc tả API. Nó không định nghĩa yêu cầu mới, mà liên kết các yêu cầu đã có và làm rõ các rủi ro, giả định.

4.1. Ma trận Truy vết Yêu cầu (Traceability Matrix)

Ma trận truy vết, hay Traceability Matrix, là một bảng thể hiện mối liên kết hai chiều giữa các artifact của dự án. Nó chứng minh rằng mọi nhu cầu nghiệp vụ (Need) đều được chuyển thành yêu cầu (Requirement), được kiểm thử (Test Case), và được hiện thực hóa (API/Data). Điều này đảm bảo không có yêu cầu nào bị bỏ sót và mọi thứ được xây dựng đều có lý do.

Kịch bản: Tạo Đơn Mua Hàng (Purchase Order) cho Nova Foods.

ID Nguồn (Source)	Loại	ID Đích (Target)	Loại	Diễn giải mối quan hệ
`NEED-001`	Business Need	`REQ-002`	Functional Req.	Nhu cầu tạo PO điện tử được đáp ứng bởi yêu cầu hệ thống cho phép tạo PO qua API.
`REQ-002`	Functional Req.	`BR-PO-001`	Business Rule	Yêu cầu tạo PO phải tuân thủ quy tắc nghiệp vụ là PO phải có nhà cung cấp.
`REQ-002`	Functional Req.	`BR-PO-003`	Business Rule	Yêu cầu tạo PO phải tuân thủ quy tắc về việc người dùng phải có quyền hạn phù hợp.
`REQ-002`	Functional Req.	`DATA/API-001`	API Endpoint	Yêu cầu được hiện thực hóa bởi endpoint `POST /api/v1/purchase-orders`.
`AC-REQ-002-01`	Acceptance Crit.	`TC-API-001-P`	Test Case (Positive)	Tiêu chí chấp nhận cho luồng thành công được xác minh bằng một ca kiểm thử dương tính.
`AC-REQ-002-03`	Acceptance Crit.	`TC-API-001-N-AUTH`	Test Case (Negative)	Tiêu chí chấp nhận cho lỗi phân quyền được xác minh bằng ca kiểm thử âm tính.
`OWASP API5:2023`	Security Risk	`AC-REQ-002-03`	Acceptance Crit.	Rủi ro Broken Function Level Authorization được giảm thiểu bằng tiêu chí chấp nhận yêu cầu xác thực quyền hạn.

4.2. Các Trường hợp Ngoại lệ và Luồng Tiêu cực (Exceptions and Negative Paths)

Luồng tiêu cực (Negative Path) mô tả cách hệ thống phản ứng với dữ liệu không hợp lệ hoặc các tình huống lỗi. Việc định nghĩa rõ các luồng này là tối quan trọng để xây dựng một API vững chắc và an toàn.

ID Lỗi	Kịch bản Lỗi (Negative Path)	Tác nhân (Trigger)	Phản hồi API mong đợi	Tham chiếu
`E_PO_VAL_001`	Thiếu thông tin bắt buộc: ID nhà cung cấp (`supplierId`) bị null hoặc rỗng.	Gửi request tạo PO không có trường `supplierId`.	`400 Bad Request` với payload: `{"errorCode": "E_PO_VAL_001", "message": "Supplier ID is required."}`	`BR-PO-001`
`E_PO_VAL_002`	Dữ liệu không hợp lệ: `productId` trong một `lineItem` không tồn tại trong hệ thống.	Gửi request tạo PO với một `productId` không có trong bảng `Products`.	`400 Bad Request` với payload: `{"errorCode": "E_PO_VAL_002", "message": "Product with ID 'PROD-99999' not found."}`	`BR-PO-005`
`E_PO_VAL_003`	Dữ liệu sai logic nghiệp vụ: `quantity` là số âm.	Gửi request tạo PO với một `lineItem` có `quantity: -5`.	`400 Bad Request` với payload: `{"errorCode": "E_PO_VAL_003", "message": "Quantity must be a positive number."}`	`BR-PO-006`
`E_AUTH_001`	Không có quyền hạn: người dùng đã xác thực nhưng không thuộc nhóm "Purchasing Staff".	Người dùng thuộc nhóm "Sales" cố gắng gọi endpoint `POST /api/v1/purchase-orders`.	`403 Forbidden` với payload: `{"errorCode": "E_AUTH_001", "message": "User does not have permission to create purchase orders."}`	`AC-REQ-002-03`

4.3. Giả định và Hạng mục cần Xác minh (Assumptions & Verification-Required Items)

Ghi nhận rõ ràng các giả định (Assumptions) và các điểm cần chuyên gia xác minh (Verification Required) giúp phân định trách nhiệm và giảm rủi ro do hiểu sai.

Bảng Giả định (Assumptions)

ID	Giả định (Assumption)	Lý do Giả định	Ảnh hưởng nếu Sai
`ASMP-API-001-01`	Dữ liệu nhà cung cấp và sản phẩm đã tồn tại và chính xác trong ERP trước khi tạo PO.	API này chỉ tập trung vào việc tạo giao dịch PO, không quản lý dữ liệu gốc (master data).	PO sẽ được tạo với thông tin sai lệch về nhà cung cấp/sản phẩm, gây sai sót trong tồn kho và công nợ.
`ASMP-API-001-02`	Tỷ giá ngoại tệ được xử lý bởi một module tài chính riêng. API này chỉ nhận `currencyCode` là 'VND'.	Để đơn giản hóa phạm vi của đặc tả API này và tránh sự phức tạp của việc tích hợp tỷ giá.	API sẽ không thể xử lý các đơn hàng quốc tế. Cần một Change Request để mở rộng chức năng này.

Bảng Hạng mục cần Xác minh (Verification-Required Items)

ID	Hạng mục cần Xác minh	Tại sao cần Xác minh	Vai trò cần Xác minh
`VER-API-001-01`	Quy tắc tính thuế GTGT (VAT) cho từng loại sản phẩm có chính xác không?	Logic thuế phức tạp và có thể thay đổi. BA không có thẩm quyền quyết định về kế toán.	Phòng Kế toán
`VER-API-001-02`	Quy trình phê duyệt PO (ví dụ: PO trên 50,000,000 VND cần Trưởng phòng Mua hàng duyệt) sẽ được áp dụng như thế nào với API?	API hiện tại tạo PO ở trạng thái `DRAFT`. Luồng phê duyệt là một quy tắc nghiệp vụ quan trọng cần được xác nhận.	Trưởng phòng Mua hàng
`VER-API-001-03`	Tính pháp lý của một đơn mua hàng được tạo hoàn toàn qua API (không có chữ ký số) có tuân thủ Nghị định 123/2020/NĐ-CP không?	Để đảm bảo các chứng từ điện tử được tạo ra có giá trị pháp lý, tránh rủi ro tranh chấp với nhà cung cấp.	Phòng Pháp chế

4.4. Ghi nhận Leo thang (Escalation Record)

Việc leo thang (escalation) xảy ra khi một vấn đề vượt quá thẩm quyền của nhóm dự án.

Vấn đề được ghi nhận: Kết quả từ VER-API-001-03.
Kịch bản: Nếu Phòng Pháp chế xác nhận rằng một đơn mua hàng điện tử thiếu chữ ký số không đủ giá trị pháp lý cho mục đích kiểm toán hoặc giải quyết tranh chấp, đây là một rào cản lớn.
Hành động: BA sẽ lập tức tạo một bản ghi vấn đề (Issue Log), thông báo cho Quản lý Dự án (Project Manager) và leo thang lên cho nhà tài trợ dự án (Project Sponsor).
Lý do leo thang: Vấn đề này có thể yêu cầu thay đổi lớn về phạm vi (bổ sung tích hợp chữ ký số), tăng chi phí và kéo dài thời gian dự án, đòi hỏi một quyết định ở cấp cao hơn.

Ma trận Truy vết Yêu cầu (Requirements Traceability Matrix - RTM)

Ma trận Truy vết Yêu cầu (thường gọi là RTM, viết tắt của Requirements Traceability Matrix) là một công cụ quản trị cốt lõi, dùng để tạo ra một bản đồ liên kết tường minh và có thể kiểm chứng được giữa các artifact trong vòng đời phát triển phần mềm. Mục tiêu của nó là đảm bảo mọi nhu cầu kinh doanh ban đầu đều được chuyển hóa thành các yêu cầu cụ thể, sau đó được thiết kế, hiện thực hóa, và cuối cùng là được kiểm thử đầy đủ. Ngược lại, nó cũng đảm bảo rằng không có chức năng nào được xây dựng hoặc kiểm thử mà không bắt nguồn từ một yêu cầu đã được phê duyệt, giúp tránh lãng phí nguồn lực.

Bảng dưới đây trình bày ma trận truy vết cho chức năng "Tiếp nhận hóa đơn nhà cung cấp qua API" trong hệ thống ERP mô phỏng của Nova Foods. Toàn bộ định danh (ID) được sử dụng trong bảng này tuân thủ quy tắc đặt tên tại /01-curriculum/TRACEABILITY_ID_REGISTRY.md để đảm bảo tính nhất quán và duy nhất trên toàn bộ tài liệu của dự án.

ID Nguồn (Upstream)	Loại Nguồn	ID Đích (Downstream)	Loại Đích	Lý do liên kết / Ghi chú
`NEED-001`	Business Need	`REQ-004`	Functional Requirement	Nhu cầu `NEED-001` (Tự động hóa quy trình nhận và xử lý hóa đơn nhà cung cấp) được hiện thực hóa bởi yêu cầu chức năng `REQ-004` (Hệ thống phải cung cấp API cho nhà cung cấp nộp hóa đơn điện tử).
`REQ-004`	Functional Requirement	`API-001`	API Specification	Đặc tả `API-001` (tài liệu này) là giải pháp kỹ thuật được chọn để đáp ứng yêu cầu `REQ-004`.
`REQ-004`	Functional Requirement	`BR-INV-01`	Business Rule	Yêu cầu `REQ-004` phải tuân thủ quy tắc `BR-INV-01` (Số hóa đơn phải là duy nhất cho mỗi nhà cung cấp trong cùng một năm tài chính).
`REQ-004`	Functional Requirement	`BR-INV-02`	Business Rule	Yêu cầu `REQ-004` phải tuân thủ quy tắc `BR-INV-02` (Tổng tiền trên hóa đơn phải là một số dương).
`REQ-004`	Functional Requirement	`AC-004.1`	Acceptance Criterion	Tiêu chí chấp nhận `AC-004.1` định nghĩa điều kiện "hoàn thành" cho `REQ-004` trong trường hợp nộp thành công (happy path).
`REQ-004`	Functional Requirement	`AC-004.2`	Acceptance Criterion	Tiêu chí chấp nhận `AC-004.2` định nghĩa phản hồi hệ thống khi `REQ-004` thất bại do vi phạm `BR-INV-01` (số hóa đơn trùng lặp).
`SEC-002`	Security Requirement	`API-001`	API Specification	Yêu cầu bảo mật `SEC-002` (Chỉ những nhà cung cấp đã xác thực và được cấp quyền mới có thể gọi API này) được áp dụng khi thiết kế `API-001`.
`API-001`	API Specification	`TC-API-001-01`	Test Case	Ca kiểm thử `TC-API-001-01` là một phần của bộ kiểm thử (test suite) toàn diện cho `API-001`.
`API-001`	API Specification	`TC-API-001-02`	Test Case	Ca kiểm thử `TC-API-001-02` là một phần của bộ kiểm thử (test suite) toàn diện cho `API-001`.
`AC-004.1`	Acceptance Criterion	`TC-API-001-01`	Test Case	Ca kiểm thử `TC-API-001-01` được viết để xác minh `AC-004.1` đã được đáp ứng (nộp thành công với dữ liệu hợp lệ).
`BR-INV-01`	Business Rule	`TC-API-001-02`	Test Case	Ca kiểm thử `TC-API-001-02` xác minh hệ thống đã thực thi đúng quy tắc `BR-INV-01`, từ chối hóa đơn có số trùng lặp.
`BR-INV-02`	Business Rule	`TC-API-001-03`	Test Case	Ca kiểm thử `TC-API-001-03` xác minh hệ thống đã thực thi đúng quy tắc `BR-INV-02`, từ chối hóa đơn có tổng tiền bằng 0 hoặc âm.
`SEC-002`	Security Requirement	`TC-API-001-04`	Test Case	Ca kiểm thử `TC-API-001-04` xác minh việc truy cập API thất bại nếu không có token xác thực hợp lệ hoặc không đủ quyền.

Bảng trên thể hiện hai chiều truy vết chính: 1. Truy vết xuôi (Forward Traceability): Đi từ trái sang phải (NEED → REQ → API-SPEC → TC). Chiều này giúp trả lời câu hỏi: "Yêu cầu này đã được hiện thực và kiểm thử chưa?". Nó đảm bảo tất cả các yêu cầu đều được chuyển thành sản phẩm có thể kiểm chứng. 2. Truy vết ngược (Backward Traceability): Đi từ phải sang trái (TC → API-SPEC → REQ → NEED). Chiều này giúp trả lời câu hỏi: "Tại sao ca kiểm thử này tồn tại?" hoặc "Tại sao chúng ta lại xây dựng chức năng này?". Nó đảm bảo không có mã lệnh hay kiểm thử thừa ("gold plating") và mọi nỗ lực đều gắn với một giá trị kinh doanh cụ thể.

Ví dụ Payload, Dữ liệu Test và Bằng chứng Truy vết

Phần này cung cấp các ví dụ cụ thể về payload, dữ liệu test, và bằng chứng truy vết để làm rõ yêu cầu cho API tạo đơn đặt hàng (POST /api/v1/purchase-orders). Payload là khối dữ liệu thực tế được gửi đi trong một yêu cầu (request) hoặc nhận về trong một phản hồi (response) của API. Nó thường ở định dạng JSON (JavaScript Object Notation), một định dạng văn bản nhẹ, dễ đọc cho người và dễ phân tích cho máy, dùng để trao đổi dữ liệu.

Payload mẫu cho Request (Yêu cầu) hợp lệ (HTTP 201 Created)

Đây là một ví dụ về payload mà một hệ thống client (ví dụ: ứng dụng web quản lý kho của Nova Foods) sẽ gửi đến ERP để tạo một đơn đặt hàng mới cho nhà cung cấp "Công ty TNHH Thực phẩm An Bình". Request này chứa tất cả thông tin cần thiết và hợp lệ.

{
  "supplierId": "NCC-ANBINH-001",
  "orderDate": "2026-09-15T10:00:00Z",
  "expectedDeliveryDate": "2026-09-25",
  "currency": "VND",
  "lineItems": [
    {
      "productId": "SP-THITHEO-01KG",
      "productName": "Thịt heo xay hữu cơ",
      "quantity": 100,
      "unit": "kg",
      "unitPrice": 150000
    },
    {
      "productId": "SP-RAUCAI-XANH",
      "productName": "Rau cải xanh VietGAP",
      "quantity": 50,
      "unit": "bó",
      "unitPrice": 15000
    }
  ],
  "notes": "Giao hàng trước 3 giờ chiều."
}

Payload mẫu cho Response (Phản hồi) thành công (HTTP 201 Created)

Khi request ở trên được xử lý thành công, API sẽ trả về mã trạng thái HTTP 201 Created và một payload chứa thông tin chi tiết của đơn hàng vừa được tạo. Phản hồi bao gồm ID của đơn hàng (purchaseOrderId) do hệ thống sinh ra và các giá trị đã được tính toán như tổng tiền, tuân thủ quy tắc nghiệp vụ.

{
  "purchaseOrderId": "PO-2026-00123",
  "status": "PENDING_APPROVAL",
  "supplierId": "NCC-ANBINH-001",
  "orderDate": "2026-09-15T10:00:00Z",
  "expectedDeliveryDate": "2026-09-25",
  "currency": "VND",
  "lineItems": [
    {
      "lineItemId": 1,
      "productId": "SP-THITHEO-01KG",
      "productName": "Thịt heo xay hữu cơ",
      "quantity": 100,
      "unit": "kg",
      "unitPrice": 150000,
      "lineTotal": 15000000
    },
    {
      "lineItemId": 2,
      "productId": "SP-RAUCAI-XANH",
      "productName": "Rau cải xanh VietGAP",
      "quantity": 50,
      "unit": "bó",
      "unitPrice": 15000,
      "lineTotal": 750000
    }
  ],
  "subtotal": 15750000,
  "vatAmount": 1575000,
  "totalAmount": 17325000,
  "createdAt": "2026-09-15T10:00:05Z",
  "createdBy": "user_nhapkho_01"
}

Payload mẫu cho Response (Phản hồi) lỗi (HTTP 422 Unprocessable Entity)

Nếu request thiếu trường bắt buộc như supplierId, API phải trả về mã lỗi phía client, ví dụ 422 Unprocessable Entity, để chỉ ra rằng server hiểu request nhưng không thể xử lý do lỗi ngữ nghĩa trong dữ liệu. Payload của response sẽ mô tả chi tiết lỗi để client có thể sửa và gửi lại.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Dữ liệu cung cấp không hợp lệ.",
    "details": [
      {
        "field": "supplierId",
        "issue": "Trường supplierId là bắt buộc và không được để trống."
      }
    ]
  }
}

Bảng Dữ liệu Test (Test Data) và Truy vết

Dữ liệu test được dùng để xác minh các tiêu chí chấp nhận (Acceptance Criteria) và quy tắc nghiệp vụ (Business Rules). Bảng dưới đây cung cấp các trường hợp kiểm thử (Test Cases) cụ thể, liên kết trực tiếp đến các yêu cầu tương ứng để đảm bảo tính toàn vẹn và có thể truy vết nguồn gốc.

ID Test Case	Mô tả	Dữ liệu đầu vào (Tóm tắt)	Kết quả mong đợi	Traceability
`TC-NF-PO-001`	Happy path: Tạo đơn đặt hàng thành công với đầy đủ thông tin hợp lệ.	`supplierId` hợp lệ, `lineItems` có ít nhất 1 sản phẩm.	HTTP Status: `201 Created`. Response body chứa `purchaseOrderId` và `totalAmount` được tính đúng. Trạng thái đơn hàng là `PENDING_APPROVAL`.	`AC-NF-PO-001.1`, `AC-NF-PO-001.3`, `BR-NF-TAX-001`
`TC-NF-PO-002`	Negative path: Tạo đơn đặt hàng thiếu `supplierId`.	`supplierId` là `null` hoặc không có trong request.	HTTP Status: `422 Unprocessable Entity`. Response body chứa thông báo lỗi cho trường `supplierId`.	`AC-NF-PO-001.2`
`TC-NF-PO-003`	Negative path: Tạo đơn đặt hàng không có sản phẩm nào (`lineItems` rỗng).	Mảng `lineItems` là `[]`.	HTTP Status: `422 Unprocessable Entity`. Response body chứa thông báo lỗi cho trường `lineItems`.	`AC-NF-PO-001.4`
`TC-NF-PO-004`	Boundary: Tạo đơn hàng có `unitPrice` bằng 0.	Một `lineItem` có `unitPrice: 0`.	HTTP Status: `422 Unprocessable Entity`. Response body chứa thông báo lỗi cho `unitPrice` (phải > 0).	`BR-NF-VALID-015`
`TC-NF-PO-005`	Boundary: Tính toán `totalAmount` với số lượng lớn.	`quantity: 10000`, `unitPrice: 999999`.	HTTP Status: `201 Created`. `totalAmount` được tính toán chính xác, không bị tràn số (overflow).	`BR-NF-TAX-001`

5. Tier 4 – Senior BA Quality Gate

Cổng chất lượng (Quality Gate) này là bước rà soát cuối cùng do Senior BA thực hiện trước khi một artifact, như đặc tả API này, được đề xuất để baseline. Mục đích là để đảm bảo artifact đáp ứng các tiêu chuẩn tối thiểu về tính đầy đủ, nhất quán, và sẵn sàng cho các giai đoạn sau (phát triển, kiểm thử, tuân thủ).

Danh sách kiểm tra dưới đây định nghĩa các tiêu chí này. Mỗi mục phải được đánh giá. Kết quả của một mục là ĐẠT (Pass) hoặc DỪNG (Stop). Bất kỳ kết quả DỪNG nào cũng sẽ tạm dừng quy trình và yêu cầu hành động khắc phục.

5.1. Danh sách kiểm tra chất lượng (Quality Checklist)

ID	Hạng mục kiểm tra	Tiêu chí ĐẠT (Pass Criteria)	Tiêu chí DỪNG (Stop Criteria)	Hành động khi DỪNG
`QG-API-01`	Tính đầy đủ (Completeness): Các mục bắt buộc	Tất cả các mục trong template (Tier 2) đã được điền đầy đủ trong ví dụ Nova Foods (Tier 3). Không có mục nào bị bỏ trống, hoặc ghi `TBD`, `TODO` mà không có lý do chính đáng và ID theo dõi.	Một hoặc nhiều trường, payload, hoặc section bị bỏ trống mà không có giải trình được chấp nhận.	`FAIL`: Yêu cầu bổ sung thông tin.
`QG-API-02`	Tính nhất quán (Consistency): Thuật ngữ và Định danh	Các thuật ngữ, tên trường và định danh (ví dụ `BR-NF-...`, `AC-NF-...`) nhất quán trong toàn bộ tài liệu và khớp với các artifact gốc như `CANONICAL_DATA_DICTIONARY` và `TRACEABILITY_ID_REGISTRY`.	Sử dụng thuật ngữ/ID không nhất quán, tự chế, hoặc mâu thuẫn với các nguồn canonical đã được định nghĩa trong corpus.	`FAIL`: Chỉnh sửa lại cho đồng bộ.
`QG-API-03`	Tính khả kiểm (Testability): Tiêu chí chấp nhận	Mỗi Tiêu chí Chấp nhận (Acceptance Criteria - AC) đủ rõ ràng, cụ thể và có thể đo lường để một QA có thể viết kịch bản kiểm thử (test case) mà không cần hỏi lại. Ví dụ: "Hệ thống phải nhanh" là không thể kiểm thử; "Hệ thống phải trả về kết quả trong vòng 500ms" là có thể.	Tiêu chí chấp nhận mơ hồ, chung chung, hoặc mang tính chủ quan.	`FAIL`: Yêu cầu viết lại AC cho rõ ràng.
`QG-API-04`	Khả năng truy vết (Traceability): Liên kết yêu cầu	Mọi yêu cầu, quy tắc nghiệp vụ, và tiêu chí chấp nhận đều được liên kết với nhau một cách logic. Bảng `Traceability` trong Section 4 đã được điền đúng, thể hiện rõ AC nào xác thực cho yêu cầu nào.	Liên kết bị đứt gãy, sai lệch, hoặc thiếu. Không thể truy ngược từ một test case về yêu cầu nghiệp vụ ban đầu.	`FAIL`: Cập nhật lại ma trận/bảng truy vết.
`QG-API-05`	Thẩm quyền nguồn (Source Authority): Quy tắc nghiệp vụ	Các quy tắc nghiệp vụ (Business Rules - BR) có nguồn gốc rõ ràng. Các quy tắc liên quan đến pháp lý, kế toán, thuế (ví dụ `BR-NF-TAX-001`) phải được ghi chú là `Verification required` từ chủ sở hữu tương ứng (Legal, Accounting).	Một quy tắc nghiệp vụ quan trọng được suy diễn hoặc tự đặt ra mà không có nguồn gốc hoặc bằng chứng từ Business Owner hoặc tài liệu pháp quy.	`ESCALATE`: Chuyển cho Business Owner hoặc chủ sở hữu chuyên môn để xác nhận.
`QG-API-06`	Ranh giới nghiệp vụ (Business Boundaries): Kế toán & Pháp lý	Các trường dữ liệu hoặc logic có ảnh hưởng đến sổ sách kế toán (ví dụ `totalAmount`, `taxAmount`) hoặc tuân thủ pháp luật (ví dụ `personalDataFlag`) phải được đánh dấu rõ ràng và chỉ ra sự cần thiết phải có xác minh từ bộ phận chuyên trách.	Đặc tả API định nghĩa một logic tính toán tài chính hoặc xử lý dữ liệu nhạy cảm như một yêu cầu đã được chốt mà không có bằng chứng xác nhận từ Kế toán hoặc Pháp chế.	`ESCALATE`: Dừng lại và yêu cầu xác nhận từ chủ sở hữu Kế toán/Pháp chế.
`QG-API-07`	Ranh giới kỹ thuật (Technical Boundaries): Bảo mật & Dữ liệu	Các yêu cầu bảo mật (ví dụ: xác thực, phân quyền) đã được xem xét và tham chiếu đến các tiêu chuẩn như OWASP API Security Top 10. Các trường chứa Thông tin nhận dạng cá nhân (PII - Personally Identifiable Information) được đánh dấu.	API cho phép truy cập dữ liệu nhạy cảm mà không định nghĩa cơ chế xác thực/phân quyền. Không xác định PII trong các payload.	`ESCALATE`: Chuyển cho Security Architect hoặc Data Governor để xem xét và bổ sung yêu cầu.
`QG-API-08`	Tác động thay đổi (Change Impact): Phụ thuộc hệ thống	Phần `Impact Analysis` xác định được các hệ thống, quy trình hoặc vai trò người dùng khác bị ảnh hưởng bởi việc triển khai API này.	Bỏ qua phân tích tác động, hoặc tuyên bố "không có tác động" mà không có cơ sở rõ ràng, đặc biệt với các API lõi như `Purchase Order`.	`FAIL`: Yêu cầu thực hiện phân tích tác động đầy đủ.

5.2. Tiêu chí ra quyết định tổng thể

Dựa trên kết quả của checklist ở trên:

PASS: Tất cả các mục đều đạt ĐẠT. Artifact được xem là đủ chất lượng để chuyển sang bước đề xuất baseline.
FAIL & REWORK: Có ít nhất một mục DỪNG với hành động là FAIL. Artifact bị trả lại cho người soạn thảo để khắc phục các lỗi đã chỉ ra. Sau khi sửa, artifact phải được review lại từ đầu.
STOP & ESCALATE: Có ít nhất một mục DỪNG với hành động là ESCALATE. Quá trình review bị tạm dừng. Vấn đề sẽ được đóng gói và chuyển lên cấp có thẩm quyền (ví dụ: Business Owner, Architect, Legal) để ra quyết định. Quá trình chỉ tiếp tục khi có phản hồi chính thức.

Danh mục Tiêu chí Chất lượng (Quality Gate Checklist)

Bảng này định nghĩa các tiêu chí chất lượng mà một Senior BA sử dụng để rà soát đặc tả API trước khi đưa vào baseline. Một đặc tả phải đạt tất cả các tiêu chí. Một hạng mục có kết quả FAIL yêu cầu phải làm lại (rework). Một hạng mục có kết quả STOP yêu cầu phải dừng ngay lập tức và chuyển vấn đề đến vai trò có thẩm quyền (escalation).

Hạng mục Kiểm tra	Mô tả & Tiêu chí "Đạt" (Pass Criteria)	Nguồn tham chiếu & Lý do	Hệ quả nếu "Không Đạt"
Tính đầy đủ (Completeness)	Tất cả các mục trong template đã được điền đầy đủ. Mọi trường dữ liệu (field) trong request/response body đều có mô tả, kiểu dữ liệu, định dạng (nếu có) và giá trị ví dụ. Tất cả các mã lỗi HTTP có thể xảy ra đều được định nghĩa rõ ràng.	OpenAPI Specification v3.1.1. Lý do: Tránh việc đội phát triển và đội kiểm thử phải tự suy diễn, giảm rủi ro hiểu sai yêu cầu.	FAIL. Developer/QA làm việc dựa trên giả định. Gây tốn thời gian và chi phí để làm rõ hoặc sửa lỗi sau này.
Tính nhất quán (Consistency)	Thuật ngữ sử dụng trong đặc tả API phải khớp hoàn toàn với `CANONICAL_DATA_DICTIONARY`. Các quy tắc nghiệp vụ được mô tả phải nhất quán với `CANONICAL_BUSINESS_RULES`. Hành vi giữa các endpoint không được mâu thuẫn (ví dụ: cùng một phương thức xác thực, cùng một cấu trúc báo lỗi).	`CANONICAL_DATA_DICTIONARY.md`, `CANONICAL_BUSINESS_RULES.md`. Lý do: Đảm bảo chỉ có một nguồn chân lý (Single Source of Truth), tránh xung đột trong logic và dữ liệu.	FAIL. Rủi ro cao về lỗi tích hợp và hành vi không nhất quán của hệ thống. Yêu cầu làm lại để đồng bộ với các artifact canonical.
Tính khả kiểm (Testability)	Mọi yêu cầu chức năng và phi chức năng đều có thể xác minh được. Tiêu chí chấp thuận (Acceptance Criteria) phải cụ thể, đo lường được. Không sử dụng các thuật ngữ mơ hồ như "nhanh", "hiệu quả", "thân thiện" nếu không đi kèm chỉ số hoặc ngưỡng đo lường cụ thể.	ISTQB CTFL Syllabus v4.0.1. Lý do: Nếu một yêu cầu không thể kiểm thử, nó không thể được xây dựng một cách chính xác và không thể nghiệm thu.	FAIL. Đội QA không thể viết kịch bản kiểm thử (test case) đầy đủ. Rủi ro cao về việc bàn giao sản phẩm không đáp ứng đúng nhu cầu.
Tính truy vết (Traceability)	Mỗi endpoint, trường dữ liệu quan trọng, và quy tắc nghiệp vụ được triển khai trong API phải có liên kết ngược (trace back) rõ ràng đến một hoặc nhiều ID yêu cầu (`REQ-NF-XXX`) hoặc ID quy tắc nghiệp vụ (`BR-NF-XXX`) đã được định danh trong `TRACEABILITY_ID_REGISTRY`.	BABOK Guide v3 (Requirements Traceability). Lý do: Chứng minh sự cần thiết của từng thành phần, phục vụ phân tích tác động thay đổi và kiểm toán (audit).	FAIL. Yêu cầu "mồ côi" (orphan requirement). Không thể đánh giá tác động khi có thay đổi. Gây khó khăn khi cần giải trình với các bên liên quan.
Thẩm quyền nguồn (Source Authority)	Nguồn của mọi yêu cầu liên quan đến pháp lý, kế toán, thuế hoặc tuân thủ phải được trích dẫn từ văn bản gốc đã xác minh (ví dụ: `Luật Kế toán 88/2015/QH13`, `Nghị định 123/2020/NĐ-CP`). Các quyết định nghiệp vụ phải được gán cho vai trò Business Owner cụ thể.	`00-research/00_SOURCE_MAP.md`. Lý do: Đảm bảo các yêu cầu không dựa trên thông tin không chính thức, diễn giải cá nhân hoặc giả định sai.	FAIL. Rủi ro cao về việc không tuân thủ quy định. Cần phải xác minh lại thông tin từ các Owner có thẩm quyền (Legal, Accounting...).
Quyền sở hữu (Ownership)	Mỗi nhóm dữ liệu logic phải có một Data Owner được xác định. Mỗi quy tắc nghiệp vụ quan trọng phải có Business Owner. Toàn bộ API phải có một Product Owner chịu trách nhiệm về mặt kỹ thuật và sản phẩm.	Nguyên tắc quản trị trong kiến trúc corpus. Lý do: Thiết lập trách nhiệm giải trình rõ ràng cho việc ra quyết định, chất lượng dữ liệu và quản lý thay đổi.	FAIL. Gây mơ hồ trong việc ra quyết định. Làm chậm quá trình xử lý sự cố, yêu cầu thay đổi và cải tiến sản phẩm.
Ranh giới (Boundaries)	Đặc tả phải xác định và tôn trọng các ranh giới: 1. Bảo mật: Xác thực và phân quyền được mô tả rõ. Các rủi ro trong danh sách OWASP API Security Top 10 được xem xét. 2. Riêng tư: Nhận diện Dữ liệu định danh cá nhân (PII - Personally Identifiable Information) và chỉ rõ cách xử lý tuân thủ `Luật Bảo vệ dữ liệu cá nhân`. 3. Pháp lý/Kế toán: Các logic liên quan đến tài chính, hóa đơn, chứng từ không được vi phạm `Luật Kế toán`. Các điểm nhạy cảm này phải được gắn nhãn `Verification Required`.	OWASP API Security Top 10 (2023), Luật 91/2025/QH15, Luật 88/2015/QH13. Lý do: Quản lý rủi ro, tránh lỗ hổng bảo mật, vi phạm pháp luật và sai sót tài chính.	STOP. Dừng và chuyển ngay cho Security Owner, Legal Owner, hoặc Accounting Owner để thẩm định. Không được tiếp tục cho đến khi có xác nhận.
Tác động thay đổi (Change Impact)	Đặc tả phải ghi rõ các hệ thống hoặc API khác phụ thuộc vào nó. Phải phân biệt rõ ràng giữa thay đổi gây lỗi (breaking change - ví dụ: xóa trường, đổi kiểu dữ liệu) và thay đổi không gây lỗi (non-breaking change). Chiến lược quản lý phiên bản (versioning) phải được xác định.	OpenAPI Specification v3.1.1 (Versioning). Lý do: Quản lý vòng đời API một cách chuyên nghiệp, tránh làm sập các hệ thống đang tích hợp một cách bất ngờ.	FAIL. Các hệ thống của đối tác hoặc nội bộ có thể ngừng hoạt động mà không được báo trước. Gây mất niềm tin và tốn chi phí khắc phục.

Áp dụng Checklist lên Ví dụ Nova Foods

Kết quả rà soát đặc tả API TMPL-API-001 phiên bản v0.9.0 cho case study Nova Foods. Việc rà soát này ghi nhận các điểm quan sát, không cấu thành phê duyệt baseline.

Hạng mục kiểm tra (Checklist Item)	ID Tham chiếu	Kết quả	Ghi chú / Bằng chứng	Hành động đề xuất
1. Tính đầy đủ (Completeness)	`TMPL-API-001#3.2`	Cần cải thiện	Endpoint `POST /api/v1/purchase-orders` thiếu định nghĩa mã lỗi cho business rule `BR-PO-011` (Nhà cung cấp phải ở trạng thái "Đã duyệt"). Payload chỉ định nghĩa lỗi 400 chung chung.	Bổ sung mã lỗi nghiệp vụ cụ thể. Ví dụ: `{"errorCode": "SUPPLIER_NOT_APPROVED", "message": "Nhà cung cấp chưa được duyệt."}`. Điều này giúp client xử lý lỗi tốt hơn.
2. Tính nhất quán (Consistency)	`TMPL-API-001#3.3`	Cần cải thiện	Thuộc tính `supplierId` trong request body của `POST /purchase-orders` không nhất quán với `CANONICAL_DATA_DICTIONARY`. Từ điển dữ liệu định nghĩa là `supplierCode` với kiểu `string(20)`. Đặc tả API dùng `supplierId` kiểu `integer`.	Chỉnh sửa đặc tả API để dùng `supplierCode` kiểu `string(20)`. Đảm bảo nhất quán với nguồn chân lý (`source of truth`) là từ điển dữ liệu.
3. Khả năng kiểm thử (Testability)	`TMPL-API-001#2.4`	Đạt	Tiêu chí chấp nhận (Acceptance Criteria) cho các endpoint được định nghĩa rõ ràng, có thể kiểm thử. Ví dụ: "Khi tạo đơn hàng thành công, API trả về HTTP 201 và location header chứa URL của tài nguyên mới."	Không cần hành động.
4. Truy vết (Traceability)	`TMPL-API-001#4.1`	Đạt	Mọi yêu cầu nghiệp vụ và quy tắc trong đặc tả đều có liên kết truy vết về `CANONICAL_BUSINESS_RULES` và `TRACEABILITY_ID_REGISTRY`. Ví dụ, yêu cầu `API-REQ-005` liên kết rõ ràng đến `BR-PO-008`.	Không cần hành động.
5. Thẩm quyền nguồn (Source Authority)	`TMPL-API-001#3.2.5`	Đạt	Đặc tả xác định rõ các tính toán liên quan đến thuế (VAT) là giả định và yêu cầu xác minh từ bộ phận Kế toán (`Verification required from Accounting Owner`). Điều này tôn trọng đúng ranh giới thẩm quyền.	Không cần hành động.
6. Quyền sở hữu (Ownership)	`TMPL-API-001#3.3`	Đạt	Các đối tượng dữ liệu chính như `Supplier`, `PurchaseOrder`, `Product` có chủ sở hữu dữ liệu (Data Owner) được ghi nhận trong phần siêu dữ liệu.	Không cần hành động.
7. Bảo mật (Security)	`TMPL-API-001#3.1`	Cần cải thiện	Endpoint `GET /api/v1/suppliers/{id}` trả về thông tin nhạy cảm của nhà cung cấp, bao gồm `taxCode` và `bankAccountNumber`. Đặc tả chưa đề cập đến biện pháp kiểm soát truy cập ở cấp độ trường (field-level access control) hoặc che dấu dữ liệu (data masking).	Thêm yêu cầu bảo mật: chỉ người dùng có vai trò `PURCHASING_MANAGER` hoặc `ACCOUNTANT` mới thấy đầy đủ `taxCode` và `bankAccountNumber`. Người dùng khác chỉ thấy dữ liệu bị che dấu. Tham chiếu OWASP API Security Top 10 - API3:2023 (Broken Object Property Level Authorization).
8. Tác động thay đổi (Change Impact)	`TMPL-API-001#1.4`	Đạt	Đặc tả sử dụng phiên bản `v1` và tuân thủ Semantic Versioning. Phần quản trị ghi nhận đây là phiên bản đầu tiên, chưa có phân tích tác động cho các phiên bản sau. Điều này chấp nhận được ở giai đoạn này.	Không cần hành động. Ghi nhận cho các phiên bản tương lai `v2` cần có phân tích thay đổi phá vỡ (breaking change analysis).

Tổng kết rà soát:

Tình trạng: Đặc tả có cấu trúc tốt, nền tảng vững chắc.
Vấn đề: Có một vài điểm không nhất quán và thiếu sót về bảo mật cần được xử lý.
Mức độ chặn: Không có lỗi nghiêm trọng (blocker) nào ngăn cản việc tiếp tục.
Đề xuất: Nhóm soạn thảo cần thực hiện các hành động đề xuất trong bảng trên để tăng chất lượng và độ rõ ràng trước khi trình baseline.

6. Cross-File Checks, Open Issues, and Escalation

6.1. Đối chiếu Chéo với Nguồn Canonical (Cross-File Consistency Check)

Kiểm tra này đảm bảo tài liệu TMPL-API-001 không mâu thuẫn với nguồn thông tin cấp cao hơn trong corpus dự án. Nguồn Canonical là artifact có thẩm quyền cao nhất cho loại thông tin cụ thể, như từ điển dữ liệu hoặc danh mục quy tắc nghiệp vụ. Khi có xung đột, BA phải cập nhật đặc tả API theo nguồn canonical; BA không có thẩm quyền diễn giải lại hoặc thay thế nguồn này.

Bảng ghi kết quả đối chiếu giữa đặc tả API và artifact quản trị trung tâm của dự án mô phỏng Nova Foods.

Hạng mục Kiểm tra	Vị trí trong TMPL-API-001	Tài liệu Đối chiếu Canonical	Kết quả & Phân tích	Hành động Đề xuất
1. Định danh & Metadata Artifact	`Mục 1.1 - Bảng Metadata`	`/01-curriculum/TEMPLATE_MANIFEST.md`	Nhất quán ID `TMPL-API-001`, phiên bản `v0.9.0`, trạng thái `IN_REVIEW` khớp thông tin đăng ký trong `TEMPLATE_MANIFEST`. Kết quả xác nhận artifact đang được nhận diện và quản trị theo manifest.	Không cần hành động. Giữ trạng thái `IN_REVIEW`.
2. Trường Dữ liệu (Data Fields)	`Mục 3.2.2 - Schema 'Supplier'`	`/01-curriculum/CANONICAL_DATA_DICTIONARY.md`	Mâu thuẫn Đặc tả API định nghĩa `status` của nhà cung cấp là `enum` gồm `ACTIVE` và `INACTIVE`. Từ điển Dữ liệu Canonical quy định ba giá trị: `ACTIVE`, `INACTIVE`, `PENDING_REVIEW`. API thiếu giá trị canonical, nên client không thể biểu diễn đầy đủ trạng thái nhà cung cấp.	BA cập nhật `enum` của `status` trong schema `Supplier` để gồm `PENDING_REVIEW`. BA bổ sung quy tắc xử lý và response phù hợp cho trạng thái này.
3. Quy tắc Nghiệp vụ (Business Rules)	`Mục 3.2.1 - Endpoint POST /suppliers`	`/01-curriculum/CANONICAL_BUSINESS_RULES.md`	Mâu thuẫn Đặc tả cho phép tạo nhà cung cấp không có `taxCode` vì trường chưa được đánh dấu bắt buộc. Điều này mâu thuẫn với `BR-NF-ACC-015`, quy định mã số thuế bắt buộc cho tất cả nhà cung cấp tại Việt Nam. API hiện cho phép dữ liệu vi phạm quy tắc canonical.	BA sửa OpenAPI cho `POST /suppliers`: thêm `taxCode` vào danh sách `required` của `requestBody`. BA thêm ví dụ `400 Bad Request` khi request bỏ trống `taxCode`.
4. Định danh Truy vết (Traceability IDs)	`Mục 4.1 - Ma trận Truy vết`	`/01-curriculum/TRACEABILITY_ID_REGISTRY.md`	Nhất quán Các ID yêu cầu, như `REQ-NF-PUR-005`, và ID quy tắc nghiệp vụ, như `BR-NF-S-002`, tuân thủ định dạng và quy tắc đặt tên trong `TRACEABILITY_ID_REGISTRY`.	Không cần hành động.
5. Người tiêu thụ Hạ nguồn (Downstream Consumers)	Toàn bộ tài liệu	Các bản kê (manifests) và kiến trúc hệ thống	Chưa áp dụng Tại thời điểm rà soát, corpus chưa định nghĩa chính thức artifact nào là consumer của API này, như đặc tả microservice khác hoặc tài liệu thiết kế frontend. Không có consumer đã xác định để BA thực hiện phân tích tác động hạ nguồn.	BA phải kiểm tra lại người tiêu thụ hạ nguồn trước bất kỳ quyết định baseline nào. Mọi thay đổi API sau khi consumer được xác định phải có đánh giá tác động và bằng chứng truy vết.

Tổng kết đối chiếu chéo:

Đặc tả liên kết đúng với các artifact quản trị chính về metadata và định danh truy vết. Hai mâu thuẫn cần xử lý trước bước xem xét tiếp theo:

Schema Supplier.status phải chứa PENDING_REVIEW theo /01-curriculum/CANONICAL_DATA_DICTIONARY.md.
POST /suppliers phải yêu cầu taxCode theo BR-NF-ACC-015 trong /01-curriculum/CANONICAL_BUSINESS_RULES.md.

Các kết quả này không thay đổi trạng thái artifact. TMPL-API-001 vẫn là IN_REVIEW.

6.2. Vấn đề Mở, Giả định và Yêu cầu Xác minh

Bảng này ghi nhận rủi ro, điều kiện chưa được xác nhận và thông tin cần xác minh trong khi TMPL-API-001 ở trạng thái IN_REVIEW. BA dùng bảng để chuyển giao đúng vấn đề cho owner có thẩm quyền. Owner xác nhận hoặc quyết định nội dung thuộc phạm vi của mình; BA cập nhật đặc tả, lịch sử thay đổi và truy vết theo kết quả được ghi nhận.

Vấn đề Mở (Open Issue): Câu hỏi hoặc mâu thuẫn đã xác định nhưng chưa có quyết định cuối cùng.
Giả định (Assumption): Điều kiện đang được dùng để xây dựng đặc tả nhưng chưa được xác minh. Nếu sai, đặc tả có thể phải thay đổi.
Yêu cầu Xác minh (Verification Required): Thông tin, quy tắc hoặc yêu cầu cần xác nhận từ owner có thẩm quyền chuyên môn trước khi được dùng làm cơ sở cho thay đổi.

Bảng Theo dõi tại phiên bản v0.9.0 (2026-08-07)

ID Theo dõi	Loại	Mô tả chi tiết	ID Bị ảnh hưởng	Owner Chịu trách nhiệm	Mức độ Ảnh hưởng (Impact)	Hành động Tiếp theo (Next Action)
`TMPL-API-001-ISS-001`	Vấn đề Mở	Đặc tả chưa định nghĩa cơ chế phân trang cho `GET /v1/purchase-orders`. Trả toàn bộ đơn hàng trong một lần gọi có thể gây quá tải khi dữ liệu tăng.	`GET /v1/purchase-orders`	Architect	Cao: Rủi ro `timeout`, tiêu thụ bộ nhớ quá mức tại client và server, giảm tính ổn định API.	Architect cung cấp đặc tả phân trang chuẩn của Nova Foods hoặc quyết định chiến lược phân trang, gồm `offset/limit` hoặc `cursor-based`. BA cập nhật endpoint, schema request, schema response, ví dụ payload và kiểm thử liên quan.
`TMPL-API-001-ASM-001`	Giả định	Đặc tả giả định xác thực và phân quyền dùng `Bearer Token` theo OAuth 2.0, do Identity Provider (IdP) trung tâm của Nova Foods quản lý. Đặc tả chỉ tham chiếu cơ chế này, không định nghĩa lại cơ chế IdP.	Toàn bộ API, gồm header `Authorization`	Architect / Security Owner	Cao: Nếu giả định sai, khung bảo mật, header, response lỗi xác thực và phân quyền phải được thiết kế lại.	Architect xác nhận cơ chế xác thực và cung cấp URL tài liệu đặc tả IdP chính thức để làm nguồn tham chiếu. BA cập nhật tham chiếu bảo mật theo xác nhận.
`TMPL-API-001-ASM-002`	Giả định	Đặc tả giả định các giá trị tiền tệ trong payload API, gồm `unitPrice` và `totalAmount`, dùng `VND` theo `locale` mặc định của corpus. Phiên bản API này không hỗ trợ đa tiền tệ.	`DD-PO-015` (`unitPrice`), `DD-PO-018` (`totalAmount`)	Business Owner / Product Manager	Trung bình: Nếu nghiệp vụ cần đa tiền tệ, API phải thay đổi schema, quy tắc tính tiền, validation và payload ở phiên bản sau.	Business Owner xác nhận phạm vi tiền tệ của MVP. BA ghi rõ “Chỉ hỗ trợ VND” trong đặc tả khi có xác nhận.
`TMPL-API-001-VER-001`	Yêu cầu Xác minh	Công thức `taxAmount` và giá trị `vatRate` trong payload cần Accounting Owner xác minh. Xác minh nhằm kiểm tra cách tính hiện tại có phù hợp với Luật Kế toán 88/2015/QH13 và Nghị định 123/2020/NĐ-CP hay không.	`BR-PO-025` (quy tắc tính thuế), `DD-PO-017` (`vatRate`)	Accounting Owner	Rất Cao: Tính sai thuế có thể gây sai sót hóa đơn, báo cáo tài chính, rủi ro tài chính và rủi ro tuân thủ.	BA lập mô tả chi tiết cách tính hiện tại, gửi Accounting Owner xem xét và lưu xác nhận bằng văn bản. BA chỉ cập nhật quy tắc hoặc payload theo xác nhận được ghi nhận.
`TMPL-API-001-VER-002`	Yêu cầu Xác minh	Các trường truy xuất nguồn gốc `lotNumber`, `productionDate`, `expiryDate` cần QA/QC Owner xác minh về tính đầy đủ và phù hợp với Luật An toàn thực phẩm 55/2010/QH12 và quy trình nội bộ Nova Foods.	`DD-PO-021` (`lotNumber`), `DD-PO-022` (`productionDate`), `DD-PO-023` (`expiryDate`)	QA/QC Owner	Cao: Thiếu hoặc sai dữ liệu có thể cản trở truy xuất nguồn gốc khi xảy ra sự cố, ảnh hưởng an toàn người tiêu dùng và uy tín thương hiệu.	BA gửi trích đoạn từ điển dữ liệu liên quan cho QA/QC Owner. QA/QC Owner xác nhận tính đầy đủ và chính xác; BA ghi nhận kết quả trong lịch sử thay đổi và truy vết.

6.3 Quy trình chuyển giao và quản lý thay đổi (Handoff and Change Propagation)

Mục này xác định cách BA chuyển giao đặc tả API để xem xét và cách quản lý thay đổi khi artifact còn IN_REVIEW. Handoff là việc Business Analyst cung cấp artifact cho Technical Architect, QA Engineer và Business Owner để kiểm tra tính khả thi kỹ thuật, tính đúng nghiệp vụ và khả năng kiểm thử. Handoff phục vụ thu thập phản hồi; không phải approval và không tạo baseline.

Bảng 12: Quy tắc chuyển giao để xem xét (Handoff for Review)

Điều kiện tiên quyết	Hành động chuyển giao	Người thực hiện	Người nhận	Mục đích	Kết quả cần ghi nhận
BA hoàn thành dự thảo Mục 1 đến Mục 5 và tự kiểm tra chất lượng theo Mục 5.1.	BA cập nhật trạng thái artifact trên hệ thống quản lý tác vụ và gửi thông báo chính thức kèm đường dẫn đến phiên bản `v0.9.0`.	`Business Analyst`	`Technical Architect`, `QA Engineer`, `Business Owner`	Thu thập phản hồi về tính khả thi kỹ thuật, tính hợp lệ quy tắc nghiệp vụ và khả năng kiểm thử.	Phản hồi phải được ghi nhận qua bình luận công cụ review, email hoặc biên bản họp. Artifact vẫn giữ `IN_REVIEW`.

Bảng 13: Quy tắc xử lý và lan truyền thay đổi (Change Propagation Rules)

Nguồn gốc thay đổi	Cơ chế phát hiện	Hành động bắt buộc của BA	Ranh giới thẩm quyền	Hệ quả nếu không thực hiện
Quy tắc nghiệp vụ trong `/01-curriculum/CANONICAL_BUSINESS_RULES.md` được cập nhật.	Thông báo từ hệ thống kiểm soát phiên bản hoặc thông báo trực tiếp từ owner artifact.	1. Phân tích ảnh hưởng đến logic, endpoint và payload. 2. Cập nhật đặc tả theo quy tắc mới. 3. Ghi thay đổi trong Lịch sử Thay đổi, kèm ID quy tắc thay đổi. 4. Cập nhật truy vết và bằng chứng kiểm thử bị ảnh hưởng.	BA không được bỏ qua hoặc diễn giải khác quy tắc canonical. API phải tuân thủ nguồn này.	Đặc tả có thể chứa logic không còn hợp lệ và tạo chênh lệch giữa yêu cầu nghiệp vụ với triển khai hoặc kiểm thử.
Định nghĩa trong `/01-curriculum/CANONICAL_DATA_DICTIONARY.md` được cập nhật.	Thông báo từ hệ thống kiểm soát phiên bản hoặc thông báo trực tiếp từ owner artifact.	1. Phân tích ảnh hưởng đến payload, kiểu dữ liệu và định dạng. 2. Cập nhật schema, request, response và ví dụ payload. 3. Ghi thay đổi kèm ID trường dữ liệu. 4. Cập nhật truy vết và kiểm thử bị ảnh hưởng.	Cấu trúc dữ liệu API phải tuân thủ từ điển dữ liệu canonical. BA không tự định nghĩa lại trường đã có trong từ điển.	Client, server và kiểm thử có thể dùng cấu trúc dữ liệu khác nhau, gây lỗi tích hợp hoặc sai dữ liệu.
Phản hồi từ `Architect`, `QA` hoặc `Business Owner` qua kênh chính thức.	Bình luận trong công cụ review, email hoặc biên bản họp được ghi nhận.	1. Đánh giá phản hồi và artifact bị ảnh hưởng. 2. BA cập nhật trực tiếp khi phản hồi sửa lỗi hoặc làm rõ và không mâu thuẫn nguồn canonical. 3. BA ghi nhận phản hồi tạo yêu cầu mới hoặc mâu thuẫn canonical trong bảng vấn đề mở. 4. BA chuyển vấn đề cho owner có thẩm quyền theo Mục 6.2.	Phản hồi không phải approval. BA chỉ thực hiện thay đổi phù hợp nguồn canonical. `Business Owner` xác nhận quyết định nghiệp vụ.	Thay đổi không được kiểm soát có thể tạo mâu thuẫn nguồn, thiếu truy vết hoặc vượt thẩm quyền BA.

Hoàn tất review và cập nhật theo quy tắc này không đồng nghĩa artifact được approved hoặc baselined. Approval và baseline là quyết định quản trị riêng, phải do vai trò có thẩm quyền ghi nhận chính thức. TMPL-API-001 giữ trạng thái IN_REVIEW cho đến khi corpus có quyết định baseline rõ ràng.