feat: 添加环境变量管理工具和部署配置改版

主要改动：
- 新增交互式环境配置脚本 (scripts/setup-env.sh)
- 新增本地启动快捷脚本 (scripts/run-local.sh)
- 新增环境变量模板文件 (.env.example)
- 部署模式改版：使用嵌入式配置 + 环境变量覆盖
- 添加对象存储功能支持
- 改进 IoT 卡片导入任务
- 优化 OpenAPI 文档生成
- 删除旧的配置文件，改用嵌入式默认配置

openspec/changes/archive/2026-01-24-add-object-storage/proposal.md

@@ -0,0 +1,97 @@
+# 通用对象存储能力
+
+## Why
+
+当前 ICCID 导入功能通过后端接收上传文件，占用服务器带宽和内存，大文件处理效率低。同时，未来的导出功能也需要文件存储能力。需要接入联通云对象存储（S3 兼容），采用预签名 URL 方案实现前端直传，提升性能和安全性。
+
+此外，本项目作为公司后端模板项目，对象存储应设计为通用能力，方便复用到其他系统。
+
+## What Changes
+
+- **新增通用对象存储包**：`pkg/storage/` 提供 S3 兼容的对象存储能力
+  - 支持上传、下载、删除、检查存在性
+  - 支持生成预签名上传/下载 URL
+  - 可扩展支持多云（阿里云、腾讯云等，仅需更换 Endpoint）
+
+- **新增存储 API 接口**：供前端获取预签名上传 URL
+  - `POST /api/admin/storage/upload-url`：获取上传预签名 URL
+
+- **改造 ICCID 导入流程**：
+  - 移除原有的文件上传处理（`c.FormFile`）
+  - 改为接收 `file_key` 参数（对象存储路径）
+  - Worker 从对象存储下载文件后处理
+  - 处理完成后删除本地临时文件
+
+- **数据模型变更**：
+  - `IotCardImportTask` 新增 `storage_bucket`、`storage_key` 字段
+  - 需要数据库迁移
+
+- **配置结构扩展**：
+  - 新增 `storage` 配置块（endpoint、region、bucket、credentials）
+
+## Capabilities
+
+### New Capabilities
+
+- `object-storage`: 通用对象存储能力，提供 S3 兼容的文件上传、下载、删除、预签名 URL 生成功能
+
+### Modified Capabilities
+
+- `iot-card-import`: ICCID 导入流程改造，从直接上传改为对象存储集成
+
+## Impact
+
+### 代码变更
+
+| 层级 | 变更内容 |
+|------|----------|
+| `pkg/storage/` | 新增：Provider 接口、S3 实现、配置类型 |
+| `pkg/config/` | 修改：新增 StorageConfig 结构 |
+| `configs/` | 修改：新增 storage 配置块 |
+| `internal/bootstrap/` | 修改：初始化 Storage Provider |
+| `internal/handler/admin/` | 新增：StorageHandler（获取上传 URL）|
+| `internal/handler/admin/` | 修改：IotCardImportHandler（移除文件上传）|
+| `internal/service/iot_card_import/` | 修改：接收 file_key 而非文件流 |
+| `internal/task/` | 修改：从对象存储下载文件处理 |
+| `internal/model/` | 修改：IotCardImportTask 新增字段 |
+| `internal/routes/` | 修改：新增 storage 路由 |
+| `migrations/` | 新增：添加 storage 字段迁移 |
+
+### API 变更
+
+| 接口 | 变更类型 | 说明 |
+|------|----------|------|
+| `POST /api/admin/storage/upload-url` | 新增 | 获取预签名上传 URL |
+| `POST /api/admin/iot-cards/import` | **BREAKING** | 移除文件上传，改为传 file_key |
+
+### 依赖变更
+
+| 依赖 | 说明 |
+|------|------|
+| `github.com/aws/aws-sdk-go` | 新增：AWS S3 兼容 SDK（已验证联通云支持） |
+
+### 配置变更
+
+```yaml
+storage:
+  provider: "s3"
+  s3:
+    endpoint: "http://obs-helf.cucloud.cn"
+    region: "cn-langfang-2"
+    bucket: "cmp"
+    access_key_id: "${OSS_ACCESS_KEY_ID}"
+    secret_access_key: "${OSS_SECRET_ACCESS_KEY}"
+    use_ssl: false
+    path_style: true
+  presign:
+    upload_expires: "15m"    # 上传预签名有效期
+    download_expires: "24h"  # 下载预签名有效期
+  temp_dir: "/tmp/junhong-storage"  # 临时文件目录
+```
+
+### 前端适配
+
+前端需要配合修改上传流程：
+1. 先调用 `POST /api/admin/storage/upload-url` 获取预签名 URL
+2. 直接 PUT 到预签名 URL 上传文件
+3. 上传成功后调用导入接口，传入 `file_key`