MoviePilot/docs/subscription-activity.md

# 订阅业务活动

订阅卡片的“订阅活动”按执行轮次显示业务事件，完成后的订阅可从订阅历史的同名入口查看。弹窗右上角的“运行日志”继续打开原有订阅日志、实时流与下载入口；历史订阅没有原有实时日志权限，因此该辅助入口禁用。

## 事件和计数

新建、可见规则修改、状态变更、RSS 刷新匹配、订阅搜索和订阅完成由业务边界直接记录。修改更新时间、搜索时间等内部字段不会产生一条规则修改事件。升级前没有业务事件的历史不会通过运行日志补造。

| 指标 | 事实口径 |
| --- | --- |
| 搜索站点 | 本轮计划搜索的站点数；实际请求另外计数，缓存结果和未发出的等待请求不会冒充网络请求 |
| 发现候选 | 来源返回的候选项数，包括插件结果；多页、多关键词返回的项目按来源处理累计 |
| RSS 共享候选 | 本轮交给匹配流程的完整共享候选数，不能当作该订阅的相关资源数 |
| 本订阅相关 | 身份关联后的资源，按站点与资源 ID 去重；没有 ID 时使用标题作为同站点备用身份 |
| 符合条件 | 通过条件或已成功提交的相关资源，单独去重 |
| 提交下载 | 下载链确认提交成功的资源，单独去重；种子内容获取失败、准备失败和下载器拒绝有独立解释 |
| 已入库集数 | 来自订阅文件接口的真实媒体库文件，不能用下载提交计数或订阅缺失进度代替 |

正常零结果使用中性状态。站点繁忙显示等待和实际续跑时间，全部站点请求失败显示失败，部分站点失败保留各站点结果和提示。停止不会撤销已成功提交的下载。资源和站点详情保留安全摘要，排除下载链接、Cookie、passkey 和原始响应。

## 请求、恢复和条件快照

搜索请求入队时创建活动，合并请求更新原等待计划，保留原请求时间和事件身份。开始执行后冻结实际使用的订阅条件；恢复执行沿用任务身份、累计去重计数，并保留每次处理的结果和条件。入队后、执行前修改条件时，不会把旧请求条件误当作实际执行条件。

后台观察使用独立短事务，保存故障不会逆转已确认的下载。队列入队及终态观察使用保存点，失败不会回滚任务本身。新建、修改和完成活动由订阅事务暂存，提交与回滚一起发生。

资源摘要和恢复记录各保留最多 100 项，资源摘要优先保留下载回执、提交失败及符合条件的资源；完整概要计数不受资源摘要上限影响，界面明确提示未保留明细的数量。站点列表记录本轮实际来源。内部去重键单独保存，不出现在 API 响应中。

## 查询和归属

- `GET /api/v1/subscribe/{subscription_id}/activity`：概要游标分页；可按事件类型、最近天数筛选。
- `GET /api/v1/subscribe/{subscription_id}/activity/{event_id}`：按需加载完整详情。
- 两个接口均要求登录，并在每次请求校验当前订阅或历史订阅的 owner；管理员可查看。
- `history=true` 使用历史订阅 ID，不能与当前订阅的整数 ID 混用。
- 不可复用的 `activity_key` 随完成快照进入历史；活动按递增记录游标分页，避免并发新增导致重复翻页。

接口属于经鉴权的前端展示合同，未增加稳定 Agent gateway 操作。Application 定义事实与 Port，数据库 Adapter 实现短事务及归属隔离，Oper 只提供查询和暂存，组合根注入依赖；新增表配套 Alembic 迁移。