上传用户头像#

验证状态：已源码核验、未联调；适用基线：源码归纳 @ 2026-09-14

用途与场景#

上传当前登录用户的头像图片（jpg/png，≤300KB）。服务端写入文件存储并立即更新用户 portraitUrl，返回公开路径。当前 Web「编辑资料」页选择文件后立即上传，再把返回路径随资料保存提交。

使用位置#

页面/功能	角色或空间分支
编辑资料页头像上传	登录用户；前端先校验 MIME（仅 jpeg/png）

端点#

POST /main-service/system-api/user-center/user/uploadAvatar — 上传当前登录用户的头像图片（jpg/png，≤300KB）

端点全量事实（参数、请求/响应字段、错误码、权限点）见清单层 user-center · user 用户；业务语义（wire 惯例、限频、租户声明等）见用户中心业务 · user 用户。

动线与完成判据#

status=200 且 data 为路径字符串表示上传与 portraitUrl 更新同步完成（非受理语义）。Web 拿到路径后仅写入表单值，需再提交修改个人基础信息（其当前 wire 存在尾随空格缺口）才完成资料闭环——但 portraitUrl 已在本次上传时被服务端同步更新。

错误与边界#

错误最终出口（认证/业务拒绝/请求校验）见错误响应差异。重复上传覆盖同名文件并删除另一种扩展名的旧头像（幂等）。getOneByUsernameCache 缓存导致「刚创建的用户立刻上传头像」的可见性未联调。

调用关系与资源清理#

无长连接资源。头像读取走 /files 静态路径（无中心鉴权）；资料表单闭环见修改个人基础信息。

已知缺口#

头像文件经 /files 无鉴权公开（持有 URL 即可访问）——与下载设备文件同一静态服务边界；getOneByUsernameCache 写后一致性未联调。