AI 资源详情页优化 - 测试指南¶

🎯 测试目标¶

验证评分判断区功能正常，信息架构符合设计要求。

🚀 快速启动¶

# 启动开发服务器
make server

# 访问测试页面
open http://localhost:1313/zh/ai/

✅ 测试清单¶

1. 判断区显示测试¶

测试页面: 任何有 GitHub 链接的 AI 资源 (如 /zh/ai/langchain/)

加载状态: 页面加载时显示"正在加载评分..."
评分显示: 加载完成后显示评分数字 (如 85/100)
进度条: 进度条填充比例与评分一致
状态徽章: 显示对应的状态词 (优秀/良好/一般/早期/谨慎)
推荐总结: 显示一句话总结 (如"优质项目·高度活跃")
位置正确: 判断区位于标题和描述之后，作者信息之前

2. 评分语义映射测试¶

访问不同评分的资源，验证映射正确：

评分范围	状态	中文标签	英文标签	颜色
90-100	excellent	强烈推荐	Must Watch	绿色
80-89	good	值得关注	Strong Recommendation	蓝色
70-79	fair	值得尝试	Worth Trying	琥珀色
60-69	early	早期/小众	Early / Niche	紫色
0-59	caution	谨慎探索	Explore Carefully	红色

测试方法:

# 查看具有不同评分的项目
# 高分项目 (90+)
open http://localhost:1313/zh/ai/langchain/

# 中等项目 (70-89)  
open http://localhost:1313/zh/ai/next-ai-draw.io/

# 早期项目 (60-69)
open http://localhost:1313/zh/ai/[找一个早期项目]/

3. 右侧卡片重构测试¶

验证点:

标题改变: "资源信息" → "评分详情" (Score Breakdown)
内容顺序:
Overall Status (评分证据)
四维评分
最后更新时间
智能徽章
视觉权重: 右侧卡片比判断区字号更小
无结论性语言: 卡片内容不应有"值得尝试"等推荐语

4. 响应式布局测试¶

桌面端 (>1024px):

判断区水平布局 (评分在左，标签在右)
进度条宽度约 120px
评分数字 2.5rem

移动端 (<768px):

判断区垂直堆叠
进度条全宽
评分数字 2rem
可读性良好

测试方法:

# Chrome DevTools
1. F12 打开开发者工具
2. 点击设备模拟按钮
3. 切换不同设备尺寸

5. 深色模式测试¶

判断区背景适配深色模式
边框颜色可见
进度条在深色背景下清晰
状态徽章颜色对比度足够

测试方法:

# 切换深色模式
系统设置 → 外观 → 深色

# 或在浏览器中
DevTools → Rendering → Emulate CSS media: prefers-color-scheme: dark

6. 相关资源排序测试¶

验证点:

相关资源有 data-ai-repo 属性
JavaScript 加载后，资源按评分重新排序
高评分资源排在前面
同等评分按原有顺序

测试方法:

// 在浏览器控制台执行
document.querySelectorAll('.related-item').forEach(item => {
  console.log(item.querySelector('h6 a').textContent, 
              item.dataset.aiRepo);
});

7. 错误处理测试¶

无 GitHub 链接的资源:

判断区不显示
页面其他部分正常工作

API 失败场景:

显示"评分数据暂不可用"
不影响页面其他功能
相关资源使用默认排序

测试方法:

# 模拟API失败(修改worker URL)
# 或使用浏览器网络节流功能
DevTools → Network → Throttling → Offline

8. 缓存测试¶

首次访问：API 被调用
刷新页面：使用缓存 (30 分钟内)
控制台无重复 API 调用

测试方法:

// 检查 sessionStorage
console.log(Object.keys(sessionStorage).filter(k => k.startsWith('ai-health-')));

// 查看缓存内容
JSON.parse(sessionStorage.getItem('ai-health-langchain/langchain'));

9. 国际化测试¶

中文页面 (/zh/ai/...):

判断区显示中文标签和总结
右侧卡片标题为"评分详情"
加载提示为"正在加载评分..."

英文页面 (/en/ai/...):

判断区显示英文标签和总结
右侧卡片标题为"Score Breakdown"
加载提示为"Loading score..."

10. 打印样式测试¶

判断区在打印时简化显示
边框和背景适配打印
避免分页断裂 (page-break-inside: avoid)

测试方法:

Ctrl+P (Cmd+P on Mac) → 打印预览

🐛 已知问题 & 预期行为¶

正常情况¶

评分数据延迟: 页面先显示静态内容，1-2 秒后评分加载完成
缓存生效: 第二次访问同一资源时，评分立即显示
非 GitHub 资源: 商业产品 (无 GitHub 链接) 不显示判断区

不是 Bug¶

判断区不显示: 资源没有 GitHub 链接是正常的
右侧仍显示评分: 右侧卡片评分是"证据展示",与主判断区互补
相关资源排序未变: 相关资源都没有 GitHub 链接时，使用默认顺序

📊 性能验证¶

Lighthouse 检查¶

# Chrome DevTools → Lighthouse → Run audit

期望指标:

Performance: ≥90
Accessibility: ≥95
Best Practices: ≥90

网络请求¶

判断区：1 个 API 请求 (有缓存时 0 个)
相关资源：最多 3 个 API 请求
总额外延迟：<500ms

🎨 视觉回归测试¶

关键检查点¶

视觉层级: 判断区 > 其他元数据
颜色对比: 所有文本满足 WCAG AA 标准
间距一致: 判断区与周围元素间距合理
边框效果: 判断区边框颜色匹配评分档位

✅ 通过标准¶

所有测试项目完成后，应满足：

90% 以上测试项通过
没有控制台错误
在 Chrome、Firefox、Safari 上表现一致
移动端可用性良好
深色模式无视觉问题

🚨 发现问题？¶

调试步骤¶

打开浏览器控制台 (F12)
检查网络请求 (Network tab)
查看 JavaScript 错误 (Console tab)
验证 DOM 结构 (Elements tab)

常见问题排查¶

判断区不显示:

# 检查元素是否存在
document.querySelector('[data-ai-judgement-header]')

# 检查repo slug
document.querySelector('[data-ai-repo]')?.dataset.aiRepo

评分始终 loading:

# 检查API响应
fetch('https://ai-oss-rank-worker.jimmysong.io/health/langchain/langchain')
  .then(r => r.json())
  .then(console.log)

样式未生效:

# 检查CSS是否加载
document.querySelectorAll('link[rel=stylesheet]').forEach(
  link => console.log(link.href)
);

📝 测试报告模板¶

## 测试日期：YYYY-MM-DD
## 测试人员：[姓名]
## 浏览器：Chrome XX / Firefox XX / Safari XX

### 通过项 (X/10)
- [x] 判断区显示
- [x] 评分映射
- [ ] ...

### 发现的问题
1. [描述问题]
   - 复现步骤：...
   - 预期行为：...
   - 实际行为：...

### 建议改进
1. [改进建议]

🎉 测试完成后¶

如果所有测试通过：

✅ 标记测试清单所有项
✅ 填写测试报告
✅ 提交到 staging 环境
✅ 准备生产部署

Happy Testing! 🚀