按文件号上传文件#

验证状态：已源码核验、未联调（无 app 调用图）；services 基线：源码归纳 @ 2026-09-14

用途与场景#

以「文件号」为键向当前登录用户名下的服务端存储目录上传一个文件，返回该文件的相对路径。App 侧可用于向账号关联存储上传附件类文件：同一个 fileNo 且同名扩展名的重复上传会覆盖旧文件，语义上适合「每号一文件」的固定槽位写入（区别于头像上传的 avatar.* 固定名）。

App 现役依据#

判定证据	内容
旧 app 文档收录记录	旧 app 文档仓在 docs/api/main-service/system-api/user-center/user/uploadByFileNo/ 收录本端点（完整页，含 curl 示例与测试截图），属 App 既有调用面
两代分工语义	/v1/retail 第二代无文件上传对应物；按文件号上传的现役通道只有本端点
后端持续维护迹象	所在 UserPlusController 2026-09-09 仍有认证链路修复提交，账号族主控制器持续维护

端点#

POST /main-service/system-api/user-center/user/uploadByFileNo — 按文件号上传文件到当前登录用户名下目录（multipart/form-data）。

端点全量事实（参数、请求/响应字段、错误码、权限点）见清单层 user-center · user 用户；落盘与覆盖规则、返回相对路径语义见用户中心业务 · user 用户。

动线与完成判据#

status=200 且 data 为 /user/{username}/{fileNo}.{ext} 形式的相对路径，表示文件已落盘（同名旧文件已被覆盖/替换）。返回值是存储相对路径，不直接可下载：实际下载需拼接 /files 静态服务前缀，对比头像上传自带 /files/ 前缀并回写 portraitUrl 的行为，本端点不回写用户资料、也不补前缀，App 侧需自行拼接后访问（/files 静态服务无鉴权，为已知部署缺口，归集见零售手册覆盖与缺口）。

错误与边界#

两个业务拒绝分支：空文件、文件号格式错误（HTTP 200 + status=422 族）；缺参走请求校验出口（HTTP 400 / status=1002 族）。判定口径见错误响应差异。fileNo 须为可识别的数字串（接受整数、小数、十六进制 0x 前缀等格式，纯非数字字符串一律拒绝）。App 侧对两个业务错误码之外应保留未知码兜底分支。存量甄别：旧 app 文档另收录过下载端点 GET /user/downloadByFileNo，该端点已从后端消失（全仓无实现），本页不收录该死端点。

调用关系与资源清理#

无客户端长连接资源需要释放。上传成功后 App 侧应保存返回的相对路径（下载时自行拼接 /files 前缀）；账号注销时用户个人空间数据被异步删除，但服务端文件目录的清理不在 UserDeactivateListener 数据删除范围内，文件残留行为未由源码闭合。

已知缺口#

未执行真实联调：无大小/类型限制意味着超大文件上传行为（容器层限制、磁盘配额）未由源码闭合；/files 无鉴权缺口的业务影响评估与多节点存储一致性归覆盖栏目缺口表。