docs: add transport address notes fill design
Capture the approved design for adding notes on pl_transport_address and filling load/delivery notes only when empty. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
1 parent
585b731846
commit
209f27606e
1 file changed
+142
@@ -0,0 +1,142 @@
|
||||
# 运输地址库「注意事项」与选址回填
|
||||
|
||||
**日期:** 2026-09-02
|
||||
**状态:** 待实现
|
||||
**选定方案:** 方案 1 — 地址库新增独立字段 `notes`;扩展现有 `PlAddressApplyPayload` / `apply` 回填链;仅当装/送货注意事项为空时写入
|
||||
|
||||
## 1. 目标
|
||||
|
||||
1. 运输通用地址库增加属性「注意事项」(独立于「备注」)。
|
||||
2. 在运输计划装货信息、送货信息中,通过「从地址库选择」或地址下拉选中地址后,按规则自动将地址库注意事项带入对应「注意事项」。
|
||||
3. 凡复用 `PlAddressWithLibrary` 的装/送货处均生效(含运输计划新增/编辑,以及安排运输等复用装/送货 section 的弹窗)。
|
||||
|
||||
## 2. 非目标
|
||||
|
||||
- 不复用地址库 `remark`(备注)作为注意事项来源。
|
||||
- 不改计划表 / stop 表结构(装/送货 `notes` 已存在)。
|
||||
- 不改客户物流记忆(`pl_customer_stop_pref`)的读写逻辑。
|
||||
- 地址检索参数 `q` 不纳入 `notes`。
|
||||
- 不抽公共地址表单组件;管理页与选择弹窗各自表单同步加字段即可。
|
||||
- 本次不做小程序端对称改造。
|
||||
- 「从地址库选择」列表不新增「注意事项」列(避免挤占宽度);编辑/新增表单必有该字段。
|
||||
|
||||
## 3. 决策记录
|
||||
|
||||
| 项 | 结论 |
|
||||
|----|------|
|
||||
| 字段形态 | 新增独立列 `notes`,与 `remark` 分离 |
|
||||
| 库内为空 | 不覆盖表单已有注意事项(与联系方式空值策略一致) |
|
||||
| 库内有值 | **仅当**表单注意事项为空(trim 后)时写入(比联系方式更保守;联系方式有值则直接写入) |
|
||||
| 适用范围 | 所有 `PlAddressWithLibrary`(下拉 + 弹窗选择) |
|
||||
| 清空地址 | 不主动清除已有注意事项 |
|
||||
| 选择弹窗列表 | 不加注意事项列;嵌套新增/编辑表单有该字段 |
|
||||
| 实现路径 | 扩展 `apply` 回填链(对齐 2026-08-06 联系方式回填架构) |
|
||||
|
||||
## 4. 数据模型
|
||||
|
||||
### 4.1 表 `pl_transport_address`
|
||||
|
||||
新增列:
|
||||
|
||||
| 列名 | 类型 | 可空 | 注释 |
|
||||
|------|------|------|------|
|
||||
| `notes` | `varchar(500)` | YES | 注意事项 |
|
||||
|
||||
字段顺序建议:业务字段中置于 `contact_phone` 之后、`status` 之前;其后仍为公共字段(`tenant_no` … `del_flag`)。
|
||||
|
||||
### 4.2 与既有字段关系
|
||||
|
||||
- `remark`:内部备注,不参与选址回填注意事项。
|
||||
- 计划装货/送货侧已有 `notes`(以及汇总层 `pickupNotes` / `destinationNotes`):本次只做前端选址时写入 stop 表单的 `notes`,不改 DDL。
|
||||
|
||||
### 4.3 迁移
|
||||
|
||||
- 提供可执行的增量 SQL(`ALTER TABLE ... ADD COLUMN notes ...`)。
|
||||
- 按仓库惯例同步更新 `docs/sql/shanxia2.0.sql` 中该表结构定义。
|
||||
|
||||
## 5. 后端
|
||||
|
||||
- Model `PlTransportAddress` 增加 `notes`。
|
||||
- Schema:`TransportAddressCreate` / `Update` / `Read`(及 Base)增加可选 `notes`(`max_length=500`);JSON 使用 camelCase 时与前端字段名 `notes` 一致即可。
|
||||
- API `transport_address`:create/update 写入;list / get / all / export 读出。
|
||||
- 导出列:在「联系电话」与「状态」之间增加「注意事项」。
|
||||
- 列表检索 `q`:仍仅匹配地址名称、详细地址、联系人、电话(all 接口仍仅名称与详细地址);**不**搜索 `notes`。
|
||||
|
||||
## 6. 前端
|
||||
|
||||
### 6.1 类型
|
||||
|
||||
- `TransportAddress`、`TransportAddressPayload`(`web-admin/src/api/pl/index.ts`)增加可选 `notes?: string`。
|
||||
|
||||
### 6.2 地址维护 UI
|
||||
|
||||
1. **管理页** `views/pl/transport-address/index.vue`
|
||||
- 新增/编辑表单:在联系电话与备注之间增加「注意事项」`textarea`(可选,非必填)。
|
||||
- 列表:增加「注意事项」列(建议默认可见,支持列设置隐藏)。
|
||||
- 查看弹窗:展示注意事项。
|
||||
|
||||
2. **选择弹窗** `pl-transport-address-select-dialog`
|
||||
- 嵌套新增/编辑表单同步增加「注意事项」。
|
||||
- 选择列表不加该列。
|
||||
- create/update payload 带上 `notes`。
|
||||
|
||||
### 6.3 回填链
|
||||
|
||||
```
|
||||
选地址(下拉 / 「从地址库选择」)
|
||||
→ pl-address-with-library.applyAddressRow
|
||||
→ emit apply { address, lng, lat, contact?, notes? }
|
||||
→ pl-plan-load-section.patchAddress
|
||||
或 pl-plan-delivery-section.patchDeliveryAddress
|
||||
→ 若 payload.notes 非空(trim)且当前 stop.notes 为空(trim)
|
||||
→ 写入 notes
|
||||
否则不改 notes
|
||||
```
|
||||
|
||||
### 6.4 组件改动文件
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `backend/.../pl_models.py` | `PlTransportAddress.notes` |
|
||||
| `backend/.../schemas/pl/transport_address.py` | Create/Update/Read |
|
||||
| `backend/.../api/pl/transport_address.py` | 读写与导出列 |
|
||||
| `docs/sql/` + `shanxia2.0.sql` | DDL |
|
||||
| `web-admin/src/api/pl/index.ts` | 类型 |
|
||||
| `pl-address-with-library/index.vue` | `PlAddressApplyPayload.notes`;选中时若库内有值则带上 |
|
||||
| `pl-plan-load-section/index.vue` | `patchAddress`:空才写 notes |
|
||||
| `pl-plan-delivery-section/index.vue` | `patchDeliveryAddress`:同上 |
|
||||
| `views/pl/transport-address/index.vue` | 表单 / 列表 / 查看 |
|
||||
| `pl-transport-address-select-dialog/index.vue` | 嵌套表单 CRUD |
|
||||
|
||||
计划表单弹窗、安排运输等若仅复用 load/delivery section,**无需再改父弹窗**。
|
||||
|
||||
### 6.5 UI 约定
|
||||
|
||||
- 表单 `label-position="top"`;注意事项用 `form-col-span-2` 的 textarea。
|
||||
- 非必填;可选 `maxlength=500` 与后端对齐。
|
||||
- 按钮图标等仍遵循 ui-conventions;本次无新按钮类型。
|
||||
|
||||
## 7. 边界与交互细节
|
||||
|
||||
1. **联系方式回填不变**:库内有联系信息则写入;皆空则不改联系方式(既有规则)。
|
||||
2. **清空地址**:`emitApply` 清空 address/lng/lat;不强制清空 `notes`(保留用户已填或已带入的注意事项)。
|
||||
3. **与客户物流记忆并存**:选客户可能先写入 pref.notes;之后再选地址时,若表单已有 notes,按「空才写」不覆盖。反之先选地址带入后再选客户,以既有客户切换逻辑为准(客户变更会清空 notes 再应用 pref)。
|
||||
4. **legacy 历史地址选项**:无库内 notes,不写入。
|
||||
|
||||
## 8. 验收要点
|
||||
|
||||
1. 地址库管理页可维护「注意事项」并持久化;查看/列表可见。
|
||||
2. 「从地址库选择」新增/编辑可维护「注意事项」。
|
||||
3. 装货注意事项为空且地址有 notes → 选地址后自动填入;送货同理。
|
||||
4. 表单已有注意事项 → 选地址不改。
|
||||
5. 地址 notes 为空 → 不改表单。
|
||||
6. 下拉选地址与弹窗「选择」行为一致。
|
||||
7. 清空地址不清除已有注意事项。
|
||||
8. `remark` 与 `notes` 互不影响;联系方式回填回归通过。
|
||||
9. 客户物流记忆带入注意事项的行为不被本次改动破坏。
|
||||
|
||||
## 9. 测试建议(实现阶段)
|
||||
|
||||
- 手工:上述验收矩阵(空/有值 × 装货/送货 × 下拉/弹窗)。
|
||||
- 后端:create/update/get 含 notes;导出列存在;旧数据 notes 为 null 时列表不报错。
|
||||
- 字段一致性:若仓库有 `check_field_consistency` 覆盖该实体,实现后跑一遍。
|
||||
Reference in new issue
Block a user