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

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

一、背景（为什么做）

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

二、目标（交付物）

后端（tool app）

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

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

三、执行步骤

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 条

五、验收命令（参考）

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（含聚合用例输出与窗口边界测试证据）。

3.1 KiB Raw Blame History Unescape Escape