CẨM NANG & HƯỚNG DẪN CÚ PHÁP ĐỊNH DẠNG MỞ RỘNG (MARKDOWN EXTENSIONS)¶

Tài liệu này tổng hợp quy chuẩn cú pháp và ví dụ thực tế của toàn bộ các tiện ích mở rộng đang được tích hợp trong hệ thống tài liệu kỹ thuật Docs Toolkit.

1. Phím tắt Bàn phím (`pymdownx.keys`)¶

Dùng khi viết tài liệu Hướng dẫn sử dụng (HDSD), phím tắt phần mềm và hướng dẫn tác nghiệp:

- Nhấn ++ctrl+s++ để lưu nhanh tài liệu.
- Nhấn ++ctrl+alt+del++ để mở trình quản lý tác vụ.
- Nhấn tổ hợp ++cmd+shift+p++ trên macOS để mở Command Palette.

Hiển thị thực tế: - Nhấn Ctrl+S để lưu nhanh tài liệu. - Nhấn Ctrl+Alt+Del để mở trình quản lý tác vụ. - Nhấn tổ hợp Cmd+Shift+P trên macOS để mở Command Palette.

2. Bôi màu Nhấn mạnh & Chỉ số (`pymdownx.mark`, `tilde`, `caret`)¶

Dùng để nhấn mạnh quy tắc nghiệp vụ cốt lõi, công thức hóa học hoặc đơn vị tính:

- Quy tắc này bắt buộc phải ==tuân thủ 100% khi nghiệm thu UAT==.
- Đơn giá sản phẩm cũ: ~~500,000 VND~~ -> Đơn giá mới: **450,000 VND**.
- Công thức hóa học: H~2~O, CO~2~.
- Diện tích mặt bằng: 150 m^2^, dung tích: 200 dm^3^.

Hiển thị thực tế: - Quy tắc này bắt buộc phải tuân thủ 100% khi nghiệm thu UAT. - Đơn giá sản phẩm cũ: ~~500,000 VND~~ $\rightarrow$ Đơn giá mới: 450,000 VND. - Công thức hóa học: H₂O, CO₂. - Diện tích mặt bằng: 150 m², dung tích: 200 dm³.

3. Danh sách Checkbox Nghiệm thu (`pymdownx.tasklist`)¶

Dùng cho Bảng Tiêu chí nghiệm thu (Acceptance Criteria), Danh mục kiểm thử hoặc Checklist Go-Live:

- [x] Đã khảo sát và thống nhất yêu cầu nghiệp vụ với Business Owner
- [x] Đã phê duyệt và ký duyệt tài liệu BRD v1.0
- [ ] Đang tiến hành thiết kế Wireframe / Prototype trên Figma
- [ ] Chưa nghiệm thu kiểm thử UAT

Hiển thị thực tế: - [x] Đã khảo sát và thống nhất yêu cầu nghiệp vụ với Business Owner - [x] Đã phê duyệt và ký duyệt tài liệu BRD v1.0 - [ ] Đang tiến hành thiết kế Wireframe / Prototype trên Figma - [ ] Chưa nghiệm thu kiểm thử UAT

4. Ký hiệu Biểu tượng Tự động (`pymdownx.smartsymbols`)¶

Tự động chuyển đổi các ký tự thông thường thành ký hiệu quy chuẩn:

- Mũi tên điều hướng: A --> B hoặc B <-- A hoặc A <--> B
- Bản quyền thương hiệu: Bản quyền (c) 2026 INTRUSTDSS (tm) - Đã đăng ký (r)
- Phân số toán học: 1/2 công, 1/4 ngày, 3/4 ca

5. Đánh số Dòng & Định dạng Code Block (`pymdownx.highlight`)¶

Tự động đánh số dòng, click vào số dòng để lấy link neo và tô màu cú pháp:

def tinh_luong_thuc_nhan(luong_co_ban: float, ngay_cong: float) -> float:
    """Hàm tính lương thực nhận tự động cho nhân viên"""
    if ngay_cong <= 0:
        return 0.0

    don_gia_ngay = luong_co_ban / 26.0
    return round(don_gia_ngay * ngay_cong, 2)

6. Chuyển đổi Tab Nội dung (`pymdownx.tabbed`)¶

Dùng để so sánh Quy trình As-Is vs To-Be hoặc hướng dẫn đa nền tảng:

Quy trình Hiện tại (As-Is)Quy trình Đề xuất (To-Be)

Thao tác: Nhân viên nhập file Excel thủ công và gửi email xin duyệt.
Thời gian xử lý: Mất trung bình 2 - 3 ngày.
Rủi ro: Dễ thất lạc email, sai sót công thức tính toán.

Thao tác: Tạo yêu cầu trực tiếp trên hệ thống Web/App, hệ thống tự động kiểm tra logic.
Thời gian xử lý: Phê duyệt tức thì ($\le 2$ giờ).
Lợi ích: Tự động hóa 100%, ghi vết kiểm toán (Audit Trail) minh bạch.

7. Khối Hộp Thu gọn / Bung rộng (`pymdownx.details`)¶

Dùng để ẩn nội dung chi tiết hoặc thông số kỹ thuật mở rộng:

Thông tin Cấu hình Endpoint Tích hợp (Nhấn để đóng / mở)

Endpoint Production: https://api.intrace.vn/v1/pricing/sync
Cơ chế xác thực: OAuth2 Bearer Token (JWT 256-bit)
Rate Limit: Tối đa 1,000 requests/phút trên mỗi Client ID.

Khuyến nghị Nghiệp vụ cho Business Analyst

Khi viết Use Case, luôn phân định rõ Hành động của Người dùng (User Action) và Phản hồi của Hệ thống (System Response) thành 2 cột riêng biệt để đội ngũ QA dễ dàng xây dựng kịch bản kiểm thử (Test Scenario).

8. Sơ đồ Quy trình & Kiến trúc (`mermaid`)¶

Tự động kết xuất sơ đồ luồng quy trình trực tiếp trên nền tảng web:

sequenceDiagram
    autonumber
    actor NV as Chuyên viên Tác nghiệp
    participant App as InTrace Portal
    participant API as Pricing Backend Service
    actor PO as Trưởng phòng Duyệt

    NV->>App: Nhập biểu giá & Gửi phê duyệt
    App->>API: POST /api/pricing/submit
    API-->>App: 200 OK (Mã hồ sơ: BG-2026-001)
    API->>PO: Gửi Email & Thông báo hệ thống
    PO->>App: Xem xét hồ sơ & Xác nhận duyệt
    App->>API: POST /api/pricing/approve
    API-->>NV: Thông báo kết quả: Đã kích hoạt hiệu lực

CẨM NANG & HƯỚNG DẪN CÚ PHÁP ĐỊNH DẠNG MỞ RỘNG (MARKDOWN EXTENSIONS)¶

1. Phím tắt Bàn phím (pymdownx.keys)¶

2. Bôi màu Nhấn mạnh & Chỉ số (pymdownx.mark, tilde, caret)¶

3. Danh sách Checkbox Nghiệm thu (pymdownx.tasklist)¶

4. Ký hiệu Biểu tượng Tự động (pymdownx.smartsymbols)¶

5. Đánh số Dòng & Định dạng Code Block (pymdownx.highlight)¶

6. Chuyển đổi Tab Nội dung (pymdownx.tabbed)¶

7. Khối Hộp Thu gọn / Bung rộng (pymdownx.details)¶

8. Sơ đồ Quy trình & Kiến trúc (mermaid)¶