1. 问题：多端权限的一致性

传统系统权限的实现分散在三个地方：

前端：菜单显隐（if-else 硬编码）
后端：API 中间件（JWT + 角色判断）
AI：Tool Registry（if-else 硬编码）

三个地方的判断逻辑各自独立，容易出现"前端隐藏了按钮但 API 没保护"或"API 返回 403 但 AI 仍建议该操作"的安全漏洞。

EAMX 的解法：全部依赖 packages/core/src/ability.ts 导出的同一套 AppAbility。

2. Actions 和 Subjects 定义

Action 不是简单的 CRUD——包含工单的生命周期动作（grab/start/complete/accept/close），这让权限粒度足够细：一个角色可以"查看所有工单"但不能"抢单"。

3. 权限字符串格式

`` "manage:equipment" → can("manage", "Equipment") "read:workorder" → can("read", "WorkOrder") "use:aichat" → can("use", "AiChat") "grab:workorder" → can("grab", "WorkOrder") // 抢单权限 ``

resolvePermission 通过 SUBJECT_KEY_MAP 将小写 subject → PascalCase Subject 类型：

```typescript const SUBJECT_KEY_MAP: Record<string, Subjects> = { "workorder": "WorkOrder", "equipment": "Equipment", // ... };

function resolvePermission(code: string): [Actions, Subjects] | null { const [action, subjectKey] = code.split(":"); return SUBJECT_KEY_MAP[subjectKey] ? [action, subject] : null; } ```

4. 能力构建：从权限列表到 AppAbility

```typescript export function buildAbilityFromPermissions( permissions: string[], options?: { isAdmin?: boolean; permissionConditions?: Record<string, Record<string, any>>; }, ): AppAbility { const { can, build } = new AbilityBuilder<AppAbility>(createMongoAbility);

// 平台超管直接拥有所有权限 if (options?.isAdmin) { can("manage", "all"); return build(); }

for (const code of permissions) { const [action, subject] = resolvePermission(code); const conditions = options?.permissionConditions?.[code]; if (conditions) { can(action, subject, conditions); // 带条件的权限 } else { can(action, subject); // 无条件权限 } } return build(); } ```

5. 条件权限：三维数据范围

```typescript // 部门管理员只能看自己部门的工单 can("read", "WorkOrder", { departmentId: user.departmentId });

// 普通维修工只能看自己的工单 can("read", "WorkOrder", { responsibleUserId: user.id }); ```

这依赖 @casl/ability 的 MongoDB 风格条件查询：

```typescript // 前端检查 ability.can("read", "WorkOrder") // → 带条件的 can 在纯前端返回 false（因为没有 DB 上下文）

// 后端 Drizzle 注入条件 const rules = ability.rulesFor("read", "WorkOrder"); // → [{ action: "read", subject: "WorkOrder", conditions: { departmentId: "dept-1" } }] // → SQL: WHERE department_id = 'dept-1' ```

三维数据范围：

all：能看到整个平台的数据（超管）
department：只看本部门（部门管理员）
self：只看自己的（普通员工）

6. 前后端 + AI 三层消费

| 层级 | 消费方式 | 实现位置 | |---|---|---| | 前端 | ability.can(action, subject) → 控制按钮/菜单显隐 | 共享 AppAbility 实例 | | 后端 API | 中间件 ability.can(action, subject) + Drizzle 条件注入 | API Server | | AI Tool Registry | toolRegistry.getAuthorized(ability) 过滤 Tool 列表 | Tool Factory |

``typescript // AI Tool Registry 消费 getAuthorized(ability: AppAbility): McpTool[] { return this.tools.filter(t => { const casl = t.annotations?.casl; if (!casl) return true; // 无 CASL 注解的 Tool 对所有人开放 return ability.can(casl.action, casl.subject); }); } ``

7. 核心文件索引

| 文件 | 行数 | 职责 | |---|---|---| | packages/core/src/ability.ts | 132 | CASL 类型 + buildAbilityFromPermissions | | packages/core/src/types.ts | — | PluginManifest、NavItem、PermissionDefinition | | 各个插件的 permissions 字段 | — | 插件自有权限定义 |

下一篇：审批工作流引擎——LifecycleBus 的拦截模式如何实现零侵入审批流。