WebODM任务生命周期-设计文档

文档名称: WebODM任务生命周期设计文档
适用系统: 项目甲后端 (Spring Boot + MyBatis-Plus + PostgreSQL)
目标: 打通第三方就绪任务扫描 -> WebODM处理 -> 第三方发布 -> 回调落库 -> DSM数据生成的完整闭环
版本: V1.0
日期: 2026-04-14

2. 背景与目标

2.1 背景

第三方系统直接在 kjzg_webodm_task 表中创建任务数据并推进状态，当 status=3 时表示第三方任务就绪并已填充 zip_path。本服务从 status=3 开始接管，基于 WebODM 完成识别流程并生成 tif 成果。随后由第三方系统进行发布，并回调发布地址。最终本服务需将关键结果写入 kjzg_bgdc_tdgwh_dsm。

2.2 目标

支持自动扫描第三方就绪任务(status=3)并接管推进。
支持按任务全生命周期推进并可追踪。
任务执行过程可观测，日志可追溯。
支持第三方通过 id 拉取 tif 文件流。
支持发布回调后自动补全 kjzg_bgdc_tdgwh_dsm。

2.3 非目标

本版本不实现 WebODM 全参数精细配置管理平台。
本版本不实现复杂分布式编排引擎，仅采用外部 xxl-job 调度推进。

3. 总体流程

3.1 生命周期步骤

前置(第三方负责): 第三方在 kjzg_webodm_task 创建数据并推进 status 至 3，同时填充 zip_path
第一步: 扫描 status=3 的任务，调用 WebODM 创建任务、轮询进度、下载 tif
第二步: 调用第三方发布接口，仅传 id
第三步: 第三方回调本服务，传 id/file/url
第四步: 生成一条完整 kjzg_bgdc_tdgwh_dsm 数据

3.2 关键约束

第三方直接操作数据库: 创建记录、推进 status 至 3、填充 zip_path
本系统从 status=3 开始接管并推进后续阶段(4→5→...→10)
第三方发布调用: 仅传 id
第三方取 tif: 调用本地下载接口，传 id，返回文件流
状态展示: status 数字状态码 + stage 中文阶段 + step_no 步骤号 + 进度百分比
推进方式: 外部 xxl-job 调用本服务推进接口

4. 任务状态机设计

4.1 status 编码映射

status	阶段说明	负责方
1	第三方阶段1(已占用)	第三方
2	第三方阶段2(已占用)	第三方
3	第三方任务就绪(zip_path已填充)	第三方
4	WebODM鉴权完成	本系统
5	WebODM任务已创建	本系统
6	WebODM处理中	本系统
7	WebODM处理完成	本系统
8	已请求第三方发布	本系统
9	已接收发布回调	本系统
10	已写入DSM(终态-成功)	本系统
-1	失败终态	第三方/本系统

4.2 step_no 编码映射

step_no	步骤说明	对应status范围
1	第三方阶段(step_no/stage/status皆可null)	1~3
2	WebODM数据处理	4~7
3	第三方发布	8
4	发布回调处理	9
5	DSM数据生成	10

4.3 stage 中文值映射

step_no	stage可选值	说明
1	(null)	第三方管理，本系统未接管
2	WebODM鉴权中	正在获取WebODM Token
2	WebODM任务创建中	正在创建WebODM任务
2	WebODM处理中	WebODM正在处理任务
2	下载正射影像中	正在下载tif文件
2	WebODM处理完成	tif已下载到本地
3	请求第三方发布中	正在调用发布接口
3	已请求第三方发布	发布接口调用成功
4	已接收发布回调	回调数据已保存
5	写入DSM中	正在写入DSM数据
5	已完成	全流程结束(终态)

重试时stage会被重置为对应步骤的起始阶段值。

4.4 状态流转

第三方: 1 → 2 → 3
本系统: 3 → 4 → 5 → 6 → 7 → 8 → 9 → 10
任意阶段失败(第三方或本系统均可置为-1): → -1

本系统失败时: status=-1, stage保留失败时的阶段值, last_error记录失败原因。第三方失败时: status=-1, stage为null(本系统未接管)。

4.5 进度口径

