Job 模块 API

Job 模块是 MyApps 平台的**定时任务调度服务**（obpm-job），基于 Quartz 提供 iScript 定时任务的增删改查、触发、暂停、恢复、重排与列表查询能力。该模块的 context-path 占位符为 ${myapps.context-path.job:}（部署时替换为具体上下文路径，缺省为空；lite 统一打包下为 /，此时模块路径前缀多一层 /job）。

注：本仓库根 docs/restful-api/index.md「服务与基址」表暂未单独列出 job 行；模块无独立 application*.yml 公开源码（端口由部署侧 server.port 决定）。本模块路径前缀与 URL 模式均以源码为准。

覆盖进度：1 / 1 控制器（已覆盖 QuartzController）

Job 模块共有 1 个有端点的控制器，合计 7 个端点。

已文档化控制器

文件	中文名	基址	端点数
quartz.md	QuartzController（定时任务调度）	${myapps.context-path.job:}/quartz	7

鉴权说明

（据源码）job 模块**不使用 Spring Security**（全模块无 org.springframework.security 引用），不注册任何 Servlet Filter 或 HandlerInterceptor 做鉴权（JobMvcConfig 仅 implements WebMvcConfigurer，未重写任何方法、未注册 Bean）。访问控制完全依赖 obpm-common 提供的共享前置过滤器：

• PassFilter（obpm-common CommWebMvcConfig.filterRegistrationBeanPassFilter1，order=HIGHEST_PRECEDENCE）：命中白名单 URL（模块首页、/health、/actuator/health、静态资源后缀、magic-api 等）即标记 request.setAttribute("pass", true) 放行。
• CommonSecurityFilter（obpm-common CommWebMvcConfig.filterRegistrationBeanCommonSecurityFilter1，URL 模式 /*，order=-1）：所有模块共享，行为如下——
• 携带合法 systemToken 请求头（系统间 Feign 调用，JWT 内 username 固定为 systemToken）→ 标记 pass=true 放行；
• 仅允许 GET/POST/HEAD/OPTIONS 方法，其他方法返回 HTTP 405（HTML 错误页）；OPTIONS 为浏览器 CORS 预检放行；
• Environment.isReady() 为 false 时返回 HTTP 500，响应体「系统正在启动中，请稍后再试！」；
• /v3/api-docs、/swagger-ui、/druid 须持有效 designerToken 或 adminToken；/actuator/health 放开；其余 /actuator/** 返回 401（无响应体）；
• 其他请求直接 chain.doFilter，不校验业务 accessToken。

job 模块所有端点（/quartz/addObpmJob、/quartz/triggerJob、/quartz/pauseJob、/quartz/resumeJob、/quartz/rescheduleJob、/quartz/deleteJob、/quartz/jobs）均不在 PassFilter 白名单内，但因 CommonSecurityFilter 不做 token 校验，实际可匿名访问。

控制器内对用户身份的使用

QuartzController 完全不引用用户身份；调用方需自行确保仅在受控网络（如 manager 控制台、Feign 内部调用）暴露该模块，避免公网直连。

完整鉴权机制与错误码说明见：顶层 index.md。

响应结构与错误码

job 模块控制器返回**多种响应形态**，均不采用顶层统一 Resource：

形态一：纯字符串（操作类端点）

addObpmJob、triggerJob、pauseJob、resumeJob、rescheduleJob、deleteJob 通过 @ResponseBody 返回字符串：

• 成功："ok"
• 失败："fail"（异常被 catch 后吞掉堆栈，仅 e.printStackTrace()）

形态二：JSON 数组（listJobs）

listJobs 返回 List<JSONObject>（每个元素由 XmlToJsonUtil.xmlToJson(jobDataMap.getString("jobXml")) 转换得到，并附带 applicationName、status 字段）。异常时返回 null。

错误码补充

job 模块**未引入模块专属业务错误码**。鉴权 / 启动层引入以下与统一 Resource 不同的纯 HTTP 状态码：

errcode / HTTP	HTTP	含义
405	405	HTTP 方法不被允许（由 CommonSecurityFilter 拦截，仅允许 GET/POST/HEAD/OPTIONS，返回 HTML 错误页）
500	500	系统正在启动中（由 CommonSecurityFilter 在 Environment.isReady() 为 false 时返回，HTML 错误页）
—	200	操作类端点失败：响应体 "fail"（HTTP 状态仍 200）

覆盖说明

本阶段覆盖 obpm-job 工作树下的 QuartzController（定时任务调度，7 个端点，含新增 / 触发 / 暂停 / 恢复 / 重排 / 删除 / 列表查询任务）。job 模块有端点控制器已**全部覆盖**。

---