Files
shanxia2.0/docs/superpowers/plans/2026-10-15-plan-list-segment-export.md
T
2026-10-19 18:28:02 +08:00

498 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 运输计划 / 库存列表导出 · 段次×产品行 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:** 标为「用户要求时」以符合仓库「未明确要求不提交」规则。