CaiWuXiTong/docs/得物完整账单取数方案留档.md

得物完整账单取数方案留档

目标

财务平台“账单流水数据 / 店铺收款账户账单 / 得物账户”以聚胜算导出的平台原始账单为权威来源，不再回退到 rpt.jst_originalBillInfo 或其得物辅助镜像。

页面现有表头和列顺序保持不变，完整保留以下渠道：

• 得物
• 退货退款订单
• 扣减其他费用明细

Dewubzj 保证金不属于本账单文件，不混入得物收支账单。

权威文件

来源固定为聚胜算“处理 / 平台原始账单（新） / 得物”导出的 XLSX。导入要求标准表头完整存在：

记录编码、订单号、线上单号、自定义备注、账单项目、店铺、订单类型、商品名称、商品货号、数量、渠道、业务类型、收入金额、支出金额、线上单号对应实际店铺、订单创建时间、支付/退款时间、发货/退货时间、结算状态、收款账期、拉取时间、修改时间、修改人。

得物文件没有单独“金额”列，系统以 收入金额 - 支出金额 计算净额。账期以“发货/退货时间”为主；该字段为空时才使用“支付/退款时间”。两个原始时间字段均单独保存，页面不会伪造支付/退款时间。

数据表

共享业务镜像库保存三张专用表：

• dewu_settlement_bill_imports：源文件名、SHA-256、账期、预期和实际控制数、渠道计数、状态。
• dewu_settlement_bill_staging：当前导入代次的暂存数据。
• dewu_settlement_bill_rows：页面和导出读取的权威正式数据。

页面 Repository 只读 dewu_settlement_bill_rows。尚未成功导入时返回明确的 503，不回退旧镜像。

导入控制

导入前必须同时提供账期、行数、收入和支出控制数：

php artisan dewu-bills:import-authoritative /protected/path/dewu.xlsx \
  --from=2026-08-01 \
  --to=2026-08-31 \
  --expected-count=68449 \
  --expected-income=1236493.96 \
  --expected-expense=634104.33

导入必须满足：

1. 文件为可读 XLSX，标准表头完整。
2. 记录编码非空且在同一文件中唯一。
3. 每行渠道非空，账单时间非空且位于指定账期。
4. 实际行数、收入、支出与权威控制数完全一致。
5. 同一 SHA-256 已成功导入时幂等跳过；同一文件使用不同账期或控制数时拒绝。
6. 先写暂存表并完成核验，再在事务内替换指定账期；任何失败均保留上一版正式数据。

每日运行

每日北京时间 08:00 处理前一自然日已生成的得物完整账单，不处理当天数据。自动任务必须先归档源文件并记录 SHA-256 与控制数，再调用受控导入命令。源文件未生成、下载失败、会话失效、控制数不一致、生产连接不可用或迁移未完成时停止，不使用旧镜像补数。

上线前需单独完成生产备份、迁移授权、发布以及首次导入授权。回滚时使用已归档的上一版源文件及其控制数重新导入相同账期。