权限标识命名规范文档

一、文档说明

1.1 目的

统一菜单、按钮权限标识的命名规则，确保前后端权限交互一致性，降低维护成本，提升团队协作效率。

1.2 适用范围

适用于项目中所有菜单权限（控制菜单可见性）、按钮权限（控制按钮显示/可用性）的标识定义，覆盖前端权限判断、后端接口校验、数据库权限存储全流程。

二、核心命名原则

原则	说明	示例
分层归类	按“系统 → 模块 → 菜单 → 操作”四级分层，用固定分隔符（.）拆分，清晰体现权限归属	多系统场景：`sys-ams.user.list.add`；单系统场景：`user.list.add`
语义直观	使用业务术语+英文单词组合，避免拼音、无意义缩写，开发人员可直接通过标识理解功能	正确：`order.list.export`（订单列表导出）；错误：`ddgl.tj`（订单管理统计，拼音+缩写）
前后端统一	前端权限判断常量、后端权限枚举、数据库存储值必须完全一致，禁止“前端用 A 标识，后端用 B 标识”	前端常量：`const ORDER_LIST_ADD = 'order.list.add'`；后端枚举：`ORDER_LIST_ADD("order.list.add", "订单列表新增")`
扩展性	预留多系统集成、模块拆分空间，避免后期功能扩展时大规模修改标识	多系统通过“sys-xxx”前缀区分，子模块通过“模块.子模块”分层（如`goods.category.manage`）

三、菜单权限标识规范

3.1 命名结构

单系统场景：模块标识.菜单标识
多系统场景：系统标识.模块标识.菜单标识

3.2 各层级定义

层级	含义	命名规则	约束
系统标识（可选）	多系统集成时，区分不同系统	格式：`sys-系统简称`，系统简称用小写英文（2-4 个字母）	单系统项目可省略，避免冗余
模块标识	业务核心模块，对应项目功能模块划分	用小写英文单词，选择模块核心名词（1-2 个词）	禁止使用拼音或模糊词汇（如“data”“info”）
菜单标识	具体菜单名称，体现菜单功能	用小写英文（名词/动词+名词），如“list”（列表）、“detail”（详情）、“setting”（设置）	嵌套菜单按“父菜单标识.子菜单标识”分层

3.3 菜单权限标识示例

业务场景	菜单名称	系统类型	权限标识	说明
电商订单模块	订单列表	单系统	`order.list`	无系统标识，直接“模块+菜单”
电商订单模块	订单详情	单系统	`order.detail`	对应订单列表的子菜单，按“模块+菜单”命名
AMS 系统用户模块	用户管理	多系统	`sys-ams.user.manage`	多系统加“sys-ams”前缀，子菜单按“模块+父菜单+子菜单”分层
系统设置模块	角色管理	单系统	`system.setting.role`	嵌套菜单（系统设置 → 角色管理），体现层级关系
商品模块	商品分类管理	单系统	`goods.category.manage`	子模块（分类）通过“模块.子模块.菜单”命名

四、按钮权限标识规范

4.1 命名结构

单系统场景：模块标识.菜单标识.操作标识
多系统场景：系统标识.模块标识.菜单标识.操作标识

4.2 各层级定义

前 3 级（系统标识、模块标识、菜单标识）：与对应菜单的权限标识完全一致，确保“按钮属于哪个菜单”清晰可查
操作标识：体现按钮具体功能，用“动词”或“动词+名词”组合，常用操作标识见下表

4.3 常用操作标识字典

