feat: improve generation analytics and maintenance

docs/planning/demo-validation-log.md

@@ -16,6 +16,8 @@
 - `./scripts/demo_smoke.sh` 已覆盖音频缓存状态查询。
 - Week 4 Demo 包装已完成：新增架构说明、Demo 包装文档、Week 4 sprint review，用户端和管理端绘本阅读器支持阅读位置恢复。
 - Week 4 最终回归通过：后端全量测试 85 passed，ruff 通过，用户端/管理端构建通过，`docker compose up -d --build` 和 `./scripts/demo_smoke.sh` 通过。
+- 继续优化后再次验证：Provider analytics 已支持时间窗口与能力筛选、失败原因摘要；音频缓存已加入 TTL 配置和后台 prune 任务。
+- 新一轮优化验证通过：新增 `GET /api/generations/ops-summary`，故事库已展示最近失败与卡住任务摘要；生成任务已支持 stale 自动收敛和重复资产任务保护。
 - 后端新增 `partial_ready`、`text_status` 与迁移 `0012_story_text_status` 后，`backend/.venv/bin/python -m pytest backend/tests -q` 通过，82 个测试通过。
 - `backend/.venv/bin/python -m ruff check backend/app backend/tests backend/alembic/versions/0012_add_story_text_status_and_partial_ready.py` 通过。
 - 用户端与管理端 `npm run build` 均通过。

docs/planning/week-2-to-4-execution-backlog.md

@@ -66,6 +66,11 @@ Week 2 已完成演示闭环、统一生成工作流、generation job/event、
 | W4-03 | Demo | 求职版 Demo 包装 | `docs/planning/demo-package.md` | P0 | Done |
 | W4-04 | QA | 全量回归与验证记录 | pytest、ruff、前端 build、Docker smoke | P0 | Done |
 | W4-05 | Product | 项目复盘与下一阶段路线 | `docs/planning/week-4-sprint-review.md` | P1 | Done |
+| W4-06 | Ops | Provider analytics 支持时间窗口与失败原因 | `days` / `capability` 筛选 + failure reason summary | P1 | Done |
+| W4-07 | Ops | 音频缓存后台清理 | TTL 配置 + Celery beat prune task | P1 | Done |
+| W4-08 | Ops | 任务运行概览与失败摘要 | `GET /api/generations/ops-summary` + 最近失败列表 | P1 | Done |
+| W4-09 | Workflow | 卡住任务自动收敛 | `GENERATION_JOB_STALE_MINUTES` + Celery beat stale job maintenance | P1 | Done |
+| W4-10 | Workflow | 防止重复资产任务 | 运行中故事拒绝重复封面/音频/资产重试请求 | P1 | Done |
 
 ---
 

docs/planning/week-4-sprint-review.md

@@ -34,6 +34,7 @@ DreamWeaver 已经具备求职演示所需的完整闭环：
 - generation job/event
 - Provider failover 和聚合指标
 - 跨故事 Provider analytics
+- 任务运行概览、最近失败摘要与卡住任务收敛
 - 前端生成轨迹和自动轮询形态
 
 ---
@@ -42,7 +43,7 @@ DreamWeaver 已经具备求职演示所需的完整闭环：
 
 最近一轮验证包括：
 
-- 后端全量测试：85 passed
+- 后端全量测试：91 passed
 - 后端 ruff：通过
 - 用户端生产构建：通过
 - 管理端生产构建：通过
@@ -56,10 +57,9 @@ DreamWeaver 已经具备求职演示所需的完整闭环：
 | Priority | Task | Why |
 | --- | --- | --- |
 | P0 | 将同步生成迁移到 Celery worker | 支持真实长任务、断点恢复和后台进度 |
-| P0 | Provider analytics 加入时间窗口和失败原因 | 让运营分析可用于成本与稳定性决策 |
-| P1 | 音频缓存过期策略与后台清理 | 控制磁盘占用和缓存生命周期 |
 | P1 | 生成任务取消与重试队列 | 防止重复任务和用户误触造成浪费 |
-| P1 | 监控告警与结构化 dashboard | 上线前需要可观测性闭环 |
+| P1 | 跨用户 / 跨环境 Provider dashboard | 当前已支持单用户摘要，后续要支持运营视角 |
+| P1 | 监控告警与结构化 dashboard | 目前已有故事库级概览，后续要接入更完整观测体系 |
 | P2 | 更细粒度叙事风格与音色策略 | 扩展体验，但不影响当前求职版主线 |
 
 ---

docs/product/unified-generation-workflow-prd.md

@@ -64,6 +64,10 @@ DreamWeaver 当前同时支持普通故事生成、完整故事生成和绘本
 - Provider 调用已可按故事聚合为成功率、平均耗时、预估成本和 adapter 明细
 - generation job 响应已提供 `progress_percent`、`progress_label` 和 `is_terminal`，前端可直接用于进度条和轮询
 - 已新增跨故事 Provider 运营摘要 `GET /api/generations/provider-analytics`，故事库可展示总调用、成功率、平均耗时、预估成本和任务/故事覆盖数
