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
Ranh giới module (Clean Architecture): domain (record thuần) ← useCase (không có Spring) ← service (Spring, JPA, security, config).
POST /cms/v1/posts/{id}/preview-link — presenter AuthPresenter ⇒ trả HTTP status thật.
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.
GET /public/v1/posts/{id}/preview?token= — presenter AbstractPresenter ⇒ luôn HTTP 200, FE đọc code trong body.
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.
Cả 3 nhánh đều trả HTTP 200 (convention pub); phân biệt bằng code trong body.
| 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 |
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.
expires_at < now) — bảng chỉ co lại khi post bị xoá. Cần cron dọn định kỳ không?