运输计划相关列表导出扩展 · 段次×产品行 — 设计文档

日期: 2026-10-15
状态: 待实现
方案: A — 与列表展平行一致（延续 2026-10-15-plan-list-segment-export-design.md）
前置: 运输计划列表 + 入库单 + 出库单 已落地段次导出（出库单复用 PlanListPage，本扩展无需再改）

1. 目标

将下列界面的 Excel 导出行模型对齐各自列表（flattenPlanArchivePairRows）：

界面	路由/入口	当前导出	目标
危化品证上传	`plan-cert`	`planApi.export`（后端已段次展开；前端缺「段次」列）	注入 `stopSegment`
运输归档	`plan-archive`	`exportFormat=archive` 配对宽表	改为段次×产品多行（方案 A）
合同完善	`plan-contract`	`exportContractGaps` 一计划一行	改为段次×产品多行 + 本段缺口语义
出库单	`outbound` → `PlanListPage`	已共用列表导出	已完成，本扩展不改

2. 已确认决策

#	项	决策
E1	行结构	与基线设计 D1/D3/D4/D5 相同：先装货产品行，再各送货段；「段次」；侧栏按行、不拼接
E2	归档列形态	方案 A：去掉装/送同排配对宽列；本段 `计划量`/`实际量`；单价/金额只填本行所属侧
E3	归档 ZIP	`archive_zip` 内 Excel 与 `archive` xlsx 同一行模型（仅附件打包方式不变）
E4	合同完善	导出对齐列表展平；每行带段次与产品；缺口类型按本行段（装货↔供方、送货↔需方）
E5	证件上传	仍走列表导出 API；前端 `planCertExportColumns` 固定注入 `stopSegment`
E6	出库单	不改代码；验收确认即可

修正基线 D6：原「归档导出不改」作废，由本扩展 E2/E3 替代。

3. 非目标

不改各页列表 UI / 合并单元格
不改归档业务规则、价格权限（无价格权限用户仍隐藏单价/金额列）
不改合同完善的缺口判定业务逻辑（只改导出行展开与列）
不新增独立导出 HTTP 路径（可复用/改造现有 endpoint）

4. 分页面设计

4.1 危化品证上传（最小改动）

后端：已用 _build_plan_list_export_rows，无需改行模型。
前端 plan-cert/index.vue：planCertExportColumns 在 planNo 后插入 stopSegment（与运输计划列表相同写法）。
文件名保持 计划证件.xlsx。

4.2 运输归档（方案 A）

行模型：复用与列表相同的段次×产品槽位迭代（可直接调用 _iter_segment_product_slots / 与 _build_plan_list_export_rows 同序的辅助函数）。

列（替换现有 PLAN_ARCHIVE_EXPORT_COLUMNS 宽表） 建议：

field	表头	规则
`rowNo`	序号	可选保留
`planNo`	计划编号	计划级，每行重复
`stopSegment`	段次	`装货` / `送货 #N`
`contractNo`	合同编号	本行段合同
计划日期 / 归档状态 / 跟进状态 / 单据类型	…	计划级
`loadCustomer` / `loadAddress` / `loadTime`	装货侧	仅装货行
`deliveryCustomer` / `deliveryAddress` / `deliveryTime`	送货侧	仅送货行
产品名称 / 品牌 / 别名 / 型号 / 包装 / 单位	…	本行段产品
`planQty` / `actualQty`	计划量 / 实际量	本段；实际量语义同列表（装货 inbound / 送货 outbound）
`unitPrice` / `amount`	单价 / 金额	仅本侧归档价额；对侧行不填另一侧价
车牌 / 运费类字段 / ERP / 备注	…	计划级（运费仍整单重复，与列表习惯一致）

删除：loadPlanQty/deliveryPlanQty 及成对的 loadActualQty/deliveryActualQty/loadInboundQty/…/deliveryAmount 等同排宽列；deliveryStopKind 由统一 stopSegment 替代。

实现落点：

改造 build_plan_archive_export_rows（或新建 build_plan_archive_segment_export_rows 并切换调用）走段次槽位，不再 _append_paired_product_rows 默认路径。
单价/金额：复用归档已有 _get_stop_archive_unit_price / _get_stop_archive_amount（按 kind）。
单测：重写/新增 test_pl_plan_archive_export.py 中配对宽表断言 → 段次多行断言；保留价格权限列过滤行为。

4.3 合同完善

现状：POST /contract-gaps/export 对 gap 列表 一计划一行（供方/需方/缺口类型摘要），与列表 displayRows（段×产品）不一致。

目标行模型：

仍用现有筛选得到「有缺口的计划」集合（list_plan_contract_gaps 的计划 id 集或等价查询）。
对这些计划加载 stops，按 _iter_segment_product_slots 展开行。
列建议：

field	表头	规则
`planNo` / `planDate` / `planType` / `followStatus`	…	计划级
`stopSegment`	段次
`loadCustomer` / `deliveryCustomer`	装/送客户	按行侧填写
`deliveryTimes`	送货时间	仅送货行本段日期（或与列表一致）
`productName` 等	产品	本行段产品（可与列表可见列对齐，最小集：产品名称）
`gapType`	缺口类型	本行段：装货行若缺供方合同 →「缺供方合同」；送货行若缺需方 →「缺需方合同」；本段无缺口可空或「—」（导出是否过滤无缺口段：默认仍导出该计划全部段×产品行，与列表展示一致；若某计划仅因一侧缺口入选，另一侧行 `gapType` 可空）
`supplierName` / `customerName`	供方/需方	计划级保留（可选）

实现落点：export_contract_gaps 改为：查 gap 计划 → load_plan_stops_grouped → 段次展开 → 填缺口标签；更新 CONTRACT_GAP_EXPORT_COLUMNS；前端 contractGapExportColumns 增加 stopSegment 等与新列对齐。

4.4 出库单

已由基线实现覆盖。本扩展只要求手工验收：出库单导出含「段次」且一装多送多行。

5. 架构关系

基线（已完成）
  _build_plan_list_export_rows  ← 运输计划 / 入库 / 出库 /（证件仅缺前端列）

本扩展
  plan-cert 前端注入 stopSegment
  build_plan_archive_export_rows → 段次×产品（方案 A 列）
  export_contract_gaps → 段次×产品 + 本段 gapType

共享：_iter_segment_product_slots、_format_stop_segment_label、段侧字段填写、CRM 别名/品牌 lookup、实际量 inbound/outbound 语义。

6. 测试与验收

证件：导出含「段次」；行数与证件列表展平一致（同筛选）。
归档：一装多送 ≥3 行；无装/送同排配对量列；本行有计划量/实际量；有价格权限时单价/金额仅本侧有值；archive 与 zip 内表结构一致；旧配对列测试更新后全绿。
合同完善：一装多送多行；段次正确；缺口列按段；文件名仍为「计划合同完善_*」。
出库单：抽测一装多送（回归）。

7. 验收标准

上述四页（含出库抽测）Excel 均可按段次对照列表阅读一装多送。
归档不再出现「一行同时装货量+多送货量拼接」的旧宽表形态。
无价格权限用户归档导出仍不含单价/金额列。

7.3 KiB Raw Blame History Unescape Escape