feat: 添加环境变量管理工具和部署配置改版
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 5m33s

主要改动:
- 新增交互式环境配置脚本 (scripts/setup-env.sh)
- 新增本地启动快捷脚本 (scripts/run-local.sh)
- 新增环境变量模板文件 (.env.example)
- 部署模式改版:使用嵌入式配置 + 环境变量覆盖
- 添加对象存储功能支持
- 改进 IoT 卡片导入任务
- 优化 OpenAPI 文档生成
- 删除旧的配置文件,改用嵌入式默认配置
This commit is contained in:
2026-01-26 10:28:29 +08:00
parent 194078674a
commit 45aa7deb87
94 changed files with 6532 additions and 1967 deletions

View File

@@ -151,6 +151,34 @@ Handler → Service → Store → Model
- 使用 table-driven tests
- 单元测试 < 100ms集成测试 < 1s
### ⚠️ 测试真实性原则(严格遵守)
**测试必须真正验证功能,禁止绕过核心逻辑:**
| 规则 | 说明 |
|------|------|
| ❌ 禁止传递 nil 绕过依赖 | 如果功能依赖外部服务(如对象存储、第三方 API测试必须验证该依赖的调用 |
| ❌ 禁止只测试部分流程 | 如果功能包含 A → B → C 三步,不能只测试 B 而跳过 A 和 C |
| ❌ 禁止声称"测试通过"但未验证核心逻辑 | 测试通过必须意味着功能真正可用 |
| ❌ 禁止擅自使用 Mock | 尽量使用真实服务进行集成测试,如需使用 Mock 必须先询问用户并获得同意 |
| ✅ 必须验证端到端流程 | 新增功能必须有完整的集成测试覆盖整个调用链 |
| ✅ 缺少配置时必须询问 | 如果测试需要的配置(如 API Key、环境变量缺失必须询问用户而非跳过测试 |
**反面案例**
```go
// ❌ 错误:传递 nil 绕过 storageService只测试了 processImport
handler := NewIotCardImportHandler(db, redis, store1, store2, nil, logger)
result := handler.processImport(ctx, task) // 跳过了 downloadAndParseCSV
// ✅ 正确:使用真实服务测试完整流程
handler := NewIotCardImportHandler(db, redis, store1, store2, realStorageService, logger)
handler.HandleIotCardImport(ctx, asynqTask) // 测试完整流程,验证真实上传/下载
```
**测试超时 = 生产超时**
- 集成测试超时意味着生产环境也可能超时
- 发现超时必须排查原因,不能简单跳过或增加超时时间
### 测试连接管理(必读)
**详细规范**: [docs/testing/test-connection-guide.md](docs/testing/test-connection-guide.md)
@@ -217,4 +245,20 @@ func TestXxx(t *testing.T) {
8. ✅ 文档更新计划
9. ✅ 中文优先
### ⚠️ 任务执行规范(必须遵守)
**提案中的 tasks.md 是契约,不可擅自变更:**
| 规则 | 说明 |
|------|------|
| ❌ 禁止跳过任务 | 每个任务都是经过规划的,不能因为"简单"或"显而易见"而跳过 |
| ❌ 禁止简化任务 | 不能将多个任务合并或简化执行,除非获得明确许可 |
| ❌ 禁止自作主张优化 | 发现可以优化的地方,必须先询问是否可以调整 |
| ✅ 必须逐项完成 | 按照 tasks.md 中的顺序逐一执行并标记完成 |
| ✅ 必须询问后变更 | 如需调整任务(简化/跳过/合并/优化),先询问用户确认 |
**询问示例**
> "我注意到任务 2.1 和 2.2 可以合并为一步完成,是否可以这样优化?"
> "任务 3.1 在当前实现中可能不需要,是否可以跳过?"
**详细规范和 OpenSpec 工作流请查看**: `@/openspec/AGENTS.md`