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

> **日期**: 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`（段×产品）不一致。

**目标行模型**：

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

| 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. 架构关系

```text
基线（已完成）
  _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. 测试与验收

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

## 7. 验收标准

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