# Input v1：内容监控自动追踪 QoL（v7.6.3）

> 阶段：`input_code_grounded`
> 版本：`v7.6.3`（短写 `763`）
> 日期：2026-09-20
> 结论：**建议开版本；暂停/恢复、另存为新规则、可选历史补扫、收藏夹/其他规则频道选择和生效期共同进入 Spec。产品规则已确认，具体存储与执行方案交由研发设计。**
> 本文用途：作为后续 `input -> spec -> design -> prd` 的上游输入，不直接冻结接口、配额或页面稿。

## 0. 一句话定义

让内容监控的自动追踪规则从“只能手动录入、编辑原规则、按账号默认周期运行”升级为可复用、可控、可解释的规则资产：频道可以从收藏夹或其他规则批量带入，编辑可以另存为新规则，规则支持暂停/恢复和明确的 7 天、30 天、长期生效期；用户还可以在规则生效时选择向前补扫最近 3、7 或 30 天的同规则命中内容，补扫覆盖全平台、不消耗独立配额，并复用未来追踪的内容去重和监控创建逻辑。

## 1. 需求清单与初步裁决

| 需求 | 代码事实 | 初步可行性 | 建议落地 |
| --- | --- | --- | --- |
| 批量添加频道：收藏夹、其他规则 | 自动追踪表单已有手动添加和 Excel 上传；资源夹已有简表、详情和频道列表接口；规则已有 list/detail | **中** | 收藏夹和其他规则都只是“选择频道”的来源，不携带关键词或短链，不自动保存规则；频道进入当前表单后仍由用户完成规则保存和既有校验 |
| 修改规则时另存为新规则 | 前端已有 `addInfluencer`（新增）和 `updateInfluencer`（更新）两条链路，更新由 `ruleId` 决定；后端已有同名校验 | **高** | 另存为新规则走新规则保存链路；保存成功后追加询问“是否立即生效”，用户确认后再启动新规则，取消则保留为未生效状态 |
| 可选追踪历史内容 | 当前只能向后追踪未来增加内容；现有“历史”接口只查监控/自动追踪用量历史，不是内容回溯接口 | **中（需复用现有异步执行链路）** | 历史补扫只在新建或另存为保存时触发；当前不对外开放 UI，但数据模型保留补扫起止时间；用户感知上与未来追踪一致，不新增独立配额或重试规则 |
| 自动追踪规则暂停/恢复 | 前端已有状态列操作；后端已有 `pauseMonitor`、`restoreMonitor`，状态 8/6/4 可恢复，运行中为 1 | **高（现有能力的语义修正）** | 暂停期间停止追踪并暂停计费；恢复时重新计算新的生效起点和到期时间。需把“用户暂停”“配额阻断”“已过期”从展示语义上分开 |
| 生效期 7 天、30 天、长期 | 当前后端按账号 `Scope_Business_Star_Track_Days` 计算到期时间，缺省 7 天；前端 `monitorDays` 会发送，但服务端 VO 没有该字段，时长不是用户级规则选择 | **中低** | 新增显式 `durationMode=7d|30d|permanent`；本版本沿用 7 天计费方式，不因 30 天或长期新增计费规则，后续再单独扩展高于 7 天的计费口径 |

## 2. 当前线上实现事实

### 2.1 前端页面与交互入口

- 入口是内容监控项目页 `pages/video-monitor/monitor.vue`，右侧抽屉由 `components/videoMonitor/monitor/addAndAutoTrack/index.vue` 承载。
- 抽屉的“自动追踪新内容”左侧是 `autoTrackForm.vue`，右侧是 `autoTrackList.vue`；规则编辑通过列表 `edit` 事件回填表单，保存成功后刷新列表。
- 当前频道来源只有两种：手动添加和 Excel 批量上传。`autoTrackUpload.vue` 调用 `/ws/monitor/video/task/checkUploadFile`，确认后把 `passList` 合并到表单；没有收藏夹选择器，也没有从其他规则复制的入口。
- 当前表单保存参数包含 `projectId / ruleName / monitorDays / stars / words`；存在 `editingRuleId` 时附带 `ruleId`，从而切换为更新接口。前端可自然增加“另存为”分支，但需要确认后端是否允许同一组频道、关键词和短链被新规则复用。
- 当前规则列表显示规则名、添加时间、到期时间、频道、关键词、状态；状态列已有编辑、停止/启动、删除操作。进行中规则不提供删除。

### 2.2 前端 API 事实

`kol-next/api/videoMonitor/list.js` 当前声明：

