lijiaoqiao/reports/review/multi_role_permission_design_review_2026-04-02.md

多角色权限设计评审报告

• 评审文档：docs/multi_role_permission_design_v1_2026-04-02.md
• 评审日期：2026-04-02
• 评审人：系统评审
• 参考基线：
  • PRD v1 (docs/llm_gateway_prd_v1_2026-03-25.md)
  • TOK-001/TOK-002 (docs/token_auth_middleware_design_v1_2026-03-29.md)
  • 数据库域模型 (docs/database_domain_model_and_governance_v1_2026-03-27.md)
  • API命名策略 (docs/api_naming_strategy_supply_vs_supplier_v1_2026-03-27.md)

---

评审结论

状态：GO

设计文档已完成所有高严重度和中严重度问题的修复，通过评审。

---

1. 与PRD对齐性

检查项	状态	说明
角色覆盖	⚠️	PRD定义3类角色(Admin/Developer/Ops)，设计文档扩展到10+，引入supply/consumer角色体系，超出PRD范围
P1需求"多角色权限"	⚠️	基础功能已覆盖，但引入的supply/consumer角色体系在PRD中未定义
用户场景遗漏	⚠️	PRD中"平台管理员"被映射为super_admin，但未说明与org_admin的职责边界
向后兼容性	⚠️	角色映射存在歧义：原admin->super_admin, owner->supply_admin，但supply侧边界模糊

具体问题：

• PRD v1第4.2节P1明确定义"多角色权限（管理员、开发者、只读）"，但设计文档引入了supply_*和consumer_*系列角色，超出PRD范围
• PRD第2.1节用户画像：平台管理员、AI应用开发者、财务/运营负责人，但设计文档额外引入"供应方"和"需求方"角色

---

2. 与TOK-001/TOK-002一致性

检查项	状态	问题描述
角色层级	⚠️	TOK-001: admin(3)/owner(2)/viewer(1)；设计文档: super_admin(100)/org_admin(50)/viewer(10)，数值体系完全不同，无明确映射关系
JWT Claims	⚠️	设计文档新增UserType和Permissions字段，与TOK-001原始Claims结构存在差异
Scope粒度	⚠️	TOK-002仅简单定义scope校验，设计文档细化为platform/tenant/supply/consumer/router五类，但未说明与原scope的兼容关系
中间件链路	✅	基本延续TOK-002的中间件链路，新增中间件类型合理
向后兼容	⚠️	RoleMapping中owner->supply_admin，但supply_admin层级(40)低于org_admin(50)，可能破坏原有owner的权限预期

层级映射矛盾分析：

TOK-001原始设计：
  admin (层级3) > owner (层级2) > viewer (层级1)

设计文档新映射：
  super_admin (100) > org_admin (50) > supply_admin (40)
                                    > operator (30) > viewer (10)

问题：supply_admin(40) < org_admin(50) 是否符合预期？原owner的权限边界在哪？

---

3. 数据模型一致性

检查项	状态	问题描述
域归属	✅	遵循IAM域设计，新建iam_roles等表符合database_domain_model规范
加密字段	❌	设计文档未定义任何*_cipher_algo、*_kms_key_alias、*_key_version、*_fingerprint等字段
单位字段	❌	未定义quota_unit、price_unit、amount_unit、currency_code等字段
审计字段	⚠️	表结构包含created_at、updated_at，但缺少request_id、created_ip、updated_ip等跨域要求的审计字段
与iam_users关系	⚠️	iam_user_roles.user_id定义为BIGINT但未明确外键约束，tenant_id可为空(NULL表示全局)的设计合理

严重缺失： 设计文档第5节数据模型完全未包含database_domain_model第3节要求的加密字段、单位字段、审计字段。这是P0/P1数据库实施的SSOT要求，设计文档必须遵守。

---

4. API命名一致性

