保存兴趣标签¶
请求参数¶
OWNER可写、OWNER及VIEWER可读,服务端每次重新核验权限。仅HTTPS,独立Cookie;八项公共请求头固定admin/web/admin_web,所有写操作均校验同源Origin及X-Admin-CSRF。JSON接口必须真实JWE;只有明确的图标上传/读取/丢弃入口不套JSON信封。
| 位置/字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| path.id | string | 是 | 目录中读取的稳定分类/标签ID,不可改写 |
| 正文字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| names | object | 是 | 恰好zh-CN/en/ja/ko四个键;每项原输入1–40个UTF-16单元,trim后非空,不允许控制字符 |
| enabled | boolean | 是 | 保存即生效;停用保留历史资料,不允许新选 |
| sortOrder | integer | 是 | 0–100000,较小优先;同序按稳定ID排序 |
| groupId | string | 是 | 已存在分类ID,最多32字符;停用分类下标签可维护,但实际不可选 |
| iconId | UUID string | 是 | 已存在图标,来自目录或成功上传响应;不接收任意图标地址 |
| expectedVersion | integer(int64) | 是 | 使用本对象读取版本,非负;过期409,重读后确认,不自动重试覆盖 |
请求是全量配置保存,未列字段拒绝;修改必须提交所有可写字段。分类最多30个、标签最多500个,包含停用项。通过enabled管理可用状态,不提供分类/标签物理删除。
请求示例¶
import {createJweEncryption} from '../../examples/budyoo-encryption.mjs';
const codec = createJweEncryption({baseUrl:location.origin});
const url = new URL('/api/v1/admin/interests/tags/meet',location.origin);
const encrypted = await codec.prepare({url,method:'PUT',body:{"groupId": "friends", "names": {"zh-CN": "跨国交友", "en": "Global friends", "ja": "国際交流", "ko": "글로벌 친구"}, "iconId": "2b9f5dc9-bcc2-5a81-a991-74cfe75393d2", "enabled": true, "sortOrder": 100, "expectedVersion": 0},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
}});
const response = await fetch(url,{method:'PUT',headers:encrypted.headers,body:encrypted.body,credentials:'same-origin',redirect:'error'});
const result = await encrypted.decode(response);
成功响应¶
HTTP200,合法请求ID回传X-Request-Id。目录及JSON响应Cache-Control:no-store。JSON外层JWE,以下为解密后正文。
{
"code": "SUCCESS",
"message": "操作成功。",
"data": {
"id": "meet",
"version": 1,
"catalogVersion": 1
},
"errors": []
}
id为实际稳定编号;version为本对象新版本,catalogVersion为目录整体新版本。界面接收后重新读取完整目录,不能把旧版本自动替换后重发未知结果。
失败响应¶
| 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 | 名称四语、长度、控制字符、版本或分类/图标引用非法 |
| 404 | NOT_FOUND | 待修改对象不存在 |
| 409 | INTEREST_CATALOG_CONFLICT/INTEREST_CATALOG_LIMIT | 并发版本冲突/目录容量达到上限 |
code固定不翻译,message中英日韩,未知/缺省回退英文;错误结构见公共协议。JSON错误沿用JWE认证响应。
接入说明¶
兴趣名称与图标由服务端维护,新增标签不要求Flutter预置对应翻译键或图片。完整目录及图标与注册/App/后台资料保存共用同一数据;只显示selectable=true项作为新选择,历史停用项可以通过完整元数据继续显示。新加入停用项返回400 INTEREST_UNAVAILABLE;原已选停用项可保留或取消,完成注册仍要求1–6个当前可选项。分类停用同时影响其全部标签;保存即生效,无单独发布按钮。
旧注册字典及后台旧资料字典保持原结构和旧分组映射,只返回原108项中当前可选的代码,不包含新建标签;完整新目录保留所有历史元数据。旧客户端仍依赖本地名称/图片,必须升级到完整目录接入才能显示后台新增或更名内容。读取失败显示重试,不能回退固定标签后提交;空可选目录须显示真实空态。
目录写入、整体版本及后台审计同事务,审计仅记录编号、版本、启停与大小摘要,不记录图标字节;图标存储于数据库,随数据库备份。服务器隔离PostgreSQL/Redis已通过551项完整回归,新增22项覆盖初始6类/108项与全部108个实际图标、四语/英文回退、分类/标签新建修改、换图与素材库、停用准入、注册完成前复核、版本冲突、上传配额、独立权限/CSRF/JWE、审计失败真实回滚,以及V25旧资料升级后原昵称/版本/注册步骤/兴趣ID保持。未在运行库创建测试用户、改选真实用户兴趣或创建演示标签。前端接入以Flutter和Java-web实际验收为准。