diff --git a/docs/fresh-mint-pl-plan-delivery-time-column-demo.html b/docs/fresh-mint-pl-plan-delivery-time-column-demo.html new file mode 100644 index 000000000..74657cb7a --- /dev/null +++ b/docs/fresh-mint-pl-plan-delivery-time-column-demo.html @@ -0,0 +1,636 @@ + + + + + + 运输计划列表 · 送货时间列 Demo + + + + + + +
+
+

运输计划 · 新增列 送货时间

+

+ 插入位置:计划日期 之后。数据来自各送货段 + pl_plan_delivery.delivery_time,去重后展示;列头漏斗支持日期区间过滤 + (与计划日期列交互一致)。下方可切换三种单元格展示方案。 +

+
+ 列:送货时间 + 去重 · 升序 + 过滤:日期区间 + 表单取值格式 YYYY-MM-DD +
+
+ +
+ + + + 当前方案:逗号拼接 +
+ +
+
+

运输计划列表(示意)

+ 绿色描边列为新增「送货时间」· 点击漏斗可预览过滤浮层 +
+
+ 今天 + 近 7 天 + 本月 + + + +
+
+ + + + + + + + + + + + + + +
#计划编号跟进状态 + 计划日期 + + + + 送货时间 + + +
+

+ 过滤语义示意:任一送货段时间落在区间内即命中该计划 + (EXISTS 子查询,不对主表 pl_plan.delivery_time 过滤)。 +

+
+
+ + +
+
+ + +
+
+
+ + +
+
+
单据类型车牌号客户 / 段次摘要
+
+
+ +
+
+

A · 逗号拼接推荐

+

与「多值文本列」一致,窄列可读;去重后如 09-12, 09-14。合并单元格场景最稳。

+
+
+

B · 标签堆叠

+

视觉区分更强,但列宽吃得更多,合并行高度波动大。

+
+
+

C · 多行换行

+

每行一个日期,对齐清晰;行高会随段次数增加,列表节奏变松。

