51 lines
5.8 KiB
Markdown
51 lines
5.8 KiB
Markdown
# 用户端地址管理开发与验证
|
||
|
||
操作时间：2026-09-07。操作类型：扩展。影响模块：用户地址、个人中心、商城下单。
|
||
|
||
## 变更前后
|
||
|
||
此前地址入口只弹出详细地址输入框，缺少列表、联系人、编辑、删除和默认切换；商城直接使用第一条地址和账户联系人。本次增加 `/addresses` 管理页及编辑页，下单显式选择地址，收货联系人随地址保存。
|
||
|
||
图 29 的顶部添加、地址卡片、默认标签、编辑区、服务说明和底部新增按钮均有对应组件；服务范围尚无可用的配置/判定契约，当前明确显示待气站确认，不能计作该项完成，也不把服务关系存在当作可配送证明。
|
||
|
||
## 代码与接口
|
||
|
||
- `apps/user_app/lib/domain/models/shipping_address.dart`：地址领域字段与列表手机号脱敏。
|
||
- `apps/user_app/lib/data/repositories/client_repository.dart`：新增 `shippingAddresses`、`saveShippingAddress`、`setDefaultAddress`、`deleteAddress`；保留旧 `addresses` 和 `addAddress`。
|
||
- `apps/user_app/lib/ui/features/address/addresses_page.dart`：列表、失败重试、默认切换、编辑及下单选择。
|
||
- `apps/user_app/lib/ui/features/address/address_edit_page.dart`：联系人、电话、地址、可选坐标、表单校验、稳定新增请求号、删除确认、未保存退出确认。
|
||
- `profile_page.dart`、`profile_edit_page.dart`、`shop_page.dart`、`app/router.dart`：接入管理和选择流程。
|
||
- `backend/api/internal/logic/client/user/address.go`：新增、更新、归档、设置默认；先锁当前账户行，再查地址归属及写入，事务失败回滚。列表函数仍在 `address_ticket.go`，旧工单逻辑保留。
|
||
- `backend/api/internal/models/user_address.go`：新增 `contact_name`、`contact_phone`、`request_no`；请求号不进入响应。
|
||
- `backend/api/cmd/cli/address_migration.go`：`migrate-user-address` 只执行上述三个新增字段及中文列注释，不运行全库 AutoMigrate、初始化或 seed。
|
||
|
||
| 方法 | 相对于 `/heqi/client/v1/user` 的路径 | 行为 |
|
||
| --- | --- | --- |
|
||
| GET | `/addresses` | 本账户未归档地址；兼容原数组结构 |
|
||
| POST | `/addresses` | 新增；可选 request_no 在本账户范围内幂等 |
|
||
| PUT | `/addresses/:identity` | 更新本人有效地址及独立联系人 |
|
||
| POST | `/addresses/:identity/default` | 原默认与新默认在同一事务切换 |
|
||
| DELETE | `/addresses/:identity` | 归档并取消默认；重复删除成功，订单快照保留 |
|
||
|
||
新增/更新字段：address、contact_name、contact_phone、longitude、latitude、is_default。新增还接受 request_no。省略联系人时兼容旧客户端，采用地址原值或账户值；历史空联系人在新页面要求补齐。坐标允许同时为空；有值时必须成对、有限且经度在 ±180、纬度在 ±90 内。新增重试返回原地址，不把后续已变更的默认状态重置。
|
||
|
||
## 环境与验证
|
||
|
||
- 本机 Go API 使用既有 `heqi_dev.yaml` 的远程 PostgreSQL、Redis；未使用 Docker 或本机数据库。新增三列的定向迁移已执行成功，旧行保留。
|
||
- 远程测试账户完成新增、同请求号重试、联系人持久化、编辑、设置默认、重复删除；测试地址已归档，原默认地址及列表数量已验证恢复。
|
||
- 用户端完整回归 52 项通过；地址专项覆盖空表单、失败草稿、同请求号重试、默认设置失败不假更新、删除确认。后续样式修改再跑地址专项通过。
|
||
- 后端专项验证坐标边界、他人地址拒绝、默认变更失败回滚、创建重试不重复写入。全库测试发现新字段缺少源代码中文注释，补齐后模型与用户逻辑测试通过。
|
||
- 资源契约同步与检查通过，48 个资源；新增 Client 路由有注册测试。
|
||
- 图 29 已生成 320、360、390、430 宽度及 1.0/1.3 文字缩放共 8 张截图，检查滚动后无溢出；截图是独立 Fixture，不是运行时数据。
|
||
- 最终 Go 全量测试、vet 和 Flutter 静态检查通过，Web 正式构建成功。浏览器已验证鉴权回跳、新增、编辑保存及列表真实刷新，并在 390×844 下查看实际页面。旧预览进程已停止后重新启动本机 API 与 Web；远程连接配置保持一致。
|
||
- 浏览器随后验证默认切换、恢复原默认及删除确认，最终只剩原地址；控制台无 error/warn。商城专项 `shop_address_selection_test.dart` 通过，确认前不写订单，提交选中地址的联系人，而非账号姓名/手机号。累计现有用户端 52 项加此专项 1 项通过。
|
||
- 视觉证据：[图 29 并排对照](视觉验收/A1/29_并排对照.png)。原稿左侧、实现右侧，仍有地图图标、字号及服务范围显示差异，当前不通过严格 1:1。
|
||
|
||
## 风险与剩余事项
|
||
|
||
本次核心文件行数：地址后端逻辑 173 行，地址模型 21 行，定向迁移 42 行，地址列表页 240 行，编辑页 232 行，地址领域模型 40 行。现有 CLI 扩展命令、Client 路由新增 3 条，资源契约生成物已同步；未添加新的运行依赖。
|
||
|
||
删除采用归档而非物理删除，不修改旧订单的地址快照；删除默认地址后不会自行选择另一地址。旧联系人为空的地址可以保留和设为默认，但下单选择时需先补齐联系人。坐标当前为手动录入，尚未接入地图定位；配送范围判定、原生端完整验证仍未完成。页面局部图标、字体与原稿仍需继续对齐，不能以接口或截图检查通过声称严格 1:1。
|
||
|
||
维护时使用现有远程开发环境配置运行 `go run ./cmd/cli migrate-user-address`，切勿为这一功能运行全库迁移。测试地址只使用指定开发测试账号，验证后归档测试记录并恢复原默认。新增接口的所有权校验必须保持在默认状态写入之前。
|