pikasTech-unidesk/project-management/PJ2026-01/specs/PJ2026-0105-user-management.md

PJ2026-0105 用户管理

修改历史

版本	对应 commit id	更新日期	变更说明
v0.3	b5d8cee438	2026-06-14	将 issue/PR 引用显示改为短号 Markdown 链接，链接目标保留完整 URL。
v0.2	b0cbe9b721	2026-06-14	将 issue/PR 引用改为完整 GitHub URL，避免 Markdown 渲染时裸 # 编号失效。
v0.1	37de91c653	2026-06-14	从迁移来源 pikasTech/HWLAB#1207 迁移到 UniDesk 项目管理目录。

当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 待提交 版本。

正文

PJ2026-0105 用户管理需求规格

1. 文档控制

字段	内容
编号	PJ2026-0105
短名	用户管理
层级	L1 方向
状态	已生效
需求规格模板	ISO/IEC/IEEE 29148 需求规格模板
上级规格	PJ2026-01 HWLAB 总规格
规格治理索引	规格治理

本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留用户管理的稳定使命、范围、术语、系统边界、内部分工和原子需求。

2. 目的和范围

2.1 目的

用户管理负责 HWLAB 的用户身份、组织、会话、API key、权限、额度、计量、账单、管理员操作和租户隔离，使多用户云服务中的任务发起、组织协同、资源消费和运营管理都能引用同一套用户、组织与账本真相。

2.2 范围内

• 用户注册、登录、登出、session、会话检查和用户身份 source-of-truth。
• 组织、组织成员、组织角色、组织内项目和组织工作台归属。
• API key 创建、撤销、scope、脱敏展示、轮换、服务端校验和调用身份绑定。
• role、admin、plan、entitlement、quota、concurrency、RPM 和资源授权预检。
• credit ledger、reservation、usage record、幂等消费、回滚补偿和 usage 来源归因。
• billing summary、admin credit adjust、报表、导出、兑换码、手动充值和运营后台能力。
• tenant 边界、用户数据隔离、资源隔离、跨用户共享约束和越权防护。

2.3 范围外

• Web、CLI 和 HTTP API 的入口体验归 客户端。
• Agent run、command、session、workspace 和 provider profile 生命周期归 Agent编排。
• HWPOD 资源身份、硬件事实、租约和物理资源状态归 硬件池。
• CaseRun 评价、回放、训练反馈和执行结果语义归 HarnessRL。
• 数据库、YAML-first 运维、发布、公开入口和 Prometheus 运维监控归 平台运维。

3. 术语表

术语	定义
用户	HWLAB 中拥有身份、权限、额度和资源消费记录的主体。
组织	可包含多个用户的 2B 协作边界，拥有组织内项目、工作台和成员权限。
组织项目	归属于某个组织并可由组织成员按权限共同访问的项目。
组织工作台	归属于某个组织并承载组织内任务、资源和结果入口的工作台。
会话	用户完成身份认证后获得的登录状态和服务端可检查的访问上下文。
API key	用户或自动化脚本用于调用 HWLAB API 的凭据，与用户身份、scope 和额度约束绑定。
权限	用户对管理操作、任务操作、资源操作和账单操作的访问许可。
配额	用户在并发、频率、资源类型或资源数量上的可消费上限。
计量账本	记录 reservation、usage、credit 增减和补偿关系的用户消费真相。
租户隔离	多用户环境中数据、资源和管理操作不能越权访问其他用户或租户的约束。

4. 系统边界和接口

本规格把用户管理作为 HWLAB 内部的身份与运营子系统看待；本章只描述该子系统的输入、输出和责任边界。

