feat: 实现 RBAC 权限系统和数据权限控制 (004-rbac-data-permission)

主要功能:
- 实现完整的 RBAC 权限系统（账号、角色、权限的多对多关联）
- 基于 owner_id + shop_id 的自动数据权限过滤
- 使用 PostgreSQL WITH RECURSIVE 查询下级账号
- Redis 缓存优化下级账号查询性能（30分钟过期）
- 支持多租户数据隔离和层级权限管理

技术实现:
- 新增 Account、Role、Permission 模型及关联关系表
- 实现 GORM Scopes 自动应用数据权限过滤
- 添加数据库迁移脚本（000002_rbac_data_permission、000003_add_owner_id_shop_id）
- 完善错误码定义（1010-1027 为 RBAC 相关错误）
- 重构 main.go 采用函数拆分提高可读性

测试覆盖:
- 添加 Account、Role、Permission 的集成测试
- 添加数据权限过滤的单元测试和集成测试
- 添加下级账号查询和缓存的单元测试
- 添加 API 回归测试确保向后兼容

文档更新:
- 更新 README.md 添加 RBAC 功能说明
- 更新 CLAUDE.md 添加技术栈和开发原则
- 添加 docs/004-rbac-data-permission/ 功能总结和使用指南

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

specs/004-rbac-data-permission/contracts/README.md

