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

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

openspec/changes/archive/2026-01-24-add-openapi-markdown-description/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-01-24

openspec/changes/archive/2026-01-24-add-openapi-markdown-description/design.md

@@ -0,0 +1,114 @@
+## Context
+
+当前项目使用 `github.com/swaggest/openapi-go/openapi3` 库生成 OpenAPI 3.0.3 规范文档。路由注册通过 `RouteSpec` 结构体传递元数据，但目前只支持 `Summary` 字段作为接口的简短描述。
+
+OpenAPI 规范的 Operation 对象包含两个描述字段：
+- `summary`: 简短摘要（通常一行）
+- `description`: 详细说明，**支持 CommonMark Markdown 语法**
+
+swaggest 库的 `openapi3.Operation` 结构体已包含 `Description *string` 字段，只需在代码中设置即可。
+
+## Goals / Non-Goals
+
+**Goals:**
+- 在 `RouteSpec` 中新增 `Description` 字段
+- 支持在接口文档中添加 Markdown 格式的详细说明
+- 保持向后兼容，Description 为可选字段
+- 更新 API 文档规范
+
+**Non-Goals:**
+- 不修改 DTO 字段的 description 标签处理逻辑
+- 不修改现有路由注册代码（新字段可选）
+- 不扩展其他 OpenAPI 字段（如 externalDocs、deprecated 等）
+
+## Decisions
+
+### 决策 1: Description 字段类型
+
+**选择**: 使用 `string` 类型
+
+**原因**:
+- 与 `Summary` 字段保持一致
+- 空字符串表示无描述，语义清晰
+- 避免指针类型带来的 nil 检查复杂度
+
+**备选方案**:
+- `*string` 指针类型 - 增加使用复杂度，无实际收益
+
+### 决策 2: 函数签名变更策略
+
+**选择**: 不修改 `AddOperation` 函数签名，通过 `RouteSpec.Description` 传递
+
+**原因**:
+- 保持 API 稳定性
+- `Register` 函数已封装了 `RouteSpec`，只需从中提取 Description
+- 避免破坏性变更
+
+**备选方案**:
+- 修改 `AddOperation` 增加 description 参数 - 需要修改所有调用点，不必要
+
+### 决策 3: 空值处理
+
+**选择**: 空字符串时不设置 OpenAPI 的 description 字段
+
+**原因**:
+- 生成更简洁的 YAML
+- 与 swaggest 库的 omitempty 行为一致
+- 保持现有生成文件格式不变
+
+## Risks / Trade-offs
+
+**[风险] Markdown 语法在不同工具中渲染差异**
+→ 缓解: 建议使用 CommonMark 基础语法（标题、列表、表格、代码块），避免扩展语法
+
+**[风险] 过长的 Description 影响文档可读性**
+→ 缓解: 在规范文档中建议控制长度，复杂说明可使用折叠或链接到外部文档
+
+**[权衡] 不修改函数签名 vs 显式参数**
+→ 选择封装在 RouteSpec 中，牺牲一定的显式性换取稳定性
+
+## 实现方案
+
+### 文件变更清单
+
+1. **`internal/routes/registry.go`**
+   - RouteSpec 新增 Description 字段
+
+2. **`pkg/openapi/generator.go`**
+   - AddOperation: 设置 op.Description
+   - AddMultipartOperation: 设置 op.Description
+
+3. **`docs/api-documentation-guide.md`**
+   - 新增 Description 字段使用说明
+   - 补充 Markdown 语法示例
+
+### 代码变更示例
+
+```go
+// internal/routes/registry.go
+type RouteSpec struct {
+    Summary     string            // 简短摘要
+    Description string            // 详细说明，支持 Markdown
+    Input       interface{}
+    Output      interface{}
+    Tags        []string
+    Auth        bool
+    FileUploads []FileUploadField
+}
+```
+
+```go
+// pkg/openapi/generator.go - AddOperation
+func (g *Generator) AddOperation(...) {
+    op := openapi3.Operation{
+        Summary: &summary,
+        Tags:    tags,
+    }
+    
+    // 新增: 设置 Description
+    if description != "" {
+        op.Description = &description
+    }
+    // ...
+}
+```

openspec/changes/archive/2026-01-24-add-openapi-markdown-description/proposal.md

