docs: add user management l2 specs

2026-06-14 17:44:12 +00:00
parent e2166b8d7f
commit 13c84af59f
8 changed files with 880 additions and 14 deletions
@@ -84,13 +84,13 @@

 | 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
 | --- | --- | --- | --- | --- | --- |
-| PJ2026-010501 | 账号会话 | 本规格 6.1 | 用户注册、登录、登出、session 和身份 source-of-truth | 客户端入口、平台数据库与 Secret | 客户端、Agent编排、管理后台 |
-| PJ2026-010502 | APIKey | 本规格 6.2 | API key 生命周期、scope、脱敏展示、轮换和调用身份绑定 | 账号会话、平台 Secret 支撑 | CLI、API、Agent编排 |
-| PJ2026-010503 | 权限配额 | 本规格 6.3 | role、admin、plan、entitlement、quota 和资源授权预检 | 用户身份、硬件资源事实、平台配置 | Agent编排、硬件池、客户端 |
-| PJ2026-010504 | 计量账本 | 本规格 6.4 | credit ledger、reservation、usage record、幂等和补偿 | Agent/Harness 消费事件、平台数据库 | billing、admin、运营分析 |
-| PJ2026-010505 | 账单后台 | 本规格 6.5 | billing summary、admin 调账、报表、导出、充值和兑换 | 计量账本、账号权限、客户端入口 | 用户、管理员、运营流程 |
-| PJ2026-010506 | 租户隔离 | 本规格 6.6 | 多用户数据、资源和管理操作隔离 | 用户身份、权限配额、平台存储 | 全部 L1 |
-| PJ2026-010507 | 组织管理 | 本规格 6.7 | 组织、成员、组织角色、组织项目和组织工作台归属 | 账号会话、权限配额、客户端工作台 | 客户端、Agent编排、硬件池、HarnessRL |
+| PJ2026-010501 | 账号会话 | [PJ2026-010501 账号会话](PJ2026-010501-account-session.md) | 用户注册、登录、登出、session 和身份 source-of-truth | 客户端入口、平台数据库与 Secret | 客户端、Agent编排、管理后台 |
+| PJ2026-010502 | APIKey | [PJ2026-010502 APIKey](PJ2026-010502-api-key.md) | API key 生命周期、scope、脱敏展示、轮换和调用身份绑定 | 账号会话、平台 Secret 支撑 | CLI、API、Agent编排 |
+| PJ2026-010503 | 权限配额 | [PJ2026-010503 权限配额](PJ2026-010503-access-quota.md) | role、admin、plan、entitlement、quota 和资源授权预检 | 用户身份、硬件资源事实、平台配置 | Agent编排、硬件池、客户端 |
+| PJ2026-010504 | 计量账本 | [PJ2026-010504 计量账本](PJ2026-010504-metering-ledger.md) | credit ledger、reservation、usage record、幂等和补偿 | Agent/Harness 消费事件、平台数据库 | billing、admin、运营分析 |
+| PJ2026-010505 | 账单后台 | [PJ2026-010505 账单后台](PJ2026-010505-billing-admin.md) | billing summary、admin 调账、报表、导出、充值和兑换 | 计量账本、账号权限、客户端入口 | 用户、管理员、运营流程 |
+| PJ2026-010506 | 租户隔离 | [PJ2026-010506 租户隔离](PJ2026-010506-tenant-isolation.md) | 多用户数据、资源和管理操作隔离 | 用户身份、权限配额、平台存储 | 全部 L1 |
+| PJ2026-010507 | 组织管理 | [PJ2026-010507 组织管理](PJ2026-010507-organization-management.md) | 组织、成员、组织角色、组织项目和组织工作台归属 | 账号会话、权限配额、客户端工作台 | 客户端、Agent编排、硬件池、HarnessRL |

 ## 6. 原子需求

@@ -98,7 +98,7 @@

 | 编号 | 短名 | 主责模块 | 关联模块 |
 | --- | --- | --- | --- |
