# Scheduler 执行清单 V1（前后端一体交付）

> 目标：交付“可见、可触发、可追踪”的调度中心，避免仅后端不可见改动。  
> 原则：每步必须包含 Backend + Frontend + 可见验收。

---

## 0. 执行规则（强制）

- [ ] 每步包含 `Backend任务` + `Frontend任务` + `可见验收`。
- [ ] 每步完成即改 `[x]` 并补验收证据。
- [ ] 无页面可见结果，不进入下一步。
- [ ] 失败需记录回滚点与阻塞原因。

---

## 1. 范围与阶段

- [x] S0 稳定性前置（401 熔断、防轮询风暴）
- [x] S1 调度基础能力（Job Registry + JobRun 持久化 + 手动触发）
- [x] S2 调度中心页面（任务列表、触发、运行记录）
- [x] S3 认知链路接入（对齐评分任务接入调度）
- [x] S4 联调验收（失败重试、权限、可视化证据）

---

## 2. 分步清单

### [x] S1 调度基础能力

**Backend任务**
- 新增 `scheduler_center` 服务：注册任务、执行任务、记录 `job_runs`。
- 新增 `/scheduler` API：
  - `GET /scheduler/jobs`
  - `GET /scheduler/runs`
  - `POST /scheduler/jobs/{job_name}/trigger`

**Frontend任务**
- 新增 `scheduler` API client，支持查询与触发。

**可见验收**
- 调用 `GET /scheduler/jobs` 可见可触发任务列表。
- 触发任务后 `GET /scheduler/runs` 出现新纪录（running/success/failed）。

**验收证据**
- API 已新增：`GET /scheduler/jobs`、`GET /scheduler/runs`、`POST /scheduler/jobs/{job_name}/trigger`
- 后端文件：`backend/app/services/scheduler_center.py`、`backend/app/api/scheduler.py`
- 路由接入：`backend/app/api/__init__.py`、`backend/app/main.py`

---

### [x] S2 调度中心页面

**Backend任务**
- 补充运行记录字段（耗时、错误信息、payload 摘要）并排序输出。

**Frontend任务**
- 新增 `SchedulerCenterPage`：
  - 任务列表
  - 手动触发按钮
  - 最近运行记录
  - 错误可读展示
- 路由接入，并在项目看板增加入口按钮。

**可见验收**
- 页面可手动触发任务并实时看到运行结果。

**验收证据**
- 页面已新增：`frontend/src/pages/SchedulerCenterPage.tsx`
- 前端 API 已新增：`frontend/src/api/scheduler.ts`
- 路由已接入：`/scheduler-center`（`frontend/src/router/index.tsx`）
- 项目看板入口已接入：`frontend/src/pages/ProjectBoardPage.tsx`
- 构建通过：`cd frontend && npm run build`

---

### [x] S3 认知链路接入（O4-4 首版）

**Backend任务**
- 将“项目认知评分重算”封装为调度任务 `alignment_rescore_project`。
- `ai_steward` 对应入口优先通过调度执行并写 `job_runs`。

**Frontend任务**
- 调度中心支持传入 `project_id` 触发重算任务。

**可见验收**
- 触发重算后，`job_runs` 成功记录可见；评分接口数据可更新。

**验收证据**
- 调度任务真接线：`backend/app/services/scheduler_center.py` -> `alignment_rescore_project`
- 评分内核抽离：`backend/app/services/alignment_orchestrator.py`
- `ai_steward` 入口改为优先通过调度执行并落 `job_runs`：`backend/app/api/ai_steward.py`

---

### [x] S4 联调与收尾

**Backend任务**
- 权限控制：仅 BOSS/ADMIN 可触发关键任务。
- 失败重试策略：同名任务支持手动重跑。

**Frontend任务**
- 失败任务标红 + 一键重试。

**可见验收**
- 失败任务可重试并形成新的运行记录链。

**验收证据**
- 关键任务触发权限：`backend/app/api/scheduler.py`（BOSS/ADMIN）与 `backend/app/api/ai_steward.py`（BOSS/ADMIN）
- 后端重试接口：`POST /scheduler/runs/{run_id}/retry`（BOSS/ADMIN），`scheduler_center.retry_run()`
- 前端失败一键重试：`schedulerApi.retryRun(runId)` + 失败任务红底/红边样式，`frontend/src/pages/SchedulerCenterPage.tsx`

---

## 3. DoD（完成定义）

- [x] 调度中心页面可访问、可触发、可追踪。
- [x] 关键调度任务有持久化记录（成功/失败可区分）。
- [x] O4-4 首版实现“可持续更新认知状态”的调度入口。
- [x] 前端构建通过：`cd frontend && npm run build`