Đặc tả Tính năng: Kiểm soát & Lịch sử Phiên bản

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

Kiểm soát Phiên bản là mạng lưới an toàn của module Document. Nó cung cấp một bản ghi đầy đủ, theo trình tự thời gian của mọi thay đổi được thực hiện đối với một tài liệu, cho phép tác giả tự tin thử nghiệm và quản trị viên kiểm toán sự phát triển của các chính sách tổ chức theo thời gian.

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

Vai trò	Mục tiêu
Tác giả	Xem lại các bản nháp trước đó và khôi phục nội dung sau khi vô tình xóa.
Quản trị viên	Kiểm toán các thay đổi cụ thể được thực hiện đối với các chính sách của công ty.
Người xem xét	So sánh phiên bản hiện tại với các chu kỳ phản hồi trướ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 xem danh sách các phiên bản trước đó để có thể khôi phục một đoạn văn tôi đã xóa hôm qua.
• Với tư cách là quản trị viên, tôi muốn xem ai đã thực hiện những thay đổi cụ thể đối với "Chính sách Làm việc Từ xa".
• Với tư cách là người dùng, tôi muốn đặt tên cho một phiên bản cụ thể (ví dụ: "Đã được Hội đồng thông qua") để dễ dàng tham khảo.

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

• REQ-VC-001: Tự động tạo ảnh chụp nhanh phiên bản mỗi khi lưu thủ công.
• REQ-VC-002: Danh sách lịch sử phiên bản trực quan với dấu thời gian và tên tác nhân.
• REQ-VC-003: Khả năng "Khôi phục" tại bất kỳ điểm nào trong lịch sử phiên bản.
• REQ-VC-004: So sánh phiên bản song song (dự kiến v1.2).

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

• Khả năng mở rộng: Hỗ trợ lên đến 1000 phiên bản trên mỗi tài liệu mà không làm giảm hiệu năng.
• Lưu trữ: Lưu trữ chênh lệch (delta) JSON (dự kiến) để giảm thiểu dung lượng cơ sở dữ liệu.

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

• Tính bất biến: Các phiên bản lịch sử KHÔNG THỂ bị sửa đổi sau khi đã tạo.
• Phục hồi: Việc khôi phục một phiên bản sẽ tạo ra một phiên bản MỚI (được sao chép từ phiên bản cũ) để duy trì lịch sử tuyến tính.
• Dọn dẹp: (Tùy chọn) Tự động cắt tỉa các phiên bản tự động lưu nhỏ cũ hơn 30 ngày.

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

• Thanh bên Lịch sử: Danh sách các phiên bản có thể cuộn với các hành động "Xem trước" và "Khôi phục".
• Siêu dữ liệu: Mỗi mục phiên bản hiển thị: Số phiên bản, Ngày/Giờ, và Avatar của tác giả.
• Chế độ Xem trước: Hiển thị chỉ đọc của phiên bản lịch sử đã chọn.

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

• "Lịch sử Phiên bản" có thể truy cập qua menu "Tệp" hoặc biểu tượng "Đồng hồ" của trình soạn thảo.

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

• Bảng: document_versions.
• Các trường: id, document_id, version_number, content, saved_by.

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

• GET /documents/:id/versions
• POST /documents/:id/versions/:versionId/restore

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

• Dịch vụ Người dùng: Liên kết ID saved_by với hồ sơ người dùng Shell đầy đủ để hiển thị avatar.

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

• RBAC: Yêu cầu quyền documents:read để xem lịch sử; documents:write để khôi phục.
• Toàn vẹn: Các phiên bản được liên kết với org_id của tài liệu cha để cô lập dữ liệu.

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

• Xác nhận Khôi phục: Bắt buộc xác nhận hai lần trước khi ghi đè lên bản nháp hiện tại.
• Phát hiện xung đột: Logic tiêu chuẩn áp dụng nếu nhiều người dùng cố gắng khôi phục các phiên bản khác nhau đồng thời.

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

• Các phiên bản được phân trang trong thanh bên lịch sử.
• Các payload JSON lớn được nén trước khi lưu trữ (dự kiến).

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

• Dấu thời gian được định dạng theo cài đặt ngôn ngữ trình duyệt của người dùng.

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

• Danh sách phiên bản có thể tiếp cận (quản lý tiêu điểm khi mở/đóng lịch sử).

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

• Theo dõi "Tần suất Khôi phục" để xác định mức độ biến động của tài liệu.

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

• Kiểm thử tích hợp cho chuỗi đánh số phiên bản.
• Kiểm thử đơn vị cho logic khôi phục (sao chép so với ghi đè).

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

• Giả định rằng lưu trữ jsonb trong PostgreSQL là đủ cho nhu cầu lịch sử v1.

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

• So sánh trực quan (đánh dấu văn bản được thêm/xóa bằng màu đỏ/xanh).
• Các phiên bản "Cột mốc" (Các phiên bản được giữ lại vĩnh viễn, bỏ qua việc dọn dẹp).