PRD: User Billing Reconciliation (UserBillingReconciliation)

状态区

• 文档状态：Implemented
• 优先级：P1
• 建议目录：planning/backlog/active/feat-12-user-billing-reconciliation/PRD.md
• 当前阶段：runtime write path and dashboard summary are already in mainline, but acceptance and indexing are still being backfilled
• 最后更新日期：2026-04-13

Summary

本 feature 用于把用户账单对账能力从“只有离线脚本核对”收口为“有结构化对账结果、可追踪差异来源、可在后台查看摘要”的统一能力。

当前代码基线里，账单流水抓取、对账结果写入和后台摘要页都已经出现明确实现信号，但验收文档、索引与迁移动作还没有完全追平，因此本条 feature 暂保持在 active/ 目录并标记为 Implemented。

背景

当前系统已经具备：

• 用户账单流水采集
• 周期性对账任务
• 差异明细持久化
• 后台摘要页基础展示

但这些能力仍分散在脚本、数据库结果和页面片段中，缺少一条统一的 feature 真源来定义边界与完成标准。

问题定义

1. 对账能力已经部分进入主线，但缺少正式的 feature 边界说明。
2. 后台虽然能看到部分摘要，但“差异类型”和“最近失败原因”的口径还不稳定。
3. 索引、迁移说明和后台展示之间仍存在局部术语歧义。

目标

• 把账单对账能力收口成一条正式 backlog feature
• 明确结构化对账结果、后台摘要与差异分类的目标态
• 允许实现先于文档时，通过 Implemented 状态维持稳定口径

成功标准

• 主 PRD、执行计划、验收清单和决策记录边界清晰
• 对账结果字段、后台摘要和迁移说明口径一致
• feature 收口完成后可以整体迁入 accepted/

非目标

• 不在本轮新增新的账单来源
• 不在本轮引入自动修复差异的工作流
• 不把历史离线脚本全部重写为在线任务

方案概览

1. 对账结果结构化

统一对账结果真源，确保差异类型、周期、来源和摘要字段有稳定定义。

2. 后台摘要收口

后台页只承载摘要和定位入口，不替代明细诊断视图。

3. 文档与迁移同步

把 backlog 文档、迁移说明和命名边界同步到同一口径。

验收标准

• 管理者能从 PRD 看清 feature 边界
• 验收清单能独立反映交付结果
• 局部命名议题以决策记录处理，而不是新开 backlog 编号

依赖与边界

• 依赖既有账单流水采集和对账结果存储
• 与“账单导出”类 feature 保持边界，不在本条里混入导出格式设计
• 局部命名结论见 decision-naming-guardrail.md
• 窄范围收尾交接见 handoff-db-patch-hardening.md

验证方式

• 核对后台摘要页口径与 PRD 是否一致
• 核对迁移说明是否使用统一术语
• 核对验收清单是否仍是验收面板，而非实施步骤