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

127 lines
7.3 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 — 与列表展平行一致(延续 `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 均可按段次对照列表阅读一装多送。
- 归档不再出现「一行同时装货量+多送货量拼接」的旧宽表形态。
- 无价格权限用户归档导出仍不含单价/金额列。