Codex
7.0 KiB
PJ2026-010503 权限配额
修改历史
| 版本 | 对应 commit id | 更新日期 | 变更说明 |
|---|
当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 待提交 版本。
正文
PJ2026-010503 权限配额需求规格
1. 文档控制
| 字段 | 内容 |
|---|---|
| 编号 | PJ2026-010503 |
| 短名 | 权限配额 |
| 层级 | L2 课题 |
| 状态 | 已生效 |
| 需求规格模板 | ISO/IEC/IEEE 29148 需求规格模板 |
| 上级规格 | PJ2026-0105 用户管理 |
| 规格治理索引 | 规格治理 |
本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留权限配额的稳定使命、范围、术语、系统边界、内部分工和原子需求。
2. 目的和范围
2.1 目的
权限配额负责 HWLAB 用户是否可以访问管理能力、消费资源能力以及可消费多少的判断，使任务发起、Agent 执行、HWPOD/Harness 资源占用和账单预检都引用同一套 role、plan、entitlement、quota、concurrency 和 RPM 真相。
D601 v0.3 当前已具备 admin role、默认 plan、code_agent / aipod / hwpod entitlement、quota/concurrency/RPM 预检和用户 plan 摘要；本课题在该基线上定义多 plan、资源级授权和跨模块预检的目标能力。
2.2 范围内
- 用户 role、admin 权限、管理操作授权和普通用户访问边界。
- plan、entitlement、resource type、quota、concurrency、RPM 和可消费资源集合。
- 任务发起前的授权预检和资源消费前的额度判断。
- 用户、API key、组织和资源类型之间的授权上下文组合。
- 未授权、额度不足、并发超限和速率超限的统一错误语义。
2.3 范围外
- API key secret 生命周期归 PJ2026-010502 APIKey。
- reservation、usage record 和 credit 扣减归 PJ2026-010504 计量账本。
- HWPOD inventory、硬件占用事实和设备健康归 硬件池。
- Agent run 生命周期和资源装配归 Agent编排。
3. 术语表
| 术语 | 定义 |
|---|---|
| role | 用户在 HWLAB 内的操作权限类别，例如普通用户或管理员。 |
| plan | 用户或组织绑定的服务计划，定义可用资源和额度组合。 |
| entitlement | 某个 plan 对特定 resource type 的授权声明。 |
| resource type | 被 user-billing 识别的资源消费类型，例如 Code Agent、AIPOD 或 HWPOD。 |
| quota | 用户在周期或资源类型上的可消费额度。 |
| concurrency | 同一用户或组织可同时占用的资源数量上限。 |
| RPM | 单位时间内允许发起的请求频率约束。 |
4. 系统边界和接口
本规格把权限配额作为用户管理的授权和资源消费预检层看待；本章只描述输入、输出和责任边界。
| 边界项 | 内容 |
|---|---|
| 外部使用者 | Cloud API、Agent编排、硬件池、客户端、平台管理员、自动化脚本。 |
| 外部输入 | 用户 principal、API key principal、role、plan、resource type、请求额度、当前 reservation、usage 窗口和管理员配置。 |
| 受控资源 | role、plan、entitlement、quota、concurrency、RPM、授权预检结果和拒绝原因。 |
| 外部输出 | admin/用户授权判断、resource entitlement 摘要、额度状态、preflight allow/deny、错误码和限额剩余摘要。 |
| 用户接口 | admin 用户管理、用户 billing summary、受保护业务 API、CLI/Web 错误展示。 |
| 系统边界 | 权限配额负责能否消费资源和可消费多少；不定义硬件是否真实可用、Agent 如何执行、usage 如何落账或页面如何展示。 |
5. 内部分工与规格索引
| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
|---|---|---|---|---|---|
| PJ2026-01050301 | 角色权限 | 本规格 6.1 | role、admin 和管理操作授权 | 账号会话 | admin API、客户端 |
| PJ2026-01050302 | Plan模型 | 本规格 6.2 | plan、entitlement 和 resource type 模型 | 平台配置、用户账号 | billing summary、preflight |
| PJ2026-01050303 | 额度约束 | 本规格 6.3 | quota、concurrency 和 RPM 判断 | usage/reservation、resource type | Agent编排、硬件池 |
| PJ2026-01050304 | 授权错误 | 本规格 6.4 | 未授权和超限错误语义 | 角色权限、额度约束 | 客户端、CLI、API |
6. 原子需求
6.1 USER-AUTHZ-REQ-001 角色权限
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| USER-AUTHZ-REQ-001 | 角色权限 | PJ2026-01050301 角色权限 | 账号会话、客户端 |
权限配额应提供 role 和 admin 授权能力，使普通用户、管理员和内部服务能在同一用户身份上下文中获得一致的操作许可判断。
管理操作必须通过用户管理的角色权限判断，不得由前端路由、临时脚本或业务模块本地列表替代。
6.2 USER-AUTHZ-REQ-002 Plan 与 entitlement 模型
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| USER-AUTHZ-REQ-002 | Plan模型 | PJ2026-01050302 Plan模型 | 账单后台、平台运维 |
权限配额应提供 plan、entitlement 和 resource type 模型，使用户或组织可以被授予不同资源能力和额度组合。
plan 模型是用户管理的业务事实。平台运维只负责持久化和配置投递；Agent编排、硬件池和客户端只消费 resource entitlement，不复制 plan 判断逻辑。
6.3 USER-AUTHZ-REQ-003 额度、并发和 RPM
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| USER-AUTHZ-REQ-003 | 额度约束 | PJ2026-01050303 额度约束 | 计量账本、Agent编排、硬件池 |
权限配额应在资源消费前检查 quota、concurrency 和 RPM，使 Code Agent、AIPOD、HWPOD 等 resource type 的占用进入统一预检。
额度约束可以消费 reservation、usage 和 resource metadata，但不得自行写 usage ledger。通过预检后产生的占用和扣费由计量账本负责。
6.4 USER-AUTHZ-REQ-004 授权错误语义
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| USER-AUTHZ-REQ-004 | 授权错误 | PJ2026-01050304 授权错误 | 客户端、APIKey |
权限配额应输出稳定的未授权、未开通、额度不足、并发超限和频率超限错误，使 Web、CLI、HTTP API 和内部模块可以一致处理失败。
授权错误必须阻止后续资源占用和计费扣减。客户端负责解释和展示错误，不得把错误映射成成功、排队中或未知状态。