Post Preview Link — Diagrams luồng

Link private có thời hạn để xem bài viết chưa xuất bản trên website public. Token opaque 32-byte lưu DB, TTL 7 ngày, thu hồi được.

Plan gốc: plans/260908-1010-post-preview-link/plan.md Contract chi tiết + checklist FE: phase-04-docs-fe-contract-handoff.md

1. Tổng quan hệ thống

[Diagram]

Ranh giới module (Clean Architecture): domain (record thuần) ← useCase (không có Spring) ← service (Spring, JPA, security, config).

2. Luồng tạo link (CMS)

POST /cms/v1/posts/{id}/preview-link — presenter AuthPresenter ⇒ trả HTTP status thật.

[Diagram]

Vì sao Base64 url-safe: alphabet chuẩn sinh / (phá path segment của endpoint DELETE) và + (bị decode thành space ở query string).

Vì sao previewUrl dựng ở controller: phụ thuộc config triển khai website.public-base-url; module useCase không có dependency Spring.

3. Luồng xem trước (public, không đăng nhập)

GET /public/v1/posts/{id}/preview?token= — presenter AbstractPresenter ⇒ luôn HTTP 200, FE đọc code trong body.

[Diagram]

Vì sao status gọi findById riêng: PostDetail cũng là response shape của GET /public/v1/posts/{id} đang chạy production — thêm field vào đó sẽ âm thầm đổi contract endpoint cũ.

Vì sao token là optional ở controller: link bị cắt khi forward sẽ trả cùng shape NOT_FOUND thay vì lỗi binding 500 trên endpoint mở ra internet.

4. Cây quyết định validate token

[Diagram]

Cả 3 nhánh đều trả HTTP 200 (convention pub); phân biệt bằng code trong body.

5. Luồng liệt kê + thu hồi (CMS)

[Diagram]

6. Vòng đời token

[Diagram]

7. Bảng endpoint và mã lỗi

Endpoint Auth Presenter HTTP Lỗi
POST /cms/v1/posts/{id}/preview-link JWT, MAKER/CHECKER/SUPER_ADMIN AuthPresenter status thật 404 post lạ, 403 sai chủ sở hữu
GET /cms/v1/posts/{id}/preview-links JWT, authenticated AuthPresenter status thật 404, 403
DELETE /cms/v1/posts/{id}/preview-links/{token} JWT, MAKER/CHECKER/SUPER_ADMIN AuthPresenter status thật 404 post/token lạ, 403
GET /public/v1/posts/{id}/preview?token= permitAll AbstractPresenter luôn 200 code: NOT_FOUND | INVALID_STATE

Quyền theo role (PostPreviewAccess.canManage):

Role Tạo / xem / thu hồi link
MAKER ✓ bài do mình tạo
CHECKER ✓ mọi bài (link xem trước là công cụ đọc)
SUPER_ADMIN ✓ mọi bài

8. Lưu trữ

[Diagram]

Token lưu clear text — ai đọc được bảng này thì đọc thẳng posts được rồi; hash chỉ thêm bước tra cứu và phá tính năng hiện lại link trong danh sách revoke của CMS.

Câu hỏi chưa chốt