forked from erp-dev/erp
feat: correct first
This commit is contained in:
276
docs/external_finance_sync.md
Normal file
276
docs/external_finance_sync.md
Normal file
@@ -0,0 +1,276 @@
|
||||
# 外部财务同步设计
|
||||
|
||||
本文档记录 `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`
|
||||
|
||||
推荐执行：
|
||||
|
||||
```bash
|
||||
python manage.py migrate
|
||||
```
|
||||
|
||||
如果只想确认本次相关迁移，也可以先查看：
|
||||
|
||||
```bash
|
||||
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. 重新执行同一个单客户同步命令
|
||||
|
||||
例如：
|
||||
|
||||
```bash
|
||||
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. 当前命令参数
|
||||
|
||||
```bash
|
||||
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`
|
||||
|
||||
常用示例：
|
||||
|
||||
```bash
|
||||
# 正式同步
|
||||
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`
|
||||
|
||||
推荐最小配置示例：
|
||||
|
||||
```env
|
||||
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`），而不是新增第二套退款模型
|
||||
Reference in New Issue
Block a user