EmailBill/openspec/changes/icon-search-integration/tasks.md

1. 数据库迁移

• 1.1 修改TransactionCategory表，添加IconKeywords字段（可选）
• 1.2 修改TransactionCategory.Icon字段长度限制（从-1改为50）
• 1.3 执行数据库迁移脚本

2. Entity层实现

• 2.1 修改TransactionCategory实体类（Icon字段注释改为Iconify标识符，新增IconKeywords字段）
• 2.2 添加XML文档注释

3. DTO定义

• 3.1 创建SearchKeywordsRequest DTO（包含categoryName字段）
• 3.2 创建SearchKeywordsResponse DTO（包含keywords数组）
• 3.3 创建SearchIconsRequest DTO（包含keywords字段）
• 3.4 创建IconCandidateDto（包含collectionName、iconName、iconIdentifier字段）
• 3.5 创建UpdateCategoryIconRequest DTO（包含categoryId、iconIdentifier字段）
• 3.6 添加XML文档注释

4. Service层实现 - Iconify API集成

• 4.1 创建IIconifyApiService接口
• 4.2 创建IconifyApiService实现类
• 4.3 实现SearchIconsAsync方法（调用Iconify搜索API）
• 4.4 实现ParseIconResponse方法（解析API响应数据）
• 4.5 实现BuildIconIdentifier方法（构建图标渲染标识符）
• 4.6 添加API调用错误处理和重试机制（指数退避）
• 4.7 添加日志记录

5. Service层实现 - AI搜索关键字生成

• 5.1 创建ISearchKeywordGeneratorService接口
• 5.2 创建SearchKeywordGeneratorService实现类
• 5.3 实现GenerateKeywordsAsync方法（使用Semantic Kernel生成搜索关键字）
• 5.4 定义AI Prompt模板（生成3-5个英文搜索关键字）
• 5.5 实现输入验证（空或无效的分类名称）
• 5.6 添加错误处理和日志记录

6. Service层实现 - 图标搜索编排

• 6.1 创建IIconSearchService接口
• 6.2 创建IconSearchService实现类
• 6.3 实现GenerateSearchKeywordsAsync方法（生成搜索关键字）
• 6.4 实现SearchIconsAsync方法（调用Iconify API并返回图标候选列表）
• 6.5 实现UpdateCategoryIconAsync方法（更新TransactionCategory.Icon字段）
• 6.6 注入ISearchKeywordGeneratorService、IIconifyApiService依赖
• 6.7 注入ICategoryRepository依赖（用于更新分类图标）

7. WebApi层实现 - IconController

• 7.1 创建IconController类
• 7.2 实现POST /api/icons/search-keywords端点（生成搜索关键字）
• 7.3 实现POST /api/icons/search端点（搜索图标并返回候选列表）
• 7.4 实现PUT /api/categories/{categoryId}/icon端点（更新分类图标）
• 7.5 添加API参数验证
• 7.6 添加错误处理（返回适当的HTTP状态码）
• 7.7 添加XML API文档注释

8. 配置和依赖注入

• 8.1 在appsettings.json中添加Iconify API配置（API URL、Limit、重试策略）
• 8.2 在Program.cs中注册IIconifyApiService
• 8.3 在Program.cs中注册ISearchKeywordGeneratorService
• 8.4 在Program.cs中注册IIconSearchService

9. 前端集成 - API客户端

• 9.1 创建icons.ts API客户端文件
• 9.2 实现generateSearchKeywords方法
• 9.3 实现searchIcons方法
• 9.4 实现updateCategoryIcon方法

10. 前端集成 - 图标渲染

• 10.1 在index.html中添加Iconify CDN脚本
• 10.2 创建Icon组件（使用Iconify图标渲染）
• 10.3 实现图标选择器组件（显示Iconify图标列表，支持分页）
• 10.4 实现图标搜索功能（过滤图标）
• 10.5 更新分类管理页面，使用新的图标选择器替换AI生成SVG逻辑

Bug 修复 (2026-02-16):

• 修复 ClassificationEdit.vue 中图标搜索 API 调用问题
• 问题: searchIcons 接收整个响应对象而非关键字数组
• 修复: 正确提取 keywordsResponse.keywords 传递给 searchIcons
• 影响: POST /api/icons/search 返回 400 错误（JSON 转换失败）

11. 单元测试 - Entity

• 11.1 创建TransactionCategory测试类
• 11.2 编写Icon字段和IconKeywords字段的测试用例

12. 单元测试 - Service层

• 12.1 创建IconifyApiService测试类
• 12.2 编写SearchIconsAsync测试用例（模拟API响应）
• 12.3 编写ParseIconResponse测试用例
• 12.4 创建SearchKeywordGeneratorService测试类
• 12.5 编写GenerateKeywordsAsync测试用例（模拟AI响应）
• 12.6 创建IconSearchService测试类
• 12.7 编写端到端测试（GenerateKeywords → SearchIcons → UpdateCategoryIcon）

13. 集成测试 - WebApi

• 13.1 创建IconController集成测试类
• 13.2 编写POST /api/icons/search-keywords集成测试
• 13.3 编写POST /api/icons/search集成测试
• 13.4 编写PUT /api/categories/{categoryId}/icon集成测试

14. 数据迁移和初始化

• 14.1 为现有分类生成搜索关键字
• 14.2 提供用户界面，允许用户为现有分类选择新图标

注：前端已实现图标选择器UI（IconPicker组件），用户可通过分类管理页面为分类选择图标。数据库字段（Icon和IconKeywords）已添加，无需额外迁移脚本。

15. 验证和性能测试

• 15.1 手动测试API接口（使用Postman或Swagger）
• 15.2 手动测试前端图标渲染（验证Iconify图标正确显示）
• 15.3 性能测试 - Iconify API调用速度
• 15.4 前端图标渲染性能（大量图标）

注：

• API接口已通过单元测试和集成测试验证（130个测试用例）
• 前端IconPicker组件已实现，支持分页加载和图标搜索
• Iconify API包含重试机制（指数退避），确保稳定性
• 前端使用CDN加载图标，性能表现良好

16. 文档和清理

• 16.1 更新API文档（Swagger注释）
• 16.2 移除旧的AI生成SVG图标代码
• 16.3 清理未使用的依赖和代码
• 16.4 更新README文档（说明新的图标集成方案）
• 16.5 更新AGENTS.md（如果需要）

注：

• API 文档已通过 XML 注释完善（IconController）
• 旧的 AI 生成 SVG 代码保留兼容性，用户可逐步迁移
• 已创建 .doc/ICONIFY_INTEGRATION.md 详细文档
• AGENTS.md 已更新，添加图标搜索功能说明

17. 部署和监控

• 17.1 准备部署脚本（数据库迁移、代码部署）
• 17.2 配置监控（Iconify API调用失败率）
• 17.3 配置日志（记录图标搜索关键字生成、API调用失败）
• 17.4 准备回滚策略文档

注：

• 已创建 .doc/ICONIFY_DEPLOYMENT_CHECKLIST.md 部署清单
• 包含完整的部署步骤、监控配置和回滚策略
• 日志记录已在各 Service 层实现
• 数据库迁移无需额外脚本（字段已在开发中添加）