6.8 KiB
ADR-006：生命周期事件与功能模块约定
- 状态：采纳（2026-10-06）；2026-10-12 精简通用链式钩子,保留生命周期事件和功能模块约定。
- 关联：ADR-002（outbox 与任务引擎）、
packages/contracts/src/events.ts（LIFECYCLE_EVENTS）、packages/contracts/src/features.ts（FEATURES、SLOT_POSITIONS）、apps/web/app/lib/slots.ts。 - 参照：MoviePilot v3
app/schemas/types.py的EventType（广播）与ChainEventType（链式），分发在app/runtime/events.py。
背景
外围功能（补字幕、以后的入库后通知、自动补字幕等）需要在业务节点上「知道发生了什么」或「插一手」。MoviePilot 用插件系统 + 两类事件解决。我们是内部工具，用户定了：
- 不做插件系统、插件市场、启停开关；
- 做「功能模块」约定：功能清单只给智能体知道；补齐生命周期事件（参考 MP 的两类事件）；前端插槽要做、默认直接显示。
决定
1. 业务调用与事后通知
同步规则由所属模块 service 明确实现,路由、能力与任务共用业务入口。跨模块需要同步取得结果时显式调用 service。
需要在业务提交后可靠执行的动作(补字幕、通知、预热等)订阅生命周期事件。业务事务内调用 ctx.outbox.emit(trx, …),与业务写入一起提交或回滚；payload 只放 ID 和少量判断事实。中继至少一次投递成任务,接收方按 ID 回查业务表并幂等执行。
原先参考 MP ChainEventType 实现的通用 rewrite/intercept 钩子没有实际业务注册者,本轮删除其注册表、挂点与调用层。以后出现真实扩展需求时再判断抽象方式。modules/decision-hooks.ts 是已有待处理事项的业务处理器,语义不同,继续保留。
2. 广播事件清单
payload schema 都在 EVENT_PAYLOADS（emit 时校验，不合法直接抛错）。已有事件保持原样；download.status_changed / organization.changed 仍是状态流（SSE 与增量游标用，每次变化都发），下表是给功能模块订阅的生命周期事件。
| 事件 | 含义 | 发出位置 | 幂等键 |
|---|---|---|---|
release.resolved |
资源识别完成（已有） | sources-identity resolve.ts 等 |
已有 |
subscription.created |
订阅已建 | 订阅 API 新建、策略自动建（acquisition.ts） |
subscription.created/<id> |
subscription.updated |
订阅已改（参数、暂停、恢复、重新订阅；changes 列字段） |
订阅 API 修改、状态动作 | 无（每次改动一条） |
subscription.completed |
订阅已完成 | completeSubscription、停止日期到达 |
…/<id>/<历史行 id>、…/<id>/stop_after:<日期> |
subscription.cancelled |
订阅已取消（删除即取消） | 订阅 API 删除 / 改状态为 cancelled | 无 |
download.submitted |
下载已提交（已有） | downloads.ts 提交 |
已有 |
download.completed / download.failed / download.removed |
下载完成 / 失败 / 移除 | downloads.ts emitStatus（与 download.status_changed 同事务） |
<type>/<任务 id>/g<代数> |
organization.finished |
整理结束，outcome = succeeded / partial / failed（统一 organization.changed 的终态） |
emitRecord（所有整理记录写入都经过它） |
organization.finished/<记录 id>/<change_seq> |
scrape.completed / scrape.failed |
刮削完成（含部分 / 跳过）/ 失败 | scrape.ts runScrapeRecord 收尾 |
<type>/<记录 id>/<结束时间> |
subtitle.written |
字幕已写入（每个文件一条） | 补字幕 applySubtitles |
subtitle.written/<写入 id> |
media.watched |
作品进入关注（建订阅、开始下载、用户搜索 / 手动认定） | 调用方：订阅 API、submitDownload、resolveRelease |
media.watched/<作品>/<原因>/<触发对象 id> |
media.metadata_refreshed |
作品元数据已刷新 | refreshMetadata 任务处理器（调用方） |
…/<作品>/<任务 run id> |
media.episode_structure_changed |
季集结构已切换（剧集组） | setEpisodeGroup 事务内 |
…/<作品>/<时间> |
site.unreachable / site.recovered |
站点不可达 / 恢复 | 列表抓取连续失败到阈值（与待处理同口径）、登录失效、站点检测结果跨越 | 列表抓取带 …/<站点>/<快照 id>，其余只在跨越时发 |
幂等键用斜杠分隔，与已有的 <type>:<id> 键分开（download.completed:<id> 已被 download.status_changed 占用，outbox 幂等键全表唯一）。
订阅：模块在 outboxRoutes 里写 type → 路由函数。生命周期事件可以有多个订阅方（collectOutboxRoutes 按模块顺序合成），其它事件（内部流程，如 release.observed → resolveObservation）仍只能一个模块认领。路由函数返回任务、任务数组或 null（不建任务）；中继对第一个任务用事件的幂等键、其余用 <键>#<任务名>。没有订阅方的生命周期事件也会被中继认领、标记已投递，并镜像到 SSE（worker/index.ts 的镜像前缀）。
3. 功能模块约定
一个外围功能 = 服务端一个 ServerModule + contracts 里一份 manifest + （可选）前端插槽注册：
- manifest（
FEATURES）：名称、说明、怎么用、订阅的事件、提供的能力、页面入口、插槽位置。服务端模块manifest: featureManifest("<id>")；modules.test.ts核对模块与清单一一对应、订阅的事件与outboxRoutes一致。 - 功能清单只给智能体：系统提示「能力地图」一节末尾列出外围功能（
renderFeatures），能力只列本次可用的。不做开关：功能都直接启用。 - 前端插槽（
apps/web/app/lib/slots.ts）：位置见SLOT_POSITIONS（侧栏入口、作品页操作区、作品页面板区、整理记录行操作、设置分区）。动作类位置注册{ label, icon, visible?, Dialog }，页面渲染成按钮 / 菜单项、点了打开对话框；面板类位置注册组件，挂载点按顺序渲染。注册写在app/features/<功能>.tsx，app/features/index.ts汇总。默认直接显示，不做开关。已挂载：作品页操作区、作品页面板区（library.$id.tsx）、整理记录行菜单（organize.tsx）；侧栏与设置分区先只定义位置。 - 样板：补字幕（
modules/subtitles）——manifest、订阅organization.finished（认出值得补字幕的整理，自动补字幕还没做，只记调试日志不建任务）、写入后发subtitle.written、前端在作品页操作区和整理记录行菜单挂「补字幕」。
不做
- 插件系统、热加载、插件市场、功能开关。
- 把广播事件放进内存队列（MP 做法）：我们已有 outbox，事件要能跨进程、跨重启。