权限命名规范

统一命名让 Auth、业务 App、管理员和 AI Agent 对同一个权限含义保持一致。权限 key 是稳定 API，不是临时 UI 文案。

1. 标准格式

{app}.{resource_path}.{action}

示例：

crm.access
crm.contact.read
crm.contact.write
reporting.dashboard.export
training.course.publish
auth.apps.sso.manage

{app}.access 是特例，也是每个 App 的必需权限。

2. App 段

• 使用 Manifest 的 appKey。
• 全小写，推荐字母、数字和下划线的稳定短名称。
• 不包含环境、域名、部门或公司名称。
• 发布后变更 appKey 等同新 App 迁移。

3. Resource 段

Resource path 表示业务对象或能力边界，至少包含一个资源段。普通业务权限优先使用单段稳定名词：

contact
report
campaign
course
requirement

只有确实存在稳定层级时才使用多段资源，例如 auth.apps.sso.manage 的资源是 apps.sso、动作是 manage。Auth 始终把最后一段解析为 action，把 app 与 action 之间的所有段解析为 resource。不要为了页面分组随意增加层级。

避免 page1、module_new、misc、button 等 UI 或临时实现名称。

4. Action 段

优先复用标准动作：

同一个 App 内不要同时使用 view、read、get 表示相同动作。

5. 粒度原则

一个权限应该对应可独立审计和授权的业务动作。不要为每个按钮创建权限，也不要用一个 admin 权限覆盖所有高风险操作。

推荐：

crm.contact.read
crm.contact.write
crm.contact.export

不推荐：

crm.button_17.click
crm.all.manage
crm.client_123.read

6. 角色命名

角色 key 使用 {app}.{role}：

crm.viewer
crm.operator
crm.admin

角色名称用中文明确职责。角色只聚合权限，不编码客户项目、部门、地区或单个用户。

7. 兼容性

• 权限显示名称和说明可以更新，不视为破坏性变更。
• permission key 的含义不得静默改变。
• 拆分权限时先新增，再迁移，最后废弃旧 key。
• 合并权限也必须保留旧 key 至少一个迁移周期。
• 业务 App 遇到未知权限应忽略，不应报错或自动授权。

8. 审查问题

提交 Manifest 前回答：

1. 这个动作是否需要独立授权和审计？
2. Resource path 是否是稳定业务对象层级，而不是页面或组件？
3. Action 是否复用了 App 内已有词汇？
4. 是否错误地把客户/部门数据范围编码进 key？
5. 是否包含 {app}.access？
6. 角色是否只引用当前 App 权限？