Component Permission Integration¶

📄 创建: 未记录

https://doc.xpku.com/raw/tech/frontend/permission/skill.md

本技能用于指导业务组件接入 @bams-app/permission 权限能力，核心依据是文档 work/packages/permission/业务组件权限接入指南.md。

触发场景¶

当出现以下需求时应调用本技能：

• 用户要求"业务组件接入权限"
• 用户要求"给按钮加权限控制"
• 用户提到 v-permission
• 用户提到 AuthPermission
• 用户提到 hasPerm
• 用户提到"权限码层级"
• 用户提到"模块级权限"、"通配符权限"或"按钮权限改造"

执行前置¶

开始改造前，必须先读取以下文档全文：

• 文档路径：work/packages/permission/业务组件权限接入指南.md

如果用户同时要求确认实现细节，还应结合以下代码一起核对：

• 权限入口：work/packages/permission/src/utils/permission.js
• 匹配工具：work/packages/permission/src/utils/permissionMatcher.js
• 指令实现：work/packages/permission/src/directive.js
• 组件实现：work/packages/permission/src/components/AuthPermission.vue

核心原则¶

1. 业务组件可以直接使用权限能力，不需要额外安装步骤。
2. 优先使用 v-permission 处理模板中的按钮、操作项和展示型节点。
3. 当需要包裹一整段区域时，使用 AuthPermission。
4. 当需要在脚本逻辑中判断权限时，使用 hasPerm。
5. 改造时优先保持现有业务结构稳定，只做最小必要改动。
6. 权限码设计优先使用 模块：操作 或 模块：子模块：操作。

接入方式选择¶

1. 指令方式¶

以下场景优先使用 v-permission：

• 按钮显隐
• 表格操作列按钮显隐
• 下拉菜单项显隐
• 简单节点展示控制

示例：

<el-button v-permission="'meter:export'">导出</el-button>
<el-button v-permission="['meter:edit', 'meter:update']">编辑</el-button>

2. 组件方式¶

以下场景优先使用 AuthPermission：

• 一整块区域需要统一做权限包裹
• 某段复杂模板需要整体控制显隐

示例：

<AuthPermission code="meter:delete">
  <el-button>删除</el-button>
</AuthPermission>

3. JS 判断方式¶

以下场景使用 hasPerm：

• 点击事件前判断是否允许继续执行
• 数据处理逻辑需要分权限分支
• 动态生成操作项时做过滤

示例：

import { hasPerm } from "@bams-app/permission";

if (hasPerm("meter:config")) {
  // 执行有权限时的逻辑
}

权限码规则¶

层级格式¶

• 模块级：meter
• 操作级：meter:export
• 细粒度：meter:list:export
• 通配符：meter:*、system:user:*

匹配规则¶

当前权限实现支持以下规则：

1. 精确匹配：meter:export 命中 meter:export
2. 模块级匹配：meter 可匹配 meter:view、meter:list:export
3. 向上兼容：meter:export 可匹配 meter:list:export
4. 通配符匹配：system:user:* 可匹配 system:user:add
5. 超级管理员直通：userStore.role === 'admin' 时直接返回 true

示例¶

// 已授权权限
["meter", "system:user:*", "order:export"];

hasPerm("meter:view"); // true
hasPerm("meter:list:export"); // true
hasPerm("system:user:add"); // true
hasPerm("order:list:export"); // true
hasPerm("system:role:edit"); // false

改造步骤¶

1. 识别权限点¶

先识别目标组件中的权限控制点，包括但不限于：

• 顶部工具栏按钮
• 表格操作列按钮
• 批量操作按钮
• 下拉菜单项
• 页面局部区域
• 点击事件中的逻辑分支

2. 选择合适接入方式¶

按以下优先级选择：

1. 模板节点显隐优先用 v-permission
2. 区块包裹优先用 AuthPermission
3. 逻辑判断使用 hasPerm

3. 复用现有权限码¶

优先复用已有权限命名，不要随意新增风格不一致的权限码。

如果需要新增权限码，建议遵循以下格式：

• 模块：操作
• 模块：子模块：操作

4. 保持业务行为稳定¶

改造后应保证：

• 有权限用户行为不变
• 无权限用户仅隐藏或阻止对应能力
• 不引入与权限无关的结构性重构

输出要求¶

完成改造时，输出内容应包含：

1. 接入方式选择说明
2. 修改的文件列表
3. 每个权限点对应的权限码
4. 是否使用了层级权限或通配符权限
5. 是否涉及 JS 逻辑权限判断
6. 改造后的注意事项或潜在风险

自检清单¶

提交前检查以下内容：

• 是否已阅读权限接入指南
• 是否优先采用 v-permission
• 是否只做了最小必要改动
• 是否使用了符合规范的权限码
• 是否确认数组权限仍为 Or 逻辑
• 是否确认无权限节点会被正确隐藏
• 是否在需要时使用了 hasPerm
• 是否未误改无关业务逻辑

工作方式¶

接到任务后，按以下顺序执行：

1. 先读取权限接入指南
2. 再分析目标组件当前实现
3. 识别所有权限控制点
4. 选择合适的接入方式并实施改造
5. 输出最小必要改动
6. 完成后做一轮权限规则自检