yida-form-message · diff
git:20261020.943f19c to git:20261021.d7c0e03
27 added, 8 removed. Audit A to A.
---
name: yida-form-message
- description: 查询和维护已有普通表单「页面设置 > 消息通知」中的原生触发、接收对象和消息模板。适用于提交、编辑、删除或评论后的表单通知；不用于应用级通知、自定义页面消息、机器人发送或集成自动化。
+ description: 为已有普通表单配置消息通知，选择新增、编辑、删除或评论后的发送时机、接收人和消息样式。支持工作通知、详情卡片、图文卡片、评论卡片和群置顶卡片等七种模板；按用户要求执行真实发送测试。
---
# 表单消息通知
- 使用 `openyida form-message` 管理表单级原生消息绑定。先查询目标表单和选项，再按用户明确要求创建或修改；保存配置不会立即发送测试消息。
+ 为已有普通表单配置“什么时候、向谁、发送什么通知”。使用 `openyida form-message` 查询、新增、修改和删除「页面设置 > 消息通知」中的配置。保存后，表单事件发生时发送通知。
+ ## 适用场景
+
+ | 用户需求 | 使用入口 |
+ | --- | --- |
+ | 配置表单新增、编辑、删除或评论后的消息通知 | 本技能 |
+ | 查询日期定时、流程开始/结束、流程节点或审批操作的已有通知 | 本技能查询；这些类型的修改使用宜搭页面 |
+ | 配置集成自动化中的通知节点 | `yida-integration` |
+ | 应用级通知、自定义页面消息、机器人消息 | 对应功能入口，独立于表单消息设置 |
+
+ ## 操作步骤
+
+ 1. 查询现有通知和可用选项，核实目标表单、字段、接收人和模板。
+ 2. 按用户要求准备配置文件，再创建或修改通知。首次配置可从[发送给发起人的示例](references/guide.md)开始。
+ 3. 核对保存结果中的 `readbackVerified: true`，交付通知 ID、触发时机和接收对象。用户要求真实测试时，按已指定的对象和范围执行并确认送达；已有明确授权可直接沿用。
+
```bash
openyida form-message list <appType> <formUuid> --json
openyida form-message options <appType> <formUuid> --json
openyida form-message inspect <appType> <formUuid> <messageId> --json
openyida form-message create <appType> <formUuid> --config message.json --json
openyida form-message update <appType> <formUuid> <messageId> --config patch.json --expected-hash <configHash> --json
```
- 普通表单已验证的写入触发为 `FORM_DATA_CREATE`、`FORM_DATA_EDIT`、`FORM_DATA_DELETE`、`FORM_COMMENT`。日期字段定时、流程开始/结束、流程节点和审批操作的已有配置可查询，但当前 CLI 会拒绝写入这些未完成独立目标验证的规则。不要用近似触发或集成自动化冒充原生设置。
+ ## 配置规则
- 接收人可以是指定人员、角色、人员字段或系统变量 `originator`；用 `options` 返回的真实字段 ID。群置顶模板使用 `groups` 中的平台群 ID。一次消息最多选择 100 人；具体人员可见性、离职状态、群成员关系和组织版本仍由平台控制。
+ 普通表单支持新增、编辑、删除和评论后通知。接收对象支持指定人员、角色、表单人员字段和发起人；群置顶模板使用平台群 ID。模板中文名称、参数和选用方式见[配置指南](references/guide.md)。
- 模板 key 包括 `workNotice`、`detailImage`、`imageCard`、`detailText`、`commentCard`、`pinnedImage`、`pinnedText`。工作通知及普通卡片发送给人，置顶卡片发送到群；详情类模板的字段映射只使用 `options.messageFields` 或系统字段。配置结构、变量和场景见 [reference](references/guide.md)。
+ 更新时 `template` 属性合并，`recipients`、`groups` 和 `template.fields` 数组整体替换。CLI 写入前自动备份并检查配置是否变化。遇到超时或回读不一致，保留 `backupPath`，先执行 `list` / `inspect` 确认远端状态，再决定下一步；不自动重放写请求。
- 更新时 `template` 属性合并，`recipients`、`groups` 和 `template.fields` 数组整体替换。写入前自动备份并再次比较列表；写后必须看到 `readbackVerified: true`。超时或回读不一致时保留 `backupPath`，先重新 list/inspect，不自动重放创建、更新或删除。
+ ## 删除与测试
- 平台当前没有独立启停字段或启停接口；不要把 `isSendMessage` 当作通知开关。移除配置只能删除，必须由用户明确要求，使用最新 hash：
+ 用户明确要求移除通知时，先用 `inspect` 获取最新 `configHash`，再执行删除。平台当前提供配置删除功能，没有独立启停接口；`isSendMessage` 是平台原生字段，不是通知开关。
```bash
openyida form-message delete <appType> <formUuid> <messageId> --expected-hash <configHash> --yes --json
```
- 删除后重建会产生新 ID，备份不能自动恢复旧引用。配置保存、触发生效和消息实际送达是三项独立证据；未经单独授权，不提交表单数据、不发送测试通知、不向真实人员或群发消息。
+ 删除后重建会产生新 ID；备份保留原配置内容，恢复时需重新核对引用。真实测试使用独立测试目标，业务配置按用户指定的表单执行。测试前确认用户已授权触发表单事件及对应接收对象；交付时分别记录配置保存、事件触发和接收端送达结果。测试结束后，按用户要求保留或清理配置和数据。
+
+ ## 参考文件
+
+ - [配置指南](references/guide.md)：四种触发、七种模板、接收对象、变量格式和配置示例。