PushGo Gateway API

整体请求 / 响应格式
Global Request / Response Format

所有推送接口都使用 JSON。先看统一格式，再看每个接口的业务字段。
All push endpoints use JSON. Read global envelope first, then endpoint business fields.

全局请求体限制：HTTP body 最大 32KB（DefaultBodyLimit::max(32 * 1024)）。 业务 ID（message_id/event_id/thing_id）由网关生成，当前格式为 32 位小写十六进制字符串。
Global request body limit: HTTP body is capped at 32KB (DefaultBodyLimit::max(32 * 1024)). Business IDs (message_id/event_id/thing_id) are generated by gateway and currently use 32-char lowercase hex strings.

当前发送类接口请求模型启用了严格 JSON 解析（deny_unknown_fields）： 未声明字段会触发 400。
Current push endpoint request models use strict JSON parsing (deny_unknown_fields): undeclared fields are rejected with HTTP 400.

请求头
Request headers

通用请求字段
Common request fields

通用响应包裹
Common response envelope

示例响应
Response examples

{
  "success": true,
  "data": {
    "op_id": "00191a2050440-0123456789abcdef0123456789abcdef",
    "message_id": "8a1fc4b3d9f04fd2857f92f66f7cc5d1"
  }
}

{
  "success": false,
  "error": "channel not found",
  "error_code": null,
  "data": null
}

消息推送接口
Message Push API

POST /message JSON

作用：发送一条顶层消息。接口同步返回“是否受理”，下发在后台异步执行。
Purpose: send a top-level message. Response indicates acceptance only.

发送说明（面向推送方）：单次请求体最大 32KB；ttl 超过 28 天会按 28 天处理。
Sender notes: request body is capped at 32KB; ttl is capped at 28 days.

请求业务字段
Request business fields

ciphertext 详细规范（重要）
Detailed ciphertext spec (important)

以下规则基于 Apple 客户端当前实现（PushGo iOS/macOS/watchOS 共享解密路径）。 发送侧请严格按此构造，否则客户端会标记解密失败并回退到明文展示（若有明文字段）。
The rules below are based on the current Apple client implementation (shared iOS/macOS/watchOS decrypt path). Follow this exactly; otherwise clients mark decrypt failure and fall back to plaintext when available.

1) 支持算法与密钥要求
1) Supported algorithm and key requirements

• 仅支持 AES-GCM。客户端若配置为其它算法会进入 algMismatch。
  Only AES-GCM is supported. Other algorithms are treated as algMismatch.
• 密钥长度必须是 16/24/32 字节（128/192/256 bit）。
  Key length must be 16/24/32 bytes (128/192/256 bits).
• IV（nonce）长度固定 12 字节，Tag 长度固定 16 字节。
  IV (nonce) is fixed to 12 bytes, Tag to 16 bytes.

2) ciphertext 编码格式
2) ciphertext encoding format

先将明文 JSON（UTF-8）做 AES-GCM 加密，然后按如下字节顺序拼接并 Base64：
Encrypt plaintext JSON (UTF-8) with AES-GCM, then concatenate and Base64:

ciphertext_field = Base64( cipher || tag || iv )

• cipher: 密文字节（不含 tag）
  cipher: ciphertext bytes (without tag)
• tag: 16 字节认证标签
  tag: 16-byte authentication tag
• iv: 12 字节 nonce，放在末尾（非常重要）
  iv: 12-byte nonce, appended at the end (important)
• Base64 使用标准字符集（A-Z a-z 0-9 + / =），长度需为 4 的倍数。
  Use standard Base64 alphabet (A-Z a-z 0-9 + / =), length must be multiple of 4.

3) 解密后 JSON 结构（客户端统一实现）
3) JSON structure after decrypt (cross-client behavior)

客户端解密 ciphertext 后会按 JSON 解码，当前识别字段为：
After decrypting ciphertext, client decodes JSON and currently recognizes:

4) 发送构造示例
4) Sender construction example