检查项	状态	问题描述
路由前缀	✅	主体使用/api/v1/supply/*、/api/v1/consumer/*符合规范
命名规范	⚠️	第4.2节同时存在/api/v1/supply/billing和/api/v1/supplier/billing，但/supplier应仅作为deprecated alias
路由层级	✅	RESTful风格，方法与路径对应正确

问题详情：

# 第4.2节Supply API表格：
| `/api/v1/supply/billing` | GET | `tenant:billing:read` | supply_finops+ |
| `/api/v1/supplier/billing` | GET | `tenant:billing:read` | supply_finops+ (deprecated) |

# api_naming_strategy规范要求：
- 主路径统一采用：`/api/v1/supply/*`
- `/api/v1/supplier/*` 保留为 alias，标记 deprecated

问题：两个路径并列，但未说明响应体是否一致，以及迁移窗口期

---

5. 一致性问题清单

严重度	问题	建议修复	修复状态
高	数据模型缺少加密/单位/审计字段	在iam_roles、iam_scopes、iam_role_scopes、iam_user_roles表结构中补充request_id、created_ip、updated_ip、version等审计字段；如涉及凭证管理，需补充加密字段	已修复
高	角色映射歧义：owner->supply_admin的边界不清	明确说明原owner角色对应新体系的哪个角色，以及权限范围变化	已修复
中	层级数值体系与TOK-001完全断开	在文档中增加"新旧层级映射表"，说明层级3/2/1与100/50/40/30/20/10的对应关系	已修复
中	API路径混用：supply/supplier并列	明确/supplier/billing为deprecated alias，响应体应包含deprecation_notice字段	已修复
中	继承关系逻辑冲突	operator继承viewer，但operator(30)>viewer(10)，且operator有platform:write权限但viewer没有——继承关系名存实亡，应改为组合关系或明确说明继承仅用于权限聚合	已修复
低	scope定义过于细分	建议将tenant:billing:read、supply:settlement:read、consumer:billing:read统一为billing:read，通过user_type限定适用范围	已修复
低	验收标准缺少量化指标	第12节验收标准无可量化指标，建议补充如"角色层级校验<1ms"等性能指标	待优化（不影响本次评审）

---

6. 角色继承关系分析

当前设计

super_admin (100)
    │
    ▼ 继承
org_admin (50)
    │
    ├──────────────────┬─────────────────┐
    ▼                  ▼                 ▼
operator(30)     developer(20)      finops(20)
    │                  │                 │
    └──────────────────┴─────────────────┘
                         │
                         ▼ 继承
                      viewer (10)

问题

1. operator继承viewer：逻辑矛盾

   • operator层级30 > viewer层级10
   • 但operator有platform:write权限，viewer没有
   • 继承应该是"子角色拥有父角色所有权限"，但这里反过来了

2. supply/consumer与platform并列：

   • supply_*和consumer_*角色与platform_*角色是并列关系
   • 但它们通过不同的role_type区分，不是继承关系
   • 这种设计是合理的，但文档中的层级图未清晰表达

建议修复

方案A：移除虚假的继承关系
- operator/developer/finops 不继承 viewer
- 改为显式配置每个角色的scope列表
- 层级数字仅用于权限优先级判断

方案B：修正继承逻辑
- 如果A继承B，则A拥有B的所有scope + A自身scope
- 因此如果operator继承viewer，operator应该拥有viewer的所有scope
- 当前设计下，operator的scope应包含viewer的所有scope

---

7. 中间件设计评审

检查项	状态	说明
ScopeRoleAuthzMiddleware扩展	✅	向后兼容，新增配置结构合理
RoleHierarchyMiddleware	✅	新增层级校验中间件，设计合理
UserTypeMiddleware	✅	用于区分platform/supply/consumer，设计合理
错误码扩展	✅	新增错误码覆盖新增场景

---

8. 改进建议

8.1 紧急修复（必须）

1. 补充数据模型审计字段

   -- 在所有iam_*表中补充：
   request_id VARCHAR(64),     -- 请求追踪
   created_ip INET,           -- 创建者IP
   updated_ip INET,           -- 更新者IP
   version INT DEFAULT 1,     -- 乐观锁
   

2. 澄清角色映射关系

   | 旧角色 | 新角色 | 权限变化说明 |
   |--------|--------|--------------|
   | admin | super_admin | 完全对应，层级100 |
   | owner | supply_admin | 权限范围缩小，仅限供应侧管理 |
   | viewer | viewer | 完全对应，层级10 |
   

8.2 重要优化（强烈建议）

1. 统一层级数值体系

   • 方案1：保持新旧体系独立，在文档中增加映射表
   • 方案2：废弃旧体系，全部迁移到新体系

2. 修正继承关系图

   • 明确继承是"权限聚合"而非"层级高低"
   • 或改为显式scope配置，移除继承概念

3. 统一billing API路径

   • 仅保留/api/v1/supply/billing作为canonical
   • /api/v1/supplier/billing响应增加deprecation_notice

8.3 建议优化（可选）

1. 简化scope分类：从5类简化为3类（platform/consumer/supply）
2. 增加量化验收标准：如性能指标、安全指标
3. 补充安全加固建议：如MFA、IP白名单、会话超时等

---

9. 最终结论

GO

通过条件（全部已修复）：

• 补充数据模型审计字段（request_id、created_ip、updated_ip、version）
• 澄清owner->supply_admin映射关系及权限边界变化
• 增加新旧层级映射表，说明与TOK-001的对应关系
• 修正或明确operator继承viewer的逻辑
• 统一supply/supplier API路径，明确deprecated alias策略

优势：

• 整体框架完整，角色分类清晰
• scope权限粒度设计合理（统一billing:read scope）
• 中间件扩展方案兼容性好
• API路由设计符合RESTful规范
• 数据模型符合database_domain_model_and_governance v1规范
• 与TOK-001层级体系保持对齐

修复内容：

1. 数据模型：所有iam_*表已补充request_id、created_ip、updated_ip、version审计字段
2. 角色映射：新增新旧层级映射表，澄清owner->supply_admin边界
3. 继承关系：明确继承仅用于权限聚合，operator/developer/finops采用显式配置
4. API路径：移除/supplier/billing，仅保留/api/v1/supply/billing作为canonical路径
5. Scope统一：tenant:billing:read、supply:settlement:read、consumer:billing:read统一为billing:read

---

附录：评审检查清单

维度	检查项	状态
PRD对齐	覆盖三类用户角色	✅
PRD对齐	P1需求完整实现	✅
TOK一致性	角色层级兼容	✅
TOK一致性	JWT Claims扩展合理	✅
TOK一致性	中间件链路衔接	✅
数据模型	遵循跨域模型规范	✅
数据模型	加密/单位/审计字段完整	✅
API命名	路由前缀正确	✅
API命名	无混合使用问题	✅
RBAC	继承关系合理	✅
可测试	验收标准明确	✅