GET/api/v1/admin/topic-placements
管理员Cookie,ADMIN_POSTS_READ,HTTPSJSON 响应接入指南 ↗

读取App顶部话题配置

请求参数

无路径参数、业务查询参数或业务正文。独立资源路径不占用既有话题代码。

独立管理员认证,需要ADMIN_POSTS_READ;OWNER与VIEWER均可读取,返回四语运营配置,不包含用户资料。Origin须为当前后台源,HttpOnly Cookie由浏览器管理。本接口只读,不要求写请求的X-Admin-CSRF,不生成配置审计。

公共请求头强制校验客户端类型、平台、版本、构建、渠道、安装和请求追踪。Accept-Language支持中英日韩,未知或缺省回退英文;仅message随请求语言变化,titles与hints仍返回完整四语。JSON使用AES/JWE,GET空正文信封放在X-Budyoo-JWE。始终要求HTTPS,不适用App开发HTTP例外。

请求示例

以下UUID、昵称、时间和数值均为合成示意;按加密协议对实际路径、查询串和本次头生成信封,不能直接发送占位密文。变量由统一网络层提供,切勿关闭TLS校验。

curl --request GET "$ADMIN_ORIGIN/api/v1/admin/topic-placements" \
  -H "Accept-Language: zh-CN" \
  -H "X-Client-Type: admin" \
  -H "X-Platform: web" \
  -H "X-App-Version: 1.0.0" \
  -H "X-App-Build: 1" \
  -H "X-Channel: admin_web" \
  -H "X-Device-Id: 33333333-3333-4333-8333-333333333333" \
  -H "X-Request-Id: $REQUEST_UUID" \
  -H "X-Request-Timestamp: $NOW_MILLIS" \
  -H "Origin: $ADMIN_ORIGIN" \
  -H "Cookie: __Secure-budyoo_admin=$ADMIN_COOKIE" \
  -H "X-Budyoo-Encryption: jwe-v1" \
  -H "Accept: application/jose" \
  -H "X-Budyoo-JWE: $REQUEST_JWE"

成功响应

HTTP200;外层使用公共信封,code=SUCCESS、message本地化、errors=[]。

字段 类型与可空性 说明
data.items array,非空 同一数据库读取快照下固定4项,按下表顺序返回;不分页,不受话题列表分类或搜索影响
data.items[].key string,非空 稳定展示位置代码,枚举见下表
data.items[].topic TopicDetail或null 当前实际使用的话题完整配置;字段类型、限制、时间和并发版本见互动共享模型“话题与目录”
顺序 key App位置 内容来源
1 inspiration 今日灵感 稳定话题代码window
2 travel 去看看世界 稳定话题代码travel
3 language 认识新朋友 稳定话题代码practice
4 hot 今日热门话题 当前featured=true且可展示的话题,可与前面的位置共用同一话题

前三个位置对应当前App既有固定入口,本接口不新增可调整的位置绑定。话题不存在或不可展示时topic=null,热门未配置时同样为null;不省略位置、不伪造默认话题。以下为合成完整示例,排序数和文案不代表运行配置:

