[PRD] 自动化对外能力补齐

[ronger-x]

[PRD] 自动化对外能力补齐

子仓库实现 Issue

仓库	Issue	说明
rymcu/mortise-automation	#2	公开 API、Webhook 触发/动作、执行与权限边界
rymcu/mortise-aiot	#17	原生物模型事件入站处理、事件标准化发布
rymcu/admin-automation	#1	场景编辑器与日志页的触发器/动作配置增强

---

问题陈述

当前 Mortise 自动化模块已经具备后台管理、场景执行、执行日志和基础设备联动能力，但对外产品能力仍然不完整。

从用户视角看，主要有三个断点：

1. 场景缺少面向业务端/开放端的正式 API，导致用户无法在自己的应用或集成端里查询、创建和控制属于自己的场景。
2. DEVICE_EVENT 触发能力目前更接近“告警事件驱动”，而不是“设备按物模型上报原生事件后驱动场景”，导致产品语义与用户认知不一致。
3. 平台缺少通用的外部事件接入与外部系统回调能力，难以接入第三方系统、工单系统、告警平台或低代码编排平台。

解决方案

在不新增业务域模块的前提下，基于现有 mortise-automation、mortise-aiot 和管理端 automation layer，补齐一轮“自动化对外能力”：

1. 在 mortise-automation-api 中提供正式的公开接口，面向当前登录主体提供其可见场景与执行记录能力。
2. 将 AIoT 原生物模型事件标准化为自动化可消费的事件源，使 DEVICE_EVENT 真正支持设备事件，而不再只依赖告警映射。
3. 新增 Webhook 触发器与 Webhook 动作，形成“外部系统触发场景”与“场景回调外部系统”的双向集成闭环。
4. 扩展已有管理端场景编辑器，而不是重做后台页面；管理端只补充缺失的配置能力和校验提示。

用户故事

1. 作为业务应用开发者，我希望通过正式 API 查询我可见的自动化场景，以便在业务端展示和管理自动化能力。
2. 作为业务应用开发者，我希望创建、编辑、启用和禁用属于自己的场景，以便用户无需进入后台管理端也能使用自动化功能。
3. 作为业务应用开发者，我希望查询某个场景的最近执行记录，以便排查为什么场景没有按预期执行。
4. 作为设备平台管理员，我希望 DEVICE_EVENT 触发器能直接绑定物模型事件标识，以便场景由设备真实上报的事件驱动。
5. 作为设备平台管理员，我希望已有基于告警的场景仍然能继续工作，以便升级后不破坏已配置规则。
6. 作为集成方，我希望通过一个受控的 Webhook 入口触发场景，以便第三方系统可以把业务事件接入 Mortise 自动化。
7. 作为集成方，我希望场景执行后可以调用外部 Webhook，以便把执行结果同步到工单、告警、通知或其他业务系统。
8. 作为安全管理员，我希望 Webhook 入口和回调都有签名、时间戳、重试和幂等约束，以便避免伪造请求、重复执行和静默失败。
9. 作为后台管理员，我希望在现有场景编辑页中配置上述能力，而不是切换到新的管理入口，以便降低学习成本。

实现决策

• 沿用现有 mortise-automation、mortise-aiot、admin-automation 边界，不新建业务域模块。
• 公开 API 首期只面向当前登录主体自己的场景，不开放复杂共享模型。
• DEVICE_EVENT 升级为标准化事件触发器，兼容 ALERT 与 THING_MODEL_EVENT 两类来源。
• 原生设备事件桥接优先落在 AIoT 应用层，自动化只消费标准化 Spring Event，不直接依赖 MQTT 协议细节。
• 新增 WEBHOOK 触发器和 WEBHOOK 动作；安全要求包含签名、时间窗、幂等和失败落日志。
• 管理端仅扩展现有场景页与日志页，不重写后台入口。

测试决策

• 公开 API 覆盖身份隔离、越权访问、自有场景 CRUD、执行记录查询。
• AIoT 覆盖原生设备事件入站解析、物模型事件匹配、标准化事件发布。
• 自动化应用层覆盖 Webhook 签名校验、幂等约束、失败重试、执行日志落库。
• 管理端覆盖 DEVICE_EVENT 新配置、Webhook 触发器和动作的提交结构。
• 至少保留一条端到端用例：设备事件或外部 Webhook 进入平台，场景命中，动作执行，执行日志可查询。

垂直切片拆分

切片 1：公开场景查询与自有场景 CRUD

覆盖的用户故事：1、2

验收标准：

• 当前登录主体可以查询自己的场景列表与详情。
• 当前登录主体可以创建、编辑、删除、启用、禁用自己的场景。
• 非本人场景不可被读取或修改。

切片 2：公开执行记录查询

覆盖的用户故事：3

验收标准：

• 当前登录主体可以查询自己场景的执行记录。
• 查询结果支持按场景和状态过滤。
• 非本人场景的执行记录不可见。

切片 3：原生物模型事件驱动 DEVICE_EVENT

覆盖的用户故事：4、5

验收标准：

• 设备按物模型上报事件后，平台能够标准化发布事件并触发场景。
• 新建场景可以区分 ALERT 与 THING_MODEL_EVENT 两类事件来源。
• 存量基于告警的场景无需改造即可继续工作。

切片 4：Webhook 触发器

覆盖的用户故事：6、8、9

验收标准：

• 管理端可以为场景配置 Webhook 触发器。
• 平台生成可调用的 Webhook 入口。
• 请求必须通过签名与时间窗校验才会触发场景。

切片 5：Webhook 动作

覆盖的用户故事：7、8、9

验收标准：

• 管理端可以为场景配置 Webhook 动作。
• 场景执行后会按配置向外部系统发送 HTTP 请求。
• 非成功响应会被有限重试，并在执行日志中体现最终状态。

范围外

• 地理围栏触发器
• 场景版本化与审批流
• 场景模板市场或一键导入
• AlertRule → Scene 迁移工具
• OTA 场景动作
• 通用 MQTT 长连接治理或 Broker 适配大重构

补充说明

这是跨仓库需求，提交后请保留本 PRD Issue 作为 Parent PRD，子仓库实现 Issue 统一引用本 Issue。