# 发送微信消息使用说明

文档类型：模块 API 事实页
是否可直接用于生成代码：是，但 `userid`、`username`、模板标题、模板关键字含义和真实通知内容必须来自用户需求或项目上下文
遇到不确定时：[index.md](index.md)、调用侧账户体系文档、项目实际接口说明、天软科技服务号模板列表

本页整理通过“天软科技服务号”发送微信模板消息的接口事实。它负责告诉智能体“该调用哪个函数、参数顺序是什么、同步和异步怎么选择、状态如何查询”，不负责替用户创造账户、授权关系、模板映射或通知内容。

## 智能体微信消息决策规则

- 用户要“发送微信通知 / 微信消息 / 微信告警 / 微信模板消息 / 查询微信发送状态”时，优先使用本页。
- 紧急通知、需要立刻知道发送结果时，默认使用 `send_wechat_message(...)`。
- 非紧急通知、批量通知、发送后可稍后查询状态时，默认使用 `send_wechat_message_async(...)`。
- 用户要求查询异步状态时，生成 `get_wechat_message_status(userid, username, wechat_message_id)`；三个实参必须来自参数、已知变量或项目上下文。
- 参数必须严格按接口顺序传入；所有参数按字符串处理。
- `url` 是固定位置参数；无详情地址时传空字符串 `""`。
- `k1` 到 `k6` 的含义由模板标题决定；只按模板映射或用户输入填充，不要发明关键字含义。
- 用户要求“通知第一眼看到”的内容时，放入带字段名的 `kN` 参数；`first` 和 `remark` 只作为点入通知后的详情文本。
- 给他人发消息时，必须使用接收者授权给发送者的 `userid`，不要把发送者自己的 `userid` 当成接收者标识。
- 不要发明 `userid`、`username`、项目封装函数、模板标题、模板关键字、授权关系或账号映射。

## 前置条件

| 条件                            | 说明                                                                                   |
| ------------------------------- | -------------------------------------------------------------------------------------- |
| 已绑定服务号                    | 首次使用需要关注并绑定“天软科技服务号”，绑定后取得 `userid`                            |
| 已取得 `userid`                 | `userid` 与用户账户和微信绑定关系相关，应由调用侧提供                                  |
| 给他人发送时已授权              | 接收者绑定后在服务号 `userid` 页面授权发送者账号，发送者使用接收者提供的 `userid` 发送 |
| 查询异步状态时已取得 `username` | `username` 是账号名，脚本查询发送状态时需要；来源以项目账户体系为准                    |

## 接口总览

| 函数                                                                                     | 用途             | 返回值                                            |
| ---------------------------------------------------------------------------------------- | ---------------- | ------------------------------------------------- |
| `send_wechat_message(userid, url, title, first, remark[, k1, k2, k3, k4, k5, k6])`       | 同步发送模板消息 | 成功返回字符串 `success`；失败返回错误信息        |
| `send_wechat_message_async(userid, url, title, first, remark[, k1, k2, k3, k4, k5, k6])` | 异步发送模板消息 | 返回 16 位字符串消息 ID                           |
| `get_wechat_message_status(userid, username, wechat_message_id)`                         | 查询异步发送结果 | 成功返回字符串 `成功`；否则返回状态信息或错误信息 |

## 同步发送

签名：

```text
send_wechat_message(userid, url, title, first, remark[, k1, k2, k3, k4, k5, k6])
```

参数表：

| 参数位置 | 参数名   | 必填     | 接收类型 | 说明                                                              |
| -------- | -------- | -------- | -------- | ----------------------------------------------------------------- |
| 1        | `userid` | 是       | 字符串   | 绑定账户后取得的用户标识；给他人发送时使用接收者授权后的 `userid` |
| 2        | `url`    | 是       | 字符串   | 详情地址；没有详情地址时传 `""`                                   |
| 3        | `title`  | 是       | 字符串   | 模板消息标题，例如 `监控报告通知`                                 |
| 4        | `first`  | 是       | 字符串   | 详情页开头文本；不作为通知列表首屏字段                            |
| 5        | `remark` | 是       | 字符串   | 详情页结尾备注；不作为通知列表首屏字段                            |
| 6        | `k1`     | 条件必填 | 字符串   | 模板关键字 1；带字段名的 `kN` 行属于首屏展示字段                  |
| 7        | `k2`     | 条件必填 | 字符串   | 模板关键字 2；带字段名的 `kN` 行属于首屏展示字段                  |
| 8        | `k3`     | 否       | 字符串   | 模板关键字 3；部分模板需要                                        |
| 9        | `k4`     | 否       | 字符串   | 模板关键字 4；部分模板需要                                        |
| 10       | `k5`     | 否       | 字符串   | 模板关键字 5；部分模板需要                                        |
| 11       | `k6`     | 否       | 字符串   | 模板关键字 6；部分模板需要                                        |

