Wiki Language Standard — FitZalo V2

Purpose: Chuẩn hoá "bộ ngôn ngữ" dùng trong toàn bộ wiki, đảm bảo một nơi duy nhất tra cứu cho mọi vai trò (Dev / QA / PM / BA / Ops). Scope: Áp dụng bắt buộc cho toàn bộ docs_hub_v3/. Status: APPROVED Last Updated: 2026-02-28 Related Decisions: DEC-001, DEC-003

---

1. Nguyên tắc chung

#	Nguyên tắc	Giải thích
L1	Docs-as-code	Tài liệu sống cùng repo, quản lý bằng PR/review/versioning
L2	Đúng một source of truth	Không tạo bản copy; mỗi thông tin chỉ viết ở 1 chỗ, link chéo nếu cần
L3	Ai cũng đọc được	Mỗi tài liệu phải rõ đối tượng đọc; viết đúng "tầng" cho đúng người
L4	Đúng ngôn ngữ cho đúng mục đích	Dùng bộ ngôn ngữ chuẩn (xem §2), không phát minh format mới
L5	Song ngữ Việt + Anh cho thuật ngữ	Nghiệp vụ viết tiếng Việt, thuật ngữ kỹ thuật song ngữ

---

2. Bộ ngôn ngữ chuẩn (Language Stack)

2.1 Core — Bắt buộc

Lớp	Ngôn ngữ	Mục đích	File types
Nền tảng	Markdown (GFM)	Toàn bộ nội dung: spec, guideline, checklist, ADR, runbook, release note	*.md
Diagram	Mermaid	Flow, sequence, state machine, ER, class diagram — nhúng trong Markdown	Code block ```mermaid
API Contract	OpenAPI 3.1	REST API contract chính thức cho Portal / MiniApp / Backend	*.openapi.yaml

2.2 Optional — Tuỳ nhu cầu module

Lớp	Ngôn ngữ	Khi nào dùng	File types
Event Contract	AsyncAPI 2.6	Khi module có event-driven / outbox / message bus	*.asyncapi.yaml
Acceptance Criteria	Gherkin (BDD)	Luồng quan trọng, rule dễ hiểu nhầm, acceptance test	*.feature

---

3. Quy tắc tài liệu 3 tầng (Three-Tier Documentation)

Mỗi module / feature quan trọng phải có tối thiểu Tầng 1 + Tầng 2. Tầng 3 cho các module có API.

┌─────────────────────────────────────────────────────────────────────┐
│  TẦNG 1 — OVERVIEW (PM/BA/QA đọc được)                            │
│  Markdown + Mermaid                                                 │
│  Nội dung: mục tiêu nghiệp vụ, user journey, flow tổng quan       │
├─────────────────────────────────────────────────────────────────────┤
│  TẦNG 2 — SPEC & RULES (Dev/QA đọc để implement/test)             │
│  Markdown + bảng rule + Gherkin (phần quan trọng)                  │
│  Nội dung: domain model, state machine, validation rules, edge case│
├─────────────────────────────────────────────────────────────────────┤
│  TẦNG 3 — CONTRACTS (Dev/QA/FE dùng để tích hợp)                  │
│  OpenAPI / AsyncAPI + examples                                      │
│  Nội dung: endpoint spec, request/response schema, error codes     │
└─────────────────────────────────────────────────────────────────────┘

Chi tiết từng tầng

Tầng	Đối tượng chính	Format	Nội dung bắt buộc	Vị trí trong docs_hub_v3
1 — Overview	PM, BA, QA, Stakeholder	Markdown + Mermaid	Mục tiêu, persona, user journey (Mermaid flowchart), glossary module-specific	02_SPECS/modules/{MODULE}/OVERVIEW.md
2 — Spec	Dev, QA	Markdown + bảng + Gherkin	Entity model, state machine (Mermaid stateDiagram), validation rules, acceptance criteria	02_SPECS/modules/{MODULE}/SPEC.md + *.feature
3 — Contract	Dev FE/BE, QA	OpenAPI / AsyncAPI	Endpoint list, request/response DTO, error codes, examples	02_SPECS/modules/{MODULE}/api.openapi.yaml

---

4. Quy tắc viết Markdown

4.1 Chuẩn format

• Dùng GFM (GitHub Flavored Markdown) — hỗ trợ bảng, task list, code block, Mermaid.
• Heading hierarchy: # H1 cho title, ## H2 cho section chính, ### H3 cho sub-section. Không skip level.
• Mỗi file bắt đầu bằng # Title + blockquote metadata:

  # Module Name — Purpose
  
  > **Purpose**: Mô tả ngắn gọn mục đích.
  > **Audience**: Dev | QA | PM | BA
  > **Status**: DRAFT | REVIEW | APPROVED
  > **Last Updated**: YYYY-MM-DD

• Bảng dùng cho structured data. Dùng bullet list cho items không cần so sánh/align.

4.2 Ngôn ngữ tự nhiên

Loại nội dung	Ngôn ngữ	Ví dụ
Nghiệp vụ, UI flow, hướng dẫn vận hành	Tiếng Việt	"Người quản trị tạo danh mục sản phẩm"
Thuật ngữ kỹ thuật quan trọng	Song ngữ Việt + Anh	"Bản phát hành Catalog (Catalog Release)"
Tên entity, permission, API route	Tiếng Anh	Product, CAT_VIEW, /api/v2/catalog/products
Code examples, CLI, config	Tiếng Anh	npm run build, @Permissions('CAT_MANAGE')

4.3 Cross-references

• Link nội bộ dùng relative path: [Glossary](../00_GOVERNANCE/02_GLOSSARY.md)
• Mỗi thuật ngữ mới phải thêm vào 02_GLOSSARY.md
• Link tới code dùng format: `libs/modules/{module}/src/...`

---

5. Quy tắc viết Mermaid Diagram

5.1 Khi nào dùng loại nào

Loại diagram	Use case	Audience
flowchart TD/LR	User journey, quy trình nghiệp vụ, luồng xử lý	PM, BA, Dev
sequenceDiagram	API call chain, auth flow, integration flow	Dev, QA
stateDiagram-v2	Entity lifecycle (Order, Membership, StockPicking...)	Dev, QA, BA
erDiagram	Quan hệ entity (khi cần mô tả domain model)	Dev
classDiagram	Module boundary, dependency map	Dev, Architect
gantt	Roadmap, timeline (dùng hạn chế)	PM

5.2 Style guidelines

• Mỗi diagram phải có title (comment %% hoặc heading trước block).
• Node labels bằng tiếng Việt hoặc song ngữ khi audience là PM/BA.
• Node labels bằng tiếng Anh khi diagram kỹ thuật (sequence, class).
• Giữ diagram ≤ 20 nodes. Nếu phức tạp hơn, tách thành sub-diagrams.
• Dùng link labels để giải thích transition (đặc biệt state diagram).

5.3 Ví dụ chuẩn

### Luồng đăng nhập MiniApp (User Journey)

​```mermaid
flowchart TD
    A[Mở MiniApp trong Zalo] --> B{Đã có tài khoản?}
    B -- Có --> C[Zalo OAuth Login]
    B -- Không --> D[Đăng ký tự động]
    C --> E[Chọn Tenant / Cửa hàng]
    D --> E
    E --> F[Trang chủ MiniApp]
