# willSystem 项目流程图

## 计划任务配置与执行流程

```mermaid
flowchart TD
    A[前端计划任务配置页面] --> B[AgentReportController]
    B --> C[JobConfigService]
    C --> D[(job_config)]
    C --> E[ConfigService]
    E --> F[(config_group / config_item)]
    F --> G[JOB_TYPE 任务功能下拉]

    C --> H[JobScheduleSyncService]
    H --> I[XxlJobScheduleSyncService]
    I --> J[XxlJobAdminClient]
    J --> K[XXL-JOB Admin]
    K --> L[executorHandler: agentReportDispatchJob]
    K --> M[executorParam: configId]

    L --> N[ZentaoEffortReportJobHandler]
    M --> N
    N --> C
    N --> O[JobExecutionDispatcher]
    O --> P[JobExecutor]
    O --> Q[BuildReportService]
    Q --> R["@ReportJob + ReportBuilder"]
    R --> S[ZentaoDailyEffortReportBuilder]
    R --> T[ZentaoWeeklyTaskDetailReportBuilder]
    S --> U[ZentaoEffortReportQueryService]
    T --> U
    U --> V[(Zentao DB)]
    Q --> W[RobotMessageClient / MailMessageClient]
    W --> X[企业微信 / 飞书 / 钉钉 / 邮件]
```

## 统一配置流程

```mermaid
flowchart TD
    A[前端统一配置页面] --> B[ConfigController]
    B --> C[ConfigService]
    C --> D[(config_group)]
    C --> E[(config_item)]
    D --> F[配置组]
    E --> G[配置项]
    G --> H[JOB_TYPE]
    H --> I[计划任务配置的任务功能下拉]
```

## 当前关键设置

- 计划任务配置表是 `job_config`。
- 系统配置主子表是 `config_group` 和 `config_item`。
- 任务功能下拉不写死在前端，来自 `config_group.code = JOB_TYPE` 下的启用配置项。
- `job_config` 不再保存 `zone`、`daysAgo`、`groupName`。
- 时区、执行范围、统计偏移等业务逻辑固定在后端执行逻辑中。
- 计划任务保存时，`name`、`jobType`、`cron` 必填。
- `jobType` 必须存在于启用的 `JOB_TYPE` 配置项中。
- 任务执行采用插件式 `JobExecutor` 结构。
- 报表类任务采用 `@ReportJob(jobType = "...") + ReportBuilder` 自动装载。
- 新增报表类计划任务时，优先新增一个 `ReportBuilder` 实现类，不改 `BuildReportService` 和调度入口。
- 非报表类任务仍可新增一个 `JobExecutor` 实现类。
- XXL-JOB 统一使用 `agentReportDispatchJob` 作为执行器 Handler。
- XXL-JOB 参数只传 `configId`，执行时再读取 `job_config` 获取完整配置。

## 新增计划任务推荐流程

```mermaid
flowchart TD
    A[新增任务需求] --> B[确认是否需要新增 jobType]
    B --> C[在 JOB_TYPE 配置项中新增任务功能]
    C --> D{是否报表发送类任务}
    D -->|是| E[新增 ReportBuilder 实现并标注 @ReportJob]
    D -->|否| F[新增 JobExecutor 实现]
    E --> G[实现 build ReportRequest]
    F --> H[实现 execute JobConfigDTO]
    G --> I[复用或新增业务 Service]
    H --> I
    I --> J[如需新字段再评估 job_config 表结构]
    J --> K[同步 SQL 脚本和前端表单]
    K --> L[运行后端编译和前端类型检查]
```

## 后续需求调整原则

- 先判断需求属于配置管理、任务类型、任务执行器、业务报表查询、消息发送还是 XXL-JOB 同步。
- 不在 `JobConfigService` 中增加具体业务执行分支。
- 不在 `ZentaoEffortReportJobHandler` 中增加具体任务类型判断。
- 不在 `BuildReportService` 中增加具体报表类型判断。
- 不在前端写死任务功能下拉值。
- 新增表字段前先确认是否是业务逻辑固定值，固定值优先放后端执行代码。
- 旧表迁移和新建表脚本必须同步检查。