# 修改本人资料

更新日期：2026-10-25。API 根地址：`https://work.zingyang.com/api`。

## 1. 版本与上线状态

**token 定位改造已于 2026-10-25 部署生产，版本 65ddec15。** 当前客户端无需传 `id`，也不再要求 `system:user:setting:edit` 额外权限；旧客户端传入的 `id` 会被忽略。下文旧版说明仅用于兼容历史客户端和理解历史错误。

两种版本都只用于本人资料，不允许修改其他用户。个人资料属于账号，不是每个租户独立的一份资料。普通资料修改不消耗 AI 套餐额度。

## 2. 请求

```http
POST /sys/user/login/setting/userEdit
Content-Type: application/json
X-Access-Token: <平台token>
X-Tenant-Id: <当前已确认租户ID>
```

token 必须是平台登录取得的 token，不是 Apple identity token。继续沿用登录会话的租户上下文，不自行填其他租户。

新实现使用 Shiro 校验 token 后的登录身份，从服务端确定本人 ID；不会根据请求中的 `id` 或 `username` 选择更新对象。认证失败、账号不存在、停用或删除时不执行更新。

由 AI 工具代理修改资料时，须先取得用户明确授权，并携带 `X-Zing-Ai-Context: 1` 和 `X-Open-Confirm: confirmed`。正常页面操作不需要这两个 AI 标识头。

## 3. 入参字段

新实现仅允许以下字段更新；只提交本次需要修改的字段。

| 字段 | 类型 | 说明 |
|---|---|---|
| realname | string | 姓名 |
| nickname | string | 昵称 |
| avatar | string | 已上传并登记的头像地址，不是 fileId、二进制或上传签名地址 |
| sex | integer | 1 男、2 女；客户端使用这两个值 |
| birthday | string | `yyyy-MM-dd`，例如 `1995-08-16` |
| email | string | 保留现有 Admin 邮箱修改兼容；此接口本身不提供邮箱验证码验证 |
| sign | string | 保留 Admin 签名地址设置；现有前端用空字符串移除签名 |
| id | string | 旧版必传本人 ID；新版本忽略，不作为更新目标 |

新实现忽略用户名、手机号、密码、账号状态、租户归属、职位、审计字段等其他字段，不直接持久化请求实体。手机号和密码应使用对应的账号安全流程。

未修改字段请省略，不要把完整用户对象回传。不要假设 null 等于清空；当前没有通用的字段清空协议。

新版本最小请求：

```json
{"nickname":"新昵称"}
```

旧客户端请求仍然兼容（当前服务忽略 id）：

```json
{"id":"<当前用户ID>","nickname":"新昵称"}
```

```bash
curl --request POST 'https://work.zingyang.com/api/sys/user/login/setting/userEdit' \
  --header 'X-Access-Token: <平台token>' \
  --header 'X-Tenant-Id: <当前租户ID>' \
  --header 'Content-Type: application/json' \
  --data '{"id":"<当前用户ID>","nickname":"新昵称"}'
```

## 4. 成功响应

```json
{
  "success": true,
  "message": "更新个人信息成功",
  "code": 200,
  "result": "更新个人信息成功",
  "timestamp": 1792886400000
}
```

时间戳仅为示例。`result` 是提示字符串，不是更新后的用户对象。检查 `success == true` 且 `code == 200` 后，再读取本人资料更新客户端缓存。

## 5. 读取资料与头像上传

`GET /sys/user/login/setting/getUserData`：携带相同认证和租户头，无请求体；成功时 `result` 是当前用户资料对象。当前更新接口不依赖该对象中的 `id`。

头像先按 [COS 上传指南](/ios-cos-upload/) 完成上传、登记，再把可用于展示的头像地址写入 `avatar`。上传受存储权益约束；上传完成不代表资料已经保存。不要提交 COS PUT 签名 URL 或临时凭据。

## 6. 错误处理与兼容

- 认证失败：检查 HTTP 状态及业务响应，按登录失效处理。新控制器对未认证或无效账号返回业务码 401；前置认证过滤器也可能先拒绝请求。
- 旧版本无编辑权限：业务码 510；新实现不再要求 `system:user:setting:edit`，但仍必须登录。
- 旧版本找不到入参 id：提示「未找到该用户数据」；id 属于他人：提示「只能修改自己的数据」。这两种旧版业务错误使用 500。
- 新实现不会用他人 id 修改他人；该字段被忽略，仍只更新 token 对应的本人。
- 新实现持久化返回失败时：`success=false`，提示「更新个人信息失败」。
- 日期解析、参数格式、数据库约束等异常按实际失败响应处理；不要把 HTTP 200 一律视作保存成功。
- 网络超时后先重新读取资料，不能假设一定未保存。

## 7. 实现与验证边界

既有调用方：Admin 个人设置、邮箱设置，以及 UniApp、CRM Uni、需求 App 的编辑资料页面。旧客户端继续传本人 id 可兼容新实现，无需同步强制升级。

本文依据 `SysUserController#userEdit/#getUserData`、`SysUser` 和实际客户端核对。本轮不会通过生产账号进行测试写入。九个服务已切至 65ddec15，认证读取及未登录更新拒绝检查通过；未对生产资料执行成功写入用例。