erpnew/docs/external_finance_sync.md

外部财务同步设计

本文档记录 ReceiptOrder 对接 HaoBuYe 外部财务 API 的当前实现口径，以及后续批量同步的预备方案。

1. 当前已实现能力

• 单客户同步命令：python manage.py sync_external_customer_finance <客户名> --operator-id <Employee.id>
• 仅同步到 business.ReceiptOrder
• PaymentOrder 当前不参与外部财务同步
• 命令完成后，会继续同步该客户的外部 sale / sale_return 业务记录，用于对账单计算

1.0 使用前前置条件

在首次使用前，需要确认以下条件：

• 已完成数据库迁移，使 ReceiptOrder / PaymentOrder 拥有 is_external_source 与 external_source_id 字段
• 已配置外部 API 访问参数：HAOBUYE_API_BASE_URL、HAOBUYE_API_AUTHORIZATION
• 已确定一个本地经办人 Employee.id，用于创建并审批同步产生的 ReceiptOrder

推荐执行：

python manage.py migrate

如果只想确认本次相关迁移，也可以先查看：

python manage.py showmigrations business

本次同步依赖的迁移文件为：

• business.0028_payment_receipt_external_source_fields
• business.0029_externalcustomerstatementorder

1.0.1 外部业务记录的落库策略

外部 sale / sale_return 当前不会落到核心 SalesOrder / SalesReturnOrder，而是落到专用模型：

• business.ExternalCustomerStatementOrder

设计目的：

• 只服务 build_customer_statement(...) 的对账计算
• 避免把外部历史业务单塞进当前 ERP 的库存/审批流程
• 不触发库存出入库
• 不修改持久化的 CustomerBalance

说明：

• 对账单计算时，会把这部分外部业务记录纳入 statement records
• 同时会在 statement 内部临时调整当前余额口径，使“本地收款已同步，但销售历史来自外部”的客户也能得到兼容结果

1.0.2 i-sale 数据实际存放位置

外部 i-sale/by-customer 拉到的 sale / sale_return 数据，当前不会展开成核心 SalesOrder / SalesReturnOrder，而是存到：

• 模型：business.ExternalCustomerStatementOrder

其中关键字段为：

• category：sale 或 sale_return
• external_customer_id：外部客户 ID，例如 KH00308
• external_source_id：外部业务单号，对应 BianHaoID
• occurred_at：业务日期，对应 RiQi
• recorded_at：录单时间，对应 KdRiQi
• total_amount：按同一 BianHaoID 聚合后的金额
• remarks：由外部备注字段整理后的文本备注

明细与扩展信息使用 JSONField 保存：

• items_payload：明细快照，按外部单据的多行 I_Sale 记录聚合后保存
• extra_payload：扩展数据，如 dan_type、raw_count 等

当前 items_payload 中保留的信息包括：

• product_id：若能通过 HpID -> Product.human_id 匹配到本地产品，则写入本地产品 ID；否则为 null
• product_name：优先本地产品名，否则回退为外部 HpID
• quantity
• price
• unit
• spec
• num_of_rolls
• external_sub_id
• external_product_id

1.1 字段映射

收款（SK%）

• BianHaoID -> ReceiptOrder.external_source_id
• FkJinE -> ReceiptOrder.amount
• ZkJinE -> ReceiptOrder.discount_amount
• JieSunFS -> ReceiptOrder.markup
• RiQi（回退 KdRiQi）-> ReceiptOrder.receipt_date

退款（XT%）

• BianHaoID -> ReceiptOrder.external_source_id
• YfJinE -> ReceiptOrder.amount
• discount_amount 固定为 0
• JieSunFS -> ReceiptOrder.markup
• RiQi（回退 KdRiQi）-> ReceiptOrder.receipt_date

说明：

• XT% 当前按负金额 ReceiptOrder 落库，表示客户退款。
• 外部 refund 若结算金额为 0，当前会跳过并记入 summary，不落库。
• 为兼容外部“纯折扣收款”（如 FkJinE=0, ZkJinE>0），同步层直接创建 ReceiptOrder 模型并复用审批逻辑，不走普通创建 API 的 amount != 0 限制。

1.2 幂等规则

• 幂等键：merchant + external_source_id + is_external_source=True
• 若本地已存在同一 external_source_id 且核心字段一致，则跳过
• 若同一 external_source_id 已存在但金额/日期/客户不一致，则报冲突错误，避免静默脏写

外部业务记录（statement-only）使用单独幂等键：

• merchant + category + external_source_id

其中：

• category = sale | sale_return
• external_source_id = BianHaoID

1.3 外部业务单来源字段

命令在同步收款/退款后，会继续调用：

• GET /api/v1/i-sale/by-customer?customer_id=...&category=sale
• GET /api/v1/i-sale/by-customer?customer_id=...&category=sale_return

当前聚合策略：

• 按 BianHaoID 聚合同一张外部业务单
• RiQi -> statement occurred_at
• KdRiQi -> statement recorded_at
• JinE 聚合为外部业务单金额
• HpID 优先匹配本地 Product.human_id
• 若未匹配到本地产品，仍保留 HpID 作为对账单 item 展示标识，不阻塞同步

