feat: introduce comprehensive API documentation and RBAC guidelines

- Added a new `api.md` file detailing the TrackGo HTTP API, including agent rules, authentication mechanisms, and global HTTP contracts.
- Established a new RBAC (Role-Based Access Control) framework in `web-rbac.mdc` to ensure all product modules in `apps/web` are gated by permissions from `GET /auth/me`.
- Updated security and web module architecture rules to incorporate RBAC requirements, ensuring consistent application of permissions across modules.

This commit enhances the project's API clarity and security by providing a structured approach to user permissions and interactions.

.cursor/rules/security.mdc

@@ -13,6 +13,7 @@ Before ANY commit:
 - [ ] All user inputs validated (Zod + `@repo/ui/validators`)
 - [ ] XSS prevention — React text nodes by default; never unsanitized `dangerouslySetInnerHTML`
 - [ ] Auth tokens only via `src/core/lib/auth.helper` and the shared `apiClient` interceptors
+- [ ] Product modules in `apps/web` wire RBAC (`moduleKey` + menu `moduleKey`); see `web-rbac.mdc`
 - [ ] No secrets in client bundles; env files only under `apps/*/.env*`
 - [ ] Error messages shown to users do not leak tokens or stack traces
 

.cursor/rules/web-module-architecture.mdc

@@ -52,6 +52,7 @@ Copy `example/full-page` — do not invent a third layout style.
 3. **Domain factory** — singleton service via `apiClient` from `src/core/lib/api-client` (never raw axios).
 4. **i18n** — `useEnterpriseModuleTranslationContext()`; module keys unprefixed; shared via `common:` / `nav:`.
 5. **Navigation** — `useEnterpriseModuleNavigationContext()` helpers, not ad-hoc paths.
+6. **RBAC** — `moduleKey` must match an `api.md` privilege-keys `code`; the menu leaf uses the same `moduleKey`. See `web-rbac.mdc`.
 
 ## Layer rules
 

.cursor/rules/web-rbac.mdc

@@ -0,0 +1,42 @@
+---
+description: RBAC is required for every apps/web product module (menu, moduleKey, action flags)
+globs: apps/web/src/apps/main/**/*.{ts,tsx}
+alwaysApply: false
+---
+
+# Web module RBAC
+
+Every authenticated product module in `apps/web` must be gated by `GET /auth/me` permissions. Copy Privileges (`system/privileges`) — do not invent a second RBAC path.
+
+Catalog keys live in `api.md` §4 (`PRIVILEGES`, `CONFIGURATION.BRANCH`, `SALES.ORDER`, …). `isSuperadmin` bypasses the matrix (adapter returns `defaultPrivileges`).
+
+## Required wiring (do all four)
+
+1. **`moduleKey`** on `ModuleConfigEntity` equals the catalog `code` (e.g. `CONFIGURATION.BRANCH`).
+2. **Menu leaf** in `layouts/data/menu.data.ts` sets the same `moduleKey`. `filterMenuByViewPrivilege` hides the item when `ALLOW_VIEW` is false.
+3. **Routes** wrap in `EnterpriseModuleProvider` so missing `ALLOW_VIEW` shows forbidden (no all-true flash).
+4. **Do not** re-check create/edit/delete in page JSX. Foundations already hide actions from `PrivilegeEntity`.
+
+```ts
+// BAD — custom hide/show, or menu without moduleKey
+if (!user.permissions.BRANCHES?.create) return null;
+{ key: 'branches', path: '/app/system/branches/index' }
+
+// GOOD
+export const branchesModuleConfig = { moduleKey: 'CONFIGURATION.BRANCH', /* ... */ };
+{ key: 'system-branches', path: '/app/system/branches/index', moduleKey: 'CONFIGURATION.BRANCH' }
+```
+
+## Flag map (`mapUserPrivileges`)
+
+| API flag | UI |
+|---|---|
+| `view` | `ALLOW_VIEW` (menu + module chrome) |
+| `create` | `ALLOW_CREATE` (create + duplicate) |
+| `update` | `ALLOW_EDIT` + `ALLOW_ACTIVATE` + `ALLOW_DEACTIVATE` |
+| `delete` | `ALLOW_DELETE` |
+| `import` | `ALLOW_IMPORT` |
+
+Missing flag → `false`. Cycles/plans: key follows `purpose` (`SALES.CYCLE` / `LOGISTICS.PLAN`), not a generic `CYCLES` key.
+
+Reference: [apps/web/src/core/lib/map-user-privileges.ts](apps/web/src/core/lib/map-user-privileges.ts), [filter-menu-by-view-privilege.ts](apps/web/src/core/lib/filter-menu-by-view-privilege.ts).