shanxia2.0/openspec/changes/pl-dibang-plan-quantity-accumulation/design.md

地磅月计划量运输联动累加与回减 — 设计

日期: 2026-07-11
OpenSpec: openspec/changes/pl-dibang-plan-quantity-accumulation/
前置: docs/superpowers/specs/2026-06-20-pl-arrange-dibang-design.md

目标

当月同维度（租户 + 业务类型 + CRM 产品 + 规格 + 往来单位）的地磅月计划，planned_quantity 应等于所有仍有效的运输地磅联动贡献之和；取消或调整运输作废联动时同步回减。

核心决策

#	决策	说明
D1	贡献量记账	pl_transport_db_link.contributed_qty（吨）为单次联动写入量；回减以该字段为准
D2	贡献量来源	创建 link 时取 _product_quantity(product)，优先级：quantity → inbound_estimate_qty → outbound_estimate_qty → 0
D3	累加时机	_sync_transport_inventory_links 在创建/复用月计划后 += contributed_qty
D4	回减时机	revoke_regeneratable_dibang_for_transport 在软删 link 前 -= contributed_qty；planned_quantity = max(0, value)
D5	调整运输	复用 arrange 流程：先 revoke（回减）→ 再 sync（累加新贡献）；净效果等同「先减旧再加新」
D6	取消计划	cancel_plan 已调用 revoke；回减逻辑集中在 revoke，cancel 无需改入口
D7	阻断不变	出入库单已关联磅单或状态不可作废时，整单阻断；月计划量不变
D8	月计划保留	回减至 0 不删除 db_purchase_plan 行

数据流

安排运输 (generateDibangPlan=true)
  → 每产品行:
      find_monthly_db_plan
        ├─ 无 → create plan, planned_qty = contrib
        └─ 有 → planned_qty += contrib
      create inventory + link(contributed_qty=contrib)

调整运输
  → revoke_regeneratable (每条 link: planned_qty -= contributed_qty)
  → sync_dibang (同上累加)

取消计划
  → revoke_regeneratable (同上回减)

数据库变更

ALTER TABLE pl_transport_db_link
  ADD COLUMN contributed_qty DECIMAL(15,3) NULL COMMENT '本次联动贡献量（吨）' AFTER db_inventory_id;

历史数据：contributed_qty 为 NULL 时，回减 fallback 读取关联 db_inbound_outbound.quantity（作废前）。

影响面

文件	变更
docs/sql/pl_tables.sql	基线 DDL
docs/sql/20260711_pl_transport_db_link_contributed_qty.sql	增量迁移
backend/app/models/pl_models.py	ORM 字段
backend/app/services/pl_dibang_bridge_service.py	累加/回减辅助函数
backend/tests/test_pl_dibang_plan_quantity.py	新建 单元测试

前端无需改动（行为对用户透明）。

风险与处理

风险	处理
历史 link 无 contributed_qty	回减时 fallback inventory.quantity
扣减后 planned_quantity < executed_quantity/1000	不回写 executed_quantity；执行状态由 weighing_logic 按现有规则重算
手工创建的月计划基础量	运输联动仅在既有 planned_quantity 上累加/回减，不区分手工基数（本期接受）