docs: add transport address notes fill implementation plan

Break the approved design into TDD-friendly tasks covering DDL, API, apply chain, and address UIs.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
zlwuandCursor committed 2026-09-02 11:55:56 +08:00
1 parent 209f27606e
commit ed96976090
1 file changed
+594
@@ -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<PlanLoadForm> = {
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<PlanDeliveryForm> = {
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
<el-form-item label="注意事项" class="form-col-span-2">
<el-input
v-model="addressForm.notes"
type="textarea"
:rows="2"
maxlength="500"
show-word-limit
placeholder="注意事项(可选,选中地址时可带入装/送货)"
/>
</el-form-item>
```
- [ ] **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
<el-table-column
v-if="isColumnVisible('notes')"
prop="notes"
label="注意事项"
min-width="160"
show-overflow-tooltip
/>
```
- [ ] **Step 3: formData + 表单 UI**
`formData` 增加 `notes: ''`。
联系电话与备注之间:
```vue
<el-form-item label="注意事项" class="form-col-span-2">
<el-input
v-model="formData.notes"
type="textarea"
:rows="2"
maxlength="500"
show-word-limit
placeholder="注意事项(可选)"
/>
</el-form-item>
```
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 差异)。