Codex
7.1 KiB
PJ2026-010504 计量账本
修改历史
| 版本 | 对应 commit id | 更新日期 | 变更说明 |
|---|
当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 待提交 版本。
正文
PJ2026-010504 计量账本需求规格
1. 文档控制
| 字段 | 内容 |
|---|---|
| 编号 | PJ2026-010504 |
| 短名 | 计量账本 |
| 层级 | L2 课题 |
| 状态 | 已生效 |
| 需求规格模板 | ISO/IEC/IEEE 29148 需求规格模板 |
| 上级规格 | PJ2026-0105 用户管理 |
| 规格治理索引 | 规格治理 |
本文采用 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 权限配额。
- admin 查询页面、CSV export 和运营视图归 PJ2026-010505 账单后台。
- Agent run、command 和 runner job 终态归 Agent编排。
- CaseRun pass/fail 和训练评价归 HarnessRL。
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 | 权限配额、Agent编排 |
计量账本应提供 reservation 能力，使任务或资源消费在执行前可以冻结额度，并在失败、取消、超时或过期时释放。
reservation 只表示额度保留，不等同于实际消费。执行中状态不得提前写 usage debit；终态事件到达后才进入 usage record 或 release。
6.2 USER-LEDGER-REQ-002 Usage record
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| USER-LEDGER-REQ-002 | UsageRecord | PJ2026-01050402 UsageRecord | Agent编排、HarnessRL、硬件池 |
计量账本应在业务终态后记录 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幂等 | 账单后台、APIKey |
计量账本应对 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编排、账单后台 |
计量账本应提供失败释放、取消释放、超时释放、冲正和人工补偿语义，使每次余额变化都能说明来源和原因。
补偿不能隐藏原始消费事实。用户和管理员应能区分任务成功扣费、任务失败释放、人工调账、兑换入账和后续支付入账。