Просмотр исходного кода

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>
zlwu 2 месяцев назад
Родитель
Сommit
209f27606e

+ 142 - 0
docs/superpowers/specs/2026-09-02-pl-transport-address-notes-fill-design.md

@@ -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` 覆盖该实体,实现后跑一遍。