- 新增/更新：`POST /ws/monitor/video/task/addInfluencer`、`POST /ws/monitor/video/task/updateInfluencer`；
- 规则查询：`GET /ws/monitor/video/rule/list`、`GET /ws/monitor/video/rule/detail`、`GET /ws/monitor/video/rule/listSimple`；
- 生命周期：`GET /ws/monitor/video/rule/pauseMonitor`、`GET /ws/monitor/video/task/restoreMonitor`；
- 删除：`GET /ws/monitor/video/rule/delete`（前端注释仍标为占位，路径字符串有前导空格风险，需在 Spec/联调时复核）；
- 当前规则 list/detail 的数据形态是 `id/ruleName/stars/words/status/createTime/monitorDuration`，前端再归一化为 `ruleId/kolList/keywords/addTime/expireTime`。

### 2.3 服务端归属与数据模型

- 在当前工作区代码中，`kol_server_v2` 没有上述自动追踪接口；实际实现位于旧 `KOLServer` 的 `VideoMonitorAutoTrackService` 和 `MonitorIndependentModularityController`。因此本版本必须按旧服务端归属评估，不能只改新服务端。
- 规则主表是 `video_monitor_project_rules`，关联频道表 `video_monitor_project_stars`、关键词表 `video_monitor_project_words` 和短链关系表。规则的 `status` 不是主表持久字段，而是由关联频道状态动态归并。
- 新建规则由 `addInfluencer` 创建规则主记录，再同步频道、短链和关键词；更新由 `updateInfluencer` 按 `ruleId` 先删除差异频道/短链，再补齐当前提交内容。
- 服务端保存前要求至少有一个关键词，或每个频道都有有效 Nox 短链；当前后端关键词上限为 5、前端表单上限为 10，v7.6.3 将统一为产品上限 10，并同步修正后端校验。
- 规则名在同一项目内必须唯一。项目访问按创建人或协作者校验，活动关联另有成员权限校验。

### 2.4 当前时间窗和状态事实

- 当前规则有效期由 `buildRuleMonitorDuration()` 计算：`now + getMonitorRuleQuotaDays(parentUid)`；账号没有配置时回退 7 天。
- 运行中规则编辑不会因为普通编辑自动延长到期时间。新增频道时沿用现有规则周期；已过期规则编辑保留原历史时间，恢复动作才会重新计算一个新周期。
- 频道状态至少包含运行中 `1/2`、过期 `4`、配额不足 `6`、暂停/终止 `8`；规则状态由这些频道状态归并。SQL 中 `monitor_duration is null` 的历史数据按 `create_time + 7 天` 判断过期，因此 null 不能直接表达“长期”。
- `pauseMonitor` 将可暂停状态写为 `8`；`restoreMonitor` 对未过期状态沿用原到期时间，对全量过期状态重新按账号周期设置到期时间。当前前端将这套状态显示为“停止/启动”，没有向用户区分暂停、配额阻断和终止。
- 工作区 `__main__.md` 已记录旧问题：规则重新激活或编辑后的抓取窗口容易偏离用户直觉，尤其是新增频道后可能扩大回溯窗口。v7.6.3 应把“编辑、另存、恢复、历史回溯”的时间语义一次写清，不能只补一个按钮。

### 2.5 收藏夹能力事实

前端已有收藏夹模块和可复用接口：

- `GET /ws/collection/simpleGroupList`：收藏夹简表；
- `GET /ws/collection/v2/groupDetail`：收藏夹详情；
- `GET /ws/collection/v2/listGroupChannel`：按 `groupId + platform` 分页读取频道；
- 现有收藏夹页面按平台分开读取频道，列表项能够提供频道 ID、平台和主页链接等字段。

但自动追踪表单没有调用这些接口；收藏夹频道也不必然带有当前规则所需的 Nox 短链。因此收藏夹导入必须在选择后做跨平台字段映射、去重、权限校验，以及“关键词或短链”可执行性校验。

### 2.6 “历史”能力事实

- `GET /ws/monitor/video/task/getMonitorHistory` 和 `getMonitorStarHistory` 是数据用量/监控网红历史查询，不是按发布时间回溯已发布内容。
- 当前自动追踪请求 VO 只有项目、规则名、规则 ID、频道和关键词等字段，没有 `includeHistorical`、发布日期起点、回溯任务 ID 或回溯状态。
- 用户已确认历史追踪定义为“向前补扫未来追踪之前的同规则命中内容”，不是独立的历史用量查询：全平台可选 3/7/30 天，不消耗独立配额，已有监控内容直接去重，不追加新监控。
- 技术上仍需要补齐发布日期窗口、回溯执行入口、幂等、内容唯一键去重和部分失败处理；这些是执行方式，不改变产品上与未来追踪一致的规则、平台、权限、通知和任务处理语义。

