70 lines
3.1 KiB
Markdown
70 lines
3.1 KiB
Markdown
# 地磅月计划量运输联动累加与回减 — 设计
|
||
|
||
> **日期**: 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` 上累加/回减，不区分手工基数（本期接受） |
|