{
  "code": "SUCCESS",
  "message": "操作成功",
  "data": {
    "items": [
      {
        "key": "inspiration",
        "topic": {
          "id": "window",
          "category": "daily",
          "titles": {
            "zh-CN": "窗外风景",
            "en": "Window views",
            "ja": "窓の外の景色",
            "ko": "창밖 풍경"
          },
          "hints": {
            "zh-CN": "窗外风景",
            "en": "Window views",
            "ja": "窓の外の景色",
            "ko": "창밖 풍경"
          },
          "iconKey": "budyoo_topic_soft_window",
          "featured": true,
          "sortOrder": 0,
          "reviewStatus": "APPROVED",
          "reviewReason": null,
          "version": 1,
          "createdAt": "2026-11-09T00:00:00Z",
          "updatedAt": "2026-11-09T00:00:00Z"
        }
      },
      {
        "key": "travel",
        "topic": {
          "id": "travel",
          "category": "travel",
          "titles": {
            "zh-CN": "旅行日记",
            "en": "Travel diary",
            "ja": "旅日記",
            "ko": "여행 일기"
          },
          "hints": {
            "zh-CN": "旅行日记",
            "en": "Travel diary",
            "ja": "旅日記",
            "ko": "여행 일기"
          },
          "iconKey": "budyoo_topic_soft_travel",
          "featured": false,
          "sortOrder": 1,
          "reviewStatus": "APPROVED",
          "reviewReason": null,
          "version": 1,
          "createdAt": "2026-11-09T00:00:00Z",
          "updatedAt": "2026-11-09T00:00:00Z"
        }
      },
      {
        "key": "language",
        "topic": {
          "id": "practice",
          "category": "language",
          "titles": {
            "zh-CN": "一起练口语",
            "en": "Practice together",
            "ja": "一緒に会話練習",
            "ko": "함께 회화 연습"
          },
          "hints": {
            "zh-CN": "一起练口语",
            "en": "Practice together",
            "ja": "一緒に会話練習",
            "ko": "함께 회화 연습"
          },
          "iconKey": "budyoo_topic_soft_practice",
          "featured": false,
          "sortOrder": 2,
          "reviewStatus": "APPROVED",
          "reviewReason": null,
          "version": 1,
          "createdAt": "2026-11-09T00:00:00Z",
          "updatedAt": "2026-11-09T00:00:00Z"
        }
      },
      {
        "key": "hot",
        "topic": {
          "id": "window",
          "category": "daily",
          "titles": {
            "zh-CN": "窗外风景",
            "en": "Window views",
            "ja": "窓の外の景色",
            "ko": "창밖 풍경"
          },
          "hints": {
            "zh-CN": "窗外风景",
            "en": "Window views",
            "ja": "窓の外の景色",
            "ko": "창밖 풍경"
          },
          "iconKey": "budyoo_topic_soft_window",
          "featured": true,
          "sortOrder": 0,
          "reviewStatus": "APPROVED",
          "reviewReason": null,
          "version": 1,
          "createdAt": "2026-11-09T00:00:00Z",
          "updatedAt": "2026-11-09T00:00:00Z"
        }
      }
    ]
  },
  "errors": []
}

失败响应

HTTP code 处理
400 BAD_REQUEST / INVALID_CLIENT_HEADERS 检查请求格式和必填公共头
401 UNAUTHORIZED 管理员身份无效、过期或安装不匹配
403 FORBIDDEN 读取权限或来源不合法
426 HTTPS_REQUIRED 使用符合后台协议的HTTPS入口
503 SERVICE_UNAVAILABLE 读取失败,保留编辑草稿并允许稍后重试,不显示旧配置为当前状态

公共JWE错误与网关限流见加密协议和入口限制。固定code不翻译,不能把未认证的网关错误正文当成成功业务响应。

接入说明

后台将这四个位置单独展示,图片、四语标题和引导语共用既有话题保存接口及其expectedVersion,不另设审核或发布步骤。写入仍需ADMIN_POSTS_WRITE、CSRF与同事务审计;同一话题用于多个位置时,保存后同时生效。热门话题沿用既有唯一featured约束,不通过此只读接口切换。

保存成功后刷新本接口和当前话题列表;普通列表搜索与分页只刷新列表。读取失败时不继续提供旧版本编辑按钮,显示明确错误与重试入口。并发冲突和写入结果不确定时继续使用原有核对流程。

实现:AdminTopicPlacementController、AdminTopicService、TopicManagementService。验证:TopicPlacementsIntegrationTest覆盖固定映射、完整四语、筛选隔离、保存后App与多个位置同步、今日话题切换与空配置、历史不可展示记录、只读角色、匿名、Origin和公共头;2026-11-09服务器完整833项测试全部通过,其中本接口5项回归通过;Node类型检查和Vite构建通过。配置写入仅在隔离测试数据库验证,真实后台仅做只读页面验收。