Đặc tả Tính năng: Mẫu & Cơ sở Tri thức

1. Tổng quan & Tầm nhìn

Tổ chức Mẫu & Cơ sở Tri thức biến một bộ sưu tập các tệp riêng lẻ thành một bộ não doanh nghiệp có cấu trúc và có thể tìm kiếm được. Nó cung cấp các công cụ để phân loại tài liệu vào các không gian và tăng tốc việc tạo tài liệu bằng cách sử dụng các mẫu đã định nghĩa trước, đảm bảo tính nhất quán và khả năng khám phá trong toàn bộ tổ chức.

2. Các Vai trò & Bên liên quan

Vai trò	Mục tiêu
Tác giả	Bắt đầu các tài liệu mới nhanh chóng bằng cách sử dụng các bố cục tiêu chuẩn.
Quản trị viên	Tổ chức các tài liệu vào các "Không gian" (Spaces) logic (ví dụ: Marketing, Kỹ thuật).
Quản trị viên Tri thức	Định nghĩa và duy trì thư viện các mẫu chính thức của tổ chức.

3. Câu chuyện Người dùng (User Stories)

• Với tư cách là tác giả, tôi muốn sử dụng mẫu "Biên bản cuộc họp" để không phải định dạng phần đầu trang mỗi lần.
• Với tư cách là quản trị viên, tôi muốn tạo một không gian "Riêng tư" cho các tài liệu pháp lý nhạy cảm.
• Với tư cách là thành viên, tôi muốn tìm kiếm "Chiến lược" và xem tất cả các tài liệu trong không gian Marketing.

4. Yêu cầu Chức năng (FR)

• REQ-KB-001: Hỗ trợ các Không gian (Spaces) theo phạm vi tổ chức (nhóm tài liệu).
• REQ-KB-002: Thư viện mẫu với phân nhóm theo danh mục.
• REQ-KB-003: Tìm kiếm toàn văn (PostgreSQL tsvector) trên tất cả các tài liệu trong một không gian.
• REQ-KB-004: Tạo tài liệu bằng một cú nhấp chuột từ bất kỳ mẫu nào đang hoạt động.

5. Yêu cầu Phi chức năng (NFR)

• Độ trễ: Khởi tạo mẫu < 200ms.
• Khả năng mở rộng: Hỗ trợ lên đến 1000 tài liệu mỗi không gian.

6. Logic & Quy tắc Nghiệp vụ

• Kế thừa Mẫu: Khi tạo từ một mẫu, tài liệu mới sẽ bị ngắt kết nối khỏi nguồn mẫu (những thay đổi đối với mẫu không ảnh hưởng đến các tài liệu hiện có).
• Cô lập Không gian: Các tài liệu PHẢI thuộc về chính xác một không gian.
• Đánh chỉ mục: Chỉ các tài liệu đã published mới được đưa vào kết quả tìm kiếm toàn tổ chức (tùy chọn).

7. Giao diện Người dùng (UI/UX)

• Trình khám phá Không gian: Danh sách tài liệu được nhóm theo không gian.
• Phòng trưng bày Mẫu: Các thẻ trực quan hiển thị bản xem trước và mô tả mẫu.
• Breadcrumbs: ví dụ: Cơ sở tri thức / Kỹ thuật / Kiến trúc hệ thống.

8. Kiến trúc Thông tin

• Thanh bên "Không gian" để điều hướng.
• Tab "Mẫu" trong modal tạo tài liệu.

9. Mô hình Dữ liệu & Lưu trữ

• Bảng: templates.
• Bảng: documents (cột space_id).
• Định dạng: Nội dung mẫu được lưu trữ dưới dạng JSON TipTap.

10. Lớp API & Dịch vụ

• GET /templates
• POST /documents (với templateId)
• GET /spaces

11. Các Mẫu Tích hợp

• AI Assistant: Sử dụng phân cấp Không gian để định nghĩa "phạm vi" truy xuất cho chatbot RAG.

12. Bảo mật & Quyền hạn

• RBAC: Yêu cầu quyền documents:read để xem một không gian; templates:manage cho Quản trị viên Tri thức.
• Khả năng hiển thị: Các không gian có thể là "Công khai" (tất cả thành viên tổ chức) hoặc "Hạn chế" (các thành viên/vai trò cụ thể).

13. Xử lý Lỗi & Khả năng Phục hồi

• Lỗi Mẫu: Dự phòng về một tài liệu trống nếu việc tải mẫu thất bại.
• Tìm kiếm quá hạn: Thông báo cho người dùng nếu các truy vấn phức tạp vượt quá thời gian chờ 5 giây.

14. Hiệu năng & Khả năng Mở rộng

• Đánh chỉ mục tìm kiếm: Các worker chạy ngầm cập nhật search_vector mỗi khi xuất bản tài liệu.
• Cache: JSON mẫu được cache trong bộ nhớ ở lớp API.

15. Toàn cầu hóa & Bản địa hóa

• Thư viện mẫu đa ngôn ngữ (Các mẫu tiêu chuẩn được cung cấp bằng tiếng Anh và tiếng Việt).

16. Khả năng Tiếp cận (a11y)

• Các vai trò Aria-search cho giao diện cơ sở tri thức.
• Phòng trưng bày mẫu có thể điều hướng bằng bàn phím.

17. Khả năng Quan sát & Phân tích

• Theo dõi "Mức độ phổ biến của mẫu" để xác định các quy trình công việc có giá trị cao.
• Phân tích "Mật độ tài liệu" trên mỗi không gian.

18. Kiểm thử & Chất lượng

• Kiểm thử hiệu năng cho tìm kiếm toàn văn quy mô lớn.
• Kiểm thử tích hợp cho việc thực thi quyền hạn dựa trên không gian.

19. Các Ràng buộc & Giả định

• Giả định PostgreSQL là cơ sở dữ liệu chính cho siêu dữ liệu và các vector tìm kiếm.

20. Các Cải tiến Tương lai

• Các không gian lồng nhau (Sub-spaces).
• Mẫu cộng tác (Chỉnh sửa mẫu chung).
• "Mẫu gợi ý" dựa trên bộ phận của người dùng.