498 lines
18 KiB
Markdown
498 lines
18 KiB
Markdown
# 运输计划 / 库存列表导出 · 段次×产品行 Implementation Plan
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** 让运输计划列表与库存入库/出库导出的 Excel 行模型对齐列表展平(先装货产品行,再各送货段产品行),每行带「段次」与本段计划量/实际量。
|
||
|
||
**Architecture:** 仍走现有 plan 导出 API;改造 `_build_plan_list_export_rows`,按 `stops_by_plan` 段×产品展开(对齐前端 `flattenPlanArchivePairRows`)。复用归档侧已有语义:`_stop_kind_label` / `_get_stop_archive_actual_qty`(或同名内联)。不改归档配对宽表。
|
||
|
||
**Tech Stack:** Python / FastAPI、pytest、Vue 3(`plan/index.vue` 导出列)
|
||
|
||
**Spec:** `docs/superpowers/specs/2026-10-15-plan-list-segment-export-design.md`
|
||
|
||
---
|
||
|
||
## File map
|
||
|
||
| 文件 | 职责 |
|
||
|------|------|
|
||
| `backend/tests/test_pl_plan_list_export.py` | 段次展开、占位、legacy、列过滤用例 |
|
||
| `backend/app/api/pl/plan.py` | `PLAN_EXPORT_COLUMNS` + `_build_plan_list_export_rows` + stop 字段 helper |
|
||
| `web-admin/src/views/pl/plan/index.vue` | `planExportColumns` 固定注入 `stopSegment`(库存页复用同一组件) |
|
||
|
||
可选(若 `plan.py` 内联过长):`backend/app/services/pl/plan_list_export_rows.py` 抽出展开逻辑;默认优先内联以最小改动为准。
|
||
|
||
---
|
||
|
||
### Task 1: 失败测试 — 一装多送段次展开
|
||
|
||
**Files:**
|
||
- Modify: `backend/tests/test_pl_plan_list_export.py`
|
||
|
||
- [ ] **Step 1: 追加一装多送用例(期望当前失败)**
|
||
|
||
在 `test_pl_plan_list_export.py` 末尾追加(可复用文件内已有 patch 模式):
|
||
|
||
```python
|
||
def test_build_plan_list_export_rows_expands_stop_segments():
|
||
"""一装多送:先装货产品行,再各送货段产品行;侧栏字段按行填写。"""
|
||
plan = SimpleNamespace(
|
||
id="p-multi",
|
||
plan_no="PO20261009016",
|
||
follow_status="arranged",
|
||
plan_date="2026-10-11",
|
||
plan_type="inbound",
|
||
supplier_name="供方",
|
||
customer_name="需方",
|
||
license_plate="皖A12345",
|
||
trailer_no=None,
|
||
driver_name="司机",
|
||
transport_status="arranged",
|
||
archive_status="unarchived",
|
||
erp_entered=0,
|
||
remark="",
|
||
products=[],
|
||
)
|
||
db = MagicMock()
|
||
query = MagicMock()
|
||
db.query.return_value = query
|
||
query.filter.return_value = query
|
||
query.order_by.return_value = query
|
||
# 有段结构时不应依赖计划级产品展开;返回空列表即可
|
||
query.all.return_value = []
|
||
|
||
load_product = SimpleNamespace(
|
||
id="lp1",
|
||
plan_product_id="pp1",
|
||
product_id="prod1",
|
||
product_name="尿素别名",
|
||
model="工业级",
|
||
package_spec="吨袋",
|
||
unit="ton",
|
||
plan_qty=30,
|
||
inbound_qty=29,
|
||
outbound_qty=None,
|
||
brand_mode=None,
|
||
brand_name=None,
|
||
)
|
||
del1_product = SimpleNamespace(
|
||
id="dp1",
|
||
plan_product_id="pp1",
|
||
product_id="prod1",
|
||
product_name="尿素别名",
|
||
model="工业级",
|
||
package_spec="吨袋",
|
||
unit="ton",
|
||
plan_qty=20,
|
||
inbound_qty=None,
|
||
outbound_qty=19,
|
||
brand_mode=None,
|
||
brand_name=None,
|
||
)
|
||
del2_product = SimpleNamespace(
|
||
id="dp2",
|
||
plan_product_id="pp1",
|
||
product_id="prod1",
|
||
product_name="尿素别名",
|
||
model="工业级",
|
||
package_spec="吨袋",
|
||
unit="ton",
|
||
plan_qty=10,
|
||
inbound_qty=None,
|
||
outbound_qty=9,
|
||
brand_mode=None,
|
||
brand_name=None,
|
||
)
|
||
load_stop = SimpleNamespace(
|
||
customer_name="装货客户A",
|
||
address="装货路1号",
|
||
load_time="2026-10-11",
|
||
generate_dibang=1,
|
||
dibang_direction="outbound",
|
||
contracts=[SimpleNamespace(contract_no="HT-L")],
|
||
products=[load_product],
|
||
)
|
||
delivery1 = SimpleNamespace(
|
||
seq=1,
|
||
customer_name="送货客户B1",
|
||
address="送货路B1",
|
||
delivery_time="2026-10-12",
|
||
generate_dibang=1,
|
||
dibang_direction="inbound",
|
||
contracts=[SimpleNamespace(contract_no="HT-B1")],
|
||
products=[del1_product],
|
||
)
|
||
delivery2 = SimpleNamespace(
|
||
seq=2,
|
||
customer_name="送货客户B2",
|
||
address="送货路B2",
|
||
delivery_time="2026-10-13",
|
||
generate_dibang=0,
|
||
dibang_direction=None,
|
||
contracts=[SimpleNamespace(contract_no="HT-B2")],
|
||
products=[del2_product],
|
||
)
|
||
|
||
fake_dump = {
|
||
"planNo": "PO20261009016",
|
||
"belongsCompany": "shanxia",
|
||
"followStatus": "arranged",
|
||
"planDate": "2026-10-11",
|
||
"planType": "inbound",
|
||
"supplierName": "供方",
|
||
"customerName": "需方",
|
||
"licensePlate": "皖A12345",
|
||
"trailerNo": None,
|
||
"personnelSummary": "司机张三",
|
||
"followUserName": "跟进人李四",
|
||
"driverName": "司机",
|
||
"transportStatus": "arranged",
|
||
"archiveStatus": "unarchived",
|
||
"erpEntered": 0,
|
||
"remark": "",
|
||
"products": [],
|
||
}
|
||
|
||
with patch(
|
||
"app.api.pl.plan.PlanWithProducts.model_validate",
|
||
return_value=MagicMock(model_dump=MagicMock(return_value=dict(fake_dump))),
|
||
), patch(
|
||
"app.api.pl.plan.load_crm_product_alias_maps",
|
||
return_value=({"prod1": "尿素"}, {"prod1": ["尿素别名"]}),
|
||
):
|
||
rows = _build_plan_list_export_rows(
|
||
db,
|
||
tenant_no="t1",
|
||
plans=[plan],
|
||
stops_by_plan={"p-multi": (load_stop, [delivery1, delivery2])},
|
||
)
|
||
|
||
assert len(rows) == 3
|
||
assert [r["stopSegment"] for r in rows] == ["装货", "送货 #1", "送货 #2"]
|
||
assert [r["planQty"] for r in rows] == [30, 20, 10]
|
||
assert [r["actualQty"] for r in rows] == [29, 19, 9]
|
||
assert rows[0]["loadCustomer"] == "装货客户A"
|
||
assert rows[0]["deliveryCustomer"] == ""
|
||
assert rows[0]["productContract"] == "HT-L"
|
||
assert rows[1]["loadCustomer"] == ""
|
||
assert rows[1]["deliveryCustomer"] == "送货客户B1"
|
||
assert rows[1]["deliveryTimes"] == "2026-10-12"
|
||
assert rows[1]["productContract"] == "HT-B1"
|
||
assert rows[2]["deliveryCustomer"] == "送货客户B2"
|
||
assert rows[2]["deliveryDibang"] == ""
|
||
assert rows[0]["productName"] == "尿素"
|
||
```
|
||
|
||
- [ ] **Step 2: 运行确认失败**
|
||
|
||
```bash
|
||
cd backend && source venv/bin/activate && pytest tests/test_pl_plan_list_export.py::test_build_plan_list_export_rows_expands_stop_segments -v
|
||
```
|
||
|
||
Expected: FAIL(当前按计划级产品展开,行数/字段不符;或无 `stopSegment`)
|
||
|
||
- [ ] **Step 3: 追加空产品占位与 legacy 用例**
|
||
|
||
```python
|
||
def test_build_plan_list_export_rows_empty_delivery_products_placeholder():
|
||
plan = SimpleNamespace(id="p-empty", plan_no="PL-E", products=[])
|
||
# …同模式 fake_dump / patches…
|
||
load_stop = SimpleNamespace(
|
||
customer_name="装A",
|
||
address="L",
|
||
load_time="2026-10-11",
|
||
generate_dibang=0,
|
||
dibang_direction=None,
|
||
contracts=[],
|
||
products=[
|
||
SimpleNamespace(
|
||
id="lp",
|
||
plan_product_id=None,
|
||
product_id="prod1",
|
||
product_name="尿素",
|
||
model="",
|
||
package_spec="",
|
||
unit="ton",
|
||
plan_qty=5,
|
||
inbound_qty=None,
|
||
outbound_qty=None,
|
||
)
|
||
],
|
||
)
|
||
delivery = SimpleNamespace(
|
||
seq=1,
|
||
customer_name="送B",
|
||
address="D",
|
||
delivery_time="2026-10-12",
|
||
generate_dibang=0,
|
||
dibang_direction=None,
|
||
contracts=[],
|
||
products=[], # 空 → 占位一行
|
||
)
|
||
# stops_by_plan={"p-empty": (load_stop, [delivery])}
|
||
# assert len(rows)==2; rows[1]["stopSegment"]=="送货 #1"; rows[1]["productName"]==""; rows[1]["planQty"] is None
|
||
|
||
|
||
def test_build_plan_list_export_rows_legacy_without_stops():
|
||
"""无段结构:回退计划级产品;stopSegment 为空。"""
|
||
# 复用现有 test_build_plan_list_export_rows_expands_products_with_crm_names 的产品 mock
|
||
# stops_by_plan={"p1": (None, [])} 或缺省
|
||
# assert rows[0]["stopSegment"] == ""
|
||
# assert rows[0]["planQty"] == 10 # 计划级 quantity
|
||
```
|
||
|
||
(实现时把占位/legacy 写成完整可运行断言,勿留注释占位。)
|
||
|
||
- [ ] **Step 4: 运行整文件确认新用例失败、旧用例仍绿或一并待修**
|
||
|
||
```bash
|
||
cd backend && source venv/bin/activate && pytest tests/test_pl_plan_list_export.py -v
|
||
```
|
||
|
||
---
|
||
|
||
### Task 2: 实现列定义与按段 stop 字段 helper
|
||
|
||
**Files:**
|
||
- Modify: `backend/app/api/pl/plan.py`(约 `PLAN_EXPORT_COLUMNS`、`_apply_plan_list_export_stop_fields`)
|
||
|
||
- [ ] **Step 1: `PLAN_EXPORT_COLUMNS` 在 `planNo` 后插入段次**
|
||
|
||
```python
|
||
PLAN_EXPORT_COLUMNS = [
|
||
ExportColumn(title="计划编号", field="planNo"),
|
||
ExportColumn(title="段次", field="stopSegment"),
|
||
ExportColumn(title="归属公司", field="belongsCompany"),
|
||
# …其余保持不变…
|
||
]
|
||
```
|
||
|
||
- [ ] **Step 2: 将整单拼接的 `_apply_plan_list_export_stop_fields` 改为按单侧填写**
|
||
|
||
替换为(或新增并改调用方):
|
||
|
||
```python
|
||
def _format_stop_segment_label(kind: str, delivery_seq: Optional[int] = None) -> str:
|
||
if kind == "load":
|
||
return "装货"
|
||
return f"送货 #{delivery_seq or 1}"
|
||
|
||
|
||
def _apply_plan_list_export_segment_stop_fields(
|
||
data: dict,
|
||
*,
|
||
kind: str,
|
||
load_read: Any = None,
|
||
delivery_read: Any = None,
|
||
delivery_seq: Optional[int] = None,
|
||
) -> None:
|
||
"""按当前导出行所属段填写装/送侧字段;对侧留空。"""
|
||
data["stopSegment"] = _format_stop_segment_label(kind, delivery_seq)
|
||
data["loadCustomer"] = ""
|
||
data["deliveryCustomer"] = ""
|
||
data["loadAddressTime"] = ""
|
||
data["deliveryAddressTime"] = ""
|
||
data["deliveryTimes"] = ""
|
||
data["productContract"] = ""
|
||
data["loadDibang"] = ""
|
||
data["deliveryDibang"] = ""
|
||
|
||
if kind == "load" and load_read is not None:
|
||
data["loadCustomer"] = (getattr(load_read, "customer_name", None) or "").strip()
|
||
data["loadAddressTime"] = _format_stop_address_time(
|
||
getattr(load_read, "address", None),
|
||
getattr(load_read, "load_time", None),
|
||
)
|
||
data["loadDibang"] = _format_stop_dibang_label(load_read)
|
||
data["productContract"] = " / ".join(_collect_stop_contract_nos([load_read]))
|
||
return
|
||
|
||
if kind == "delivery" and delivery_read is not None:
|
||
data["deliveryCustomer"] = (
|
||
getattr(delivery_read, "customer_name", None) or ""
|
||
).strip()
|
||
data["deliveryAddressTime"] = _format_stop_address_time(
|
||
getattr(delivery_read, "address", None),
|
||
getattr(delivery_read, "delivery_time", None),
|
||
)
|
||
data["deliveryTimes"] = _format_export_date_text(
|
||
getattr(delivery_read, "delivery_time", None)
|
||
)
|
||
data["deliveryDibang"] = _format_stop_dibang_label(delivery_read)
|
||
data["productContract"] = " / ".join(
|
||
_collect_stop_contract_nos([delivery_read])
|
||
)
|
||
```
|
||
|
||
可删除或保留旧 `_apply_plan_list_export_stop_fields`(若无引用则删除,避免死代码)。
|
||
|
||
- [ ] **Step 3: Commit(若用户要求提交再执行;否则跳过本步)**
|
||
|
||
```bash
|
||
git add backend/app/api/pl/plan.py backend/tests/test_pl_plan_list_export.py
|
||
git commit -m "$(cat <<'EOF'
|
||
feat(pl): add stopSegment column helpers for list export
|
||
|
||
Prepare segment-scoped stop fields for plan/stock list Excel export.
|
||
EOF
|
||
)"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 3: 重写 `_build_plan_list_export_rows` 段次展开
|
||
|
||
**Files:**
|
||
- Modify: `backend/app/api/pl/plan.py`(`_build_plan_list_export_rows`)
|
||
|
||
- [ ] **Step 1: 实现展开逻辑(最小可用)**
|
||
|
||
核心行为:
|
||
|
||
1. 构建计划公共 `data`(与现有相同:`PlanWithProducts` dump、标签、车牌、ERP 是/否)。
|
||
2. `load_read, delivery_reads = stops_by_plan.get(plan.id, (None, []))`。
|
||
3. **若** `load_read is None and not delivery_reads`:走 **legacy**——查 `products_by_plan`,按计划级产品展开;每行 `stopSegment=""`;`planQty`/`actualQty` 用计划级 `quantity`/`actual_qty`;stop 侧字段清空或留空。
|
||
4. **否则**(有段):
|
||
- 批量加载计划级产品,仅用于品牌 lookup(`plan_product_id` / `product_id` → `brand_mode`/`brand_name`),对齐归档 `_lookup_plan_product` + `_format_plan_list_export_brand`。
|
||
- CRM 别名:收集段产品 `product_id` 调用 `load_crm_product_alias_maps`。
|
||
- 装货:`products = list(load_read.products or []) or [None]`(空则占位);每项一行,`kind=load`。
|
||
- 送货:若 `delivery_reads` 为空,视为 `[None]` 占位一段(与列表 `deliveries.length ? … : [null]` 一致);否则按顺序;每段 `products or [None]`;`delivery_seq = delivery.seq or index+1`。
|
||
- 每行:
|
||
- `row = dict(data)`
|
||
- `_apply_plan_list_export_segment_stop_fields(...)`
|
||
- 若 `product is None`:产品列空,`planQty`/`actualQty` = `None`
|
||
- 否则:`resolve_product_display_names`;`planQty = product.plan_qty`;`actualQty = product.inbound_qty if kind=="load" else product.outbound_qty`(对齐列表 `getRowActualQty`)
|
||
- 品牌:经 plan product lookup 后 `_format_plan_list_export_brand`
|
||
|
||
参考片段(伪代码):
|
||
|
||
```python
|
||
def _iter_segment_product_slots(load_read, delivery_reads):
|
||
if load_read is not None:
|
||
load_products = list(getattr(load_read, "products", None) or []) or [None]
|
||
for product in load_products:
|
||
yield ("load", load_read, None, None, product)
|
||
deliveries = list(delivery_reads or []) or ([None] if load_read is not None else [])
|
||
for index, delivery in enumerate(deliveries):
|
||
seq = getattr(delivery, "seq", None) if delivery is not None else (index + 1)
|
||
if seq is None:
|
||
seq = index + 1
|
||
products = list(getattr(delivery, "products", None) or []) if delivery else []
|
||
if not products:
|
||
products = [None]
|
||
for product in products:
|
||
yield ("delivery", None, delivery, seq, product)
|
||
```
|
||
|
||
注意:仅有送货无装货时仍展开送货段;仅有装货无送货时,`deliveries = [None]` 出送货占位行(与列表一致)。
|
||
|
||
- [ ] **Step 2: 跑测试至全绿**
|
||
|
||
```bash
|
||
cd backend && source venv/bin/activate && pytest tests/test_pl_plan_list_export.py -v
|
||
```
|
||
|
||
Expected: PASS(含旧用例;旧用例 `stops_by_plan` 有单装单送时需改为段展开——**更新** `test_build_plan_list_export_rows_expands_products_with_crm_names`:
|
||
|
||
- 给 `load_stop` / `delivery_stop` 挂上 `products=[product_as_stop]`(字段用 `plan_qty`/`inbound_qty`/`outbound_qty`)
|
||
- 断言 `stopSegment`、装货行/送货行侧栏空非空
|
||
- 或拆成「有段单装单送」+ 保留 legacy 断言
|
||
|
||
- [ ] **Step 3: 归档导出回归(确认未误伤)**
|
||
|
||
```bash
|
||
cd backend && source venv/bin/activate && pytest tests/test_pl_plan_archive_export.py -v --tb=line
|
||
```
|
||
|
||
Expected: PASS
|
||
|
||
- [ ] **Step 4: Commit(用户要求时)**
|
||
|
||
```bash
|
||
git commit -m "$(cat <<'EOF'
|
||
feat(pl): expand plan list export by stop segment and product
|
||
|
||
Align Excel rows with flattenPlanArchivePairRows for stock and plan lists.
|
||
EOF
|
||
)"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 4: 前端导出列注入「段次」
|
||
|
||
**Files:**
|
||
- Modify: `web-admin/src/views/pl/plan/index.vue`(`planExportColumns`)
|
||
|
||
说明:列表无「段次」可见列;导出按可见列过滤时会被丢掉。固定在导出列中注入,保证入库/出库/计划列表 Excel 都有该列。
|
||
|
||
- [ ] **Step 1: 修改 `planExportColumns`**
|
||
|
||
```typescript
|
||
const planExportColumns = computed(() => {
|
||
const skip = new Set(['arrangeCopy', 'planAttachments'])
|
||
const cols = [...visibleColumns.value]
|
||
.filter((col) => !skip.has(col))
|
||
.map((col) => PLAN_EXPORT_COLUMN_FIELD_MAP[col] || col)
|
||
if (!cols.includes('planNo')) cols.unshift('planNo')
|
||
// 导出专用:列表无此列,始终紧挨计划编号
|
||
const planNoIdx = cols.indexOf('planNo')
|
||
if (!cols.includes('stopSegment')) {
|
||
cols.splice(planNoIdx + 1, 0, 'stopSegment')
|
||
}
|
||
return cols
|
||
})
|
||
```
|
||
|
||
- [ ] **Step 2: 手动验收要点**
|
||
|
||
1. 打开运输计划列表、入库单、出库单,各导出一次(筛选含一装多送计划更佳)。
|
||
2. Excel:计划编号后有「段次」;一装多送多行;装货行送货客户空、送货行装货客户空;计划量为本段。
|
||
3. 文件名仍为 `入库单_*.xlsx` / `出库单_*.xlsx` / `计划列表_*.xlsx`。
|
||
|
||
- [ ] **Step 3: Commit(用户要求时)**
|
||
|
||
```bash
|
||
git commit -m "$(cat <<'EOF'
|
||
feat(web-admin): always include stopSegment in plan list export columns
|
||
|
||
Ensure stock inbound/outbound and plan list Excel show segment labels.
|
||
EOF
|
||
)"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 5: 收尾核对
|
||
|
||
- [ ] **Step 1: 对照 spec 清单**
|
||
|
||
| Spec 项 | 对应 Task |
|
||
|---------|-----------|
|
||
| D1 段次×产品多行 | Task 3 |
|
||
| D2 三入口共用 | 同一 API + Task 4 |
|
||
| D3 段次列文案 | Task 2–3 |
|
||
| D4 侧栏按行、不拼接 | Task 2–3 |
|
||
| D5 计划字段重复 | Task 3 |
|
||
| D6 归档不改 | Task 3 回归 |
|
||
| D7 文件名不变 | 已有逻辑 + 旧测 |
|
||
| 空产品占位 / legacy | Task 1+3 |
|
||
| 实际量 inbound/outbound | Task 3 |
|
||
|
||
- [ ] **Step 2: 最终测试**
|
||
|
||
```bash
|
||
cd backend && source venv/bin/activate && pytest tests/test_pl_plan_list_export.py tests/test_pl_plan_archive_export.py -v
|
||
```
|
||
|
||
Expected: 全部 PASS
|
||
|
||
---
|
||
|
||
## Self-review (plan author)
|
||
|
||
1. **Spec coverage:** D1–D7、占位、legacy、实际量语义、前端注入均有 Task。
|
||
2. **No placeholders:** 测试与 helper 给出可粘贴代码;legacy/占位在 Task 1 Step 3 要求写成完整断言。
|
||
3. **Types:** field 统一 `stopSegment`;实际量装货 `inbound_qty`、送货 `outbound_qty`。
|
||
4. **Commits:** 标为「用户要求时」以符合仓库「未明确要求不提交」规则。
|