1.4 已同步客户如何补齐 i-sale 业务依据

对于“已经同步过收款/退款，但当时还没有 i-sale 接口”的客户，不需要删除任何旧数据，也不需要回滚收款单。

正确做法是：

1. 先执行数据库迁移
2. 重新执行同一个单客户同步命令

例如：

python manage.py migrate
python manage.py sync_external_customer_finance "张晓鹏" --operator-id 12 --allow-create-customer

原因：

• 已存在的 ReceiptOrder 会按既有幂等键跳过，不会重复插入
• 缺失的 ExternalCustomerStatementOrder 会被补齐
• 已存在的外部业务来源单，也会按 merchant + category + external_source_id 跳过

因此，补齐老客户时不需要先删除收款/退款数据；“先删再重灌”既不科学，也会增加误删风险。

建议：

• 如果只是想先确认将会补哪些业务依据，可先用 --dry-run
• 如果外部同一 BianHaoID 的核心字段与本地已存快照不一致，命令会报冲突错误，而不是静默覆盖
• 真正需要人工处理的场景，应优先核对外部数据是否修订过，而不是直接删除本地记录

2. 当前命令参数

python manage.py sync_external_customer_finance "张晓鹏" --operator-id 12 --allow-create-customer

参数说明：

• customer_name：外部客户名称，精确匹配
• --operator-id：本地经办人 Employee.id。若不传，则回退使用 HAOBUYE_FINANCE_SYNC_OPERATOR_ID
• --allow-create-customer：本地没有该客户时自动创建；默认关闭
• --dry-run：只校验，不写入；默认关闭

命令行为说明：

• 如果既没有传 --operator-id，也没有配置 HAOBUYE_FINANCE_SYNC_OPERATOR_ID，命令会直接报错退出
• 如果客户不存在且未传 --allow-create-customer，命令会直接报错退出
• 如果外部返回 status=not_found，命令不会写入任何数据，而是返回一份空结果 summary
• 如果本地已存在同一个 external_source_id 且字段一致，会跳过，不会重复插入
• 如果本地已存在同一个 external_source_id 但核心字段不一致，会报冲突错误，避免静默覆盖
• 收款/退款同步完成后，命令会继续同步外部 sale / sale_return 到 ExternalCustomerStatementOrder

常用示例：

# 正式同步
python manage.py sync_external_customer_finance "张晓鹏" --operator-id 12 --allow-create-customer

# 只做拉取和校验，不写入
python manage.py sync_external_customer_finance "张晓鹏" --operator-id 12 --allow-create-customer --dry-run

# 使用环境变量里的默认 operator
python manage.py sync_external_customer_finance "张晓鹏" --allow-create-customer

命令成功后会输出 summary，典型字段包括：

• customer_name
• external_customer_id
• receipts_seen
• refunds_seen
• sales_seen
• sale_returns_seen
• created_count
• skipped_existing_count
• skipped_zero_settlement_count
• external_business_created_count
• external_business_skipped_existing_count
• dry_run_count
• created_receipt_ids
• created_external_business_ids
• skipped_external_ids

对于已同步过财务数据、再次补齐 i-sale 的客户，常见 summary 形态是：

• created_count = 0
• skipped_existing_count > 0
• external_business_created_count > 0

这表示：

• 收款/退款因为已存在而被跳过
• 但外部业务依据（statement-only）被成功补录

也可通过环境变量预配置：

• HAOBUYE_API_BASE_URL
• HAOBUYE_API_AUTHORIZATION
• HAOBUYE_API_TIMEOUT_SECONDS
• HAOBUYE_FINANCE_SYNC_OPERATOR_ID

推荐最小配置示例：

HAOBUYE_API_BASE_URL=http://43.139.183.222:18080
HAOBUYE_API_AUTHORIZATION=your-fixed-authorization-secret
HAOBUYE_API_TIMEOUT_SECONDS=30
HAOBUYE_FINANCE_SYNC_OPERATOR_ID=12

3. 已预留的批量能力

代码中已实现批量入口：

• sync_customer_finance_batch(...)

设计原则：

• 批量模式只负责“枚举客户”
• 单客户同步逻辑完全复用 sync_customer_finance(...)
• 当前尚未暴露为 command / celery / cron

3.1 批量模式预期流程

1. 调用外部 GET /api/v1/customers?cursor_id=...
2. 拿到最多 10 个客户
3. 对每个客户执行 sync_customer_finance(...)
4. 整页处理完毕后再推进 next_cursor_id

3.2 后续建议

• 若进入定时任务阶段，建议将外部 cursor_id 持久化到 api_v1.DataSync
• 若需要失败补偿，建议单独增加 finance failure model，记录 customer_name / external_source_id / run_date / error
• 若前端后续需要区分“收款/退款”，建议在 ReceiptOrder 列表 API 上增加只读过滤参数（例如 amount_sign=positive|negative），而不是新增第二套退款模型