包花厂集采开发文档

结论

集采拆在两个服务里：

• 运营端 xm-bulky-mall-admin/app：采购计划（发布、追加、撤回、终止）、自动定采、运营看单 / 改量 / 处理超量 / 取消、包花厂商品管理、需求推进定时任务。
• 供应商端 xm-bulky-mall-supplier：供应商报价、仓库 PDA 作业（签到、打印、扫码、盘点）、超量处理、唯一的结算记账实现、自动结算与自动取消任务。

运营后台的「手动结算」不在 admin 里记账，而是签发 60 秒一次性凭证，经 Feign 调 supplier 内部接口，由 BulkPurchaseSettleServiceImpl 统一记账。两端操作同一批表，并发靠「Redis 锁 + 带状态条件的 UPDATE」双保险。

业务口径（给产品 / 测试 / 现场看的版本）见 包花厂集采业务逻辑。本篇讲代码在哪、怎么串、改的时候要注意什么。

代码入口

路径前缀：

• admin：xm-bulky-mall-admin/app/src/main/java/com/xunmeng/xmbulkymalladmin/
• supplier-core：xm-bulky-mall-supplier/supplier-core/src/main/java/com/xunmeng/xmbulkymallsupplier/suppliercore/
• supplier-api：xm-bulky-mall-supplier/supplier-api/src/main/java/com/xunmeng/xmbulkymallsupplier/supplierapi/

仓库内已有的历史资料在 xm-bulky-mall-admin/docs/（bulk-purchase-tech-design.md、bulk-purchase-api-admin.html、bulk-purchase-api-supplier.html、bulk-purchase-admin-settle-over-frontend.md、DDL 在 docs/sql/2026-09-*-bulk-purchase-*.sql）。

接口清单

全部是 POST。两个服务都有 /bulkPurchase 前缀，但网关、鉴权不同，不要混用地址。

运营后台（admin）

供应商小程序（supplier-api）

仓库 PDA（supplier-api）

内部接口

关键常量

枚举值（计划 05、供货单 10/20/30/40/90、标签 10/30/90、范围 16、超量类型 1/2、补偿方式 1/2/3）见 包花厂集采业务逻辑 的「主流程」和各规则章节。补充只在代码里出现的：

状态流转与写入条件

所有状态推进都是带旧状态条件的 UPDATE，affected=0 视为被并发抢先，回滚或返回失败。改代码时不要去掉这些条件。

扫码事务

BulkPurchaseWmsLogic#scan 在一个事务里：查标签 → 跨单校验 → 拿盘点锁 → 重读标签 → 作废 / 状态校验 → 占用人校验 → 解析商品映射 → occupyForScan → 等级扫码数 +1 → 整单产出 +1 → 商品 remain_stock、max_stock +1 → 商品日志 / 分类聚合；开放平台库存推送在事务提交后执行。

• 失败流水 bulk_purchase_scan_reject_log 一律记在当前作业单（expectOrderId）下，便于按单查扫码明细。
• 非占用人扫码是前置条件错误，直接抛异常，不写失败流水。
• 撤销扫码扣库存时把 remain_stock >= 1 写进条件，不够扣说明已售出，整次撤销回滚。

提交盘点

不信任扫码时的累加值，提交时按 bulk_purchase_order_rank.scanned_label_num 重算 actual_label_num、settle_label_num、amount、total_amount，作废未扫标签，写 plan_settle_time = now + 3 天，actual > confirm 时置 over_flag=1。最后走带 SET inventory_by = NULL 的 SQL 释放占用（MyBatis-Plus 默认不更新 null 字段）。

自动定采

BpConfirmLogic#autoConfirm：读当前版本报价 → BpAutoConfirmAlgorithm.allocate(需求含追加, 候选, 5) → 报价定性（中选 / 未中选）→ 每个中选供应商一张供货单（冻结各等级单价，生成 JC 货架码）→ 计划直接 finishConfirmedDemand 为已完成；没有中选则关闭（closeReason=3）。货架码序号在 Redis bp:shelf:seq:，定采按需求加锁 bp:confirm:lock:（30 秒）。

算法排序：价格升序 → 提交时间升序 → 供应商 ID 升序（第三级保证同一数据跑两次结果一致）。永不超采、可能少采，缺口写进 traces。

并发控制

资金类操作的固定顺序：先 getById 拿 demandId → 加资金锁 → getByIdForUpdate 重读并校验 demandId 未变。事务隔离级别 READ_COMMITTED，避免拿锁后读到旧快照。

定时任务

• 三个步骤各自 try/catch，一步失败不影响其他步。
• 待定采过了采集截止就不再重试：此时生成的供货单会立刻被自动取消任务取消。日志 集采需求卡在待定采且已过采集截止，需人工处理。
• 自动结算单张独立事务，乐观锁冲突的单留在待结算等下一轮。

