4.6 KiB
4.6 KiB
Context
当前状态:
- 分类图标由 AI 生成，有两个生成入口：用户手动生成（前端触发）和后台 JOB 自动生成
- 两套生成逻辑使用不同的提示词，导致生成的图标风格和质量不一致
- 分类编辑页面缺少删除图标功能，用户无法清除不需要的图标
ClassificationIconGenerateService.cs和ClassificationIconGenerateJob.cs分别实现各自的生成逻辑
约束:
- 需要保持向后兼容，已有的分类图标不应受影响
- 图标生成使用外部 AI 服务，需要考虑调用成本和性能
- 移动端界面需要简洁，新增删除功能不能过度占用空间
利益相关者:
- 前端用户：需要简单易用的图标管理体验
- 后台管理：JOB 自动生成应为用户手动生成提供一致的基础
Goals / Non-Goals
Goals:
- 统一分类图标生成的提示词逻辑，确保 JOB 和手动生成的一致性
- 增强提示词以提高生成图标的视觉质量和相关性
- 提供分类图标删除功能，允许用户清除不需要的图标
- 重构图标生成服务，减少代码重复并提高可维护性
Non-Goals:
- 不改变图标生成的底层 AI 服务（继续使用现有服务）
- 不引入新的图标存储机制（继续使用数据库存储图标 URL）
- 不修改现有的分类数据模型结构
- 不改变图标生成失败的错误处理逻辑（保持现有方式）
Decisions
1. 图标生成提示词统一化
- 决策: 创建
IClassificationIconPromptProvider接口，提取公共提示词模板 - 理由: 通过接口抽象提示词生成逻辑，便于测试和维护；模板化提示词确保一致性
- 替代方案: 将提示词硬编码在配置文件中 - 不够灵活，难以进行动态调整
- 影响:
ClassificationIconGenerateService和ClassificationIconGenerateJob都将使用统一的提示词提供器
2. 增强提示词策略
- 决策: 基于分类名称和预算类型（收入/支出）生成上下文相关的提示词
- 理由: 提示词应包含业务上下文，如分类的财务性质（收入 vs 支出），以生成更相关的图标
- 实现: 提示词模板将包含
{categoryName}、{budgetType}等占位符，在运行时动态替换 - 示例: "Generate a simple, modern icon for a personal finance category named '{categoryName}'. This is a {budgetType} category. Use a minimalist style with flat design, suitable for a mobile app."
3. 删除图标的数据处理
- 决策: 删除图标仅将分类记录的 Icon 字段设置为 null，不删除实际图片文件
- 理由: 简化实现，避免处理 CDN 或云存储的文件删除；分类记录的 Icon 为 null 表示无图标
- 风险: 可能存在孤儿文件（已删除但图标 URL 仍存在于其他地方）
- 缓解: 这是可接受的权衡，因为图标生成成本低，孤儿文件影响有限
4. 前端删除交互设计
- 决策: 在分类编辑页面的图标区域添加删除按钮（垃圾桶图标），点击后显示确认对话框
- 理由: 使用标准移动端删除模式（删除前确认）防止误操作
- 布局: 删除按钮放置在图标预览的右上角或下方，不破坏现有布局
Risks / Trade-offs
风险 1: 提示词统一后，JOB 生成的图标可能与用户期望不一致
- 缓解: 在部署前进行充分测试，对比 JOB 和手动生成的结果；提供重新生成选项
风险 2: AI 服务调用成本增加（如果提示词更复杂）
- 缓解: 增强提示词不应显著增加 token 使用量；监控调用成本，必要时缓存生成结果
权衡 1: 删除图标不清理实际文件 vs 简化实现
- 决策: 选择简化实现，接受孤儿文件的存在
权衡 2: 增强提示词 vs 生成速度
- 决策: 提示词增强优先于速度，因为生成是异步的（JOB 或后台任务）
Migration Plan
部署步骤:
- 部署后端代码（新的提示词服务和删除 API）
- 部署前端代码（删除按钮和 API 调用）
- 重启后台 JOB 服务，使用新的统一提示词
- 验证：手动测试分类图标生成和删除功能；检查 JOB 日志确保提示词正确应用
回滚策略:
- 如果新提示词导致生成质量下降，可回退到旧版本的后端代码
- 删除功能是新增的，不影响现有功能，无需回滚前端（用户可选择不使用）
数据迁移:
- 无需数据迁移，因为删除图标只是将字段设置为 null
- 现有图标不受影响
Open Questions
无待解决的开放问题。设计已明确技术方案和实现路径。