EmailBill/.doc/icon-prompt-testing-guide.md

图标生成优化 - 测试与部署指南

本文档说明如何手动完成剩余的测试和部署任务。

第三阶段：测试与验证（手动部分）

任务 3.5：在测试环境批量生成新图标

目的：验证新提示词在测试环境能够正常生成图标

步骤：

1. 确保测试环境已部署最新代码（包含新的 IconPromptSettings 和 ClassificationIconPromptProvider）
2. 在测试环境的 appsettings.json 中配置：

   {
     "IconPromptSettings": {
       "EnableNewPrompt": true,
       "GrayScaleRatio": 1.0,
       "StyleStrength": 0.7,
       "ColorScheme": "single-color"
     }
   }
   

3. 查询数据库中已有的分类列表：

   SELECT Name, Type FROM TransactionCategories WHERE Icon IS NOT NULL AND Icon != '';
   

4. 手动触发图标生成任务（或等待定时任务自动执行）
5. 观察日志，确认：
   • 成功为每个分类生成了 5 个 SVG 图标
   • 使用了新版提示词（日志中应显示"新版"）

预期结果：

• 所有分类成功生成 5 个 SVG 图标
• 图标内容为 JSON 数组格式
• 日志显示"使用新版提示词"

任务 3.6：对比新旧图标的可识别性

目的：评估新图标相比旧图标的可识别性提升

步骤：

1. 从数据库中提取一些分类的旧图标数据：

   SELECT Name, Icon FROM TransactionCategories LIMIT 10;
   

2. 手动为相同分类生成新图标（或使用 3.5 的结果）
3. 将图标数据解码为实际的 SVG 代码
4. 在浏览器中打开 SVG 文件进行视觉对比

评估维度：

维度	旧图标	新图标	说明
复杂度	高（渐变、多色、细节多）	低（单色、扁平、细节少）	-
可识别性	较低（细节过多导致混淆）	较高（几何简约，直观易懂）	-
颜色干扰	多色和渐变导致视觉混乱	单色避免颜色干扰	-
一致性	5 个图标风格差异大，不易识别	5 个图标风格统一，易于识别	-

记录方法： 创建对比表格：

分类名称	旧图标可识别性	新图标可识别性	提升程度
餐饮	3/5	5/5	+2
交通	2/5	4/5	+2
购物	3/5	5/5	+2

任务 3.7-3.8：编写集成测试

由于这些任务需要实际调用 AI 服务生成图标并验证结果，建议采用以下方法：

方法 A：单元测试模拟 在测试中使用 Mock 的 AI 服务，返回预设的图标数据，然后验证：

• 相同分类名称和类型 → 返回相同的图标结构
• 不同分类名称或类型 → 返回不同的图标结构

方法 B：真实环境测试 在有真实 AI API key 的测试环境中执行：

[Fact]
public async Task GetPrompt_相同分类_应生成结构一致的图标()
{
    // Arrange
    var categoryName = "餐饮";
    var categoryType = TransactionType.Expense;

    // Act
    var icon1 = await _aiService.GenerateCategoryIconsAsync(categoryName, categoryType);
    var icon2 = await _aiService.GenerateCategoryIconsAsync(categoryName, categoryType);

    // Assert
    icon1.Should().NotBeNull();
    icon2.Should().NotBeNull();
    // 验证图标结构相似性（具体实现需根据实际图标格式）
}

注意事项：

• 真实环境测试会增加测试时间和成本
• 建议 CI/CD 环境中使用 Mock，本地开发环境使用真实 API
• 添加测试标记区分需要真实 API 的测试

任务 3.9：A/B 测试

目的：收集真实用户对新图标的反馈

步骤：

1. 确保灰度发布开关已开启（EnableNewPrompt = true）
2. 设置灰度比例为 10%（GrayScaleRatio = 0.1）
3. 部署到生产环境
4. 观察 1-2 天，收集：
   • 图标生成成功率（生成成功的数量 / 总生成请求数）
   • 用户反馈（通过客服、问卷、应用内反馈等）
   • 用户对图标的满意度评分

反馈收集方法：

• 应用内反馈按钮：在分类设置页面添加"反馈图标质量"按钮
• 用户问卷：通过邮件或应用内问卷收集用户对新图标的评价
• 数据分析：统计用户选择新图标的频率

评估指标：

指标	目标值	说明
图标生成成功率	> 95%	确保新提示词能稳定生成图标
用户满意度	> 4.0/5.0	用户对新图标的整体满意度
旧图标选择比例	< 30%	理想情况下用户更倾向选择新图标

任务 3.10：根据测试结果微调

调整方向：

1. 如果可识别性仍不够：

   • 增加 StyleStrength 值（如从 0.7 提升到 0.85）
   • 在提示词中添加更多"去除细节"的指令

2. 如果图标过于简单：

   • 降低 StyleStrength 值（如从 0.7 降低到 0.6）
   • 在提示词中放宽"保留必要细节"的约束

3. 如果某些特定分类识别困难：

   • 更新 category-visual-mapping.md 文档，为该分类添加更精确的视觉元素描述
   • 在提示词模板中为该分类添加特殊说明

4. 如果生成失败率高：

   • 检查 AI API 响应，分析失败原因
   • 可能需要调整提示词长度或结构
   • 考虑增加 timeout 参数

第四阶段：灰度发布

任务 4.1：测试环境验证

已在任务 3.5 中完成。

任务 4.2-4.3：配置灰度发布

配置已在 appsettings.json 中添加：

• EnableNewPrompt: 灰度发布总开关
• GrayScaleRatio: 灰度比例（0.0-1.0）

配置建议：

• 初始阶段：0.1（10% 用户）
• 稳定阶段：0.5（50% 用户）
• 全量发布前：0.8（80% 用户）
• 正式全量：1.0（100% 用户）或 EnableNewPrompt: true 且移除灰度逻辑