progress 范围 0~100
当 status=6(WebODM处理中) 时: progress = webodm.progress * 100
其他阶段按里程碑给固定值，例如:
- status=3(第三方就绪): 5
- status=5(WebODM任务已创建): 20
- status=7(WebODM处理完成): 70
- status=8(已请求第三方发布): 80
- status=9(已接收发布回调): 90
- status=10(已写入DSM): 100

5. 数据库设计

5.1 主任务表: `kjzg_webodm_task`

5.1.1 建表SQL

CREATE TABLE IF NOT EXISTS public.kjzg_webodm_task (
  id varchar(32) PRIMARY KEY,
  xmbh varchar(255) NOT NULL,
  zip_path varchar(1024),
  project_id int4,
  webodm_task_id varchar(64),
  tif_path varchar(1024),
  publish_file varchar(1024),
  publish_url varchar(1024),
  status int4,
  stage varchar(32),
  step_no int2,
  progress numeric(5,2) NOT NULL DEFAULT 0,
  retry_count int4 NOT NULL DEFAULT 0,
  last_error text,
  created_time timestamp(0) NOT NULL DEFAULT now(),
  updated_time timestamp(0) NOT NULL DEFAULT now(),
  finished_time timestamp(0)
);

CREATE INDEX IF NOT EXISTS idx_webodm_task_status ON public.kjzg_webodm_task(status);
CREATE INDEX IF NOT EXISTS idx_webodm_task_stage ON public.kjzg_webodm_task(stage);
CREATE INDEX IF NOT EXISTS idx_webodm_task_created_time ON public.kjzg_webodm_task(created_time);
CREATE INDEX IF NOT EXISTS idx_webodm_task_xmbh ON public.kjzg_webodm_task(xmbh);

COMMENT ON TABLE public.kjzg_webodm_task IS 'WebODM任务主表';
COMMENT ON COLUMN public.kjzg_webodm_task.id IS '任务主键ID(第三方创建时传入)';
COMMENT ON COLUMN public.kjzg_webodm_task.xmbh IS '第三方任务ID';
COMMENT ON COLUMN public.kjzg_webodm_task.zip_path IS '第三方填充的zip绝对路径(status=3时填充)';
COMMENT ON COLUMN public.kjzg_webodm_task.project_id IS 'WebODM项目ID';
COMMENT ON COLUMN public.kjzg_webodm_task.webodm_task_id IS 'WebODM任务ID';
COMMENT ON COLUMN public.kjzg_webodm_task.tif_path IS '本地tif文件路径';
COMMENT ON COLUMN public.kjzg_webodm_task.publish_file IS '第三方回调发布后图片地址';
COMMENT ON COLUMN public.kjzg_webodm_task.publish_url IS '第三方回调发布后服务地址';
COMMENT ON COLUMN public.kjzg_webodm_task.status IS '任务状态码(1-3第三方阶段, 4-10本系统阶段, -1失败终态, 可为null)';
COMMENT ON COLUMN public.kjzg_webodm_task.stage IS '当前阶段状态(中文值，示例: WebODM处理中)，null表示本系统尚未接管';
COMMENT ON COLUMN public.kjzg_webodm_task.step_no IS '当前生命周期步骤(1-5)，null表示本系统尚未接管';
COMMENT ON COLUMN public.kjzg_webodm_task.progress IS '任务进度百分比(0-100)';
COMMENT ON COLUMN public.kjzg_webodm_task.retry_count IS '本系统处理重试次数';
COMMENT ON COLUMN public.kjzg_webodm_task.last_error IS '最近一次失败原因';
COMMENT ON COLUMN public.kjzg_webodm_task.created_time IS '创建时间';
COMMENT ON COLUMN public.kjzg_webodm_task.updated_time IS '更新时间';
COMMENT ON COLUMN public.kjzg_webodm_task.finished_time IS '完成时间';

5.1.2 字段说明

id: 任务主键，第三方创建时传入
xmbh: 第三方任务ID
zip_path: 第三方填充的zip绝对路径(status=3时填充)
webodm_task_id: WebODM任务ID
tif_path: 本地tif文件路径
publish_file/publish_url: 第三方回调产出
status: 任务状态码(int4)，1-3第三方阶段，4-10本系统阶段，-1失败，可为null
stage: 本系统当前阶段状态(中文值)，null表示本系统尚未接管
step_no: 当前生命周期步骤(1-5)，null表示本系统尚未接管
progress: 进度百分比
retry_count: 本系统处理重试次数