## 3. 建议的产品语义

### 3.1 规则来源与新增方式

新增规则统一采用三种来源：

1. **手动/Excel**：沿用现有输入；
2. **收藏夹**：选择收藏夹、平台和频道集合，导入后进入同一待确认列表；
3. **其他规则**：选择当前项目内可见规则，只把频道带入当前表单，不复制关键词或短链，不跨项目。

三种来源最终都必须经过同一套频道去重和表单校验；收藏夹和其他规则来源本身不携带关键词或短链，也不直接保存规则：

- 频道唯一键按 `platform + channelId`，兼容 URL/alias 去重；
- 关键词由当前表单继续维护、去重和 trim，统一服务端上限为 10；
- 同一频道在导入批次和当前表单中重复时只保留一条，并告知过滤数量；
- 关键词为空时，仍按当前规则保存校验提示频道缺少可用短链；
- 收藏夹权限变化、频道已删除或平台字段不完整时逐条返回失败原因，不因一条失败丢弃整批。

### 3.2 另存为新规则

- 编辑已有规则时提供“保存并更新”和“另存为新规则”两个明确动作。
- “另存为新规则”生成新的 `ruleId`，原规则的状态、创建时间、到期时间和历史任务不被修改；保存成功后追加询问是否立即生效，确认后才进入运行态，取消则保留未生效状态。
- 默认名称建议为“原规则名 - 副本”，若同名则按现有规则名唯一校验提示用户修改；不自动覆盖原规则。
- 具体采用 clone 接口、复用新增接口或其他实现方式交由研发决定；需求只要求生成新规则、保留原规则不变，并在保存成功后追加生效确认。

### 3.3 暂停/恢复

- 暂停只影响规则是否继续产生新监控内容，不删除已产生任务，不修改规则配置。
- 暂停期间停止追踪并暂停计费；恢复时重新计算新的生效起点和到期时间，不沿用暂停前剩余时间。
- UI 状态至少区分：运行中、已暂停、已过期、配额不足、已删除。若后端暂时继续复用状态 8，需要在返回字段中增加可解释的 `statusReason`，禁止把配额阻断显示成用户主动暂停。
- 项目归档/撤销归档不应默默恢复规则；恢复动作必须由用户或明确的批处理策略触发。

### 3.4 生效期

建议采用显式枚举，不用 null 猜测：

```text
durationMode = 7d | 30d | permanent
startsAt      = 服务端确认生效时间
expiresAt     = 7d/30d 的明确时间；permanent 为空
```

- 7 天、30 天为规则级选择，但本版本沿用 7 天计费方式；不能因为时长选择新增独立计费口径。
- `permanent` 表示持续运行，不代表无限制消耗。需要单独定义席位、数据抓取、任务数、通知和停止/删除规则；没有明确 entitlement 时不展示该选项。
- 旧数据迁移：把现有 `monitor_duration` 按当前有效窗口映射到 `7d/30d` 或 `legacy`，不能把所有 null 直接迁成 permanent；本版本不改变 7 天计费口径。

### 3.5 历史内容补扫

- 当前自动追踪的未来窗口保持不变：规则生效后只命中之后新增、且符合频道/关键词/短链条件的内容。
- 新增一个可选开关 `includeHistorical`；打开后必须选择 `3d | 7d | 30d`，表示从本次规则保存确认的 `startsAt` 向前查询对应天数的已发布内容。
- 历史补扫只在新建规则或另存为新规则的保存动作触发；编辑保存不能触发，也不能取消既有历史补扫设定。
- 当前用户只选择“追溯时长”，但内部模型应保留 `historicalStartAt` 与 `historicalEndAt`；当前默认 `historicalEndAt` 为保存时的当前时间，时长用于反推起点，便于后续开放自定义起止时间。
- 补扫范围覆盖规则支持的全部平台，使用与未来追踪相同的频道、关键词、短链和权限判断。
- 补扫不消耗独立配额，沿用未来追踪已有的监控配额、席位和权限约束；不能因为“历史”再建立一套独立计费口径。
- 已有监控内容按平台内容 ID（无法取得时再用规范化 URL）去重；命中已存在内容时跳过创建，不追加新的监控任务。
- 去重不丢失当前规则命中关系：同一条内容可以同时关联多个自动追踪规则，内容来源由单一 `ruleId/ruleName` 升级为 `sourceList[]` 多重来源。
- 产品上补扫和未来追踪属于同一条规则链路；用户感知为“立刻完成的异步任务”，执行、重试、失败和通知规则复用未来追踪，不另建一套历史任务语义。
- 默认关闭；用户未勾选时不发起历史查询，也不创建回溯任务。
- 本期不提供“全历史”、自定义日期范围或独立历史配额。

