feat: 采集任务状态跟踪(ingest_jobs)——fire-and-forget 可观测性 #12

2026-09-21T21:19:44+08:00

WorkBuddy commented

2026-09-21 21:19:44 +08:00

改动

数据层

新表 ingest_jobs(迁移 0019):id(UUID)/task/params JSONB/status(pending|running|success|failed,CheckConstraint)/result JSONB(统计摘要)/error/created_at/started_at/finished_at

API

POST /api/v1/ingest/bzzoiro:启动后台前创建 pending job,响应返回 job_id;仍 require_admin
后台 _run_bzzoiro:running → success/failed;result 按子任务记录摘要(errors 截断 10 条)
_update_job 尽力而为:更新失败只记日志,不影响采集主流程;与 IngestFailure 死信独立(行级 vs 任务级,可同时存在)
GET /api/v1/admin/ingest/jobs/{job_id}、GET /api/v1/admin/ingest/jobs?limit&status(挂 /admin 路由,路由级 require_admin)

前端

Admin 采集页:提交后凭 job_id 3 秒轮询,running 显示进度,终态展示结果摘要/失败原因;10 分钟兜底;无 job_id 回退旧的盲等提示

测试(新增 11 项,全量 274 passed + 1 skipped)

建 job + job_id 契约、非法 task 422、成功/失败/all 状态流转、_update_job 失败不拖垮采集、部分失败仍 success(死信另行记录)、admin 端点 200/404/列表、结构守护(job 路由在 admin 路由且带 require_admin)

禁止项确认

未动分批 UoW、BzzoiroSource、死信与 Bronze 写入
docs(01/03/05/07/README)同步 13 张表与新端点

注:基于 docs-public-api-fixes(PR #11)叠加,两批改动共享文档文件;PR #11 合并后本 PR 可顺畅合入 main。

## 改动 ### 数据层 - 新表 `ingest_jobs`(迁移 0019):id(UUID)/task/params JSONB/status(pending|running|success|failed,CheckConstraint)/result JSONB(统计摘要)/error/created_at/started_at/finished_at ### API - `POST /api/v1/ingest/bzzoiro`:启动后台前创建 pending job,响应返回 `job_id`;仍 require_admin - 后台 `_run_bzzoiro`:running → success/failed;result 按子任务记录摘要(errors 截断 10 条) - `_update_job` 尽力而为:更新失败只记日志,不影响采集主流程;与 IngestFailure 死信独立(行级 vs 任务级,可同时存在) - `GET /api/v1/admin/ingest/jobs/{job_id}`、`GET /api/v1/admin/ingest/jobs?limit&status`(挂 /admin 路由,路由级 require_admin) ### 前端 - Admin 采集页:提交后凭 job_id 3 秒轮询,running 显示进度,终态展示结果摘要/失败原因;10 分钟兜底;无 job_id 回退旧的盲等提示 ### 测试(新增 11 项,全量 274 passed + 1 skipped) - 建 job + job_id 契约、非法 task 422、成功/失败/all 状态流转、_update_job 失败不拖垮采集、部分失败仍 success(死信另行记录)、admin 端点 200/404/列表、结构守护(job 路由在 admin 路由且带 require_admin) ## 禁止项确认 - 未动分批 UoW、BzzoiroSource、死信与 Bronze 写入 - docs(01/03/05/07/README)同步 13 张表与新端点 > 注:基于 docs-public-api-fixes(PR #11)叠加,两批改动共享文档文件;PR #11 合并后本 PR 可顺畅合入 main。

WorkBuddy added 1 commit 2026-09-21 21:19:44 +08:00

feat(ingest): 采集任务状态跟踪(ingest_jobs),解决 fire-and-forget 不可观测 983363dab7

- 新表 ingest_jobs(迁移 0019): id UUID/task/params JSONB/
  status(pending|running|success|failed,CheckConstraint)/
  result JSONB(统计摘要)/error/created_at/started_at/finished_at
- POST /ingest/bzzoiro: 启动后台前创建 pending job,响应返回 job_id;
  仍 require_admin。后台 _run_bzzoiro 流转 running→success/failed,
  result 按子任务(events/standings/stats)记录摘要(errors 截断 10 条)
- _update_job 尽力而为: 状态更新失败只记日志,绝不拖垮采集主流程;
  与 IngestFailure 死信独立(行级 vs 任务级,可同时存在)
- 新增 admin 端点(挂 /api/v1/admin 路由,路由级 require_admin):
  GET /admin/ingest/jobs/{job_id} 与 GET /admin/ingest/jobs?limit&status
- 前端采集页: 提交后凭 job_id 3 秒轮询,终态展示结果摘要/失败原因;
  无 job_id 时回退旧的 30 秒盲等 + 系统日志提示
- 测试 11 项: 建 job+job_id 契约、非法 task 422、成功/失败/all 流转、
  update 失败不拖垮采集、部分失败仍 success、admin 端点 200/404/列表、
  结构守护(job 路由在 admin 路由且带 require_admin)
- 禁止项确认: 未动分批 UoW、BzzoiroSource、死信与 Bronze 写入;
  docs(01/03/05/07/README)同步 13 张表与端点说明

shangfangjian merged commit c7be14c518 into docs-public-api-fixes

2026-09-21 21:39:21 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: shangfangjian/Profeto#12