# Campaign 架构深化阶段总结

**版本**：v1.0
**归档日期**：2026-08-11
**阶段状态**：已完成并纳入项目 v1.0.0
**代码基线**：`10a089e` → `1782b24`
**需求来源**：Gitea Issue #2、`.scratch/refactor-plan-architecture-deepening-v2.md`

## 一、阶段目标

本阶段在不改变 HTTP 契约、业务口径、管理后台信息架构和部署拓扑的前提下，继续深化 Campaign 相关模块：统一智能分析与周期对比的耐久作业编排，建立稳定读模型，收窄 Campaign 运行时接口，并验证是否值得抽取跨领域条件写入模块。

## 二、交付结果

1. **耐久智能作业**：新增统一 owner，集中管理 queued 持久化、条件认领、任务句柄、成功/失败结算、启动恢复和关闭。重复入队不再把 `generating` 回退为 `queued`；恢复最多 3 次，避免无限模型调用。
2. **Campaign 读模型**：列表、详情、报告、时间线、智能分析、周期对比和 Markdown 导出统一消费稳定 projection；列表 child Run 改为批量读取。
3. **CampaignRuntime**：生产调用面收敛为 `start`、`cancel`、`recover`、`shutdown`，时钟、child Run 执行器、tick、reconcile 与 TaskRegistry 留在实现内部。
4. **前端请求编排**：`useCampaignReport` 统一列表、报告快照、展开行时间线、状态感知轮询、silent refresh、生成操作和迟到响应过滤；页面回归渲染与交互职责。
5. **删除测试**：拒绝通用条件写入模块。Campaign 与 Intelligent Evaluation 只有 SQL 外形相似，状态、时间、事务副作用和冲突语义不同；结论记录于 ADR-0006。

## 三、质量与发布验收

- 后端：`744 passed`。
- 前端：`15 passed`；`tsc --noEmit` 与生产构建通过。
- 迁移：Alembic upgrade/downgrade 往返通过，生产数据库位于 `d4e7f9a1b2c3 (head)`。
- 代码质量：本阶段相关 Ruff 检查及 `git diff --check` 通过。
- 阶段验收镜像：`agenteval:0.8.0-1782b24`；版本漂移随后在项目 `v1.0.0` 发布中统一修正。
- 正式地址：<https://agenteval.solahqb22.cn/>；前端、健康接口和 OpenClaw 均验证成功。
- 发布前备份：`/var/backups/agenteval/agenteval-0.8.0-1782b24-20260811T051927Z.tgz`。

## 四、关键决策

- 数据库是 Campaign 与智能作业的耐久权威；TaskRegistry 只保存当前进程句柄。
- `queued` 可以有限恢复；遗留 `generating` 失败结算，不自动重放可能已产生外部副作用或费用的工作。
- Campaign 读模型是跨 Repository 组合的唯一稳定 seam，Router 不拼装领域快照。
- 保持单进程 FastAPI + SQLite 假设；引入多 worker 前必须重新评审认领、恢复和 SQLite 并发边界。

## 五、后续事项

- 阶段结束提交为 `1782b24`；后续发布提交统一项目版本并重新部署双线环境。
- `.scratch/` 中原始计划和辅助脚本继续保留，未纳入版本控制。
- 全仓库 Ruff 仍有 6 个历史迁移格式问题；与本阶段逻辑无关，后续可单独清理。
- 下一轮架构工作应以真实第三个 adapter 或新部署约束为触发条件，避免仅因代码形状相似继续抽象。