-| USER-L1-REQ-001 | 账号会话 | PJ2026-010501 账号会话 | [客户端](PJ2026-0104-client.md)、[平台运维](PJ2026-0106-platform-ops.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |
+| USER-L1-REQ-001 | 账号会话 | [PJ2026-010501 账号会话](PJ2026-010501-account-session.md) | [客户端](PJ2026-0104-client.md)、[平台运维](PJ2026-0106-platform-ops.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |

 用户管理应提供统一账号与会话能力，使 HWLAB 用户能够完成注册、登录、登出、会话检查和身份续用，并让 Web、CLI、API 和内部服务都引用同一用户身份。

@@ -108,7 +108,7 @@

 | 编号 | 短名 | 主责模块 | 关联模块 |
 | --- | --- | --- | --- |
-| USER-L1-REQ-002 | APIKey | PJ2026-010502 APIKey | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[平台运维](PJ2026-0106-platform-ops.md) |
+| USER-L1-REQ-002 | APIKey | [PJ2026-010502 APIKey](PJ2026-010502-api-key.md) | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[平台运维](PJ2026-0106-platform-ops.md) |

 用户管理应提供 API key 生命周期能力，使用户和自动化脚本能够创建、撤销、轮换并以受限 scope 调用 HWLAB 服务。

@@ -118,7 +118,7 @@ API key 必须绑定用户身份、权限和额度约束，并在展示和日志

 | 编号 | 短名 | 主责模块 | 关联模块 |
 | --- | --- | --- | --- |
-| USER-L1-REQ-003 | 权限配额 | PJ2026-010503 权限配额 | [硬件池](PJ2026-0101-hardware-pool.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[客户端](PJ2026-0104-client.md) |
+| USER-L1-REQ-003 | 权限配额 | [PJ2026-010503 权限配额](PJ2026-010503-access-quota.md) | [硬件池](PJ2026-0101-hardware-pool.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[客户端](PJ2026-0104-client.md) |

 用户管理应提供权限、计划、额度和资源授权预检能力，使 HWLAB 在任务发起和资源占用前能够判断用户是否有权消费对应能力。

@@ -128,7 +128,7 @@ API key 必须绑定用户身份、权限和额度约束，并在展示和日志

 | 编号 | 短名 | 主责模块 | 关联模块 |
 | --- | --- | --- | --- |
-| USER-L1-REQ-004 | 计量账本 | PJ2026-010504 计量账本 | [Agent编排](PJ2026-0102-agent-orchestration.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[平台运维](PJ2026-0106-platform-ops.md) |
+| USER-L1-REQ-004 | 计量账本 | [PJ2026-010504 计量账本](PJ2026-010504-metering-ledger.md) | [Agent编排](PJ2026-0102-agent-orchestration.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[平台运维](PJ2026-0106-platform-ops.md) |

 用户管理应提供计量账本能力，使 reservation、usage record、credit 增减、幂等处理和回滚补偿都能落到同一用户消费真相中。

@@ -138,7 +138,7 @@ API key 必须绑定用户身份、权限和额度约束，并在展示和日志

 | 编号 | 短名 | 主责模块 | 关联模块 |
 | --- | --- | --- | --- |
-| USER-L1-REQ-005 | 账单后台 | PJ2026-010505 账单后台 | [客户端](PJ2026-0104-client.md)、[平台运维](PJ2026-0106-platform-ops.md) |
+| USER-L1-REQ-005 | 账单后台 | [PJ2026-010505 账单后台](PJ2026-010505-billing-admin.md) | [客户端](PJ2026-0104-client.md)、[平台运维](PJ2026-0106-platform-ops.md) |

 用户管理应提供账单与管理后台能力，使用户和管理员能够查看消费摘要、ledger 明细、额度状态，并完成受控的 credit 调整、兑换、充值和运营查询。

@@ -148,7 +148,7 @@ API key 必须绑定用户身份、权限和额度约束，并在展示和日志

 | 编号 | 短名 | 主责模块 | 关联模块 |
 | --- | --- | --- | --- |
-| USER-L1-REQ-006 | 租户隔离 | PJ2026-010506 租户隔离 | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[平台运维](PJ2026-0106-platform-ops.md) |
+| USER-L1-REQ-006 | 租户隔离 | [PJ2026-010506 租户隔离](PJ2026-010506-tenant-isolation.md) | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[平台运维](PJ2026-0106-platform-ops.md) |

 用户管理应提供租户隔离能力，使多用户环境中的账户、任务、资源、usage、账单和管理操作不会越权访问其他用户或租户的数据。

@@ -158,7 +158,7 @@ API key 必须绑定用户身份、权限和额度约束，并在展示和日志

 | 编号 | 短名 | 主责模块 | 关联模块 |
 | --- | --- | --- | --- |
-| USER-L1-REQ-007 | 组织管理 | PJ2026-010507 组织管理 | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[HarnessRL](PJ2026-0103-harness-rl.md) |
+| USER-L1-REQ-007 | 组织管理 | [PJ2026-010507 组织管理](PJ2026-010507-organization-management.md) | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[HarnessRL](PJ2026-0103-harness-rl.md) |

 用户管理应提供组织管理能力，使多个用户能够被分配到同一个组织，并在组织边界内共享组织所属的项目和工作台。

@@ -0,0 +1,123 @@
+# PJ2026-010501 账号会话
+
+## 修改历史
+
+| 版本 | 对应 commit id | 更新日期 | 变更说明 |
+| --- | --- | --- | --- |
+
+当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。
+
+## 正文
+
+## PJ2026-010501 账号会话需求规格
+
+## 1. 文档控制
+
+| 字段 | 内容 |
+| --- | --- |
+| 编号 | PJ2026-010501 |
+| 短名 | 账号会话 |
+| 层级 | L2 课题 |
+| 状态 | 已生效 |
+| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
+| 上级规格 | [PJ2026-0105 用户管理](PJ2026-0105-user-management.md) |
+| 规格治理索引 | [规格治理](spec-governance.md) |
+
+本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留账号会话的稳定使命、范围、术语、系统边界、内部分工和原子需求。
+
+## 2. 目的和范围
+
+### 2.1 目的
+
+账号会话负责 HWLAB 的个人账号身份事实，使用户、管理员、Web、CLI、API 和内部服务都能引用同一套注册、登录、会话和当前用户上下文。
+
+D601 v0.3 当前已具备 app-local 注册、登录、登出、会话检查、当前用户、profile 和 password 基础接口；本课题在该基线上定义后续安全设置、身份恢复和多端会话治理的目标能力。
+
+### 2.2 范围内
+
+- 用户注册、登录、登出、会话检查、会话续用和当前用户身份。
+- 用户 profile、显示名、邮箱状态、密码修改和账号状态。
+- 会话与用户状态、角色和禁用状态的一致校验。
+- 邮箱验证、找回密码、多因素认证、账号绑定和登录安全通知的规格边界。
+- Web session、API key principal 和内部服务 principal 对同一用户身份的消费边界。
+
+### 2.3 范围外
+
+- API key 生命周期归 [PJ2026-010502 APIKey](PJ2026-010502-api-key.md)。
+- 组织成员关系和组织角色归 [PJ2026-010507 组织管理](PJ2026-010507-organization-management.md)。
+- 前端登录页、账户页布局和 CLI 输出体验归 [客户端](PJ2026-0104-client.md)。
+- 数据库、Secret 注入、公开入口和发布健康归 [平台运维](PJ2026-0106-platform-ops.md)。
+
+## 3. 术语表
+
+| 术语 | 定义 |
+| --- | --- |
+| app-local 账号 | HWLAB 自身维护的账号体系，不依赖 Keycloak 作为主身份源。 |
+| Web session | 浏览器登录后由服务端签发并可校验的会话状态。 |
+| principal | 内部服务消费的已认证调用主体，包含用户、角色、状态和来源。 |
+| 当前用户 | 通过 session 或 API key 校验后得到的用户身份事实。 |
+| 身份恢复 | 用户在忘记密码、邮箱验证或账号安全事件后恢复访问的受控流程。 |
+
+## 4. 系统边界和接口
+
+本规格把账号会话作为用户管理的身份事实层看待；本章只描述输入、输出和责任边界。
+
+| 边界项 | 内容 |
+| --- | --- |
+| 外部使用者 | 普通用户、平台管理员、Cloud Web、CLI、HTTP API、Agent编排和需要用户身份的内部服务。 |
+| 外部输入 | 注册资料、登录凭据、登出请求、会话 cookie、密码修改请求、profile 修改请求、账号状态变化和身份恢复请求。 |
+| 受控资源 | 用户账号、密码哈希、profile、邮箱状态、用户状态、角色、Web session 和当前用户上下文。 |
+| 外部输出 | 登录结果、会话状态、当前用户摘要、profile 摘要、认证错误、禁用/未认证错误和身份恢复状态。 |
+| 用户接口 | Cloud Web auth 入口、HTTP auth API、`hwlab-cli` 用户身份命令。 |
+| 系统边界 | 账号会话负责用户身份和 session 真相；不定义 API key 策略、组织授权、Agent 执行、页面布局或发布机制。 |
+
+## 5. 内部分工与规格索引
+
+| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
+| --- | --- | --- | --- | --- | --- |
+| PJ2026-01050101 | 注册登录 | 本规格 6.1 | app-local 注册、登录和登出语义 | 客户端入口、平台数据库 | Web、CLI、API |
+| PJ2026-01050102 | 会话状态 | 本规格 6.2 | session 检查、当前用户和禁用状态生效 | 注册登录、平台 Secret | API key、Agent编排、客户端 |
+| PJ2026-01050103 | Profile安全 | 本规格 6.3 | profile、密码修改和安全设置 | 用户身份、客户端账户入口 | 用户自服务、admin 用户管理 |
+| PJ2026-01050104 | 身份恢复 | 本规格 6.4 | 邮箱验证、找回密码和多因素认证边界 | 邮件/通知能力、平台配置 | 用户恢复、运营支持 |
+
+## 6. 原子需求
+
+### 6.1 USER-ACCT-REQ-001 注册登录
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| USER-ACCT-REQ-001 | 注册登录 | PJ2026-01050101 注册登录 | [客户端](PJ2026-0104-client.md)、[平台运维](PJ2026-0106-platform-ops.md) |
+
+账号会话应提供 app-local 注册、登录和登出能力，使 HWLAB 可以在不引入 Keycloak 主路径的前提下承载多用户云服务身份。
+
+注册登录必须写入用户管理的用户事实源，返回可被 Web、CLI、API 和内部服务共同理解的认证结果。客户端负责呈现入口和错误，平台运维负责持久化和 Secret 支撑。
+
+### 6.2 USER-ACCT-REQ-002 会话状态
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| USER-ACCT-REQ-002 | 会话状态 | PJ2026-01050102 会话状态 | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |
+
+账号会话应提供可检查、可续用、可撤销的 session 状态，使当前用户、角色和账号状态能够在每次受保护访问前被一致判断。
+
+被禁用、被撤销或未认证的 session 必须以明确错误进入客户端和内部服务，不得由 Agent、HWPOD、账单或页面状态自行猜测身份有效性。
+
+### 6.3 USER-ACCT-REQ-003 Profile 与安全设置
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| USER-ACCT-REQ-003 | Profile安全 | PJ2026-01050103 Profile安全 | [客户端](PJ2026-0104-client.md)、[账单后台](PJ2026-010505-billing-admin.md) |
+
+账号会话应提供 profile、密码修改和账号安全设置能力，使用户能够维护基本资料和登录安全，而不影响账本、API key 或任务事实。
+
+profile 安全设置只拥有账号资料和登录安全事实。余额通知、账单展示和运营视图可消费这些资料，但不能把页面状态作为账号事实源。
+
+### 6.4 USER-ACCT-REQ-004 身份恢复
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| USER-ACCT-REQ-004 | 身份恢复 | PJ2026-01050104 身份恢复 | [客户端](PJ2026-0104-client.md)、[平台运维](PJ2026-0106-platform-ops.md) |
+
+账号会话应定义邮箱验证、找回密码、多因素认证和账号绑定的恢复边界，使用户在安全事件或凭据丢失后有受控恢复路径。
+
+身份恢复必须通过用户管理状态机更新账号事实，并由平台运维提供邮件、Secret 和运行支撑。未实现的恢复能力不得由临时 admin SQL、直接改库或客户端本地状态替代。
@@ -0,0 +1,122 @@
+# PJ2026-010502 APIKey
+
+## 修改历史
+
+| 版本 | 对应 commit id | 更新日期 | 变更说明 |
+| --- | --- | --- | --- |
+
+当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。
+
+## 正文
+
+## PJ2026-010502 APIKey 需求规格
+
+## 1. 文档控制
+
+| 字段 | 内容 |
+| --- | --- |
+| 编号 | PJ2026-010502 |
+| 短名 | APIKey |
+| 层级 | L2 课题 |
+| 状态 | 已生效 |
+| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
+| 上级规格 | [PJ2026-0105 用户管理](PJ2026-0105-user-management.md) |
+| 规格治理索引 | [规格治理](spec-governance.md) |
+
+本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 APIKey 的稳定使命、范围、术语、系统边界、内部分工和原子需求。
+
+## 2. 目的和范围
+
+### 2.1 目的
+
+APIKey 负责 HWLAB 自动化调用凭据的生命周期和调用身份绑定，使用户脚本、CLI、Agent 入口和内部 API 能以可撤销、可审计、可限额的方式代表用户发起请求。
+
+D601 v0.3 当前已具备用户自服务 API key 创建、列表、重命名、撤销、prefix 展示和创建时一次性 secret 返回；本课题在该基线上定义 expiry、quota、IP/rate 策略、轮换和调用审计的目标能力。
+
+### 2.2 范围内
+
+- API key 创建、一次性 secret 返回、prefix 脱敏展示、列表、重命名、撤销和轮换。
+- key 与用户、scope、状态、过期时间、quota、rate limit、IP 策略和调用身份的绑定。
+- API key introspection、preflight principal 生成和受保护 API 调用鉴权。
+- key 使用记录、last used、拒绝原因和审计摘要。
+
+### 2.3 范围外
+
+- 用户注册登录和 Web session 归 [PJ2026-010501 账号会话](PJ2026-010501-account-session.md)。
+- quota、plan、entitlement 的业务解释归 [PJ2026-010503 权限配额](PJ2026-010503-access-quota.md)。
+- usage、ledger 和费用扣减归 [PJ2026-010504 计量账本](PJ2026-010504-metering-ledger.md)。
+- CLI 参数和输出格式归 [客户端](PJ2026-0104-client.md)。
+
+## 3. 术语表
+
+| 术语 | 定义 |
+| --- | --- |
+| API key secret | 创建时一次性返回给用户的完整调用凭据。 |
+| key prefix | 可长期展示和搜索的非敏感 key 摘要。 |
+| scope | API key 可访问能力集合的声明。 |
+| introspection | 服务端根据 API key 解析用户、状态、scope 和策略的过程。 |
+| key 策略 | 绑定在 API key 上的过期、quota、IP、rate limit 或状态约束。 |
+
+## 4. 系统边界和接口
+
+本规格把 APIKey 作为用户管理的自动化凭据层看待；本章只描述输入、输出和责任边界。
+
+| 边界项 | 内容 |
+| --- | --- |
+| 外部使用者 | 普通用户、自动化脚本、CLI、Cloud API、Agent编排、平台管理员。 |
+| 外部输入 | 创建 key 请求、重命名请求、撤销请求、轮换请求、API key 调用凭据、scope 和策略配置。 |
+| 受控资源 | API key 记录、secret hash、prefix、scope、状态、过期时间、quota/rate/IP 策略和 last used 摘要。 |
+| 外部输出 | 创建结果、一次性 secret、脱敏 key 列表、introspection principal、拒绝错误和审计摘要。 |
+| 用户接口 | Cloud Web API key 页面、HTTP API、`hwlab-cli` API key 命令和受保护业务 API。 |
+| 系统边界 | APIKey 负责调用凭据和用户身份绑定；不定义用户登录、计费扣减、客户端布局或 Agent 执行事实。 |
+
+## 5. 内部分工与规格索引
+
+| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
+| --- | --- | --- | --- | --- | --- |
+| PJ2026-01050201 | Key生命周期 | 本规格 6.1 | 创建、展示、重命名、撤销和轮换 | 账号会话 | Web、CLI |
+| PJ2026-01050202 | Key策略 | 本规格 6.2 | scope、expiry、quota、IP 和 rate limit 绑定 | 权限配额、平台配置 | 受保护 API |
+| PJ2026-01050203 | Key校验 | 本规格 6.3 | introspection 和 principal 输出 | 账号状态、key 策略 | Agent编排、Cloud API |
+| PJ2026-01050204 | Key审计 | 本规格 6.4 | last used、拒绝原因和脱敏审计 | key 校验、计量账本 | admin、运营分析 |
+
+## 6. 原子需求
+
+### 6.1 USER-KEY-REQ-001 Key 生命周期
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| USER-KEY-REQ-001 | Key生命周期 | PJ2026-01050201 Key生命周期 | [客户端](PJ2026-0104-client.md)、[账号会话](PJ2026-010501-account-session.md) |
+
+APIKey 应提供用户自服务的 key 创建、列表、重命名、撤销和轮换能力，并保证完整 secret 只在创建或轮换时返回一次。
+
+长期展示和日志中只能使用 prefix、状态、scope、last used 和 redacted 摘要。客户端负责呈现这些摘要，不得保存或重新展示完整 secret。
+
+### 6.2 USER-KEY-REQ-002 Key 策略
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| USER-KEY-REQ-002 | Key策略 | PJ2026-01050202 Key策略 | [权限配额](PJ2026-010503-access-quota.md)、[平台运维](PJ2026-0106-platform-ops.md) |
+
+APIKey 应支持把 scope、过期时间、quota、IP 约束和 rate limit 策略绑定到 key，使自动化调用可以被按用户和凭据级别限制。
+
+key 策略只表达调用凭据约束。plan、entitlement 和资源可消费性由权限配额解释；平台运维只提供配置和运行支撑，不定义用户策略。
+
+### 6.3 USER-KEY-REQ-003 Key 校验
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| USER-KEY-REQ-003 | Key校验 | PJ2026-01050203 Key校验 | [Agent编排](PJ2026-0102-agent-orchestration.md)、[计量账本](PJ2026-010504-metering-ledger.md) |
+
+APIKey 应提供服务端 introspection，使受保护 API 能把调用凭据解析为用户 principal、scope、状态和策略判断结果。
+
+撤销 key、过期 key、禁用用户和不满足 scope 的调用必须在进入 Agent 执行、硬件资源占用或计费记录前被拒绝，并返回可被客户端一致呈现的错误。
+
+### 6.4 USER-KEY-REQ-004 Key 审计
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| USER-KEY-REQ-004 | Key审计 | PJ2026-01050204 Key审计 | [账单后台](PJ2026-010505-billing-admin.md)、[租户隔离](PJ2026-010506-tenant-isolation.md) |
+
+APIKey 应记录 key 使用摘要、last used、拒绝原因和策略命中信息，使用户和管理员可以排查自动化调用而不暴露完整 secret。
+
+审计输出必须脱敏，并与 usage、ledger 和租户隔离判断保持一致。任何 issue、日志、导出和页面都不得打印完整 API key。
@@ -0,0 +1,125 @@
+# PJ2026-010503 权限配额
+
+## 修改历史
+
+| 版本 | 对应 commit id | 更新日期 | 变更说明 |
+| --- | --- | --- | --- |
+
+当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。
+
+## 正文
+
+## PJ2026-010503 权限配额需求规格
+
+## 1. 文档控制
+
+| 字段 | 内容 |
+| --- | --- |
+| 编号 | PJ2026-010503 |
+| 短名 | 权限配额 |
+| 层级 | L2 课题 |
+| 状态 | 已生效 |
+| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
+| 上级规格 | [PJ2026-0105 用户管理](PJ2026-0105-user-management.md) |
+| 规格治理索引 | [规格治理](spec-governance.md) |
+
+本文采用 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](PJ2026-010502-api-key.md)。
+- reservation、usage record 和 credit 扣减归 [PJ2026-010504 计量账本](PJ2026-010504-metering-ledger.md)。
+- HWPOD inventory、硬件占用事实和设备健康归 [硬件池](PJ2026-0101-hardware-pool.md)。
+- Agent run 生命周期和资源装配归 [Agent编排](PJ2026-0102-agent-orchestration.md)。
+
+## 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 角色权限 | [账号会话](PJ2026-010501-account-session.md)、[客户端](PJ2026-0104-client.md) |
+
+权限配额应提供 role 和 admin 授权能力，使普通用户、管理员和内部服务能在同一用户身份上下文中获得一致的操作许可判断。
+
+管理操作必须通过用户管理的角色权限判断，不得由前端路由、临时脚本或业务模块本地列表替代。
+
+### 6.2 USER-AUTHZ-REQ-002 Plan 与 entitlement 模型
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| USER-AUTHZ-REQ-002 | Plan模型 | PJ2026-01050302 Plan模型 | [账单后台](PJ2026-010505-billing-admin.md)、[平台运维](PJ2026-0106-platform-ops.md) |
+
+权限配额应提供 plan、entitlement 和 resource type 模型，使用户或组织可以被授予不同资源能力和额度组合。
+
+plan 模型是用户管理的业务事实。平台运维只负责持久化和配置投递；Agent编排、硬件池和客户端只消费 resource entitlement，不复制 plan 判断逻辑。
+
+### 6.3 USER-AUTHZ-REQ-003 额度、并发和 RPM
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| USER-AUTHZ-REQ-003 | 额度约束 | PJ2026-01050303 额度约束 | [计量账本](PJ2026-010504-metering-ledger.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[硬件池](PJ2026-0101-hardware-pool.md) |
+
+权限配额应在资源消费前检查 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 授权错误 | [客户端](PJ2026-0104-client.md)、[APIKey](PJ2026-010502-api-key.md) |
+
+权限配额应输出稳定的未授权、未开通、额度不足、并发超限和频率超限错误，使 Web、CLI、HTTP API 和内部模块可以一致处理失败。
+
+授权错误必须阻止后续资源占用和计费扣减。客户端负责解释和展示错误，不得把错误映射成成功、排队中或未知状态。
@@ -0,0 +1,124 @@
+# PJ2026-010504 计量账本
+
+## 修改历史
+
+| 版本 | 对应 commit id | 更新日期 | 变更说明 |
+| --- | --- | --- | --- |
+
+当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。
+
+## 正文
+
+## PJ2026-010504 计量账本需求规格
+
+## 1. 文档控制
+
+| 字段 | 内容 |
+| --- | --- |
+| 编号 | PJ2026-010504 |
+| 短名 | 计量账本 |
+| 层级 | L2 课题 |
+| 状态 | 已生效 |
+| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
+| 上级规格 | [PJ2026-0105 用户管理](PJ2026-0105-user-management.md) |
+| 规格治理索引 | [规格治理](spec-governance.md) |
+
+本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留计量账本的稳定使命、范围、术语、系统边界、内部分工和原子需求。
+
+## 2. 目的和范围
+
+### 2.1 目的
+
+计量账本负责 HWLAB credit、reservation、usage、ledger 和补偿关系的业务真相，使资源消费、失败释放、终态扣费、手动调账和兑换入账都能被统一查询、幂等处理和审计。
+
+D601 v0.3 当前已具备 Code Agent running reservation、terminal success record、failed/canceled/timeout release、用户 billing summary、admin ledger/usage 查询、manual credit audit 和 redeem ledger；本课题在该基线上定义所有 resource type 的计量归因和补偿边界。
+
+### 2.2 范围内
+
+- credit account、balance、reserved balance、ledger delta、before/after 和 source。
+- reservation create/release/expire、terminal usage record 和幂等 key。
+- Code Agent、AIPOD、HWPOD、Harness 相关 resource type 的 usage 归因。
+- admin adjustment、redeem、manual recharge、payment placeholder 和后续 payment order 的账本落点。
+- 失败、取消、超时、重复提交和补偿操作的账本语义。
+
+### 2.3 范围外
+
+- plan、entitlement 和 preflight allow/deny 归 [PJ2026-010503 权限配额](PJ2026-010503-access-quota.md)。
+- admin 查询页面、CSV export 和运营视图归 [PJ2026-010505 账单后台](PJ2026-010505-billing-admin.md)。
+- Agent run、command 和 runner job 终态归 [Agent编排](PJ2026-0102-agent-orchestration.md)。
+- CaseRun pass/fail 和训练评价归 [HarnessRL](PJ2026-0103-harness-rl.md)。
+
+## 3. 术语表
+
+| 术语 | 定义 |
+| --- | --- |
+| credit account | 用户或组织在 HWLAB 中的余额与保留额度账户。 |
+| reservation | 任务开始前为预估消费冻结的额度。 |
+| usage record | 任务终态后按实际资源用量写入的消费记录。 |
+| credit ledger | 记录余额增减、前后余额、来源、状态和幂等关系的账本。 |
+| idempotency key | 防止重复 reservation、record、adjust 或 redeem 的幂等标识。 |
+| compensation | 对失败、取消、超时或错误记账进行释放、冲正或补偿的账本操作。 |
+
+## 4. 系统边界和接口
+
+本规格把计量账本作为用户管理的消费事实层看待；本章只描述输入、输出和责任边界。
+
+| 边界项 | 内容 |
+| --- | --- |
+| 外部使用者 | Agent编排、HarnessRL、硬件池、账单后台、客户端、平台管理员。 |
+| 外部输入 | 授权预检结果、reservation 请求、terminal usage 事件、release 事件、admin adjust、redeem、payment/order 状态和幂等 key。 |
+| 受控资源 | credit account、reservation、usage record、credit ledger、balance before/after、source、status、metadata 和 idempotency。 |
+| 外部输出 | 可用余额、保留余额、账本行、usage 摘要、reservation 状态、幂等结果和补偿结果。 |
+| 用户接口 | billing summary、admin ledger/usage API、受保护业务 API、Cloud Web/CLI 账务入口。 |
+| 系统边界 | 计量账本负责消费事实和余额变化；不定义资源是否可用、执行是否成功、页面如何展示或支付 provider 如何回调。 |
+
+## 5. 内部分工与规格索引
+
+| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
+| --- | --- | --- | --- | --- | --- |
+| PJ2026-01050401 | Reservation | 本规格 6.1 | 额度冻结、释放和过期 | 权限配额、业务请求 | Agent编排、硬件池 |
+| PJ2026-01050402 | UsageRecord | 本规格 6.2 | 终态用量和 resource metadata | Agent/Harness 终态事件 | billing summary、admin usage |
+| PJ2026-01050403 | Ledger幂等 | 本规格 6.3 | credit delta、before/after 和幂等处理 | usage、adjust、redeem | 账单后台、运营审计 |
+| PJ2026-01050404 | 补偿归因 | 本规格 6.4 | 失败释放、冲正和来源归因 | terminal status、admin 操作 | 客户端、admin |
+
+## 6. 原子需求
+
+### 6.1 USER-LEDGER-REQ-001 Reservation
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| USER-LEDGER-REQ-001 | Reservation | PJ2026-01050401 Reservation | [权限配额](PJ2026-010503-access-quota.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |
+
+计量账本应提供 reservation 能力，使任务或资源消费在执行前可以冻结额度，并在失败、取消、超时或过期时释放。
+
+reservation 只表示额度保留，不等同于实际消费。执行中状态不得提前写 usage debit；终态事件到达后才进入 usage record 或 release。
+
+### 6.2 USER-LEDGER-REQ-002 Usage record
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| USER-LEDGER-REQ-002 | UsageRecord | PJ2026-01050402 UsageRecord | [Agent编排](PJ2026-0102-agent-orchestration.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[硬件池](PJ2026-0101-hardware-pool.md) |
+
+计量账本应在业务终态后记录 usage，使 service、resource type、quantity、credits、API key、trace 或 task metadata 能被用户和管理员追溯。
+
+Agent编排和 HarnessRL 提供终态和用量语义，硬件池提供资源类型和硬件上下文；计量账本负责把这些输入归一为用户消费事实。
+
+### 6.3 USER-LEDGER-REQ-003 Ledger 幂等
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| USER-LEDGER-REQ-003 | Ledger幂等 | PJ2026-01050403 Ledger幂等 | [账单后台](PJ2026-010505-billing-admin.md)、[APIKey](PJ2026-010502-api-key.md) |
+
+计量账本应对 usage、admin adjust、redeem、payment/order 和补偿操作提供幂等处理，并在 ledger 中记录 delta、before/after、source、reason、status 和 operator 摘要。
+
+重复提交同一幂等 key 不得重复扣费或重复入账。账本输出不得包含 API key secret、session token、密码、DB DSN 或 provider 凭据。
+
+### 6.4 USER-LEDGER-REQ-004 补偿与来源归因
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| USER-LEDGER-REQ-004 | 补偿归因 | PJ2026-01050404 补偿归因 | [Agent编排](PJ2026-0102-agent-orchestration.md)、[账单后台](PJ2026-010505-billing-admin.md) |
+
+计量账本应提供失败释放、取消释放、超时释放、冲正和人工补偿语义，使每次余额变化都能说明来源和原因。
+
+补偿不能隐藏原始消费事实。用户和管理员应能区分任务成功扣费、任务失败释放、人工调账、兑换入账和后续支付入账。
@@ -0,0 +1,124 @@
+# PJ2026-010505 账单后台
+
+## 修改历史
+
+| 版本 | 对应 commit id | 更新日期 | 变更说明 |
+| --- | --- | --- | --- |
+
+当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。
+
+## 正文
+
+## PJ2026-010505 账单后台需求规格
+
+## 1. 文档控制
+
+| 字段 | 内容 |
+| --- | --- |
+| 编号 | PJ2026-010505 |
+| 短名 | 账单后台 |
+| 层级 | L2 课题 |
+| 状态 | 已生效 |
+| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
+| 上级规格 | [PJ2026-0105 用户管理](PJ2026-0105-user-management.md) |
+| 规格治理索引 | [规格治理](spec-governance.md) |
+
+本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留账单后台的稳定使命、范围、术语、系统边界、内部分工和原子需求。
+
+## 2. 目的和范围
+
+### 2.1 目的
+
+账单后台负责把用户管理的余额、usage、ledger、plan、entitlement、admin 调账、兑换和支付/订阅状态以用户和管理员可操作的方式暴露出来，使 HWLAB 能从内测账号运营演进到可审计的多用户云服务运营。
+
+D601 v0.3 当前已具备用户 billing summary、admin usage/ledger filter、CSV export、manual credit audit、redeem code 管理、用户兑换和 payment/subscription `unconfigured` 占位；本课题在该基线上定义真实支付 provider、订阅和增长活动接入前后的边界。
+
+### 2.2 范围内
+
+- 用户 billing summary、余额、plan、entitlement、reservation、usage 和 ledger 摘要。
+- admin usage/ledger 查询、过滤、分页、导出和运营对账。
+- admin credit adjust、operator、reason、idempotency、before/after 和审计显示。
+- redeem code 创建、list、disable、redemption 查询和兑换入账。
+- subscription/payment provider-agnostic 占位、真实 provider 接入边界、订单和回调状态的账本落点。
+
+### 2.3 范围外
+
+- 余额、reservation、usage 和 ledger 真相归 [PJ2026-010504 计量账本](PJ2026-010504-metering-ledger.md)。
+- plan、entitlement 和 quota 解释归 [PJ2026-010503 权限配额](PJ2026-010503-access-quota.md)。
+- 页面布局、筛选控件和下载交互归 [客户端](PJ2026-0104-client.md)。
+- 真实 payment provider 的 Secret 同步、回调公开入口和运行支撑归 [平台运维](PJ2026-0106-platform-ops.md)。
+
+## 3. 术语表
+
+| 术语 | 定义 |
+| --- | --- |
+| billing summary | 用户可见的余额、plan、quota、usage、ledger 和 reservation 摘要。 |
+| admin usage | 管理员按用户、服务、资源、API key、时间和状态查询的 usage 视图。 |
+| admin ledger | 管理员按用户、来源、动作、状态和幂等 key 查询的 credit ledger 视图。 |
+| redeem code | 管理员生成、用户兑换、可限制次数和状态的充值凭证。 |
+| payment placeholder | 没有真实 provider 配置时明确返回的未配置支付状态。 |
+| operator audit | 管理员写操作的操作人、原因、幂等、前后余额和时间摘要。 |
+
+## 4. 系统边界和接口
+
+本规格把账单后台作为用户管理的运营视图和操作层看待；本章只描述输入、输出和责任边界。
+
+| 边界项 | 内容 |
+| --- | --- |
+| 外部使用者 | 普通用户、平台管理员、运营人员、Cloud Web、CLI、HTTP API。 |
+| 外部输入 | billing summary 查询、admin usage/ledger filter、credit adjust 请求、redeem code 管理、redeem 请求、payment/subscription 状态请求。 |
+| 受控资源 | billing summary、admin usage view、admin ledger view、CSV export、redeem code、redemption、manual adjust 和 payment/subscription 状态摘要。 |
+| 外部输出 | 用户账单摘要、运营过滤结果、导出文件、调账结果、兑换结果、redemption/ledger 关联和 provider 未配置状态。 |
+| 用户接口 | Cloud Web billing/admin billing 页面、HTTP API、`hwlab-cli` 管理命令。 |
+| 系统边界 | 账单后台负责运营查询和受控写操作入口；不创建第二账本，不直连内部数据库替代 user-billing authority。 |
+
+## 5. 内部分工与规格索引
+
+| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
+| --- | --- | --- | --- | --- | --- |
+| PJ2026-01050501 | 用户账单 | 本规格 6.1 | 用户 billing summary 和 quota/ledger 摘要 | 计量账本、权限配额 | 客户端、CLI |
+| PJ2026-01050502 | 管理查询 | 本规格 6.2 | admin usage/ledger filter/export | 计量账本、账号权限 | 运营对账 |
+| PJ2026-01050503 | 调账兑换 | 本规格 6.3 | manual adjust、redeem code 和 redemption | 计量账本、admin 权限 | 用户充值、运营支持 |
+| PJ2026-01050504 | 支付订阅 | 本规格 6.4 | payment/subscription placeholder 和真实 provider 边界 | 平台配置、计量账本 | 后续商业化 |
+
+## 6. 原子需求
+
+### 6.1 USER-BILL-REQ-001 用户账单摘要
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| USER-BILL-REQ-001 | 用户账单 | PJ2026-01050501 用户账单 | [计量账本](PJ2026-010504-metering-ledger.md)、[权限配额](PJ2026-010503-access-quota.md)、[客户端](PJ2026-0104-client.md) |
+
+账单后台应提供用户账单摘要，使用户能查看余额、保留额度、plan、entitlement、quota、usage、ledger 和 reservation 状态。
+
+用户账单摘要只聚合用户管理事实，不在客户端或 Cloud API 中创建平行余额、quota 或 ledger。
+
+### 6.2 USER-BILL-REQ-002 管理查询与导出
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| USER-BILL-REQ-002 | 管理查询 | PJ2026-01050502 管理查询 | [计量账本](PJ2026-010504-metering-ledger.md)、[租户隔离](PJ2026-010506-tenant-isolation.md) |
+
+账单后台应提供 admin usage 和 ledger 的过滤、分页和导出能力，使管理员可以按时间、用户、服务、资源、API key、状态、来源和幂等关系做运营对账。
+
+导出内容必须与当前 filter 一致，并排除 session token、API key secret、password hash、DB DSN 和 provider token 等敏感值。
+
+### 6.3 USER-BILL-REQ-003 调账与兑换
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| USER-BILL-REQ-003 | 调账兑换 | PJ2026-01050503 调账兑换 | [计量账本](PJ2026-010504-metering-ledger.md)、[APIKey](PJ2026-010502-api-key.md) |
+
+账单后台应提供 admin credit adjust、redeem code 管理和用户 redeem 能力，使人工充值、运营补偿和兑换码入账可以进入同一 ledger。
+
+调账和兑换必须保留 operator、reason、idempotency、before/after、redemption 或 code 摘要，并防止一次性 code 或重复幂等 key 产生重复入账。
+
+### 6.4 USER-BILL-REQ-004 支付与订阅边界
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| USER-BILL-REQ-004 | 支付订阅 | PJ2026-01050504 支付订阅 | [平台运维](PJ2026-0106-platform-ops.md)、[计量账本](PJ2026-010504-metering-ledger.md) |
+
+账单后台应在没有真实 provider 配置时明确返回 payment/subscription `unconfigured` 状态，并在 provider 配置齐备后承接订单、回调、订阅状态和 ledger 入账。
+
+真实 payment provider 只能通过受控 YAML/sourceRef/Secret sync 和端到端回调验证接入。不得硬编码 provider、手工写 Secret、临时 SQL 入账或在 Cloud API 中维护平行 payment ledger。
@@ -0,0 +1,123 @@
+# PJ2026-010506 租户隔离
+
+## 修改历史
+
+| 版本 | 对应 commit id | 更新日期 | 变更说明 |
+| --- | --- | --- | --- |
+
+当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。
+
+## 正文
+
+## PJ2026-010506 租户隔离需求规格
+
+## 1. 文档控制
+
+| 字段 | 内容 |
+| --- | --- |
+| 编号 | PJ2026-010506 |
+| 短名 | 租户隔离 |
+| 层级 | L2 课题 |
+| 状态 | 已生效 |
+| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
+| 上级规格 | [PJ2026-0105 用户管理](PJ2026-0105-user-management.md) |
+| 规格治理索引 | [规格治理](spec-governance.md) |
+
+本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留租户隔离的稳定使命、范围、术语、系统边界、内部分工和原子需求。
+
+## 2. 目的和范围
+
+### 2.1 目的
+
+租户隔离负责 HWLAB 多用户和后续组织协同中的数据、任务、资源和管理操作边界，使用户不能越权读取或操作其他用户、组织或租户的账户、任务、usage、ledger、API key、workspace 和硬件资源。
+
+D601 v0.3 当前已具备个人用户、admin/普通用户角色、受保护 Web/API session、admin-only 管理入口和用户账务隔离基础；本课题在该基线上定义组织、项目、工作台和跨模块资源隔离的目标能力。
+
+### 2.2 范围内
+
+- 用户、组织、项目、工作台、Agent session、HWPOD 资源、usage 和 ledger 的归属上下文。
+- 普通用户、管理员、组织成员和内部服务之间的访问边界。
+- 用户自服务、admin 管理、API key 调用和内部任务回写中的越权防护。
+- 跨模块 principal、tenant context 和 ownership metadata 的传递。
+- 越权拒绝、审计摘要和敏感信息脱敏。
+
+### 2.3 范围外
+
+- 组织、成员和组织项目模型归 [PJ2026-010507 组织管理](PJ2026-010507-organization-management.md)。
+- 页面可见性和路由守卫归 [客户端](PJ2026-0104-client.md)。
+- Agent run、workspace 和 session 生命周期归 [Agent编排](PJ2026-0102-agent-orchestration.md)。
+- 物理硬件资源事实和租约归 [硬件池](PJ2026-0101-hardware-pool.md)。
+
+## 3. 术语表
+
+| 术语 | 定义 |
+| --- | --- |
+| tenant context | 一次请求或任务所属的用户、组织、项目和工作台上下文。 |
+| ownership metadata | 数据或资源记录上用于判断归属的用户、组织或项目字段。 |
+| 越权访问 | 调用者访问或操作不属于其权限范围的数据、任务、资源或账务。 |
+| admin override | 管理员在授权范围内查看或操作用户数据的受控路径。 |
+| isolation decision | 根据 principal 和 ownership metadata 得出的 allow/deny 结论。 |
+
+## 4. 系统边界和接口
+
+本规格把租户隔离作为用户管理的横向访问边界看待；本章只描述输入、输出和责任边界。
+
+| 边界项 | 内容 |
+| --- | --- |
+| 外部使用者 | 客户端、Agent编排、硬件池、HarnessRL、账单后台、平台管理员和内部服务。 |
+| 外部输入 | principal、tenant context、ownership metadata、请求动作、目标资源、admin 操作和组织成员关系。 |
+| 受控资源 | 用户数据、组织数据、项目、工作台、Agent session、workspace、API key、usage、ledger、reservation 和硬件资源引用。 |
+| 外部输出 | allow/deny 决策、越权错误、admin override 审计、脱敏摘要和下游 tenant context。 |
+| 用户接口 | Web/API 访问检查、admin API、业务 API、CLI 错误输出。 |
+| 系统边界 | 租户隔离负责访问边界和 ownership 判断；不定义组织业务模型、任务执行事实、硬件事实或页面布局。 |
+
+## 5. 内部分工与规格索引
+
+| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
+| --- | --- | --- | --- | --- | --- |
+| PJ2026-01050601 | 数据归属 | 本规格 6.1 | 用户、组织、项目和资源 ownership | 账号会话、组织管理 | 全部业务模块 |
+| PJ2026-01050602 | 访问约束 | 本规格 6.2 | allow/deny 和 admin override | 数据归属、权限配额 | Web/API/CLI |
+| PJ2026-01050603 | 上下文传递 | 本规格 6.3 | tenant context 跨模块传递 | Agent编排、硬件池、客户端 | 计量账本、HarnessRL |
+| PJ2026-01050604 | 越权审计 | 本规格 6.4 | 越权错误和审计摘要 | 访问约束、账单后台 | admin、运营排障 |
+
+## 6. 原子需求
+
+### 6.1 USER-TENANT-REQ-001 数据归属
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| USER-TENANT-REQ-001 | 数据归属 | PJ2026-01050601 数据归属 | [组织管理](PJ2026-010507-organization-management.md)、[账号会话](PJ2026-010501-account-session.md) |
+
+租户隔离应为用户、组织、项目、工作台、任务、资源、usage 和 ledger 提供稳定 ownership metadata，使访问判断有明确归属依据。
+
+没有归属上下文的数据不能默认公开给全部用户。历史个人账号数据在进入组织模型后也必须有明确迁移或默认归属规则。
+
+### 6.2 USER-TENANT-REQ-002 访问约束
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| USER-TENANT-REQ-002 | 访问约束 | PJ2026-01050602 访问约束 | [权限配额](PJ2026-010503-access-quota.md)、[客户端](PJ2026-0104-client.md) |
+
+租户隔离应根据 principal、role、组织成员关系、请求动作和目标资源归属输出访问 allow/deny 决策。
+
+客户端路由、页面隐藏和 CLI 参数过滤不能替代服务端访问约束。admin override 必须由角色权限允许，并保留可审计摘要。
+
+### 6.3 USER-TENANT-REQ-003 上下文传递
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| USER-TENANT-REQ-003 | 上下文传递 | PJ2026-01050603 上下文传递 | [Agent编排](PJ2026-0102-agent-orchestration.md)、[硬件池](PJ2026-0101-hardware-pool.md)、[HarnessRL](PJ2026-0103-harness-rl.md) |
+
+租户隔离应把 tenant context 传递给 Agent、HWPOD、CaseRun、usage 和 ledger 相关模块，使执行事实和消费事实都能回到正确用户或组织。
+
+下游模块可以消费 tenant context，但不得在本地重新发明不兼容的用户、组织或租户模型。
+
+### 6.4 USER-TENANT-REQ-004 越权审计
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| USER-TENANT-REQ-004 | 越权审计 | PJ2026-01050604 越权审计 | [账单后台](PJ2026-010505-billing-admin.md)、[平台运维](PJ2026-0106-platform-ops.md) |
+
+租户隔离应为越权拒绝、admin override 和敏感资源访问提供脱敏审计摘要，使管理员能定位访问问题而不泄露用户 Secret 或私有数据。
+
+审计摘要只能记录必要的 userId、organizationId、resource id、动作、状态和错误码，不得输出 API key secret、session token、password hash、DB DSN 或 provider token。
@@ -0,0 +1,125 @@
+# PJ2026-010507 组织管理
+
+## 修改历史
+
+| 版本 | 对应 commit id | 更新日期 | 变更说明 |
+| --- | --- | --- | --- |
+
+当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。
+
+## 正文
+
+## PJ2026-010507 组织管理需求规格
+
+## 1. 文档控制
+
+| 字段 | 内容 |
+| --- | --- |
+| 编号 | PJ2026-010507 |
+| 短名 | 组织管理 |
+| 层级 | L2 课题 |
+| 状态 | 已生效 |
+| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
+| 上级规格 | [PJ2026-0105 用户管理](PJ2026-0105-user-management.md) |
+| 规格治理索引 | [规格治理](spec-governance.md) |
+
+本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留组织管理的稳定使命、范围、术语、系统边界、内部分工和原子需求。
+
+## 2. 目的和范围
+
+### 2.1 目的
+
+组织管理负责 HWLAB 2B 协同中的组织身份、成员、组织角色、组织项目和组织工作台归属，使多个用户可以围绕同一组织上下文共享项目、任务、资源、结果和账务边界。
+
+D601 v0.3 当前以个人用户和 admin 管理为主，尚未把组织作为一等业务实体；本课题定义从个人账号基线扩展到组织协同、组织级资源授权和组织级租户隔离的目标能力。
+
+### 2.2 范围内
+
+- 组织创建、组织资料、组织状态和组织身份。
+- 组织成员、邀请、移除、成员状态和组织角色。
+- 组织项目、组织工作台、组织内 Agent session、HWPOD/CaseRun 资源归属。
+- 组织级 plan、entitlement、quota、billing summary 和 admin 管理边界。
+- 个人账号与组织上下文切换、默认归属和迁移规则。
+
+### 2.3 范围外
+
+- 个人账号登录和 Web session 归 [PJ2026-010501 账号会话](PJ2026-010501-account-session.md)。
+- 组织访问边界和越权判断归 [PJ2026-010506 租户隔离](PJ2026-010506-tenant-isolation.md)。
+- 组织项目或工作台的页面体验归 [客户端](PJ2026-0104-client.md)。
+- Agent 执行和 workspace materialization 归 [Agent编排](PJ2026-0102-agent-orchestration.md)。
+- 真实硬件资源事实和 HWPOD 资源池归 [硬件池](PJ2026-0101-hardware-pool.md)。
+
+## 3. 术语表
+
+| 术语 | 定义 |
+| --- | --- |
+| 组织 | 多个用户协作的业务主体，可拥有成员、项目、工作台、资源和账务边界。 |
+| 组织成员 | 与组织绑定并拥有组织角色的用户。 |
+| 组织角色 | 用户在组织内的权限类别，例如 owner、admin、member 或 viewer。 |
+| 组织项目 | 归属于组织并可被成员按权限访问的项目。 |
+| 组织工作台 | 归属于组织并承载组织内任务、资源和结果入口的工作台。 |
+| 组织上下文 | 请求或任务当前所属的组织、项目和工作台身份。 |
+
+## 4. 系统边界和接口
+
+本规格把组织管理作为用户管理的 2B 协同事实层看待；本章只描述输入、输出和责任边界。
+
+| 边界项 | 内容 |
+| --- | --- |
+| 外部使用者 | 组织 owner、组织成员、平台管理员、客户端、Agent编排、硬件池、HarnessRL、账单后台。 |
+| 外部输入 | 组织创建请求、成员邀请、角色变更、组织项目归属、组织工作台归属、组织 plan/entitlement 配置和组织上下文选择。 |
+| 受控资源 | 组织、组织成员、组织角色、组织项目、组织工作台、组织资源归属、组织 billing context 和组织 tenant context。 |
+| 外部输出 | 组织摘要、成员列表、角色判断、组织上下文、组织资源归属、组织账务摘要和组织内访问判断输入。 |
+| 用户接口 | Cloud Web 组织入口、HTTP API、admin API、CLI 组织命令。 |
+| 系统边界 | 组织管理负责组织事实和归属；不定义页面布局、Agent 执行、硬件状态、账本扣费细节或平台发布机制。 |
+
+## 5. 内部分工与规格索引
+
+| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
+| --- | --- | --- | --- | --- | --- |
+| PJ2026-01050701 | 组织身份 | 本规格 6.1 | 组织创建、资料和状态 | 账号会话、admin 权限 | 客户端、租户隔离 |
+| PJ2026-01050702 | 成员角色 | 本规格 6.2 | 成员邀请、移除和组织角色 | 组织身份、账号会话 | 权限配额、客户端 |
+| PJ2026-01050703 | 项目工作台 | 本规格 6.3 | 组织项目和组织工作台归属 | 成员角色、客户端工作台 | Agent编排、硬件池 |
+| PJ2026-01050704 | 组织运营 | 本规格 6.4 | 组织 plan、quota、billing 和资源归属 | 权限配额、计量账本 | 账单后台、租户隔离 |
+
+## 6. 原子需求
+
+### 6.1 USER-ORG-REQ-001 组织身份
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| USER-ORG-REQ-001 | 组织身份 | PJ2026-01050701 组织身份 | [账号会话](PJ2026-010501-account-session.md)、[客户端](PJ2026-0104-client.md) |
+
+组织管理应提供组织创建、资料维护和状态管理能力，使团队或企业可以作为 HWLAB 协同和运营边界存在。
+
+组织身份是组织成员、组织项目、组织工作台、组织资源和组织账务的上游事实。个人账号不能用临时标签替代组织身份。
+
+### 6.2 USER-ORG-REQ-002 成员与角色
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| USER-ORG-REQ-002 | 成员角色 | PJ2026-01050702 成员角色 | [权限配额](PJ2026-010503-access-quota.md)、[租户隔离](PJ2026-010506-tenant-isolation.md) |
+
+组织管理应提供组织成员邀请、移除、状态和组织角色能力，使组织内访问和管理操作可以按成员关系授权。
+
+组织角色只定义组织内权限上下文；全局 admin、个人账号状态和 API key 策略仍由对应用户管理课题定义。
+
+### 6.3 USER-ORG-REQ-003 组织项目与工作台
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| USER-ORG-REQ-003 | 项目工作台 | PJ2026-01050703 项目工作台 | [客户端](PJ2026-0104-client.md)、[Agent编排](PJ2026-0102-agent-orchestration.md)、[硬件池](PJ2026-0101-hardware-pool.md) |
+
+组织管理应定义组织项目和组织工作台归属，使组织成员可以在同一组织上下文中发起任务、查看结果和共享资源。
+
+项目和工作台的用户体验由客户端实现，Agent 和硬件模块消费组织上下文与归属，不在本地创建另一个组织模型。
+
+### 6.4 USER-ORG-REQ-004 组织运营边界
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| USER-ORG-REQ-004 | 组织运营 | PJ2026-01050704 组织运营 | [账单后台](PJ2026-010505-billing-admin.md)、[计量账本](PJ2026-010504-metering-ledger.md)、[权限配额](PJ2026-010503-access-quota.md) |
+
+组织管理应定义组织级 plan、entitlement、quota、billing 和资源归属边界，使组织可以作为资源消费和账务汇总主体。
+
+组织运营边界不得破坏个人用户账本和租户隔离。组织级消费应能追溯到组织、成员、项目、工作台和具体 resource type。