浅浅升级一下

openspec/changes/archive/2026-05-06-split-worker-roles/tasks.md

@@ -0,0 +1,38 @@
+## 1. 配置与常量
+
+- [x] 1.1 在 `pkg/constants/` 新增 Worker 角色常量：`all`、`leader`、`consumer`，并为所有导出常量添加中文注释
+- [x] 1.2 在 `pkg/config/config.go` 新增 `WorkerConfig`，字段包含 `Role` 和 `InstanceName`
+- [x] 1.3 在 `Config` 中挂载 `Worker WorkerConfig`，并在 `Validate()` 中校验 `worker.role` 只允许 `all`、`leader`、`consumer`
+- [x] 1.4 在 `pkg/config/defaults/config.yaml` 新增 `worker.role: "all"` 和 `worker.instance_name: ""`
+- [x] 1.5 在 `pkg/config/loader.go` 绑定 `worker.role` 和 `worker.instance_name` 环境变量
+- [x] 1.6 运行 `lsp_diagnostics` 检查 `pkg/config/config.go`、`pkg/config/loader.go`、新增常量文件无诊断错误
+
+## 2. Worker 启动角色拆分
+
+- [x] 2.1 在 `cmd/worker/main.go` 中读取 `cfg.Worker.Role` 和 `cfg.Worker.InstanceName`，并输出当前角色和实例名称日志
+- [x] 2.2 将当前 Worker 启动流程整理为共享依赖初始化段，确保 Redis、PostgreSQL、Storage、Gateway、Asynq Client、`BootstrapWorker`、`PollingConfigManager`、`PollingQueueManager`、`PollingBase`、`PollingLifecycleService` 对所有角色都可用
+- [x] 2.3 为 `all/leader` 启动 `PollingInitializer`，并保留配置从空变为非空时触发 `Restart(ctx)` 的 WatchChanges 逻辑
+- [x] 2.4 为 `all/leader` 创建并启动 `PollingScheduler`，为 `consumer` 跳过调度器创建或启动
+- [x] 2.5 为 `all/leader` 创建、注册并启动 Asynq Scheduler，注册现有 `order_expire`、`alert_check`、`data_cleanup`、`daily_traffic_flush` 定时任务；为 `consumer` 完全跳过
+- [x] 2.6 确保所有角色都创建 Asynq Worker Server、注册全部任务 Handler，并调用 `workerServer.Run(taskHandler.GetMux())`
+- [x] 2.7 启动日志输出已启用模块和已禁用模块，模块名包含 `queue_server`、`polling_initializer`、`polling_scheduler`、`asynq_scheduler`
+- [x] 2.8 调整优雅关闭逻辑：只关闭当前角色实际启动过的 Asynq Scheduler 和 Polling Scheduler，所有角色都关闭 Worker Server
+- [x] 2.9 运行 `lsp_diagnostics` 检查 `cmd/worker/main.go` 无诊断错误
+
+## 3. 文档更新
+
+- [x] 3.1 更新 `docs/environment-variables.md`，新增 `JUNHONG_WORKER_ROLE` 和 `JUNHONG_WORKER_INSTANCE_NAME` 说明、默认值和示例
+- [x] 3.2 在 `docs/environment-variables.md` 的 Docker Compose 示例中说明单实例默认 `all`，多实例推荐 `1 leader + N consumer`
+- [x] 3.3 更新 `docs/polling-system/performance-tuning.md` 的 Worker 多实例部署段落，明确禁止直接复制完整 worker，推荐扩展 `consumer`
+- [x] 3.4 对更新过的文档执行人工阅读检查，确认无“多个完整 worker 可直接多开”的歧义表述
+
+## 4. 编译与人工验证
+
+- [x] 4.1 对修改过的 Go 文件执行 `gofmt`
+- [x] 4.2 执行 `go build ./cmd/worker`，确认 Worker 入口编译通过
+- [x] 4.3 执行 `go build ./...`，确认项目整体编译通过
+- [x] 4.4 使用默认配置值检查 `all` 模式日志预期：应显示启用 `queue_server`、`polling_initializer`、`polling_scheduler`、`asynq_scheduler`
+- [x] 4.5 使用 `JUNHONG_WORKER_ROLE=leader` 检查日志预期：应显示与 `all` 相同的启用模块，并体现角色为 `leader`
+- [x] 4.6 使用 `JUNHONG_WORKER_ROLE=consumer` 检查日志预期：应显示启用 `queue_server`，禁用 `polling_initializer`、`polling_scheduler`、`asynq_scheduler`
+- [x] 4.7 使用非法角色值检查配置校验预期：`JUNHONG_WORKER_ROLE=invalid` 时启动失败，错误信息明确指向 `worker.role`
+- [x] 4.8 记录未覆盖风险：本期不包含 Redis Leader 锁、自动选主、任务唯一性去重，这些进入第二期增强