EmailBill/.doc/ICONIFY_DEPLOYMENT_CHECKLIST.md

# Iconify 图标集成 - 部署清单

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

## 部署前检查

### 1. 代码完整性
- [x] 所有代码已提交到版本控制
- [x] 所有测试通过（130/130 测试用例）
- [x] 代码已通过 code review

### 2. 配置检查
- [ ] `appsettings.json` 包含 Iconify 配置
- [ ] AI API 配置正确（用于关键字生成）
- [ ] 数据库连接字符串正确

### 3. 数据库准备
- [x] TransactionCategory 表已包含 Icon 和 IconKeywords 字段
- [ ] 数据库备份已完成
- [ ] 测试环境验证通过

## 部署步骤

### 1. 数据库迁移

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

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

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

### 2. 后端部署

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

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

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

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

### 3. 前端部署

```bash
cd Web

# 安装依赖
pnpm install

# 构建生产版本
pnpm build

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

### 4. 配置文件

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

```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. 日志查询示例

```bash
# 查看 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 测试以下接口：

```bash
# 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. 代码回滚
```bash
# 回滚到上一个稳定版本
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