本目录是前端联调用的本地接口文档快照，已与当前后端实现和内嵌 Web 页面同步。

• openapi.yaml
• examples/create-job.request.json
• examples/job-detail.completed.json
• examples/job-detail.failed.json
• examples/system-status.json
• examples/system-options.json

• 本地开发：http://localhost:8080
• 生产 / 内网：由后端 server.publicBaseURL 配置项对外暴露
• 接口中的时间字段默认按 Asia/Shanghai 输出，例如 2026-03-26T10:30:00+08:00

queued -> pulling -> scanning -> rendering -> notifying -> completed

异常时终态：

failed

以下字段前后端可视为冻结字段，联调阶段不要自行改名：

• status
• sourceType
• targetRef
• imageRef
• dbSource
• dbLoadedAt
• scannersResolved
• pluginProfileResolved
• pluginTogglesResolved
• artifacts[].downloadUrl

• POST /api/v1/jobs
• 用途：提交一个新的通用扫描任务

请求重点：

• sourceType 可选，默认 registry
• targetRef 必填，imageRef 仅作为兼容旧客户端的别名保留
  • registry 模式：填写镜像地址
  • http-download 模式：填写镜像包下载 URL
  • filesystem 模式：填写 /workspace 或 /data 下的目录 / 压缩包 / rootfs 路径
  • repository 模式：填写本地仓库路径或远程 Git URL
  • sbom 模式：填写 /workspace 或 /data 下的 SBOM 文件路径
• scanPaths 可选，当前仅 filesystem 模式支持
  • 传数组，一项一个路径
  • 后端会把 targetRef 与 scanPaths 去重合并，作为最终扫描范围
• excludePaths 可选，当前仅 filesystem 模式支持
  • 传数组，一项一个路径
  • 支持相对扫描根的目录名 / 子路径，也支持 /workspace、/data 下的绝对路径
• scanners 可选，按任务覆盖 Trivy --scanners
  • 不传时继承 /api/v1/system/options 返回的 defaultScanners
  • 显式传空数组会被拒绝
  • sbom 模式仅支持 vuln 与 license
• registryProfile 仅 registry 模式可用
• pluginProfile 可选，指向后端配置中的插件组合
• pluginToggles 可选，按任务覆盖插件开关
• notificationProfile 可选，选择通知配置
• clientToken 可选，做幂等

成功返回：

• 202 Accepted
• body 直接返回初始任务对象

• GET /api/v1/jobs/{jobId}
• 用途：轮询任务状态、拿摘要和下载清单

前端建议：

• 任务处于 queued/pulling/scanning/rendering/notifying 时，每 3-5 秒轮询一次
• completed 后停止轮询，并展示下载清单
• failed 后展示 error.code、error.message、error.stage

• GET /api/v1/jobs/{jobId}/artifacts
• 用途：单独拉下载列表
• GET /api/v1/jobs/{jobId}/artifacts/preview/{name}
• 用途：在线预览工件；Markdown / HTML 走 JitViewer，JSON 走文本模式
• GET /api/v1/jobs/{jobId}/artifacts/raw/{name}
• 用途：为预览页提供 inline 原始内容

工件类型约定：

• html
• markdown
• json
• sbom
• summary
• other

• GET /api/v1/system/status
• 用途：前端首页展示当前数据库来源、插件可用性、系统是否 ready

• GET /api/v1/system/options
• 用途：前端动态拉取来源类型、scanner 默认值、registry profile、plugin profile、notification profile

• GET /api/v1/jobs?limit=50
• 用途：任务列表页展示最近任务

返回说明：

• body 直接返回 JobResponse[]
• 默认按 createdAt DESC 排序
• 首版只提供 limit，不做复杂分页

后端完成任务后，通常会返回以下工件：

• compliance-report.html
• compliance-report.md
• report.html
• scan.json
• native.spdx.json
• sbom.spdx.json
• summary.json

前端展示建议：

• compliance-report.html：合规评审与打印首选入口
• compliance-report.md：可审计、可版本管理的报告源文件
• report.html：主按钮，优先展示
• sbom.spdx.json：合规 / 审计下载按钮
• scan.json：高级模式或调试折叠区
• summary.json：摘要计数与自动化消费入口
• artifacts/preview/{name}：浏览器与企业微信预览入口
• artifacts/raw/{name}：预览页内部拉取原始内容，不建议直接给最终用户

保留策略说明：

• report.html、compliance-report.html、compliance-report.md 属于可视化报告，默认保留 30 天
• scan.json、summary.json、native.spdx.json、sbom.spdx.json 属于原始证据，默认保留 90 天
• 如果报告文件已被清理，但原始证据仍在，请求下载或原始内容时会自动重建报告文件

统一结构：

{
  "code": "registry_auth_failed",
  "message": "Registry authentication failed",
  "details": "profile prod-registry rejected by registry.example.com",
  "traceId": "trace-123",
  "stage": "pulling"
}

前端展示建议：

• 标题用 message
• 次级信息用 code
• 展开态展示 details
• 将 stage 作为故障步骤徽标

• external：完全使用 /data 下外部数据库
• embedded：完全回退到镜像内置数据库
• mixed：部分外部、部分内置

• registry：直接扫描镜像仓库引用
• http-download：先通过 HTTP/HTTPS 下载镜像包，再转离线输入给 Trivy
• filesystem：扫描项目目录、压缩包或 rootfs，本地路径必须位于 /workspace 或 /data
• repository：扫描本地 Git 仓库路径或远程 Git URL
• sbom：扫描 SPDX / CycloneDX 等 SBOM 文件

• scanPaths / excludePaths 目前只对 filesystem 模式生效
• 多路径扫描适合把多个项目目录、多个离线解包目录合并到同一次任务中
• excludePaths 适合过滤 node_modules、vendor、dist、.git、生成物目录等噪音来源
• 前端建议使用多行输入框，一行一个路径，再转成字符串数组提交给后端

• /api/v1/system/options 会返回 scannerOptions 与 defaultScanners
• 前端若保持默认勾选，可省略 scanners 字段，让后端继承当前配置
• 前端若修改勾选，应显式提交 scanners
• GET /api/v1/jobs/{jobId} 返回的 scannersResolved 表示本次任务最终生效的 scanners
• sbom 模式最终只会执行 vuln 与 license

• artifacts[].downloadUrl 现在统一返回相对路径 /api/v1/jobs/{jobId}/artifacts/download/{name}，前端应直接交给浏览器按当前地址栏 / 反代域名解析
• Webhook URL 与 Registry 密码不应在前端输入明文，只能选择 profile
• 前端任务列表应以后端 GET /api/v1/jobs 为准，不应只依赖浏览器本地缓存
• 前端优先使用 targetRef 展示扫描目标；若兼容旧返回结构，可回退到 imageRef
• 高级设置中的 pluginToggles 现在会显式提交 true/false，可以真正覆盖默认 profile，而不是只能“加开不能关”
• 高级设置中的 scanners 建议仅在用户改动后才提交；sbom 模式需限制或提示仅 vuln/license 生效