# PJ2026-010504 计量账本

## 修改历史

| 版本 | 对应 commit id | 更新日期 | 变更说明 |
| --- | --- | --- | --- |

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

## 正文

## PJ2026-010504 计量账本需求规格

## 1. 文档控制

| 字段 | 内容 |
| --- | --- |
| 编号 | PJ2026-010504 |
| 短名 | 计量账本 |
| 层级 | 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 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 权限配额](PJ2026-010503-access-quota.md)。
- admin 查询页面、CSV export 和运营视图归 [PJ2026-010505 账单后台](PJ2026-010505-billing-admin.md)。
- Agent run、command 和 runner job 终态归 [Agent编排](PJ2026-0102-agent-orchestration.md)。
- CaseRun pass/fail 和训练评价归 [HarnessRL](PJ2026-0103-harness-rl.md)。

## 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 | [权限配额](PJ2026-010503-access-quota.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |

计量账本应提供 reservation 能力，使任务或资源消费在执行前可以冻结额度，并在失败、取消、超时或过期时释放。

reservation 只表示额度保留，不等同于实际消费。执行中状态不得提前写 usage debit；终态事件到达后才进入 usage record 或 release。

### 6.2 USER-LEDGER-REQ-002 Usage record

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| USER-LEDGER-REQ-002 | UsageRecord | PJ2026-01050402 UsageRecord | [Agent编排](PJ2026-0102-agent-orchestration.md)、[HarnessRL](PJ2026-0103-harness-rl.md)、[硬件池](PJ2026-0101-hardware-pool.md) |

计量账本应在业务终态后记录 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幂等 | [账单后台](PJ2026-010505-billing-admin.md)、[APIKey](PJ2026-010502-api-key.md) |

计量账本应对 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编排](PJ2026-0102-agent-orchestration.md)、[账单后台](PJ2026-010505-billing-admin.md) |

计量账本应提供失败释放、取消释放、超时释放、冲正和人工补偿语义，使每次余额变化都能说明来源和原因。

补偿不能隐藏原始消费事实。用户和管理员应能区分任务成功扣费、任务失败释放、人工调账、兑换入账和后续支付入账。
