预标注流水线（Prediction Pipeline）

v0.9.8 引入 prediction_jobs 表后，AI 预标注从"无状态触发"升级为有状态的流水线。本页讲清状态机、写入时点、与下游表的关系。

决策依据：ADR 0014 — Prediction Jobs 历史表

状态机

状态	何时进入	关键字段
`created`	API 入队 Celery 时	`created_at`, `celery_task_id`, `prompt`, `ml_backend_id`
`running`	worker 在 task body 第一步写入	`started_at`
`succeeded`	task 正常返回	`finished_at`, `succeeded_count`, `failed_count`
`failed`	`_BatchPredictTask.on_failure` 兜底	`finished_at`, `error`

用途	查哪张表
列出"现在能采纳的候选框"	`predictions`（按 task 过滤）
列出"AI 跑了哪几次、成功失败、谁触发"	`prediction_jobs`
重置批次后回看历史	只能 `prediction_jobs`（`predictions` 已被清）
工作台读取候选 → 渲染紫框	`predictions` 经 `to_internal_shape` adapter

v0.10.17 起 predictions.tool_unit_id String(30) 列必填:

写入时由 PredictionService.create_from_ml_result 调 derive_tool_unit_from_result 按 result[0].type 派生:
- polygonlabels / brushlabels / multi_polygon → region
- rectanglelabels → bbox
- 其它(keypointlabels / linelabels)→ bbox 占位
to_internal_shape() 出参也带 tool_unit_id, 供前端候选层 / AAP JSON 导出消费
accept_prediction() 创建的 annotation 沿用 prediction 的 tool_unit_id (与项目 tool_bindings[unit].classes 软校验保一致)

通道	谁订阅	内容
`project:{id}:preannotate`	该项目工作台	单项目进度 / 错误
`global:prediction-jobs`	任何 admin	全局 in-flight job 进度（Topbar Badge）

后者解决 v0.9.7 的痛点：admin 切换项目后，旧项目的 in-flight 进度从屏幕上消失。

_BatchPredictTask.on_failure 把所有未捕获异常（包括 dispatch 阶段的 TypeError）推到 project:{id}:preannotate，前端 progress.error 分支可见——避免再出现"已排队后无响应"。