Tiêu Chuẩn Tài Liệu
Tài liệu kỹ thuật của dự án tuân thủ các tiêu chuẩn chung để đảm bảo tính nhất quán, dễ hiểu và dễ bảo trì. Các tiêu chuẩn được lựa chọn dựa trên nguyên tắc AI-Friendly, ưu tiên các định dạng mà cả người và AI Agent đều có thể dễ dàng đọc, hiểu và tạo ra.
Nguyên tắc cốt lõi: AI-Friendly
Việc lựa chọn các tiêu chuẩn này dựa trên một nguyên tắc trung tâm: AI-Friendly. Mục tiêu là tạo ra một hệ thống tài liệu mà cả con người và các AI Agent đều có thể dễ dàng đọc, hiểu, và tương tác.
- Định dạng có cấu trúc: Chúng tôi ưu tiên các định dạng văn bản thuần túy như Markdown (cho tài liệu), YAML (cho định nghĩa API), và Mermaid (cho sơ đồ). Các định dạng này dễ dàng được phân tích và tạo ra bởi AI.
- Tính tường minh: Các tiêu chuẩn như C4 Model và ADRs buộc chúng ta phải làm rõ các quyết định và cấu trúc hệ thống, cung cấp context rõ ràng cho AI.
- Khả năng tự động hóa: Các định dạng và tiêu chuẩn này mở ra khả năng tự động hóa cao trong việc tạo, kiểm tra và bảo trì tài liệu.
Các tiêu chuẩn chính được áp dụng là C4 Model để mô hình hoá kiến trúc phần mềm, Architectural Decision Records (ADRs) để ghi lại các quyết định quan trọng, và OpenAPI Standard cho tài liệu API.
Cấu trúc Thư mục Tài liệu
Để dễ dàng điều hướng và tìm kiếm, tài liệu được tổ chức theo cấu trúc thư mục sau:
docs
├── DOCUMENTATION_GENERATION_REPORT.md
├── README.md
├── adrs
│ ├── 0000-template.md
│ ├── 20250528-adopt-documentation-standard.md
│ ├── 20250528-adopt-jai1-framework.md
│ ├── 20250528-legacy-choice-lumen-framework.md
│ ├── 20250528-legacy-docker-containerization.md
│ ├── 20250528-legacy-passport-authentication.md
│ └── 20250528-legacy-repository-pattern.md
├── api
│ ├── README.md
│ └── openapi.yaml
├── bugfixes
│ └── bugfix-template.md
├── diagrams
│ ├── code-diagram.md
│ ├── component-diagram.md
│ ├── container-diagram.md
│ ├── deployment-diagram.md
│ ├── diagram-template.md
│ ├── system-context-diagram.md
│ └── system-landscape-diagram.md
├── features
│ ├── feature-clinic-management.md
│ ├── feature-reservation-system.md
│ ├── feature-template.md
│ ├── feature-treatment-menu.md
│ └── feature-user-management.md
├── guides
│ ├── example-guide.md
│ ├── onboarding-guide.md
│ └── unit-test-guide.md
├── project-structure.md
├── releases
│ └── release-template.md
├── rules
│ ├── update-legacy-project-docs.md
│ ├── update-rules.md
│ ├── usage-rules.md
│ └── workflows.md
└── use-cases
└── usecase-template.md1. C4 Model cho Kiến trúc Phần mềm
C4 Model (tham khảo tại c4model.com) là một phương pháp "tinh gọn" để mô tả kiến trúc phần mềm ở các mức độ chi tiết khác nhau, giống như việc bạn zoom vào một bản đồ. Mô hình này giúp các thành viên trong nhóm (từ kỹ sư đến quản lý sản phẩm) có một cái nhìn chung và nhất quán về hệ thống.
C4 Model bao gồm 4 cấp độ sơ đồ (diagrams):
Cấp độ 1: System Context Diagram (Sơ đồ Ngữ cảnh Hệ thống)
- Mục đích: Cho thấy hệ thống của bạn tương tác với người dùng và các hệ thống khác như thế nào. Đây là cái nhìn tổng quan nhất.
- Đối tượng: Tất cả mọi người, bao gồm cả những người không chuyên về kỹ thuật.
Cấp độ 2: Container Diagram (Sơ đồ Container)
- Mục đích: Phân rã hệ thống thành các "container" (ví dụ: ứng dụng web, API, cơ sở dữ liệu, microservice). Sơ đồ này cho thấy các thành phần công nghệ chính và cách chúng giao tiếp với nhau.
- Đối tượng: Kỹ sư phần mềm, kiến trúc sư hệ thống.
Cấp độ 3: Component Diagram (Sơ đồ Thành phần)
- Mục đích: Phân rã một "container" thành các "component" (thành phần) bên trong nó. Sơ đồ này mô tả trách nhiệm và mối quan hệ của các thành phần chính trong một container.
- Đối tượng: Kỹ sư phần mềm.
Cấp độ 4: Code Diagram (Sơ đồ Mã nguồn)
- Mục đích: Đi sâu vào chi tiết triển khai của một "component". Cấp độ này thường được biểu diễn bằng các sơ đồ lớp UML hoặc các sơ đồ tương tự và có thể được tạo tự động từ mã nguồn.
- Đối tượng: Kỹ sư phần mềm.
2. Architectural Decision Records (ADRs)
Architectural Decision Records (ADRs) (tham khảo tại adr.github.io) là các tài liệu ngắn gọn ghi lại một quyết định quan trọng về kiến trúc được đưa ra trong quá trình phát triển dự án. Mỗi ADR ghi lại bối cảnh, quyết định đã được đưa ra và các hệ quả của quyết định đó.
Tại sao sử dụng ADRs?
- Minh bạch: Giúp mọi người hiểu tại sao hệ thống được xây dựng theo cách hiện tại.
- Chia sẻ kiến thức: Giúp các thành viên mới nhanh chóng nắm bắt được các quyết định kỹ thuật quan trọng đã được đưa ra trong quá khứ.
- Tránh lặp lại sai lầm: Ghi lại các phương án đã được xem xét và lý do tại sao chúng bị từ chối.
Áp dụng trong dự án:
- Tất cả các quyết định kiến trúc quan trọng (ví dụ: lựa chọn framework, thư viện, pattern,...) đều được ghi lại dưới dạng ADR.
- Các ADR được lưu trữ trong thư mục
/adrs. - Khi tạo một ADR mới, hãy sử dụng file mẫu 0000-template.md.
3. OpenAPI Standard cho Tài liệu API
OpenAPI Standard (trước đây là Swagger) là một đặc tả tiêu chuẩn để mô tả các API RESTful. Nó cho phép cả người và máy có thể đọc và hiểu khả năng của một dịch vụ mà không cần truy cập vào mã nguồn, tài liệu bổ sung hoặc kiểm tra lưu lượng mạng.
Lợi ích chính:
- Tài liệu tự động: Tạo ra tài liệu API tương tác, dễ đọc và luôn cập nhật.
- Sinh mã nguồn (Code Generation): Tự động sinh ra mã nguồn cho client (SDK) và server stub từ file định nghĩa OpenAPI.
- Thử nghiệm dễ dàng: Cung cấp một giao diện người dùng (như Swagger UI) để người dùng có thể thử nghiệm các endpoint API trực tiếp từ trình duyệt.
Áp dụng trong dự án:
- File định nghĩa API của dự án được đặt tại
api/openapi.yaml. - Mọi thay đổi về API (thêm, sửa, xóa endpoint) phải được cập nhật trong file này.
Việc tuân thủ các tiêu chuẩn này giúp chúng ta xây dựng một hệ thống tài liệu bền vững, dễ dàng cho việc onboarding thành viên mới và giảm thiểu rủi ro trong quá trình phát triển và bảo trì.