Files
shanxia2.0/docs/superpowers/specs/2026-08-26-pl-customer-stop-pref-design.md
T
2026-08-27 14:23:18 +08:00

144 lines
5.2 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-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,成文。