@@ -0,0 +1,263 @@
+# API Contracts: RBAC 表结构与 GORM 数据权限过滤
+
+**Feature**: 004-rbac-data-permission
+**Date**: 2025-11-18
+**Format**: OpenAPI 3.0.3
+
+## 概述
+
+本目录包含 RBAC 权限系统的完整 API 接口规范，使用 OpenAPI 3.0.3 标准定义。所有 API 遵循 RESTful 设计原则，支持统一的认证、错误处理和响应格式。
+
+## 文件结构
+
+```
+contracts/
+├── README.md                 # 本文件
+├── account-api.yaml          # 账号管理接口
+├── role-api.yaml             # 角色管理接口
+└── permission-api.yaml       # 权限管理接口
+```
+
+## API 模块
+
+### 1. Account Management API (`account-api.yaml`)
+
+**基础路径**: `/api/v1/accounts`
+
+**核心功能**:
+- 账号 CRUD：创建、查询、更新、删除账号
+- 账号-角色关联：为账号分配角色、查询账号的角色、移除角色
+
+**关键端点**:
+- `POST /accounts` - 创建账号（非 root 必须提供 parent_id）
+- `GET /accounts` - 查询账号列表（自动应用数据权限过滤）
+- `GET /accounts/{id}` - 查询账号详情
+- `PUT /accounts/{id}` - 更新账号（禁止修改 parent_id 和 user_type）
+- `DELETE /accounts/{id}` - 软删除账号
+- `POST /accounts/{id}/roles` - 为账号分配角色
+- `GET /accounts/{id}/roles` - 查询账号的所有角色
+- `DELETE /accounts/{account_id}/roles/{role_id}` - 移除账号的角色
+
+**数据权限过滤**:
+- 查询账号列表和详情时，自动应用 `WHERE owner_id IN (当前用户及所有下级的ID列表) AND shop_id = 当前用户的shop_id`
+- root 用户（user_type=1）跳过数据权限过滤
+
+**业务规则**:
+- username 和 phone 必须唯一（软删除后可重用）
+- 密码使用 bcrypt 哈希（建议替代 MD5）
+- parent_id 创建后不可修改
+- 账号类型：1=root, 2=平台, 3=代理, 4=企业
+
+### 2. Role Management API (`role-api.yaml`)
+
+**基础路径**: `/api/v1/roles`
+
+**核心功能**:
+- 角色 CRUD：创建、查询、更新、删除角色
+- 角色-权限关联：为角色分配权限、查询角色的权限、移除权限
+
+**关键端点**:
+- `POST /roles` - 创建角色
+- `GET /roles` - 查询角色列表（支持按类型和状态过滤）
+- `GET /roles/{id}` - 查询角色详情
+- `PUT /roles/{id}` - 更新角色
+- `DELETE /roles/{id}` - 软删除角色
+- `POST /roles/{id}/permissions` - 为角色分配权限
+- `GET /roles/{id}/permissions` - 查询角色的所有权限
+- `DELETE /roles/{role_id}/permissions/{perm_id}` - 移除角色的权限
+
+**角色类型**:
+- 1=超级角色
+- 2=代理角色
+- 3=企业角色
+
+### 3. Permission Management API (`permission-api.yaml`)
+
+**基础路径**: `/api/v1/permissions`
+
+**核心功能**:
+- 权限 CRUD：创建、查询、更新、删除权限
+- 层级支持：支持权限的层级关系（parent_id）
+- 树形查询：查询完整的权限树结构
+
+**关键端点**:
+- `POST /permissions` - 创建权限（支持层级关系）
+- `GET /permissions` - 查询权限列表（支持按类型、父权限、状态过滤）
+- `GET /permissions/{id}` - 查询权限详情
+- `PUT /permissions/{id}` - 更新权限
+- `DELETE /permissions/{id}` - 软删除权限
+- `GET /permissions/tree` - 查询权限树（完整层级结构）
+
+**权限类型**:
+- 1=菜单权限
+- 2=按钮权限
+
+**权限编码规范**:
+- 格式：`module:action`（如 `user:create`、`order:delete`）
+- 必须唯一
+- 使用小写字母和冒号
+
+## 统一规范
+
+### 认证方式
+
+所有 API 使用 **Bearer Token** 认证（JWT）:
+
+```http
+Authorization: Bearer <token>
+```
+
+### 统一响应格式
+
+所有 API 响应使用统一的 JSON 格式：
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": { ... },
+  "timestamp": "2025-11-18T15:30:00Z"
+}
+```
+
+**字段说明**:
+- `code`: 错误码（0 表示成功，1xxx 表示客户端错误，2xxx 表示服务端错误）
+- `message`: 响应消息（中英文双语）
+- `data`: 响应数据（具体内容根据接口而定）
+- `timestamp`: 响应时间戳（ISO 8601 格式）
+
+### 分页参数
+
+所有列表查询接口统一使用以下分页参数：
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| page | integer | 1 | 页码（从 1 开始） |
+| page_size | integer | 20 | 每页大小（最大 100） |
+
+分页响应格式：
+
+```json
+{
+  "items": [ ... ],
+  "total": 100,
+  "page": 1,
+  "page_size": 20
+}
+```
+
+### 时间格式
+
+所有时间字段使用 **ISO 8601 格式**（RFC3339）：
+
+```
+2025-11-18T15:30:00Z
+```
+
+### HTTP 状态码
+
+| 状态码 | 说明 |
+|--------|------|
+| 200 | 请求成功 |
+| 400 | 请求参数错误 |
+| 401 | 未认证 |
+| 403 | 无权限访问 |
+| 404 | 资源不存在 |
+| 500 | 服务器错误 |
+
+### 错误响应示例
+
+**客户端错误（400）**:
+
+```json
+{
+  "code": 1001,
+  "message": "用户名已存在",
+  "data": null,
+  "timestamp": "2025-11-18T15:30:00Z"
+}
+```
+
+**服务器错误（500）**:
+
+```json
+{
+  "code": 2001,
+  "message": "服务器内部错误，请稍后重试",
+  "data": null,
+  "timestamp": "2025-11-18T15:30:00Z"
+}
+```
+
+## 数据权限过滤
+
+### 过滤机制
+
+所有业务数据查询（账号、用户、订单等）自动应用数据权限过滤：
+
+```sql
+WHERE owner_id IN (当前用户及所有下级的ID列表) AND shop_id = 当前用户的shop_id
+```
+
+### 特殊情况
+
+1. **root 用户（user_type=1）**: 跳过数据权限过滤，返回所有数据
+2. **C 端业务用户**: 使用 `WithoutDataFilter` 选项，改为基于业务字段（如 iccid/device_id）过滤
+3. **系统任务**: Context 中无用户信息时，不应用过滤
+
+### 缓存策略
+
+用户的所有下级 ID 列表缓存到 Redis：
+
+- **Key**: `account:subordinates:{账号ID}`
+- **Value**: 下级 ID 列表（JSON 数组）
+- **过期时间**: 30 分钟
+- **清除时机**: 账号创建、删除时主动清除相关缓存
+
+## 使用工具
+
+### 在线查看
+
+可以使用以下工具在线查看和测试 API：
+
+- **Swagger Editor**: https://editor.swagger.io/
+- **Swagger UI**: https://petstore.swagger.io/
+- **Postman**: 导入 OpenAPI 文件自动生成 API 集合
+
+### 代码生成
+
+使用 OpenAPI Generator 可以生成客户端 SDK 和服务端代码骨架：
+
+```bash
+# 安装 OpenAPI Generator
+npm install -g @openapitools/openapi-generator-cli
+
+# 生成 Go 服务端代码（Fiber）
+openapi-generator-cli generate -i account-api.yaml -g go-server -o ./generated/account
+
+# 生成 TypeScript 客户端代码
+openapi-generator-cli generate -i account-api.yaml -g typescript-axios -o ./generated/client
+```
+
+## 下一步
+
+1. **实现 Handler 层**: 根据 API 规范实现 Fiber Handler
+2. **实现 Service 层**: 实现业务逻辑和数据权限过滤
+3. **实现 Store 层**: 实现数据库访问和 GORM Scopes
+4. **集成测试**: 编写 API 集成测试，验证接口行为
+5. **文档部署**: 部署 Swagger UI 提供在线 API 文档
+
+## 注意事项
+
+1. **密码字段安全**: 账号的 `password` 字段在查询时不返回（使用 GORM 标签 `json:"-"`）
+2. **软删除支持**: 所有表支持软删除，删除操作只设置 `deleted_at` 字段
+3. **唯一性约束**: username、phone、perm_code 使用软删除感知的唯一索引（`WHERE deleted_at IS NULL`）
+4. **关联表**: account_roles 和 role_permissions 使用联合唯一索引防止重复分配
+5. **层级关系**: parent_id 创建后不可修改，权限支持多层级（parent_id）
+
+## 参考资料
+
+- [OpenAPI 3.0.3 规范](https://spec.openapis.org/oas/v3.0.3)
+- [RESTful API 设计指南](https://restfulapi.net/)
+- [Fiber 框架文档](https://docs.gofiber.io/)
+- [GORM 文档](https://gorm.io/docs/)

specs/004-rbac-data-permission/contracts/account-api.yaml

@@ -0,0 +1,616 @@
+openapi: 3.0.3
+info:
+  title: Account Management API
+  description: RBAC 账号管理接口 - 支持账号的创建、查询、更新、删除和角色分配
+  version: 1.0.0
+
+servers:
+  - url: http://localhost:8080/api/v1
+    description: Development server
+
+tags:
+  - name: accounts
+    description: 账号管理
+  - name: account-roles
+    description: 账号-角色关联
+
+paths:
+  /accounts:
+    post:
+      summary: 创建账号
+      description: 创建新账号，非 root 账号必须提供 parent_id，密码使用 bcrypt 哈希
+      tags:
+        - accounts
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateAccountRequest'
+      responses:
+        '200':
+          description: 创建成功
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/ApiResponse'
+                  - type: object
+                    properties:
+                      data:
+                        $ref: '#/components/schemas/AccountResponse'
+        '400':
+          description: 请求参数错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+        '500':
+          description: 服务器错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+
+    get:
+      summary: 查询账号列表
+      description: 分页查询账号列表，自动应用数据权限过滤（只返回自己和下级创建的账号）
+      tags:
+        - accounts
+      parameters:
+        - name: page
+          in: query
+          description: 页码（从 1 开始）
+          schema:
+            type: integer
+            default: 1
+            minimum: 1
+        - name: page_size
+          in: query
+          description: 每页大小
+          schema:
+            type: integer
+            default: 20
+            minimum: 1
+            maximum: 100
+        - name: username
+          in: query
+          description: 用户名模糊查询
+          schema:
+            type: string
+        - name: user_type
+          in: query
+          description: 用户类型过滤（1=root, 2=平台, 3=代理, 4=企业）
+          schema:
+            type: integer
+            enum: [1, 2, 3, 4]
+        - name: status
+          in: query
+          description: 状态过滤（0=禁用, 1=启用）
+          schema:
+            type: integer
+            enum: [0, 1]
+      responses:
+        '200':
+          description: 查询成功
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/ApiResponse'
+                  - type: object
+                    properties:
+                      data:
+                        $ref: '#/components/schemas/ListAccountsResponse'
+        '400':
+          description: 请求参数错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+        '500':
+          description: 服务器错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+
+  /accounts/{id}:
+    get:
+      summary: 查询账号详情
+      description: 根据 ID 查询账号详情，自动应用数据权限过滤
+      tags:
+        - accounts
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: 账号 ID
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: 查询成功
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/ApiResponse'
+                  - type: object
+                    properties:
+                      data:
+                        $ref: '#/components/schemas/AccountResponse'
+        '404':
+          description: 账号不存在或无权访问
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+        '500':
+          description: 服务器错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+
+    put:
+      summary: 更新账号
+      description: 更新账号信息，禁止修改 parent_id 和 user_type
+      tags:
+        - accounts
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: 账号 ID
+          schema:
+            type: integer
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateAccountRequest'
+      responses:
+        '200':
+          description: 更新成功
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/ApiResponse'
+                  - type: object
+                    properties:
+                      data:
+                        $ref: '#/components/schemas/AccountResponse'
+        '400':
+          description: 请求参数错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+        '404':
+          description: 账号不存在或无权访问
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+        '500':
+          description: 服务器错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+
+    delete:
+      summary: 删除账号
+      description: 软删除账号，设置 deleted_at 字段，并清除该账号及所有上级的下级 ID 缓存
+      tags:
+        - accounts
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: 账号 ID
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: 删除成功
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+        '404':
+          description: 账号不存在或无权访问
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+        '500':
+          description: 服务器错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+
+  /accounts/{id}/roles:
+    post:
+      summary: 为账号分配角色
+      description: 批量为账号分配角色，已存在的关联会被忽略
+      tags:
+        - account-roles
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: 账号 ID
+          schema:
+            type: integer
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignRolesToAccountRequest'
+      responses:
+        '200':
+          description: 分配成功
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/ApiResponse'
+                  - type: object
+                    properties:
+                      data:
+                        type: array
+                        items:
+                          $ref: '#/components/schemas/AccountRoleResponse'
+        '400':
+          description: 请求参数错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+        '404':
+          description: 账号或角色不存在
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+        '500':
+          description: 服务器错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+
+    get:
+      summary: 查询账号的所有角色
+      description: 查询指定账号已分配的所有角色
+      tags:
+        - account-roles
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: 账号 ID
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: 查询成功
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/ApiResponse'
+                  - type: object
+                    properties:
+                      data:
+                        type: array
+                        items:
+                          $ref: '#/components/schemas/RoleResponse'
+        '404':
+          description: 账号不存在或无权访问
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+        '500':
+          description: 服务器错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+
+  /accounts/{account_id}/roles/{role_id}:
+    delete:
+      summary: 移除账号的角色
+      description: 软删除账号-角色关联
+      tags:
+        - account-roles
+      parameters:
+        - name: account_id
+          in: path
+          required: true
+          description: 账号 ID
+          schema:
+            type: integer
+        - name: role_id
+          in: path
+          required: true
+          description: 角色 ID
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: 移除成功
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+        '404':
+          description: 账号或角色不存在
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+        '500':
+          description: 服务器错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+
+components:
+  schemas:
+    ApiResponse:
+      type: object
+      required:
+        - code
+        - message
+        - timestamp
+      properties:
+        code:
+          type: integer
+          description: 错误码（0 表示成功，1xxx 表示客户端错误，2xxx 表示服务端错误）
+          example: 0
+        message:
+          type: string
+          description: 响应消息
+          example: success
+        data:
+          type: object
+          description: 响应数据
+        timestamp:
+          type: string
+          format: date-time
+          description: 响应时间戳（ISO 8601 格式）
+          example: "2025-11-18T15:30:00Z"
+
+    CreateAccountRequest:
+      type: object
+      required:
+        - username
+        - phone
+        - password
+        - user_type
+      properties:
+        username:
+          type: string
+          minLength: 3
+          maxLength: 20
+          pattern: '^[a-zA-Z0-9_]+$'
+          description: 用户名（3-20 个字符，字母、数字、下划线）
+          example: admin001
+        phone:
+          type: string
+          pattern: '^1[3-9]\d{9}$'
+          description: 手机号（11 位中国大陆手机号）
+          example: "13812345678"
+        password:
+          type: string
+          minLength: 8
+          description: 密码（最少 8 位，包含字母和数字）
+          example: "Password123"
+        user_type:
+          type: integer
+          enum: [1, 2, 3, 4]
+          description: 用户类型（1=root, 2=平台, 3=代理, 4=企业）
+          example: 2
+        shop_id:
+          type: integer
+          nullable: true
+          description: 所属店铺 ID（可选）
+          example: 10
+        parent_id:
+          type: integer
+          nullable: true
+          description: 上级账号 ID（非 root 用户必须提供）
+          example: 1
+        status:
+          type: integer
+          enum: [0, 1]
+          default: 1
+          description: 状态（0=禁用, 1=启用）
+          example: 1
+
+    UpdateAccountRequest:
+      type: object
+      properties:
+        username:
+          type: string
+          minLength: 3
+          maxLength: 20
+          pattern: '^[a-zA-Z0-9_]+$'
+          description: 用户名（可选更新）
+          example: admin002
+        phone:
+          type: string
+          pattern: '^1[3-9]\d{9}$'
+          description: 手机号（可选更新）
+          example: "13812345679"
+        password:
+          type: string
+          minLength: 8
+          description: 密码（可选更新）
+          example: "NewPassword123"
+        status:
+          type: integer
+          enum: [0, 1]
+          description: 状态（可选更新）
+          example: 0
+
+    AccountResponse:
+      type: object
+      properties:
+        id:
+          type: integer
+          description: 账号 ID
+          example: 1
+        username:
+          type: string
+          description: 用户名
+          example: admin001
+        phone:
+          type: string
+          description: 手机号
+          example: "13812345678"
+        user_type:
+          type: integer
+          description: 用户类型（1=root, 2=平台, 3=代理, 4=企业）
+          example: 2
+        shop_id:
+          type: integer
+          nullable: true
+          description: 所属店铺 ID
+          example: 10
+        parent_id:
+          type: integer
+          nullable: true
+          description: 上级账号 ID
+          example: 1
+        status:
+          type: integer
+          description: 状态（0=禁用, 1=启用）
+          example: 1
+        creator:
+          type: integer
+          description: 创建人 ID
+          example: 1
+        updater:
+          type: integer
+          description: 更新人 ID
+          example: 1
+        created_at:
+          type: string
+          format: date-time
+          description: 创建时间
+          example: "2025-11-18T10:00:00Z"
+        updated_at:
+          type: string
+          format: date-time
+          description: 更新时间
+          example: "2025-11-18T10:00:00Z"
+
+    ListAccountsResponse:
+      type: object
+      properties:
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/AccountResponse'
+        total:
+          type: integer
+          description: 总记录数
+          example: 100
+        page:
+          type: integer
+          description: 当前页码
+          example: 1
+        page_size:
+          type: integer
+          description: 每页大小
+          example: 20
+
+    AssignRolesToAccountRequest:
+      type: object
+      required:
+        - role_ids
+      properties:
+        role_ids:
+          type: array
+          items:
+            type: integer
+          minItems: 1
+          description: 角色 ID 列表
+          example: [1, 2, 3]
+
+    AccountRoleResponse:
+      type: object
+      properties:
+        id:
+          type: integer
+          description: 关联 ID
+          example: 1
+        account_id:
+          type: integer
+          description: 账号 ID
+          example: 1
+        role_id:
+          type: integer
+          description: 角色 ID
+          example: 1
+        status:
+          type: integer
+          description: 状态（0=禁用, 1=启用）
+          example: 1
+        creator:
+          type: integer
+          description: 创建人 ID
+          example: 1
+        created_at:
+          type: string
+          format: date-time
+          description: 创建时间
+          example: "2025-11-18T10:00:00Z"
+
+    RoleResponse:
+      type: object
+      properties:
+        id:
+          type: integer
+          description: 角色 ID
+          example: 1
+        role_name:
+          type: string
+          description: 角色名称
+          example: 平台管理员
+        role_desc:
+          type: string
+          description: 角色描述
+          example: 平台系统管理员角色
+        role_type:
+          type: integer
+          description: 角色类型（1=超级, 2=代理, 3=企业）
+          example: 1
+        status:
+          type: integer
+          description: 状态（0=禁用, 1=启用）
+          example: 1
+        created_at:
+          type: string
+          format: date-time
+          description: 创建时间
+          example: "2025-11-18T10:00:00Z"
+
+  securitySchemes:
+    BearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+
+security:
+  - BearerAuth: []

specs/004-rbac-data-permission/contracts/permission-api.yaml

@@ -0,0 +1,482 @@
+openapi: 3.0.3
+info:
+  title: Permission Management API
+  description: RBAC 权限管理接口 - 支持权限的创建、查询、更新、删除，支持层级关系
+  version: 1.0.0
+
+servers:
+  - url: http://localhost:8080/api/v1
+    description: Development server
+
+tags:
+  - name: permissions
+    description: 权限管理
+
+paths:
+  /permissions:
+    post:
+      summary: 创建权限
+      description: 创建新权限，支持层级关系（通过 parent_id）
+      tags:
+        - permissions
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreatePermissionRequest'
+      responses:
+        '200':
+          description: 创建成功
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/ApiResponse'
+                  - type: object
+                    properties:
+                      data:
+                        $ref: '#/components/schemas/PermissionResponse'
+        '400':
+          description: 请求参数错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+        '500':
+          description: 服务器错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+
+    get:
+      summary: 查询权限列表
+      description: 分页查询权限列表，支持按类型和父权限过滤
+      tags:
+        - permissions
+      parameters:
+        - name: page
+          in: query
+          description: 页码（从 1 开始）
+          schema:
+            type: integer
+            default: 1
+            minimum: 1
+        - name: page_size
+          in: query
+          description: 每页大小
+          schema:
+            type: integer
+            default: 20
+            minimum: 1
+            maximum: 100
+        - name: perm_type
+          in: query
+          description: 权限类型过滤（1=菜单, 2=按钮）
+          schema:
+            type: integer
+            enum: [1, 2]
+        - name: parent_id
+          in: query
+          description: 父权限 ID 过滤（查询指定权限的子权限）
+          schema:
+            type: integer
+        - name: status
+          in: query
+          description: 状态过滤（0=禁用, 1=启用）
+          schema:
+            type: integer
+            enum: [0, 1]
+      responses:
+        '200':
+          description: 查询成功
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/ApiResponse'
+                  - type: object
+                    properties:
+                      data:
+                        $ref: '#/components/schemas/ListPermissionsResponse'
+        '400':
+          description: 请求参数错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+        '500':
+          description: 服务器错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+
+  /permissions/{id}:
+    get:
+      summary: 查询权限详情
+      description: 根据 ID 查询权限详情
+      tags:
+        - permissions
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: 权限 ID
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: 查询成功
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/ApiResponse'
+                  - type: object
+                    properties:
+                      data:
+                        $ref: '#/components/schemas/PermissionResponse'
+        '404':
+          description: 权限不存在
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+        '500':
+          description: 服务器错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+
+    put:
+      summary: 更新权限
+      description: 更新权限信息
+      tags:
+        - permissions
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: 权限 ID
+          schema:
+            type: integer
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdatePermissionRequest'
+      responses:
+        '200':
+          description: 更新成功
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/ApiResponse'
+                  - type: object
+                    properties:
+                      data:
+                        $ref: '#/components/schemas/PermissionResponse'
+        '400':
+          description: 请求参数错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+        '404':
+          description: 权限不存在
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+        '500':
+          description: 服务器错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+
+    delete:
+      summary: 删除权限
+      description: 软删除权限，设置 deleted_at 字段
+      tags:
+        - permissions
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: 权限 ID
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: 删除成功
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+        '404':
+          description: 权限不存在
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+        '500':
+          description: 服务器错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+
+  /permissions/tree:
+    get:
+      summary: 查询权限树
+      description: 查询完整的权限层级树结构（菜单和按钮的层级关系）
+      tags:
+        - permissions
+      responses:
+        '200':
+          description: 查询成功
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/ApiResponse'
+                  - type: object
+                    properties:
+                      data:
+                        type: array
+                        items:
+                          $ref: '#/components/schemas/PermissionTreeNode'
+        '500':
+          description: 服务器错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+
+components:
+  schemas:
+    ApiResponse:
+      type: object
+      required:
+        - code
+        - message
+        - timestamp
+      properties:
+        code:
+          type: integer
+          description: 错误码（0 表示成功，1xxx 表示客户端错误，2xxx 表示服务端错误）
+          example: 0
+        message:
+          type: string
+          description: 响应消息
+          example: success
+        data:
+          type: object
+          description: 响应数据
+        timestamp:
+          type: string
+          format: date-time
+          description: 响应时间戳（ISO 8601 格式）
+          example: "2025-11-18T15:30:00Z"
+
+    CreatePermissionRequest:
+      type: object
+      required:
+        - perm_name
+        - perm_code
+        - perm_type
+      properties:
+        perm_name:
+          type: string
+          maxLength: 50
+          description: 权限名称
+          example: 用户管理
+        perm_code:
+          type: string
+          maxLength: 100
+          pattern: '^[a-z]+:[a-z]+$'
+          description: 权限编码（格式：module:action，如 user:create）
+          example: user:create
+        perm_type:
+          type: integer
+          enum: [1, 2]
+          description: 权限类型（1=菜单, 2=按钮）
+          example: 1
+        url:
+          type: string
+          maxLength: 255
+          description: URL 路径（菜单权限必填，按钮权限可选）
+          example: /admin/users
+        parent_id:
+          type: integer
+          nullable: true
+          description: 上级权限 ID（顶级权限为 null）
+          example: null
+        sort:
+          type: integer
+          default: 0
+          description: 排序序号（数字越小越靠前）
+          example: 1
+        status:
+          type: integer
+          enum: [0, 1]
+          default: 1
+          description: 状态（0=禁用, 1=启用）
+          example: 1
+
+    UpdatePermissionRequest:
+      type: object
+      properties:
+        perm_name:
+          type: string
+          maxLength: 50
+          description: 权限名称（可选更新）
+          example: 用户管理模块
+        perm_code:
+          type: string
+          maxLength: 100
+          pattern: '^[a-z]+:[a-z]+$'
+          description: 权限编码（可选更新）
+          example: user:manage
+        url:
+          type: string
+          maxLength: 255
+          description: URL 路径（可选更新）
+          example: /admin/users/manage
+        sort:
+          type: integer
+          description: 排序序号（可选更新）
+          example: 2
+        status:
+          type: integer
+          enum: [0, 1]
+          description: 状态（可选更新）
+          example: 0
+
+    PermissionResponse:
+      type: object
+      properties:
+        id:
+          type: integer
+          description: 权限 ID
+          example: 1
+        perm_name:
+          type: string
+          description: 权限名称
+          example: 用户管理
+        perm_code:
+          type: string
+          description: 权限编码
+          example: user:create
+        perm_type:
+          type: integer
+          description: 权限类型（1=菜单, 2=按钮）
+          example: 1
+        url:
+          type: string
+          description: URL 路径
+          example: /admin/users
+        parent_id:
+          type: integer
+          nullable: true
+          description: 上级权限 ID
+          example: null
+        sort:
+          type: integer
+          description: 排序序号
+          example: 1
+        status:
+          type: integer
+          description: 状态（0=禁用, 1=启用）
+          example: 1
+        creator:
+          type: integer
+          description: 创建人 ID
+          example: 1
+        updater:
+          type: integer
+          description: 更新人 ID
+          example: 1
+        created_at:
+          type: string
+          format: date-time
+          description: 创建时间
+          example: "2025-11-18T10:00:00Z"
+        updated_at:
+          type: string
+          format: date-time
+          description: 更新时间
+          example: "2025-11-18T10:00:00Z"
+
+    ListPermissionsResponse:
+      type: object
+      properties:
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/PermissionResponse'
+        total:
+          type: integer
+          description: 总记录数
+          example: 80
+        page:
+          type: integer
+          description: 当前页码
+          example: 1
+        page_size:
+          type: integer
+          description: 每页大小
+          example: 20
+
+    PermissionTreeNode:
+      type: object
+      description: 权限树节点（包含子权限）
+      properties:
+        id:
+          type: integer
+          description: 权限 ID
+          example: 1
+        perm_name:
+          type: string
+          description: 权限名称
+          example: 系统管理
+        perm_code:
+          type: string
+          description: 权限编码
+          example: system:manage
+        perm_type:
+          type: integer
+          description: 权限类型（1=菜单, 2=按钮）
+          example: 1
+        url:
+          type: string
+          description: URL 路径
+          example: /admin/system
+        sort:
+          type: integer
+          description: 排序序号
+          example: 1
+        status:
+          type: integer
+          description: 状态（0=禁用, 1=启用）
+          example: 1
+        children:
+          type: array
+          description: 子权限列表
+          items:
+            $ref: '#/components/schemas/PermissionTreeNode'
+
+  securitySchemes:
+    BearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+
+security:
+  - BearerAuth: []

specs/004-rbac-data-permission/contracts/role-api.yaml

@@ -0,0 +1,588 @@
+openapi: 3.0.3
+info:
+  title: Role Management API
+  description: RBAC 角色管理接口 - 支持角色的创建、查询、更新、删除和权限分配
+  version: 1.0.0
+
+servers:
+  - url: http://localhost:8080/api/v1
+    description: Development server
+
+tags:
+  - name: roles
+    description: 角色管理
+  - name: role-permissions
+    description: 角色-权限关联
+
+paths:
+  /roles:
+    post:
+      summary: 创建角色
+      description: 创建新角色
+      tags:
+        - roles
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateRoleRequest'
+      responses:
+        '200':
+          description: 创建成功
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/ApiResponse'
+                  - type: object
+                    properties:
+                      data:
+                        $ref: '#/components/schemas/RoleResponse'
+        '400':
+          description: 请求参数错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+        '500':
+          description: 服务器错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+
+    get:
+      summary: 查询角色列表
+      description: 分页查询角色列表
+      tags:
+        - roles
+      parameters:
+        - name: page
+          in: query
+          description: 页码（从 1 开始）
+          schema:
+            type: integer
+            default: 1
+            minimum: 1
+        - name: page_size
+          in: query
+          description: 每页大小
+          schema:
+            type: integer
+            default: 20
+            minimum: 1
+            maximum: 100
+        - name: role_type
+          in: query
+          description: 角色类型过滤（1=超级, 2=代理, 3=企业）
+          schema:
+            type: integer
+            enum: [1, 2, 3]
+        - name: status
+          in: query
+          description: 状态过滤（0=禁用, 1=启用）
+          schema:
+            type: integer
+            enum: [0, 1]
+      responses:
+        '200':
+          description: 查询成功
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/ApiResponse'
+                  - type: object
+                    properties:
+                      data:
+                        $ref: '#/components/schemas/ListRolesResponse'
+        '400':
+          description: 请求参数错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+        '500':
+          description: 服务器错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+
+  /roles/{id}:
+    get:
+      summary: 查询角色详情
+      description: 根据 ID 查询角色详情
+      tags:
+        - roles
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: 角色 ID
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: 查询成功
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/ApiResponse'
+                  - type: object
+                    properties:
+                      data:
+                        $ref: '#/components/schemas/RoleResponse'
+        '404':
+          description: 角色不存在
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+        '500':
+          description: 服务器错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+
+    put:
+      summary: 更新角色
+      description: 更新角色信息
+      tags:
+        - roles
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: 角色 ID
+          schema:
+            type: integer
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateRoleRequest'
+      responses:
+        '200':
+          description: 更新成功
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/ApiResponse'
+                  - type: object
+                    properties:
+                      data:
+                        $ref: '#/components/schemas/RoleResponse'
+        '400':
+          description: 请求参数错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+        '404':
+          description: 角色不存在
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+        '500':
+          description: 服务器错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+
+    delete:
+      summary: 删除角色
+      description: 软删除角色，设置 deleted_at 字段
+      tags:
+        - roles
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: 角色 ID
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: 删除成功
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+        '404':
+          description: 角色不存在
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+        '500':
+          description: 服务器错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+
+  /roles/{id}/permissions:
+    post:
+      summary: 为角色分配权限
+      description: 批量为角色分配权限，已存在的关联会被忽略
+      tags:
+        - role-permissions
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: 角色 ID
+          schema:
+            type: integer
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignPermsToRoleRequest'
+      responses:
+        '200':
+          description: 分配成功
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/ApiResponse'
+                  - type: object
+                    properties:
+                      data:
+                        type: array
+                        items:
+                          $ref: '#/components/schemas/RolePermissionResponse'
+        '400':
+          description: 请求参数错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+        '404':
+          description: 角色或权限不存在
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+        '500':
+          description: 服务器错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+
+    get:
+      summary: 查询角色的所有权限
+      description: 查询指定角色已分配的所有权限
+      tags:
+        - role-permissions
+      parameters:
+        - name: id
+          in: path
+          required: true
+          description: 角色 ID
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: 查询成功
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/ApiResponse'
+                  - type: object
+                    properties:
+                      data:
+                        type: array
+                        items:
+                          $ref: '#/components/schemas/PermissionResponse'
+        '404':
+          description: 角色不存在
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+        '500':
+          description: 服务器错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+
+  /roles/{role_id}/permissions/{perm_id}:
+    delete:
+      summary: 移除角色的权限
+      description: 软删除角色-权限关联
+      tags:
+        - role-permissions
+      parameters:
+        - name: role_id
+          in: path
+          required: true
+          description: 角色 ID
+          schema:
+            type: integer
+        - name: perm_id
+          in: path
+          required: true
+          description: 权限 ID
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: 移除成功
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+        '404':
+          description: 角色或权限不存在
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+        '500':
+          description: 服务器错误
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiResponse'
+
+components:
+  schemas:
+    ApiResponse:
+      type: object
+      required:
+        - code
+        - message
+        - timestamp
+      properties:
+        code:
+          type: integer
+          description: 错误码（0 表示成功，1xxx 表示客户端错误，2xxx 表示服务端错误）
+          example: 0
+        message:
+          type: string
+          description: 响应消息
+          example: success
+        data:
+          type: object
+          description: 响应数据
+        timestamp:
+          type: string
+          format: date-time
+          description: 响应时间戳（ISO 8601 格式）
+          example: "2025-11-18T15:30:00Z"
+
+    CreateRoleRequest:
+      type: object
+      required:
+        - role_name
+        - role_type
+      properties:
+        role_name:
+          type: string
+          maxLength: 50
+          description: 角色名称
+          example: 平台管理员
+        role_desc:
+          type: string
+          maxLength: 255
+          description: 角色描述
+          example: 平台系统管理员角色
+        role_type:
+          type: integer
+          enum: [1, 2, 3]
+          description: 角色类型（1=超级, 2=代理, 3=企业）
+          example: 1
+        status:
+          type: integer
+          enum: [0, 1]
+          default: 1
+          description: 状态（0=禁用, 1=启用）
+          example: 1
+
+    UpdateRoleRequest:
+      type: object
+      properties:
+        role_name:
+          type: string
+          maxLength: 50
+          description: 角色名称（可选更新）
+          example: 平台超级管理员
+        role_desc:
+          type: string
+          maxLength: 255
+          description: 角色描述（可选更新）
+          example: 平台系统超级管理员角色
+        status:
+          type: integer
+          enum: [0, 1]
+          description: 状态（可选更新）
+          example: 0
+
+    RoleResponse:
+      type: object
+      properties:
+        id:
+          type: integer
+          description: 角色 ID
+          example: 1
+        role_name:
+          type: string
+          description: 角色名称
+          example: 平台管理员
+        role_desc:
+          type: string
+          description: 角色描述
+          example: 平台系统管理员角色
+        role_type:
+          type: integer
+          description: 角色类型（1=超级, 2=代理, 3=企业）
+          example: 1
+        status:
+          type: integer
+          description: 状态（0=禁用, 1=启用）
+          example: 1
+        creator:
+          type: integer
+          description: 创建人 ID
+          example: 1
+        updater:
+          type: integer
+          description: 更新人 ID
+          example: 1
+        created_at:
+          type: string
+          format: date-time
+          description: 创建时间
+          example: "2025-11-18T10:00:00Z"
+        updated_at:
+          type: string
+          format: date-time
+          description: 更新时间
+          example: "2025-11-18T10:00:00Z"
+
+    ListRolesResponse:
+      type: object
+      properties:
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/RoleResponse'
+        total:
+          type: integer
+          description: 总记录数
+          example: 50
+        page:
+          type: integer
+          description: 当前页码
+          example: 1
+        page_size:
+          type: integer
+          description: 每页大小
+          example: 20
+
+    AssignPermsToRoleRequest:
+      type: object
+      required:
+        - perm_ids
+      properties:
+        perm_ids:
+          type: array
+          items:
+            type: integer
+          minItems: 1
+          description: 权限 ID 列表
+          example: [1, 2, 3, 4, 5]
+
+    RolePermissionResponse:
+      type: object
+      properties:
+        id:
+          type: integer
+          description: 关联 ID
+          example: 1
+        role_id:
+          type: integer
+          description: 角色 ID
+          example: 1
+        perm_id:
+          type: integer
+          description: 权限 ID
+          example: 1
+        status:
+          type: integer
+          description: 状态（0=禁用, 1=启用）
+          example: 1
+        creator:
+          type: integer
+          description: 创建人 ID
+          example: 1
+        created_at:
+          type: string
+          format: date-time
+          description: 创建时间
+          example: "2025-11-18T10:00:00Z"
+
+    PermissionResponse:
+      type: object
+      properties:
+        id:
+          type: integer
+          description: 权限 ID
+          example: 1
+        perm_name:
+          type: string
+          description: 权限名称
+          example: 用户管理
+        perm_code:
+          type: string
+          description: 权限编码
+          example: user:create
+        perm_type:
+          type: integer
+          description: 权限类型（1=菜单, 2=按钮）
+          example: 1
+        url:
+          type: string
+          description: URL 路径
+          example: /admin/users
+        parent_id:
+          type: integer
+          nullable: true
+          description: 上级权限 ID
+          example: null
+        sort:
+          type: integer
+          description: 排序序号
+          example: 1
+        status:
+          type: integer
+          description: 状态（0=禁用, 1=启用）
+          example: 1
+        created_at:
+          type: string
+          format: date-time
+          description: 创建时间
+          example: "2025-11-18T10:00:00Z"
+
+  securitySchemes:
+    BearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+
+security:
+  - BearerAuth: []