简介

本文件为用户资料管理模块的完整API参考，覆盖以下能力：

• 用户个人信息获取、更新
• 修改密码、退出登录
• 头像上传
• 联系方式（地址簿）增删改查、设为默认
• 数据验证规则（字段格式、必填项、完整性）
• 隐私保护（敏感信息脱敏、访问权限控制）
• 多端一致性与同步建议

项目结构

用户资料相关API位于API层控制器中，业务逻辑下沉至服务层，路由集中声明。认证通过中间件在HTTP边界完成。

graph TB
Client["客户端"] --> MW["UserAuthMiddleware<br/>鉴权中间件"]
MW --> Route["路由 user.php<br/>user/*, user/contact/*"]
Route --> UC["UserController<br/>个人资料/密码/头像/文件"]
Route --> CC["ContactController<br/>地址簿CRUD"]
UC --> PS["ProfileService<br/>资料装配/更新/昵称占用检测"]
CC --> CS["ContactService<br/>地址簿读写/默认地址"]
PS --> DB[("数据库: user / user_contact")]
CS --> DB

核心组件

• 用户资料控制器：提供会员中心首页、注册/登录/找回密码、资料编辑保存、修改密码、第三方账号管理、地区数据、文件上传、头像上传、登录态检查等。
• 联系人（地址簿）控制器：提供地址列表、新增、编辑、删除、设为默认、JSON列表与详情。
• 资料服务：负责资料装配、更新、昵称占用检测、默认收货地址快照合并等。
• 联系人服务：负责地址簿分页、新增/更新/删除、默认地址设置、JSON列表与详情、contact_id解析。
• 认证中间件：从请求头提取Bearer Token，校验登录态与工作身份，未授权返回统一错误。

架构总览

• 认证与授权：所有需要登录的接口均受中间件保护，未携带有效Token或Token失效将返回401；涉及工作身份的接口会进一步校验并可能返回403。
• 路由组织：以 user 为根路径，子资源 contact 独立分组；所有动作通过声明式路由映射到控制器方法。
• 分层设计：控制器仅做参数校验与响应组装，核心逻辑委托服务层；服务层再调用模型与基础设施（存储、审计日志等）。

sequenceDiagram
participant C as "客户端"
participant M as "鉴权中间件"
participant R as "路由"
participant U as "UserController"
participant S as "ProfileService"
participant D as "数据库"
C->>M : 携带Authorization : Bearer <token>
M-->>C : 401/403(失败时终止)
M->>R : 通过鉴权
R->>U : 调用 edit_post / upload_avatar 等
U->>S : updateProfile / 头像处理
S->>D : 写入 user / user_contact
D-->>S : 成功
S-->>U : 结果
U-->>C : ApiResponse.success(...)

详细组件分析

用户资料接口（UserController）

• 会员中心首页：返回基础资料、登录状态、VIP/工作/分销详情等聚合数据。
• 注册/登录/找回密码：表单与提交接口，含验证码校验、邮箱短信通道选择、推广关系登记。
• 资料编辑：
  • 读取可编辑资料（包含默认地址快照、头像URL、性别选项等）。
  • 保存资料：对昵称、联系方式、电话、姓名、国家、省份、地址、邮编进行校验；若昵称变更则检测是否被其他用户占用；最终调用服务层更新用户主表与默认收货地址。
• 修改密码：校验旧密码与新密码，成功后要求重新登录。
• 退出登录：吊销当前设备的API会话Token。
• 第三方账号管理：列出可用插件、支持解绑。
• 省市区数据：根据类型返回初始化或级联列表。
• 文件上传/删除：通用文件框，支持草稿模式与图片尺寸、水印、业务字段标记。
• 头像上传：按用户维度存储并回写头像字段，返回文件URL。
• 登录态检查：用于小程序侧判断当前Token有效性。

flowchart TD
Start(["edit_post 入口"]) --> V["参数校验<br/>nickname/phone/address/postcode等"]
V --> N{"昵称是否变更?"}
N -- 是 --> Check["检测昵称是否被其他用户占用"]
N -- 否 --> Build["构建更新数据"]
Check --> |占用| Err["抛出领域异常(重复昵称)"]
Check --> |未占用| Build
Build --> Update["调用 ProfileService.updateProfile"]
Update --> Done(["返回成功"])
Err --> End(["结束"])
Done --> End

地址簿接口（ContactController）