返回值：

| 返回值     | 含义         |
| ---------- | ------------ |
| `success`  | 同步发送成功 |
| 其他字符串 | 错误信息     |

使用规则：

- 同步发送会阻塞当前程序，必须等待发送函数执行完毕后才进入下一步。
- 紧急通知优先使用同步发送。
- 返回值不是 `success` 时，按错误信息处理。

## 异步发送

签名：

```text
send_wechat_message_async(userid, url, title, first, remark[, k1, k2, k3, k4, k5, k6])
```

参数表：

| 参数位置 | 参数名   | 必填     | 接收类型 | 说明                                                              |
| -------- | -------- | -------- | -------- | ----------------------------------------------------------------- |
| 1        | `userid` | 是       | 字符串   | 绑定账户后取得的用户标识；给他人发送时使用接收者授权后的 `userid` |
| 2        | `url`    | 是       | 字符串   | 详情地址；没有详情地址时传 `""`                                   |
| 3        | `title`  | 是       | 字符串   | 模板消息标题                                                      |
| 4        | `first`  | 是       | 字符串   | 详情页开头文本；不作为通知列表首屏字段                            |
| 5        | `remark` | 是       | 字符串   | 详情页结尾备注；不作为通知列表首屏字段                            |
| 6        | `k1`     | 条件必填 | 字符串   | 模板关键字 1；带字段名的 `kN` 行属于首屏展示字段                  |
| 7        | `k2`     | 条件必填 | 字符串   | 模板关键字 2；带字段名的 `kN` 行属于首屏展示字段                  |
| 8        | `k3`     | 否       | 字符串   | 模板关键字 3；部分模板需要                                        |
| 9        | `k4`     | 否       | 字符串   | 模板关键字 4；部分模板需要                                        |
| 10       | `k5`     | 否       | 字符串   | 模板关键字 5；部分模板需要                                        |
| 11       | `k6`     | 否       | 字符串   | 模板关键字 6；部分模板需要                                        |

返回值：

| 返回值      | 含义                                                       |
| ----------- | ---------------------------------------------------------- |
| 16 位字符串 | 异步消息 ID；前 10 位为 1900 年以来的秒数，后 6 位为随机数 |

使用规则：

- 异步发送把命令提交给服务器后立即返回，不等待最终发送结果。
- 非紧急通知优先使用异步发送。
- 需要最终结果时，保存返回的 `wechat_message_id`，再调用 `get_wechat_message_status(...)` 查询。

## 查询异步发送状态

签名：

```text
get_wechat_message_status(userid, username, wechat_message_id)
```

参数表：

| 参数位置 | 参数名              | 必填 | 接收类型 | 说明                                                 |
| -------- | ------------------- | ---- | -------- | ---------------------------------------------------- |
| 1        | `userid`            | 是   | 字符串   | 发送时使用的用户标识                                 |
| 2        | `username`          | 是   | 字符串   | 账号名；脚本执行查询时需要，来源以项目账户体系为准   |
| 3        | `wechat_message_id` | 是   | 字符串   | `send_wechat_message_async(...)` 返回的 16 位消息 ID |

返回值：

| 返回值     | 含义               |
| ---------- | ------------------ |
| `成功`     | 异步消息发送成功   |
| 其他字符串 | 状态信息或错误信息 |

调用规则：

- 状态查询用于异步发送后的结果确认。
- `username` 按账号名参数、已知变量或项目上下文传入，不写字面量 `"username"`。
- `wechat_message_id` 使用 `send_wechat_message_async(...)` 的返回值。

## 模板展示规则

| 模板片段                            | 展示位置               | 生成规则                                         |
| ----------------------------------- | ---------------------- | ------------------------------------------------ |
| `字段名：{{kN}}`                    | 通知列表首屏可见       | 用户要求“第一眼看到”的信息放到对应 `kN`          |
| `{{first}}`                         | 点入通知后的详情页开头 | 放说明、背景、摘要引导；不承载首屏必须展示的信息 |
| `{{remark}}`                        | 点入通知后的详情页结尾 | 放补充说明、处理建议、联系人等尾部信息           |
| 字面标题行，例如 `监控报告通知`     | 模板固定内容           | 不作为接口参数；接口参数 `title` 仍使用模板标题  |
| 动态标签行，例如 `{{k5}}幅：{{k6}}` | 通知列表首屏可见       | `k5` 填字段标签的一部分，`k6` 填对应数值         |

生成规则：

