From 209f27606e531b13e960980f1d5c38b2595ce04b Mon Sep 17 00:00:00 2001 From: zlwu <704541015@qq.com> Date: Wed, 2 Sep 2026 11:53:22 +0800 Subject: [PATCH] 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 --- ...-pl-transport-address-notes-fill-design.md | 142 ++++++++++++++++++ 1 file changed, 142 insertions(+) create mode 100644 docs/superpowers/specs/2026-09-02-pl-transport-address-notes-fill-design.md diff --git a/docs/superpowers/specs/2026-09-02-pl-transport-address-notes-fill-design.md b/docs/superpowers/specs/2026-09-02-pl-transport-address-notes-fill-design.md new file mode 100644 index 000000000..4e6948df1 --- /dev/null +++ b/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` 覆盖该实体,实现后跑一遍。