后台保存用户资料与相册¶
请求参数¶
面向后台网页,要求可信HTTPS、独立HttpOnly Cookie及OWNER的ADMIN_USER_PROFILES_WRITE权限。App Bearer不能调用。JSON请求与响应必须使用真实JWE。写操作要求Origin等于后台源并带会话X-Admin-CSRF。
公共头见请求头,四语见公共响应,身份见后台协议。客户端类型和图片UUID本身不授予权限。
路径userId必填,为目标用户UUID;不存在返回404。无查询参数。 | 正文字段 | 类型 | 必填 | 约束与部分更新语义 | | --- | --- | --- | --- | | expectedVersion | integer(int64) | 是 | 非负;使用读取响应的version,冲突409后重读,不自动覆盖 | | country | string | 否 | 目录内小写国家代码;不传/null保留;实际变更仅限目标用户为有效VIP | | nickname | string | 否 | 输入1–8个UTF-16代码单元,trim后非空;不传/null保留 | | birthday | string(date) | 否 | 1900-01-01至服务端当天;不传/null保留 | | spokenLanguage | string | 否 | 字典内单个代码;不传/null保留;保存后须与learningLanguage不同 | | learningLanguage | string | 否 | 字典内单个代码;不传/null保留;保存后须与spokenLanguage不同 | | introduction | string | 否 | 输入最多30个UTF-16代码单元,保存时trim;空字符串清空,不传/null保留 | | avatarId | string | 否 | 本人上传头像UUID;空字符串清除引用,不传/null保留 | | interests | string[] | 否 | 1–6个不重复的字典代码,不能清空;不传/null保留 | | albumPhotoIds | string(UUID)[] | 否 | 0–9个不重复的本人有效照片;[]清空,不传/null保留 |
至少提供一个非null可编辑字段;仅版本号不是有效编辑。未知字段(包括gender、userId、registrationStatus、registrationStep、VIP字段)拒绝,不能通过后台修改只读属性。长度按UTF-16代码单元计算,表情可能占两个;以原输入长度校验后trim。
仅当前服务端有效VIP可以更改已注册资料的国家/地区;按目标用户权益判断,App和后台代改共用规则,不由渠道VIP门槛、管理员身份或客户端声明放行。country不传、null或与已保存值相同仍按原规则保存;首次注册选择国家不受此限制。非VIP实际变更返回HTTP403/PROFILE_COUNTRY_VIP_REQUIRED,整次PATCH不写资料、相册、兴趣、审核候选或版本,后台不写成功审计。到期、撤销、尚未生效均不算有效VIP;开发管理员测试覆盖沿用既有dev且非prod规则,权益读取失败返回503。
请求示例¶
示例UUID为合成数据;deviceId必须复用当前安装,不要每次新建。以下示例覆盖八项公共头;禁止日志输出Cookie或Bearer。
import {createJweEncryption} from '../../examples/budyoo-encryption.mjs';
const url = new URL('/api/v1/admin/users/11111111-1111-4111-8111-111111111111/profile', location.origin);
const headers = {
'Accept-Language': 'zh-CN',
'X-Client-Type': 'admin', 'X-Platform': 'web',
'X-App-Version': '1.0.0', 'X-App-Build': '1', 'X-Channel': 'admin_web',
'X-Device-Id': installationId, // 当前浏览器已持久保存的安装UUID
'X-Request-Id': crypto.randomUUID(), 'X-Request-Timestamp': String(Date.now()),
'X-Admin-CSRF': csrfToken, // 从加密会话响应取得,只保留内存
};
const codec = createJweEncryption({baseUrl: location.origin});
const encrypted = await codec.prepare({url, method: 'PATCH', headers, body: {"expectedVersion":0,"nickname":"合成用户","introduction":"喜欢旅行和摄影","interests":["photo","travel"],"albumPhotoIds":[]}});
const response = await fetch(url, {method: 'PATCH', headers: encrypted.headers,
body: encrypted.body, credentials: 'same-origin', redirect: 'error'});
const result = await encrypted.decode(response); // 必须认证解密后才使用业务结果
必须从已验证的HTTPS同源页面调用;Origin和Cookie由浏览器维护,不在脚本写入Cookie。实际前端统一封装接入另行完成。
成功响应¶
HTTP200,Cache-Control:no-store;合法请求ID回传。外层为JWE,下方是解密后的JSON。
{
"code": "SUCCESS",
"message": "操作成功。",
"data": {
"userId": "11111111-1111-4111-8111-111111111111",
"registrationStatus": "COMPLETE",
"version": 1,
"updatedAt": "2026-11-03T10:00:00Z",
"country": "cn",
"nickname": "合成用户",
"gender": "female",
"birthday": "2000-01-02",
"spokenLanguage": "zh",
"learningLanguage": "en",
"introduction": "喜欢旅行和摄影",
"avatarId": null,
"interests": [
"photo",
"travel"
],
"albumPhotoIds": [],
"moderation": {
"avatar": {
"status": "EMPTY",
"reviewId": null,
"reason": null,
"submittedAt": null,
"reviewedAt": null
},
"nickname": {
"status": "PENDING",
"reviewId": "00000000-0000-4000-8000-000000000002",
"reason": null,
"submittedAt": "2026-11-06T00:00:00Z",
"reviewedAt": null
},
"introduction": {
"status": "PENDING",
"reviewId": "00000000-0000-4000-8000-000000000003",
"reason": null,
"submittedAt": "2026-11-06T00:00:00Z",
"reviewedAt": null
},
"published": {
"avatarId": null,
"nickname": null,
"introduction": null
}
}
},
"errors": []
}
| data字段 | 类型 | 可空 | 说明 |
|---|---|---|---|
| userId | string(UUID) | 否 | 资料所属用户,不由请求体指定 |
| registrationStatus | string | 否 | INCOMPLETE/COMPLETE;只读,后台可读取未完成资料 |
| version | integer(int64) | 否 | 从0开始;每次编辑保存递增,下一次作为expectedVersion |
| updatedAt | string(date-time) | 否 | 带时区ISO 8601;仅展示,不能代替version |
| country | string | 是 | 249国家/地区目录的小写代码 |
| nickname | string | 是 | 新写入1–8个UTF-16代码单元;历史昵称按原值返回 |
| gender | string | 是 | male/female,注册后只读 |
| birthday | string(date) | 是 | YYYY-MM-DD,1900-01-01至服务端当天 |
| spokenLanguage | string | 是 | 字典中的单个我会的语言代码 |
| learningLanguage | string | 是 | 字典中的单个学习语言代码 |
| introduction | string | 是 | 最多30个UTF-16代码单元;编辑后允许空字符串 |
| avatarId | string(UUID) | 是 | 本人上传头像引用,无头像为null |
| interests | string[] | 否 | 按代码升序,完成账号保留1–6个 |
| albumPhotoIds | string(UUID)[] | 否 | 0–9张;保留旧照片相对顺序,新照片按提交顺序追加 |
失败响应¶
| HTTP | code | 条件 |
|---|---|---|
| 400 | INTEREST_UNAVAILABLE | 新加入停用标签,请刷新目录重新选择 |
| 400 | PROFILE_LANGUAGES_SAME | 我会的语言与想学习的语言相同,请重新选择不同的语言 |
| 400 | BAD_REQUEST/VALIDATION_FAILED/INVALID_PROFILE | 类型、日期、长度、字典、重复兴趣、缺少版本或未知字段 |
| 400 | INVALID_CLIENT_HEADERS | 公共头缺失、重复或格式错误 |
| 403 | PROFILE_COUNTRY_VIP_REQUIRED | 目标用户当前不是有效VIP,却提交不同的国家;保持原表单,不作为登录失效或VIP准入跳转 |
| 401 | UNAUTHORIZED | 未登录、会话失效或安装不匹配 |
| 403 | FORBIDDEN/ADMIN_CSRF_INVALID | 无对应权限、Origin或CSRF不符 |
| 404 | NOT_FOUND | 用户或归属范围内的图片不存在/已删除 |
| 426 | HTTPS_REQUIRED | 当前路径不允许明文HTTP |
| 503 | SERVICE_UNAVAILABLE | 数据库/Redis依赖暂不可用 |
| 409 | PROFILE_CONFLICT | expectedVersion过期;重读并由用户确认,禁止自动覆盖 |
| 409 | REGISTRATION_INCOMPLETE | 目标用户尚未完成注册,后台也不代为完成注册 |
| 403 | ACCOUNT_DISABLED | 目标账号被禁用 |
| 400 | INVALID_AVATAR/INVALID_PHOTO | 文件无效、已删除、跨用户或相册重复/超过9张 |
| 400/409 | 加密协议错误码 | JWE缺失、篡改、过期、重放,按公共加密协议处理 |
非VIP修改国家的中文失败示例:
{"code":"PROFILE_COUNTRY_VIP_REQUIRED","message":"仅VIP用户可以修改国家或地区。","data":null,"errors":[]}
错误结构示例:
{"code":"PROFILE_CONFLICT","message":"按Accept-Language返回中文、英文、日文或韩文提示","data":null,"errors":[]}
未知或缺省语言回退英文;code不翻译。字段校验明细在errors[].field/message。网关可能先返回429/413,不能当成认证过的JWE业务响应。
接入说明¶
新增moderation对象,三项avatar/nickname/introduction分别返回status、reviewId、reason、submittedAt及reviewedAt,另有published保存当前实际公开值。类型、可空范围、状态和示例见逐项资料审核。本人响应的原头像、昵称、签名继续表示本人提交内容;保存或注册完成只表示自动进入审核,公开页面只取最后通过值,首次无通过值使用默认头像/四语默认昵称/空签名。审核不新增注册步骤、不改变渠道VIP,其他字段或无变化保存不重复提审;清空头像或签名立即撤下。
兴趣选项由完整兴趣目录提供。新加入的标签须selectable=true;原已选停用项可保留或取消,取消后不能再加入,完成注册要求所选1–6项全部当前可选。分类停用同样影响其标签;不可选的新提交返回400 INTEREST_UNAVAILABLE,失败不改资料、版本或步骤。
我会的语言(spokenLanguage)与想学习的语言(learningLanguage)按服务端目录id比较,保存后的两项必须不同。PATCH仅传一项时,服务端在用户行锁内与已保存的另一项合并后校验;未提供或null保留,不能通过分次提交绕过。可在同次请求中交换两种不同语言。历史重复资料读取时保持原值,未修改语言的其他资料保存不强制清空;修改任一语言时必须修正重复。校验失败不保存资料、兴趣、版本或注册步骤。
重复语言返回HTTP400,code固定为PROFILE_LANGUAGES_SAME;message按Accept-Language支持中英日韩,未知语言回退英文,data=null、errors=[]。例如中文:
{"code":"PROFILE_LANGUAGES_SAME","message":"我会的语言和想学习的语言不能相同,请重新选择。","data":null,"errors":[]}
新编辑接口与注册草稿分开:不会回退registrationStep,不改变性别、身份或VIP。相册和兴趣在子页面只修改客户端草稿,点击资料页保存后一次事务提交。删除相册项使对应照片软删除;原有照片相对顺序保留,不支持手动排序或封面。头像替换只改变引用,旧头像不物理删除。
后台成功动作与审计同事务,审计失败回滚数据库修改;新上传文件按事务失败补偿。审计只记录动作、目标UUID、请求ID和版本/数量摘要,不保存生日、介绍、图片内容或Cookie。资料保存动作USER_PROFILE_UPDATE,头像上传USER_AVATAR_UPLOAD,相册上传USER_PHOTO_UPLOAD,暂存丢弃USER_PHOTO_DISCARD。
已通过服务器隔离PostgreSQL/Redis完整整合272项回归,包含并行国家目录改动;本批24项覆盖30/31字符、鉴权、字段白名单、相册归属与九张上限、并发版本、两端真实JWE、后台CSRF和审计回滚。真实Servlet验证上传10MiB与超限,隔离Nginx另通过8项媒体路径大小检查。实现位于profile、media及admin/users模块,跨业务只走api契约。已随账号列表整合版本部署,V9已应用且媒体网关已更新;后台账号列表已接入头像读取,Flutter与后台资料编辑/相册页面尚未接入。完整278项服务器整合回归通过;本次公网浏览器核对列表及头像,其他新写接口的验收范围仍为服务器隔离测试。物理文件清理、公开图片分发、审核、好友、钱包和聊天不在本批范围。
2026-11-05资料规则验证:服务器隔离PostgreSQL/Redis的529项完整回归通过;8项昵称用例及新增16项语言用例覆盖三条资料写入口、两种语言同次/单项重复、显式null合并、合法交换、失败不改资料/兴趣/版本/步骤、旧重复草稿完成前修正、历史资料非语言修改、领域调用与并发注册提交,以及四语/未知语言回退的真实JWE错误响应。未在运行库创建测试账号或修改真实用户资料。
2026-11-06服务器隔离PostgreSQL/Redis的clean verify共784项全部通过,零失败/错误/跳过;新增16项国家修改权限回归覆盖App、后台及领域入口的非VIP拒绝与原子回滚,省略/null/原值兼容、有效VIP即时放行、未生效/到期/撤销权益、开发测试覆盖设置及取消、首次注册选择国家、字段/版本校验、权益故障503,以及四语/未知及缺省英文的真实JWE响应。仅使用隔离合成账号和测试权益,未在运行库创建账号、发放VIP或修改用户资料;本轮不包含Flutter国家选择器界面改动。