浅浅升级一下

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

@@ -0,0 +1,63 @@
+## Why
+
+当前 `cmd/worker` 同时承担 Asynq 任务消费、轮询初始化、轮询调度、套餐激活/流量重置扫描和 Asynq 定时任务调度职责，导致完整 worker 进程不能安全横向复制。为了支持后续多实例扩容，同时避免重复扫库、重复调度和重复入队，本变更先引入显式 Worker 角色，将“可多开的消费职责”和“必须单例的主动调度职责”拆开。
+
+## What Changes
+
+- 新增 Worker 运行角色配置：
+  - `all`：兼容当前单实例行为，启动全部模块
+  - `leader`：明确承担单例职责，启动全部模块
+  - `consumer`：只启动 Asynq Worker Server 和任务处理依赖，不启动任何主动调度/初始化模块
+- 新增实例名称配置 `JUNHONG_WORKER_INSTANCE_NAME`，用于日志区分多实例。
+- 修改 `cmd/worker/main.go` 启动流程，将共享依赖初始化和按角色启停模块分离。
+- `consumer` 仍注册全部任务 Handler，确保可以消费轮询任务、套餐激活任务、订单超时任务、告警任务、数据清理任务等已有 Asynq 任务。
+- 启动日志明确打印当前角色、实例名、启用模块和禁用模块，便于部署验证和排障。
+- 保持默认 `all`，不修改现有部署配置时行为完全不变。
+- 不引入自动选主、Redis Leader 锁或任务唯一性去重；这些作为第二期增强，不纳入本次最小改造。
+
+## Capabilities
+
+### New Capabilities
+
+- `worker-role-management`：定义 Worker 运行角色、按角色启停模块、兼容模式、消费者扩容语义和启动日志要求。
+
+### Modified Capabilities
+
+- `embedded-config`：新增 `worker.role`、`worker.instance_name` 默认配置和环境变量覆盖要求。
+
+## Impact
+
+**功能 ID**：`feature-worker-role-split`
+
+**涉及文件**：
+- `cmd/worker/main.go`：按角色控制 `PollingInitializer`、`PollingScheduler`、`Asynq Scheduler` 启停
+- `pkg/config/config.go`：新增 Worker 配置结构和角色校验
+- `pkg/config/defaults/config.yaml`：新增默认 worker 配置节
+- `pkg/config/loader.go`：绑定 `worker.role`、`worker.instance_name`
+- `docs/environment-variables.md`：补充 Worker 角色环境变量和部署说明
+
+**技术栈合规性**：
+- 配置继续使用 Viper 加载和环境变量覆盖
+- 日志继续使用 Zap 输出中文日志
+- 异步任务继续使用 Asynq，不新增队列依赖
+- 不涉及 Fiber Handler、GORM Store、数据库迁移或 DTO 变更
+
+**架构分层**：
+- 本变更属于进程编排和配置层改造，不新增业务 Handler/Service/Store/Model
+- 已有任务处理链路保持不变，仍由 Asynq Worker Server 分发到 `pkg/queue` 注册的 Handler
+
+**验证计划**：
+- 按项目根规范，本变更不新增自动化测试或 `*_test.go` 文件
+- 使用 `go build ./cmd/worker` 验证 worker 入口编译通过
+- 使用 `go build ./...` 验证项目整体编译通过
+- 人工以 `all`、`leader`、`consumer` 三种配置启动/观察日志，确认模块启停符合角色语义
+- 人工检查 `consumer` 日志不出现“轮询调度器已启动”和“Asynq Scheduler 已启动”
+
+**性能影响**：
+- 单实例默认 `all` 行为不变，无额外运行时开销
+- `consumer` 不运行初始化器和调度器，可降低多实例场景下重复 DB/Redis 压力
+- 多实例阶段应优先扩展 `consumer`，不要复制 `leader`
+
+**兼容性与回滚**：
+- 默认值为 `all`，旧部署无需新增环境变量即可保持当前行为
+- 如上线后有问题，可停止所有 `consumer`，保留单个 `leader`；必要时将唯一实例切回 `all`