junhong_cmp_fiber/openspec/specs/embedded-config/spec.md

embedded-config Specification

Purpose

TBD - created by archiving change deployment-self-init. Update Purpose after archive.

Requirements

Requirement: 配置嵌入

系统 SHALL 使用 Go 的 go:embed 指令将默认配置文件嵌入二进制文件。

嵌入文件位置：pkg/config/defaults/config.yaml

Scenario: 加载嵌入配置

• WHEN 调用 config.Load()
• THEN 系统从嵌入的 defaults/config.yaml 读取默认配置
• AND 无需外部配置文件即可启动

Scenario: 嵌入配置包含完整结构

• WHEN 读取嵌入配置
• THEN 配置包含所有配置节：server、database、redis、storage、logging、queue、jwt、middleware、worker

Requirement: 环境变量覆盖

系统 SHALL 支持通过环境变量覆盖嵌入的默认配置值。

环境变量格式：JUNHONG_{SECTION}_{KEY}

Scenario: 环境变量覆盖配置

• WHEN 设置环境变量 JUNHONG_DATABASE_HOST=myhost
• THEN config.Database.Host 的值为 "myhost"
• AND 覆盖嵌入配置中的默认值

Scenario: 嵌套配置覆盖

• WHEN 设置环境变量 JUNHONG_LOGGING_LEVEL=debug
• THEN config.Logging.Level 的值为 "debug"

Scenario: 未设置环境变量

• WHEN 未设置某个配置的环境变量
• THEN 使用嵌入配置中的默认值

Requirement: Worker 运行配置

系统 SHALL 在嵌入默认配置中提供 worker 配置节，并支持通过 JUNHONG_WORKER_ROLE 和 JUNHONG_WORKER_INSTANCE_NAME 环境变量覆盖。

默认配置：

• worker.role: all
• worker.instance_name: 空字符串

Scenario: 默认 Worker 角色

• WHEN 未设置 JUNHONG_WORKER_ROLE
• THEN config.Load() 返回的 Config.Worker.Role 为 all

Scenario: 环境变量覆盖 Worker 角色

• WHEN 设置环境变量 JUNHONG_WORKER_ROLE=consumer
• THEN config.Load() 返回的 Config.Worker.Role 为 consumer

Scenario: 环境变量覆盖实例名称

• WHEN 设置环境变量 JUNHONG_WORKER_INSTANCE_NAME=worker-consumer-1
• THEN config.Load() 返回的 Config.Worker.InstanceName 为 worker-consumer-1

Scenario: Worker 角色参与配置校验

• WHEN 设置环境变量 JUNHONG_WORKER_ROLE=invalid
• THEN config.Load() 返回错误
• AND 错误信息明确指出 worker.role 只允许 all、leader、consumer

Requirement: 配置优先级

系统 SHALL 按以下优先级应用配置（高到低）：

1. 环境变量 (JUNHONG_*)
2. 嵌入默认值 (go:embed)

Scenario: 优先级验证

• WHEN 嵌入配置中 server.address 为 ":3000"
• AND 设置环境变量 JUNHONG_SERVER_ADDRESS=:8080
• THEN 最终 config.Server.Address 为 ":8080"

Requirement: 必填配置验证

系统 SHALL 在加载配置后验证必填配置项是否已设置。

必填配置项：

• database.host
• database.user
• database.password
• database.dbname
• redis.address
• jwt.secret_key

Scenario: 必填配置缺失

• WHEN 必填配置项为空且未通过环境变量设置
• THEN config.Load() 返回错误
• AND 错误信息明确指出缺失的配置项和对应的环境变量名

Scenario: 必填配置通过环境变量提供

• WHEN 所有必填配置通过环境变量设置
• THEN config.Load() 成功返回配置

Requirement: 删除外部配置文件支持

系统 SHALL 移除对外部配置文件的支持。

Scenario: 不读取 configs 目录

• WHEN 应用启动
• THEN 不读取 configs/*.yaml 文件
• AND 不依赖 CONFIG_PATH 或 CONFIG_ENV 环境变量

Requirement: 删除配置热重载

系统 SHALL 移除配置热重载功能。

Scenario: 不监听配置文件变化

• WHEN 应用运行中
• THEN 不使用 fsnotify 监听文件变化
• AND 删除 pkg/config/watcher.go

Scenario: 配置变更需重启

• WHEN 需要更改配置
• THEN 必须重启应用使新配置生效

Requirement: 环境变量前缀

系统 SHALL 使用 JUNHONG_ 作为环境变量前缀。

Scenario: 前缀隔离

• WHEN 存在环境变量 DATABASE_HOST=other
• AND 存在环境变量 JUNHONG_DATABASE_HOST=correct
• THEN config.Database.Host 为 "correct"
• AND 忽略无前缀的 DATABASE_HOST

Requirement: 敏感配置处理

系统 SHALL 确保敏感配置不嵌入二进制文件。

敏感配置项（嵌入值为空）：

• database.password
• redis.password
• jwt.secret_key
• storage.s3.access_key_id
• storage.s3.secret_access_key

Scenario: 敏感配置默认为空

• WHEN 读取嵌入配置
• THEN 敏感配置项的值为空字符串
• AND 必须通过环境变量提供实际值