签入版本

EasyGoAdmin_Gin_EleVue/zh/core/job-scheduler.md

@@ -0,0 +1,69 @@
+# 5.19 定时任务调度机制
+
+:::tip 概述
+调度基于 robfig/cron：**调度器基础设施在 service 的 job 模块，任务实现集中放在 internal/task 包**，经 init 自注册、按任务记录的 url 字段数据驱动查找。配套执行锁、任务日志与管理界面。
+:::
+
+## 架构分工
+
+```text
+internal/service/job*.go     调度器基础设施（cron 挂载/摘除/执行分派/执行锁）
+internal/task/*.go           任务处理方法（一任务一文件，init 自注册）
+service.DaemonInit           启动接线（cmd/api 在启动序列调用）
+cmd/api                      空白导入 task 包 → 触发 init 注册
+```
+
+依赖方向单向：task → service（注册 + 共享能力），service 不反向依赖 task。
+
+## 任务实现契约
+
+```go
+// internal/task/xxx.go
+func init() {
+    service.RegisterJobHandler("任务名", handler)   // 注册名 = 任务记录 url 字段值
+}
+
+// 处理方法签名
+func(ctx context.Context, params string) (string, error)
+// params：任务参数（JSON 字符串，可为空）
+// 返回：写入任务日志摘要的文本
+```
+
+**新增任务三步**：写 task 文件 → init 注册 → 管理界面建任务记录（url 填注册名 + cron 表达式）。不改调度器一行代码。
+
+## 内置任务
+
+| 任务 | 职责 |
+|---|---|
+| LogClean | 按 `job.logRetentionDays`（默认 90 天）物理清理超期的操作/登录/任务日志（经 WithPhysicalDelete 放行） |
+| SendSms | 短信发送示例任务 |
+| HelloWorld | 演示任务 |
+
+## 执行可靠性
+
+| 机制 | 说明 |
+|---|---|
+| 执行锁 | 键 TTL `job.lockTTLSeconds`（默认 300 秒），执行期自动续期；长任务超时也不会被并发抢占 |
+| 任务日志 | 每次执行写 gin_job_log（开始/结束/耗时/结果/摘要） |
+| 失败处理 | 错误写入任务日志，不影响下次调度 |
+| 启动恢复 | DaemonInit 按数据库任务记录重建 cron 挂载 |
+
+## 管理界面
+
+任务管理页（monitor/job）：任务 CRUD、cron 表达式配置、启停、手动执行、执行日志查看。见 [6.16 定时任务管理](/zh/modules/job.html)。
+
+## 配置
+
+```yaml
+job:
+  logRetentionDays: 90     # 日志保留天数（LogClean 消费）
+  lockTTLSeconds: 300      # 执行锁 TTL（任务参数可覆盖）
+```
+
+## 优雅关闭
+
+关闭链中"停定时任务"排在"关 DB"之前——任务可能还在写库，先停任务再关连接，避免执行期报错。
+
+## 下一步
+
+→ [第 6 章 业务模块](/zh/modules/user.html)