OfflinePush 前端对接指南

01 · Quick start

先把共性约定对齐

页面初始化时并行加载系统人群和计划列表；所有写操作完成后，以接口结果或重新查询的数据为准。

两项项目约定待确认

基础域名、鉴权头、统一响应包裹/错误码，以及 HTTP JSON 枚举使用数字还是协议字符串。下文同时标注枚举数字与协议名，不代替项目网关约定。

5前端接口查询、提交、重试、人群、明细

1 / 20建议初始分页页码从 1 开始，单页最多 100

+5s最小定时提前量定时发送至少晚于当前时间 5 秒

GETOfflinePushTopicList表单初始化：可选系统人群与实时可用状态

GETOfflinePushList计划列表、筛选、分页与操作入口判断

POSTOfflinePushSubmits批量新增、编辑、取消；逐行返回结果

POSTOfflinePushRetry重试未关联 Push Job 的失败计划

GETOfflinePushTargetList关联 Push Job 的逐设备投递结果

02 · Integration flow

按业务动作组织调用

切换标签查看每条主流程。中间状态由系统自动推进，前端不自行推断终态。

01并行初始化加载人群与计划列表

02选择人群不可用项禁用并说明原因

03填写内容标题、副标题、角标与跳转

04设置时间立即为 0；定时至少 +5 秒

05提交 add_rowsid 与 version 均为 0

06逐行反馈按 index 映射，再重查列表

03 · Endpoint reference

接口详解

接口卡片默认收起，展开后可查看字段、最小请求示例与前端处理重点。

点击卡片展开

GET

OfflinePushTopicList

/admin.admin.v1.lobby.Message/OfflinePushTopicList

请求与响应

方向	字段	说明
请求	无业务参数	页面初始化时调用
响应	`list[].topic`	系统人群枚举
响应	`name / description`	优先直接用于下拉文案
响应	`available`	实时可用状态，不在前端硬编码
响应	`unavailable_reason`	禁用项的解释文案

与计划列表并行请求，减少首屏等待。
不可用项保留可见、禁用选择，并展示原因。

结构示例 · RESPONSE

{
  "list": [
    {
      "topic": 1,
      "name": "接口返回的人群名称",
      "description": "接口返回的人群说明",
      "available": false,
      "unavailable_reason": "接口返回的不可用原因"
    }
  ]
}

GET

OfflinePushList

/admin.admin.v1.lobby.Message/OfflinePushList

查询字段

字段	要求	用途
`page`	必传，≥ 1	页码
`page_size`	必传，1–100	建议初始值 20
`name`	可选	计划名称模糊查询
`status`	可选，1–7	计划状态
`job_status`	可选，1–7	远端投递状态
`topic`	可选，1–5	系统人群
`operator_id`	可选	创建管理员
`create_time_start / end`	Unix 秒	同时存在时 start ≤ end

排序固定为 add_time DESC, id DESC。
前端固定传合法分页值，不依赖服务端回退。
站点由请求上下文隔离，请求体不传 game_app_id。

示例值 · REQUEST

GET .../OfflinePushList
  ?page=1
  &page_size=20
  &status=2

结构示例 · RESPONSE

{
  "list": [{
    "id": 1001,
    "version": 1,
    "name": "示例计划",
    "status": 2,
    "message_job_id": 0,
    "total_count": 0,
    "accepted_count": 0,
    "failed_count": 0
  }],
  "total": 1
}

POST

OfflinePushSubmits

/admin.admin.v1.lobby.Message/OfflinePushSubmits

三类操作共用一次提交

数组	身份字段	关键约束
`add_rows`	`id = 0` `version = 0`	创建立即或定时计划
`edit_rows`	`id > 0` `version > 0`	仅当前 SCHEDULED 版本；必须保持定时
`delete_rows`	`id > 0` `version > 0`	仅当前 SCHEDULED 版本；reason 必填；保留台账

每个数组最多 100 行；同批次中单行失败不回滚已完成的其他行。
按返回的 index 映射原始行；message 为空表示成功。
成功项的 id 为计划 ID，extra 为 biz_id。

示例值 · ADD REQUEST

{
  "add_rows": [{
    "id": 0,
    "version": 0,
    "name": "示例计划",
    "topic": 1,
    "title": "示例通知标题",
    "subtitle": "示例通知副标题",
    "badge": 0,
    "keys": {
      "entry_type": 0,
      "jump_type": 0,
      "jump_link": "",
      "game_play": 0
    },
    "execute_at": 0
  }],
  "edit_rows": [],
  "delete_rows": []
}

不要把 HTTP 成功等同于整批成功

分别遍历 add_result、edit_result、delete_result；按 index 给每行展示成功或错误信息。

POST

OfflinePushRetry

/admin.admin.v1.lobby.Message/OfflinePushRetry

调用条件

字段/条件	要求
`id`	必传，计划 ID
`version`	必传，当前版本
`status`	必须为 FAILED
`message_job_id`	必须为 0

使用响应中的最新 plan 局部替换列表行。
重试后可能进入调度中、等待调度或已提交。
延迟超过 30 分钟的计划可能转为 EXPIRED。

示例值 · REQUEST

{
  "id": 1001,
  "version": 3
}

结构示例 · RESPONSE

{
  "plan": {
    "id": 1001,
    "version": 4,
    "status": 3,
    "message_job_id": 0
  }
}

