5.8 KiB
用户端地址管理开发与验证
操作时间：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 并排对照。原稿左侧、实现右侧，仍有地图图标、字号及服务范围显示差异，当前不通过严格 1:1。
风险与剩余事项
本次核心文件行数：地址后端逻辑 173 行，地址模型 21 行，定向迁移 42 行，地址列表页 240 行，编辑页 232 行，地址领域模型 40 行。现有 CLI 扩展命令、Client 路由新增 3 条，资源契约生成物已同步；未添加新的运行依赖。
删除采用归档而非物理删除，不修改旧订单的地址快照；删除默认地址后不会自行选择另一地址。旧联系人为空的地址可以保留和设为默认，但下单选择时需先补齐联系人。坐标当前为手动录入，尚未接入地图定位；配送范围判定、原生端完整验证仍未完成。页面局部图标、字体与原稿仍需继续对齐，不能以接口或截图检查通过声称严格 1:1。
维护时使用现有远程开发环境配置运行 go run ./cmd/cli migrate-user-address，切勿为这一功能运行全库迁移。测试地址只使用指定开发测试账号，验证后归档测试记录并恢复原默认。新增接口的所有权校验必须保持在默认状态写入之前。