### 3.6 内容多重来源

- 同一内容只创建一个监控任务；多个规则命中时，在该任务下追加规则命中关系，不重复创建任务。
- 需求层只规定可观察行为：内容可以展示多个自动追踪规则来源，并能区分未来追踪命中和历史补扫命中；具体采用关系表、数组或其他存储方式由研发决定。
- 内容列表和详情不再假设只有一个自动追踪规则：单来源直接展示规则名，多来源展示“自动追踪 · N 个规则”，点击后查看来源列表。
- 来源筛选按关系命中：筛选某条规则时，能够找到所有关联该规则的内容；不因内容还有其他规则来源而被排除。
- 暂停、过期或删除某条规则时，不删除已经创建的监控内容和其他规则来源关系；只停止该规则后续产生的新命中。
- 同一内容被多个规则同时命中时，系统通知和新增统计按监控任务去重，规则明细可以展开查看多个来源，避免一条内容重复计数。

## 4. 推荐落地拆分

### Phase A：先收口服务端契约（进入 Spec 前置条件）

1. 明确规则状态模型：暂停、过期、配额阻断、终止是否拆成独立状态/原因；
2. 增加 `durationMode / startsAt / expiresAt`，保留旧字段兼容并补迁移策略；
3. 统一关键词上限和收藏夹频道字段映射；
4. 决定 clone 是复用新增接口还是新增原子接口；需求不规定具体实现，只要求生成新规则、原规则不变、保存后追加生效确认；
5. 落实历史补扫的起止时间、异步执行状态和内容唯一键；产品口径已确认：3/7/30 天、全平台、无独立配额、已有内容去重、仅新建/另存保存触发；
6. 按产品要求实现多来源可观察行为；关系表、数组或其他存储方式由研发决定。

### Phase B：本版本主路径

- 在 `AutoTrackForm` 中加入来源选择器和导入预览；
- 增加“另存为新规则”，保留原规则不变；
- 另存为保存成功后追加是否立即生效的确认；
- 将现有停止/启动文案调整为暂停/恢复，并补充状态原因；
- 将生效期改为 7 天、30 天、长期的显式选择，服务端返回最终 `startsAt/expiresAt`；
- 增加历史补扫开关和 3/7/30 天选择；只在新建/另存保存触发，编辑不能触发或取消；补扫作为与未来追踪一致的即时异步任务，已有监控内容不重复创建；
- 将关键词上限前后端统一为 10；
- 继续沿用当前规则列表和项目权限，不新建重型规则管理中心。

### Phase C：历史补扫执行验证

- 先以离线/测试环境验证全平台、3/7/30 天窗口和一条规则；
- 重点验证同规则命中一致性、已有内容去重、补扫与未来追踪并发时的幂等、与未来追踪一致的重试/失败/通知；
- 若执行链路尚未关闭，入口必须显示补扫未完成或部分完成，不能把规则保存成功冒充为历史内容已经全部补齐。

## 5. Input 级验收边界

进入下游 Spec 前已确认：

- 收藏夹和其他规则只作为频道选择来源，不携带关键词/短链，不自动保存；其他规则不跨项目；
- 另存为保存成功后追加是否立即生效的确认；
- 暂停期间停止追踪并暂停计费，恢复时重新计算生效起点和到期时间；
- 30 天和长期暂沿用 7 天计费方式；
- 历史补扫只在新建/另存保存触发，窗口为全平台 3/7/30 天，内部保留起止时间，当前终点为保存时当前时间；
- 历史补扫复用未来追踪的异步、重试、失败和通知规则，不新增独立配额；
- 多来源允许同一内容关联多个规则，存储方案由研发决定；
- 关键词上限统一为 10。

进入 Spec 后仍需由研发在技术方案中明确：历史查询接口和任务复用方式、补扫与未来追踪并发幂等、来源关系的具体存储、来源列表排序，以及暂停/恢复对现有席位账本的实现映射。

## 6. 风险与暂不承诺

