Lyon
10 KiB
PJ2026-010501 账号会话
修改历史
| 版本 | 对应 commit id | 更新日期 | 变更说明 |
|---|
当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 待提交 版本。
正文
PJ2026-010501 账号会话需求规格
1. 文档控制
| 字段 | 内容 |
|---|---|
| 编号 | PJ2026-010501 |
| 短名 | 账号会话 |
| 层级 | L2 课题 |
| 状态 | 已生效 |
| 需求规格模板 | ISO/IEC/IEEE 29148 需求规格模板 |
| 上级规格 | PJ2026-0105 用户管理 |
| 规格治理索引 | 规格治理 |
本文采用 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 对同一用户身份的消费边界。
- 浏览器同源
hwlab_session到 canonical principal 的唯一解释通道，以及 recovery/bootstrap 身份的显式边界。
2.3 范围外
- API key 生命周期归 PJ2026-010502 APIKey。
- 组织成员关系和组织角色归 PJ2026-010507 组织管理。
- 前端登录页、账户页布局和 CLI 输出体验归 客户端。
- 数据库、Secret 注入、公开入口和发布健康归 平台运维。
3. 术语表
| 术语 | 定义 |
|---|---|
| app-local 账号 | HWLAB 自身维护的账号体系，不依赖 Keycloak 作为主身份源。 |
| Web session | 浏览器登录后由服务端签发并可校验的会话状态。 |
| principal | 内部服务消费的已认证调用主体，包含用户、角色、状态和来源。 |
| canonical principal | 认证层把 Web session、API key 或受控 recovery 身份解释后产出的最小身份主体，包含 authMethod、identityAuthority、sessionKind、actor 摘要和后端授权摘要。 |
| 当前用户 | 通过 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 | 邮箱验证、找回密码和多因素认证边界 | 邮件/通知能力、平台配置 | 用户恢复、运营支持 |
| PJ2026-01050105 | 用户导航ACL | PJ2026-01050105 用户导航ACL | 浏览器 session transport、canonical principal、YAML 预置用户和根导航 ACL 边界 | 注册登录、会话状态、权限配额、YAML运维 | API契约、Web工作台、业务 API |
6. 原子需求
6.1 USER-ACCT-REQ-001 注册登录
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| USER-ACCT-REQ-001 | 注册登录 | PJ2026-01050101 注册登录 | 客户端、平台运维 |
账号会话应提供 app-local 注册、登录和登出能力，使 HWLAB 可以在不引入 Keycloak 主路径的前提下承载多用户云服务身份。
注册登录必须写入用户管理的用户事实源，返回可被 Web、CLI、API 和内部服务共同理解的认证结果。客户端负责呈现入口和错误，平台运维负责持久化和 Secret 支撑。
6.2 USER-ACCT-REQ-002 会话状态
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| USER-ACCT-REQ-002 | 会话状态 | PJ2026-01050102 会话状态 | 客户端、Agent编排 |
账号会话应提供可检查、可续用、可撤销的 session 状态，使当前用户、角色和账号状态能够在每次受保护访问前被一致判断。
被禁用、被撤销或未认证的 session 必须以明确错误进入客户端和内部服务，不得由 Agent、HWPOD、账单或页面状态自行猜测身份有效性。
6.3 USER-ACCT-REQ-003 Profile 与安全设置
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| USER-ACCT-REQ-003 | Profile安全 | PJ2026-01050103 Profile安全 | 客户端、账单后台 |
账号会话应提供 profile、密码修改和账号安全设置能力，使用户能够维护基本资料和登录安全，而不影响账本、API key 或任务事实。
profile 安全设置只拥有账号资料和登录安全事实。余额通知、账单展示和运营视图可消费这些资料，但不能把页面状态作为账号事实源。
6.4 USER-ACCT-REQ-004 身份恢复
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| USER-ACCT-REQ-004 | 身份恢复 | PJ2026-01050104 身份恢复 | 客户端、平台运维 |
账号会话应定义邮箱验证、找回密码、多因素认证和账号绑定的恢复边界，使用户在安全事件或凭据丢失后有受控恢复路径。
身份恢复必须通过用户管理状态机更新账号事实，并由平台运维提供邮件、Secret 和运行支撑。未实现的恢复能力不得由临时 admin SQL、直接改库或客户端本地状态替代。
6.5 USER-ACCT-REQ-005 Web 鉴权唯一通道
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| USER-ACCT-REQ-005 | 用户导航ACL | PJ2026-01050105 用户导航ACL | API契约、客户端、权限配额、YAML运维 |
账号会话应把浏览器同源 hwlab_session 视为 Web session transport，由后端唯一认证入口解释为 canonical principal。Cloud Web、Workbench、Usage、Billing、Admin 和 Code Agent 等业务面只能消费这个 principal 与后端 capability 摘要，不得在页面、route 或业务 handler 中重新解析 cookie prefix、Bearer、hws_、API key secret、user-billing token 或 localStorage authority 来定义用户身份。
canonical principal 至少应表达 authenticated、authMethod、identityAuthority、sessionKind、actor 摘要和脱敏 capability 摘要。authMethod 用于说明 transport 来源，例如 Web session、user-billing session、API key 或 local-bootstrap；identityAuthority 用于说明身份事实归属，例如 hwlab-local、user-billing 或 bootstrap-recovery；sessionKind 用于区分浏览器、API key 和 recovery 身份。local/bootstrap 或 recovery 身份不能静默伪装成完整业务用户，必须在 canonical principal 中显式标记其能力边界和 blocker。
身份验证和业务授权必须分层：账号会话先证明“当前调用主体是谁”；权限配额、账单后台、Agent编排、Workbench 和 Admin 再判断“该主体能做什么”。billing、usage、API key、Workbench 或 Code Agent 的业务 capability 不得反过来决定 Web 是否已登录。未登录、禁用、撤销或能力不可用必须返回结构化错误或 blocker，不能让前端通过二次登录、API key 输入、cookie prefix 判断或 fallback endpoint 补救身份。
D601 v0.3 预置用户、根导航 navId、nav profile、Secret sourceRef、session access claim、router guard 和后端 API capability enforcement 的专项边界见 PJ2026-01050105 用户导航ACL。该专项规格是本需求在 YAML-first 预置用户与根导航访问控制方向的 P0 SPEC-first source of truth。