# 权限规则定义

<cite>
**本文档引用文件**  
- [sys_auth_rule.go](file://api/sys_auth_rule/v1/sys_auth_rule.go)
- [model.go](file://api/sys_auth_rule/v1/model.go)
- [sys_auth_rule.go](file://internal/controller/sys_auth_rule/sys_auth_rule_v1_rule_add.go)
- [sys_auth_rule.go](file://internal/controller/sys_auth_rule/sys_auth_rule_v1_rule_update.go)
- [sys_auth_rule.go](file://internal/controller/sys_auth_rule/sys_auth_rule_v1_rule_delete.go)
- [sys_auth_rule.go](file://internal/service/sys_auth_rule.go)
- [v_1_sys_auth_rule.go](file://internal/dao/v_1_sys_auth_rule.go)
- [v_1_sys_auth_rule.go](file://internal/model/entity/v_1_sys_auth_rule.go)
- [sys_auth_rule.go](file://internal/model/sys_auth_rule.go)
</cite>

## 目录
1. [简介](#简介)
2. [权限规则数据模型设计](#权限规则数据模型设计)
3. [权限规则接口实现](#权限规则接口实现)
4. [权限规则与角色、菜单的关联关系](#权限规则与角色菜单的关联关系)
5. [多层级权限继承机制](#多层级权限继承机制)
6. [权限规则配置最佳实践](#权限规则配置最佳实践)
7. [权限规则冲突检测与解决策略](#权限规则冲突检测与解决策略)
8. [权限规则版本管理建议](#权限规则版本管理建议)

## 简介
本文档详细阐述了 kami_backend 系统中权限规则的定义、实现机制与最佳实践。权限系统是保障系统安全的核心组件，通过精细化的权限控制实现不同角色对系统资源的访问隔离。本文深入分析权限规则的数据结构、接口实现、关联关系及高级特性，为系统维护和扩展提供全面的技术指导。

## 权限规则数据模型设计

权限规则的数据模型设计基于树形结构，支持目录、菜单和按钮三级权限粒度。核心字段包括规则ID、规则类型、规则值等，具备良好的扩展性和查询效率。

```mermaid
erDiagram
SYS_AUTH_RULE {
uint id PK
uint pid FK
string name UK
string title
uint menuType
int weigh
uint isHide
string path
string component
uint isLink
uint isIframe
uint isCached
uint isAffix
string linkUrl
string redirect
string icon
string condition
string remark
string moduleType
uint modelId
datetime createdAt
datetime updatedAt
}
SYS_AUTH_RULE ||--o{ SYS_AUTH_RULE : "父子关系"
```

**图示来源**  
- [v_1_sys_auth_rule.go](file://internal/model/entity/v_1_sys_auth_rule.go#L11-L34)
- [v_1_sys_auth_rule.go](file://internal/dao/v_1_sys_auth_rule.go#L21-L23)

**本节来源**  
- [v_1_sys_auth_rule.go](file://internal/model/entity/v_1_sys_auth_rule.go#L11-L34)
- [model.go](file://api/sys_auth_rule/v1/model.go#L6-L52)

### 核心字段说明

| 字段名 | 类型 | 必填 | 约束 | 说明 |
|--------|------|------|------|------|
| id | uint | 是 | 主键 | 权限规则唯一标识 |
| pid | uint | 是 | 外键 | 父级规则ID，根节点为0 |
| name | string | 是 | 唯一索引 | 规则编码，用于权限校验 |
| title | string | 是 | 长度1-100 | 规则显示名称 |
| menuType | uint | 是 | 0-2 | 类型：0目录 1菜单 2按钮 |
| weigh | int | 否 | - | 权重，用于排序 |
| isHide | uint | 否 | 0或1 | 显示状态：0显示 1隐藏 |
| path | string | 否 | - | 路由地址 |
| component | string | 否 | - | 前端组件路径 |
| isLink | uint | 否 | 0或1 | 是否外链 |
| isIframe | uint | 否 | 0或1 | 是否内嵌iframe |
| isCached | uint | 否 | 0或1 | 是否缓存 |
| isAffix | uint | 否 | 0或1 | 是否固定标签页 |
| linkUrl | string | 否 | - | 外链地址 |
| redirect | string | 否 | - | 路由重定向地址 |
| icon | string | 否 | - | 图标标识 |
| condition | string | 否 | - | 权限条件表达式 |
| remark | string | 否 | - | 备注信息 |
| moduleType | string | 否 | - | 所属模块类型 |
| modelId | uint | 否 | - | 关联模型ID |

**本节来源**  
- [v_1_sys_auth_rule.go](file://internal/model/entity/v_1_sys_auth_rule.go#L11-L34)
- [model.go](file://api/sys_auth_rule/v1/model.go#L6-L52)

## 权限规则接口实现

权限规则的增删改查接口实现了完整的业务逻辑，包括请求参数验证、数据持久化和缓存更新等关键环节。

### 创建接口实现

创建权限规则接口（`RuleAdd`）接收前端提交的规则信息，执行严格的参数验证后持久化到数据库。

```mermaid
sequenceDiagram
participant 前端 as 前端应用
participant 控制器 as 控制器
participant 服务层 as 服务层
participant 数据访问层 as 数据访问层
participant 数据库 as 数据库
前端->>控制器 : POST /menu/add
控制器->>控制器 : 参数验证
控制器->>服务层 : 调用Add方法
服务层->>数据访问层 : 插入记录
数据访问层->>数据库 : 执行INSERT
数据库-->>数据访问层 : 返回结果
数据访问层-->>服务层 : 返回插入ID
服务层->>服务层 : 更新缓存
服务层-->>控制器 : 返回成功
控制器-->>前端 : 返回响应
```

**图示来源**  
- [sys_auth_rule.go](file://api/sys_auth_rule/v1/sys_auth_rule.go#L30-L67)
- [sys_auth_rule.go](file://internal/controller/sys_auth_rule/sys_auth_rule_v1_rule_add.go#L1-L15)
- [sys_auth_rule.go](file://internal/service/sys_auth_rule.go#L14-L34)

**本节来源**  
- [sys_auth_rule.go](file://api/sys_auth_rule/v1/sys_auth_rule.go#L30-L67)
- [sys_auth_rule.go](file://internal/controller/sys_auth_rule/sys_auth_rule_v1_rule_add.go#L1-L15)

### 更新接口实现

更新权限规则接口（`RuleUpdate`）接收规则ID和更新字段，确保数据一致性并维护缓存同步。

```mermaid
sequenceDiagram
participant 前端 as 前端应用
participant 控制器 as 控制器
participant 服务层 as 服务层
participant 数据访问层 as 数据访问层
participant 数据库 as 数据库
前端->>控制器 : PUT /menu/update
控制器->>控制器 : 参数验证
控制器->>服务层 : 调用Update方法
服务层->>数据访问层 : 查询原记录
数据访问层->>数据库 : 执行SELECT
数据库-->>数据访问层 : 返回记录
数据访问层-->>服务层 : 返回记录
服务层->>数据访问层 : 更新记录
数据访问层->>数据库 : 执行UPDATE
数据库-->>数据访问层 : 返回结果
数据访问层-->>服务层 : 返回结果
服务层->>服务层 : 清除缓存
服务层-->>控制器 : 返回成功
控制器-->>前端 : 返回响应
```

**图示来源**  
- [sys_auth_rule.go](file://api/sys_auth_rule/v1/sys_auth_rule.go#L75-L104)
- [sys_auth_rule.go](file://internal/controller/sys_auth_rule/sys_auth_rule_v1_rule_update.go#L1-L15)
- [sys_auth_rule.go](file://internal/service/sys_auth_rule.go#L14-L34)

**本节来源**  
- [sys_auth_rule.go](file://api/sys_auth_rule/v1/sys_auth_rule.go#L75-L104)
- [sys_auth_rule.go](file://internal/controller/sys_auth_rule/sys_auth_rule_v1_rule_update.go#L1-L15)

### 删除接口实现

删除权限规则接口（`RuleDelete`）支持批量删除，采用软删除策略并维护树形结构完整性。

```mermaid
flowchart TD
A[接收删除请求] --> B{参数验证}
B --> |失败| C[返回错误]
B --> |成功| D[查询待删除节点]
D --> E{是否存在子节点}
E --> |是| F[级联删除子节点]
E --> |否| G[标记删除状态]
F --> H[更新数据库]
G --> H
H --> I[清除相关缓存]
I --> J[返回成功]
```

**图示来源**  
- [sys_auth_rule.go](file://api/sys_auth_rule/v1/sys_auth_rule.go#L102-L104)
- [sys_auth_rule.go](file://internal/controller/sys_auth_rule/sys_auth_rule_v1_rule_delete.go#L1-L15)
- [sys_auth_rule.go](file://internal/service/sys_auth_rule.go#L14-L34)

**本节来源**  
- [sys_auth_rule.go](file://api/sys_auth_rule/v1/sys_auth_rule.go#L102-L104)
- [sys_auth_rule.go](file://internal/controller/sys_auth_rule/sys_auth_rule_v1_rule_delete.go#L1-L15)

## 权限规则与角色、菜单的关联关系

权限规则通过中间表与角色建立多对多关联关系，实现灵活的权限分配机制。

```mermaid
erDiagram
SYS_ROLE {
uint id PK
string name
string remark
}
SYS_AUTH_RULE {
uint id PK
string name
string title
}
SYS_ROLE_RULE {
uint roleId PK,FK
uint ruleId PK,FK
}
SYS_ROLE ||--o{ SYS_ROLE_RULE : "包含"
SYS_AUTH_RULE ||--o{ SYS_ROLE_RULE : "被包含"
```

**图示来源**  
- [v_1_sys_auth_rule.go](file://internal/model/entity/v_1_sys_auth_rule.go#L11-L34)
- [sys_role.go](file://internal/model/entity/v_1_sys_role.go)
- [sys_auth_rule.go](file://internal/service/sys_auth_rule.go#L14-L34)

**本节来源**  
- [sys_auth_rule.go](file://internal/service/sys_auth_rule.go#L14-L34)
- [v_1_sys_casbin_rule.go](file://internal/model/entity/v_1_sys_casbin_rule.go)

### 关联管理接口

系统提供专门的接口用于管理角色与权限规则的绑定关系：

- `BindRoleRule`: 绑定角色与权限规则
- `UpdateRoleRule`: 更新角色权限规则
- `GetMenuRoles`: 获取规则关联的角色列表

这些接口确保权限分配的原子性和一致性，避免出现权限配置不一致的问题。

**本节来源**  
- [sys_auth_rule.go](file://internal/service/sys_auth_rule.go#L14-L34)
- [sys_auth_rule.go](file://internal/controller/sys_auth_rule/sys_auth_rule.go)

## 多层级权限继承机制

系统采用树形结构实现多层级权限继承，子节点自动继承父节点的权限配置。

```mermaid
classDiagram
class SysAuthRule {
+uint id
+uint pid
+string name
+string title
+uint menuType
+int weigh
+uint isHide
+string path
+string component
+Children []*SysAuthRule
}
class SysAuthRuleTreeRes {
+*SysAuthRuleInfoRes
+Children []*SysAuthRuleTreeRes
}
class RuleSearchInput {
+MenuCreateReq
}
SysAuthRule <|-- SysAuthRuleTreeRes
SysAuthRuleTreeRes "1" *-- "0..*" SysAuthRuleTreeRes : 包含
```

**图示来源**  
- [sys_auth_rule.go](file://internal/model/sys_auth_rule.go#L7-L10)
- [model.go](file://api/sys_auth_rule/v1/model.go#L20-L25)
- [model.go](file://api/sys_auth_rule/v1/model.go#L6-L17)

**本节来源**  
- [sys_auth_rule.go](file://internal/model/sys_auth_rule.go#L7-L10)
- [model.go](file://api/sys_auth_rule/v1/model.go#L20-L25)

### 继承实现逻辑

1. **树形结构构建**：通过 `GetMenuListTree` 方法递归构建完整的菜单树
2. **父子关系维护**：`FindSonByParentId` 方法用于查找指定父节点的所有子节点
3. **权限继承计算**：在权限校验时，自动包含父节点的所有权限规则

这种设计确保了权限配置的层次性和可维护性，简化了复杂系统的权限管理。

**本节来源**  
- [sys_auth_rule.go](file://internal/service/sys_auth_rule.go#L14-L34)
- [sys_auth_rule.go](file://internal/model/sys_auth_rule.go#L7-L10)

## 权限规则配置最佳实践

### 权限编码规范

权限编码应遵循统一的命名规范，便于管理和维护：

- **格式**：`模块:功能:操作`
- **示例**：`user:profile:read`、`order:management:create`
- **要求**：小写字母、数字、冒号和下划线，长度不超过50字符

### 权限分类

建议将权限规则按以下维度进行分类管理：

| 分类 | 说明 | 示例 |
|------|------|------|
| 功能权限 | 系统功能模块访问控制 | dashboard:view |
| 数据权限 | 数据范围访问控制 | order:data:own |
| 操作权限 | 具体操作行为控制 | user:create |
| 字段权限 | 字段级访问控制 | user:profile:email |

### 权限粒度控制

根据业务需求合理设置权限粒度：

1. **粗粒度**：适用于功能模块级别的控制
2. **细粒度**：适用于具体操作和数据范围的控制
3. **动态权限**：结合条件表达式实现动态权限判断

**本节来源**  
- [model.go](file://api/sys_auth_rule/v1/model.go#L6-L52)
- [sys_auth_rule.go](file://internal/service/sys_auth_rule.go#L14-L34)

## 权限规则冲突检测与解决策略

系统提供权限冲突检测机制，确保权限配置的一致性和有效性。

### 冲突检测规则

1. **编码冲突**：同一层级下权限编码必须唯一
2. **路径冲突**：路由路径不能重复
3. **循环引用**：禁止父子节点形成循环引用
4. **权限重叠**：避免相同功能的权限规则重复定义

### 解决策略

- **优先级机制**：明确权限规则的优先级顺序
- **继承覆盖**：子节点可以覆盖父节点的特定权限
- **显式声明**：通过明确的权限声明避免隐式冲突
- **审计日志**：记录权限变更历史，便于追溯和分析

**本节来源**  
- [sys_auth_rule.go](file://internal/service/sys_auth_rule.go#L14-L34)
- [v_1_sys_auth_rule.go](file://internal/model/entity/v_1_sys_auth_rule.go#L11-L34)

## 权限规则版本管理建议

为确保权限系统的稳定性和可追溯性，建议实施以下版本管理策略：

1. **变更记录**：详细记录每次权限规则的变更内容
2. **版本快照**：定期创建权限配置的版本快照
3. **灰度发布**：新权限配置先在测试环境验证
4. **回滚机制**：建立快速回滚通道应对配置错误
5. **审批流程**：重要权限变更需经过审批流程

通过完善的版本管理，可以有效降低权限配置风险，保障系统安全稳定运行。

**本节来源**  
- [v_1_sys_auth_rule.go](file://internal/model/entity/v_1_sys_auth_rule.go#L11-L34)
- [sys_auth_rule.go](file://internal/service/sys_auth_rule.go#L14-L34)