5s.interface.contract.doc.standard

✅ Checklist Tiêu Chuẩn 5★ cho File interface-contract.md (Markdown)

1. 🎯 Tổng quan và Giới thiệu Rõ ràng (Clear Overview and Introduction):

• Mục đích của Service/API: Giới thiệu ngắn gọn về service, các chức năng chính mà API cung cấp, và phạm vi của nó.
• Đối tượng sử dụng API: Xác định rõ ai (ví dụ: Superadmin Webapp, Auth Service, Sub Service) sẽ là consumer chính của các API này.
• Nguyên tắc chung khi sử dụng API (General Principles): Nêu các quy ước chung quan trọng, ví dụ: định dạng PATCH trả về 204 No Content, cách xử lý trace_id, hoặc các header chung cần thiết.

2. 📜 Đặc tả API Chi tiết, Dễ Hiểu và Chính Xác (Detailed, Understandable & Accurate API Specification):

• Bảng tóm tắt API (API Summary Table):
  • Cung cấp một cái nhìn tổng quan nhanh với các cột: Method, Path, Mô tả ngắn, và Quyền yêu cầu (RBAC Permission). Đây là điểm khởi đầu tuyệt vời để người đọc nắm bắt các API.
• Chi tiết từng API Endpoint:
  • Đường dẫn (Path) và Phương thức (HTTP Method): Ghi rõ ràng, tuân thủ ADR-013 Naming Convention.
  • Mô tả chi tiết (Detailed Description): Giải thích mục đích, hành vi, và các kịch bản sử dụng của API.
  • Tham số (Parameters - Path, Query, Headers):
    • Liệt kê từng tham số với: Tên, Kiểu dữ liệu, Bắt buộc/Tùy chọn, Mô tả rõ ràng.
  • Nội dung Request (Request Body):
    • Mô tả cấu trúc (ví dụ: JSON) và ý nghĩa của từng trường.
    • Chỉ rõ các trường bắt buộc, kiểu dữ liệu, và các ràng buộc (nếu có).
    • Ví dụ Request Body cụ thể (đặt trong code block).
  • Nội dung Response (Response Body):
    • Mô tả cấu trúc response cho các kịch bản thành công (ví dụ: 200 OK, 201 Created).
    • Luôn tuân thủ cấu trúc response chuẩn của hệ thống (ví dụ: { data, error, meta } theo ADR-012).
    • Ví dụ Response Body cụ thể (đặt trong code block).
  • HTTP Status Codes: Liệt kê các status code có thể trả về (cả thành công và lỗi) cùng với giải thích ngắn gọn.
  • Xử lý lỗi (Error Handling): Mô tả cách lỗi được trả về, tham chiếu đến chuẩn lỗi chung của hệ thống (ví dụ ADR-011) và có thể cung cấp ví dụ response lỗi.
  • Quyền yêu cầu (Required Permissions): Ghi rõ permission code (RBAC) cần thiết để gọi API này.
  • Sự kiện phát ra (Emitted Events): Nếu API là nguồn trigger việc phát ra sự kiện, cần mô tả rõ tên sự kiện và có thể cả ví dụ payload của sự kiện đó (hoặc tham chiếu đến nơi định nghĩa chi tiết hơn).

3. ✨ Ví dụ Minh Họa Thực Tế và Phong Phú (Practical & Rich Examples):

• Cung cấp đủ ví dụ JSON cụ thể cho request body và response body, bao gồm cả trường hợp thành công và một số lỗi điển hình cho các API phức tạp hoặc quan trọng. Các ví dụ này giúp người dùng API hiểu và tích hợp nhanh chóng.

4. 🛠️ Tuân thủ Nguyên tắc Thiết kế và ADRs (Adherence to Design Principles & ADRs):

• Nhất quán với các ADRs: Nội dung đặc tả API phải phản ánh đúng các quyết định trong ADRs liên quan (API Naming, Response Structure, Error Format, Security Policies, RBAC Strategy, v.v.).
• Sử dụng thuật ngữ thống nhất: Đảm bảo các thuật ngữ kỹ thuật, tên trường, mã lỗi được sử dụng nhất quán trong toàn bộ tài liệu và với các tài liệu khác của hệ thống.

5. 📄 Thông Tin Bổ Sung và Quản Trị (Supplementary Information & Governance):

• Phụ lục (Appendices - nếu cần):
  • Định nghĩa các ENUMs, các giá trị hằng số được sử dụng trong API (như bạn đã làm với assignment_status, auth_provider trong file user-service/master/interface-contract.md).
  • Bảng tóm tắt các Permission Code liên quan đến các API của service (như bạn đã làm cho User Service Master).
• Liên kết đến tài liệu liên quan:
  • Verlink đến file design chi tiết của service, data model, file OpenAPI spec (nếu có), các ADRs quan trọng.
• Thông tin phiên bản tài liệu: Ghi rõ phiên bản, ngày cập nhật cuối cùng, tác giả, người review ở đầu hoặc cuối tài liệu.

6. 📖 Tính Dễ Đọc, Dễ Tra Cứu và Bảo trì (Readability, Navigability & Maintainability):

• Markdown Formatting: Sử dụng hiệu quả các tính năng của Markdown (headings, tables, code blocks, blockquotes, lists) để tài liệu sáng sủa, dễ đọc.
• Cấu trúc logic: Phân chia tài liệu thành các mục, tiểu mục một cách hợp lý, giúp người đọc dễ dàng tìm thấy thông tin họ cần.
• Mục lục (Table of Contents): Đối với các tài liệu dài, có mục lục tự động hoặc thủ công là rất cần thiết.
• Dễ cập nhật: Thiết kế tài liệu theo cách dễ dàng chỉnh sửa và bổ sung khi API có sự thay đổi.