fix: 修复 AI 分析与内容归因契约

ANALYSIS_ATTRIBUTION_CONTRACT_TASK.md

@@ -0,0 +1,55 @@
+# AI 分析与内容归因契约修复任务
+
+## 背景
+
+第二次工程复检确认三个数据正确性问题：长直播结果缺少必需质量字段，显式反馈会错误绑定当前 active Run，官方导出缺少时长时 Prompt 对比无法计算平均观看比例。
+
+## 目标
+
+- 让长直播完整与不完整结果都产生结构完整、可验证的质量元数据。
+- 让反馈只绑定候选片段的真实来源 Run；来源不可信时保留反馈但不进行 Prompt 归因。
+- 让 Prompt 对比复用内容诊断已经采用的有效时长回退顺序。
+
+## 允许修改范围
+
+- `app/services/ai/long_live_talk_analyzer.py`
+- `app/services/clip_feedback_service.py`
+- `app/services/content_review_service.py`
+- 上述行为对应的测试文件
+- `DEVELOPMENT_LOG.md`、`NEXT_STEPS.md` 与本任务文件
+
+## 禁止修改范围
+
+- 数据库结构和活动 SQLite。
+- Provider 调用、发布执行、Chrome Worker 和运行中服务。
+- 前端交互、迁移框架和本阶段无关的代码味道。
+
+## 已确定实现要求
+
+1. `quality_degraded` 必须由长直播分析器显式写入，不能放宽共享校验器的缺失字段门禁。
+2. 显式反馈不得查询或猜测当前 active Run；只接受候选 `source_analysis_run_id` 且必须属于同一任务。
+3. 来源缺失、不存在或属于其他任务时，`analysis_run_id` 写为 `NULL`，反馈本身继续保存。
+4. 有效时长顺序固定为导入时长、候选时长、输出片段 `source_duration_ms`。
+
+## 验收标准
+
+- 完整长直播元数据通过共享切片校验，不完整结果仍被门禁阻止。
+- 旧候选在新 active Run 存在时仍归因到旧来源 Run。
+- 不可信来源不会回退到 active Run，也不会触发外键错误。
+- 官方导出时长为空时，Prompt 对比能用候选或输出片段时长计算观看比例。
+- 定向测试、全量测试、Ruff、Compileall 和 `git diff --check` 通过。
+
+## 测试命令
+
+```powershell
+pytest -q tests/test_long_live_selection.py tests/test_partial_ai_analysis.py tests/test_content_review_foundation.py tests/test_content_review.py
+ruff check app tests scripts
+python -m compileall -q app tests scripts
+pytest -q
+git diff --check
+```
+
+## 返回格式
+
+- 三个契约的修复说明与回归证据。
+- 修改文件、测试结果、分支、提交 SHA、远端 SHA 和 PR 状态。

CONTENT_REVIEW_FEEDBACK_LOOP_TASK.md