{
  "title": "Encrypted title",
  "body": "Encrypted body",
  "url": "https://safe.example/open",
  "description": "Encrypted event summary",
  "message": "Encrypted event body",
  "attrs": {"name":{"label":"名称","value":"泵站A"}},
  "images": [
    "https://cdn.example.com/a.png",
    "https://cdn.example.com/b.png"
  ]
}

将上面 JSON 作为明文，使用共享密钥 + 12-byte IV 做 AES-GCM，加密后拼成 cipher||tag||iv，再 Base64，放入 /message 的 ciphertext 字段。
Use the JSON above as plaintext, encrypt with shared key + 12-byte IV using AES-GCM, concatenate cipher||tag||iv, Base64 it, and put the result in /message.ciphertext.

{
  "channel_id": "YOUR_CHANNEL_ID",
  "password": "YOUR_PASSWORD",
  "title": "Fallback title",
  "body": "Fallback body",
  "ciphertext": "BASE64_OF_cipher_tag_iv"
}

5) 行为优先级与回退
5) priority and fallback behavior

• 客户端正文优先级：ciphertext.body > body。
  Client body priority: ciphertext.body > body.
• 若 ciphertext 格式错误、密钥不匹配或解密失败：客户端保留原始 payload 并标记解密失败。
  If ciphertext is malformed, key mismatched, or decrypt fails, client keeps original payload and marks decrypt failed.
• 网关不校验密文字节布局；正确性由发送方与客户端密钥配置共同保证。
  Gateway does not validate encrypted byte layout; correctness is guaranteed by sender/client key alignment.

响应业务字段
Response business fields

发送状态查询
Send Status Query

GET /send_status/{op_id} 查询单次发送的粗粒度状态。该接口只接受 Gateway 返回的 op_id，不支持按频道、设备、payload 或 provider 信息查询。
Query a coarse sender-facing status for one send operation. The only lookup key is the gateway-returned op_id; channel, device, payload, and provider details are intentionally not exposed.

状态记录会按维护清理策略自动过期；过期或不存在时返回 404 send_status_not_found。
Status records expire through maintenance cleanup; expired or missing records return 404 send_status_not_found.

事件推送接口
Event Push APIs

