MinGo.Quartz 1.1.0

MinGo.Quartz.SDK — Quartz.NET 基础补强 + Agent SDK（L1 + L2 合并仓）

本仓合并了原 L1 MinGo.Quartz（Quartz.NET 基础补强 + 开放可观测性）与 L2 MinGo.Quartz.Agent（Agent SDK + 跨端共享契约）两层，所有包在同级目录下扁平组织。

依赖方向：MinGo.Quartz.Agent → MinGo.Quartz.Agent.Abstractions + MinGo.Quartz.OpenTelemetry → MinGo.Quartz → Quartz.NET + OpenTelemetry.Api。

项目构成

L1 — 基础补强 + 开放可观测性

L2 — Agent SDK + 跨端共享契约

快速开始

仅使用 L1（可观测性）

// 1) 宿主注册 L1 服务（读取器 + 默认脱敏器）
services.AddMinGoQuartzOpenTelemetry(o =>
{
    o.ActivitySourceName = "MinGo.Quartz";
    o.MeterName = "MinGo.Quartz";
    o.CaptureJobDataMap = true;          // 把 JobData（脱敏后）写入 span
});

// 2) 对调度器挂载监听器（创建 scheduler 后、Start 前均可）
using var observability = MinGoQuartzObservability.Attach(scheduler, services);

// 3) 宿主侧接 OTel SDK（导出器由宿主决定）
builder.Services.AddOpenTelemetry()
    .WithTracing(t => t.AddSource("MinGo.Quartz"))
    .WithMetrics(m => m.AddMeter("MinGo.Quartz"));

使用 L2（Agent SDK，自动组合 L1）

var builder = WebApplication.CreateBuilder(args);

// Quartz（宿主自行注册 Scheduler；SDK 自动发现单例/集合/ISchedulerFactory）
builder.Services.AddQuartz(q =>
{
    q.SchedulerName = "MyScheduler";
    q.UseInMemoryStore();
});
builder.Services.AddQuartzHostedService(o => o.WaitForJobsToComplete = true);

// MinGo Agent（注册/心跳/上报 + 自动挂 L1 可观测监听器 + 执行日志监听器）
builder.AddMinGoAgent();

var app = builder.Build();
app.MapMinGoAgentApi();          // /api/agent/...
app.Run();

config.yaml（可选，SDK 自动加载）：

agent:
  heartbeatIntervalSeconds: 30
  externalUrl: "http://localhost:5001"
platform:
  url: "http://localhost:5256"   # L3 Platform 地址
  apiToken: "your-api-token"

Agent Minimal API（MapMinGoAgentApi，前缀默认 /api/agent）

• GET /schedulers、GET /scheduler —— Scheduler 列表/默认状态
• GET/PUT/DELETE /jobs... —— Job 列表/详情/创建替换/更新/删除
• POST /jobs/{name}[/{group}]/trigger|pause|resume —— Job 级操作
• GET /manifest —— Agent 可调度 Job 清单（含参数元数据）

X-Scheduler-Name Header 或 ?schedulerName= 用于多 Scheduler 路由。

观测约定

• Span：quartz.job.execute、quartz.trigger.fire、quartz.trigger.misfire、quartz.scheduler.lifecycle。
• Metric：quartz.job.executions(counter)、quartz.job.duration(histogram)、quartz.trigger.fires/misfires(counter)、quartz.scheduler.executing.jobs(gauge)。
• 安全：JobDataMap 键含 password/token/secret/connectionstring/... 时值替换为 ***（DefaultJobDataRedactor，默认开启）。

关键能力（L2 相对旧 MinGo.Qap.Agent 的补强）

• Misfire 闭环：QuartzOptionsDto.MisfirePolicy 按 Trigger 类型真实写入 CronScheduleBuilder / SimpleScheduleBuilder；GetJobAsync 从 Trigger 回读真实指令（ReadMisfirePolicy），不再写死 FireAndProceed。
• 并发语义化：DisallowConcurrentExecution / StoreDurable / RequestRecovery 直接写入 JobDetail，而非仅 JobDataMap 标记。
• Trigger 级操作：pause / resume / unschedule 单 Trigger；Scheduler start / standby；Job interrupt。
• L1 组合：AddMinGoAgent() 内部调用 AddMinGoQuartzOpenTelemetry()，SchedulerListenerAttacher 在每个被发现的 Scheduler 上自动挂载 L1 观测监听器 + Agent 执行日志监听器。

构建与测试

正常 .NET 安装环境：dotnet build MinGo.Quartz.SDK.slnx。 本沙箱/精简环境请用 .\scripts\build.ps1 与 .\scripts\test.ps1（详见 scripts/README.md）。

依赖：Quartz 3.15.1、OpenTelemetry.Api 1.15.3、NSwag.AspNetCore 14.7.1、YamlDotNet 16.3.0；目标框架 net10.0（后续可多目标 net8.0）。

里程碑状态

L1

L2