docs: add design for plan list delivery times column
Capture the approved brainstorm for showing and filtering deduplicated delivery-stop dates on PL plan family lists. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
wuzilongandCursor committed
1 parent
2dadd34981
commit
cb57a71d2d
2 files changed
+806
No files matched your search
@@ -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`
|
||||
Reference in new issue
Block a user