Đặc tả Kỹ thuật: Module Document
Tài liệu này chi tiết về kiến trúc kỹ thuật, stack công nghệ và các mẫu tích hợp cho module Document.
v1.0 — Đã phê duyệtNền tảng: Shell VENI-AIStack: Bun/Ignis/Hono
1. Kiến trúc Cấp cao
Module Document được xây dựng như một Hệ thống Tự vận hành (SCS) với engine đánh số phiên bản tùy chỉnh và một đường ống xử lý rich-text.
Sơ đồ Thành phần
2. Stack Công nghệ
Backend (API)
- Runtime: Bun
- Framework: Ignis Framework
- Router: Hono
- ORM: Drizzle ORM
- Cơ sở dữ liệu: PostgreSQL (đã kích hoạt Tìm kiếm Toàn văn)
Frontend (UI)
- Thư viện: React 18
- Engine Soạn thảo: TipTap (Wrapper headless cho Prosemirror)
- Công cụ Build: Vite
- Styling: Tailwind CSS v4 + ARDOR UI Kit
3. Logic Triển khai Cốt lõi
3.1 Lưu trữ Nội dung
Thay vì HTML thô, module lưu trữ nội dung tài liệu dưới dạng TipTap JSON. Điều này cho phép:
- So sánh các phiên bản (diffing) một cách tin cậy.
- Dễ dàng render trên nhiều nền tảng.
- Trích xuất dữ liệu có cấu trúc (ví dụ: tự động tạo Mục lục - TOC).
3.2 Engine Kiểm soát Phiên bản
Mỗi lệnh PUT /api/documents/:id tạo ra một bản ghi mới trong document_versions.
- Đồng thời: Khóa lạc quan (optimistic locking) cơ bản sử dụng dấu thời gian
updatedAt. - Hoàn tác: Khôi phục một phiên bản bao gồm việc sao chép một bản ghi
document_versionscũ và đặt nó làmcurrentVersionIdmới.
3.3 Tìm kiếm Toàn văn
Được triển khai thông qua tsvector gốc của PostgreSQL.
- Khi một tài liệu được xuất bản, API tạo ra một
searchVectorcó trọng số kết hợp Tiêu đề (trọng số A) và văn bản thuần túy được trích xuất từ nội dung JSON (trọng số B).
4. Chi tiết Tích hợp
4.1 Xác thực Shell
- Document trích xuất
organizationIdvàuserIdtừ Platform JWT. - Việc ủy quyền được kiểm tra dựa trên RBAC của Shell:
documents:read,documents:write,documents:publish.
4.2 Sử dụng Chéo module
- AI Assistant: Đánh chỉ mục các tài liệu đã xuất bản vào cơ sở tri thức (Vector Store) của nó thông qua một webhook sau khi xuất bản.
Liên kết liên quan