Codex
139 lines
9.4 KiB
Markdown
139 lines
9.4 KiB
Markdown
# 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 对同一用户身份的消费边界。
|
||
- 浏览器同源 `hwlab_session` 到 canonical principal 的唯一解释通道，以及 recovery/bootstrap 身份的显式边界。
|
||
|
||
### 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 | 内部服务消费的已认证调用主体，包含用户、角色、状态和来源。 |
|
||
| 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 | Web鉴权 | 本规格 6.5 | 浏览器 session transport、canonical principal 和 recovery 身份边界 | 注册登录、会话状态、权限配额 | API契约、Web工作台、业务 API |
|
||
|
||
## 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、直接改库或客户端本地状态替代。
|
||
|
||
### 6.5 USER-ACCT-REQ-005 Web 鉴权唯一通道
|
||
|
||
| 编号 | 短名 | 主责模块 | 关联模块 |
|
||
| --- | --- | --- | --- |
|
||
| USER-ACCT-REQ-005 | Web鉴权 | PJ2026-01050105 Web鉴权 | [API契约](PJ2026-010403-api-contract.md)、[客户端](PJ2026-0104-client.md)、[权限配额](PJ2026-010503-access-quota.md) |
|
||
|
||
账号会话应把浏览器同源 `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 补救身份。
|