操作类型	操作标识	适用场景	示例
新增	`add`/`create`	新增数据（如新增用户、新增订单）	`user.list.add`（用户列表新增）
删除	`delete`/`remove`	单条删除、批量删除	单条删除：`order.list.delete`；批量删除：`order.list.batch.delete`
编辑	`edit`/`update`	修改数据（如编辑用户信息、修改订单状态）	`user.detail.edit`（用户详情编辑）
查看	`view`/`detail`	按钮触发的详情查看（非菜单跳转）	`order.list.view`（订单列表 → 查看详情按钮）
导出	`export`	导出 Excel/PDF 等文件，可加文件类型后缀	导出 Excel：`order.list.export.excel`；通用导出：`order.list.export`
导入	`import`	导入数据（如导入用户、导入商品）	`goods.list.import`（商品列表导入）
审核	`approve`/`review`	审批类操作，可加审批结果后缀	审核通过：`order.list.approve.pass`；通用审核：`order.list.approve`
启用/禁用	`enable`/`disable`	状态切换类操作（如账号启用、功能禁用）	`user.list.enable`（用户列表启用）
提交	`submit`	多步骤流程中的提交操作（如订单确认提交）	`order.list.confirm.submit`（订单列表 → 确认弹窗 → 提交）

4.4 按钮权限标识示例

业务场景	按钮功能	所属菜单	系统类型	权限标识	说明
电商用户模块	用户新增	用户列表	单系统	`user.list.add`	单系统场景，“模块+菜单+操作”
AMS 系统订单模块	订单删除	订单列表	多系统	`sys-ams.order.list.delete`	多系统场景，加“sys-ams”系统标识
电商订单模块	批量审核订单	订单列表	单系统	`order.list.batch.approve`	批量操作加“batch.”前缀
系统设置模块	角色编辑	角色管理	单系统	`system.setting.role.edit`	嵌套菜单下的按钮，按“模块+父菜单+子菜单+操作”命名
电商商品模块	商品导入 Excel	商品列表	单系统	`goods.list.import.excel`	带文件类型的操作，加后缀区分

五、特殊场景处理规则

5.1 通用按钮（跨菜单复用）

定义：如“刷新”“重置”“返回”等无需权限控制或跨菜单复用的按钮
命名结构：common.操作标识
示例：common.refresh（刷新按钮）、common.reset（重置按钮）

5.2 弹窗内按钮

定义：弹窗（如确认弹窗、编辑弹窗）内的按钮，需关联主菜单
命名结构：模块标识.主菜单标识.弹窗功能.操作标识
示例：订单列表 → 确认弹窗 → 提交按钮：order.list.confirm.submit

5.3 数据权限关联按钮

定义：按钮权限需结合数据范围（如“仅查看自己的订单”“查看所有订单”）
命名结构：模块标识.菜单标识.操作标识.数据范围
示例：order.list.view.self（查看自己的订单）、order.list.view.all（查看所有订单）

六、权限标识字典表（示例）

权限类型	权限标识	权限名称	所属模块	前后端使用场景	备注
菜单权限	`order.list`	订单列表	订单模块	前端：控制订单列表菜单显示；后端：校验菜单访问权限	-
菜单权限	`sys-ams.user.manage`	用户管理	AMS 系统-用户模块	前端：控制 AMS 系统用户管理菜单显示；后端：校验菜单访问权限	多系统场景
按钮权限	`order.list.add`	订单新增	订单模块	前端：订单列表页新增按钮显示；后端：校验新增接口权限	-
按钮权限	`goods.list.export.excel`	商品导出 Excel	商品模块	前端：商品列表页导出 Excel 按钮显示；后端：校验导出接口权限	带文件类型后缀
通用按钮权限	`common.refresh`	刷新	通用模块	前端：所有页面刷新按钮显示	跨菜单复用

七、落地检查清单

检查项	检查内容	结果（是/否）
1	权限标识是否按“系统 → 模块 → 菜单 → 操作”分层
2	无拼音、无意义缩写（如“ddgl”“add1”）
3	前后端权限标识完全一致（前端常量=后端枚举=数据库存储值）
4	多系统场景加“sys-xxx”前缀，单系统场景无冗余前缀
5	批量操作加“batch.”前缀，数据范围关联权限加“数据范围”后缀
6	新增权限标识已录入“权限标识字典表”

八、附则

新增权限标识时，需由开发人员按本规范定义，提交代码前需经团队负责人审核
若业务场景需调整规则，需更新本文档并同步至全团队，禁止私自修改命名规则
定期（如每季度）维护“权限标识字典表”，清理废弃标识，确保标识有效性