feat: message-api for mission via wecomm agent

2026-05-14 09:30:38 +08:00
parent 9359013b4c
commit f409f2e6ee
38 changed files with 2085 additions and 49 deletions
--- a/docs/MESSAGE_API.md
+++ b/docs/MESSAGE_API.md
@@ -0,0 +1,165 @@
+# 消息发送 API
+
+这组 API 用于对外主动发送企业微信应用消息。
+
+当前提供两个接口：
+
+- `POST /api/message/send`：发送文本消息
+- `POST /api/message/send/news`：发送单篇图文消息，可同时投递到多个 `agent_id`
+
+## 鉴权
+
+仅这组消息发送 API 需要固定 `Authorization` 请求头。
+
+服务端读取环境变量：
+
+- `MESSAGE_API_AUTHORIZATION`
+
+默认值：
+
+- `hophopkk`
+
+请求示例：
+
+```http
+Authorization: hophopkk
+Content-Type: application/json
+```
+
+鉴权失败时返回：
+
+```json
+{
+  "detail": "Invalid Authorization header"
+}
+```
+
+HTTP 状态码：`401 Unauthorized`
+
+## 发送文本消息
+
+### 请求
+
+`POST /api/message/send`
+
+```json
+{
+  "agent_id": 1000007,
+  "content": "库存盘点将在 18:00 开始",
+  "user_ids": ["zhangsan", "lisi"]
+}
+```
+
+字段说明：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `agent_id` | integer | 是 | 企业微信应用 ID |
+| `content` | string | 是 | 文本内容，1-2048 字节 |
+| `user_ids` | string[] | 否 | 接收用户 UserID 列表；为空时发送给应用可见范围内全部成员 |
+
+### 成功响应
+
+```json
+{
+  "errcode": 0,
+  "errmsg": "ok"
+}
+```
+
+### curl 示例
+
+```bash
+curl -X POST 'http://localhost:8198/api/message/send' \
+  -H 'Authorization: hophopkk' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "agent_id": 1000007,
+    "content": "库存盘点将在 18:00 开始",
+    "user_ids": ["zhangsan", "lisi"]
+  }'
+```
+
+## 发送图文消息
+
+### 请求
+
+`POST /api/message/send/news`
+
+```json
+{
+  "agent_ids": [1000007, 1000008],
+  "title": "销售日报",
+  "description": "点击查看今日各区域销售汇总",
+  "url": "https://example.com/reports/daily-sales",
+  "image_url": "https://example.com/static/daily-sales-cover.png",
+  "user_ids": ["zhangsan"]
+}
+```
+
+字段说明：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `agent_ids` | integer[] | 是 | 目标应用 ID 列表，至少 1 个 |
+| `title` | string | 是 | 图文标题，1-128 字符 |
+| `description` | string | 是 | 图文描述，1-512 字符 |
+| `url` | string | 是 | 点击跳转链接 |
+| `image_url` | string | 是 | 封面图片 URL，直接映射到企业微信 `picurl` |
+| `user_ids` | string[] | 否 | 接收用户 UserID 列表；为空时发送给应用可见范围内全部成员 |
+
+### 成功响应
+
+至少一个 `agent_id` 发送成功时返回 `200`，并带每个应用的发送结果：
+
+```json
+{
+  "results": [
+    {
+      "agent_id": 1000007,
+      "ok": true,
+      "response": {
+        "errcode": 0,
+        "errmsg": "ok"
+      },
+      "error": null
+    },
+    {
+      "agent_id": 1000008,
+      "ok": false,
+      "response": null,
+      "error": "agent not found"
+    }
+  ]
+}
+```
+
+如果所有 `agent_id` 都失败，则返回 `502 Bad Gateway`：
+
+```json
+{
+  "detail": "All agent sends failed"
+}
+```
+
+### curl 示例
+
+```bash
+curl -X POST 'http://localhost:8198/api/message/send/news' \
+  -H 'Authorization: hophopkk' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "agent_ids": [1000007, 1000008],
+    "title": "销售日报",
+    "description": "点击查看今日各区域销售汇总",
+    "url": "https://example.com/reports/daily-sales",
+    "image_url": "https://example.com/static/daily-sales-cover.png",
+    "user_ids": ["zhangsan"]
+  }'
+```
+
+## 发布建议
+
+- 如果要对外给第三方系统调用，至少同步交付这份文档和环境变量名 `MESSAGE_API_AUTHORIZATION`
+- 当前是固定密钥模式，适合内网或受控系统对接，不适合开放互联网暴露
+- 如果后续要接入更多对外方，建议升级为签名、时间戳或短期 token 模式