# 工程需求

## 技术基线

- MQ 固定为 RocketMQ 5.x，当前本机镜像版本为 `apache/rocketmq:5.3.2`。
- 业务模块只依赖 `MessageBusAdapter` 与版本化事件，不直接引用客户端 SDK 类型。
- Scheduler 只发布任务，Worker 只消费执行；重复投递由幂等键和业务唯一约束处理。

## 配置契约

- Scheduler 使用 `ROCKETMQ_ENABLED`、`ROCKETMQ_NAMESRV_ADDR`、`ROCKETMQ_ENDPOINT`、`ROCKETMQ_TOPIC_PREFIX` 和发送超时。RocketMQ 5.x Proxy 官方 Node Producer 不要求 Producer Group，禁止把旧 Remoting 参数混入配置。
- Worker 使用相同的基础连接字段，并增加 `ROCKETMQ_CONSUMER_GROUP` 和客户端消费并发。
- 开发和生产模板的同一进程必须保持相同键集合；生产连接地址留空且不得提交真实值。
- `ROCKETMQ_ENABLED=false` 时不建立连接；启用后 Endpoint、Topic 和对应 Group 必须通过启动配置 Schema 校验。

## 消息语义

- 事件必须包含 `eventId`、`eventType`、`schemaVersion`、`occurredAt`、`tradeDate`、`traceId` 和 `idempotencyKey`。
- Topic 表达稳定业务域，Tag 表达事件类型，Consumer Group 表达独立消费进度。
- 需要顺序处理时必须声明消息组键；普通消息不保证全局顺序。
- 超过最大消费次数后进入死信，必须支持查询、告警和受控重放。
- 最大投递次数属于 RocketMQ 服务端 Consumer Group 重试策略，由运维配置并纳入部署验收，不作为官方 Node PushConsumer 的客户端环境变量。

## 本机验证

- 检查容器、镜像、端口映射和 NameServer 启动日志。
- 使用 TCP 探针验证 `127.0.0.1:9876`。
- 检查 Docker 容器和本机原生进程，避免把相同端口的其他监听者误判为目标容器。
- 通过 `mqadmin clusterList`、`topicList`、`brokerStatus` 确认 Broker 注册、版本和管理链路；不擅自创建 Topic 或写入测试消息。