任务 4.4：灰度逻辑实现

已在 ClassificationIconPromptProvider.ShouldUseNewPrompt() 方法中实现：

private bool ShouldUseNewPrompt()
{
    if (!_config.EnableNewPrompt)
    {
        return false;
    }

    var randomValue = _random.NextDouble();
    return randomValue < _config.GrayScaleRatio;
}

验证方法：

• 在日志中查看是否同时出现"新版"和"旧版"提示词
• 检查新版和旧版的比例是否接近配置的灰度比例

任务 4.5：部署灰度版本

部署步骤：

1. 准备部署包（包含更新后的代码和配置）
2. 在 appsettings.json 中设置：

   {
     "IconPromptSettings": {
       "EnableNewPrompt": true,
       "GrayScaleRatio": 0.1,
       "StyleStrength": 0.7,
       "ColorScheme": "single-color"
     }
   }
   

3. 部署到生产环境
4. 验证部署成功（检查应用日志、健康检查端点）

任务 4.6：监控图标生成成功率

监控方法：

1. 在 SmartHandleService.GenerateCategoryIconsAsync() 方法中添加指标记录：

   • 生成成功计数
   • 生成失败计数
   • 生成耗时
   • 使用的提示词版本（新版/旧版）

2. 导入到监控系统（如 Application Insights, Prometheus）

3. 设置告警规则：

   • 成功率 < 90% 时发送告警
   • 平均耗时 > 30s 时发送告警

SQL 查询生成失败分类：

SELECT Name, Type, COUNT(*) as FailCount
FROM IconGenerationLogs
WHERE Status = 'Failed'
GROUP BY Name, Type
ORDER BY FailCount DESC
LIMIT 10;

任务 4.7：监控用户反馈

监控渠道：

1. 应用内反馈（如果已实现）
2. 客服系统反馈记录
3. 用户问卷调查结果

反馈分析维度：

• 新旧图标满意度对比
• 具体分类的反馈差异
• 意见类型（正面/负面/中性）

任务 4.8：逐步扩大灰度比例

时间规划：

阶段	灰度比例	持续时间	验证通过条件
阶段 1	10%	3-5 天	成功率 > 95%，用户满意度 > 4.0
阶段 2	50%	3-5 天	成功率 > 95%，用户满意度 > 4.0
阶段 3	80%	3-5 天	成功率 > 95%，用户满意度 > 4.0
全量	100%	-	长期运行

扩容操作： 只需修改 appsettings.json 中的 GrayScaleRatio 值并重新部署。

任务 4.9：回滚策略

触发回滚的条件：

• 成功率 < 90% 且持续 2 天以上
• 用户满意度 < 3.5 且负面反馈占比 > 30%
• 出现重大 bug 导致用户无法正常使用

回滚步骤：

1. 修改 appsettings.json：

   {
     "IconPromptSettings": {
       "EnableNewPrompt": false
     }
   }
   

2. 部署配置更新（无需重新部署代码）
3. 验证所有用户都使用旧版提示词（日志中应只显示"旧版"）

回滚后：

• 分析失败原因
• 修复问题
• 从小灰度比例（5%）重新开始测试

任务 4.10：记录提示词迭代

记录格式： 在 .doc/prompt-iteration-history.md 中维护迭代历史：

版本	日期	变更内容	灰度比例	用户反馈	结果
1.0.0	2026-02-14	初始版本，简约风格提示词	10%	-	-
1.1.0	2026-02-XX	调整风格强度为 0.8，增加去除细节指令	50%	满意度提升至 4.2	扩容至全量

第五阶段：文档与清理

任务 5.1-5.4：文档更新

已创建/需要更新的文档：

1. ✅ .doc/category-visual-mapping.md - 分类名称到视觉元素的映射规则
2. ✅ .doc/icon-prompt-testing-guide.md - 本文档
3. ⏳ API 文档 - 需更新说明 IconPromptSettings 的参数含义
4. ⏳ 运维文档 - 需说明如何调整提示词模板和风格参数
5. ⏳ 故障排查文档 - 需添加图标生成问题的排查步骤
6. ⏳ 部署文档 - 需说明灰度发布的操作流程

任务 5.5：清理测试代码

清理清单：

• 移除所有 Console.WriteLine 调试语句
• 移除临时的 TODO 注释
• 移除仅用于测试的代码分支

任务 5.6：代码 Review

Review 检查点：

• ✅ 所有类和方法都有 XML 文档注释
• ✅ 遵循项目代码风格（命名、格式）
• ✅ 无使用 var 且类型可明确推断的地方
• ✅ 无硬编码的魔法值（已在配置中）
• ✅ 异常处理完善
• ✅ 日志记录适当

任务 5.7-5.8：测试运行

后端测试：

cd WebApi.Test
dotnet test --filter "FullyQualifiedName~ClassificationIconPromptProviderTest"

前端测试：

cd Web
pnpm lint
pnpm build

总结

自动化部分（已完成）：

• ✅ 第一阶段：提示词模板化（1.1-1.10）
• ✅ 第二阶段：提示词优化（2.1-2.10）
• ✅ 第三阶段单元测试（3.1-3.4）

手动/灰度发布部分（需人工操作）：

• ⏳ 第三阶段手动测试（3.5-3.10）
• ⏳ 第四阶段：灰度发布（4.1-4.10）
• ⏳ 第五阶段：文档与清理（5.1-5.8）

下一步操作：

1. 部署到测试环境并执行任务 3.5-3.8
2. 根据测试结果调整配置（任务 3.10）
3. 部署到生产环境并开始灰度发布（任务 4.5-4.10）
4. 完成文档更新和代码清理（任务 5.1-5.8）