更新用户资料

1. 接口定位

• 接口名称: 更新用户资料
• 所属域: client/user
• 业务目标: 允许用户更新自己的个人信息（昵称、头像、性别等），管理员可修改任何用户信息

2. 请求定义

• Method: POST
• Path: /user/update
• Content-Type: 推荐 application/json（服务端按 JSON body 解析，当前未对该请求头做强校验）
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 必填，需要通过 Header token 传入有效的登录令牌
• 幂等性: 非幂等（会修改用户数据库记录）

3. 请求参数

Header 参数

字段	必填	类型	说明
operationID	是	string	链路追踪 ID
token	是	string	登录令牌

Body 参数

字段	必填	类型	说明
userID	是	string	目标用户 ID
nickname	否	string	用户昵称
faceURL	否	string	头像 URL
gender	否	int32	性别：0 未设置，1 男，2 女
phoneNumber	条件必填	string	手机号；修改时必须与 areaCode 同时提供
areaCode	条件必填	string	手机区号；修改时必须与 phoneNumber 同时提供
email	否	string	邮箱
account	否	string	账户名，只允许字母数字组合

字段约束

• phoneNumber 和 areaCode 必须同时提供或同时不提供。
• areaCode 必须以 + 开头且为数字（如 +86）；若不带 +，服务端会自动补齐。
• phoneNumber 必须为纯数字。
• account 只允许字母数字组合；修改时会检查重复注册。
• email 修改时会检查格式有效性和重复注册。
• 至少保留一个登录凭证（Account/Phone/Email），不能全部删除。
• 普通用户只能修改自己的信息（UserID 必须等于令牌对应的操作者 ID）。
• 普通用户不能修改 registerType 字段（仅管理员可修改）。

用户类型与权限

用户类型	权限
普通用户	只能修改自己的信息，不能修改 registerType
管理员	可以修改任何用户的所有字段，包括 registerType

4. 响应结构

通用响应包裹

字段	类型	说明
errCode	int	错误码，0 表示成功
errMsg	string	错误简述
errDlt	string	错误详情
data	any	业务数据

data 字段

• 本接口成功时返回空对象（无业务数据返回）。

5. 业务规则

• 修改前会校验用户是否存在，不存在则返回账户不存在错误。
• 修改 phoneNumber 时检查新手机号是否已被其他账户注册。
• 修改 areaCode 时检查格式（必须以 + 开头且后续为数字）。
• 修改 account 时检查是否已被其他账户注册。
• 修改 email 时检查格式和重复注册。
• 修改后会同时更新本地数据库（chat）和 OpenIM SDK 系统，保持两端数据一致。
• 普通用户尝试修改他人信息或修改 registerType 时返回无权限错误。

6. 错误码与失败场景

错误码	场景	典型报错
1001	UserID 为空或格式错误	user id is empty
1001	phoneNumber 和 areaCode 不同时设置	phone number and area code must be set at the same time
1001	phoneNumber 为空但 areaCode 非空	area code is provided but phone number is not
1001	areaCode 格式错误（不以 + 开头）	area code must start with +
1001	areaCode 非数字	area code must be number
1001	phoneNumber 非数字	phone number must be number
1001	email 格式非法	email must be right
1001	account 非字母数字	account must be alphanumeric
1001	登录凭证全部被删除	cannot delete all credentials
1004	账户不存在	user not found
20003	手机号已被其他账户注册	PhoneAlreadyRegister
20004	账户已被其他账户注册	AccountAlreadyRegister
20014	邮箱已被其他账户注册	EmailAlreadyRegister
1002	普通用户尝试修改他人信息	no permission
1002	普通用户尝试修改 registerType	registerType can only be changed by admin

7. 示例

fetch 请求示例

fetch("http://localhost:10008/user/update", {
  method: "POST",
  headers: {
    operationID: "550e8400-e29b-41d4-a716-446655440001",
    token: "eyJhbGciOiJIUzI1NiIs...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    userID: "user123",
    nickname: "张三",
    faceURL: "https://example.com/avatar.jpg",
    gender: 1,
    areaCode: "+86",
    phoneNumber: "13800138000",
    email: "user@example.com",
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "userID": "user123",
  "nickname": "张三",
  "faceURL": "https://example.com/avatar.jpg",
  "gender": 1,
  "areaCode": "+86",
  "phoneNumber": "13800138000",
  "email": "user@example.com"
}

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {}
}

失败响应示例（手机号已注册）

{
  "errCode": 20003,
  "errMsg": "PhoneAlreadyRegister",
  "errDlt": "phone number has been registered by another account"
}

失败响应示例（无权限）

{
  "errCode": 1002,
  "errMsg": "NoPermission",
  "errDlt": "normal user cannot update other user's information"
}

8. 时序流程

1. 验证令牌并提取操作者用户身份（普通用户或管理员）。
2. 校验请求参数（userID、phoneNumber/areaCode 配对、格式等）。
3. 查询目标用户是否存在。
4. 检查权限：普通用户只能修改自己的信息，不能修改 registerType。
5. 检查新凭证（phone/account/email）是否已被其他账户注册。
6. 更新用户信息到本地数据库。
7. 同步更新到 OpenIM SDK 系统。
8. 返回成功响应。

9. 变更记录

• 2026-03-31: 首版发布，包含完整的字段定义、权限规则、错误场景和 fetch 示例。