# C-02 · 工具热榜 + 最近使用

| 字段 | 值 |
|---|---|
| 项目 | 可乐工具 · `chunyu_project`（tool app）+ `chunyu_project_react` |
| 优先级 | P0 · M2 |
| 建议模型 | deepseek-v4.1-flash（主）/ qwen3.8-flash（时间窗边界用例） |
| 依赖 | C-01（路由基线修好再动页面） |
| 预估 | 1.5 天 |

## 一、背景（为什么做）

1. 工具只有 16 个，竞品 100+——先激活存量：`Tool.usage_count` 字段已有，但**没有转化为任何排行榜/热门入口**（数据在睡觉）。
2. 竞品实证：tool.lu 有 `/top/` 排行榜、掘金有排行榜侧栏——这是低成本高粘性的标准件。
3. 报告结论：工具页无"最近使用/最热使用"入口是 P0 级发现缺口（`docs/产品问题分析与改造路线.md` P0-1）。

## 二、目标（交付物）

**后端（tool app）**
1. 新模型 `ToolUsageRecord`：`tool`(FK)、`user`(nullable，匿名可为空)、`session_key`(匿名归因)、`created_at`，索引 `(tool, created_at)`。
2. 现有"使用工具"计数逻辑处**双写**：保留 `usage_count` 自增，同时写 `ToolUsageRecord`。
3. 聚合接口：
   - `GET /api/tool/top?range=all|week&limit=10` → `[{id, name, icon, usage_count, weekly_count, rank}]`
   - `GET /api/tool/recent`（登录，返回本人最近使用工具）
4. 迁移文件 + 存量 `usage_count` 回填说明（无历史明细则从当前值起算，文档写清楚）。

**前端（React）**
5. 新页面 `Top.tsx`（路由 `/top`）：总榜 / 周榜切换 + 完整榜单。
6. `Home.tsx`：Hero 下方加"🔥 热门工具 Top10"横条（横向滚动卡片）。
7. 工具卡片展示"本周 XX 人在用"（取 `weekly_count`；为 0 时不显示）。

## 三、执行步骤

```text
1. 定位现有 usage_count 自增点（tool app views/ 与前端调用处）
2. 建模 + 迁移 + 双写 + 聚合接口（异步视图，adrf 风格对齐项目惯例）
3. 前端 Top 页 + Home 横条 + 卡片徽标
4. 写测试：聚合正确性（总/周窗口）、匿名归因、recent 权限
5. 回归既有测试 + 手工验收
```

## 四、验收标准

- [ ] 使用任意工具 → `ToolUsageRecord` 新增记录（登录记 user，匿名记 session_key）
- [ ] 总榜 = 全部记录聚合；**周榜 = 最近 7 天窗口**（用固定时间戳测试用例验证窗口边界：7 天整、7 天+1 秒）
- [ ] `/top` 页总榜/周榜切换正常，排名序号正确
- [ ] 首页 Top10 横条渲染，空数据时有优雅空态
- [ ] `usage_count` 旧数据与新聚合口径一致（或文档说明差异）
- [ ] 既有测试全绿 + 新增用例 ≥6 条

## 五、验收命令（参考）

```bash
cd chunyu_project && python manage.py makemigrations tool && python manage.py migrate
python manage.py test tool -v 2          # 新增用例全绿
# 手工：连续调用同一工具 3 次 → GET /api/tool/top?range=week 计数=3
```

## 六、边界（不许做）

- 不改 `Tool` 既有字段语义（`usage_count` 继续有效）
- 不做"工具使用周报"等衍生功能（另一张卡的空间）
- 不动其他 app

## 七、交接

写 `PROGRESS_C-02.md`（含聚合用例输出与窗口边界测试证据）。