diff --git a/docs/superpowers/plans/2026-09-02-pl-transport-address-notes-fill.md b/docs/superpowers/plans/2026-09-02-pl-transport-address-notes-fill.md new file mode 100644 index 000000000..27197c953 --- /dev/null +++ b/docs/superpowers/plans/2026-09-02-pl-transport-address-notes-fill.md @@ -0,0 +1,594 @@ +# 运输地址库「注意事项」与选址回填 Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** 地址库新增独立字段 `notes`(注意事项),选地址时仅当装/送货注意事项为空则自动带入。 + +**Architecture:** DDL + Model/Schema/API 持久化 `notes`;前端地址维护表单可编辑;`PlAddressWithLibrary` 经 `apply` 附带 `notes`;装/送货 `patch*Address` 调用纯函数 `resolveAddressNotesFill`(空才写)。不改计划表结构。 + +**Tech Stack:** MySQL 5.7 · FastAPI/SQLAlchemy/Pydantic v2 · Vue 3 + Element Plus · 现有 `transportAddressApi` / `PlAddressWithLibrary` + +**Spec:** `docs/superpowers/specs/2026-09-02-pl-transport-address-notes-fill-design.md` + +--- + +## File map + +| 文件 | 职责 | +|------|------| +| `docs/sql/migrations/2026-09-02-pl-transport-address-notes.sql` | 增量 DDL | +| `docs/sql/shanxia2.0.sql` | 基线表结构同步 | +| `backend/app/models/pl_models.py` | `PlTransportAddress.notes` | +| `backend/app/schemas/pl/transport_address.py` | Create/Update/Read `notes` | +| `backend/app/api/pl/transport_address.py` | create 写入 + 导出列 | +| `backend/tests/test_pl_transport_address_notes_schema.py` | Schema 接受 notes | +| `web-admin/src/utils/pl-address-notes-fill.ts` | 回填纯函数 | +| `web-admin/src/utils/pl-address-notes-fill.test.ts` | 回填单测 | +| `web-admin/src/api/pl/index.ts` | TS 类型 | +| `web-admin/src/components/business/pl-address-with-library/index.vue` | apply 带 notes | +| `web-admin/src/components/business/pl-plan-load-section/index.vue` | patchAddress 空才写 | +| `web-admin/src/components/business/pl-plan-delivery-section/index.vue` | patchDeliveryAddress 空才写 | +| `web-admin/src/components/business/pl-transport-address-select-dialog/index.vue` | 嵌套表单字段 | +| `web-admin/src/views/pl/transport-address/index.vue` | 管理页表单/列表/查看 | + +--- + +### Task 1: 回填纯函数(TDD) + +**Files:** +- Create: `web-admin/src/utils/pl-address-notes-fill.ts` +- Create: `web-admin/src/utils/pl-address-notes-fill.test.ts` + +- [ ] **Step 1: Write the failing test** + +```ts +import assert from 'node:assert/strict' +import { describe, it } from 'node:test' +import { resolveAddressNotesFill } from './pl-address-notes-fill' + +describe('resolveAddressNotesFill', () => { + it('returns library notes when current is empty', () => { + assert.equal(resolveAddressNotesFill('', '大门左侧卸货'), '大门左侧卸货') + assert.equal(resolveAddressNotesFill(' ', '大门左侧卸货'), '大门左侧卸货') + assert.equal(resolveAddressNotesFill(null, '大门左侧卸货'), '大门左侧卸货') + assert.equal(resolveAddressNotesFill(undefined, ' trim me '), 'trim me') + }) + + it('returns undefined when library notes empty', () => { + assert.equal(resolveAddressNotesFill('', ''), undefined) + assert.equal(resolveAddressNotesFill('已有', ''), undefined) + assert.equal(resolveAddressNotesFill('已有', ' '), undefined) + assert.equal(resolveAddressNotesFill('已有', null), undefined) + }) + + it('returns undefined when current notes already set', () => { + assert.equal(resolveAddressNotesFill('表单已有', '库内注意事项'), undefined) + assert.equal(resolveAddressNotesFill(' 表单已有 ', '库内'), undefined) + }) +}) +``` + +- [ ] **Step 2: Run test to verify it fails** + +Run: + +```bash +cd web-admin && node --import tsx --test src/utils/pl-address-notes-fill.test.ts +``` + +Expected: FAIL(模块不存在或导出缺失) + +- [ ] **Step 3: Write minimal implementation** + +```ts +/** + * 地址库注意事项 → 装/送货注意事项回填。 + * 仅当库内有非空 notes 且当前表单 notes 为空(trim)时返回待写入值;否则 undefined(不改动)。 + */ +export function resolveAddressNotesFill( + currentNotes: string | null | undefined, + libraryNotes: string | null | undefined +): string | undefined { + const lib = (libraryNotes || '').trim() + if (!lib) return undefined + if ((currentNotes || '').trim()) return undefined + return lib +} +``` + +- [ ] **Step 4: Run test to verify it passes** + +Run: same command as Step 2 +Expected: PASS(3 tests) + +- [ ] **Step 5: Commit** + +```bash +git add web-admin/src/utils/pl-address-notes-fill.ts web-admin/src/utils/pl-address-notes-fill.test.ts +git commit -m "$(cat <<'EOF' +feat(web-admin): add resolveAddressNotesFill for address library notes + +Encode empty-only fill rule for load/delivery notes when selecting an address. +EOF +)" +``` + +--- + +### Task 2: DDL + Model + Schema + API + +**Files:** +- Create: `docs/sql/migrations/2026-09-02-pl-transport-address-notes.sql` +- Modify: `docs/sql/shanxia2.0.sql`(`pl_transport_address` 表定义:在 `contact_phone` 后增加 `notes`) +- Modify: `backend/app/models/pl_models.py`(`PlTransportAddress`) +- Modify: `backend/app/schemas/pl/transport_address.py` +- Modify: `backend/app/api/pl/transport_address.py` +- Create: `backend/tests/test_pl_transport_address_notes_schema.py` + +- [ ] **Step 1: Write failing schema tests** + +```python +"""运输地址库 Schema 接受 notes。""" +from __future__ import annotations + +from decimal import Decimal + +from app.schemas.pl.transport_address import TransportAddressCreate, TransportAddressUpdate + + +def test_transport_address_create_accepts_notes(): + body = TransportAddressCreate.model_validate( + { + "addressName": "测试仓", + "fullAddress": "安庆市某某路1号", + "lng": Decimal("117.0"), + "lat": Decimal("30.5"), + "notes": "大门左侧卸货", + } + ) + assert body.notes == "大门左侧卸货" + + +def test_transport_address_update_accepts_notes(): + body = TransportAddressUpdate.model_validate({"notes": "进厂需报备"}) + assert body.notes == "进厂需报备" + + +def test_transport_address_create_notes_optional(): + body = TransportAddressCreate.model_validate( + { + "addressName": "测试仓", + "fullAddress": "安庆市某某路1号", + "lng": Decimal("117.0"), + "lat": Decimal("30.5"), + } + ) + assert body.notes is None +``` + +- [ ] **Step 2: Run tests to verify they fail** + +Run: + +```bash +cd backend && source venv/bin/activate && pytest tests/test_pl_transport_address_notes_schema.py -v +``` + +Expected: FAIL(`notes` 字段不存在 / validation 忽略未知字段视配置而定;目标为 Create 无 `notes` 属性) + +- [ ] **Step 3: Add migration SQL** + +`docs/sql/migrations/2026-09-02-pl-transport-address-notes.sql`: + +```sql +-- 运输地址库增加注意事项 +-- 设计: docs/superpowers/specs/2026-09-02-pl-transport-address-notes-fill-design.md + +SET NAMES utf8mb4; + +ALTER TABLE `pl_transport_address` + ADD COLUMN `notes` varchar(500) DEFAULT NULL COMMENT '注意事项' AFTER `contact_phone`; +``` + +- [ ] **Step 4: Sync baseline CREATE in `docs/sql/shanxia2.0.sql`** + +在 `CREATE TABLE \`pl_transport_address\`` 中,于 `` `contact_phone` varchar(32) DEFAULT NULL COMMENT '联系电话', `` 之后插入: + +```sql + `notes` varchar(500) DEFAULT NULL COMMENT '注意事项', +``` + +(勿改 INSERT 语句列清单,除非一并补 `notes` 值;现有 INSERT 未列 `notes` 时依赖列默认 NULL,保持 INSERT 不动即可。) + +- [ ] **Step 5: Model** + +在 `PlTransportAddress` 中 `contact_phone` 后增加: + +```python + notes = Column(String(500), nullable=True, comment="注意事项") +``` + +- [ ] **Step 6: Schema** + +`TransportAddressBase` 增加: + +```python + notes: Optional[str] = Field(default=None, max_length=500, description="注意事项") +``` + +`TransportAddressUpdate` 增加: + +```python + notes: Optional[str] = Field(default=None, max_length=500) +``` + +(Read 继承 Base,自动带上。) + +- [ ] **Step 7: API create + export** + +`create_transport_address` 构造 `PlTransportAddress(...)` 时增加: + +```python + notes=payload.notes, +``` + +`ADDRESS_EXPORT_COLUMNS` 在联系电话与状态之间插入: + +```python + ExportColumn(title="注意事项", field="notes"), +``` + +Update 已用 `model_dump(exclude_unset=True)` + `setattr`,Schema 有字段即可,无需改 update 循环。 + +- [ ] **Step 8: Run schema tests — expect PASS** + +```bash +cd backend && source venv/bin/activate && pytest tests/test_pl_transport_address_notes_schema.py -v +``` + +Expected: PASS + +- [ ] **Step 9: Apply DDL on local DB**(实现者环境) + +```bash +# 按本地 .env 连接执行 migrations 文件;示例: +mysql -h ... -u ... -p ... < docs/sql/migrations/2026-09-02-pl-transport-address-notes.sql +``` + +Expected: 成功;重复执行会因列已存在失败(一次性迁移,可接受)。 + +- [ ] **Step 10: Commit** + +```bash +git add docs/sql/migrations/2026-09-02-pl-transport-address-notes.sql \ + docs/sql/shanxia2.0.sql \ + backend/app/models/pl_models.py \ + backend/app/schemas/pl/transport_address.py \ + backend/app/api/pl/transport_address.py \ + backend/tests/test_pl_transport_address_notes_schema.py +git commit -m "$(cat <<'EOF' +feat(pl): add notes column on transport address library + +Persist address-level precautions for later fill into plan load/delivery notes. +EOF +)" +``` + +--- + +### Task 3: 前端类型 + 地址组件 apply 带 notes + +**Files:** +- Modify: `web-admin/src/api/pl/index.ts` +- Modify: `web-admin/src/components/business/pl-address-with-library/index.vue` + +- [ ] **Step 1: Extend TS types** + +`TransportAddress` 与 `TransportAddressPayload` 增加: + +```ts + notes?: string +``` + +(放在 `contactPhone` 与 `status`/`remark` 之间或紧挨 contact 字段均可,保持可读。) + +- [ ] **Step 2: Extend apply payload + applyAddressRow** + +`PlAddressApplyPayload`: + +```ts +export type PlAddressApplyPayload = { + address: string + lng: number | null + lat: number | null + contact?: string + notes?: string +} +``` + +在 `applyAddressRow` 中,拼装 contact 之后: + +```ts + const notesText = (row.notes || '').trim() + if (notesText) { + payload.notes = notesText + } +``` + +`handleClear` **不要**传 `notes`(保持清空地址不清注意事项)。 + +- [ ] **Step 3: Commit** + +```bash +git add web-admin/src/api/pl/index.ts \ + web-admin/src/components/business/pl-address-with-library/index.vue +git commit -m "$(cat <<'EOF' +feat(web-admin): pass address library notes through apply payload + +Allow load/delivery sections to receive notes when an address is selected. +EOF +)" +``` + +--- + +### Task 4: 装货 / 送货 patchAddress 空才写 + +**Files:** +- Modify: `web-admin/src/components/business/pl-plan-load-section/index.vue` +- Modify: `web-admin/src/components/business/pl-plan-delivery-section/index.vue` + +- [ ] **Step 1: Load section** + +Import: + +```ts +import { resolveAddressNotesFill } from '@/utils/pl-address-notes-fill' +``` + +更新 `patchAddress`: + +```ts + function patchAddress(fields: PlAddressApplyPayload) { + const partial: Partial = { + address: fields.address, + lng: fields.lng, + lat: fields.lat + } + if (fields.contact !== undefined) { + partial.contact = fields.contact + } + const nextNotes = resolveAddressNotesFill(props.modelValue.notes, fields.notes) + if (nextNotes !== undefined) { + partial.notes = nextNotes + } + patch(partial) + } +``` + +- [ ] **Step 2: Delivery section** + +同样 import `resolveAddressNotesFill`,更新 `patchDeliveryAddress`: + +```ts + function patchDeliveryAddress(index: number, fields: PlAddressApplyPayload) { + const delivery = props.modelValue[index] + const partial: Partial = { + address: fields.address, + lng: fields.lng, + lat: fields.lat + } + if (fields.contact !== undefined) { + partial.contact = fields.contact + } + const nextNotes = resolveAddressNotesFill(delivery?.notes, fields.notes) + if (nextNotes !== undefined) { + partial.notes = nextNotes + } + patchDelivery(index, partial) + } +``` + +- [ ] **Step 3: Commit** + +```bash +git add web-admin/src/components/business/pl-plan-load-section/index.vue \ + web-admin/src/components/business/pl-plan-delivery-section/index.vue +git commit -m "$(cat <<'EOF' +feat(web-admin): fill load/delivery notes from address when empty + +Apply library notes only if the stop notes field is currently blank. +EOF +)" +``` + +--- + +### Task 5: 选择弹窗嵌套表单可维护 notes + +**Files:** +- Modify: `web-admin/src/components/business/pl-transport-address-select-dialog/index.vue` + +- [ ] **Step 1: Form model + UI** + +`addressForm` 增加 `notes: ''`。 + +在联系电话与备注之间增加: + +```vue + + + +``` + +- [ ] **Step 2: reset / fill / payload** + +`resetAddressForm`:`notes: ''` +`fillAddressForm`:`notes: row.notes || ''` +`buildPayload`: + +```ts + notes: addressForm.notes.trim() || undefined, +``` + +列表**不加**注意事项列(spec 非目标)。 + +- [ ] **Step 3: Commit** + +```bash +git add web-admin/src/components/business/pl-transport-address-select-dialog/index.vue +git commit -m "$(cat <<'EOF' +feat(web-admin): edit address library notes in select dialog + +Allow create/update of notes while picking an address for a plan stop. +EOF +)" +``` + +--- + +### Task 6: 地址库管理页表单 / 列表 / 查看 + +**Files:** +- Modify: `web-admin/src/views/pl/transport-address/index.vue` + +- [ ] **Step 1: listColumnDefs** + +在 `contactPhone` 与 `status` 之间增加: + +```ts + { prop: 'notes', label: '注意事项' }, +``` + +- [ ] **Step 2: 表格列** + +在联系电话列与状态列之间增加: + +```vue + +``` + +- [ ] **Step 3: formData + 表单 UI** + +`formData` 增加 `notes: ''`。 + +联系电话与备注之间: + +```vue + + + +``` + +reset / openEdit 赋值 `notes`;submit payload: + +```ts + notes: formData.notes.trim() || undefined, +``` + +- [ ] **Step 4: 查看弹窗** + +`viewSections` 在备注前增加: + +```ts + { label: '注意事项', value: d.notes || '—', long: true }, +``` + +- [ ] **Step 5: Commit** + +```bash +git add web-admin/src/views/pl/transport-address/index.vue +git commit -m "$(cat <<'EOF' +feat(web-admin): manage transport address notes on library page + +Expose notes in list, form, and view dialog for address master data. +EOF +)" +``` + +--- + +### Task 7: 验证与图谱 + +- [ ] **Step 1: 后端单测** + +```bash +cd backend && source venv/bin/activate && pytest tests/test_pl_transport_address_notes_schema.py -v +``` + +Expected: PASS + +- [ ] **Step 2: 前端单测** + +```bash +cd web-admin && node --import tsx --test src/utils/pl-address-notes-fill.test.ts +``` + +Expected: PASS + +- [ ] **Step 3: 手工验收(对照 spec §8)** + +1. 管理页新增地址,填写注意事项,保存后列表/查看可见。 +2. 运输计划新增:装货注意事项为空 → 选该地址 → 注意事项带入。 +3. 先手填注意事项再选地址 → 不覆盖。 +4. 地址无 notes → 不改表单。 +5. 送货段同样验证;下拉与弹窗选择一致。 +6. 清空地址 → 注意事项仍在。 +7. 备注字段与注意事项互不串写;联系方式回填仍正常。 + +- [ ] **Step 4: 更新图谱** + +```bash +./scripts/update-graph.sh all +# 或分别:graphify update . (仓库规则) +``` + +- [ ] **Step 5: Commit graphify(若有变更)** + +```bash +git add graphify-out backend/graphify-out web-admin/graphify-out 2>/dev/null || true +git status +# 若有图谱文件变更再 commit +git commit -m "chore: update graphify after transport address notes" +``` + +--- + +## Spec coverage checklist + +| Spec 要求 | Task | +|-----------|------| +| DDL `notes` + 基线 SQL | Task 2 | +| Model/Schema/API/导出 | Task 2 | +| 空才写回填规则 | Task 1 + 4 | +| apply 链 / 所有 PlAddressWithLibrary | Task 3 + 4 | +| 选择弹窗表单可编辑 notes、列表不加列 | Task 5 | +| 管理页表单/列表/查看 | Task 6 | +| 不清空 notes、不改 pref、不搜 notes | Task 3 clear / 未改 q / 未改 pref | +| 验收 | Task 7 | + +## Placeholder / consistency self-review + +- 无 TBD;函数名统一 `resolveAddressNotesFill`。 +- Payload 字段名统一 `notes`(与联系方式 `contact` 并列)。 +- 后端字段 `notes` / 前端 `notes`(无 alias 差异)。