简介

本开发文档面向 DouPHP 小程序“联系人管理”模块，聚焦收货地址的增删改查、默认地址设置、地址分类与批量操作等能力。文档覆盖：

• 联系人创建与编辑界面：姓名、电话、身份证（预约场景）、省市区、详细地址、标签、是否默认等字段的输入与校验。
• 地址管理业务逻辑：默认地址互斥、列表展示、删除、选择默认地址。
• 数据同步机制：订单结算页与用户地址本的联动，确保多端一致性。
• 用户体验优化：省市区级联、快速选择常用地址、从结算页直达并返回等。

项目结构

小程序侧联系人管理由以下页面与脚本组成：

• 列表页：contact.wxml + contact.ts
• 新增页：contact_create.ts（含省市区级联）
• 编辑页：contact_edit.ts（含省市区回显与级联）
• 后端接口：订单结算相关控制器与服务提供联系人列表、选择默认地址等能力；数据库升级脚本维护 user_contact 表结构。

graph TB
subgraph "小程序前端"
C["contact.ts<br/>列表/默认/删除"]
CC["contact_create.ts<br/>新增+省市区级联"]
CE["contact_edit.ts<br/>编辑+省市区回显"]
CW["contact.wxml<br/>列表渲染"]
end
subgraph "后端服务"
OC["CheckoutController.php<br/>联系人列表/选择"]
OS["CheckoutService.php<br/>业务逻辑"]
OR["order.php<br/>路由定义"]
end
subgraph "数据层"
DB["user_contact<br/>收货地址表"]
end
C --> OC
CC --> OC
CE --> OC
OC --> OS
OS --> DB
CW --> C

核心组件

• 联系人列表（contact.ts + contact.wxml）
  • 功能：登录态检查、加载联系人列表、设置默认地址、删除地址、跳转编辑页。
  • 关键交互：点击“设为默认”调用设置默认接口；点击删除调用删除接口；点击编辑跳转编辑页。
• 新增联系人（contact_create.ts）
  • 功能：省市区三级联动、表单提交（姓名、电话、身份证、省市区、详细地址、标签、是否默认）。
  • 特殊流程：若 from=checkout，保存后直接返回结算页并携带 contact_id。
• 编辑联系人（contact_edit.ts）
  • 功能：根据 id 获取联系人详情并回显省市区；支持修改并提交更新；from=checkout 时返回结算页。
• 后端接口（CheckoutController/Service）
  • 功能：提供联系人列表 JSON、选择默认地址、校验归属用户等；在下单流程中读取/同步默认收货信息。

架构总览

小程序通过 http 服务调用后端路由，后端由控制器接收请求，交由服务层处理业务逻辑，最终读写 user_contact 表。

sequenceDiagram
participant U as "用户"
participant MP as "小程序页面"
participant API as "后端控制器"
participant SVC as "服务层"
participant DB as "数据库(user_contact)"
U->>MP : 打开联系人列表/新增/编辑
MP->>API : GET/POST 联系人接口
API->>SVC : 调用业务方法
SVC->>DB : 查询/更新/插入
DB-->>SVC : 结果集
SVC-->>API : 结构化响应
API-->>MP : JSON 数据
MP->>MP : 渲染列表/提示/跳转

详细组件分析

联系人列表（contact.ts + contact.wxml）

• 列表加载：onShow 触发登录校验后调用 loadData，GET 获取联系人列表并渲染到 contact_list。
• 设置默认：setDefault 调用 POST 设置默认接口，成功后刷新列表。
• 删除：del 调用 POST 删除接口，成功后刷新列表。
• 视图：contact.wxml 展示姓名、电话、身份证或完整地址、是否默认标记，并提供“设为默认”和“编辑”入口。

flowchart TD
Start(["进入列表页"]) --> Auth{"已登录?"}
Auth -- 否 --> Login["提示登录/跳转登录"]
Auth -- 是 --> Load["加载联系人列表"]
Load --> Render["渲染列表"]
Render --> Action{"用户操作"}
Action -- 设为默认 --> SetDefault["调用设置默认接口"]
Action -- 删除 --> Delete["调用删除接口"]
Action -- 编辑 --> Edit["跳转到编辑页"]
SetDefault --> Reload["刷新列表"]
Delete --> Reload
Reload --> End(["结束"])

新增联系人（contact_create.ts）

• 省市区级联：通过 user.area 接口分别获取省、市、区列表，并在选择时联动清空下级。
• 表单提交：contactAction 收集 name、phone、id_card、province/city/district、address、tag、is_default，POST 提交。
• 结算页联动：当 from=checkout 时，保存成功后重定向至结算页并附带 contact_id。

