junhong_cmp_fiber/specs/004-rbac-data-permission/contracts

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）:

Authorization: Bearer <token>

统一响应格式

所有 API 响应使用统一的 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）

分页响应格式：

{
  "items": [ ... ],
  "total": 100,
  "page": 1,
  "page_size": 20
}

时间格式

所有时间字段使用 ISO 8601 格式（RFC3339）：

2025-11-18T15:30:00Z

HTTP 状态码

状态码	说明
200	请求成功
400	请求参数错误
401	未认证
403	无权限访问
404	资源不存在
500	服务器错误

错误响应示例

客户端错误（400）:

{
  "code": 1001,
  "message": "用户名已存在",
  "data": null,
  "timestamp": "2025-11-18T15:30:00Z"
}

服务器错误（500）:

{
  "code": 2001,
  "message": "服务器内部错误，请稍后重试",
  "data": null,
  "timestamp": "2025-11-18T15:30:00Z"
}

数据权限过滤

过滤机制

所有业务数据查询（账号、用户、订单等）自动应用数据权限过滤：

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 和服务端代码骨架：

# 安装 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 规范
• RESTful API 设计指南
• Fiber 框架文档
• GORM 文档