二级事件已并入一级事件接口：都走 /event/*，是否挂在某个对象下由可选 thing_id 决定。
Thing-scoped events are merged into top-level event APIs; optional thing_id decides whether the event belongs to a thing.

/event/* 请求支持可选 ciphertext，网关仅透传密文；路由与优先级字段（如 channel_id/event_id/thing_id/severity）建议保持明文。
/event/* accepts optional ciphertext. Gateway only forwards it; routing/priority fields (for example channel_id/event_id/thing_id/severity) should remain plaintext.

POST /event/create

作用：创建事件并推送。
Purpose: create an event.
约束：/event/create 不接受 event_id，由网关生成。
Rule: /event/create does not accept event_id; gateway generates it.

额外约束：started_at 只在 create 可传；event_id 由网关生成；create 需要 title/status/message/severity。
Extra rules: started_at is create-only; event_id is generated by gateway; create requires title/status/message/severity.

POST /event/update

作用：更新事件并推送。
Purpose: update an event.

额外约束：update 需要 event_id/status/message/severity；不允许传 started_at 或 ended_at。
Extra rules: update requires event_id/status/message/severity; started_at and ended_at are not allowed.

POST /event/close

作用：关闭事件并推送。
Purpose: close an event.

额外约束：close 需要 event_id/status/message/severity；ended_at 仅 close 可传，started_at 不允许。
Extra rules: close requires event_id/status/message/severity; ended_at is close-only and started_at is not allowed.

对象推送接口
Thing Push APIs

/thing/* 请求支持可选 ciphertext，网关仅透传密文；路由字段（如 channel_id/thing_id）建议保持明文。
/thing/* accepts optional ciphertext. Gateway only forwards it; routing fields (for example channel_id/thing_id) should remain plaintext.

POST /thing/create

作用：创建对象并推送。
Purpose: create a thing.

POST /thing/update

作用：更新对象并推送。
Purpose: update a thing.

POST /thing/archive

作用：归档对象。
Purpose: archive a thing.

POST /thing/delete

作用：删除对象。
Purpose: delete a thing.

Markdown 支持说明
Markdown support

body 字段按客户端 Markdown 渲染链路处理，无需额外开关或字段；普通纯文本也可直接发送。
The body field goes through the client Markdown rendering pipeline by default, with no extra flags required; plain text also works.

常见 Markdown 写法在 PushGo 客户端总体兼容；不同平台渲染引擎存在细微差异，复杂写法可能展示略有不同。
Common Markdown authoring is broadly compatible across PushGo clients. Rendering can vary slightly between platforms for complex constructs.

若遇到不兼容语法，客户端会尽量保留原文文本，不影响消息可读性。
For unsupported syntax, clients preserve readable plain text whenever possible.

建议写法
Authoring guidance

• 建议优先使用常见 Markdown 结构（标题、列表、引用、链接、行内代码），可获得最稳定的跨端一致性。
  Prefer common Markdown patterns for best cross-platform consistency.
• 建议正文保持简洁；通知与列表预览场景会做截断（典型为 1 行约 180 字符、列表约 6 行/1200 字符）。
  Keep body concise; notification/list previews are truncated (typically ~180 chars for 1-line notifications, ~6 lines/1200 chars for list preview).

示例：业务通知
Example: Business notification

# 微信消息转发
> 来源：@alice 在 #渠道运营
**标题：** 新品上线通知
*时间：* 2026-03-20 09:30

[!info] 已将原消息转发到企业微信，请确认是否需要补充说明。

- 重点：==首批库存 2,000== 件
- 文档：查看 [发布说明](https://example.com/release)
- 备注：~~延后发布~~ 改为今天 10:00
1. 负责人：@bob
2. 联系：ops@example.com / 400-800-1234

| 字段 | 值 | 说明 |
| --- | --- | --- |
| 原始群 | 产品内测群 | WeChat |
| 消息 ID | WX-98231 | `msg_id` |
| 链接 | https://wechat.example.com/msg/98231 | 自动识别 |

---

这个消息包含 `inline code` 和 #转发 标签。

示例：监控告警
Example: Monitoring alert

# 服务器监控报警
[!warning] CPU 持续 5 分钟 > 92%，请立即处理。
> 机器：`prod-api-03` (10.2.0.23)
> 时间窗：2026-03-20 10:05-10:10

**影响面：** *支付* 与 *结算* 服务
- 负载：==7.8==
- 错误率：3.2%
- 关联工单：#incident-20260320

1. 检查近期发布：`v2.18.4`
2. 查看日志：https://grafana.example.com/d/abc
3. 值班人：@oncall

| 指标 | 当前 | 阈值 |
| --- | --- | --- |
| CPU | 92% | 85% |
| Memory | 78% | 80% |
| P95 延迟 | 680ms | 500ms |

---

需要升级到 [Runbook](https://example.com/runbook) 或发邮件 ops@example.com。

错误与限制
Errors and limits

• 参数校验失败返回 400。
  Validation failures return 400.
• 请求体超过 32KB 时返回 413。
  Requests larger than 32KB return 413.
• 认证失败返回 401。
  Authentication failures return 401.
• 频道不存在返回 404。
  Missing channels return 404.
• 发送端成功响应只表示 gateway 已受理；下游部分投递失败不改变发送端回执。
  Sender success responses only mean gateway accepted the request; downstream partial delivery failures do not change the sender ack.

兼容接口（附录）
Compatibility Endpoints (Appendix)

本节为迁移与低门槛接入提供的兼容入口，优先级低于标准接口。生产集成建议优先使用 /message、/event/*、/thing/*。
This section provides migration-friendly compatibility endpoints and is secondary to the standard APIs. Prefer /message, /event/*, and /thing/* for production integrations.

鉴权保持 PushGo 基础规则：兼容参数中使用明文 <channel_id>:<password>（称为 compat_key），并借位放入对方风格参数（topic/sendkey/device_key）。
Authentication still follows PushGo rules: use plaintext <channel_id>:<password> as a compatibility key and place it in provider-style parameters (topic/sendkey/device_key).

兼容接口与 GET /message 均不接受 thing_id。
thing_id is not accepted by compatibility endpoints and GET /message.

兼容路由
Compatibility routes