5.2 任务日志表: `kjzg_webodm_task_log`

5.2.1 建表SQL

CREATE TABLE IF NOT EXISTS public.kjzg_webodm_task_log (
    id varchar(32) PRIMARY KEY,
  task_id varchar(32) NOT NULL,
    action varchar(255) NOT NULL,
    success int2 NOT NULL,
    message varchar(1000),
    detail_json text,
    start_time timestamp(0),
    end_time timestamp(0),
    cost_ms int8,
    operator varchar(32) NOT NULL,
    request_id varchar(64),
    created_time timestamp(0) NOT NULL DEFAULT now()
);

CREATE INDEX IF NOT EXISTS idx_webodm_task_log_task_time
ON public.kjzg_webodm_task_log(task_id, created_time);

COMMENT ON TABLE public.kjzg_webodm_task_log IS 'WebODM任务生命周期日志表';
COMMENT ON COLUMN public.kjzg_webodm_task_log.id IS '日志主键ID(UUID去中划线)';
COMMENT ON COLUMN public.kjzg_webodm_task_log.task_id IS '任务主表ID';
COMMENT ON COLUMN public.kjzg_webodm_task_log.action IS '动作名称(中文值，示例: WebODM任务创建)';
COMMENT ON COLUMN public.kjzg_webodm_task_log.success IS '是否成功 1成功 0失败';
COMMENT ON COLUMN public.kjzg_webodm_task_log.message IS '动作结果摘要';
COMMENT ON COLUMN public.kjzg_webodm_task_log.detail_json IS '动作明细JSON';
COMMENT ON COLUMN public.kjzg_webodm_task_log.start_time IS '动作开始时间';
COMMENT ON COLUMN public.kjzg_webodm_task_log.end_time IS '动作结束时间';
COMMENT ON COLUMN public.kjzg_webodm_task_log.cost_ms IS '动作耗时毫秒';
COMMENT ON COLUMN public.kjzg_webodm_task_log.operator IS '操作来源(API/XXLJOB/CALLBACK/SYSTEM)';
COMMENT ON COLUMN public.kjzg_webodm_task_log.request_id IS '请求追踪ID';
COMMENT ON COLUMN public.kjzg_webodm_task_log.created_time IS '日志创建时间';

5.2.2 记录原则

必须记录以下节点:

WebODM鉴权
WebODM任务创建
轮询过程 (可做摘要)
tif下载
第三方发布请求
第三方回调保存
DSM写入
任意失败节点

动作字段建议值(中文直接入库):

WebODM鉴权
WebODM任务创建
WebODM状态轮询
下载正射影像
请求第三方发布
保存发布回调
写入DSM数据
任务失败处理
任务重试

5.3 既有表使用说明: `kjzg_bgdc_tdgwh_dsm`

5.3.1 本版本原则

不对既有 kjzg_bgdc_tdgwh_dsm 表结构做任何改造，保持现网兼容。

5.3.2 V1字段映射

xmbh: 映射第三方任务ID (xmbh)
file: 映射回调 file
url: 映射回调 url
scsj/rectangle/size: 本版本先空置

说明: 后续版本可再评估 scsj/rectangle/size 的自动提取规则。

6. 接口设计

6.1 调度推进接口 (供xxl-job调用)

6.1.1 批量推进

方法: POST
路径: /api/kjzg-webodm-task/trigger/pending?limit=50
作用: 扫描 status=3 的就绪任务以及 status=4~8 的进行中任务，按当前状态推进下一步（跳过 status=-1 的失败任务，因为第三方也可能置为-1）

6.1.2 单任务推进

方法: POST
路径: /api/kjzg-webodm-task/trigger/{id}
作用: 手动推进单个任务

6.2 手动重试接口

