OPOfflinePush / Admin
接口基准：当前工作区最新协议CURRENT · 2026-09-09

Frontend integration / current contract

离线推送
对接手册

本文只描述当前可接入协议：内容支持动态文章模板与直接英文文本，新增和编辑请求不含版本，取消只提交计划 ID，列表查询负责尽力同步当前页投递快照。

5 个主接口2 种内容来源Unix 秒无自动轮询
CONTRACT.CURRENT接入基线
01提交与计划快照包含 source / article_id / template_args
02add_rows / edit_rows 不包含 version
03delete_rows 为计划 ID 数组，不包含原因或版本
04列表加载时同步当前页非终态 Job，单条失败保留持久化快照
05PUSH_SYSTEM_TOPIC_REGISTERED_USERS（RegisteredUsers）不可提交；列表每页最多 50 条
01

最新接口契约

前端从零接入时，直接按下表构建请求模型、交互与校验。

能力当前契约前端实现要点
新增add_rows[] 传 id = 0 与完整表单请求行不定义 version
编辑edit_rows[] 传 id > 0 与完整表单仅开放给 OFFLINE_PUSH_PLAN_STATUS_SCHEDULED，请求行不定义 version
取消delete_rows: int64[]数组项只传正整数计划 ID，不设计原因或版本输入
内容MAILBOX_TASK_SOURCE_TEMPLATE / MAILBOX_TASK_SOURCE_TEXT按来源切换字段，并在切换时清空互斥字段
列表分页page_size 为 1–50选择器仅提供 20 / 50，建议默认 20
投递快照加载列表时尽力同步当前页使用“重新加载列表”，不设计独立同步按钮
赛事报名人群PUSH_SYSTEM_TOPIC_REGISTERED_USERS 不可提交选择器始终禁用并展示接口返回原因
02

接入主流程

首屏并行加载人群与计划；写操作返回逐行结果，随后重新加载列表获取当前状态和最新可用投递快照。

01初始化

并行请求 TopicList 与 List

02准备内容

模板或直接英文文本

03前置校验

人群、内容、Keys 与时间

04批量提交

add / edit / delete 分数组

05逐行反馈

按 index 映射每一行

06重新加载

当前页非终态 Job 同步

i
当前页同步不是轮询

页面不自动轮询。每次调用计划列表时，服务端查询本地台账后，以最多 10 路并发尽力同步当前页中已关联 Job 的非终态计划；单条同步失败不会让整个列表失败，也不会覆盖当前持久化快照。

03

内容来源决定表单结构

新提交必须明确传 MAILBOX_TASK_SOURCE_TEMPLATE = 1 或 MAILBOX_TASK_SOURCE_TEXT = 2；未指定来源会被拒绝。切换模式查看字段规则和可提交 JSON。

source必传1 / MAILBOX_TASK_SOURCE_TEMPLATE
article_id必传大于 0；只接受动态邮件模板文章
title必须为空模板标题来自文章多语言配置
subtitle必须为空模板正文作为推送副标题模板
template_args可选键为完整占位串；序列化后 ≤ 4096 字节
EN
模板必须有可用英文回退

发送前会把文章标题与正文的全部语言同步到推送配置；缺少可用英文内容时计划会失败。

请求体参考

切换来源并编辑示例字段

可交互
键必须是完整占位串0 / 4096 bytes
POST BODY · ADD_ROWS

          

        

        
配套依赖：如何加载动态文章模板 GET /admin.admin.v1.system.Content/ArticleList
  • page / page_size页码从 1 开始；单页最多 100
  • type = 6仅查询动态邮件模板文章
  • articles[].id提交为 OfflinePush 的 article_id
  • articles[].title_en可作为选择器主文案
QUERY · EXAMPLE
GET /admin.admin.v1.system.Content/ArticleList
  ?page=1
  &page_size=20
  &type=6

      


      

        