跨服务手动结算

运营后台 POST /bulkPurchase/order/settle/manual
  └─ BpOrderSettleLogic：校验后台登录态，生成 UUID 凭证
       Redis SET bp:settle:admin-ticket:{uuid} = {orderId, remark, operatorId, operatorName}  EX 60
  └─ Feign POST /internal/bulkPurchase/order/settle/manual  Header X-Bp-Admin-Settle-Ticket: {uuid}
       └─ BulkPurchaseAdminSettleLogic：Lua 原子 GET+DEL 消费凭证（防重放）
            └─ BulkPurchaseSettleServiceImpl#settleManual(..., END_ADMIN)

• 操作人来自凭证，supplier 不接受客户端自报的操作人。
• admin 与 supplier 必须连同一个 Redis 库，否则凭证永远「无效或已过期」。
• Feign 异常不打印内容（可能带凭证）。调用超时不代表没结算，先查订单和账变。

记账流程

BulkPurchaseSettleServiceImpl#settle：

1. 自动路径再挡一次 over_flag=1（兜底）。
2. 金额 ≤ 0：直接置已结算、写审计、提交后发通知，不产生账变。
3. 供货方 increaseAccountMoney（乐观锁，冲突抛「操作冲突，请刷新后重试」）→ 写 95 账变。
4. 发布主体 decreaseAccountMoney，不校验余额，允许负数 → 写 96 账变（金额为负）。
5. finishSettle 带 status=30 + total_amount 条件置 40，失败抛异常回滚。
6. 写审计 settle / settleManual；afterCommit 发消息（类型 14，FACTORY_ORDER_COMPLETED，只发给供货方）。

数据表

只读核查 SQL

先确认连的是哪个环境，再按单号 / ID 精确查询。以下只提供 SELECT，不提供生产修改语句。

供货单与等级

SELECT id, order_no, demand_id, demand_no, quote_id,
       supplier_id, publish_supplier_id, round_no, status,
       confirm_label_num, actual_label_num, settle_label_num, total_amount,
       over_flag, over_handle_time, over_handle_remark,
       inventory_by, inventory_submit_time, output_end_time,
       plan_settle_time, settle_time, settle_flag, settle_type
FROM bulk_purchase_order
WHERE order_no = '替换为完整供货单号';

SELECT order_id, rank_code, price, confirm_label_num,
       printed_label_num, scanned_label_num, settle_label_num, amount
FROM bulk_purchase_order_rank
WHERE order_id = 123456
ORDER BY rank_code;

核对顺序：

1. actual_label_num = Σ 等级 scanned_label_num；
2. settle_label_num = Σ 等级 settle_label_num；
3. total_amount = Σ（等级 settle_label_num × price）。

被登记补款的目标单，应结算数可能大于扫码数，属正常。

标签与扫码失败

SELECT id, label_code, order_id, rank_code, seq_no, status,
       product_id, scan_by, scan_time, revoke_count, void_time, void_reason
FROM bulk_purchase_label
WHERE order_id = 123456
ORDER BY rank_code, seq_no;

SELECT label_code, order_id, rank_code, reject_reason, fail_msg,
       first_scan_time, operator_name, create_time
FROM bulk_purchase_scan_reject_log
WHERE order_id = 123456
ORDER BY id DESC
LIMIT 100;

补偿、账变、审计

SELECT order_id, order_no, occupied_order_id, occupied_order_no,
       occupied_supplier_id, rank_code, occupied_label_num,
       price, compensate_type, compensate_amount, handler_name, create_time
FROM bulk_purchase_over_compensate
WHERE order_id = 123456 OR occupied_order_id = 123456
ORDER BY id;

SELECT supplier_id, type, order_sn, old_money, money, new_money, create_time
FROM xm_bulky_supplier_account_change
WHERE order_sn = '替换为完整供货单号'
  AND type IN (95, 96)
ORDER BY id;

SELECT biz_type, biz_id, biz_no, action, before_value, after_value,
       reason, operator_end, operator_name, create_time
FROM bulk_purchase_audit_log
WHERE biz_no = '替换为完整供货单号'
ORDER BY id;

正金额结算应有一条 95 + 一条 96。只有单边、同单号多次入账、金额与订单不一致时，保留查询结果和时间线升级，不要自行冲正。

日志与审计关键词

按 traceId、demandNo、orderNo、orderId 搜对应服务日志。

审计 action：publish、appendNum、appendSupplier、quoteExpire、autoConfirm、finishCollect、submitQuote、updateQuote、adjustPrice、checkIn、normal_print、reprint、revokeScan、submitInventory、updateSettleNum、handleOver、overCompensateIn、settle、settleManual、cancel。

配置与依赖

联调注意与已知坑