方法: POST
路径: /api/kjzg-webodm-task/retry/{id}
作用: 对失败任务(status=-1)进行手动重试
前置条件: status=-1 且 stage IS NOT NULL（即本系统已接管过的任务）
行为: 重置 status 为失败前的状态码，清空 last_error，retry_count +1，重新推进
错误场景:
1. id不存在
2. 任务非失败状态
3. stage为null（第三方失败，本系统不可重试）
返回: JsonResult

6.3 按id下载tif文件流

方法: GET
路径: /api/kjzg-webodm-task/download/{id}
入参: 路径参数 id
出参: 文件流 (image/tiff)
失败响应: JsonResult风格错误信息

错误场景:

id不存在
任务未生成tif
文件路径不存在或文件丢失

6.4 发布回调接口

方法: POST
路径: /api/kjzg-webodm-task/publish/callback
入参:

{
  "id": "[ID已隐藏]",
  "file": "http://xxx/xxx/orthophoto.tif",
  "url": "http://xxx/tiles/{TileMatrix}/{TileCol}/{TileRow}.png"
}

返回: JsonResult

幂等策略:

同一 id 重复回调时执行覆盖更新，并追加日志。

6.5 查询接口

6.5.1 任务分页

方法: GET
路径: /api/kjzg-webodm-task/page
参数: page, limit, xmbh, status, stage, step_no
返回包含: 创建时间、状态码、阶段、步骤号、进度、重试次数、错误信息

6.5.2 任务详情

方法: GET
路径: /api/kjzg-webodm-task/detail/{id}

6.5.3 日志分页

方法: GET
路径: /api/kjzg-webodm-task/logs
参数: id, page, limit

7. 业务编排设计

7.1 WebODM处理逻辑

获取Token
创建WebODM任务
轮询状态
任务完成下载 orthophoto.tif
保存本地路径并更新任务状态

轮询建议:

间隔: 10-30秒
status=40: 完成
status=30: 失败
status=50: 取消

7.2 本地文件存储策略

配置项: webodm.flow.tif-storage-path
未配置: 默认项目 public 目录
路径规则: {basePath}/{id}/orthophoto.tif

7.3 第三方发布逻辑

本服务调用第三方发布接口，仅传 id
第三方调用本地下载接口拉取tif
第三方发布成功后回调 file/url

8. 调度推进设计

项目采用HTTP接口 + 外部调度器模式，通过 WebodmTaskCornController(/webodm-corn) 暴露推进接口，由外部xxl-job定时调用。

8.1 推荐调度任务

triggerPending(/webodm-corn/triggerPending): 每1-2分钟执行一次
repair(/webodm-corn/repair): 每10-30分钟巡检异常任务(仅处理stage IS NOT NULL的失败任务)

8.2 并发控制

按 id 做任务级互斥，避免重复推进
单次批量推进数量可配 (limit)

8.3 重试策略

重试前提: stage IS NOT NULL（本系统已接管过的任务）
不可重试: stage IS NULL 且 status=-1（第三方失败，本系统无法介入）
自动重试次数: 3次 (可配置 webodm.flow.max-retry-count)
超限: 置为 status=-1，记录 last_error，不再自动重试
手动重试: 通过 /api/kjzg-webodm-task/retry/{id} 接口触发，不受自动重试次数上限约束

8.4 推进接口设计建议

推荐采用“单入口 + 阶段路由”，不建议对外暴露过多分阶段接口。

对外保留三个接口: 批量推进、单任务推进、手动重试。
推进接口内部根据 status + stage 路由执行对应阶段处理。

8.5 WebODM轮询执行建议

WebODM轮询建议独立于推进接口HTTP线程执行，避免阻塞推进接口。

推进接口只负责触发并快速返回。
轮询由后台异步任务执行。
推荐单独配置轮询定时任务，只处理 status=6(WebODM处理中) 状态任务。

9. 日志与可观测性

9.1 业务日志

每个动作节点写一条 kjzg_webodm_task_log
记录成功/失败、耗时、上下文摘要

9.2 操作日志

控制器接口建议增加统一操作日志注解，用于调用审计

9.3 关键监控指标

任务总量、成功量、失败量
各阶段平均耗时
WebODM失败率
第三方回调成功率

10. 异常处理

10.1 错误分类

