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

145 lines
7.9 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.
# 运输计划 / 库存列表导出 · 段次×产品行 — 设计文档
> **日期**: 2026-10-15
> **状态**: 待实现
> **方案**: A — 完全对齐列表展平行(`flattenPlanArchivePairRows`)
> **范围**: 运输计划列表 + 库存管理入库单/出库单(共用同一套导出逻辑)
## 1. 目标
列表导出 Excel 的行模型与列表 UI 一致:
- 一装多送时,能按段次拆成多行(先装货产品行,再各送货段产品行)
- 每行的「计划量 / 实际量」为本行所属段上的数量,不再把多段产品/客户压成一行
- 库存管理(`stockRole=inbound|outbound`)与运输计划列表走**同一**后端导出构建函数
## 2. 已确认决策
| # | 项 | 决策 |
|---|-----|------|
| D1 | 行结构 | **方案 A**:段次×产品多行,对齐 `flattenPlanArchivePairRows` |
| D2 | 作用面 | 运输计划列表 + 入库单 + 出库单,共用逻辑 |
| D3 | 段次列 | 新增「段次」列:`装货` / `送货 #1` / `送货 #2`… |
| D4 | 客户/地址列 | 装货行只填装货侧;送货行只填对应送货段;**不再**用 ` / ` 拼接多送客户 |
| D5 | 计划级字段 | 计划编号等每行重复(Excel 不做合并单元格) |
| D6 | 归档导出 | **不改**归档配对宽表(`build_plan_archive_export_rows`) |
| D7 | 文件名 / Sheet | 保持现有:`入库单` / `出库单` / `计划列表` |
## 3. 非目标
- 不改列表 UI、合并单元格、斑马纹等展示逻辑
- 不改计划归档导出的配对宽表与「装货量+送货量同列」结构
- 不新增独立导出 API;仍走现有 `plan` 列表导出入口
- 不做前端本地拼 Excel;行展开在后端完成
## 4. 现状问题
| 层 | 现状 | 问题 |
|----|------|------|
| 列表 | `flattenPlanArchivePairRows`:装货产品行 → 各送货段产品行;`planQty`/`actualQty` 取本段产品 | 正确 |
| 列表导出 | `_build_plan_list_export_rows`:按**计划级** `PlPlanProduct` 展开;装/送客户、地址用 ` / ` 汇总整单 | 一装多送时一行;数量无法按段对照列表 |
## 5. 行模型
对每个计划,按 `stops_by_plan`(`load_plan_stops_grouped`)展开:
```text
装货段.products[] → 行:段次=装货,产品/量=装货段产品
送货段1.products[] → 行:段次=送货 #1,产品/量=该送货段产品
送货段2.products[] → 行:段次=送货 #2,…
```
### 5.1 顺序与占位
1. **先**全部装货段产品行,**再**按送货 `seq` 依次展开各送货段产品行(与列表一致)。
2. 某侧无产品:仍输出该侧**占位行**(产品列、计划量、实际量为空),与列表「空产品仍占一行」行为一致。
3. **无段结构(legacy)**:无 load/delivery 段时,回退为计划级 `PlPlanProduct` 一行(段次为空),兼容旧数据。
4. 筛选条件(含 `stockRole`、列头筛选等)仍由现有列表查询决定「导出哪些计划」;本设计只改**单计划内行展开**。
### 5.2 示例
计划 `PO20261009016`:装货 1 个产品、送货 2 段各 1 个产品 → 导出 **3 行**:
| 段次 | 装货客户 | 送货客户 | 产品 | 计划量 |
|------|----------|----------|------|--------|
| 装货 | A | (空) | 尿素 | 30 |
| 送货 #1 | (空) | B1 | 尿素 | 20 |
| 送货 #2 | (空) | B2 | 尿素 | 10 |
## 6. 列语义
### 6.1 新增列
| field | 表头 | 取值 |
|-------|------|------|
| `stopSegment` | 段次 | `装货`;`送货 #{seq}`(seq 缺省时用展开序号) |
默认导出列顺序:建议紧挨「计划编号」之后。前端可见列导出映射:若列表无独立段次 prop,仍由后端默认列包含 `stopSegment`;前端 `planExportColumns` 增加 `{ prop: 'stopSegment', label: '段次' }`(或等价别名),以便「按可见列导出」时可选。
### 6.2 按行填写规则
| 列 | 装货行 | 送货行 |
|----|--------|--------|
| 计划级(编号、归属公司、跟进状态、计划日期、单据类型、车牌、人员、跟进人、供方、需方、司机、运输/归档状态、ERP、备注等) | 重复填计划值 | 同左 |
| 送货时间(`deliveryTimes`) | 空 | 本送货段日期(单值,不再整单 ` / ` 拼接) |
| 装货客户 / 装货地址时间 / 装货地磅 | 本装货段 | 空 |
| 送货客户 / 送货地址时间 / 送货地磅 | 空 | 本送货段 |
| 合同(`productContract`) | 本装货段合同号 | 本送货段合同号 |
| 产品名称 / 品牌 / 别名 / 型号规格 / 包装规格 / 单位 | 本行段产品(CRM 标准名/别名解析保持现有) | 同左 |
| 计划量 / 实际量 | 本行段产品 `planQty`;实际量语义对齐列表 `getRowActualQty`(装货读 inbound 侧实际量,送货读 outbound 侧实际量) | 同左 |
枚举中文标签(跟进状态、单据类型、运输/归档状态、归属公司等)与文件名/Sheet 标题逻辑**保持**现有实现。
### 6.3 字典与别名
- 单位等 `dict_type` 列仍走现有 `export_rows_to_xlsx_response` 字典翻译。
- `_PLAN_EXPORT_COLUMN_ALIASES`:如前端 prop 与 field 不一致则补映射;`stopSegment` 本身可直接作为 prop。
## 7. 架构与落点
```text
ListExportDropdown(运输计划 / 入库 / 出库)
→ POST 现有 plan 导出 API(带 filters + stockRole + columns)
→ 查询 plans(不变)
→ load_plan_stops_grouped
→ _build_plan_list_export_rows 【改为段次×产品展开】
→ PLAN_EXPORT_COLUMNS(+ stopSegment)
→ xlsx(filename/sheet 按 stockRole)
```
| 单元 | 职责 | 依赖 |
|------|------|------|
| `_build_plan_list_export_rows` | 单计划 → 多行 dict;段次与侧栏字段按行写入 | `stops_by_plan`、CRM 别名 map、段产品 |
| `PLAN_EXPORT_COLUMNS` | 列定义含 `stopSegment` | — |
| `_apply_plan_list_export_stop_fields` | 改为**按单侧 stop**填写,或拆成 load/delivery 专用 helper,避免整单拼接 | 单条 load 或单条 delivery |
| `web-admin` `plan/index.vue`(及库存页复用) | 导出列清单增加段次;文件名已按 stockRole | 共用 `PlanListPage` |
| `tests/test_pl_plan_list_export.py` | 一装多送行数、段次文案、侧栏字段空/非空、qty | — |
**建议**:段次展开逻辑可抽到 `backend/app/services/pl/` 下小函数(如 `iter_plan_list_export_segments`),便于单测且与 `plan.py` 路由层解耦;若改动面小,也可先内联在 `_build_plan_list_export_rows`,以最小必要为准。
## 8. 实际量语义(与列表对齐)
列表:
- `getRowPlanQty` ← 本行 `PlanStopProduct.planQty`
- `getRowActualQty` ← `getStopArchiveActualQty`:装货用 `inboundQty`,送货用 `outboundQty`
导出 MUST 使用同一语义读取段产品字段(后端 stop product 模型上的对应属性),不得再写计划级 `PlPlanProduct.actual_qty` 作为有段计划的实际量来源。
## 9. 测试要求
至少覆盖:
1. **一装多送**:1 装货产品 + 2 送货段各 1 产品 → 3 行;段次为 `装货`/`送货 #1`/`送货 #2`;各行 `planQty` 为段量;装货行 `deliveryCustomer` 为空、送货行 `loadCustomer` 为空。
2. **单装单送**:行为与列值正确;中文标签回归(跟进状态、单据类型等)。
3. **空产品占位**:送货段无产品仍有一行,产品/量为空。
4. **legacy**:无 stops 时仍按计划级产品展开,段次为空。
5. **文件名**:`stockRole` → `入库单_` / `出库单_` / `计划列表_`(现有用例保留)。
6. **列过滤**:请求 `stopSegment` 时出现在导出列;别名 normalize 不破坏既有 prop。
## 10. 验收标准
- 对 `PO20261009016` 类一装多送计划:导出 Excel 行数与列表展平行数一致(同筛选、同计划集合前提下)。
- 打开「入库单.xlsx / 出库单.xlsx / 计划列表.xlsx」均可看到「段次」及按段拆分的计划量/实际量。
- 计划归档导出行为不变(回归抽测或现有 `test_pl_plan_archive_export` 全绿)。