144 lines
5.2 KiB
Markdown
144 lines
5.2 KiB
Markdown
# 运输计划 · 客户装/送货物流默认记忆
|
||
|
||
**日期:** 2026-08-26
|
||
**状态:** 设计已确认(待实现)
|
||
**选定方案:** 方案 1 — 独立表 `pl_customer_stop_pref`
|
||
**范围:** `backend`(表 + 读 API + 计划保存时 upsert)+ `web-admin`(装货/送货选客户带出)
|
||
|
||
## 背景与目标
|
||
|
||
创建/编辑运输计划时,选择装货或送货客户后,自动带出该客户在该角色下上次使用的**地址、经纬度、联系方式、注意事项**,减少重复填写。
|
||
|
||
## 已确认决策
|
||
|
||
| 项 | 决定 |
|
||
|----|------|
|
||
| 选客户后表单填充 | **一律覆盖**记忆值(换客户先清空相关字段再填) |
|
||
| 持久化 | **落库**(跨会话、跨终端) |
|
||
| 写入时机 | 计划 **新建保存** 与 **编辑保存** 均 upsert |
|
||
| 共享范围 | **租户内全员共享**(按客户,不按操作人) |
|
||
| 装货 vs 送货 | **独立记录**,不共享 |
|
||
| 空字段 | 保存时**空也写入**(覆盖旧记忆,避免残留) |
|
||
| 经纬度 | **一并记忆**并带出 |
|
||
|
||
## 非目标
|
||
|
||
- 不做记忆的独立 CRUD / 管理界面
|
||
- 不与「运输地址库」双向同步(地址库仍可选手动改当前计划地址)
|
||
- 不记忆合同、产品、地磅勾选、装/送货时间
|
||
- 打开编辑已有计划时,**不**用记忆覆盖计划已存数据(仅用户重新选客户时带出)
|
||
|
||
---
|
||
|
||
## 1. 数据模型
|
||
|
||
表名:`pl_customer_stop_pref`(运输计划-客户装卸货默认记忆)
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `id` | VARCHAR(64) NOT NULL | 主键 UUID |
|
||
| `customer_id` | VARCHAR(64) NOT NULL | 客户 ID |
|
||
| `customer_name` | VARCHAR(200) | 冗余名称 |
|
||
| `stop_type` | VARCHAR(20) NOT NULL | `load` \| `delivery` |
|
||
| `address` | VARCHAR(500) | 地址文案 |
|
||
| `lng` | DECIMAL(10,6) | 经度 |
|
||
| `lat` | DECIMAL(10,6) | 纬度 |
|
||
| `contact` | VARCHAR(200) | 联系方式 |
|
||
| `notes` | VARCHAR(500) | 注意事项 |
|
||
| 公共字段 | | `tenant_no`、`order_num`、`remark`、`create_by`、`create_dept_id`、`create_time`、`update_by`、`update_time`、`del_flag` |
|
||
|
||
**业务唯一键:** `(tenant_no, customer_id, stop_type)`。本期以 upsert 覆盖为主,一般不软删记忆行;若沿用 `del_flag`,查询默认排除 `del_flag=1`,唯一约束实现与现有 PL 表惯例一致即可。
|
||
|
||
**多送货段同客户:** 保存时按段顺序依次 upsert,最终以**最后一段**的值为准。
|
||
|
||
DDL 放入 `docs/sql/migrations/`,并评估同步 `docs/sql` 基线快照(按仓库惯例)。
|
||
|
||
---
|
||
|
||
## 2. API 与后端写入
|
||
|
||
### 2.1 读取
|
||
|
||
`GET /api/admin/pl/customer-stop-pref?customerId={id}&stopType=load|delivery`
|
||
|
||
- 按当前用户 `tenant_no` 过滤
|
||
- 无记录:空 data
|
||
- 有记录:返回 `customerId`、`stopType`、`address`、`lng`、`lat`、`contact`、`notes`
|
||
- 权限:与运输计划表单一致即可(无需单独菜单)
|
||
|
||
### 2.2 写入(服务端隐式)
|
||
|
||
**不**对业务员暴露独立「保存记忆」接口作为主路径。
|
||
|
||
在计划 `createFull` / `update` **主流程保存成功后**,服务层 upsert:
|
||
|
||
1. 装货:`customer_id` 非空 → `stop_type=load`
|
||
2. 每个送货段:`customer_id` 非空 → `stop_type=delivery`(同客户多段后者覆盖)
|
||
3. 字段取自该段最终 `address/lng/lat/contact/notes`(含空)
|
||
4. 客户 ID 为空的段跳过
|
||
|
||
**失败策略:** 记忆 upsert 失败只记日志,**不阻断**计划保存成功响应。
|
||
|
||
路由注册遵循 `app/api/__init__.py` + `app/main.py` 既有 PL 模块惯例。
|
||
|
||
---
|
||
|
||
## 3. 前端交互
|
||
|
||
涉及:`pl-plan-load-section`、`pl-plan-delivery-section`(及客户弹窗确认同一路径)。
|
||
|
||
### 3.1 选客户
|
||
|
||
1. 执行现有逻辑(客户名、合同清空、地磅默认等)
|
||
2. **先清空** `address / lng / lat / contact / notes`
|
||
3. `GET customer-stop-pref`(装货 `load` / 送货 `delivery`)
|
||
4. 有记忆则覆盖上述字段;无记忆保持空
|
||
5. 下拉变更与「客户搜索」弹窗确认走同一套带出逻辑
|
||
|
||
### 3.2 清空客户
|
||
|
||
清空客户 ID 时,同步清空 `address / lng / lat / contact / notes`。
|
||
|
||
### 3.3 编辑打开
|
||
|
||
加载计划详情时**不**拉记忆覆盖;仅用户更换客户时拉记忆。
|
||
|
||
### 3.4 与地址库
|
||
|
||
`PlAddressWithLibrary` 仍可改当前表单地址;保存后由后端用表单终值 upsert 记忆。记忆地址不在库内时,沿用现有 legacy 回显。
|
||
|
||
### 3.5 体验
|
||
|
||
- 拉记忆失败:静默或一次轻量提示,不阻断选客户
|
||
- 本期无「保存到常用」按钮、无记忆管理页
|
||
|
||
---
|
||
|
||
## 4. 验收场景
|
||
|
||
| 场景 | 期望 |
|
||
|------|------|
|
||
| 首次选客户无记忆 | 地址/联系方式/注意事项为空,可手填 |
|
||
| 保存后再新建选同客户同角色 | 带出上次值 |
|
||
| 同客户装货记忆 ≠ 送货记忆 | 互不影响 |
|
||
| 编辑保存修改地址等 | 同事再选同客户同角色带出新值 |
|
||
| 打开编辑且不换客户 | 不被记忆覆盖 |
|
||
| 清空客户 | 相关字段清空 |
|
||
| 计划保存成功但记忆失败 | 计划仍成功 |
|
||
|
||
---
|
||
|
||
## 5. 实现落点(供计划拆分)
|
||
|
||
| 层 | 落点 |
|
||
|----|------|
|
||
| DB | migration + 模型 |
|
||
| Backend | CRUD/service upsert;plan create/update 挂钩;GET API |
|
||
| Frontend | 选客户后拉 pref 填表;API 模块 |
|
||
|
||
---
|
||
|
||
## 修订记录
|
||
|
||
- 2026-08-26:头脑风暴确认方案 1 与 §1–§3,成文。
|