This commit is contained in:
zlwu committed 2026-07-12 12:04:43 +08:00
1 parent 7b1d4c8729
commit ffc89d9b57
75 files changed
+12263 -7950

No files matched your search

@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-07-11
@@ -0,0 +1,69 @@
# 地磅月计划量运输联动累加与回减 — 设计
> **日期**: 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` 上累加/回减,不区分手工基数(本期接受) |
@@ -0,0 +1,29 @@
## Why
运输计划勾选「生成地磅单」联动地磅月计划时,当前实现仅在**首次创建**月计划时写入 `planned_quantity`,**复用**已有月计划时不更新计划量;取消计划或调整运输作废旧联动时也不回减。导致同月同往来单位、同产品多次运输后,月计划量与真实运输需求不一致。
## What Changes
- `pl_transport_db_link` 新增 `contributed_qty`(吨),记录单次运输联动对月计划的贡献量
- 安排运输勾选地磅时:新建月计划 `planned_quantity = 贡献量`;复用月计划 `planned_quantity += 贡献量`
- 调整运输、取消计划作废旧联动时:`planned_quantity -= contributed_qty`(下限 0)
- 调整运输重建联动时:先回减旧贡献、再按新产品数量累加新贡献
- 新增/补充单元测试覆盖累加、调整、取消三条路径
## Capabilities
| Capability | Spec |
|------------|------|
| 地磅月计划量运输联动累加与回减 | `specs/dibang-plan-quantity/spec.md` |
## Non-goals
- 不修改地磅磅单(`db_weighing_slip`)生成逻辑
- 不自动重算或回写 `executed_quantity`(仍由磅单业务逻辑维护)
- 不删除 `planned_quantity = 0` 的月计划记录
- 不改变「已关联磅单 / 已完成出入库单阻断作废」的现有门禁
## Dependencies
- 现有 `pl_dibang_bridge_service.py`、`POST /transport/order/arrange/{plan_id}`、`POST /transport/plan/{id}/cancel`
- 前置设计:`docs/superpowers/specs/2026-06-20-pl-arrange-dibang-design.md`
@@ -0,0 +1,84 @@
# Dibang Plan Quantity (地磅月计划量运输联动)
## ADDED Requirements
### Requirement: 运输联动地磅月计划量累加
当运输计划安排运输且勾选「生成地磅单」(`generateDibangPlan=true`)时,系统 SHALL 按产品行联动地磅月计划,并按运输计划产品数量更新月计划 `planned_quantity`(单位:吨)。
贡献量 SHALL 取自 `pl_plan_product`,优先级为:`quantity` → `inbound_estimate_qty` → `outbound_estimate_qty` → `0`。
月计划匹配维度 SHALL 与现有 `find_monthly_db_plan` 一致:同租户、同业务类型(入库/出库)、同 CRM `product_id`、同 `specification`、同 `customer_name`(往来单位),且计划有效期与运输计划地磅日期所在自然月相交。
#### Scenario: 首次联动创建月计划
- **GIVEN** 当月不存在匹配的地磅月计划
- **WHEN** 运输计划 A(往来单位 B、产品 C)勾选生成地磅单且产品数量为 30 吨
- **THEN** 系统 SHALL 创建地磅月计划
- **AND** `db_purchase_plan.planned_quantity` SHALL 为 `30`
- **AND** 系统 SHALL 创建出入库单与 `pl_transport_db_link`
- **AND** `pl_transport_db_link.contributed_qty` SHALL 为 `30`
#### Scenario: 后续联动累加月计划
- **GIVEN** 当月已存在匹配的地磅月计划且 `planned_quantity` 为 `30`
- **WHEN** 运输计划 B(同往来单位 B、同产品 C)勾选生成地磅单且产品数量为 31 吨
- **THEN** 系统 SHALL 复用该地磅月计划(不新建第二条同维度月计划)
- **AND** `db_purchase_plan.planned_quantity` SHALL 更新为 `61`
- **AND** 系统 SHALL 新建出入库单与 `pl_transport_db_link`,`contributed_qty` 为 `31`
---
### Requirement: 调整运输时地磅月计划量回减与重建
当用户对已安排运输的计划执行「调整运输」且该运输单此前存在地磅联动时,系统 SHALL 在重建联动前作废仍可作废的出入库单与关联,并回减对应月计划贡献量;若本次仍勾选生成地磅单,系统 SHALL 按当前计划产品数量重新累加贡献量。
#### Scenario: 调整运输变更数量
- **GIVEN** 运输计划 A 已联动地磅,月计划 `planned_quantity` 为 `30`,`pl_transport_db_link.contributed_qty` 为 `30`
- **WHEN** 用户对计划 A 执行调整运输,勾选生成地磅单,且产品数量变更为 `25` 吨
- **THEN** 系统 SHALL 作废旧出入库单与关联,并将月计划 `planned_quantity` 回减为 `0`
- **AND** 系统 SHALL 创建新出入库单与关联,`contributed_qty` 为 `25`
- **AND** 月计划 `planned_quantity` SHALL 为 `25`
#### Scenario: 调整运输取消勾选地磅
- **GIVEN** 运输计划 A 已联动地磅,月计划 `planned_quantity` 为 `30`
- **WHEN** 用户对计划 A 执行调整运输且**未**勾选生成地磅单
- **THEN** 系统 SHALL 作废旧出入库单与关联,并将月计划 `planned_quantity` 回减为 `0`
- **AND** 系统 SHALL NOT 创建新的地磅联动记录
#### Scenario: 调整运输被阻断
- **GIVEN** 运输计划 A 的联动出入库单已关联有效地磅磅单,或出入库单状态不在 `{待入库, 待出库, 待三方填写, 待处理}`
- **WHEN** 用户对计划 A 执行调整运输
- **THEN** 系统 SHALL 拒绝操作并提示需在地磅管理中先处理
- **AND** 月计划 `planned_quantity` SHALL 保持不变
---
### Requirement: 取消计划时地磅月计划量回减
当用户取消运输计划且该计划关联的运输单存在地磅联动时,系统 SHALL 作废仍可作废的出入库单与关联,并从对应地磅月计划回减贡献量。
#### Scenario: 取消计划回减月计划量
- **GIVEN** 运输计划 A(30 吨)与运输计划 B(31 吨)均已联动同一地磅月计划,`planned_quantity` 为 `61`
- **WHEN** 用户取消运输计划 A
- **THEN** 系统 SHALL 软删计划 A 的出入库单与 `pl_transport_db_link`
- **AND** 地磅月计划 `planned_quantity` SHALL 更新为 `31`
- **AND** 计划 A 的 `follow_status` SHALL 为 `cancelled`
#### Scenario: 取消计划被阻断
- **GIVEN** 运输计划 A 的联动出入库单已关联有效地磅磅单或状态不可作废
- **WHEN** 用户取消运输计划 A
- **THEN** 系统 SHALL 拒绝取消并提示需在地磅管理中先处理
- **AND** 月计划 `planned_quantity` SHALL 保持不变
#### Scenario: 取消后月计划量下限
- **GIVEN** 仅运输计划 A(30 吨)联动地磅月计划,`planned_quantity` 为 `30`
- **WHEN** 用户取消运输计划 A
- **THEN** 月计划 `planned_quantity` SHALL 为 `0`
- **AND** 系统 SHALL NOT 物理删除该 `db_purchase_plan` 记录
@@ -0,0 +1,23 @@
# Tasks: 地磅月计划量运输联动累加与回减
## 1. Schema 与迁移
- [x] 1.1 编写 `docs/sql/20260711_pl_transport_db_link_contributed_qty.sql`
- [x] 1.2 同步 `docs/sql/pl_tables.sql` 中 `pl_transport_db_link.contributed_qty`
- [x] 1.3 `backend/app/models/pl_models.py` 增加 `PlTransportDbLink.contributed_qty`
## 2. 桥接服务
- [x] 2.1 `pl_dibang_bridge_service.py` 新增 `_apply_plan_quantity_delta`、`_resolve_link_contributed_qty`
- [x] 2.2 `_sync_transport_inventory_links`:复用月计划时 `+= contributed_qty`;写入 link.contributed_qty
- [x] 2.3 `revoke_regeneratable_dibang_for_transport`:作废前 `-= contributed_qty`(下限 0)
## 3. 测试
- [x] 3.1 新建 `backend/tests/test_pl_dibang_plan_quantity.py`
- [x] 3.2 覆盖:累加、回减、阻断(本地 venv 损坏,已用 python3 手工验证核心路径)
## 4. 验收
- [ ] 4.1 本地 pytest 通过(需修复 venv 或 `pip install pytest`)
- [ ] 4.2 手工:A(30)+B(31)→61;取消 A→31;调整 A 30→25→净 25