@microi.net/cli 5.5.9 → 5.6.1

package/skills/message-notification/references/contracts.md

@@ -1,102 +1,102 @@
-# 消息通知契约
-
-## 表结构并集
-
-### `mic_msgset`
-
-| 字段 | 用途 |
-|---|---|
-| `Key` | 稳定业务键，租户内唯一 |
-| `Title` | 配置名称/默认标题 |
-| `IsEnable` | 总开关 |
-| `Type` | 多选渠道：微信公众号模板消息、短信、邮件、平台内部 |
-| `Receivers` | 固定接收用户 JSON |
-| `ReceiversRoles` | 固定接收角色 JSON |
-| `WxTplMsgId` | 公众号模板配置 Id |
-| `ChannelApiEngineMap` | 渠道到适配器接口引擎 Key 的 JSON 映射 |
-| `TenantId/TenantName` | 业务层租户信息；不能替代 MCP 的 OsClient 边界 |
-| `TableChild99` | 兼容已有子表配置 |
-
-### `wx_tpl_msg`
-
-| 字段 | 用途 |
-|---|---|
-| `Key/Title/TemplateId/Content/Remark/LinkUrl` | 模板业务键、标题、微信模板 Id、内容与普通跳转 |
-| `WxMpId/WxMpName` | 发送模板消息的公众号或服务号；关联 `wx_mp` |
-| `MiniProgramId/MiniProgramName` | 可选小程序配置；关联 `wx_mini_program` |
-| `MiniProgramAppId/MiniProgramPagePath` | 模板消息的可选小程序跳转目标 |
-
-公众号和服务号都属于微信公众帐号，由 `wx_mp` 保存发送凭据。小程序由 `wx_mini_program` 保存，不能使用小程序 AppId 调用公众号模板消息发送接口。
-
-### `mic_msg_event_log`
-
-| 字段 | 用途 |
-|---|---|
-| `EventId` | 调用方稳定幂等键 |
-| `MsgEventId` | 关联的消息设置 Id |
-| `ChannelType` | 本条日志对应的渠道 |
-| `ReceiverUserId` | 单一接收用户 Id |
-| `Receivers` | 接收人安全快照 JSON |
-| `Title/MsgContent/LinkUrl/Payload` | 通知展示快照 |
-| `IsRead/ReadTime` | 平台内部通知已读状态 |
-| `IsSuccess/MsgResult` | 分发状态和经过脱敏的结果 |
-
-索引基线：
-
-- 唯一：`EventId, ChannelType, ReceiverUserId`；共享表模型再前置 `OsClient`。
-- 普通：`ReceiverUserId, ChannelType, IsRead, CreateTime`。
-- `mic_msgset.Key`、`wx_tpl_msg.Key` 在租户业务库内唯一。
-
-## V8 接口
-
-### `msg_event`
-
-输入：
-
-```js
-{
-  MsgKey: '策略 Key',
-  EventId: '稳定幂等键',
-  ReceiverUserId: '可选单用户',
-  ReceiverUserIds: ['可选用户数组'],
-  Title: '可覆盖配置标题',
-  Content: '正文',
-  LinkUrl: '/#/route',
-  Payload: { BusinessId: '...' }
-}
-```
-
-处理顺序：校验当前租户与登录上下文 → 读取启用策略 → 合并固定用户、角色用户和参数用户 → 去重/限流 → 按接收人和渠道插入日志 claim → 仅对 claim 成功项分发 → 汇总成功、失败、重复。出现部分失败时仍要提交已经产生的日志与外部副作用，并把失败逐项返回，不能为了漂亮的 `Code` 回滚成功事实。
-
-### `msg_internal_list`
-
-- 仅返回 `V8.CurrentUser.Id` 的 `ChannelType=平台内部` 记录。
-- 支持 `PageIndex/PageSize`，`PageSize` 最大 100。
-- `DataAppend.UnreadCount` 返回同一用户权威未读数。
-- 每条记录统一投影 `SenderUserId/Account=AI`、`SenderName=AI助手`、`ReadOnly=false`；聊天侧只能固定一个 AI 助手联系人，并将通知权威历史与 AI 聊天历史按时间合并。
-- 兼容旧 `MICROI_PLATFORM_ADMIN/admin` 元数据时只改显示投影，不批量删除或改写 `mic_msg_event_log` 历史事实。
-
-### `msg_internal_mark_read`
-
-- `{ Id }` 只允许更新当前用户拥有的单条平台内部通知。
-- `{ All: true }` 更新当前用户全部未读平台内部通知。
-- 不接受客户端指定 `ReceiverUserId` 越权操作。
-
-### `V8.Notification.Send`
-
-`ReceiverUserId/ReceiverUserIds` 必填其一，最多 200 个；`Title` 最长 200 字符；`Content` 与序列化后的 `Payload` 各最多 32 KiB；`LinkUrl` 最长 500 字符且只允许站内路径、锚点、HTTP/HTTPS。事件名固定为 `ReceivePlatformNotification`。
-
-## 验收矩阵
-
-| 场景 | 断言 |
-|---|---|
-| 重复请求 | 同一接收人/渠道只存在一条日志，适配器不重复产生业务副作用 |
-| 两节点同时发送 | 唯一索引只有一个 claim 成功，两节点都不崩溃 |
-| 写入后节点退出 | 日志仍可查询；发送状态可审计、可补偿 |
-| SignalR/Redis 短故障 | 业务写入不回滚，客户端列表回读恢复 |
-| SignalR Hub 调用聊天运行时 | `StopHttp=1` 保持关闭；仅固定 Key/租户/权威用户绑定的一次性宿主上下文可通过，V8 原子消费一次 |
-| 事务回滚 | 不产生实时通知，业务日志随事务回滚 |
-| 离线用户 | 下次打开通知中心能看到并标记已读 |
-| 越权读取/已读 | 其它用户 Id 无效，记录不改变 |
-| 微信配置 | `WxMpId` 决定发送主体，小程序字段只决定跳转 |
-| 应用安装 | 无密钥、OpenId、历史日志或固定用户；安装后字段/索引/接口回读一致 |
+# 消息通知契约
+
+## 表结构并集
+
+### `mic_msgset`
+
+| 字段 | 用途 |
+|---|---|
+| `Key` | 稳定业务键，租户内唯一 |
+| `Title` | 配置名称/默认标题 |
+| `IsEnable` | 总开关 |
+| `Type` | 多选渠道：微信公众号模板消息、短信、邮件、平台内部 |
+| `Receivers` | 固定接收用户 JSON |
+| `ReceiversRoles` | 固定接收角色 JSON |
+| `WxTplMsgId` | 公众号模板配置 Id |
+| `ChannelApiEngineMap` | 渠道到适配器接口引擎 Key 的 JSON 映射 |
+| `TenantId/TenantName` | 业务层租户信息；不能替代 MCP 的 OsClient 边界 |
+| `TableChild99` | 兼容已有子表配置 |
+
+### `wx_tpl_msg`
+
+| 字段 | 用途 |
+|---|---|
+| `Key/Title/TemplateId/Content/Remark/LinkUrl` | 模板业务键、标题、微信模板 Id、内容与普通跳转 |
+| `WxMpId/WxMpName` | 发送模板消息的公众号或服务号；关联 `wx_mp` |
+| `MiniProgramId/MiniProgramName` | 可选小程序配置；关联 `wx_mini_program` |
+| `MiniProgramAppId/MiniProgramPagePath` | 模板消息的可选小程序跳转目标 |
+
+公众号和服务号都属于微信公众帐号，由 `wx_mp` 保存发送凭据。小程序由 `wx_mini_program` 保存，不能使用小程序 AppId 调用公众号模板消息发送接口。
+
+### `mic_msg_event_log`
+
+| 字段 | 用途 |
+|---|---|
+| `EventId` | 调用方稳定幂等键 |
+| `MsgEventId` | 关联的消息设置 Id |
+| `ChannelType` | 本条日志对应的渠道 |
+| `ReceiverUserId` | 单一接收用户 Id |
+| `Receivers` | 接收人安全快照 JSON |
+| `Title/MsgContent/LinkUrl/Payload` | 通知展示快照 |
+| `IsRead/ReadTime` | 平台内部通知已读状态 |
+| `IsSuccess/MsgResult` | 分发状态和经过脱敏的结果 |
+
+索引基线：
+
+- 唯一：`EventId, ChannelType, ReceiverUserId`；共享表模型再前置 `OsClient`。
+- 普通：`ReceiverUserId, ChannelType, IsRead, CreateTime`。
+- `mic_msgset.Key`、`wx_tpl_msg.Key` 在租户业务库内唯一。
+
+## V8 接口
+
+### `msg_event`
+
+输入：
+
+```js
+{
+  MsgKey: '策略 Key',
+  EventId: '稳定幂等键',
+  ReceiverUserId: '可选单用户',
+  ReceiverUserIds: ['可选用户数组'],
+  Title: '可覆盖配置标题',
+  Content: '正文',
+  LinkUrl: '/#/route',
+  Payload: { BusinessId: '...' }
+}
+```
+
+处理顺序：校验当前租户与登录上下文 → 读取启用策略 → 合并固定用户、角色用户和参数用户 → 去重/限流 → 按接收人和渠道插入日志 claim → 仅对 claim 成功项分发 → 汇总成功、失败、重复。出现部分失败时仍要提交已经产生的日志与外部副作用，并把失败逐项返回，不能为了漂亮的 `Code` 回滚成功事实。
+
+### `msg_internal_list`
+
+- 仅返回 `V8.CurrentUser.Id` 的 `ChannelType=平台内部` 记录。
+- 支持 `PageIndex/PageSize`，`PageSize` 最大 100。
+- `DataAppend.UnreadCount` 返回同一用户权威未读数。
+- 每条记录统一投影 `SenderUserId/Account=AI`、`SenderName=AI助手`、`ReadOnly=false`；聊天侧只能固定一个 AI 助手联系人，并将通知权威历史与 AI 聊天历史按时间合并。
+- 兼容旧 `MICROI_PLATFORM_ADMIN/admin` 元数据时只改显示投影，不批量删除或改写 `mic_msg_event_log` 历史事实。
+
+### `msg_internal_mark_read`
+
+- `{ Id }` 只允许更新当前用户拥有的单条平台内部通知。
+- `{ All: true }` 更新当前用户全部未读平台内部通知。
+- 不接受客户端指定 `ReceiverUserId` 越权操作。
+
+### `V8.Notification.Send`
+
+`ReceiverUserId/ReceiverUserIds` 必填其一，最多 200 个；`Title` 最长 200 字符；`Content` 与序列化后的 `Payload` 各最多 32 KiB；`LinkUrl` 最长 500 字符且只允许站内路径、锚点、HTTP/HTTPS。事件名固定为 `ReceivePlatformNotification`。
+
+## 验收矩阵
+
+| 场景 | 断言 |
+|---|---|
+| 重复请求 | 同一接收人/渠道只存在一条日志，适配器不重复产生业务副作用 |
+| 两节点同时发送 | 唯一索引只有一个 claim 成功，两节点都不崩溃 |
+| 写入后节点退出 | 日志仍可查询；发送状态可审计、可补偿 |
+| SignalR/Redis 短故障 | 业务写入不回滚，客户端列表回读恢复 |
+| SignalR Hub 调用聊天运行时 | `StopHttp=1` 保持关闭；仅固定 Key/租户/权威用户绑定的一次性宿主上下文可通过，V8 原子消费一次 |
+| 事务回滚 | 不产生实时通知，业务日志随事务回滚 |
+| 离线用户 | 下次打开通知中心能看到并标记已读 |
+| 越权读取/已读 | 其它用户 Id 无效，记录不改变 |
+| 微信配置 | `WxMpId` 决定发送主体，小程序字段只决定跳转 |
+| 应用安装 | 无密钥、OpenId、历史日志或固定用户；安装后字段/索引/接口回读一致 |