will_server/PROJECT_FLOW.md

willSystem 项目流程图

计划任务配置与执行流程

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[企业微信 / 飞书 / 钉钉 / 邮件]

统一配置流程

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 获取完整配置。

新增计划任务推荐流程

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 中增加具体报表类型判断。
• 不在前端写死任务功能下拉值。
• 新增表字段前先确认是否是业务逻辑固定值，固定值优先放后端执行代码。
• 旧表迁移和新建表脚本必须同步检查。