# 消息规范

本文面向外部业务项目负责人和开发人员。通知使用钉钉原生消息模板，不是 HTML/CSS 网页；卡片外框、宽度、颜色和按钮外观由钉钉客户端渲染。

通知中心固定展示项目来源和业务标题；业务项目决定正文排版、按钮文字及跳转目标。

## 1. 卡片类型和跳转

| 外部项目提交内容 | 通知中心使用的模板 | 收件人看到的效果 |
| --- | --- | --- |
| `actionUrl` 非空 | `sampleActionCard` | 原生 ActionCard，底部显示一个跳转按钮 |
| `actionUrl` 未传或为空 | `sampleMarkdown` | 普通 Markdown 消息，没有底部按钮，外框和宽度可能与 ActionCard 不同 |

要实现“固定资产待审批”那种带按钮的卡片，提供 Markdown 正文和非空 `actionUrl` 即可；`actionTitle` 建议写明确动作，例如“立即审批”，未填写时默认“查看详情”。只填按钮文字但不填地址，不会生成按钮。

业务项目仍调用通知中心的 `POST /v1/notifications`，无需提交 `msgKey`、`msgParam`、`singleTitle` 或 `singleURL`，也无需直接调用钉钉 API。通知中心会把 `actionTitle` 映射为钉钉的 `singleTitle`，把实际发送的跳转地址映射为 `singleURL`。

按钮目标由业务项目的 `actionUrl` 决定。HTTP、HTTPS、内网 IP/域名和端口均可使用，无需为普通通知登记域名白名单；接收人的设备仍须能够访问该业务地址。只有启用钉钉 H5 免登且目标满足既有 HTTPS 登录规则时，通知中心才会包装到免登入口，最终仍回到指定业务页面。

## 2. 固定项目抬头

业务项目的 `title` 只填写业务主题，不要自行拼接项目名称。通知中心从当前鉴权项目的配置中取得名称，生成：

```text
【项目名称】业务标题
```

发送给钉钉时，不只设置独立的 `title` 字段，还会在可见正文顶部加入 Markdown 标题，两种消息模板都如此：

```markdown
### 【项目名称】业务标题

业务项目提交的 content
```

请勿在 `content` 中再重复同一条项目抬头或业务标题，以免出现双标题。除此之外，通知中心不添加固定时间、业务字段顺序或其它正文模板。

## 3. 完整 ActionCard 请求示例

以下为发送接口的 JSON 正文示例。花名、业务记录和地址均为示例值，接入时替换为本项目实际内容；接口鉴权与签名见[接入指南](./接入指南.md#5-请求签名)。

```json
{
  "idempotencyKey": "asset_disposal:53:海棠:v1",
  "recipientAlias": "海棠",
  "title": "资产报废待审批",
  "content": "**申请时间：** 2026年8月31日 15:58\n\n**资产：** 电脑桌（JS-CPU-0704）\n\n**申请人：** 示例员工\n\n**报废原因：** 资产损坏，申请报废。\n\n> 请核对资产及配件明细后处理。",
  "actionTitle": "立即审批",
  "actionUrl": "http://asset.example.com/workflows/disposals/53"
}
```

假设管理面板中的项目名称是“固定资产”，卡片正文为：

```markdown
### 【固定资产】资产报废待审批

**申请时间：** 2026年8月31日 15:58

**资产：** 电脑桌（JS-CPU-0704）

**申请人：** 示例员工

**报废原因：** 资产损坏，申请报废。

> 请核对资产及配件明细后处理。
```

底部按钮显示“立即审批”，点击进入 `http://asset.example.com/workflows/disposals/53`。`**字段名：**` 表示加粗，空行用于分段，`>` 用于引用提示；这些只是可复用的示例排版，不要求所有业务项目都使用相同字段。

## 4. 字段与长度

| 字段 | 规则 |
| --- | --- |
| `title` | 必填，最长 100 字符；拼接项目名称后的最终标题最长 120 字符 |
| `content` | 必填，输入最长 4800 字符；纯文本或 Markdown 均可，显示在固定项目抬头之后 |
| `actionTitle` | 可选，最长 20 字符；有跳转地址但未填写时默认“查看详情” |
| `actionUrl` | 可选；按业务项目提交值使用，不限制协议、公网/内网地址或项目域名白名单 |

当前发送实现会将“`### ` + 最终标题 + 两个换行 + `content`”组成的钉钉 `text` 截取前 4800 字符。因此抬头也占显示额度，超长正文尾部可能被截断；业务详情宜放在跳转页面。业务项目仍对自己提交的原始 JSON 签名，无需预先插入抬头，保存的业务正文也不会因此改写。

## 5. 样式验收

- 确认钉钉聊天中的可见正文顶部有正确的 `【项目名称】业务标题`，不是只看消息摘要或接口返回值。
- 如需 ActionCard，使用非空 `actionUrl` 发送，确认正文格式、底部按钮和实际点击目标。
- 如果选择不提供跳转地址，应预期收到没有按钮的普通 Markdown 消息，而非相同外框的 ActionCard。
- 已发出的旧消息不会随代码、项目配置或测试页变化而自动更新。测试新的样式时创建一条新的测试事件并使用新幂等键；重试同一业务事件时仍复用原幂等键，不能借此绕过防重。