# 消息发送 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 模式