​```

---

6. Quy tắc viết OpenAPI Contract

6.1 Cấu trúc file

02_SPECS/modules/{MODULE}/
├── OVERVIEW.md              # Tầng 1
├── SPEC.md                  # Tầng 2
├── api.openapi.yaml         # Tầng 3 — REST contract
├── events.asyncapi.yaml     # Tầng 3 — Event contract (optional)
└── features/                # Gherkin files (optional)
    ├── create-order.feature
    └── cancel-order.feature

6.2 OpenAPI conventions

• Version: OpenAPI 3.1.0
• File format: YAML (dễ đọc hơn JSON cho review)
• Naming:
  • operationId: camelCase — listProducts, createOrder, getOrderById
  • Schema: PascalCase — ProductDto, CreateOrderRequest, OrderListResponse
  • Path param: kebab-case resource, camelCase param — /api/v2/ecommerce/orders/{orderId}
• Mỗi endpoint phải có:
  • summary (tiếng Anh ngắn gọn)
  • description (song ngữ nếu cần, giải thích logic)
  • tags (group by module)
  • security requirements
  • Ít nhất 1 example cho request/response
  • Error responses: 400, 401, 403, 404, 422 (tuỳ endpoint)
• Tóm tắt bảng endpoint trong SPEC.md (cho PM/BA đọc nhanh), detail trong .openapi.yaml

6.3 Ví dụ chuẩn

openapi: 3.1.0
info:
  title: Order Module API
  version: 1.0.0
  description: |
    API quản lý đơn hàng (Order Lifecycle).
    Module: ecommerce | Key: ORDER
paths:
  /api/v2/ecommerce/orders:
    get:
      operationId: listOrders
      summary: List orders with filters
      description: |
        Lấy danh sách đơn hàng trong tenant hiện tại.
        Hỗ trợ filter theo status, date range, customer.
      tags: [Order]
      security:
        - BearerAuth: []
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [draft, confirmed, processing, shipped, delivered, completed, cancelled]
      responses:
        '200':
          description: Paginated order list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderListResponse'
              example:
                data:
                  - id: "ord_abc123"
                    status: "confirmed"
                    total: 150000
                pagination:
                  page: 1
                  limit: 20
                  total: 42

---

7. Quy tắc viết Gherkin (BDD)

7.1 Khi nào dùng Gherkin

• Luồng quan trọng: onboarding tenant, checkout, membership state transition, catalog publish
• Rule dễ hiểu nhầm giữa dev/test/ba
• Acceptance criteria cần formal hơn bullet list

7.2 Khi nào KHÔNG cần Gherkin

• CRUD đơn giản (list/create/update/delete)
• Logic đã rõ trong bảng validation rules
• Khi bullet list trong SPEC.md đã đủ rõ

7.3 Convention

• File path: 02_SPECS/modules/{MODULE}/features/{feature-name}.feature
• Viết bằng tiếng Việt (hoặc song ngữ) để BA/QA đọc được
• Mỗi Feature có description giải thích context
• Scenario name = hành vi cụ thể, không quá dài
• Dùng Scenario Outline + Examples khi có nhiều cases tương tự

7.4 Ví dụ chuẩn

# language: vi
Tính năng: Quản lý vòng đời đơn hàng (Order Lifecycle)
  Là Người quản trị tenant (Tenant Operator)
  Tôi muốn quản lý trạng thái đơn hàng
  Để đảm bảo quy trình giao hàng đúng

  Kịch bản: Xác nhận đơn hàng từ trạng thái Nháp
    Cho rằng có đơn hàng ở trạng thái "draft"
    Và đơn hàng có ít nhất 1 sản phẩm
    Khi tôi xác nhận đơn hàng
    Thì trạng thái đơn hàng chuyển thành "confirmed"
    Và hệ thống ghi audit log

  Kịch bản: Không thể huỷ đơn hàng đã giao
    Cho rằng có đơn hàng ở trạng thái "delivered"
    Khi tôi cố huỷ đơn hàng
    Thì hệ thống từ chối với lỗi "ORDER_CANNOT_CANCEL_DELIVERED"
    Và trạng thái đơn hàng vẫn là "delivered"

Note: Gherkin tiếng Việt dùng các keyword: Tính năng, Kịch bản, Cho rằng, Khi, Thì, Và, Nhưng. Gherkin tiếng Anh: Feature, Scenario, Given, When, Then, And, But. Team có thể chọn 1 ngôn ngữ thống nhất. Khuyến nghị: tiếng Việt cho dự án này.

---

8. Quy tắc viết AsyncAPI (Optional)

8.1 Khi nào cần

• Module phát event qua EventEmitter2 / outbox / message bus
• Cần contract rõ ràng giữa producer và consumer
• Ví dụ: order.confirmed, membership.created, stock.adjusted

8.2 Convention

• Version: AsyncAPI 2.6.0
• File: 02_SPECS/modules/{MODULE}/events.asyncapi.yaml
• Channel name = event name dạng {domain}.{action} (lowercase, dot-separated)
• Mỗi message phải có payload schema + example

---

9. Checklist áp dụng cho module mới

Khi tạo spec cho 1 module mới, đảm bảo:

• [ ] OVERVIEW.md — Markdown + Mermaid user journey (Tầng 1)
• [ ] SPEC.md — Domain model + state machine (Mermaid) + validation rules (Tầng 2)
• [ ] api.openapi.yaml — REST contract với examples (Tầng 3)
• [ ] *.feature files cho ≥ 2 luồng quan trọng nhất (nếu module có logic phức tạp)
• [ ] Thuật ngữ mới → thêm vào 02_GLOSSARY.md
• [ ] Link traceability → cập nhật FEATURE_STATUS_MATRIX.md
• [ ] Cross-reference → link từ MODULE_INDEX.md

---

10. Tổng kết: Language Stack Map

---

Audit stamp: Document created 2026-02-28. Approved as governance standard.
Next review: Khi team thêm event-driven architecture hoặc đổi API versioning strategy.