API Traceability (UI → API → RBAC → Data)

Mục tiêu: nhìn vào đây biết màn hình gọi gì, endpoint nào, quyền nào, entity nào. Quy ước: 1 dòng = 1 interaction quan trọng.

MiniApp V2 Packet Coverage Snapshot (2026-02-27)

• Packet coverage: 36/36 (100%) cho toàn bộ WI-MA-S*.
• Packet index: 02_SPECS/workitems/WI-MA_PACKET_INDEX.md.
• Sprint execution board: 03_TRACEABILITY/WORKITEM_BOARD.md.
• Ý nghĩa traceability: toàn bộ miniapp workitems đã có execution packet để map UI flow ↔ API contract ↔ acceptance.

WI-MA-S4-004 Closeout Contract Linkage (2026-02-27)

Workitem / Cluster	Implemented Contract(s)	Source of Truth	Evidence
WI-SEC-001 (Guard audit)	Tenant-scope API guard/permission parsing hardened via manifest generator	v2/scripts/generate_manifests.js + generated API manifest	05_GENERATED/backend_api_manifest.md (missing PermissionsGuard warnings = 0), closeout: 04_OPERATIONS/16_WI-SEC-001_CLOSEOUT_2026-02-27.md
WI-IAM-001 (Tenant settings migration)	Tenant settings migration contract tests + rollout checklist	IAM contract specs/tests	Tenant-settings contract test pass (8 tests) + rollout closure: 04_OPERATIONS/17_WI-IAM-001_ROLLOUT_CHECKLIST_2026-02-27.md
WI-PB-001 (Portal + Catalog parity)	Portal Product list/form mapped to real Catalog/Brand APIs (/v2/catalog/products, /v2/catalog/brands, /v2/catalog/categories)	Portal app + backend catalog controllers/services	nx test catalog PASS (11 tests) and portal compile blockers resolved (recorded on board)
File Management rollout	/v2/files/* policy/entitlement/upload/asset/share + metadata update/restore + migration contracts	File-management module + generated manifests	Runtime module: v2/libs/modules/file-management/src/lib/*, manifests: 05_GENERATED/backend_api_manifest.md, 05_GENERATED/backend_entity_manifest.md, 05_GENERATED/permission_manifest.md

Closeout rule: các hợp đồng đã implement phải xuất hiện đồng thời ở ít nhất 2 lớp: code truth (controller/service/test) và generated/doc traceability (05_GENERATED/* + board/matrix notes).

Core Trace Rows

Surface	Screen/Flow	UI Route	HTTP	Endpoint	Permission / Policy	Tenant Scope	Entities	Notes
Portal	General Login	/login	POST	/api/v2/iam/auth/login	@Public()	No tenant early (DEC-001)	User, Identity	Returns JWT without tenantId
Portal	Zalo Login	/login	POST	/api/v2/iam/auth/zalo-login	@Public()	No tenant early (DEC-002)	User, Identity	Returns JWT without tenantId
MiniApp	Zalo Tenant Init	/auth	POST	/api/v2/iam/auth/zalo-tenant-login	@Public()	Requires tenant bind (DEC-002)	User, Identity	Returns JWT with tenantId
Portal	Workspace Select	/workspace	GET	/api/v2/iam/tenants	TENANT_VIEW	Bypass (@SkipTenantCheck)	Tenant, Membership	Load list of available tenants
Portal	Switch Tenant	/workspace	POST	/api/v2/iam/auth/switch-tenant	Authenticated	Sets active_tenant	Membership	Updates JWT context
Portal	Product Mgmt	/catalog/products	GET	/api/v2/catalog/products	CAT_VIEW / CAT_MANAGE	Required	Product, Category	Tenant-scoped list
MiniApp	Browse Catalog	/catalog	GET	/api/v2/catalog/products	CAT_VIEW	Required	Product	Passed via header/JWT
Portal	Orders	/ecommerce/orders	GET	/api/v2/ecommerce/orders	ORDER_VIEW	Required	Order	List all orders
MiniApp	My Orders	/profile/orders	GET	/api/v2/ecommerce/orders/my	@Public() / Custom	Required	Order	Filter by customer ID
Portal	Vendors	/crm/partners	GET	/api/v2/crm/partners	CRM_VIEW	Required	Partner	Filter by type=vendor
Portal	Vouchers	/marketing/vouchers	GET	/api/v2/marketing/vouchers	VOUCHER_VIEW	Required	Voucher
MiniApp	Apply Voucher	/checkout	POST	/api/v2/marketing/vouchers/apply	VOUCHER_VIEW	Required	Voucher	Validates cart state
Portal	Manage Plugins	/admin/plugins	GET	/api/v2/admin/plugins/installed	PLUGIN_VIEW	Bypass (@SkipTenantCheck)	InstalledPlugin	System Admin scoped
Backend	File Storage Policy API	n/a	GET/POST	/api/v2/files/policy/storage-mode	FILE_POLICY_VIEW / FILE_POLICY_MANAGE	Required	TenantFilePolicy	Portal route chưa implement, currently API contract only
Backend	File Quota & Usage API	n/a	GET	/api/v2/files/usage, /api/v2/files/entitlement	FILE_USAGE_VIEW	Required	FileAsset, FileUsageLedger, TenantFileEntitlement	Portal route chưa implement, currently API contract only
Backend	File Asset Admin API	n/a	GET/PATCH/DELETE/POST	/api/v2/files/assets, /api/v2/files/assets/:id, /api/v2/files/assets/:id/restore, /api/v2/files/assets/:id/share-link	FILE_VIEW / FILE_EDIT / FILE_DELETE / FILE_RESTORE	Required	FileAsset, FileShareLink	Portal route chưa implement, currently API contract only
Portal	Production Orders	/production/orders	GET/POST	/api/v2/supply-chain/production/work-orders	PROD_MANAGE	Required	WorkOrder	NEW: List + create work orders
Portal	Production Detail	/production/orders/:id	GET/PATCH	/api/v2/supply-chain/production/work-orders/:id, .../status, .../progress	PROD_MANAGE	Required	WorkOrder	NEW: Detail + status/progress update
Portal	Balance/Wallet	/balance	GET/POST	/api/v2/balance/wallet, /api/v2/balance/transactions, /api/v2/balance/adjust	BILLING_VIEW	Required	Wallet, BalanceTransaction	NEW: Wallet card + transaction history + manual adjust
Portal	Customer Loyalty	/crm/loyalty	GET/POST	/api/v2/crm/loyalty/conditions, /api/v2/crm/loyalty/conditions/evaluate	CRM_MANAGE	Required	MembershipCondition	NEW: Conditions CRUD + partner eval
Portal	Zalo Center	/marketing/zalo	GET/POST	/api/v2/integrations/zalo/oas, .../connect, .../zns/templates, .../zns/send	SYSTEM_ADMIN	Required	ConnectedOA, ZnsTemplate	Refactored from hardcoded → API-driven
Portal	Billing Admin	/admin/billing	GET/POST/DELETE	/api/v2/billing/subscriptions/active, .../subscribe, .../cancel, /api/v2/billing/usage/summary	BILLING_MANAGE	Required	Subscription	Refactored from hardcoded → API-driven; usage/summary now implemented
Portal	In-App Notifications	n/a (component)	GET/PATCH	/api/v2/content/notifications/in-app, .../in-app/:id/read, .../in-app/read-all, .../in-app/unread-count	NOTIFY_VIEW	Required	Notification	Endpoints now guarded with PermissionsGuard + PermissionString.NOTIFY_VIEW

Ghi chú: Scope Bypass nghĩa là endpoint này gọi controller decorator @SkipTenantCheck(), do đó bỏ qua TenantGuard nhưng vẫn phải có JWT (ngoại trừ @Public).

---

Extended Backend API Traceability (From CKB)

Rehydrated from docs_delivery_v2/08_TRACEABILITY/API_TRACEABILITY_EXTENDED.md

IAM APIs (CP-01)

Method	Endpoint	Guard Chain	Permission	Entity	Event	Spec	Status
POST	/api/v2/iam/auth/login	@Public()	—	User	—	FR-AUTH-01	✅
POST	/api/v2/iam/auth/login/zalo	@Public()	—	User	—	FR-AUTH-02	✅
POST	/api/v2/iam/auth/refresh	@Public(refresh)	—	—	—	FR-AUTH-04	⬜
POST	/api/v2/iam/auth/logout	JwtAuth	—	—	—	FR-AUTH-05	⬜
POST	/api/v2/iam/auth/register	@Public()	—	User, Membership	iam.member.accepted	FR-AUTH-08	⬜
POST	/api/v2/iam/auth/switch-tenant	JwtAuth	—	Membership	—	FR-AUTH-06	⬜
GET	/api/v2/iam/tenants	JwtAuth+Admin	SystemAdmin	Tenant	—	FR-TENANT-01	✅
POST	/api/v2/iam/tenants	JwtAuth+Admin	SystemAdmin	Tenant, Role	iam.tenant.created	FR-TENANT-01	✅
POST	/api/v2/iam/tenants/register	@Public()	—	User, Tenant, Role, Membership	iam.tenant.created, iam.user.created	FR-TENANT-02	✅
GET	/api/v2/iam/tenants/:id/provisioning	JwtAuth	TENANT_CREATE_OPEN	TenantProvisionJob	iam.tenant.provisioned	FR-TENANT-02	✅
GET	/api/v2/iam/tenants/:id	JwtAuth+Tenant	TENANT_VIEW	Tenant	—	FR-TENANT-03	✅
PATCH	/api/v2/iam/tenants/:id	JwtAuth+Tenant	TENANT_MANAGE	Tenant	iam.tenant.updated	FR-TENANT-04	✅
GET	/api/v2/iam/tenants/:id/settings	JwtAuth+Tenant	TENANT_VIEW	TenantSettings	—	FR-TN-02	✅
PATCH	/api/v2/iam/tenants/:id/settings	JwtAuth+Tenant	TENANT_MANAGE	TenantSettings	iam.tenant.settings_updated	FR-TN-02	✅
PATCH	/api/v2/iam/tenants/:id/suspend	JwtAuth+Admin	SystemAdmin	Tenant	iam.tenant.suspended	FR-TN-03	⬜
GET	/api/v2/iam/tenants/:tid/members	JwtAuth+Tenant	MEMBER_VIEW	Membership	—	FR-MEMBER-01	⬜
POST	/api/v2/iam/tenants/:tid/members/invite	JwtAuth+Tenant	MEMBER_MANAGE	Membership	iam.member.invited	FR-MEMBER-02	⬜
PATCH	/api/v2/iam/members/:id/role	JwtAuth+Tenant	MEMBER_MANAGE	Membership	iam.member.role_changed	FR-MEMBER-04	⬜
DELETE	/api/v2/iam/members/:id	JwtAuth+Tenant	MEMBER_MANAGE	Membership	iam.member.removed	FR-MEMBER-05	⬜
GET	/api/v2/iam/tenants/:tid/roles	JwtAuth+Tenant	ROLE_VIEW	Role	—	FR-ROLE-01	⬜
POST	/api/v2/iam/tenants/:tid/roles	JwtAuth+Tenant	ROLE_MANAGE	Role	iam.role.created	FR-ROLE-02	⬜
PATCH	/api/v2/iam/roles/:id	JwtAuth+Tenant	ROLE_MANAGE	Role	iam.role.updated	FR-ROLE-03	⬜
DELETE	/api/v2/iam/roles/:id	JwtAuth+Tenant	ROLE_MANAGE	Role	iam.role.deleted	FR-ROLE-04	⬜

Commerce APIs

Method	Endpoint	Permission	Entity	Event	Spec	Status
GET	/api/v2/catalog/categories	CAT_VIEW	Category	—	FR-CT-01	🟡
POST	/api/v2/catalog/categories	CAT_MANAGE	Category	catalog.category.created	FR-CT-01	🟡
GET	/api/v2/catalog/products	PROD_VIEW	Product	—	FR-CT-02	🟡
POST	/api/v2/catalog/products	PROD_MANAGE	Product	catalog.product.created	FR-CT-02	🟡
POST	/api/v2/catalog/products/import	PROD_MANAGE	Product	—	FR-CT-06	⬜
GET	/api/v2/ecommerce/orders	ORDER_VIEW	Order	—	FR-OR-07	⬜
POST	/api/v2/ecommerce/orders	ORDER_MANAGE	Order	order.created	FR-OR-02	⬜
PATCH	/api/v2/ecommerce/orders/:id/status	ORDER_MANAGE	Order	order.	FR-OR-01	✅
POST	/api/v2/ecommerce/orders/:id/refund	ORDER_MANAGE	Refund	order.refund.requested	FR-OR-06	⬜
POST	/api/v2/marketing/vouchers/validate	—	Voucher	—	FR-VO-01	⬜
POST	/api/v2/marketing/vouchers/apply	—	VoucherRedemption	voucher.redeemed	FR-VO-01	⬜

Loyalty & CRM APIs

Method	Endpoint	Permission	Entity	Event	Spec	Status
GET	/loyalty/points-ledger	LOYALTY_VIEW	PointTransaction	—	FR-LY-01	✅
GET	/loyalty/payouts	LOYALTY_VIEW	Payout	—	FR-LY-02	✅
GET	/crm/loyalty/conditions	CRM_VIEW	MembershipCondition	—	FR-CL-01	✅
POST	/crm/loyalty/conditions	CRM_MANAGE	MembershipCondition	—	FR-CL-02	✅
POST	/crm/loyalty/conditions/evaluate	CRM_MANAGE	MembershipCondition	—	FR-CL-03	✅

Supply Chain APIs

Method	Endpoint	Permission	Entity	Event	Spec	Status
GET	/api/v2/supply-chain/production/work-orders	PROD_MANAGE	WorkOrder	—	—	✅
POST	/api/v2/supply-chain/production/work-orders	PROD_MANAGE	WorkOrder	production.order.created	—	✅
GET	/api/v2/supply-chain/production/work-orders/:id	PROD_MANAGE	WorkOrder	—	—	✅
PATCH	/api/v2/supply-chain/production/work-orders/:id/status	PROD_MANAGE	WorkOrder	production.order.status_changed	—	✅
PATCH	/api/v2/supply-chain/production/work-orders/:id/progress	PROD_MANAGE	WorkOrder	—	—	✅

Balance/Billing APIs

Method	Endpoint	Permission	Entity	Event	Spec	Status
GET	/api/v2/balance/wallet	BILLING_VIEW	Wallet	—	—	✅
GET	/api/v2/balance/transactions	BILLING_VIEW	BalanceTransaction	—	—	✅
POST	/api/v2/balance/adjust	BILLING_MANAGE	BalanceTransaction	balance.adjusted	—	✅
GET	/api/v2/billing/subscriptions/active	BILLING_VIEW	Subscription	—	—	✅
POST	/api/v2/billing/subscribe	BILLING_MANAGE	Subscription	billing.subscribed	—	✅
DELETE	/api/v2/billing/cancel	BILLING_MANAGE	Subscription	billing.cancelled	—	✅
GET	/api/v2/billing/usage/summary	BILLING_VIEW	UsageSummary	—	—	✅

Notification APIs

Method	Endpoint	Permission	Entity	Event	Spec	Status
GET	/api/v2/content/notifications/in-app	NOTIFY_VIEW	Notification	—	—	✅
PATCH	/api/v2/content/notifications/in-app/:id/read	NOTIFY_VIEW	Notification	notification.read	—	✅
PATCH	/api/v2/content/notifications/in-app/read-all	NOTIFY_VIEW	Notification	—	—	✅
GET	/api/v2/content/notifications/in-app/unread-count	NOTIFY_VIEW	Notification	—	—	✅

Zalo Integration APIs

Method	Endpoint	Permission	Entity	Event	Spec	Status
GET	/api/v2/integrations/zalo/oas	SYSTEM_ADMIN	ConnectedOA	—	—	✅
POST	/api/v2/integrations/zalo/connect	SYSTEM_ADMIN	ConnectedOA	zalo.oa.connected	—	✅
GET	/api/v2/integrations/zalo/zns/templates	SYSTEM_ADMIN	ZnsTemplate	—	—	✅
POST	/api/v2/integrations/zalo/zns/send	SYSTEM_ADMIN	ZnsTemplate	zalo.zns.sent	—	✅

Supply Chain + Other APIs (Each module's API details are in their respective CKB 30_API_CONTRACT section)