pikasTech-unidesk/project-management/PJ2026-01/specs/PJ2026-010505-billing-admin.md

PJ2026-010505 账单后台

修改历史

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

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

正文

PJ2026-010505 账单后台需求规格

1. 文档控制

字段	内容
编号	PJ2026-010505
短名	账单后台
层级	L2 课题
状态	已生效
需求规格模板	ISO/IEC/IEEE 29148 需求规格模板
上级规格	PJ2026-0105 用户管理
规格治理索引	规格治理

本文采用 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 计量账本。
• plan、entitlement 和 quota 解释归 PJ2026-010503 权限配额。
• 页面布局、筛选控件和下载交互归 客户端。
• 真实 payment provider 的 Secret 同步、回调公开入口和运行支撑归 平台运维。

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 用户账单	计量账本、权限配额、客户端

账单后台应提供用户账单摘要，使用户能查看余额、保留额度、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 管理查询	计量账本、租户隔离

账单后台应提供 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 调账兑换	计量账本、APIKey

账单后台应提供 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 支付订阅	平台运维、计量账本

账单后台应在没有真实 provider 配置时明确返回 payment/subscription unconfigured 状态，并在 provider 配置齐备后承接订单、回调、订阅状态和 ledger 入账。

真实 payment provider 只能通过受控 YAML/sourceRef/Secret sync 和端到端回调验证接入。不得硬编码 provider、手工写 Secret、临时 SQL 入账或在 Cloud API 中维护平行 payment ledger。