# fs-task 定时任务模块说明

## 架构

| 模块 | 职责 |
|------|------|
| **fs-quartz** | Quartz 框架、sys_job CRUD、ScheduleConfig |
| **fs-task** | 所有 Task Bean（原 admin-saas / fs-qw-task / fs-service 任务类） |
| **fs-admin** | 唯一调度入口：引入 fs-quartz + fs-task，无 @EnableScheduling |
| **fs-admin-saas** | 纯 API：引入 fs-task 仅用于 Controller 手动触发，无 fs-quartz、无 @Scheduled |

## 迁移内容

- fs-admin-saas/src/.../task/** 迁移到 fs-task
- fs-qw-task/src/.../app/task/**、taskService/** 迁移到 fs-task
- fs-service 内 com.fs.*.task 包已删除（避免与 fs-task 类重复）
- 所有 @Scheduled 已移除，改由 sys_job + Quartz 调度

## 部署步骤

1. 编译：mvn -pl fs-admin -am package -DskipTests
2. 执行菜单 SQL：sql/admin_sys_menu_job.sql（总后台 sys_menu）
3. 执行任务种子 SQL：sql/fs_task_sys_job_seed.sql（通用任务，按需将 status 改为 0 启用）
4. 执行企微任务 SQL：sql/fs_qw_task_sys_job_seed.sql（28 条，job_group=QW_TASK）
5. 在 adminUI 系统监控 - 定时任务 管理任务；新增时可点 Bean注册表 选用 invoke_target

## 调用方式

Quartz 通过 sys_job.invoke_target 调用 Spring Bean 方法，格式示例：

``
qwTask.addTag()
task.deleteUserOperationLog()
lobsterBridgeDataSyncService.syncLobsterBridgeData()
platformStatisticsServiceImpl.executeHourlyStats()
``

在 adminUI 定时任务页面点击 Bean注册表，可查看 fs-task 中所有可调度方法。

## 注意事项

- 原 @Scheduled(fixedDelay=...) 需在 sys_job 中改用近似 cron 表达式
- EventLogUtils 200ms 轮询类任务建议保留独立线程或单独评估，不宜直接配 Quartz
- fs-qw-task 独立进程已去除 @EnableScheduling，任务统一由 fs-admin 调度
- seed SQL 中任务默认 status=1（暂停），确认无误后改为 0 才会执行

## 相关文件

| 文件 | 说明 |
|------|------|
| fs-task/pom.xml | 任务模块依赖 |
| fs-task/.../TaskModuleConfiguration.java | Task Bean 包扫描配置 |
| fs-task/.../TaskRegistryController.java | Bean 注册表 API |
| sql/admin_sys_menu_job.sql | 总后台定时任务菜单 |
| sql/fs_task_sys_job_seed.sql | 通用任务 sys_job 种子数据 |
| sql/fs_qw_task_sys_job_seed.sql | 企微 fs-qw-task 迁移任务（28 条） |
| sql/generate_qw_task_sys_job_seed.py | 重新生成企微任务 SQL |

## 独立运行 fs-task（可选，用于手动触发任务调试）
```bash
cd fs-task
mvn clean package -DskipTests
java -jar target/fs-task.jar
# 默认端口 8018，可通过 application.yml 修改
# 访问 http://localhost:8018/app/common/test 等手动接口
```

## 集成到 fs-admin
fs-admin 的 pom 依赖 fs-task（任务 Bean 由 TaskModuleConfiguration 自动扫描注册，Bean 注册表 /monitor/taskRegistry 和 /app/common 手动调试接口可用）。

fs-admin-saas 已移除对 fs-task 的直接依赖（原 SgTestController 等测试入口已随任务类迁移到 fs-task 模块内部；如需保留特定测试端点，可在 fs-task 内添加或通过 HTTP 远程调用旧 taskApi）。

相关文件：
- FsTaskApplication.java （启动类，支持独立调试运行）
- TaskPackages.java + TaskModuleConfiguration + TaskRegistryService （统一任务包扫描列表，避免不一致）
- 标准配置文件（application*.yml, logback.xml 等，参考其他模块完善）
- META-INF/spring/.../AutoConfiguration.imports （自动加载配置）

## 当前包结构（重新整理后）

fs-task/src/main/java/com/fs/
├── FsTaskApplication.java
├── task/
│   ├── TaskPackages.java                  // 所有任务包前缀列表（供扫描 + 注册表过滤）
│   ├── config/
│   │   └── TaskModuleConfiguration.java   // @ComponentScan 声明
│   ├── controller/
│   │   ├── TaskRegistryController.java    // /monitor/taskRegistry Bean 注册表
│   │   └── TaskManualController.java      // /app/common/* 手动触发调试接口
│   ├── service/
│   │   └── TaskRegistryService.java       // 反射扫描可调用方法的实现
│   ├── jobs/                              // 任务入口（可被 sys_job 直接 invoke 的 @Component）
│   │   ├── QwTask.java                    // 企微 SOP / 群 / 客户相关主入口（原 qwTask）
│   │   ├── CourseWatchLogScheduler.java
│   │   └── QwUserAsyncTask.java
│   └── support/                           // 复杂任务的支撑服务与实现（原 app.taskService）
│       ├── *.java (接口)
│       └── impl/*.java
├── his/task/ ...                          // HIS 领域任务（BillTask, Task.java 大类等）
├── course/task/ ...
├── tenant/task/ ...
├── admin/sync/ ...
└── ad/controller/task/ ...

说明：
- 历史遗留的 com.fs.app.task / com.fs.app.taskService 已迁移到 com.fs.task.jobs / com.fs.task.support
- 迁移后保持 bean 名称不变（类名未改或大小写调整后首字母小写结果一致），sys_job 中的 invoke_target 无需修改。
- 新增任务时，把入口类放在 jobs/ 下（或对应 his/course 子包），支撑逻辑放在 support/ 下，并在 TaskPackages 中登记包前缀。