+- 跨故事 Provider 运营摘要已支持按时间窗口和 capability 筛选，并聚合失败原因
+- 已新增任务运行概览 `GET /api/generations/ops-summary`，故事库可展示最近失败、运行中任务和超时待收敛任务
+- 重复资产任务已加入保护：同一故事存在运行中 job 时，不再重复触发封面、音频或统一资产重试
+- Celery beat 已支持定时收敛卡住的 generation job，避免任务长期停在 running
 - 用户端与管理端生成轨迹组件会在任务未终止时自动轮询，为后续后台 worker 进度流保留前端形态
 - `POST /api/generations` 响应已返回 `generation_job_id`，smoke 脚本会验证 job 查询与 story job history
 - 用户端与管理端的故事详情页、绘本阅读页已接入生成轨迹，展示生成/重试任务、关键事件、Provider 调用结果和聚合指标
@@ -74,7 +78,7 @@ DreamWeaver 当前同时支持普通故事生成、完整故事生成和绘本
 
 - 普通故事、完整生成、绘本生成已有统一外部入口，内部 workflow 仍可继续减少兼容层分支
 - 统一资产重试入口已覆盖普通故事封面、绘本缺失插图和故事音频，后续可继续扩展更细的资产级审计
-- 后台异步 worker 执行、断点续跑、跨时间窗口筛选和更完整的 Provider 运营分析仍属于后续生产化增强
+- 后台异步 worker 执行、断点续跑、跨用户/跨环境 Provider 分析，以及真正的取消/重试队列仍属于后续生产化增强
 
 ### What This Means
 

docs/technical/generation-job-state.md

@@ -19,9 +19,10 @@
 - `GET /api/generations/jobs/{job_id}`：查询单次生成/补全任务及其事件流。
 - `GET /api/generations/{story_id}/jobs`：查询某个故事或绘本的生成与重试历史。
 - `GET /api/generations/{story_id}/provider-stats`：按故事聚合 Provider 调用成功率、平均耗时、预估成本和 adapter 明细。
-- `GET /api/generations/provider-analytics`：按当前用户聚合跨故事 Provider 调用、任务数、故事数、成功率、平均耗时和预估成本。
+- `GET /api/generations/provider-analytics`：按当前用户聚合跨故事 Provider 调用、任务数、故事数、成功率、平均耗时和预估成本，并支持 `days` / `capability` 筛选。
+- `GET /api/generations/ops-summary`：按当前用户聚合最近任务健康度，包括运行中数量、超时阈值、卡住任务数和最近失败摘要。
 
-job 响应会返回 `progress_percent`、`progress_label` 和 `is_terminal`，用户端与管理端已经消费这些查询入口，在故事详情页和绘本阅读页展示最近任务、任务历史、事件时间线、进度条和 Provider 聚合指标；当任务未终止时，前端会自动轮询，为后台 worker 进度流预留体验形态。
+job 响应会返回 `progress_percent`、`progress_label` 和 `is_terminal`，用户端与管理端已经消费这些查询入口，在故事详情页和绘本阅读页展示最近任务、任务历史、事件时间线、进度条和 Provider 聚合指标；当任务未终止时，前端会自动轮询，为后台 worker 进度流预留体验形态。当前 analytics 还会聚合失败原因，便于快速解释“最近为什么失败”；ops summary 会额外把“哪些任务卡住了、最近哪些任务失败了”压缩成故事库首页能直接看的摘要。
 
 ## 现有状态模型
 
@@ -37,6 +38,12 @@ job 响应会返回 `progress_percent`、`progress_label` 和 `is_terminal`，
 
 这些字段足够支撑前端展示、smoke 检查、失败降级、资产重试和生成轨迹解释。
 
+## 当前维护策略
+
+- 音频缓存由 `STORY_AUDIO_CACHE_TTL_DAYS` 控制过期时间，Celery beat 会每日清理。
+- 生成任务由 `GENERATION_JOB_STALE_MINUTES` 控制卡住阈值，Celery beat 会每 30 分钟扫描一次，将超时运行中的任务标记为 `generation_stale_failed`。
+- 当某个故事已经有运行中的 job 时，封面补全、音频生成和统一资产重试会直接拒绝重复请求，避免用户连点造成重复成本。
+
 ## 什么时候需要落库 job
 
 如果后续进入真实生产化，需要扩展当前 job/event 模型：
@@ -52,7 +59,7 @@ job 响应会返回 `progress_percent`、`progress_label` 和 `is_terminal`，
 当前已有两层记录，未来可以继续扩展字段和事件颗粒度：
 
 - 将同步生成请求迁移到真正异步 worker 后，继续复用现有 job 查询和前端轮询进度条。
-- 将当前跨故事 provider 指标扩展为跨时间窗口、跨用户和失败原因维度的运营分析。
+- 将当前跨故事 provider 指标扩展为跨用户、跨环境和更细颗粒度的失败原因维度分析。
 
 ## 面试表达