• 列表：分页返回当前用户的地址条目。
• 新增/编辑：校验名称、电话、地址，中文环境下强制手机号格式；可选启用省市区必填；插入或更新后返回ID。
• 删除：按用户隔离删除指定地址。
• 设为默认：将指定地址设为默认，同时清空其他默认。
• JSON列表/详情：供订单/预约等场景下拉选择与详情展示。
• contact_id解析：优先使用传入ID，否则回退到默认或最新地址。

sequenceDiagram
participant C as "客户端"
participant CC as "ContactController"
participant CS as "ContactService"
participant DB as "数据库"
C->>CC : POST /api/user/contact/store
CC->>CC : 校验 name/phone/address/province/city
CC->>CS : insertContact(userId, data)
CS->>DB : 写入 user_contact
DB-->>CS : 新ID
CS-->>CC : ID
CC-->>C : {contact_id, 消息}

认证与权限（UserAuthMiddleware）

• 从请求头 Authorization: Bearer <token> 解析API会话Token。
• 未登录返回401，无工作身份返回403。
• 注入上下文后由后续控制器执行具体业务。

依赖关系分析

• 控制器依赖服务：UserController 依赖 ProfileService、UserService、UserPasswordService、ApiTokenService 等；ContactController 依赖 ContactService。
• 服务依赖基础设施：ProfileService 通过 User 模型、UserContactQuery、审计日志等；ContactService 通过 UserContact 模型。
• 路由与中间件：所有受保护的接口经 UserAuthMiddleware 前置校验，路由文件集中声明 user 与 user/contact 的动作集合。

graph LR
UC["UserController"] --> PS["ProfileService"]
UC --> UPS["UserPasswordService"]
UC --> ATS["ApiTokenService"]
CC["ContactController"] --> CS["ContactService"]
PS --> UQ["UserContactQuery"]
CS --> UM["UserContact Model"]

性能与一致性

• 数据一致性
  • 资料更新：服务层将收货相关字段上写到默认收货地址行，用户主表只保留非收货字段，减少冗余与冲突。
  • 默认地址：设为默认时会先清空其他默认，保证唯一性。
• 性能要点
  • 列表分页：地址簿采用分页查询，避免一次性加载大量数据。
  • 头像与文件：上传时限制图片宽度、支持草稿模式，降低带宽与存储压力。
• 多端一致性建议
  • 客户端缓存策略：本地缓存用户资料与地址簿，网络失败时降级显示；更新成功后主动刷新。
  • 冲突解决：服务端为权威源；客户端在提交前尽量复用服务端最新数据（如昵称可用性检查）。
  • 离线编辑：利用文件草稿机制暂存内容，待正式提交时持久化。

故障排查指南

• 401 未登录
  • 检查请求头是否携带有效的 Authorization: Bearer <token>。
  • 确认Token未过期且未被注销（logout会吊销）。
• 403 无工作身份
  • 该接口需要工作身份，请确认当前用户具备相应角色。
• 资料更新失败
  • 常见原因：昵称重复、非法字符、必填项缺失。查看返回的错误字段定位问题。
• 地址簿操作失败
  • 中文环境需符合手机号格式；省市区开启时需填写对应字段；删除需确保属于当前用户。
• 头像上传失败
  • 检查文件类型、大小、服务器存储配置；确认已正确传递 avatar 字段。

结论

本模块通过清晰的控制器-服务分层、严格的参数校验与统一的鉴权中间件，提供了完整的用户资料管理能力。结合默认地址快照、文件草稿与分页优化，兼顾了易用性与性能。建议在客户端实现合理的缓存与重试策略，以保证多端数据一致性与用户体验。

附录：接口参考

认证与会话

• 获取登录态
  • 方法：GET
  • 路径：/api/user/check_login_state
  • 说明：检查当前Bearer Token是否有效，返回登录状态。
  • 鉴权：需要登录。
  • 响应：包含登录状态字段。
• 退出登录
  • 方法：POST
  • 路径：/api/user/logout
  • 说明：吊销当前设备API会话Token。
  • 鉴权：需要登录。
  • 响应：空数据。

个人资料

• 会员中心首页
  • 方法：GET
  • 路径：/api/user/index
  • 说明：返回基础资料、登录状态、VIP/工作/分销详情等聚合数据。
  • 鉴权：需要登录。
  • 响应：包含 title、welcome、link_user_center、if_connect_plugin、dou.user、dou.auth、dou.vip、dou.work、dou.distribution。
• 获取可编辑资料
  • 方法：GET
  • 路径：/api/user/edit
  • 说明：返回可编辑的用户资料（含默认地址快照、头像URL、性别选项等）。
  • 鉴权：需要登录。
  • 响应：包含 title、user_info。