- `title` 决定模板，`k1` 到 `k6` 按模板字段名依次填入。
- 有名称的 `kN` 行是首屏展示字段；需要首屏展示的信息优先放入 `kN`。
- `first` 和 `remark` 是详情页内容；不要把“第一眼必须看到”的核心字段放入 `first` 或 `remark`。
- 模板未列出的 `kN` 不主动传入；需要扩展字段时先换模板或由用户提供模板映射。

## 模板关键字映射

### 系统监控类

| 模板标题             | `k1`         | `k2`         | `k3`         | `k4` | `k5` | `k6` |
| -------------------- | ------------ | ------------ | ------------ | ---- | ---- | ---- |
| `系统运行简报`       | 系统名称     | 简报内容     | 发布时间     |      |      |      |
| `监控报告通知`       | 运行状态     | 时间         |              |      |      |      |
| `监控结果通知`       | 监控项目     | 内容         | 时间         |      |      |      |
| `告警通知`           | 告警内容     | 告警发生时间 |              |      |      |      |
| `故障恢复通知`       | 故障信息     | 恢复时间     |              |      |      |      |
| `服务器异常监控通知` | 监控通知     | 监控通知类型 | 监控通知内容 |      |      |      |
| `服务器宕机通知`     | 故障时间     | 故障原因     |              |      |      |      |
| `服务器恢复通知`     | 故障停止时间 | 故障持续时间 |              |      |      |      |

### 交易通知类

| 模板标题       | `k1`     | `k2`     | `k3`     | `k4`     | `k5`     | `k6`     |
| -------------- | -------- | -------- | -------- | -------- | -------- | -------- |
| `交易成功通知` | 交易金额 | 交易类型 | 交易时间 | 交易单号 |          |          |
| `交易完成通知` | 股票简称 | 股票代码 | 股票价格 | 交易状态 | 股票数量 |          |
| `交易下单通知` | 交易品种 | 下单方向 | 下单价格 | 止损价格 | 下单时间 |          |
| `成交回报提示` | 证券名称 | 证券代码 | 买卖标识 | 成交价格 | 成交数量 | 成交时间 |
| `委托成交提醒` | 数量     | 价格     | 时间     |          |          |          |

### 策略通知类

| 模板标题           | `k1`     | `k2`       | `k3`         | `k4`       | `k5`                      | `k6`   |
| ------------------ | -------- | ---------- | ------------ | ---------- | ------------------------- | ------ |
| `投资策略更新提醒` | 策略名称 | 操作风格   | 目前策略收益 |            |                           |        |
| `股票调仓通知`     | 股票名称 | 操作类型   | 调仓时间     | 调仓价格   | 调仓仓位                  |        |
| `实时建仓提醒`     | 品种     | 方向       | 仓位         | 价格       | 止盈止损                  |        |
| `个股到价通知`     | 股票名   | 当前成交价 | 预警价       |            |                           |        |
| `个股涨跌幅通知`   | 股票名   | 当前成交价 | 对比日期     | 对比收盘价 | 动态标签，组成 `{{k5}}幅` | 动态值 |

### 其他通知类

| 模板标题           | `k1`     | `k2`     | `k3` | `k4` | `k5` | `k6` |
| ------------------ | -------- | -------- | ---- | ---- | ---- | ---- |
| `账号绑定成功通知` | 账号名称 | 绑定时间 |      |      |      |      |
| `服务开启通知`     |          |          |      |      |      |      |
| `授权请求通知`     | 申请人   | 请求权限 |      |      |      |      |

`服务开启通知` 当前只记录模板标题，未固定 `k1` 到 `k6` 的字段映射。

## 发送示例

同步发送系统运行简报：

```tsl
function SendSystemBrief(user_id);
begin
    url := "";
    title := "系统运行简报";
    first := "系统运行情况如下。";
    k1 := "风控服务";
    k2 := "运行正常";
    dateTimeToString(k3, "YYYY-MM-DD HH:NN:SS", now());
    remark := "如有疑问请联系值班人员。";

    return send_wechat_message(user_id, url, title, first, remark, k1, k2, k3);
end;
```

异步发送并保留消息 ID：

```tsl
function SendSystemBriefAsync(user_id);
begin
    url := "";
    title := "系统运行简报";
    first := "系统运行情况如下。";
    k1 := "风控服务";
    k2 := "运行正常";
    dateTimeToString(k3, "YYYY-MM-DD HH:NN:SS", now());
    remark := "如有疑问请联系值班人员。";

    return send_wechat_message_async(user_id, url, title, first, remark, k1, k2, k3);
end;
```

查询异步发送结果：

```tsl
function QueryWechatMessageStatus(user_id, username, wechat_message_id);
begin
    return get_wechat_message_status(user_id, username, wechat_message_id);
end;
```