修改密码

1. 接口定位

• 接口名称: 修改密码
• 所属域: client/account
• 业务目标: 为已登录用户或管理员修改账户密码，并在成功后使现有登录态失效

2. 请求定义

• Method: POST
• Path: /account/password/change
• Content-Type: 推荐 application/json（服务端按 JSON body 解析，当前未对该请求头做强校验）
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 必填，需要通过 Header token 传入有效登录令牌
• 幂等性: 非幂等（会更新密码、使 token 失效，并触发 IM 侧强制离线）

3. 请求参数

Header 参数

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

Body 参数

字段	必填	类型	说明
userID	条件必填	string	目标用户 ID；管理员必填，普通用户可不传
currentPassword	条件必填	string	当前密码；普通用户修改自己的密码时应传，管理员可跳过
newPassword	是	string	新密码

字段约束

• newPassword 必填。
• newPassword 不能与 currentPassword 相同。
• 普通用户:
  • userID 为空时，服务端会按当前 token 对应用户处理。
  • 若显式传 userID，必须等于当前登录用户 ID。
  • 必须通过当前密码校验。
• 管理员:
  • 必须显式传 userID。
  • 可以跳过 currentPassword 校验。
• 为了让 API 层的 IM 强制离线动作明确命中目标用户，建议调用时始终显式传入 userID。

4. 响应结构

通用响应包裹

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

data 字段

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

5. 业务规则

• 请求先经过 CheckToken 中间件解析并写入操作者身份。
• 服务端会根据 token 身份区分普通用户自助修改与管理员代改密码。
• 普通用户只能修改自己的密码，且必须校验当前密码。
• 管理员可以直接修改指定用户密码，无需校验旧密码。
• 密码修改成功后，服务端会立即使该用户的 Chat Token 失效。
• API 层随后会调用 IM 强制离线接口，将该用户从 IM 侧踢下线。
• 本接口不会返回新的 token，修改成功后应重新登录。

6. 错误码与失败场景

错误码	场景	典型报错
1001	未传 token	token is empty
1001	newPassword 为空	newPassword is empty / new password must be set
1001	新旧密码相同	new password == current password
1001	管理员未传 userID	user id must be set
1002	普通用户尝试修改他人密码	no permission change other user password
1002	普通用户当前密码错误	current password is wrong
1004	目标用户不存在	RecordNotFoundError

7. 示例

fetch 请求示例

fetch("http://localhost:10008/account/password/change", {
  method: "POST",
  headers: {
    operationID: "550e8400-e29b-41d4-a716-446655440001",
    token: "eyJhbGciOiJIUzI1NiIs...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    userID: "2817364510",
    currentPassword: "OldP@ssw0rd",
    newPassword: "N3wP@ssw0rd",
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "userID": "2817364510",
  "currentPassword": "OldP@ssw0rd",
  "newPassword": "N3wP@ssw0rd"
}

成功响应示例

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

失败响应示例

{
  "errCode": 1002,
  "errMsg": "NoPermissionError",
  "errDlt": "current password is wrong"
}

8. 时序流程

1. 中间件解析 token 并注入操作者身份。
2. 解析请求并校验目标用户与密码字段。
3. 服务端根据操作者角色确定可修改的目标用户。
4. 普通用户场景校验当前密码。
5. 更新目标用户密码。
6. 使该用户现有 Chat Token 失效。
7. API 层调用 IM 强制离线。
8. 返回统一成功响应。

9. 变更记录

• 2026-03-31: 首版发布，明确了普通用户与管理员的差异、token 失效与 IM 离线行为，并纠正了本接口不会返回 20002 的实现事实。