CaiWuXiTong/docs/京东日账单接入.md

京东日账单

店铺收款账户账单的“京东流水”展示胜算“平台原始账单（新）→ 京东商城 → 京东日账单”，以费用结算时间筛选。保留原始记录编码、单据编号、商品、费用发生时间和费用结算时间；日账单没有账户余额，页面第三项汇总为收支净额。

当前来源是胜算完整月份原始导出，尚未接入自动增量接口。页面标明已接入月份与导入时间，不将未导入月份解释为源端无数据。旧库 jd_billFromShop2024 尚未通过完整性核对，不作为正式来源。

平台口径：京东账单与京喜账单

同一份日账单同时支撑「京东账单」和「京喜账单」两个页签，共用取数逻辑、列定义、筛选、排序、分页与导出，只按平台口径拆分数据。日账单导出没有平台字段：单据类型（订单/取消退款单/售后服务单/非销售单）两边都有，费用项、账户代码、京东门店编码、品牌门店编号、门店名称均为空，账单项目只有「直营服务费」单独属于京喜；实测全量 699,447 笔中只有店铺维度可靠区分（京喜 213 个店铺 488,464 笔与京东 46 个店铺 210,983 笔互不重叠，店铺号也不跨两边）。

口径集中定义在 config/jd_bill_platform.php（京喜店铺名关键字、口径切换起始日期），由 Modules\EcommerceFinance\JdBillPlatform 读取，JdDailyBillRepository::forPlatform() 在查询层收窄：京东账单排除京喜店铺，京喜账单只取京喜店铺。两个口径互补，笔数与金额之和恒等于拆分前，底层镜像数据不修改、不删除。

scope_start_date 默认 null（全量历史）；改为某个 Y-m-d 后，该记账日期起的京喜行归入京喜账单，之前的京喜行仍留在京东账单，总数保持守恒。新增第三个小平台时，在同一配置与 JdBillPlatform 中扩展口径即可，不要在各处散写 if-else。

同步及回滚

1. 在胜算按费用结算时间查询完整月份，记录笔数及收入、支出合计；下载该查询的全部异步导出分片。
2. 将原始明细无损转为 UTF-8 CSV，长编号保持文本，金额保持两位小数。原件、CSV、核对证据仅存放私有目录。
3. 备份 jd_daily_bill_periods 和受影响月份旧版本；首次接入记录两表原先不存在。生产同步节点持有 /run/caiwu-upstream-sync.lock 后运行：

php artisan business-mirror:import-jd-daily <CSV路径> <YYYY-MM> --count=<笔数> --income=<收入> --expense=<支出>

导入分批写入共享业务镜像 jd_daily_bill_rows，精确核对笔数、金额、月份、币种、时间格式及记录编码唯一性。全部成功后才原子更新 jd_daily_bill_periods 的有效版本；失败清理本次未启用版本，保留旧数据。状态保存源文件 SHA256 和导入时间。重复导入不会叠加流水。

回滚时在同一互斥锁下恢复备份的月份状态（active_generation），旧版本行保留。首次接入回滚只撤销该月份状态，保留原始文件和镜像用于核查。代码回滚沿用发布脚本保留的上一版本镜像。

验收核对源端和镜像笔数、收支，验证真实页面首页、翻页、店铺和月份筛选、全量导出及耗时。后续自动同步只能在确认完整官方来源及稳定游标后接入，不能拿部分旧表填补未导入期间。