Đặc tả Tính năng: Soạn thảo Rich-Text
1. Tổng quan & Tầm nhìn
Tính năng Soạn thảo Rich-Text là động lực sáng tạo cốt lõi của module Document. Nó cung cấp một trải nghiệm chỉnh sửa chuyên nghiệp, "Những gì bạn thấy là những gì bạn nhận được" (WYSIWYG), cho phép người dùng tạo các tài liệu nội bộ, chính sách và báo cáo chất lượng cao trực tiếp trong nền tảng VENI-AI.
2. Các Vai trò & Bên liên quan
| Vai trò | Mục tiêu |
|---|---|
| Tác giả | Tạo và định dạng các tài liệu có cấu trúc một cách dễ dàng. |
| Người xem xét | Đọc và nhận xét về nội dung tài liệu trong chu kỳ phê duyệt. |
| Quản trị viên Tri thức | Duy trì các phong cách và định dạng tiêu chuẩn trong toàn 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 các phím tắt Markdown (như
#cho H1) để có thể viết mà không cần nhấc tay khỏi bàn phím. - Với tư cách là tác giả, tôi muốn chèn bảng và các khối mã (code blocks) để tài liệu hóa các yêu cầu kỹ thuật.
- Với tư cách là tác giả, tôi muốn công việc của mình được tự động lưu sau mỗi vài giây để không bị mất tiến độ.
4. Yêu cầu Chức năng (FR)
- REQ-ED-001: Chỉnh sửa văn bản rich-text dựa trên TipTap (In đậm, In nghiêng, Danh sách, H1-H3).
- REQ-ED-002: Hỗ trợ các nút nâng cao (Bảng, Khối mã, Danh sách công việc).
- REQ-ED-003: Hỗ trợ phím tắt Markdown cho các định dạng phổ biến.
- REQ-ED-004: Tự động lưu ngầm (mỗi 30 giây).
5. Yêu cầu Phi chức năng (NFR)
- Hiệu năng: Khởi tạo trình soạn thảo < 500ms.
- Độ tin cậy: Không mất dữ liệu thông qua đệm lưu trữ cục bộ (dự kiến).
6. Logic & Quy tắc Nghiệp vụ
- Xác thực Lược đồ: Nội dung phải tuân thủ nghiêm ngặt lược đồ JSON của TipTap.
- Khóa tài liệu: Tài liệu ở chế độ chỉ đọc khi ở trạng thái "Đang xem xét" hoặc "Đã xuất bản".
- Logic Tự động lưu: Chỉ kích hoạt nếu phát hiện có thay đổi kể từ lần lưu cuối cùng.
7. Giao diện Người dùng (UI/UX)
- Thanh công cụ nổi: Các tùy chọn định dạng theo ngữ cảnh (xuất hiện khi chọn văn bản).
- Menu cố định: Thanh trên cùng với các biểu tượng hành động vĩnh viễn (In đậm, Liên kết, v.v.).
- Chế độ tập trung: Tùy chọn ẩn các thanh bên để tập trung viết lách.
8. Kiến trúc Thông tin
- Chế độ xem chính cho
docs.venizia.ai/edit/:id. - Bảng điều khiển bên cho "Dàn ý" (Tự động tạo từ các thẻ H1-H3).
9. Mô hình Dữ liệu & Lưu trữ
- Bảng:
document_versions. - Trường:
content(jsonb). - Định dạng: Cấu trúc JSON của TipTap/Prosemirror.
10. Lớp API & Dịch vụ
PUT /documents/:id(Lưu một phiên bản nháp mới).GET /templates/:id(Tải nội dung ban đầu).
11. Các Mẫu Tích hợp
- Phần mở rộng TipTap: Các phần mở rộng tùy chỉnh cho các liên kết nền tảng (ví dụ: liên kết đến một tệp Drive).
12. Bảo mật & Quyền hạn
- RBAC: Yêu cầu quyền
documents:writeđể truy cập trình soạn thảo. - Bảo mật Nội dung: Làm sạch (sanitization) tất cả HTML/JSON trước khi lưu trữ.
13. Xử lý Lỗi & Khả năng Phục hồi
- Xung đột Đồng bộ: Cảnh báo người dùng nếu một phiên bản mới hơn đã tồn tại trên máy chủ.
- Lỗi Mạng: Thông báo khi việc tự động lưu thất bại.
14. Hiệu năng & Khả năng Mở rộng
- Tuần tự hóa/Giải tuần tự hóa JSON hiệu quả.
- Hỗ trợ các tài liệu lên đến 100.000 ký tự mà không bị lag.
15. Toàn cầu hóa & Bản địa hóa
- UI đa ngôn ngữ cho thanh công cụ của trình soạn thảo.
- Hỗ trợ các ngôn ngữ RTL (Phải sang Trái) (dự kiến v2).
16. Khả năng Tiếp cận (a11y)
- Các phím tắt tiêu chuẩn (Ctrl+B, Ctrl+I).
- Hỗ trợ trình đọc màn hình cho dàn ý tài liệu.
17. Khả năng Quan sát & Phân tích
- Theo dõi "Thời gian chỉnh sửa" trên mỗi tài liệu.
- Phân tích "Các công cụ định dạng được sử dụng nhiều nhất".
18. Kiểm thử & Chất lượng
- Kiểm thử tích hợp cho việc xác thực lược đồ JSON.
- Kiểm thử Cypress E2E cho chuỗi tự động lưu.
19. Các Ràng buộc & Giả định
- Giả định người dùng có trình duyệt hiện đại với JavaScript đã được kích hoạt.
20. Các Cải tiến Tương lai
- Chỉnh sửa cộng tác thời gian thực (tích hợp Yjs/Websocket).
- Trợ lý Viết AI (Tích hợp với module AI để viết lại/tóm tắt).