@@ -0,0 +1,36 @@
+## Why
+
+当前项目的 OpenAPI 文档生成模块只支持通过 `RouteSpec.Summary` 设置接口的简短摘要，无法添加详细的 Markdown 格式说明。前端团队使用 Apifox 查看 API 文档时，需要在某些接口上看到更详细的使用说明、注意事项、业务规则等信息。
+
+OpenAPI 规范的 Operation 对象支持 `description` 字段，且该字段明确支持 **CommonMark** Markdown 语法。Apifox 作为 OpenAPI 工具，能够正确渲染这些 Markdown 内容。因此需要扩展当前的文档生成模块以支持此功能。
+
+## What Changes
+
+- 在 `RouteSpec` 结构体中新增 `Description` 字段，用于设置接口的详细 Markdown 说明
+- 修改 `pkg/openapi/generator.go` 中的 `AddOperation` 和 `AddMultipartOperation` 方法，将 Description 写入 OpenAPI 规范
+- 更新 `internal/routes/registry.go` 中的 `Register` 函数以传递 Description 参数
+- 更新 API 文档规范，说明 Description 字段的使用方法和 Markdown 语法支持
+
+## Capabilities
+
+### New Capabilities
+
+- `openapi-markdown-description`: 支持在 OpenAPI 接口文档中添加 Markdown 格式的详细描述，包括表格、列表、代码块等富文本内容
+
+### Modified Capabilities
+
+<!-- 无现有能力需要修改，这是纯新增功能 -->
+
+## Impact
+
+**受影响的代码**:
+- `internal/routes/registry.go` - RouteSpec 结构体定义和 Register 函数
+- `pkg/openapi/generator.go` - AddOperation 和 AddMultipartOperation 方法
+
+**受影响的文档**:
+- `docs/api-documentation-guide.md` - 需要补充 Description 字段使用说明
+
+**不受影响**:
+- 所有现有路由注册代码（Description 字段为可选，空值时行为与当前一致）
+- 生成的 OpenAPI 文件格式（符合 OpenAPI 3.0.3 规范）
+- Apifox 导入流程（无需任何配置变更）

openspec/changes/archive/2026-01-24-add-openapi-markdown-description/specs/openapi-markdown-description/spec.md

@@ -0,0 +1,56 @@
+## ADDED Requirements
+
+### Requirement: RouteSpec 支持 Description 字段
+
+RouteSpec 结构体 SHALL 包含 `Description` 字段，类型为 `string`，用于设置接口的详细 Markdown 说明。
+
+#### Scenario: Description 字段为空时不影响生成
+
+- **WHEN** RouteSpec.Description 为空字符串
+- **THEN** 生成的 OpenAPI 规范中该接口不包含 description 字段
+
+#### Scenario: Description 字段有内容时写入 OpenAPI
+
+- **WHEN** RouteSpec.Description 包含非空内容
+- **THEN** 生成的 OpenAPI 规范中该接口的 description 字段包含该内容
+
+### Requirement: Description 支持 Markdown 语法
+
+生成器 SHALL 原样保留 Description 字段的 Markdown 内容，不进行转义或处理，以便 OpenAPI 工具（如 Apifox）正确渲染。
+
+#### Scenario: 支持基础 Markdown 格式
+
+- **WHEN** Description 包含 Markdown 标题、列表、表格、代码块
+- **THEN** 生成的 OpenAPI YAML 文件中保留完整的 Markdown 格式
+
+#### Scenario: 支持多行内容
+
+- **WHEN** Description 包含多行文本
+- **THEN** 生成的 OpenAPI YAML 文件使用 YAML 多行字符串格式正确表示
+
+### Requirement: AddOperation 方法处理 Description
+
+AddOperation 方法 SHALL 接受 description 参数并设置到 openapi3.Operation.Description 字段。
+
+#### Scenario: 普通接口设置 Description
+
+- **WHEN** 调用 AddOperation 且 description 参数非空
+- **THEN** 生成的 Operation 对象包含 Description 字段
+
+### Requirement: AddMultipartOperation 方法处理 Description
+
+AddMultipartOperation 方法 SHALL 与 AddOperation 一致，支持 description 参数。
+
+#### Scenario: 文件上传接口设置 Description
+
+- **WHEN** 调用 AddMultipartOperation 且 description 参数非空
+- **THEN** 生成的 multipart/form-data 接口包含 Description 字段
+
+### Requirement: Register 函数传递 Description
+
+Register 函数 SHALL 从 RouteSpec 中提取 Description 字段并传递给文档生成器。
+
+#### Scenario: Register 调用时传递 Description
+
+- **WHEN** 调用 Register 函数注册路由
+- **THEN** RouteSpec.Description 被传递到对应的 AddOperation 或 AddMultipartOperation 调用

openspec/changes/archive/2026-01-24-add-openapi-markdown-description/tasks.md

@@ -0,0 +1,24 @@
+## 1. RouteSpec 结构体扩展
+
+- [x] 1.1 在 `internal/routes/registry.go` 的 RouteSpec 结构体中新增 Description 字段
+
+## 2. OpenAPI 生成器修改
+
+- [x] 2.1 修改 `pkg/openapi/generator.go` 的 AddOperation 方法签名，增加 description 参数
+- [x] 2.2 在 AddOperation 方法中设置 op.Description 字段
+- [x] 2.3 修改 AddMultipartOperation 方法签名，增加 description 参数
+- [x] 2.4 在 AddMultipartOperation 方法中设置 op.Description 字段
+
+## 3. Register 函数更新
+
+- [x] 3.1 更新 `internal/routes/registry.go` 的 Register 函数，传递 spec.Description 给生成器
+
+## 4. 文档更新
+
+- [x] 4.1 更新 `docs/api-documentation-guide.md`，新增 Description 字段使用说明
+- [x] 4.2 补充 Markdown 语法示例和最佳实践
+
+## 5. 验证
+
+- [x] 5.1 运行 `go run cmd/gendocs/main.go` 验证文档生成正常
+- [x] 5.2 检查生成的 YAML 文件格式正确