Codex
127 lines
7.8 KiB
Markdown
127 lines
7.8 KiB
Markdown
# PJ2026-010505 账单后台
|
|
|
|
## 修改历史
|
|
|
|
| 版本 | 对应 commit id | 更新日期 | 变更说明 |
|
|
| --- | --- | --- | --- |
|
|
|
|
当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。
|
|
|
|
## 正文
|
|
|
|
## PJ2026-010505 账单后台需求规格
|
|
|
|
## 1. 文档控制
|
|
|
|
| 字段 | 内容 |
|
|
| --- | --- |
|
|
| 编号 | PJ2026-010505 |
|
|
| 短名 | 账单后台 |
|
|
| 层级 | 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 目的
|
|
|
|
账单后台负责把用户管理的余额、usage、ledger、plan、entitlement、admin 调账、兑换和支付/订阅状态以用户和管理员可操作的方式暴露出来，使 HWLAB 能从内测账号运营演进到可审计的多用户云服务运营。
|
|
|
|
D601 v0.3 当前已具备用户 billing summary、admin usage/ledger filter、CSV export、manual credit audit、redeem code 管理、用户兑换和 payment/subscription `unconfigured` 占位；本课题在该基线上定义真实支付 provider、订阅和增长活动接入前后的边界。
|
|
|
|
### 2.2 范围内
|
|
|
|
- 用户 billing summary、余额、plan、entitlement、reservation、usage 和 ledger 摘要。
|
|
- admin usage/ledger 查询、过滤、分页、导出和运营对账。
|
|
- admin credit adjust、operator、reason、idempotency、before/after 和审计显示。
|
|
- redeem code 创建、list、disable、redemption 查询和兑换入账。
|
|
- subscription/payment provider-agnostic 占位、真实 provider 接入边界、订单和回调状态的账本落点。
|
|
|
|
### 2.3 范围外
|
|
|
|
- 余额、reservation、usage 和 ledger 真相归 [PJ2026-010504 计量账本](PJ2026-010504-metering-ledger.md)。
|
|
- plan、entitlement 和 quota 解释归 [PJ2026-010503 权限配额](PJ2026-010503-access-quota.md)。
|
|
- 页面布局、筛选控件和下载交互归 [客户端](PJ2026-0104-client.md)。
|
|
- 真实 payment provider 的 Secret 同步、回调公开入口和运行支撑归 [平台运维](PJ2026-0106-platform-ops.md)。
|
|
|
|
## 3. 术语表
|
|
|
|
| 术语 | 定义 |
|
|
| --- | --- |
|
|
| billing summary | 用户可见的余额、plan、quota、usage、ledger 和 reservation 摘要。 |
|
|
| admin usage | 管理员按用户、服务、资源、API key、时间和状态查询的 usage 视图。 |
|
|
| admin ledger | 管理员按用户、来源、动作、状态和幂等 key 查询的 credit ledger 视图。 |
|
|
| redeem code | 管理员生成、用户兑换、可限制次数和状态的充值凭证。 |
|
|
| payment placeholder | 没有真实 provider 配置时明确返回的未配置支付状态。 |
|
|
| operator audit | 管理员写操作的操作人、原因、幂等、前后余额和时间摘要。 |
|
|
|
|
## 4. 系统边界和接口
|
|
|
|
本规格把账单后台作为用户管理的运营视图和操作层看待；本章只描述输入、输出和责任边界。
|
|
|
|
| 边界项 | 内容 |
|
|
| --- | --- |
|
|
| 外部使用者 | 普通用户、平台管理员、运营人员、Cloud Web、CLI、HTTP API。 |
|
|
| 外部输入 | billing summary 查询、admin usage/ledger filter、credit adjust 请求、redeem code 管理、redeem 请求、payment/subscription 状态请求。 |
|
|
| 受控资源 | billing summary、admin usage view、admin ledger view、CSV export、redeem code、redemption、manual adjust 和 payment/subscription 状态摘要。 |
|
|
| 外部输出 | 用户账单摘要、运营过滤结果、导出文件、调账结果、兑换结果、redemption/ledger 关联和 provider 未配置状态。 |
|
|
| 用户接口 | Cloud Web billing/admin billing 页面、HTTP API、`hwlab-cli` 管理命令。 |
|
|
| 系统边界 | 账单后台负责运营查询和受控写操作入口；不创建第二账本，不直连内部数据库替代 user-billing authority。 |
|
|
|
|
## 5. 内部分工与规格索引
|
|
|
|
| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
|
|
| --- | --- | --- | --- | --- | --- |
|
|
| PJ2026-01050501 | 用户账单 | 本规格 6.1 | 用户 billing summary 和 quota/ledger 摘要 | 计量账本、权限配额 | 客户端、CLI |
|
|
| PJ2026-01050502 | 管理查询 | 本规格 6.2 | admin usage/ledger filter/export | 计量账本、账号权限 | 运营对账 |
|
|
| PJ2026-01050503 | 调账兑换 | 本规格 6.3 | manual adjust、redeem code 和 redemption | 计量账本、admin 权限 | 用户充值、运营支持 |
|
|
| PJ2026-01050504 | 支付订阅 | 本规格 6.4 | payment/subscription placeholder 和真实 provider 边界 | 平台配置、计量账本 | 后续商业化 |
|
|
|
|
## 6. 原子需求
|
|
|
|
### 6.1 USER-BILL-REQ-001 用户账单摘要
|
|
|
|
| 编号 | 短名 | 主责模块 | 关联模块 |
|
|
| --- | --- | --- | --- |
|
|
| USER-BILL-REQ-001 | 用户账单 | PJ2026-01050501 用户账单 | [计量账本](PJ2026-010504-metering-ledger.md)、[权限配额](PJ2026-010503-access-quota.md)、[客户端](PJ2026-0104-client.md) |
|
|
|
|
账单后台应提供用户账单摘要，使用户能查看余额、保留额度、plan、entitlement、quota、usage、ledger 和 reservation 状态。
|
|
|
|
用户账单摘要只聚合用户管理事实，不在客户端或 Cloud API 中创建平行余额、quota 或 ledger。
|
|
|
|
账单后台是 canonical principal 之后的业务消费面，不是 Web 登录态的来源。浏览器身份是否成立由账号会话和 `/auth/session` 证明；账单后台只能基于后端传入的 principal 查询或返回 billing capability、summary 和 blocker。`billing=unlinked`、`billing=unavailable`、provider 未配置或 user-billing 暂时不可达时，应返回结构化业务状态，不得要求前端补 user-billing token、API key 或 cookie prefix 来重新定义登录。
|
|
|
|
### 6.2 USER-BILL-REQ-002 管理查询与导出
|
|
|
|
| 编号 | 短名 | 主责模块 | 关联模块 |
|
|
| --- | --- | --- | --- |
|
|
| USER-BILL-REQ-002 | 管理查询 | PJ2026-01050502 管理查询 | [计量账本](PJ2026-010504-metering-ledger.md)、[租户隔离](PJ2026-010506-tenant-isolation.md) |
|
|
|
|
账单后台应提供 admin usage 和 ledger 的过滤、分页和导出能力，使管理员可以按时间、用户、服务、资源、API key、状态、来源和幂等关系做运营对账。
|
|
|
|
导出内容必须与当前 filter 一致，并排除 session token、API key secret、password hash、DB DSN 和 provider token 等敏感值。
|
|
|
|
### 6.3 USER-BILL-REQ-003 调账与兑换
|
|
|
|
| 编号 | 短名 | 主责模块 | 关联模块 |
|
|
| --- | --- | --- | --- |
|
|
| USER-BILL-REQ-003 | 调账兑换 | PJ2026-01050503 调账兑换 | [计量账本](PJ2026-010504-metering-ledger.md)、[APIKey](PJ2026-010502-api-key.md) |
|
|
|
|
账单后台应提供 admin credit adjust、redeem code 管理和用户 redeem 能力，使人工充值、运营补偿和兑换码入账可以进入同一 ledger。
|
|
|
|
调账和兑换必须保留 operator、reason、idempotency、before/after、redemption 或 code 摘要，并防止一次性 code 或重复幂等 key 产生重复入账。
|
|
|
|
### 6.4 USER-BILL-REQ-004 支付与订阅边界
|
|
|
|
| 编号 | 短名 | 主责模块 | 关联模块 |
|
|
| --- | --- | --- | --- |
|
|
| USER-BILL-REQ-004 | 支付订阅 | PJ2026-01050504 支付订阅 | [平台运维](PJ2026-0106-platform-ops.md)、[计量账本](PJ2026-010504-metering-ledger.md) |
|
|
|
|
账单后台应在没有真实 provider 配置时明确返回 payment/subscription `unconfigured` 状态，并在 provider 配置齐备后承接订单、回调、订阅状态和 ledger 入账。
|
|
|
|
真实 payment provider 只能通过受控 YAML/sourceRef/Secret sync 和端到端回调验证接入。不得硬编码 provider、手工写 Secret、临时 SQL 入账或在 Cloud API 中维护平行 payment ledger。
|