数据校验错误 (zip_path为空/status异常)
文件错误 (zip不存在/tif不存在)
WebODM错误
第三方发布错误
回调数据错误
数据库错误

10.2 错误返回规范

统一返回 JsonResult 风格，建议携带:

status
msg
result (可选)

第三方发布接口响应判定:

当前按 JsonResult 标准结构处理
具体 success code 通过配置项约束，联调前最终确认

11. 安全与边界

11.1 鉴权策略

下载接口暂不设置鉴权
回调接口暂不设置鉴权

11.2 数据边界

本系统接管前校验 zip_path 是否在白名单目录，防止任意路径读取风险
回调参数需做长度与格式校验

12. 测试与验收

12.1 功能测试

第三方创建任务数据并推进至 status=3，本系统能正确扫描并接管
调度推进可完成到 WebODM 下载阶段
第三方按 id 成功下载 tif 流
回调后 file/url 成功保存
自动生成 kjzg_bgdc_tdgwh_dsm 数据

12.2 异常测试

status=3但zip_path为空或路径无效
WebODM失败
tif文件缺失
回调重复提交
调度重复触发并发
本系统失败任务自动重试，验证重试次数上限
手动重试本系统失败任务
尝试重试第三方失败任务(stage为null)，应被拒绝

12.3 验收标准

生命周期可闭环
状态与进度可查询
全链路日志可追溯
失败可定位、可重试、可终止
本系统失败任务可自动/手动重试，第三方失败任务不可重试

13. 待确认项

第三方发布接口最终URL、请求方法、字段名（开发时先空置）
JsonResult 成功码最终判定值 (如 status=1 或 code=200)

13.1 已确认项

下载接口暂不设置鉴权
xmbh 允许重复创建任务
scsj/rectangle/size 本版本先空置
第三方直接在数据库创建任务数据，本系统不提供创建接口
status字段使用数字编码，1-3为第三方阶段，4-10为本系统阶段，-1为失败终态(第三方和本系统均可置为-1)
本系统使用stage/step_no记录内部阶段状态，重试机制仅对stage不为null的任务生效
status/stage/step_no均可为null，无默认值，由第三方创建时自行管理
涉及第三方发布接口的代码先空置(预留接口调用位和TODO注释)，待联调时补充
DSM实体类已存在: com.geostar.zrzy.devops.entity.kjzgBgdcTdgwhDsm

14. 上线建议

先上线表结构与只读查询接口
再上线调度推进与 WebODM 处理
最后联调第三方发布与回调
联调期间开启详细日志，稳定后降级轮询日志颗粒度

附录A: 既有DSM实体结构

已有实体类 com.geostar.zrzy.devops.entity.kjzgBgdcTdgwhDsm:

@Data
public class kjzgBgdcTdgwhDsm {
    private float id;
    private String xmbh;       // 项目编号
    private LocalDateTime scsj; // 生成时间
    private String rectangle;
    private String size;        // width,height
    private String file;        // 文件地址
    private String url;         // 服务url
}

已有Mapper: com.geostar.zrzy.devops.mapper.KjzgBgdcTdgwhDsmMapper extends BaseMapper<kjzgBgdcTdgwhDsm>

注意: Mapper XML 的 namespace 当前指向了错误的 KjzgPatrolTaskMapper，开发时需修正。

V1写入字段映射:

DSM字段	数据来源	说明
`id`	自增	数据库自增主键
`xmbh`	`kjzg_webodm_task.xmbh`	第三方任务ID
`scsj`	null	本版本先空置
`rectangle`	null	本版本先空置
`size`	null	本版本先空置
`file`	回调参数 `file`	第三方发布后图片地址
`url`	回调参数 `url`	第三方发布后服务地址

附录B: 调度模式说明

项目未使用xxl-job注解，采用HTTP接口 + 外部调度器调用模式。

已有调度控制器模式参考

TaskCornController     → @RequestMapping("/cornApi")
UavTaskCornController  → @RequestMapping("/uav-corn")

本次开发调度控制器设计:

控制器类: WebodmTaskCornController
路径前缀: @RequestMapping("/webodm-corn")
对外暴露推进接口，由外部调度器(如xxl-job)定时HTTP调用

调度控制器与业务控制器分离:

