add-biz-message

name	add-biz-message
description	接到"加 Biz 类型 / 加新消息类型 / 加新消息样式 / 发某某卡片 / 想发个表单让用户填 / 消息发出去对端没收到"等需求时触发。引导决策：基础类型 vs 已有 BIZ vs 新增 BIZ；新增 BIZ 必须走后端专属接口 + 前后端共同约定 4 步流程；前端职责仅"调发送接口 + 写展示卡片"。
allowed-tools	["Read","Grep"]

新增 Biz 消息类型决策与流程

触发场景

• 加新消息类型 / 加 Biz 类型 / 加新消息样式
• 发某某卡片功能（不在已有基础卡片范围内）
• 想发个表单让用户填
• 消息发出去对端没收到（排查项之一）
• 改一下订单卡片的展示（先确认是已有 Biz，不触发新 Biz 流程）

步骤 1：先 Read 领域知识

Read .ai/knowledge/message-types.md，拿"现状盘点" + "基础类型枚举" + "BIZ 子类型表"，确认用户说的不是已有能力。

步骤 2：决策树（基础 vs 已有 Biz vs 新 Biz）

场景	走法	理由
内容能用基础类型表达（TEXT/IMAGE/VIDEO/STICKER/CARD/RICH_TEXT 等）	复用既有发送通道	平台标准能力，不该绕过
是已有 BIZ 子类型（ORDER_*/AFTER_SALE/TRANSFER/QUEUE/SATISFACTION/TIMEOUT_WARNING）	复用现有实现	不当新 Biz 处理
平台没覆盖的业务方定制化交互	走新增 BIZ 流程（继续步骤 3）	BIZ 是预留扩展槽

判断顺序：

1. 用基础类型能否表达？能 → 用基础类型
2. 是已有 BIZ 子类型场景？是 → 复用既有 BIZ 实现
3. 不能 → 是不是 IM 平台应该收编为通用能力？是 → 推动 IM 平台扩基础类型，不自己开新 Biz
4. 既不能用基础、不是已有 Biz、也不该收编 → 走新增 BIZ 子类型

步骤 3：新 Biz 强制告知用户（架构 + 前置约束）

3.1 发送架构（强红线）

新 BIZ 子类型的发送链路必须走后端专属接口，禁止前端直接组装 BIZ 消息体走通用 Send 接口。

前端 → 后端专属接口（每个新 bizType 一个）
       → 后端组装消息体 + 执行发送
       → IM 平台分发
       → 接收端按 bizType 渲染卡片

为什么：

• 服务端业务校验 / 关联数据查询 / 状态机操作（如创建工单、生成订单）
• 跨端 schema 一致性（移动端 / Web / 小程序）
• 业务事件可追溯（服务端记录）

3.2 前置约束（4 步前后端协作）

步骤	角色	输出
1	业务方（产品）	bizType 业务语义 + 必要业务字段 + 展示卡片设计稿
2	后端	bizType 定义 + 消息存储/推送格式 + 专属发送接口（必须）
3	前后端	共同约定：发送接口入参 / 消息体字段 / 展示卡片字段 / 错误码 / 兼容策略 → 落到接口文档
4	前端	实现：(a) 调用后端专属发送接口 (b) 接收侧做 bizType 展示卡片

3.3 违反前置约束的真实问题

• 后端没识别 bizType → 消息可能被拒收或落库失败
• 跨端不一致：移动端 / 商家端 / 用户端可能完全看不到（按"未知类型降级 UNKNOWN"处理）
• 前端独立加 bizType → 业务事件丢失（无服务端记录）+ 历史消息无法补救

步骤 4：用户确认后实施

按 5 步 SOP（详见 CLAUDE.md product-need-flow 段）：

• 路由 → 定位 → 复述方案 → 等确认 → 主动验收

前端职责清单（新 Biz）：

1. 调后端专属发送接口（传业务必要字段）
2. 接收侧实现该 bizType 对应的展示卡片（MessageBubble 内新增分支）

前端不做：

• 消息体组装
• 直接调通用 Send 接口发 BIZ

排查：消息发出去对端没收到

按以下顺序排查：

1. 是否新 Biz 但前端绕过后端接口直接发 → 后端可能拒收（最常见）
2. 接收端是否实现了对应 bizType 渲染 → 不然显示 UNKNOWN
3. 后端是否真发出（看 IM 平台 trace）
4. 跨端 schema 是否一致（移动端 / Web / 小程序版本是否同步升级）