EmailBill/openspec/changes/archive/2026-02-17-icon-search-integration/specs/icon-search/spec.md

ADDED Requirements

Requirement: 图标搜索能力

系统SHALL能够根据分类名称搜索Iconify图标库中的图标。

Scenario: AI生成搜索关键字

• WHEN 系统接收到分类名称（如"餐饮"、"交通"）
• THEN 系统SHALL使用AI生成多个英文搜索关键字（如"food", "restaurant", "dining"）
• THEN 系统SHALL将搜索关键字保存到TransactionCategory.IconKeywords字段（JSON数组格式）

Scenario: 检索图标

• WHEN 系统使用搜索关键字调用Iconify API
• THEN 系统SHALL获取最多N个图标（N可配置，默认为20）
• THEN 每个图标包含图标集名称和图标名称

Scenario: 更新分类图标

• WHEN 用户为分类选择一个图标
• THEN 系统SHALL将Iconify图标标识符（如"mdi:home"）保存到TransactionCategory.Icon字段
• THEN 系统SHALL更新TransactionCategory记录

Scenario: 获取多个图标供选择

• WHEN 前端请求某分类的图标候选列表
• THEN 系统SHALL返回Iconify API检索到的图标列表
• THEN 返回数据SHALL包含图标集名称、图标名称和Iconify渲染标识符

Requirement: Iconify API集成

系统SHALL通过Iconify搜索API检索图标库。

Scenario: API调用格式

• WHEN 系统调用Iconify搜索API
• THEN 请求URL格式MUST为：https://api.iconify.design/search?query=<keyword>&limit=<limit>
• THEN 响应数据MUST包含图标集名称和图标名称

Scenario: 响应数据解析

• WHEN 系统接收到Iconify API响应
• THEN 系统SHALL解析响应JSON，提取每个图标的name（图标名称）和collection.name（图标集名称）
• THEN 系统SHALL构建Iconify渲染标识符：{collection.name}:{name}

Scenario: API错误处理

• WHEN Iconify API返回错误
• THEN 系统SHALL记录错误日志
• THEN 系统SHALL返回错误信息给调用方

Requirement: AI搜索关键字生成

系统SHALL使用AI根据分类名称生成英文搜索关键字。

Scenario: 生成搜索关键字

• WHEN 系统接收到中文分类名称
• THEN 系统SHALL生成3-5个相关英文搜索关键字
• THEN 关键字SHALL涵盖同义词、相关概念和常见英文表达

Scenario: 输入验证

• WHEN 系统接收到空或无效的分类名称
• THEN 系统SHALL返回错误
• THEN 系统SHALL不调用AI服务

Requirement: API接口

系统SHALL提供RESTful API接口用于图标管理。

Scenario: 生成搜索关键字

• WHEN 客户端调用 POST /api/icons/search-keywords 请求体包含分类名称
• THEN 系统SHALL返回AI生成的搜索关键字数组

Scenario: 搜索图标（供用户选择）

• WHEN 客户端调用 POST /api/icons/search 请求体包含搜索关键字
• THEN 系统SHALL调用Iconify API搜索图标
• THEN 系统SHALL返回Iconify API检索到的图标列表

Scenario: 更新分类图标

• WHEN 客户端调用 PUT /api/categories/{categoryId}/icon 请求体包含图标标识符
• THEN 系统SHALL更新TransactionCategory.Icon字段
• THEN 系统SHALL返回更新后的分类信息