90 lines
4.6 KiB
Markdown
90 lines
4.6 KiB
Markdown
## 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
|
||
|
||
**部署步骤**:
|
||
1. 部署后端代码（新的提示词服务和删除 API）
|
||
2. 部署前端代码（删除按钮和 API 调用）
|
||
3. 重启后台 JOB 服务，使用新的统一提示词
|
||
4. 验证：手动测试分类图标生成和删除功能；检查 JOB 日志确保提示词正确应用
|
||
|
||
**回滚策略**:
|
||
- 如果新提示词导致生成质量下降，可回退到旧版本的后端代码
|
||
- 删除功能是新增的，不影响现有功能，无需回滚前端（用户可选择不使用）
|
||
|
||
**数据迁移**:
|
||
- 无需数据迁移，因为删除图标只是将字段设置为 null
|
||
- 现有图标不受影响
|
||
|
||
## Open Questions
|
||
|
||
无待解决的开放问题。设计已明确技术方案和实现路径。
|