用户资料 API（/user 身份能力域）

全量用户资料读写 JSON API — "数据在 UM，UI 在各应用" 的统一契约。

/user 是云集栈统一身份能力域（与 /oauth 协议域并列）。/user/profile 提供全量用户资料的读写，供登录后的各应用渲染品牌化资料页。它与 /oauth/userinfo（OIDC 只读标准端点）互补：前者给应用的「我的资料」页，后者给 OAuth 流程内的 RP 客户端。

基础信息

项目	值
网关	`https://api.yunjii.cn`
能力域	`/user/*`
数据格式	JSON
鉴权	`Authorization: Bearer <access_token>`（UM 签发的用户 JWT）
支持方法	`GET` / `PATCH` / `OPTIONS`

端点 1：读取资料

GET https://api.yunjii.cn/user/profile
Authorization: Bearer <access_token>

返回当前用户的完整资料。

响应（成功）

{
  "code": 0,
  "data": {
    "user_id": 1281,
    "openid": "o44iJ6sSDuFFEHHecRq1tSevM4fk",
    "login_type": "wx",
    "nickname": "张三",
    "avatar": "https://...",
    "email": "zhangsan@example.com",
    "username": "zhangsan",
    "gender": "male",
    "location": "北京",
    "phone": "138****1234",
    "status": 1,
    "referral_code": "D38B3A",
    "referrer_id": 0,
    "score": 0,
    "balance": 0,
    "created_at": "2026-07-16 22:35:32",
    "last_login_time": "2026-07-17 16:01:17",
    "last_login_ip": "127.0.0.1"
  }
}

字段说明见下方「字段与权限」。balance / score / phone / referral_code 等扩展字段是 /user/profile 相对 /oauth/userinfo 的增值部分。

端点 2：更新资料

PATCH https://api.yunjii.cn/user/profile
Authorization: Bearer <access_token>
Content-Type: application/json

请求体为 JSON 对象，仅可包含白名单字段，未知字段静默忽略（不报错、不泄露）。

{ "nickname": "新昵称", "gender": "female", "location": "上海" }

响应（成功）

{ "code": 0, "data": { "...": "更新后的完整资料" }, "msg": "资料已更新" }

可写字段白名单

字段	最长	格式	唯一性
`nickname`	50	—	—
`gender`	10	—	—
`location`	100	—	—
`phone`	11	`/^1[3-9]\d{9}$/`	全站唯一
`email`	128	`FILTER_VALIDATE_EMAIL`	全站唯一
`username`	32	—	全站唯一

只读字段（PATCH 不可修改）

user_id openid login_type avatar status referral_code referrer_id score balance created_at last_login_time last_login_ip

唯一性字段（phone/email/username）若与其他账号冲突，返回 errcode=409；格式错误返回 errcode=422。

错误响应

统一错误信封：

{ "code": -1, "errcode": <int>, "msg": "<string>" }

HTTP	errcode	说明
401	401	未提供 / 无效 / 过期的 access_token
405	405	仅支持 GET/PATCH/OPTIONS
422	422	字段格式错误（如邮箱/手机号格式）
409	409	唯一性冲突（phone/email/username 已被占用）

参考实现（UM 官网 dogfooding）

UM 官网 um.yunjii.cn/[locale]/user/profile 自身就是本端点的第一个消费方，证明闭环成立：

浏览器同源调用 GET/PATCH /api/user/profile；
服务端路由 next/app/api/user/profile/route.ts 取出 um_token cookie 中的 JWT，再以 Bearer 转发到 https://api.yunjii.cn/user/profile；
既避免跨域 CORS，又不把 JWT 暴露给前端 JS。

其他应用（music/win/vi 等）接入方式相同：在自己站内写资料页，用 Bearer token 调本端点 GET/PATCH，以自己的品牌色渲染同一份数据。