sequenceDiagram
participant P as "新增页"
participant A as "area 接口"
participant S as "store 接口"
P->>A : 获取省份列表
A-->>P : 省份数组
P->>A : 选择城市(按父级)
A-->>P : 城市数组
P->>A : 选择区县(按父级)
A-->>P : 区县数组
P->>S : 提交联系人数据
S-->>P : 成功(可能返回 contact_id)
P->>P : 根据 from 决定跳转

编辑联系人（contact_edit.ts）

• 数据回显：onLoad 通过 user.contact.edit 获取联系人详情，并初始化省市区下拉框当前值。
• 级联回显：若已有 city/district，则依次加载对应下级列表并选中。
• 提交更新：contactAction 将修改后的字段 POST 到 user.contact.update，from=checkout 时返回结算页。

sequenceDiagram
participant E as "编辑页"
participant EE as "edit 接口"
participant A as "area 接口"
participant UU as "update 接口"
E->>EE : 获取联系人详情(id)
EE-->>E : 联系人数据
E->>A : 加载省份(带current)
A-->>E : 省份列表
E->>A : 加载城市(按父级,current)
A-->>E : 城市列表
E->>A : 加载区县(按父级,current)
A-->>E : 区县列表
E->>UU : 提交更新
UU-->>E : 成功
E->>E : 根据 from 跳转

后端接口与业务逻辑（订单结算联动）

• 路由：order.php 定义了 checkout 相关路由，包含 contact_list 等。
• 控制器：CheckoutController 提供联系人列表 JSON，用于结算页动态加载；并对所选联系人进行归属校验。
• 服务：CheckoutService 在下单流程中读取/同步默认收货信息，保证订单与地址本的一致性。

sequenceDiagram
participant O as "订单结算页"
participant C as "CheckoutController"
participant S as "CheckoutService"
participant D as "user_contact"
O->>C : 获取联系人列表(contact_list)
C->>S : 组装联系人数据
S->>D : 查询用户地址本
D-->>S : 地址列表
S-->>C : 结构化数据
C-->>O : 返回JSON
O->>C : 选择默认/使用某地址
C->>S : 校验并设置默认
S->>D : 更新默认标记
D-->>S : 成功
S-->>C : 成功
C-->>O : 返回结果

数据模型与字段说明（user_contact）

• 关键字段：name（姓名）、phone（电话）、id_card（身份证，预约场景）、province/city/district（省市区）、address（详细地址）、tag（标签）、is_default（是否默认）、created_at（创建时间）。
• 历史变更：升级脚本对 phone、id_card、default 字段进行了更名与类型调整，确保与现有代码一致。

依赖关系分析

• 小程序页面依赖 http 服务与 route 工具，统一封装接口路径。
• 列表/新增/编辑页面均依赖 authStore 做登录态校验。
• 后端通过路由将请求分发到控制器，再由服务层执行业务逻辑与数据访问。
• 订单结算页与联系人模块共享同一套地址数据源，保证一致性。

graph LR
CT["contact.ts"] --> H["http.js"]
CC["contact_create.ts"] --> H
CE["contact_edit.ts"] --> H
H --> R["route.js"]
R --> OC["CheckoutController.php"]
OC --> OS["CheckoutService.php"]
OS --> DB["user_contact"]

性能考虑

• 列表分页与懒加载：建议在列表页实现分页与滚动加载更多，减少首屏数据量。
• 省市区级联缓存：可对 area 接口返回的省市区数据进行本地缓存，避免重复请求。
• 默认地址互斥更新：设置默认地址时采用原子更新策略，避免并发导致状态不一致。
• 图片与资源：列表中的头像/图标按需加载，避免阻塞渲染。

故障排查指南

• 未登录或登录态失效：页面会先执行 ensureLogin，若失败应引导用户重新登录。
• 网络请求失败：catch 分支统一使用 douMsg 提示错误，可结合日志定位接口异常。
• 省市区为空：检查 area 接口返回与当前选择项是否正确传递 parent/current。
• 默认地址未生效：确认后端是否更新了 is_default，并刷新列表。
• 结算页返回异常：检查 from=checkout 的重定向参数 contact_id 是否正确传递。

结论

本模块以小程序页面为核心，配合后端控制器与服务层，实现了联系人地址的完整生命周期管理。通过省市区级联、默认地址互斥、结算页联动等设计，兼顾了易用性与数据一致性。后续可在列表分页、区域数据缓存、默认地址原子更新等方面进一步优化体验与性能。

附录

• 字段映射与校验建议
  • 姓名：必填，长度限制。
  • 电话：必填，手机号格式校验。
  • 身份证：预约场景必填，正则校验。
  • 省市区：至少选择到区，空值需提示。
  • 详细地址：必填，非空校验。
  • 标签：可选，用于分类（如“家”、“公司”）。
  • 是否默认：单选，默认地址唯一。
• 常见交互
  • 从结算页新增/编辑后返回结算页并自动选中该地址。
  • 列表页一键设为默认，其他地址自动取消默认。
  • 删除前二次确认，防止误删。