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

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

docs/object-storage/前端接入指南.md

@@ -0,0 +1,250 @@
+# 对象存储前端接入指南
+
+## 文件上传流程
+
+```
+前端                      后端 API                    对象存储
+  │                          │                          │
+  │ 1. POST /storage/upload-url                         │
+  │    {file_name, content_type, purpose}               │
+  │ ─────────────────────────►                          │
+  │                          │                          │
+  │ 2. 返回 {upload_url, file_key, expires_in}          │
+  │ ◄─────────────────────────                          │
+  │                          │                          │
+  │ 3. PUT upload_url (文件内容)                        │
+  │ ─────────────────────────────────────────────────► │
+  │                          │                          │
+  │ 4. 上传成功 (200 OK)                                │
+  │ ◄───────────────────────────────────────────────── │
+  │                          │                          │
+  │ 5. POST /iot-cards/import                           │
+  │    {carrier_id, batch_no, file_key}                 │
+  │ ─────────────────────────►                          │
+  │                          │                          │
+  │ 6. 返回任务创建成功                                  │
+  │ ◄─────────────────────────                          │
+```
+
+## 获取预签名 URL 接口
+
+### 请求
+
+```http
+POST /api/admin/storage/upload-url
+Content-Type: application/json
+Authorization: Bearer {token}
+
+{
+  "file_name": "cards.csv",
+  "content_type": "text/csv",
+  "purpose": "iot_import"
+}
+```
+
+### 响应
+
+```json
+{
+  "code": 0,
+  "message": "成功",
+  "data": {
+    "upload_url": "http://obs-helf.cucloud.cn/cmp/imports/2025/01/24/abc123.csv?X-Amz-Algorithm=...",
+    "file_key": "imports/2025/01/24/abc123.csv",
+    "expires_in": 900
+  }
+}
+```
+
+### purpose 可选值
+
+| 值 | 说明 | 生成路径 |
+|---|------|---------|
+| iot_import | ICCID 导入 | imports/YYYY/MM/DD/uuid.csv |
+| export | 数据导出 | exports/YYYY/MM/DD/uuid.xlsx |
+| attachment | 附件上传 | attachments/YYYY/MM/DD/uuid.ext |
+
+## 使用预签名 URL 上传文件
+
+获取到 `upload_url` 后，直接使用 PUT 请求上传文件到对象存储：
+
+```javascript
+const response = await fetch(upload_url, {
+  method: 'PUT',
+  headers: {
+    'Content-Type': content_type
+  },
+  body: file
+});
+
+if (response.ok) {
+  console.log('上传成功');
+} else {
+  console.error('上传失败:', response.status);
+}
+```
+
+## ICCID 导入接口变更（BREAKING CHANGE）
+
+### 变更前
+
+```http
+POST /api/admin/iot-cards/import
+Content-Type: multipart/form-data
+
+carrier_id=1
+batch_no=BATCH-2025-01
+file=@cards.csv
+```
+
+### 变更后
+
+```http
+POST /api/admin/iot-cards/import
+Content-Type: application/json
+Authorization: Bearer {token}
+
+{
+  "carrier_id": 1,
+  "batch_no": "BATCH-2025-01",
+  "file_key": "imports/2025/01/24/abc123.csv"
+}
+```
+
+## 完整代码示例（TypeScript）
+
+```typescript
+interface UploadURLResponse {
+  upload_url: string;
+  file_key: string;
+  expires_in: number;
+}
+
+async function uploadAndImportCards(
+  file: File,
+  carrierId: number,
+  batchNo: string
+): Promise<void> {
+  // 1. 获取预签名上传 URL
+  const urlResponse = await fetch('/api/admin/storage/upload-url', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${getToken()}`
+    },
+    body: JSON.stringify({
+      file_name: file.name,
+      content_type: file.type || 'text/csv',
+      purpose: 'iot_import'
+    })
+  });
+
+  if (!urlResponse.ok) {
+    throw new Error('获取上传 URL 失败');
+  }
+
+  const { data } = await urlResponse.json();
+  const { upload_url, file_key } = data as UploadURLResponse;
+
+  // 2. 上传文件到对象存储
+  const uploadResponse = await fetch(upload_url, {
+    method: 'PUT',
+    headers: {
+      'Content-Type': file.type || 'text/csv'
+    },
+    body: file
+  });
+
+  if (!uploadResponse.ok) {
+    throw new Error('文件上传失败');
+  }
+
+  // 3. 调用导入接口
+  const importResponse = await fetch('/api/admin/iot-cards/import', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${getToken()}`
+    },
+    body: JSON.stringify({
+      carrier_id: carrierId,
+      batch_no: batchNo,
+      file_key: file_key
+    })
+  });
+
+  if (!importResponse.ok) {
+    throw new Error('导入任务创建失败');
+  }
+
+  console.log('导入任务已创建');
+}
+```
+
+## 错误处理和重试策略
+
+### 预签名 URL 过期
+
+预签名 URL 有效期为 15 分钟。如果上传时 URL 已过期，需要重新获取：
+
+```typescript
+async function uploadWithRetry(file: File, purpose: string, maxRetries = 3) {
+  for (let i = 0; i < maxRetries; i++) {
+    const { upload_url, file_key } = await getUploadURL(file.name, file.type, purpose);
+    
+    try {
+      await uploadFile(upload_url, file);
+      return file_key;
+    } catch (error) {
+      if (i === maxRetries - 1) throw error;
+      console.warn(`上传失败，重试 ${i + 1}/${maxRetries}`);
+    }
+  }
+}
+```
+
+### 网络错误
+
+对象存储上传可能因网络问题失败，建议实现重试机制：
+
+```typescript
+async function uploadFile(url: string, file: File, retries = 3) {
+  for (let i = 0; i < retries; i++) {
+    try {
+      const response = await fetch(url, {
+        method: 'PUT',
+        headers: { 'Content-Type': file.type },
+        body: file
+      });
+      
+      if (response.ok) return;
+      
+      if (response.status >= 500) {
+        // 服务端错误，可重试
+        continue;
+      }
+      
+      throw new Error(`上传失败: ${response.status}`);
+    } catch (error) {
+      if (i === retries - 1) throw error;
+      await new Promise(r => setTimeout(r, 1000 * (i + 1)));
+    }
+  }
+}
+```
+
+## 常见问题
+
+### Q: 上传时报 CORS 错误
+
+确保对象存储已配置 CORS 规则允许前端域名访问。
+
+### Q: 预签名 URL 无法使用
+
+1. 检查 URL 是否过期（15 分钟有效期）
+2. 确保 Content-Type 与获取 URL 时指定的一致
+3. 检查文件大小是否超过限制
+
+### Q: file_key 可以重复使用吗
+
+可以。file_key 一旦上传成功就永久有效，可以在多个业务接口中使用同一个 file_key。