• 保存资料
  • 方法：POST
  • 路径：/api/user/edit_post
  • 说明：更新昵称、联系方式、电话、姓名、国家、省份、地址、邮编等；若昵称变更会检测占用。
  • 鉴权：需要登录。
  • 请求体关键字段：nickname、contact/first_name/last_name、phone、country、province、address、postcode、sex、defined（自定义字段）。
  • 响应：成功返回空数据；失败返回字段级错误。
• 修改密码
  • 方法：POST
  • 路径：/api/user/password_post
  • 说明：校验旧密码与新密码，成功后返回要求重新登录。
  • 鉴权：需要登录。
  • 请求体关键字段：old_password、password、password_confirmation。
  • 响应：包含 relogin=true 及成功消息。
• 头像上传
  • 方法：POST
  • 路径：/api/user/upload_avatar
  • 说明：上传头像并更新用户头像字段，返回文件URL。
  • 鉴权：需要登录。
  • 请求体：multipart/form-data，字段名为 avatar。
  • 响应：包含 file_url。

地址簿（联系方式）

• 地址列表
  • 方法：GET
  • 路径：/api/user/contact
  • 说明：分页返回当前用户地址条目。
  • 鉴权：需要登录。
  • 响应：包含 title、contact_list、pager。
• 新增地址
  • 方法：POST
  • 路径：/api/user/contact/store
  • 说明：新增地址，中文环境强制手机号格式；可选启用省市区必填。
  • 鉴权：需要登录。
  • 请求体关键字段：name、phone、address、province、city、district、id_card、tag、is_default。
  • 响应：包含 contact_id 与成功消息。
• 编辑地址
  • 方法：POST
  • 路径：/api/user/contact/update
  • 说明：更新地址，校验规则同新增。
  • 鉴权：需要登录。
  • 请求体关键字段：id、name、phone、address、province、city、district、id_card、tag。
  • 响应：包含 contact_id 与成功消息。
• 删除地址
  • 方法：POST
  • 路径：/api/user/contact/destroy
  • 说明：删除指定地址。
  • 鉴权：需要登录。
  • 请求体关键字段：id。
  • 响应：成功消息。
• 设为默认
  • 方法：POST
  • 路径：/api/user/contact/set
  • 说明：将指定地址设为默认，同时清空其他默认。
  • 鉴权：需要登录。
  • 请求体关键字段：id。
  • 响应：成功消息。
• JSON地址列表
  • 方法：POST
  • 路径：/api/user/contact/list_json
  • 说明：供订单/预约等下拉选择。
  • 鉴权：需要登录。
  • 请求体关键字段：contact_id（可选，传0取默认）。
  • 响应：包含 contact_list。
• 地址详情
  • 方法：POST
  • 路径：/api/user/contact/info
  • 说明：返回单条地址详情。
  • 鉴权：需要登录。
  • 请求体关键字段：contact_id（可选，传0取默认）。
  • 响应：包含 contact。

数据验证规则

• 资料更新（edit_post）
  • nickname：必填，禁止非法字符；若变更需检测是否被其他用户占用。
  • contact/first_name/last_name：必填，禁止非法字符（按语言切换）。
  • phone：必填，禁止非法字符。
  • country/province/address/postcode：允许为空，但需通过非法字符校验。
• 地址簿（store/update）
  • name/phone/address：必填，禁止非法字符；中文环境下 phone 需符合手机号格式。
  • province/city/district：当启用地区功能时为必填。
• 修改密码（password_post）
  • password/password_confirmation：必填，符合密码强度规则。

隐私与安全

• 敏感信息脱敏
  • 资料聚合接口不返回密码、令牌、支付码等凭证类字段。
• 访问权限控制
  • 所有需要登录的接口受鉴权中间件保护；未登录返回401；无工作身份返回403。
• 安全输入
  • 资料与地址写入前进行XSS过滤与非法字符校验。
• 文件安全
  • 头像与文件上传支持图片宽度限制、水印、草稿模式与业务字段标记，防止滥用。

典型请求与响应示例（描述性）

• 个人资料更新
  • 请求：POST /api/user/edit_post，包含 nickname、phone、address、postcode、sex、defined 等。
  • 成功：返回空数据。
  • 失败：返回字段级错误，如 nickname 重复、非法字符等。
• 头像上传成功
  • 请求：POST /api/user/upload_avatar，multipart/form-data，字段 avatar。
  • 成功：返回 file_url。
• 信息修改失败
  • 请求：POST /api/user/edit_post，包含不符合规则的字段。
  • 失败：返回错误信息与字段提示。