5.2 KiB
运输计划 · 客户装/送货物流默认记忆
日期： 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：
- 装货：
customer_id非空 →stop_type=load - 每个送货段：
customer_id非空 →stop_type=delivery（同客户多段后者覆盖） - 字段取自该段最终
address/lng/lat/contact/notes（含空） - 客户 ID 为空的段跳过
失败策略： 记忆 upsert 失败只记日志，不阻断计划保存成功响应。
路由注册遵循 app/api/__init__.py + app/main.py 既有 PL 模块惯例。
3. 前端交互
涉及：pl-plan-load-section、pl-plan-delivery-section（及客户弹窗确认同一路径）。
3.1 选客户
- 执行现有逻辑（客户名、合同清空、地磅默认等）
- 先清空
address / lng / lat / contact / notes GET customer-stop-pref（装货load/ 送货delivery）- 有记忆则覆盖上述字段；无记忆保持空
- 下拉变更与「客户搜索」弹窗确认走同一套带出逻辑
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，成文。