JSM Bot v2 正式切换清单

1. 切换范围与已知资源

2. Request Type 与字段快照

“Submit a request” 的 Request Type ID 已能定位，但由于正式表单字段尚未迁移， 下表中的目标 ID只能作为切换目标候选；字段完成修改后必须重新读取元数据并再次确认。

2.1 表单迁移后必须核对的目标字段

2.2 Repo 修改点

• 同步修改 jsm-production-v2/slack-bot/request-fields.json 和 jsm-production-v2/lark-bot/request-fields.json： 三个 requestTypeId、必填状态和选项快照。
• 保持两份 JSON 完全一致；现有测试会检查一致性。
• 更新 jsm-production-v2/config.test.js 中 2164、30、4398 的断言。
• 如果字段 ID 与预期一致，不需要修改 Bot 表单代码和 Create Handler。
• 如果 Org / Cluster / Lake 字段 ID 发生变化，修改 create-issue-handler/snapshot-payload.js，并同时修改 Slack/Lark app.js 的字段构造逻辑和相关测试。
• 更新 README 和 infrastructure/deployment-state.md， 删除“仅 pilot 启用”和“TEST FORGE”过期说明。

3. Channel / Group 配置

4. 正式应用凭证与 Lambda 环境变量

AWS 只读比对结果显示：v2 当前使用的 Slack/Lark 应用凭证与线上正式应用不同。 正式切换不能只换回调 URL，必须先换 v2 Lambda 中的应用凭证。不得把值写入 repo。

4.1 必须保留的 v2 独立变量

• SQS_QUEUE_URL：继续指向 JsmBotTicketQueue-v2，不能复制旧队列 URL。
• EXPECTED_SQS_QUEUE_NAME=JsmBotTicketQueue-v2。
• EXPECTED_JSM_HOST：继续使用当前生产 JSM host 保护值。
• BOT_EVENT_SOURCE、LARK_EVENT_SOURCE：保持 v2 当前约定。
• DATABASE_URL、JSM_SITE：当前与正式版一致，无需修改。
• 飞书 LAMBDA_API_URL 必须保持为 v2 地址： https://abfl58h599.execute-api.us-west-2.amazonaws.com/default/lark-support-bot-v2。

5. Slack / 飞书回调地址

5.1 Slack 正式应用

• 先更新 v2 的正式 Signing Secret，再验证 Slack URL challenge。
• 三个地址全部切换；漏掉 Options Load URL 会导致 Cluster/Lake 搜索无结果。
• 确认正式 App 的事件 scope、Bot scope 和 Channel 安装状态不变。
• 确认按钮、Modal、external_select 都在 3 秒内完成 ack。

5.2 飞书正式应用

• 先更新 v2 的正式 App ID、Secret、Union ID，再进行 URL 校验。
• 确认事件订阅和卡片回调均已发布到正式应用版本，而不是只保存草稿。
• 验证群内 @Bot、类型选择、表单提交、成功卡片自动消失。
• 确认 API Gateway 3 秒内返回，耗时工作继续通过异步调用/SQS 完成。

6. JSM Automation Webhook

JSM → IM 的评论、状态和附件同步由 Jira Automation 的 Send web request 调用 Bot API Gateway。正式切换时必须搜索 ST、TCID、 TCLID 范围内所有指向旧地址的规则，不应只修改一个评论规则。

• 导出/备份每条 Automation 完整规则 JSON。
• 检查 comment created、status changed、attachment/comment webhook 等所有规则。
• 只替换 URL，保留请求体、header、触发条件和隐藏值。
• 修改前通过 Automation validation；修改后重新读取确认。
• 不要让同一事件同时发给旧 URL 和新 URL，否则会重复同步。

7. SQS 与 Create Handler

• 切换前确认 v2 Queue、DLQ 都没有历史失败消息。
• 确认 Slack/Lark v2 均发送到 v2 Queue。
• 创建 ST、TCID、TCLID 各一单，确认 batch item failure 不会重复提单。
• 保留旧 Mapping 到旧队列排空；排空后禁用，不要立即删除。

8. Org / Cluster / Lake 同步

• 正式切换前手工运行一次 v2 Sync，确认 18 个 Org 均完成。
• 核对 Org、Cluster、Lake snapshot active/deleted 数量和最近同步时间。
• 等待并确认至少一次 v2 Scheduler 自动执行成功。
• 确认 Bot 表单能读取目标 Org 的 Cluster/Lake。
• 验证后再禁用旧 jsm-orgs-daily-sync；先禁用，不删除。

9. AWS 运行配置

• Slack、飞书、Create Handler 保持无 Reserved Concurrency，与正式版一致。
• IAM Role 当前已按正式版权限模型建立；切换前重新检查 Logs、SQS、飞书自调用权限。
• 不要把 v2 Handler 改回根目录旧路径。
• 切换发布时重新 build，必要时发布新的不可变 Layer version，并让四个 Lambda 指向同一已验证版本。
• 确认 API Gateway access log、Lambda log 和 SQS/DLQ 告警可用。

10. 推荐切换顺序

11. 验收清单

11.1 提单

• Slack 创建 ST Enterprise、TCID Premium、TCLID Lake 工单。
• 飞书创建 ST Enterprise、TCID Premium、TCLID Lake 工单。
• Reporter 来自 IM 用户映射，未使用 Slack 表单中的 Reporter email。
• Org payload、Cluster payload、Lake payload 与 snapshot 一致。
• Cluster 为空、已删除或不存在时 Cloud 工单仍能创建。
• 附件、特殊字符、链接、HTML 文件均能正确创建和展示。
• 同一表单提交只产生一张工单，没有 SQS 重复消费。

11.2 评论同步

• Premium：Slack/飞书 → JSM 和 JSM → Slack/飞书均同步。
• Enterprise：按当前设计不进行双向评论同步。
• 旧工单的 ticket_thread 可以被 v2 继续读取。
• 链接、inlineCard、代码中的 </>、图片和多个文件正确。
• Automation 只调用 v2，不产生新旧 Bot 双份消息。

11.3 运行状态

• API Gateway 无新增 5xx，Slack/Lark 回调在 3 秒内响应。
• 四个 v2 Lambda 均为 Active / Successful，无持续错误或超时。
• v2 Queue 可见消息归零，DLQ 为 0。
• Org Sync 18 个 Org 全部完成，个别失败不会阻塞其他 Org。

12. 回滚方案

1. Slack App 三个 URL 恢复为 https://51c5tv1vsk.execute-api.us-west-2.amazonaws.com/default/slack-bot。
2. 飞书事件和卡片 URL 恢复为 https://rw75r1e3bi.execute-api.us-west-2.amazonaws.com/default/lark-support-bot。
3. 将 JSM Automation Send web request 恢复到旧 URL。
4. 如已禁用，重新启用旧 Queue Event Source Mapping 和旧 Org Sync schedule。
5. 暂停 v2 Bot 回调流量；保留 v2 snapshot 和线程数据用于排查。
6. 检查两边 Queue，避免回滚期间重复消费或遗漏工单。