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

> **日期**: 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 (同上回减)
```

## 数据库变更

```sql
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` 上累加/回减，不区分手工基数（本期接受） |