边界项	内容
外部使用者	硬件研发用户、自动化脚本、平台管理员、Agent编排、客户端和需要授权判断的内部模块。
外部输入	登录凭据、API key、组织创建和成员分配请求、组织项目和工作台归属、权限请求、计划和配额配置、任务消费事件、硬件资源约束、管理员操作和充值/兑换请求。
受控资源	用户记录、组织、组织成员、组织项目、组织工作台、会话、API key、角色、计划、额度、credit ledger、usage record、billing summary、admin 操作记录和租户边界。
外部输出	用户身份、组织成员关系、组织项目和工作台可见性、会话状态、API key 摘要、授权预检结果、额度状态、usage/credit 记录、账单摘要、管理员查询结果和租户隔离判断。
用户接口	Cloud Web 登录和账户入口、hwlab-cli 用户与管理命令、HTTP API、admin API。
系统边界	用户管理负责身份、组织、权限、额度、计量、账单和租户隔离真相；不定义客户端界面、Agent 执行、硬件事实、Harness 评价或平台发布机制。

5. 内部分工与规格索引

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

6. 原子需求

6.1 USER-L1-REQ-001 账号与会话

编号	短名	主责模块	关联模块
USER-L1-REQ-001	账号会话	PJ2026-010501 账号会话	客户端、平台运维、Agent编排

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

账号与会话是用户管理的身份事实源。客户端负责呈现登录和账户入口，平台运维提供数据库与 Secret 支撑，Agent编排只消费已确认身份，不另建任务侧用户身份。

6.2 USER-L1-REQ-002 API key 生命周期

编号	短名	主责模块	关联模块
USER-L1-REQ-002	APIKey	PJ2026-010502 APIKey	客户端、Agent编排、平台运维

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

API key 必须绑定用户身份、权限和额度约束，并在展示和日志中只暴露安全摘要。客户端负责入口和输出形态，平台运维负责 Secret 运行支撑，业务模块只消费校验结果和调用身份。

6.3 USER-L1-REQ-003 权限、配额与资源授权

编号	短名	主责模块	关联模块
USER-L1-REQ-003	权限配额	PJ2026-010503 权限配额	硬件池、Agent编排、客户端

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

权限配额只定义用户是否可以消费资源和可消费多少。硬件池负责真实硬件可用性，Agent编排负责任务装配与执行，客户端负责把授权失败或额度不足以一致方式暴露给用户。

6.4 USER-L1-REQ-004 计量账本

编号	短名	主责模块	关联模块
USER-L1-REQ-004	计量账本	PJ2026-010504 计量账本	Agent编排、HarnessRL、平台运维

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

计量账本必须能区分任务发起、资源占用、执行失败、执行完成和人工调整等消费来源。Agent编排和 HarnessRL 提供消费事件语义，平台运维提供持久化和运行支撑，但不得反向定义 credit 或 usage 业务规则。

6.5 USER-L1-REQ-005 账单与管理后台

编号	短名	主责模块	关联模块
USER-L1-REQ-005	账单后台	PJ2026-010505 账单后台	客户端、平台运维

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

账单与管理后台承载用户管理的运营视图，不能用客户端页面状态或临时数据库查询替代账本真相。客户端负责页面和命令入口，平台运维负责运行支撑和数据服务可用性。

6.6 USER-L1-REQ-006 租户隔离

编号	短名	主责模块	关联模块
USER-L1-REQ-006	租户隔离	PJ2026-010506 租户隔离	客户端、Agent编排、硬件池、HarnessRL、平台运维

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

租户隔离必须成为各入口和内部模块共享的访问边界。组织内共享项目和工作台也必须受租户边界约束。客户端、Agent编排、硬件池、HarnessRL 和平台运维都应消费用户管理给出的身份、组织和权限上下文，而不是在各自模块中发明不一致的隔离规则。

6.7 USER-L1-REQ-007 组织管理

编号	短名	主责模块	关联模块
USER-L1-REQ-007	组织管理	PJ2026-010507 组织管理	客户端、Agent编排、硬件池、HarnessRL

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

组织管理是 HWLAB 的 2B 协同基础能力。它必须定义组织身份、组织成员关系、组织角色、组织内项目归属和组织工作台归属，使企业或团队用户可以围绕同一组织上下文发起任务、查看结果、管理资源和协同工作。

用户管理负责组织成员、角色和组织资源归属真相。客户端负责呈现组织切换、组织项目和组织工作台入口；Agent编排、硬件池和 HarnessRL 消费组织上下文与权限约束，不在各自模块中另建组织模型。