@@ -0,0 +1,60 @@
+# 内容复盘反馈闭环实施任务
+
+## 背景
+
+当前内容复盘已经具备官方作品报表导入、作品归因和 Prompt 版本证据链，但精确同步时间、匹配语义、折叠体验和可执行改进闭环仍不完整；现有“周期”还错误地按导入批次数计算。
+
+## 目标
+
+- 明确展示最近一次官方作品导出的北京时间和匹配统计。
+- 美化文件选择入口，并让趋势明细、作品归因、Prompt 证据默认折叠且记忆状态。
+- 修正 2 秒跳出率的好坏方向和匹配状态文案。
+- 新增透明、无 AI 调用的作品诊断与人工实验闭环。
+- 在投稿执行前允许给发布任务关联一个实验，执行开始后冻结关联。
+
+## 允许修改范围
+
+- 内容复盘服务、路由、模型、模板、JavaScript 和 CSS。
+- 发送中心中与“关联内容实验”直接相关的服务、路由、模板和 JavaScript。
+- SQLite 向后兼容迁移、数据库文档、开发日志、后续步骤和 UI 参考。
+- 内容复盘、发送中心、迁移及浏览器测试。
+
+## 禁止修改范围
+
+- 不修改 Provider、登录、Token、Cookie、`.env` 或代理配置。
+- 不触发真实抖音导出、AI 分析、排期、投稿或远端数据库操作。
+- 不自动修改 Prompt、候选片段、发布状态或现有历史快照。
+- 不重构前端框架，不改无关页面，不覆盖用户数据。
+
+## 已确定实现要求
+
+- 官方导出周只按成功的 `douyin_item_export` 最新采集时间所在自然周去重。
+- 诊断只使用最新、已准确匹配且指标完整的作品；按体裁、片长区间和发布年龄建立对照，使用中位数与四分位数。
+- 每条建议必须带证据、单一动作、主指标、护栏指标和数据充分性；缺失作品级封面点击率时不得生成封面建议。
+- 实验基线在创建时冻结；发布任务同一时间只能属于一个实验；进入 `PUBLISHING`、`PUBLISHED`、`FAILED` 或人工复核等执行后状态后不得关联或解除。
+- 10 条实验作品仅显示早期趋势；对照与实验各至少 20 条且覆盖 3 个官方导出周后才允许记录最终结论。
+- 系统只记录用户的保留、回退或结论不足决定，不自动实施改动。
+
+## 验收标准
+
+- 页面显示独立官方导出精确时间、批次和匹配统计。
+- 自定义文件按钮可访问、显示文件名、未选文件时不可预览。
+- 三个明细区默认折叠并通过浏览器本地存储记忆开合状态。
+- 匹配文案和 2 秒跳出率颜色正确。
+- 可创建实验、投稿前关联/解除、执行后冻结，并基于后续官方快照自动汇总进度。
+- Prompt 证据按账号隔离并显示真实周数与缺口，不把历史未版本化作品当成 Prompt 结论。
+- 迁移完整性、外键检查、定向测试、完整测试、静态检查和浏览器宽度回归通过。
+
+## 测试命令
+
+- `.\.venv\Scripts\python.exe -m pytest tests\test_content_review.py tests\test_content_review_browser.py -q`
+- `.\.venv\Scripts\python.exe -m pytest tests -q`
+- `.\.venv\Scripts\python.exe -m ruff check app tests`
+- `.\.venv\Scripts\python.exe -m compileall app`
+- `node --check app\static\js\content-review.js`
+- `node --check app\static\js\publish-center.js`
+- `git diff --check`
+
+## 返回格式
+
+报告修改摘要、文件范围、数据库迁移、测试证据、Git 分支/提交/远端 SHA、PR 与 CI 状态；明确说明未触发真实导出、AI 或投稿。

DEVELOPMENT_LOG.md

@@ -1,5 +1,16 @@
 # Development Log
 
+## 2026-08-29 内容复盘“数据 → 动作 → 验证”闭环
+
+- 自动导出卡改为显示最近一次官方作品导出的北京时间、批次作品数及已匹配/待确认/未匹配统计；账号趋势表不再参与作品导出时间和周数口径，同一自然周多次导出只计一个官方导出周。
+- 文件上传复用项目自定义按钮，选择后显示文件名，未选择时禁用预览；账号每日明细、作品归因和 Prompt 高级证据默认折叠，并通过当前浏览器 `localStorage` 记忆状态。
+- 匹配状态统一为“已匹配·唯一证据 / 已匹配·人工确认 / 待人工确认·多个候选 / 未匹配·没有候选”；修正 2 秒跳出率好坏方向，上升为红色、下降为绿色。
+- 主栏目改为“本周改进建议”：只对准确匹配且指标完整的官方作品，按同体裁、片长和发布年龄构造中位数与四分位数对照，规则化识别开头留存、中段节奏、分发窗口和正样本；作品级封面指标为空时不生成封面建议，全程不调用 AI。
+- 新增内容实验与作品关联：创建时冻结批次基线、唯一改动、主指标和护栏；发送中心可在投稿前选择实验，一个作品同一时刻只有一个实验归属，执行领取或已有执行证据后冻结。切换归属由单一事务完成，避免先删后加的中间状态。
+- 实验 10 条后才显示早期趋势；只有实验与对照各至少 20 条、覆盖 3 个不同官方导出周时，才允许人工记录“保留 / 回退 / 结论不足”。系统只记录结论，不改 Prompt、切片、文案、排期或投稿。
+- Prompt 证据按账号及官方作品导出隔离，显示真实导出周数和距离 30 条准确作品的缺口；历史未绑定 Prompt 的作品继续只作观察基线。
+- 新增账本迁移 `20260829_02_content_feedback_loop`，只追加 `content_improvement_experiments` 与 `content_improvement_experiment_items`，保留全部现有快照、发布记录和排期。当前开发验收使用 pytest 临时库，未迁移活动库、未重启服务，也未触发真实导出、AI 或投稿。
+
 ## 2026-08-29 抖音官方作品报表全量同步
 
 - 内容复盘不再监听创作者中心私有作品接口，也不再逐作品请求 `metrics_trend`；Windows Chrome Worker 改为打开内容管理页、只点击一次“导出数据”，使用浏览器下载事件读取官方 `作品列表导出.xlsx`。
