349 lines
11 KiB
Markdown
349 lines
11 KiB
Markdown
# 图标生成优化 - 测试与部署指南
|
||
|
||
本文档说明如何手动完成剩余的测试和部署任务。
|
||
|
||
## 第三阶段：测试与验证（手动部分）
|
||
|
||
### 任务 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）
|