+
+
+ +
+ 示例数据说明: + PO20260912001 有 3 个送货段,时间 09-12 / 09-12 / 09-14 → 去重后 2 个; + PO20260912002 单段;PO20260912003 两段不同日;PO20260912004 无送货时间 → 展示「—」。 + 主表冗余字段 pl_plan.delivery_time 仅同步首段,不作为本列数据源。 +
+
+ + + + diff --git a/docs/superpowers/specs/2026-09-12-pl-plan-delivery-times-column-design.md b/docs/superpowers/specs/2026-09-12-pl-plan-delivery-times-column-design.md new file mode 100644 index 000000000..1d2b6afc3 --- /dev/null +++ b/docs/superpowers/specs/2026-09-12-pl-plan-delivery-times-column-design.md @@ -0,0 +1,170 @@ +# 运输计划列表「送货时间」列设计 + +日期:2026-09-12 +状态:已评审(待实现) +相关 Demo:`docs/fresh-mint-pl-plan-delivery-time-column-demo.html` + +## 背景与目标 + +运输计划可有多个送货段(`pl_plan_delivery`),各段有独立「送货时间」。业务需要在计划列表「计划日期」后展示**去重后的送货时间**,并支持列头区间过滤。 + +主表 `pl_plan.delivery_time` 仅为首段同步冗余,**不得**作为本列数据源或过滤依据。 + +## 已确认决策 + +| 项 | 决策 | +|----|------| +| 展示 | 多行换行,一行一个日期 | +| 格式 | `YYYY-MM-DD` | +| 去重 | 按日历日去重后升序 | +| 过滤语义 | 任一送货段落在区间内即命中(EXISTS) | +| 范围 | 主列表 + 归档 + 合同完善 + 证书 | +| 顶部日期 pills | 仍只筛「计划日期」;送货时间仅列头漏斗 | +| 实现路径 | 方案 1:后端 EXISTS 过滤 + 列表返回 `deliveryTimes[]` | + +## 方案 1 概要 + +1. 列表/导出查询增加 `deliveryTimeFrom` / `deliveryTimeTo`。 +2. `build_plan_column_filters`(及四页同源参数透传)用 `PlPlanDelivery` EXISTS 过滤。 +3. 列表项增加 `deliveryTimes: string[]`(去重升序 `YYYY-MM-DD`)。 +4. 四页 UI 在「计划日期」后加列,多行展示,并入计划区合并列。 + +## §1 数据与过滤 + +### 数据源 + +- 表:`pl_plan_delivery` +- 字段:`delivery_time` +- 条件:`del_flag = 0`,且与计划同租户、同 `plan_id` +- **排除**:`pl_plan.delivery_time` + +### 聚合规则 + +对每个计划: + +1. 收集送货段 `delivery_time` 非空值; +2. 截断为日历日(忽略时分秒); +3. 去重、升序; +4. 格式化为 `YYYY-MM-DD` 字符串数组 → `deliveryTimes`; +5. 无有效值 → `[]`(前端显示 `—`)。 + +### 过滤 + +- 参数:`deliveryTimeFrom`、`deliveryTimeTo`(`date`,camelCase alias) +- 语义:存在至少一条未删除送货段,其 `DATE(delivery_time)` 落在闭区间 `[from, to]`(缺一侧则只约束另一侧) +- 与 `planDateFrom/To` 等其它条件 **AND** +- 顶部「今天 / 近 7 天 / 本月」**不**写入 `deliveryTime*` + +## §2 API 与导出 + +### 查询 + +以下 list / export(及共用 `_column_filters_from_params` / `build_plan_column_filters` 的路径)透传新参数: + +- 运输计划主列表 +- 运输计划归档 +- 运输计划合同完善 +- 运输计划证书相关列表 + +落点: + +- `backend/app/services/pl/plan_list_filters.py` → `build_plan_column_filters` +- `backend/app/api/pl/plan.py`(及归档/证书/合同完善若分路由,同样透传) + +### 响应 + +- Schema 计划列表项增加 `deliveryTimes: list[str]`(camelCase) +- 在已有批量 `load_plan_stops_grouped` / 装配路径上按 `plan_id` 聚合写入,避免 N+1 +- 详情/编辑:已有 `deliveries[].deliveryTime`,可不重复依赖列表字段 + +### 导出 + +- **计划维度**导出:在「计划日期」后增加「送货时间」列 +- 单元格:多个日期用 ` / ` 拼接(Excel 友好);空则空或 `—`(与现有空值习惯一致) +- **段次展开**类导出若已有「段次时间」,不再加计划级聚合列,避免重复 + +### 明确不做 + +- 不改写 `pl_plan.delivery_time` +- 无 DB 迁移、无新表字段、无历史回填任务 + +## §3 四页 UI + +### 页面 + +| 页面 | 路径 | +|------|------| +| 运输计划 | `web-admin/src/views/pl/plan/index.vue` | +| 归档 | `web-admin/src/views/pl/plan-archive/index.vue` | +| 合同完善 | `web-admin/src/views/pl/plan-contract/index.vue` | +| 证书 | `web-admin/src/views/pl/plan-cert/index.vue` | + +各页 `columnFilterDefs.ts` 同步增加 `deliveryTimes` 定义。 + +### 列行为 + +- 位置:紧挨「计划日期」之后 +- `prop`: `deliveryTimes`;列设置默认可见 +- 单元格:竖排多行,每行一个 `YYYY-MM-DD`;`[]` → `—` +- 样式:纯文本,不用 Tag;`min-width` 约 120~140;居中 +- 并入 `PLAN_MERGE_COLUMN_PROPS`,插在 `planDate` 之后(计划区合并只显示一份) + +### 列头过滤 + +- `type: 'datetime'` +- `queryKeyFrom: 'deliveryTimeFrom'` +- `queryKeyTo: 'deliveryTimeTo'` +- 与 `planDate` 列头控件同交互 +- 点顶部日期 pills:沿用现逻辑只清 `planDate` 列过滤,**不清**送货时间过滤 +- 「清空列过滤」同时清除送货时间过滤 + +### 明确不做 + +- 不改表单/详情内已有送货时间编辑控件 +- 不把送货时间并入顶部快捷 pills + +## §4 边界与验收 + +### 边界 + +- 多段同日 → 去重后一行 +- 部分段有时间 → 只展示/过滤有值段 +- 全部无时间 → `—`;送货时间过滤下不命中 +- 带时分的 `delivery_time` → 按日历日截断后再去重/比较 +- `del_flag=1` 送货段不参与 +- 计划日期过滤与送货时间过滤可同时生效(AND) +- 合并单元格键包含 `deliveryTimes`(与同计划其它计划区字段一致) + +### 验收 + +1. 主列表「计划日期」后有「送货时间」,多段去重多行 `YYYY-MM-DD` +2. 列头区间:任一送货段落入即出结果;与计划日期 pills 互不覆盖参数 +3. 归档 / 合同完善 / 证书行为一致 +4. 计划维度导出含「送货时间」,多值可读 +5. 无送货时间显示 `—`,且不会被送货时间过滤误筛入 + +### 范围外 + +- 小程序端 +- 运费、出入库等非同类计划列表 +- DB 新字段 / 主表历史回填 + +## 主要改动面(实现索引) + +**Backend** + +- `app/services/pl/plan_list_filters.py` — EXISTS + from/to +- `app/api/pl/plan.py` — Query/Body 透传、列表装配、导出列 +- `app/schemas/pl/plan.py` — `deliveryTimes` +- 归档/证书/合同完善若有独立 list/export 参数拼装,同步透传 + +**Frontend** + +- `views/pl/plan|plan-archive|plan-cert|plan-contract/index.vue` +- 对应 `columnFilterDefs.ts` +- 类型定义(若有集中 Plan 类型)增加 `deliveryTimes?: string[]` + +## 参考 + +- 列过滤基线:`docs/superpowers/specs/2026-09-06-pl-list-server-column-filters-design.md` +- UI Demo:`docs/fresh-mint-pl-plan-delivery-time-column-demo.html`