GET

OfflinePushTargetList

/admin.admin.v1.lobby.Message/OfflinePushTargetList

查询字段

字段	要求	说明
`plan_id`	必传	传计划 ID，不直接传 Push Job ID
`status`	可选，1–4	设备投递状态筛选
`page`	必传，≥ 1	页码
`page_size`	必传，1–100	每页数量

仅在 message_job_id > 0 时展示入口。
尚未关联 Job 时显示“投递明细暂不可查”，不发起请求。
设备 token 只展示脱敏后缀 token_suffix。

示例值 · REQUEST

GET .../OfflinePushTargetList
  ?plan_id=1001
  &status=3
  &page=1
  &page_size=20

结构示例 · RESPONSE

{
  "list": [{
    "token_suffix": "脱敏后缀",
    "status": 3
  }],
  "total": 1
}

04 · Data dictionary

字段与枚举速查

输入协议名、数字或中文含义即可过滤。系统人群的实时可用性始终以接口响应为准。

共 38 项

计划状态

OfflinePushPlanStatus

1SCHEDULING调度处理中

2SCHEDULED等待定时执行

3SUBMITTING正在创建 Push Job

4SUBMITTED已创建 Push Job

5CANCELLED发送前已取消

6EXPIRED超过补发窗口

7FAILED调度或 Job 创建失败

Job 状态

PushJobStatus

1PENDING待处理

2RESOLVING解析目标中

3PROCESSING投递处理中

4SUCCEEDED全部成功

5PARTIALLY_SUCCEEDED部分成功

6FAILED失败

7NO_TARGET无目标设备

设备状态

PushTargetStatus

1PENDING待处理

2PROCESSING处理中

3PROVIDER_ACCEPTED推送服务已接受

4PERMANENT_FAILED永久失败

系统人群

PushSystemTopic

1ALL_USERS全部用户

2NEWBIE新手用户

3INACTIVE_USERS_2424 小时不活跃用户

4INACTIVE_USERS_7272 小时不活跃用户

5REGISTERED_USERS赛事报名用户

入口类型

GameActivityEntryType

0NONE无跳转

1GAMEPLAY玩法

2TOURNAMENT赛事

3ACTIVITY活动

跳转类型

GameActivityJumpType

0NONE无

1INGAME游戏内文本

2H5外部 H5

3FUNCTION功能跳转

4TOURNAMENT赛事

5RULE规则

玩法

GameActivityGamePlay

0NONE无

1CASH现金桌

2SITGOSit & Go

3TOURNAMENT锦标赛

4OMAHA奥马哈

05 · UI reference

把接口条件直接映射到交互

右侧为可切换的界面结构参考；它表达信息层级与操作条件，不代表线上业务数据。

管理后台结构参考

计划 / 人群发送时间通知内容状态 / 结果操作

计划名称
接口返回的人群定时 · Unix 秒通知标题
通知副标题SCHEDULED编辑取消

计划名称
接口返回的人群立即发送通知标题
通知副标题FAILED重试

行操作权限矩阵

条件	编辑	取消	重试	明细
`SCHEDULED`	显示	显示	隐藏	通常隐藏
`FAILED` 且 job id = 0	隐藏	隐藏	显示	隐藏
`message_job_id > 0`	隐藏	隐藏	隐藏	显示
其他状态	隐藏/禁用	隐藏/禁用	隐藏	按关联决定

表单联动

entry_type = NONE

清空并禁用跳转类型、跳转目标和玩法。

GAMEPLAY

只显示并要求选择 game_play。

TOURNAMENT

固定赛事跳转，要求 jump_link，清空玩法。

ACTIVITY

要求非 NONE 的 jump_type，清空玩法。

jump_type = H5

jump_link 必须是完整 http/https URL。

REGISTERED_USERS

强制赛事入口与赛事跳转；jump_link 非空且不超过 128 字符。

06 · Failure strategy

错误、并发与状态反馈

把可预防的错误挡在表单，把不可预测的冲突交给重新读取后的真实状态。

表单无效

前置校验时间、必填项与跳转联动；保留用户输入，定位到具体字段。

version 冲突

提示“数据已更新，请确认后重试”；关闭编辑态或保留草稿，重新拉取当前行。

批量部分成功

分别遍历三类结果，以 index 回填；成功行及时确认，失败行保留内容和错误。

依赖不可用

展示可恢复错误并允许稍后重试；不自动高频重试。

设备明细尚不可查

当 message_job_id 为 0 时隐藏入口，或给出明确空状态，不发起无效请求。

技术错误详情

last_error 在详情内可复制展示；列表仅给中文概括，job_failure_summary 按脱敏摘要展示。

07 · Joint testing

联调检查单

覆盖主流程、边界条件与前端反馈，避免只验证“请求能通”。

01系统人群和计划列表并行初始化

02立即创建：execute_at = 0

03定时创建：至少晚于当前时间 5 秒

04仅 SCHEDULED 可编辑且保持定时

05取消要求二次确认和必填原因

06批量提交中部分成功、部分失败

07version 冲突后重新读取当前行

08FAILED 且无 Job 的计划可重试

09超过 30 分钟窗口后进入 EXPIRED

10无 Job 时不请求设备明细

11设备状态筛选与分页

12不可用人群禁用并显示原因

13badge 未传与 badge = 0 正确区分

14移动端无页面级横向溢出