@@ -1423,3 +1434,10 @@
 - 保留 `master` 分支 push 的既有 CI，同时取消 Pull Request 目标分支限制，让以功能分支为目标的堆叠 PR 也运行 Linux 测试、Windows 主机冒烟和 Docker 镜像冒烟。
 - 不修改 CI Job 内容、权限、Secrets、依赖版本或业务代码；继续使用权限更低的 `pull_request` 事件，不切换到 `pull_request_target`。
 - 本次只恢复自动验收链路。现有堆叠 PR 的依赖、合并顺序与目标分支将在 CI 修复合并后逐一核对，不自动改写历史或合并 PR。
+
+## 2026-08-30 AI 分析与内容归因契约修复
+
+- 长直播分析结果现在始终显式写入 `quality_degraded=false`；完整结果可通过共享质量校验，不完整窗口仍由 `analysis_incomplete` 和覆盖率门禁阻止切片，没有放宽损坏元数据的 fail-closed 规则。
+- 显式片段反馈改为只绑定候选的 `source_analysis_run_id`，并验证 Run 属于同一任务；来源缺失、不存在或跨任务时保留反馈但不归因，绝不回退到当前 active Run。
+- Prompt 对比统一使用“官方导入时长 → 候选时长 → 输出片段源时长”的有效时长口径，官方报表时长为空时仍能计算平均观看比例。
+- 定向回归由修复前 `55 passed` 增加到 `62 passed`，全量回归 `861 passed`；Ruff、Compileall、5 个 JavaScript 语法检查、20 个 PowerShell 解析检查、三套合并 Compose 配置、`pip check` 和 `git diff --check` 均通过。测试只使用临时 SQLite 和本地 mock，未调用真实 Provider、Chrome 或发布平台，也未修改活动数据库。

NEXT_STEPS.md

@@ -1,5 +1,14 @@
 # Next Steps
 
+## 2026-08-29 内容复盘闭环使用与上线检查
+
+1. 本分支合并并受控重启 Web 前，先确认没有 `PUBLISHING` 任务并备份活动 SQLite；启动时会应用 `20260829_02_content_feedback_loop`。重启后检查 `/api/system/readiness?deep=1` 和发送中心，确认迁移账本、实验表及 Worker 状态均正常。
+2. 打开“内容复盘”，自动导出卡应显示“上次成功导出：北京时间 YYYY-MM-DD HH:mm”以及本批匹配统计；账号每日明细和作品归因默认收起。折叠一次后刷新，状态应保持。
+3. “本周改进建议”只使用准确匹配且指标完整的官方作品。若显示“证据不足”，先处理未匹配作品或等待下一次官方导出，不要为了得到建议手工补造指标。
+4. 点击“采纳为下轮实验”只会建立实验卡。前往发送中心，在确实采用该唯一改动的作品上选择实验并保存；已经开始投稿的作品不能补标、改标或解除。
+5. 少于 10 条只显示收集进度；10 条起仅显示早期趋势。实验与对照各 20 条并覆盖 3 个不同官方导出周后，页面才开放“保留改动 / 回退 / 结论不足”，仍由用户人工决定。
+6. Prompt 高级证据区只评估当前账号、已绑定真实 Prompt 版本的官方作品；历史未绑定作品不能补猜版本。页面和接口不会自动修改 Prompt、重新切片、调整排期或投稿。
+
 ## 2026-08-29 官方作品报表同步使用说明
 
 1. 在“内容复盘”选择正确的抖音账号后，点击“自动导出并同步全部作品”；系统只会打开创作者中心内容管理页并点击一次“导出数据”，不会投稿、改排期或改 Prompt。
@@ -1164,3 +1173,11 @@
 2. 由用户明确确认后再 Squash 合并该 PR；Codex 不自动合并。
 3. 合并后，将最新 `master` 通过普通 merge 合入仍需继续的堆叠分支，不 rebase、不强推。
 4. 逐个确认目标为功能分支的 PR 已出现三项 CI 检查，再继续业务正确性修复。
+
+## 2026-08-30 AI 分析与内容归因契约验收
+
+1. 先确认阶段 1 PR 的全量测试、Windows 主机冒烟和 Docker 镜像冒烟全部通过；未经用户确认不合并。
+2. 后续人工发起新的长直播分析时，完整结果应能进入审核与切片；若存在失败窗口，仍应明确显示分析不完整并阻止切片。该验证会消耗 Provider 额度，不在自动测试中触发。
+3. 对历史候选提交显式反馈时，反馈应归属于候选生成时的 Prompt Run；来源无法证明的旧候选应显示为未归因，不得算到当前 Prompt。
+4. 导入抖音官方作品报表后，即使报表没有视频时长，已匹配作品的 Prompt 对比仍应按候选或输出片段时长显示平均观看比例。
+5. 本阶段不需要重启服务、修改活动数据库或执行真实投稿；完成自动验收后继续处理数据库迁移原子性。