# worker-role-management Specification

## Purpose
TBD - created by archiving change split-worker-roles. Update Purpose after archive.

## Requirements

### Requirement: Worker 角色配置

系统 SHALL 支持 `all`、`leader`、`consumer` 三种 Worker 运行角色，并在启动时根据配置决定当前进程职责。角色值 MUST 使用小写英文字符串，非法角色 MUST 使配置加载失败并返回明确错误。

#### Scenario: 默认兼容模式
- **WHEN** 未设置 `JUNHONG_WORKER_ROLE`
- **THEN** Worker 使用默认角色 `all`
- **AND** 启动行为与变更前单实例 worker 保持一致

#### Scenario: 非法角色启动失败
- **WHEN** 设置 `JUNHONG_WORKER_ROLE=scheduler`
- **THEN** `config.Load()` 返回配置校验错误
- **AND** Worker 不进入 Redis、PostgreSQL 或 Asynq 启动流程

#### Scenario: 实例名称可为空
- **WHEN** 未设置 `JUNHONG_WORKER_INSTANCE_NAME`
- **THEN** Worker 可以正常启动
- **AND** 启动日志中的实例名称为空或显示默认占位值

### Requirement: 按角色启停 Worker 模块

系统 SHALL 将 Worker 启动流程拆分为共享依赖初始化和角色模块启停两部分。所有角色 MUST 启动 Asynq Worker Server；只有 `all` 和 `leader` SHALL 启动主动调度与初始化模块。

**共享模块**：
- Redis 客户端
- PostgreSQL 连接
- Storage 服务（可选）
- Gateway 客户端（可选）
- Asynq Client
- `BootstrapWorker`
- Asynq Worker Server
- `PollingConfigManager`
- `PollingQueueManager`
- `PollingBase`
- `PollingLifecycleService`
- TaskHandler 及全部任务 Handler 注册

**单例模块**：
- `PollingInitializer`
- `PollingScheduler`
- Asynq Scheduler

#### Scenario: all 角色启动全部模块
- **WHEN** `worker.role=all`
- **THEN** Worker 启动 Asynq Worker Server
- **AND** 启动 `PollingInitializer`
- **AND** 启动 `PollingScheduler`
- **AND** 启动 Asynq Scheduler

#### Scenario: leader 角色启动全部模块
- **WHEN** `worker.role=leader`
- **THEN** Worker 启动 Asynq Worker Server
- **AND** 启动 `PollingInitializer`
- **AND** 启动 `PollingScheduler`
- **AND** 启动 Asynq Scheduler
- **AND** 日志表达该实例承担单例主动调度职责

#### Scenario: consumer 角色只启动任务消费模块
- **WHEN** `worker.role=consumer`
- **THEN** Worker 启动 Asynq Worker Server
- **AND** 注册全部任务 Handler
- **AND** 不启动 `PollingInitializer`
- **AND** 不启动 `PollingScheduler`
- **AND** 不启动 Asynq Scheduler

### Requirement: consumer 保留轮询任务运行依赖

`consumer` 角色虽然不主动调度，但系统 SHALL 保留轮询任务 Handler 所需依赖，使其可以正常消费 Leader 投递的轮询任务并在任务完成后重新入队。

#### Scenario: consumer 消费轮询任务后可重新入队
- **WHEN** `consumer` 实例消费 `TaskTypePollingCarddata` 任务
- **THEN** Handler 可通过 `PollingBase` 读取轮询配置和 Redis 并发控制
- **AND** Handler 可通过 `PollingQueueManager` 将卡重新写回分片 Sorted Set

#### Scenario: consumer 可处理导入任务的轮询生命周期回调
- **WHEN** `consumer` 实例消费 IoT 卡导入任务并创建新卡
- **THEN** 导入任务可通过 `PollingLifecycleService` 将新卡按配置加入轮询分片队列
- **AND** 该操作不依赖本实例启动 `PollingScheduler`

### Requirement: Worker 启动日志

系统 SHALL 在 Worker 启动时输出当前角色、实例名称、启用模块和禁用模块，日志消息 MUST 使用中文，便于部署后通过日志确认实际运行职责。

#### Scenario: consumer 日志显示禁用单例模块
- **WHEN** `worker.role=consumer`
- **THEN** 启动日志包含 `Worker 角色`
- **AND** 启动日志包含 `实例名称`
- **AND** 启动日志显示已禁用 `polling_initializer`、`polling_scheduler`、`asynq_scheduler`

#### Scenario: leader 日志显示启用单例模块
- **WHEN** `worker.role=leader`
- **THEN** 启动日志显示已启用 `queue_server`、`polling_initializer`、`polling_scheduler`、`asynq_scheduler`

### Requirement: 按启动状态优雅关闭

系统 SHALL 只关闭当前角色实际启动过的后台模块，避免 `consumer` 对未启动模块执行 `Stop` 或 `Shutdown`。

#### Scenario: consumer 关闭不访问未启动调度器
- **WHEN** `consumer` 收到退出信号
- **THEN** Worker 关闭 Asynq Worker Server
- **AND** 不调用未启动的 `PollingScheduler.Stop`
- **AND** 不调用未启动的 Asynq Scheduler `Shutdown`

#### Scenario: leader 关闭全部已启动模块
- **WHEN** `leader` 收到退出信号
- **THEN** Worker 关闭 Asynq Scheduler
- **AND** 停止 `PollingScheduler`
- **AND** 优雅关闭 Asynq Worker Server

### Requirement: 多实例部署语义

系统 SHALL 支持“1 个 `leader` + N 个 `consumer`”的部署形态。部署时 SHOULD 固定只有一个 `leader` 或 `all` 实例承担主动调度职责，横向扩容 SHALL 优先增加 `consumer`。

#### Scenario: 新增 consumer 不复制主动调度
- **WHEN** 生产已有一个 `leader`，再新增一个 `consumer`
- **THEN** 定时任务仍只由 `leader` 主动提交
- **AND** 轮询全量初始化仍只由 `leader` 执行
- **AND** `consumer` 只从 Asynq 队列消费已有任务

#### Scenario: 回滚到单实例兼容模式
- **WHEN** 多实例部署出现问题并停止所有 `consumer`
- **THEN** 保留一个 `leader` 可继续运行完整 Worker 功能
- **AND** 必要时可将唯一实例配置切回 `all` 恢复兼容模式