04
5 个主接口
从左侧选择接口。请求示例使用 snake_case 和数字枚举；若项目 HTTP SDK 对 proto 枚举采用字符串，请统一使用同表中的完整协议名。

        

          

            
            
            
            
            
          


          

            
GET
OfflinePushList
/admin.admin.v1.lobby.Message/OfflinePushList
分页查询当前站点计划，并在返回前尽力同步当前页已关联 Job 的非终态快照。

            
  • page必传，≥ 1
  • page_size必传，1–50；固定传合法值，建议 20
  • name计划名称模糊查询，最多 128 字符
  • status / job_status可选，分别为 OfflinePushPlanStatus / PushJobStatus；有效筛选值 1–7
  • topic可选，PushSystemTopic；有效筛选值 1–5
  • operator_id0 表示不筛选
  • create_time_start / endUnix 秒；同时存在时 start ≤ end
  • responselist[] + total
QUERY · EXAMPLE
GET .../OfflinePushList
  ?page=1
  &page_size=20
  &status=2
  &topic=3

            
!
筛选依据与响应快照可能处于两个时点
job_status 筛选使用查询时的本地快照；返回前同步可能把当前行更新为另一状态。不要在前端再次强制过滤响应，下一次加载会基于新快照重新筛选。

          


          

          

          

          
        


        
计划列表的自动快照同步逻辑 展开流程
01 / QUERY查询本地台账
筛选和 total 使用持久化快照
02 / SELECT只看当前页
仅 Job ID > 0 且非终态
03 / FETCH最多 10 路并发
逐个读取远端 Job 汇总
04 / APPLY成功则写库并更新响应
状态、计数、摘要与同步时间
05 / FALLBACK失败保留持久化快照
单条异常不阻断列表
终态 Job：PUSH_JOB_STATUS_SUCCEEDED、PUSH_JOB_STATUS_PARTIALLY_SUCCEEDED、PUSH_JOB_STATUS_FAILED、PUSH_JOB_STATUS_NO_TARGET；这些状态不会进入自动同步队列。

      


      

        
05
状态流转与操作权限
计划状态控制编辑、取消和重试；Job 是否存在控制设备明细。不要仅依据按钮点击结果自行推导状态。

        

          
立即发送
OFFLINE_PUSH_PLAN_STATUS_SUBMITTING→OFFLINE_PUSH_PLAN_STATUS_SUBMITTED或OFFLINE_PUSH_PLAN_STATUS_FAILED

          
定时发送
OFFLINE_PUSH_PLAN_STATUS_SCHEDULING→OFFLINE_PUSH_PLAN_STATUS_SCHEDULED→OFFLINE_PUSH_PLAN_STATUS_SUBMITTING→OFFLINE_PUSH_PLAN_STATUS_SUBMITTED/OFFLINE_PUSH_PLAN_STATUS_FAILED

          
取消 / 过期
OFFLINE_PUSH_PLAN_STATUS_SCHEDULED→OFFLINE_PUSH_PLAN_STATUS_SCHEDULING→OFFLINE_PUSH_PLAN_STATUS_CANCELLED或超窗OFFLINE_PUSH_PLAN_STATUS_EXPIRED

          
失败重试
OFFLINE_PUSH_PLAN_STATUS_FAILED→OFFLINE_PUSH_PLAN_STATUS_SCHEDULING / OFFLINE_PUSH_PLAN_STATUS_SUBMITTING→OFFLINE_PUSH_PLAN_STATUS_SCHEDULED / OFFLINE_PUSH_PLAN_STATUS_SUBMITTED或OFFLINE_PUSH_PLAN_STATUS_EXPIRED

        

        
当前条件查看编辑取消重试设备明细
status = OFFLINE_PUSH_PLAN_STATUS_SCHEDULED显示显示显示隐藏按 Job ID
status = OFFLINE_PUSH_PLAN_STATUS_FAILED && message_job_id = 0显示隐藏隐藏显示隐藏
message_job_id > 0显示隐藏隐藏隐藏显示
status = OFFLINE_PUSH_PLAN_STATUS_CANCELLED / OFFLINE_PUSH_PLAN_STATUS_EXPIRED显示隐藏隐藏隐藏按 Job ID
其他中间态显示禁用禁用隐藏按 Job ID

      


      

        
06
完整计划字段与枚举
列表响应中的 plan 同时承载运营表单、调度生命周期、远端投递快照与审计信息；下表逐字保留 proto 完整枚举标识与 0 值。

        

          
身份
idbiz_idrequest_idgame_app_idname

          
内容
sourcearticle_idtitlesubtitletemplate_argsbadge

          
人群与路由
topickeys.entry_typekeys.jump_typekeys.jump_linkkeys.game_play

          
生命周期
execute_atstatusversionschedule_run_idlast_errorcancel_reason

          
投递快照
message_job_idjob_statustotal_countaccepted_countfailed_countjob_failure_summaryjob_sync_time

          
审计时间
operator_idoperator_namesubmit_timecancel_timeadd_timelast_time

        


        
共 45 项

        

          

            
内容来源
MailboxTaskSource

            

              
0MAILBOX_TASK_SOURCE_UNSPECIFIED新提交不可用

              
1MAILBOX_TASK_SOURCE_TEMPLATE文章模板

              
2MAILBOX_TASK_SOURCE_TEXT直接文本

            

          

          

            
计划状态
OfflinePushPlanStatus

            

              
0OFFLINE_PUSH_PLAN_STATUS_UNSPECIFIED未指定计划状态

              
1OFFLINE_PUSH_PLAN_STATUS_SCHEDULING创建/更新调度中

              
2OFFLINE_PUSH_PLAN_STATUS_SCHEDULED等待定时执行

              
3OFFLINE_PUSH_PLAN_STATUS_SUBMITTING创建 Push Job 中

              
4OFFLINE_PUSH_PLAN_STATUS_SUBMITTED已创建 Push Job

              
5OFFLINE_PUSH_PLAN_STATUS_CANCELLED发送前已取消

              
6OFFLINE_PUSH_PLAN_STATUS_EXPIRED超过补发窗口

              
7OFFLINE_PUSH_PLAN_STATUS_FAILED调度或 Job 创建失败

            

          

          

            
Job 状态
PushJobStatus

            

              
0PUSH_JOB_STATUS_UNSPECIFIED未指定任务状态

              
1PUSH_JOB_STATUS_PENDING待处理

              
2PUSH_JOB_STATUS_RESOLVING解析目标中

              
3PUSH_JOB_STATUS_PROCESSING投递处理中

              
4PUSH_JOB_STATUS_SUCCEEDED全部成功

              
5PUSH_JOB_STATUS_PARTIALLY_SUCCEEDED部分成功

              
6PUSH_JOB_STATUS_FAILED失败

              
7PUSH_JOB_STATUS_NO_TARGET无目标设备

            

          

          

            
设备状态
PushTargetStatus

            

              
0PUSH_TARGET_STATUS_UNSPECIFIED未指定目标状态

              
1PUSH_TARGET_STATUS_PENDING待处理

              
2PUSH_TARGET_STATUS_PROCESSING处理中

              
3PUSH_TARGET_STATUS_PROVIDER_ACCEPTEDFCM 已接受

              
4PUSH_TARGET_STATUS_PERMANENT_FAILED永久失败

            

          

          

            
系统人群
PushSystemTopic

            

              
0PUSH_SYSTEM_TOPIC_UNSPECIFIED未指定系统人群

              
1PUSH_SYSTEM_TOPIC_ALL_USERS全部有效用户

              
2PUSH_SYSTEM_TOPIC_NEWBIE注册不超过 14 天

              
3PUSH_SYSTEM_TOPIC_INACTIVE_USERS_24离线至少 24 小时

              
4PUSH_SYSTEM_TOPIC_INACTIVE_USERS_72离线至少 72 小时

              
5PUSH_SYSTEM_TOPIC_REGISTERED_USERS赛事报名；暂不可提交

            

          

          

            
入口类型
GameActivityEntryType

            

              
0GAME_ACTIVITY_ENTRY_TYPE_NONE无入口

              
1GAME_ACTIVITY_ENTRY_TYPE_GAMEPLAY玩法

              
2GAME_ACTIVITY_ENTRY_TYPE_TOURNAMENT赛事

              
3GAME_ACTIVITY_ENTRY_TYPE_ACTIVITY活动

            

          

          

            
跳转类型
GameActivityJumpType

            

              
0GAME_ACTIVITY_JUMP_TYPE_NONE无

              
1GAME_ACTIVITY_JUMP_TYPE_INGAME游戏内文本

              
2GAME_ACTIVITY_JUMP_TYPE_H5外部 H5

              
3GAME_ACTIVITY_JUMP_TYPE_FUNCTION功能跳转

              
4GAME_ACTIVITY_JUMP_TYPE_TOURNAMENT赛事

              
5GAME_ACTIVITY_JUMP_TYPE_RULE规则

            

          

          

            
玩法
GameActivityGamePlay

            

              
0GAME_ACTIVITY_GAMEPLAY_NONE无

              
1GAME_ACTIVITY_GAMEPLAY_CASH现金桌

              
2GAME_ACTIVITY_GAMEPLAY_SITGOSit & Go

              
3GAME_ACTIVITY_GAMEPLAY_TOURNAMENT锦标赛

              
4GAME_ACTIVITY_GAMEPLAY_OMAHA奥马哈

            

          

        

        
K
Keys 联动规则
GAME_ACTIVITY_ENTRY_TYPE_NONE 必须清空全部路由字段；GAME_ACTIVITY_ENTRY_TYPE_GAMEPLAY 只允许非零 game_play；GAME_ACTIVITY_ENTRY_TYPE_TOURNAMENT 要求 GAME_ACTIVITY_JUMP_TYPE_TOURNAMENT 与非空 jump_link；GAME_ACTIVITY_ENTRY_TYPE_ACTIVITY 要求非 GAME_ACTIVITY_JUMP_TYPE_NONE 的 jump_type。所有非 GAME_ACTIVITY_JUMP_TYPE_NONE 跳转都要求 jump_link，GAME_ACTIVITY_JUMP_TYPE_H5 仅允许 http/https。jump_link 最多 1024 字符，deep_link 固定为空。

      


      

        
07
管理后台 UI 参考
以信息密度和操作安全为先：列表承担状态判断，抽屉承担完整表单，设备明细独立承载筛选与失败信息。

        

          
交互结构预览

          

            
搜索计划名称
计划状态
内容来源
计划 / 人群内容来源发送 / 同步时间状态 / 投递操作
计划名称
InactiveUsers_24文章模板
文章 ID · 示例定时发送
列表加载时同步等待发送编辑 · 取消
计划名称
AllUsers直接文本
英文标题立即发送
显示 job_sync_time全部成功设备明细
计划名称
Newbie文章模板立即发送计划失败重试

            
            
          

        

      


      

        
08
错误处理与联调清单
把字段错误就地反馈，把状态竞争交给重载后的真实数据；批量接口永远按行解释结果。

        

          
invalid input
保留用户输入，定位到来源、文章、文本、模板参数、Keys 或时间字段。

          
plan conflict
编辑或取消状态已变化时关闭操作态并重新加载当前列表，再按最新行数据重建操作。

          
dependency unavailable
模板同步、调度或消息服务异常时保留失败计划，允许满足条件后重试。

          
partial batch
HTTP 成功不代表整批成功；分别解析 add_result、edit_result、delete_result。

          
stale job snapshot
单 Job 同步失败时响应保留持久化值；展示 job_sync_time，避免宣称实时。

          
target unavailable
message_job_id = 0 时隐藏设备明细入口，不发送无效查询。

        

        

          
01TopicList 与 List 并行初始化
02列表 page_size 仅传 20 或 50

          
03模板模式只选 type = 6 的文章
04模板模式 title / subtitle 为空

          
05文本模式 article_id = 0 且 title 必填
06空副标题不发送 subtitle template

          
07template_args 键非空且 ≤ 4096 bytes
08badge 缺失与 badge = 0 正确区分

          
09新增行 id = 0 且不包含 version
10编辑行 id > 0 且不包含 version

          
11取消只提交 delete_rows: number[]
12重试提交当前 id + version

          
13PUSH_SYSTEM_TOPIC_REGISTERED_USERS 始终保持禁用
14列表同步失败时接受持久化快照

          
15job_status 筛选不二次过滤返回行
16移动端无页面级横向溢出

        

      


      
    

  


  
已复制