- **服务端归属风险**：当前能力在旧 `KOLServer`，新服务端没有对应端点；迁移前不能只在 `kol_server_v2` 加接口后宣称线上生效。
- **时间窗风险**：历史规则的恢复、编辑、新增频道会改变用户对抓取起点的理解；必须以 `startsAt/expiresAt` 和“本次操作是否回溯”显式表达。
- **长期规则风险**：旧 SQL 和状态归并把 null 解释为 legacy 7 天；直接复用 null 会造成永久规则误过期或席位统计错误。
- **收藏夹数据风险**：收藏夹是资源沉淀区，不等于自动追踪可执行输入；频道、短链、平台和权限需要重新校验。
- **配额风险**：历史补扫不新增独立配额，但仍会触发已有监控任务和席位约束；新增来源、新时长和补扫必须纳入同一事务/幂等链路。
- **多来源风险**：现有内容来源展示和筛选可能按单一规则字段实现；若只覆盖文案，不补规则-内容关系，历史命中会被去重后丢失来源解释。
- **浏览器证据缺口**：本轮已完成前端和两个服务端仓库的静态核对，并运行 `kol-next/scripts/video-monitor-auto-track-rule.test.js`（7 项通过）；Codex 内置 Browser 当前因 `unsupported Codex auth method: apikey` 无法建立可用浏览器会话，因此未完成登录态页面实测。本文把浏览器线上表现标为待确认，不把静态代码等同于生产运行证据。

## 7. 代码证据索引

### 前端 `../kol-next`

- `components/videoMonitor/monitor/addAndAutoTrack/index.vue`：抽屉、表单/列表挂载、编辑回填、保存后刷新。
- `components/videoMonitor/monitor/addAndAutoTrack/autoTrackForm.vue:332-443`：手动/批量频道合并、去重、`ruleId` 更新参数、`monitorDays` 请求字段。
- `components/videoMonitor/monitor/addAndAutoTrack/autoTrackForm.vue:474-589`：非运行规则编辑后的恢复确认、更新/新增分支。
- `components/videoMonitor/monitor/addAndAutoTrack/autoTrackList.vue:611-758`：状态映射、暂停/恢复、编辑和删除。
- `components/videoMonitor/monitor/addAndAutoTrack/components/autoTrackUpload.vue:236-320`：Excel 上传校验、解析和 `passList` 合并。
- `api/videoMonitor/list.js:71-86,1245-1321`：自动追踪端点和前端请求封装。
- `api/resource/list.js:4-22,430-475,554-578`：收藏夹简表、详情、频道列表和相关请求封装。
- `scripts/video-monitor-auto-track-rule.test.js`：规则归一化、追加频道和路由构造的现有脚本测试。

### 服务端 `../KOLServer`

- `WebService/src/main/java/com/nox/kol/ws/monitor/MonitorIndependentModularityController.java:696-828`：新增、更新、恢复、规则 list/detail/delete/pause 路由。
- `ServiceInternal/src/main/java/com/nox/kol/service/monitor/video/VideoMonitorAutoTrackService.java:147-199`：新增/更新规则入口。
- `.../VideoMonitorAutoTrackService.java:204-361,405-493`：频道/短链/关键词同步与编辑后的时间窗决策。
- `.../VideoMonitorAutoTrackService.java:620-771`：参数校验、关键词上限、账号默认追踪天数和到期计算。
- `.../VideoMonitorAutoTrackService.java:1260-1341`：暂停后恢复、过期恢复和配额检查。
- `.../VideoMonitorAutoTrackService.java:1414-1614`：规则列表、简表、详情及动态状态计算。
- `ServiceInternal/src/main/java/com/nox/kol/service/monitor/video/VideoMonitorCommonHelper.java:803-870`：规则状态归并、添加/到期时间和监控天数展示。
- `ServiceInternal/src/main/resources/com/nox/kol/mapper/VideoMonitorProjectRulesMapper.xml:47-129`：规则时间字段、动态周期和运行中规则统计。
- `ServiceInternal/src/main/resources/com/nox/kol/mapper/VideoMonitorProjectStarsMapper.xml:337-385`：暂停、过期恢复、恢复和历史用量查询。

### 当前仓库状态

- `kol-next` 当前工作分支：`codex/752-brand-reputation-radar`；自动追踪相关文件最近一次合并提交为 `4aa02ea98`（2026-09-08）。
- `KOLServer` 当前分支：`master`；最近提交为 `706dc8ea0e`（2026-08-21）。
- `kol_server_v2` 当前分支：`master`；本轮未发现自动追踪规则端点。