WebodmTaskCornController (/webodm-corn): 供调度器调用的推进和巡检接口
WebodmTaskController (/api/kjzg-webodm-task): 供前端/第三方调用的查询、下载、回调、手动重试接口

异步处理

项目已配置 @EnableAsync（AsyncConfig.java），WebODM轮询可使用 @Async 方法异步执行。

附录C: WebODM配置项模板

在Nacos配置中心的 kjzg.yaml 增加以下配置:

webodm:
  base-url: http://localhost:8000         # WebODM服务地址
  username: admin                          # WebODM用户名
  password: yourpassword                   # WebODM密码
  project-id: 1                            # WebODM目标项目ID
  flow:
    tif-storage-path: [本地路径已隐藏]   # tif本地存储根目录(未配置则用public目录)
    max-retry-count: 3                     # 本系统自动重试次数上限
    poll-interval-seconds: 15              # WebODM轮询间隔(秒)
    token-expire-hours: 6                  # Token过期时间(小时)，用于主动刷新
  publish:                                 # 第三方发布(待联调确认)
    url: ""                                # 第三方发布接口URL
    method: POST                           # 请求方法

附录D: WebODM API 接口速查

Step 1: 获取Token

POST /api/token-auth/
Body: {"username":"xxx","password":"xxx"}
响应: {"token":"JWT_TOKEN"}
Token有效期6小时，过期返回403

Step 2: 上传ZIP创建任务

POST /api/projects/{project_id}/tasks/
Header: Authorization: JWT <token>
Content-Type: multipart/form-data
字段: images(ZIP文件，字段名必须为images)、name(任务名)、options(JSON字符串)
响应(201): 返回 id(UUID格式的task_id)、status(初始null)、progress(初始0.0)

options示例:

[{"name":"orthophoto-resolution","value":5}]

Step 3: 查询任务进度

GET /api/projects/{project_id}/tasks/{task_id}/
WebODM状态码: null=NEW, 10=QUEUED, 20=RUNNING, 30=FAILED, 40=COMPLETED, 50=CANCELED
progress: 0.0~1.0 (乘以100为百分比)
完成时 available_assets 包含 "orthophoto.tif"
失败时查看 last_error 字段

Step 4: 下载正射影像

GET /api/projects/{project_id}/tasks/{task_id}/download/orthophoto.tif
响应: 二进制文件流 (image/tiff)
前置: status==40 且 available_assets 包含 orthophoto.tif

附录E: 项目编码规范参考

包结构

实体: com.geostar.zrzy.devops.entity
Mapper: com.geostar.zrzy.devops.mapper
Service接口: com.geostar.zrzy.devops.service
Service实现: com.geostar.zrzy.devops.service.impl
Controller: com.geostar.zrzy.devops.controller
配置类: com.geostar.zrzy.devops.config
工具类: com.geostar.zrzy.devops.utils

Entity规范

@Data
public class XxxEntity {
    private String id;  // 无@TableName/@TableId注解也可(部分实体有)
}

Service规范

// 接口
public interface IXxxService extends IService<XxxEntity> { }
// 实现
@Service
public class XxxServiceImpl extends ServiceImpl<XxxMapper, XxxEntity> implements IXxxService { }

Controller规范

@RestController
@RequestMapping("/xxx")
@Api(tags = "模块描述")
public class XxxController {
    @ApiOperation(value = "接口名称", notes = "接口说明")
    @RequestMapping("/method")
    public JsonResult method() { }
}

HTTP调用

项目使用 PostUtil(OkHttp) 和 HttpUtil(Hutool)
JSON POST: PostUtil.httpPost2(url, jsonStr, token)
Form POST: PostUtil.doPost(url, map, charset, token)
GET: PostUtil.doGet(url, charset)
Multipart上传: 使用OkHttp MultipartBody 构建

ID生成

cn.hutool.core.util.IdUtil.simpleUUID() (32位无中划线UUID)

返回值

com.geostar.zrzy.geobase.result.JsonResult
构造: new JsonResult("成功消息") / new JsonResult(JsonResult.ERROR, "失败消息", null)
常量: JsonResult.SUCCESS, JsonResult.ERROR