mirrors/pikasTech-unidesk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
94dece78369c8cc8dc61d1057845d121ebc0bf64
pikasTech-unidesk/project-management/PJ2026-01/specs/PJ2026-0105-user-management.md
T
Codex 13c84af59f docs: add user management l2 specs
2026-06-14 17:44:12 +00:00

168 lines
13 KiB
Markdown
Raw Blame History

# PJ2026-0105 用户管理
## 修改历史
| 版本 | 对应 commit id | 更新日期 | 变更说明 |
| --- | --- | --- | --- |
| v0.3 | b5d8cee438a3bd66ca440a25bf5a16d9081d9efa | 2026-06-14 | 将 issue/PR 引用显示改为短号 Markdown 链接，链接目标保留完整 URL。 |
| v0.2 | b0cbe9b721b50e9fff4d350ee50ed2af03cf0405 | 2026-06-14 | 将 issue/PR 引用改为完整 GitHub URL，避免 Markdown 渲染时裸 # 编号失效。 |
| v0.1 | 37de91c653c055bf19ac271bdb687b54072639fa | 2026-06-14 | 从迁移来源 pikasTech/HWLAB#1207 迁移到 UniDesk 项目管理目录。 |
当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。
## 正文
## PJ2026-0105 用户管理需求规格
## 1. 文档控制
| 字段 | 内容 |
| --- | --- |
| 编号 | PJ2026-0105 |
| 短名 | 用户管理 |
| 层级 | L1 方向 |
| 状态 | 已生效 |
| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
| 上级规格 | [PJ2026-01 HWLAB 总规格](PJ2026-01-HWLAB.md) |
| 规格治理索引 | [规格治理](spec-governance.md) |
本文采用 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 的入口体验归 [客户端](PJ2026-0104-client.md)。
- Agent run、command、session、workspace 和 provider profile 生命周期归 [Agent编排](PJ2026-0102-agent-orchestration.md)。
- HWPOD 资源身份、硬件事实、租约和物理资源状态归 [硬件池](PJ2026-0101-hardware-pool.md)。
- CaseRun 评价、回放、训练反馈和执行结果语义归 [HarnessRL](PJ2026-0103-harness-rl.md)。
- 数据库、YAML-first 运维、发布、公开入口和 Prometheus 运维监控归 [平台运维](PJ2026-0106-platform-ops.md)。
## 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 账号会话](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. 原子需求
### 6.1 USER-L1-REQ-001 账号与会话
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| 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 和内部服务都引用同一用户身份。
账号与会话是用户管理的身份事实源。客户端负责呈现登录和账户入口，平台运维提供数据库与 Secret 支撑，Agent编排只消费已确认身份，不另建任务侧用户身份。
### 6.2 USER-L1-REQ-002 API key 生命周期
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| 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 服务。
API key 必须绑定用户身份、权限和额度约束，并在展示和日志中只暴露安全摘要。客户端负责入口和输出形态，平台运维负责 Secret 运行支撑，业务模块只消费校验结果和调用身份。
### 6.3 USER-L1-REQ-003 权限、配额与资源授权
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| 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 在任务发起和资源占用前能够判断用户是否有权消费对应能力。
权限配额只定义用户是否可以消费资源和可消费多少。硬件池负责真实硬件可用性，Agent编排负责任务装配与执行，客户端负责把授权失败或额度不足以一致方式暴露给用户。
### 6.4 USER-L1-REQ-004 计量账本
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| 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 增减、幂等处理和回滚补偿都能落到同一用户消费真相中。
计量账本必须能区分任务发起、资源占用、执行失败、执行完成和人工调整等消费来源。Agent编排和 HarnessRL 提供消费事件语义，平台运维提供持久化和运行支撑，但不得反向定义 credit 或 usage 业务规则。
### 6.5 USER-L1-REQ-005 账单与管理后台
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| USER-L1-REQ-005 | 账单后台 | [PJ2026-010505 账单后台](PJ2026-010505-billing-admin.md) | [客户端](PJ2026-0104-client.md)、[平台运维](PJ2026-0106-platform-ops.md) |
用户管理应提供账单与管理后台能力，使用户和管理员能够查看消费摘要、ledger 明细、额度状态，并完成受控的 credit 调整、兑换、充值和运营查询。
账单与管理后台承载用户管理的运营视图，不能用客户端页面状态或临时数据库查询替代账本真相。客户端负责页面和命令入口，平台运维负责运行支撑和数据服务可用性。
### 6.6 USER-L1-REQ-006 租户隔离
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| 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、账单和管理操作不会越权访问其他用户或租户的数据。
租户隔离必须成为各入口和内部模块共享的访问边界。组织内共享项目和工作台也必须受租户边界约束。客户端、Agent编排、硬件池、HarnessRL 和平台运维都应消费用户管理给出的身份、组织和权限上下文，而不是在各自模块中发明不一致的隔离规则。
### 6.7 USER-L1-REQ-007 组织管理
| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| 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) |
用户管理应提供组织管理能力，使多个用户能够被分配到同一个组织，并在组织边界内共享组织所属的项目和工作台。
组织管理是 HWLAB 的 2B 协同基础能力。它必须定义组织身份、组织成员关系、组织角色、组织内项目归属和组织工作台归属，使企业或团队用户可以围绕同一组织上下文发起任务、查看结果、管理资源和协同工作。
用户管理负责组织成员、角色和组织资源归属真相。客户端负责呈现组织切换、组织项目和组织工作台入口；Agent编排、硬件池和 HarnessRL 消费组织上下文与权限约束，不在各自模块中另建组织模型。
Reference in New Issue View Git Blame Copy Permalink