用途：为 MaintainX 集成配置企业级基于角色的访问控制（RBAC），涵盖角色定义、按地点（location）与指派（assignee）范围的权限过滤、按角色划分的 API 密钥以及审计日志。适用于实施 SSO、管理组织级权限等场景。
前提条件：MaintainX 企业版计划；理解 RBAC 概念；Node.js 18+。
角色层级：Organization Admin 可管理所有地点、用户、团队与设置，拥有完整 API 访问；Location Manager 可管理所分配地点的工作单与资产，API 按 locationId 过滤；Technician 可查看/更新被指派的工作单，API 按 assigneeId 过滤；Viewer 只读，仅限 GET 端点。
主要能力：
- 角色定义：以 TypeScript 定义 Role 类型与 ROLE_PERMISSIONS 映射，为每个角色声明资源、动作（create/read/update/delete）与作用域（all/location/assigned）。
- 权限中间件：提供 Express 的 authorize(resource, action) 中间件，校验权限并注入作用域过滤（location 时设置 req.query.locationId，assigned 时设置 req.query.assigneeId）。
- 按角色划分的 API 密钥：为每个角色创建独立 MaintainXClient，通过环境变量 MAINTAINX_API_KEY_ADMIN、MAINTAINX_API_KEY_MANAGER、MAINTAINX_API_KEY_TECH、MAINTAINX_API_KEY_VIEWER 实现纵深防御。
- 用户与团队管理：获取用户及其角色，并关联团队信息。
- 审计日志：记录访问控制决策（时间戳、用户、角色、资源、动作、结果、地点范围），可发送至 CloudWatch、Datadog 等日志聚合。
使用方式：按步骤定义角色、编写中间件、创建作用域客户端、管理用户团队、记录审计日志；在路由上应用 authorize()。
限制与错误处理：403 通常因缺少动作权限，需检查 ROLE_PERMISSIONS；manager 结果为空多因地点范围过窄，需核对 locationIds；作用域密钥缺失需补充对应环境变量；审计日志缺失需确保所有路由都应用 authorize()。
资源：MaintainX Enterprise、OWASP Access Control Cheat Sheet、MaintainX API Reference。完整平台迁移可参考 maintainx-migration-deep-dive。