PRD: Phân quyền scoped Casbin theo merchant
| Module | Quyền hạn (CORE-02) | PRD ID | PRD-EFF-001 |
| Status | Shipped | Owner | Permissions squad |
| Date | 2026-06-04 | Version | v1.0 |
| Packages | @nx/core · @nx/identity · @nx/commerce · @nx/finance · @nx/inventory | URD | EFF · GRANT · ROLE |
TL;DR
Tập trung phân quyền lên một engine Casbin theo merchant, để mọi verifier service enforce các grant trong active merchant domain được chọn theo từng request, và giải quyết những merchant/organizer mà người dùng tiếp cận được từ Casbin policy repository thay vì lọc theo request context rải rác. Kết quả: "người dùng này thấy và làm được gì ở đây" trở thành một câu trả lời nhất quán, dựa trên policy, xuyên suốt commerce, finance và inventory - với cô lập theo merchant (per-schema) và tôn trọng soft-delete.
1. Bối cảnh & Vấn đề
Phân quyền trong KICKO ban đầu được điều khiển bằng lọc theo request context: mỗi service tự suy ra những organization và merchant mà người dùng tiếp cận được từ request rồi lọc thủ công các truy vấn của mình. Điều này khiến "người dùng này thấy được gì" trở nên ngầm định, lặp lại khắp các service, và không thể suy luận tại một nơi duy nhất - đồng thời không có chỗ chung nào để giải quyết một grant trong active merchant domain mà request đang hoạt động trên đó.
Một engine scoped-RBAC Casbin tập trung trong VerifierApplication lấp khoảng trống này: mọi verifier service enforce các grant theo cùng một cách, và độ tiếp cận merchant/organizer đến từ Casbin policy repository thay vì phỏng đoán theo từng request. Vì adapter của framework không tôn trọng soft-delete và KICKO cần cô lập theo merchant (per-schema), một Casbin adapter cấp ứng dụng nên nằm trong @nx/core để các dòng policy/grouping được nạp theo hợp đồng riêng của dự án mà không phải sửa IGNIS. Inventory là bề mặt thí điểm trước khi mở rộng.
2. Mục tiêu & Ngoài phạm vi
Mục tiêu
- Enforce phân quyền qua Casbin trong
VerifierApplication, giải quyết các grant trong active merchant domain được chọn theo từng request (x-merchant-id). - Giải quyết những merchant/organizer mà người dùng tiếp cận được từ Casbin policy repository thay vì lọc theo request context (commerce, finance, core).
- Cung cấp một scoped Casbin adapter cấp ứng dụng trong
@nx/coretôn trọng soft-delete và cô lập theo merchant (per-schema), không cần sửa IGNIS. - Thí điểm enforcement end-to-end trên inventory: seed permission của role inventory, backfill các role owner, giải quyết các merchant ID được phép qua policy.
- Giữ engine đồng bộ với scoped Casbin model của framework (đúng đắn của wildcard/scoped model, scoped adapter, vô hiệu hoá cache Casbin khi refresh token).
Ngoài phạm vi
- Permission wildcard / regex (
sales.*) - ngoài phạm vi (URD §2, §7). - Permission categories / nhóm UI, và role template / bundle.
- Permission theo thời gian hoặc theo ca, và ghi log audit permission.
- Bộ công cụ phân cấp resource / action / domain và khai báo - thuộc về PRD-HIER-001 (
HIER,DECL).
3. Success Metrics
| Metric | Mục tiêu / tín hiệu |
|---|---|
| Enforcement tập trung | 100% quyết định phân quyền của verifier service đi qua Casbin enforcer, không phải lọc request tuỳ tiện |
| Đúng đắn của scope | Độ tiếp cận merchant/organizer giải quyết từ policy khớp với grant thực tế của người dùng; không rò rỉ dữ liệu merchant lạ |
| Cô lập tenant | Các dòng policy/grouping không bao giờ vượt ranh giới một merchant (per-schema) |
| Trung thực soft-delete | Grant đã thu hồi (soft-delete) không bao giờ được enforce như đang hiệu lực |
| Ổn định thí điểm | Inventory vận hành hoàn toàn dưới phân quyền theo merchant mà không hồi quy ở việc giải quyết merchant được phép |
4. Personas & Use Cases
| Persona | Mục tiêu trong tính năng này |
|---|---|
| Owner | Chỉ tiếp cận organizer của chính mình và các merchant của nó - giải quyết nhất quán từ policy |
| Employee / Cashier | Chỉ thao tác trong các merchant được giao, enforce theo active merchant domain |
| Quản trị nền tảng | Tin cậy một đường enforcement tập trung duy nhất xuyên mọi verifier service |
| Service (verifier) | Giải quyết các merchant ID được phép từ policy thay vì lọc tuỳ biến theo từng request |
Core scenarios: một request đến kèm active-merchant header → verifier enforce grant trong merchant domain đó qua Casbin → các merchant/organizer tiếp cận được giải quyết từ policy repository → các grant đã soft-delete bị loại trừ và các dòng tenant giữ nguyên per-schema.
5. User Stories
- Là quản trị nền tảng, tôi muốn phân quyền được enforce tập trung trong verifier, để mọi service trả lời "người dùng này làm được điều này ở đây không" theo cùng một cách.
- Là owner, tôi muốn các merchant tiếp cận được của mình giải quyết từ policy, để tôi thấy đúng các merchant của organizer mình và không thấy gì lạ.
- Là employee, tôi muốn grant được enforce trong active merchant domain, để truy cập của tôi giới hạn ở merchant tôi đang thao tác.
- Là lập trình viên service, tôi muốn giải quyết các merchant ID được phép từ Casbin policy, để ngừng lọc thủ công các truy vấn từ request context.
- Là quản trị nền tảng, tôi muốn grant đã thu hồi ngừng áp dụng ngay lập tức (không enforce dòng đã soft-delete), để việc thu hồi truy cập đáng tin cậy.
- Là quản trị nền tảng, tôi muốn token được refresh xoá cache Casbin, để thay đổi role/permission có hiệu lực gọn gàng.
6. Functional Requirements
| # | Yêu cầu | URD ref |
|---|---|---|
| FR-1 | Enforcement Casbin RBAC được nối vào VerifierApplication; mọi verifier service enforce grant tập trung | URD-EFF-004 |
| FR-2 | Một grant chỉ giải quyết trong active merchant domain được chọn theo từng request (x-merchant-id) | URD-EFF-004 · URD-ROLE-005..006 |
| FR-3 | Effective permission là hợp đã khử trùng lặp của grant trực tiếp + grant kế thừa qua role, giải quyết từ policy repository | URD-EFF-001..002 |
| FR-4 | Các organization và merchant người dùng tiếp cận được giải quyết từ Casbin policy repository, không phải lọc theo request context | URD-EFF-003 |
| FR-5 | Grant / revoke được enforce qua policy repository (idempotent, có chốt chặn leo thang đặc quyền) | URD-GRANT-001..007 |
| FR-6 | Một scoped Casbin adapter cấp ứng dụng nạp các dòng policy/grouping tôn trọng soft-delete và cô lập theo merchant (per-schema) | URD-EFF-004 |
| FR-7 | Cô lập tenant được enforce bằng cách ràng buộc variant của membership trong truy vấn grouping | URD-ROLE-007..008 |
| FR-8 | Một Owner tại merchant trụ sở vươn tới mọi merchant anh em của organizer đó | URD-ROLE-009 |
| FR-9 | Inventory giải quyết các merchant ID được phép qua Casbin policy; permission của role inventory được seed và các role owner được backfill | URD-EFF-003..004 |
| FR-10 | Một lần refresh token vô hiệu hoá cache Casbin để thay đổi policy có hiệu lực | URD-EFF-004 |
Toàn văn yêu cầu và tiêu chí nghiệm thu nằm trong URD Quyền hạn. PRD này tham chiếu chứ không lặp lại.
7. Non-Functional Requirements
| Khía cạnh | Yêu cầu |
|---|---|
| Enforcement tập trung | Mọi quyết định phân quyền trong verifier service đi qua một Casbin enforcer; không còn lọc tuỳ tiện theo từng service làm nguồn sự thật |
| Tenancy & authz | Mỗi grant giải quyết trong một active merchant domain mỗi request; các dòng policy/grouping được cô lập theo merchant (per-schema) |
| Trung thực soft-delete | Scoped adapter loại trừ các dòng policy/grouping đã soft-delete; việc thu hồi được tôn trọng mà không xoá vật lý |
| Nhất quán | Vô hiệu hoá cache khi refresh token giữ enforcement đồng bộ với policy hiện hành |
| Đồng bộ framework | Adapter cấp ứng dụng không cần sửa IGNIS và bám theo scoped Casbin model của framework |
| i18n | Nhãn role/permission hiển thị cho người dùng vẫn song ngữ ({ en, vi }) |
8. UX & Flows
Các bề mặt chính thuộc backend: enforcement nằm trong @nx/core (application/verifier.ts, security/casbin-model.ts, security/application-casbin-adapter.ts, utilities/request.utility.ts); commerce/finance/core giải quyết scope từ policy; inventory là service thí điểm. Không có màn hình người dùng cuối riêng - increment này là nền tảng phân quyền mà các module khác dựa vào.
9. Data & Domain
| Entity | Vai trò |
|---|---|
Casbin policy (p) | Một grant: subject, resource, action, scoped tới một merchant domain |
Casbin grouping (g) | Membership - user→role, user→org/merchant, role→org/merchant; cô lập tenant theo variant |
| Scoped Casbin adapter | Nạp các dòng policy/grouping tôn trọng soft-delete và theo merchant (per-schema) |
| Active merchant domain | Merchant mà một request hoạt động trên đó, chọn qua x-merchant-id |
| Casbin model | Scoped RBAC model định nghĩa cách grant giải quyết trong một domain |
Chỉ mang tính khái niệm - toàn bộ schema policy và hợp đồng adapter nằm trong tài liệu Casbin Authorization cho developer và tài liệu RBAC.
10. Dependencies & Assumptions
Phụ thuộc vào
- Role cố định & tùy chỉnh + grant (URD-ROLE · URD-GRANT) - các dòng policy mà engine enforce.
- Commerce (
@nx/commerce) - organization và merchant là các scope mà grant gắn vào. - Identity (
@nx/identity) - token đăng nhập mang context role; refresh token kích hoạt vô hiệu hoá cache. - Framework IGNIS - scoped Casbin model mà adapter cấp ứng dụng bám theo.
Giả định
- Request mang active-merchant header (
x-merchant-id) chọn domain. - Các dòng policy/grouping của một merchant tồn tại trong schema riêng của nó (cô lập theo merchant).
- Các role owner được backfill và permission của role inventory được seed cho thí điểm.
11. Risks & Open Questions
| Rủi ro / câu hỏi | Giảm thiểu / trạng thái |
|---|---|
| Adapter của framework bỏ qua soft-delete | Adapter cấp ứng dụng trong @nx/core tôn trọng soft-delete; không sửa IGNIS |
| Rò rỉ policy liên merchant | Truy vấn membership ràng buộc variant; các dòng cô lập theo schema |
| Enforcement cũ sau khi đổi role/permission | Cache Casbin xoá khi refresh token |
| Casbin model của framework lệch khỏi kỳ vọng ứng dụng | Bám theo scoped model; migrate sang scoped adapter mới khi upstream thay đổi |
| Mở rộng ngoài thí điểm inventory | Triển khai theo từng service sau khi thí điểm inventory xác nhận end-to-end |
12. Release Plan & Launch Criteria
| Khía cạnh | Kế hoạch |
|---|---|
| Phase | P2 (EFF + GRANT, Built) - xem catalog tính năng URD |
| Rollout | Thí điểm inventory trước, rồi mở rộng cho các verifier service |
| Migration | Seed permission của role inventory; backfill các role owner |
| Tiêu chí ra mắt | Enforcement tập trung được xác nhận trong verifier; scope giải quyết từ policy khớp grant; soft-delete và cô lập per-schema được xác nhận; giải quyết merchant được phép của inventory đúng end-to-end |
| Monitoring | Độ phủ đường quyết định phân quyền, các nỗ lực truy cập merchant lạ, vô hiệu hoá cache khi refresh token, tỉ lệ lỗi thí điểm |
13. FAQ
Hiện phân quyền được enforce ở đâu? Tập trung, trong VerifierApplication qua Casbin enforcer - mọi verifier service dùng cùng một đường thay vì lọc thủ công từ request context.
"Merchant nào" được quyết định ra sao? Theo từng request, qua active-merchant header (x-merchant-id); một grant chỉ giải quyết trong merchant domain đó.
Vì sao adapter cấp ứng dụng thay vì của framework? Adapter của framework không tôn trọng soft-delete và KICKO cần cô lập theo merchant (per-schema); adapter @nx/core cung cấp cả hai mà không sửa IGNIS.
Thu hồi một grant có hiệu lực ngay không? Thu hồi sẽ soft-delete dòng policy, vốn bị scoped adapter loại trừ; một lần refresh token xoá cache Casbin để thay đổi áp dụng gọn gàng.
Vì sao thí điểm trên inventory trước? Để xác nhận enforcement theo merchant end-to-end (seed + backfill owner + merchant ID giải quyết từ policy) trên một service trước khi mở rộng.
Permission wildcard / phân cấp có thuộc phần này không? Không - grant thô qua phân cấp resource/action/domain thuộc về PRD-HIER-001.
References
- URD: Quyền hạn - Effective Permissions & Scope · Grant / Revoke · Role cố định
- PRD liên quan: Phân cấp Resource, Action & Domain
- Module: Quyền hạn - tổng quan + truy vết
- Developer: @nx/core · @nx/identity · Casbin Authorization