POST/api/v1/admin/interests/icons
独立管理员Cookie、HTTPS、ADMIN_INTERESTS_WRITE、写CSRF;文件不套JWEJSON 响应接入指南 ↗

上传兴趣标签图标

请求参数

OWNER可写、OWNER及VIEWER可读,服务端每次重新核验权限。仅HTTPS,独立Cookie;八项公共请求头固定admin/web/admin_web,所有写操作均校验同源Origin及X-Admin-CSRF。JSON接口必须真实JWE;只有明确的图标上传/读取/丢弃入口不套JSON信封。

multipart/form-data仅一个必填file;实际JPEG/PNG/WebP,输入≤1MiB(1048576字节),边长≤4096、总像素≤1600万。真实解码、去除元数据,最长边缩至1024,输出PNG也须≤1MiB;SVG上传不接受。每管理员每小时最多30次成功上传,目录图标总数最多2000个;未使用图标可显式丢弃。Nginx此精确上传路径整包上限2MiB,其余JSON限制不变。

请求示例

const body = new FormData();
body.append('file', fileInput.files[0]);
const response = await fetch('/api/v1/admin/interests/icons', {
  method: 'POST', credentials: 'same-origin', redirect: 'error',
  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,'X-Request-Id':crypto.randomUUID(),
    'X-Request-Timestamp':String(Date.now()), 'X-Admin-CSRF':csrfToken},
  body,
});
const result = await response.json();

浏览器自动管理Cookie及同源Origin;先检查HTTP状态和Content-Type,失败不得当成可展示图像。不要手工设置multipart的Content-Type边界。

成功响应

HTTP200,合法请求ID回传X-Request-Id。

{
  "code": "SUCCESS",
  "message": "操作成功。",
  "data": {
    "id": "2b9f5dc9-bcc2-5a81-a991-74cfe75393d2",
    "contentType": "image/png",
    "size": 2048,
    "iconUrl": "/api/v1/admin/interests/icons/2b9f5dc9-bcc2-5a81-a991-74cfe75393d2"
  },
  "errors": []
}

id是随后保存标签使用的iconId,size为规范化PNG实际字节数,iconUrl为后台同源读取路径;上传尚未绑定标签,目录版本不变化。

失败响应

HTTP code 条件/处理
400 INVALID_CLIENT_HEADERS/BAD_REQUEST/VALIDATION_FAILED 公共头、UUID、正文类型或必填字段不合法
426 HTTPS_REQUIRED 不满足当前HTTPS策略
429 TOO_MANY_REQUESTS 网关限流,按公共协议处理
503 SERVICE_UNAVAILABLE 数据库/Redis依赖不可用,不回退本地标签
401/403 UNAUTHORIZED/FORBIDDEN/ADMIN_CSRF_INVALID Cookie失效、权限不足、来源或CSRF错误
400 INVALID_INTEREST_ICON 非真实允许图片、超体积/尺寸/像素或规范化后超过1MiB
409/429 INTEREST_CATALOG_LIMIT/INTEREST_ICON_LIMIT 图标总容量/管理员小时上传额度达到上限
413 PAYLOAD_TOO_LARGE 入口或Servlet拒绝过大整包,入口响应不具有JWE认证,可能非JSON

code固定不翻译,message中英日韩,未知/缺省回退英文;错误结构见公共协议。文件入口错误为普通JSON,不能当成图像或成功结果。

接入说明

兴趣名称与图标由服务端维护,新增标签不要求Flutter预置对应翻译键或图片。完整目录及图标与注册/App/后台资料保存共用同一数据;只显示selectable=true项作为新选择,历史停用项可以通过完整元数据继续显示。新加入停用项返回400 INTEREST_UNAVAILABLE;原已选停用项可保留或取消,完成注册仍要求1–6个当前可选项。分类停用同时影响其全部标签;保存即生效,无单独发布按钮。

旧注册字典及后台旧资料字典保持原结构和旧分组映射,只返回原108项中当前可选的代码,不包含新建标签;完整新目录保留所有历史元数据。旧客户端仍依赖本地名称/图片,必须升级到完整目录接入才能显示后台新增或更名内容。读取失败显示重试,不能回退固定标签后提交;空可选目录须显示真实空态。

目录写入、整体版本及后台审计同事务,审计仅记录编号、版本、启停与大小摘要,不记录图标字节;图标存储于数据库,随数据库备份。服务器隔离PostgreSQL/Redis已通过551项完整回归,新增22项覆盖初始6类/108项与全部108个实际图标、四语/英文回退、分类/标签新建修改、换图与素材库、停用准入、注册完成前复核、版本冲突、上传配额、独立权限/CSRF/JWE、审计失败真实回滚,以及V25旧资料升级后原昵称/版本/注册步骤/兴趣ID保持。未在运行库创建测试用户、改选真实用户兴趣或创建演示标签。前端接入以Flutter和Java-web实际验收为准。