读取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构建通过。配置写入仅在隔离测试数据库验证,真实后台仅做只读页面验收。