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

1. 配置与常量

• 1.1 在 pkg/constants/ 新增 Worker 角色常量：all、leader、consumer，并为所有导出常量添加中文注释
• 1.2 在 pkg/config/config.go 新增 WorkerConfig，字段包含 Role 和 InstanceName
• 1.3 在 Config 中挂载 Worker WorkerConfig，并在 Validate() 中校验 worker.role 只允许 all、leader、consumer
• 1.4 在 pkg/config/defaults/config.yaml 新增 worker.role: "all" 和 worker.instance_name: ""
• 1.5 在 pkg/config/loader.go 绑定 worker.role 和 worker.instance_name 环境变量
• 1.6 运行 lsp_diagnostics 检查 pkg/config/config.go、pkg/config/loader.go、新增常量文件无诊断错误

2. Worker 启动角色拆分

• 2.1 在 cmd/worker/main.go 中读取 cfg.Worker.Role 和 cfg.Worker.InstanceName，并输出当前角色和实例名称日志
• 2.2 将当前 Worker 启动流程整理为共享依赖初始化段，确保 Redis、PostgreSQL、Storage、Gateway、Asynq Client、BootstrapWorker、PollingConfigManager、PollingQueueManager、PollingBase、PollingLifecycleService 对所有角色都可用
• 2.3 为 all/leader 启动 PollingInitializer，并保留配置从空变为非空时触发 Restart(ctx) 的 WatchChanges 逻辑
• 2.4 为 all/leader 创建并启动 PollingScheduler，为 consumer 跳过调度器创建或启动
• 2.5 为 all/leader 创建、注册并启动 Asynq Scheduler，注册现有 order_expire、alert_check、data_cleanup、daily_traffic_flush 定时任务；为 consumer 完全跳过
• 2.6 确保所有角色都创建 Asynq Worker Server、注册全部任务 Handler，并调用 workerServer.Run(taskHandler.GetMux())
• 2.7 启动日志输出已启用模块和已禁用模块，模块名包含 queue_server、polling_initializer、polling_scheduler、asynq_scheduler
• 2.8 调整优雅关闭逻辑：只关闭当前角色实际启动过的 Asynq Scheduler 和 Polling Scheduler，所有角色都关闭 Worker Server
• 2.9 运行 lsp_diagnostics 检查 cmd/worker/main.go 无诊断错误

3. 文档更新

• 3.1 更新 docs/environment-variables.md，新增 JUNHONG_WORKER_ROLE 和 JUNHONG_WORKER_INSTANCE_NAME 说明、默认值和示例
• 3.2 在 docs/environment-variables.md 的 Docker Compose 示例中说明单实例默认 all，多实例推荐 1 leader + N consumer
• 3.3 更新 docs/polling-system/performance-tuning.md 的 Worker 多实例部署段落，明确禁止直接复制完整 worker，推荐扩展 consumer
• 3.4 对更新过的文档执行人工阅读检查，确认无“多个完整 worker 可直接多开”的歧义表述

4. 编译与人工验证

• 4.1 对修改过的 Go 文件执行 gofmt
• 4.2 执行 go build ./cmd/worker，确认 Worker 入口编译通过
• 4.3 执行 go build ./...，确认项目整体编译通过
• 4.4 使用默认配置值检查 all 模式日志预期：应显示启用 queue_server、polling_initializer、polling_scheduler、asynq_scheduler
• 4.5 使用 JUNHONG_WORKER_ROLE=leader 检查日志预期：应显示与 all 相同的启用模块，并体现角色为 leader
• 4.6 使用 JUNHONG_WORKER_ROLE=consumer 检查日志预期：应显示启用 queue_server，禁用 polling_initializer、polling_scheduler、asynq_scheduler
• 4.7 使用非法角色值检查配置校验预期：JUNHONG_WORKER_ROLE=invalid 时启动失败，错误信息明确指向 worker.role
• 4.8 记录未覆盖风险：本期不包含 Redis Leader 锁、自动选主、任务唯一性去重，这些进入第二期增强