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

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

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

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

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

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

**步骤**：
1. 确保测试环境已部署最新代码（包含新的 IconPromptSettings 和 ClassificationIconPromptProvider）
2. 在测试环境的 `appsettings.json` 中配置：
   ```json
   {
     "IconPromptSettings": {
       "EnableNewPrompt": true,
       "GrayScaleRatio": 1.0,
       "StyleStrength": 0.7,
       "ColorScheme": "single-color"
     }
   }
   ```
3. 查询数据库中已有的分类列表：
   ```sql
   SELECT Name, Type FROM TransactionCategories WHERE Icon IS NOT NULL AND Icon != '';
   ```
4. 手动触发图标生成任务（或等待定时任务自动执行）
5. 观察日志，确认：
   - 成功为每个分类生成了 5 个 SVG 图标
   - 使用了新版提示词（日志中应显示"新版"）

**预期结果**：
- 所有分类成功生成 5 个 SVG 图标
- 图标内容为 JSON 数组格式
- 日志显示"使用新版提示词"

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

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

**步骤**：
1. 从数据库中提取一些分类的旧图标数据：
   ```sql
   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 的测试环境中执行：
```csharp
[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()` 方法中实现：
```csharp
private bool ShouldUseNewPrompt()
{
    if (!_config.EnableNewPrompt)
    {
        return false;
    }

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

**验证方法**：
- 在日志中查看是否同时出现"新版"和"旧版"提示词
- 检查新版和旧版的比例是否接近配置的灰度比例

### 任务 4.5：部署灰度版本

**部署步骤**：
1. 准备部署包（包含更新后的代码和配置）
2. 在 `appsettings.json` 中设置：
   ```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 查询生成失败分类**：
```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`：
   ```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：测试运行

**后端测试**：
```bash
cd WebApi.Test
dotnet test --filter "FullyQualifiedName~ClassificationIconPromptProviderTest"
```

**前端测试**：
```bash
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）