EmailBill/.doc/ICONIFY_DEPLOYMENT_CHECKLIST.md

Iconify 图标集成 - 部署清单

版本: v1.0.0
日期: 2026-02-16

部署前检查

1. 代码完整性

• 所有代码已提交到版本控制
• 所有测试通过（130/130 测试用例）
• 代码已通过 code review

2. 配置检查

• appsettings.json 包含 Iconify 配置
• AI API 配置正确（用于关键字生成）
• 数据库连接字符串正确

3. 数据库准备

• TransactionCategory 表已包含 Icon 和 IconKeywords 字段
• 数据库备份已完成
• 测试环境验证通过

部署步骤

1. 数据库迁移

数据库字段已在开发过程中添加，无需额外迁移：

-- Icon 字段（已存在，长度已调整为 50）
ALTER TABLE TransactionCategory MODIFY COLUMN Icon VARCHAR(50);

-- IconKeywords 字段（已添加）
-- 格式：JSON数组，如 ["food", "restaurant", "dining"]

2. 后端部署

# 构建项目
dotnet build EmailBill.sln --configuration Release

# 运行测试
dotnet test WebApi.Test/WebApi.Test.csproj

# 发布 WebApi
dotnet publish WebApi/WebApi.csproj \
  --configuration Release \
  --output ./publish

# 部署到服务器
# （根据实际部署环境操作）

3. 前端部署

cd Web

# 安装依赖
pnpm install

# 构建生产版本
pnpm build

# 构建产物在 dist/ 目录
# 部署到 Web 服务器

4. 配置文件

确保 appsettings.json 包含以下配置：

{
  "Iconify": {
    "ApiUrl": "https://api.iconify.design/search",
    "DefaultLimit": 20,
    "MaxRetryCount": 3,
    "RetryDelayMs": 1000
  },
  "AI": {
    "Endpoint": "your-ai-endpoint",
    "Key": "your-ai-key",
    "Model": "your-model"
  }
}

监控配置

1. 日志监控

关键日志事件：

• IconSearchService: 图标搜索关键字生成、API 调用
• IconifyApiService: Iconify API 调用失败、重试
• SearchKeywordGeneratorService: AI 关键字生成失败
• IconController: API 请求和响应

2. 性能指标

监控以下指标：

• Iconify API 调用成功率: 应 > 95%
• 关键字生成成功率: 应 > 90%
• 图标搜索平均响应时间: 应 < 2秒
• 图标更新成功率: 应 = 100%

3. 错误告警

配置告警规则：

• Iconify API 连续失败 3 次 → 发送告警
• AI 关键字生成连续失败 5 次 → 发送告警
• 图标更新失败 → 记录日志

4. 日志查询示例

# 查看 Iconify API 调用失败
grep "Iconify API调用失败" /var/log/emailbill/app.log

# 查看图标搜索关键字生成日志
grep "生成搜索关键字" /var/log/emailbill/app.log

# 查看图标更新日志
grep "更新分类.*图标" /var/log/emailbill/app.log

部署后验证

1. API 接口验证

使用 Swagger 或 Postman 测试以下接口：

# 1. 生成搜索关键字
POST /api/icons/search-keywords
{
  "categoryName": "餐饮"
}

# 预期响应：
{
  "success": true,
  "data": {
    "keywords": ["food", "restaurant", "dining"]
  }
}

# 2. 搜索图标
POST /api/icons/search
{
  "keywords": ["food", "restaurant"]
}

# 预期响应：
{
  "success": true,
  "data": [
    {
      "collectionName": "mdi",
      "iconName": "food",
      "iconIdentifier": "mdi:food"
    },
    ...
  ]
}

# 3. 更新分类图标
PUT /api/categories/{categoryId}/icon
{
  "iconIdentifier": "mdi:food"
}

# 预期响应：
{
  "success": true,
  "message": "更新分类图标成功"
}

2. 前端功能验证

• 访问分类管理页面
• 点击"选择图标"按钮
• 验证图标选择器打开
• 搜索图标（输入关键字）
• 选择图标并保存
• 验证图标在分类列表中正确显示

3. 性能验证

• 图标搜索响应时间 < 2秒
• 图标渲染无闪烁
• 分页加载流畅
• 图标 CDN 加载正常

回滚策略

如果部署后出现问题，按以下步骤回滚：

1. 数据库回滚

数据库字段保留，不影响回滚。旧代码仍可读取 Icon 字段（SVG 或 Iconify 标识符）。

2. 代码回滚

# 回滚到上一个稳定版本
git checkout <previous-stable-commit>

# 重新部署
dotnet publish WebApi/WebApi.csproj --configuration Release
cd Web && pnpm build

3. 配置回滚

• 移除 appsettings.json 中的 Iconify 配置
• 恢复旧的 AI 生成 SVG 配置

已知问题和限制

1. Iconify API 依赖: 如果 Iconify API 不可用，图标搜索功能将失败

   • 缓解: 实现了重试机制（3次重试，指数退避）
   • 备选: 用户可手动输入图标标识符

2. AI 关键字生成: 依赖 AI API，可能受限流影响

   • 缓解: 用户可手动输入搜索关键字
   • 备选: 使用默认关键字映射表

3. 图标数量: 某些分类可能返回大量图标

   • 缓解: 分页加载（每页20个图标）
   • 备选: 提供搜索过滤功能

部署后监控清单

• 第 1 天: 检查日志，确认无严重错误
• 第 3 天: 查看 Iconify API 调用成功率
• 第 7 天: 分析用户使用数据，优化推荐算法
• 第 30 天: 评估功能效果，规划后续优化

联系信息

技术支持: 开发团队
紧急联系: On-call 工程师

---

准备者: AI Assistant
审核者: 待审核
批准者: 待批准
最后更新: 2026-02-16