vscode-workbench/PLANNING/PROGRESS_C-02.md

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

• 状态：done

日期 2026-09-12/13 · 范围：可乐工具（chunyu_project/tool + chunyu_project_react）

现状 vs 差距（接手时）

• 已有：ToolUsageRecord 模型+迁移、ToolTopView（仅 period=total|week）、increment 双写、Home 热榜横条（period=total）。
• 缺口：无 GET /api/tool/recent；榜单缺 range=all|week 口径与 rank/weekly_count 字段；无 /top 页面；首页无空态/周榜徽标；零聚合单测。

改动

后端（chunyu_project/tool/）：

1. views/tool_manage_view.py：ToolTopView 支持 range=all|week（兼容旧 period=total|week）， 返回项统一含 usage_count/weekly_count/weekly_usage/rank；新增 ToolRecentView （登录，去重按 -created_at,-id 倒序）。
2. views/__init__.py、urls.py：挂载 path('recent/', ToolRecentView)。
3. management/commands/seed_tools.py：新增 AI 工具 分类（给 C-04 用）+ AI 图片放大 / 代码在线运行 两个工具种子。
4. tests/test_tool_top.py（新建，9 条）：总榜排序+rank、period 别名、周聚合、 7 天窗口边界（±60s）、空周回退总榜、匿名/登录双写、recent 401、recent 去重排序。

前端（chunyu_project_react/src/）： 5. pages/Top/（新建 Top.tsx+Top.css）：/top 总榜/周榜切换 + 排名 + “本周 XX 人在用”。 6. App.tsx：Top 懒加载路由 /top。 7. utils/request.ts：tool.getTop 沿用 + 新增 tool.getRecent。 8. pages/Home/Home.tsx：热榜改 range=all，查看全部指向 /top，加空态 + 周榜徽标；Home.css 加 .home-utility-card-weekly、.home-top-empty。

口径说明

• 存量 Tool.usage_count 继续为累计口径（不清零、不重算）；周榜用 ToolUsageRecord 近 7 天聚合；两者差异为预期（明细只从双写上线日起算），文档以此为准。

验证

DB_ENGINE=django.db.backends.sqlite3 DB_NAME=".../chunyu_project/dev_db.sqlite3" \
python ".../chunyu_project/manage.py" test tool -v 1
# Ran 15 tests … OK（6 存量 + 9 新增；含一次 recent 排序稳定性修复：order_by 加 -id 兜底）
tsc --noEmit -p chunyu_project_react/tsconfig.json   # 零报错
vite build  # 成功；Top/Upscaler/CodeRunner/pyodide-runner 均为独立 chunk

手工：同工具连调 3 次 increment → GET /tool/top/?range=week weekly_count=3（单测已覆盖同等价）。

状态

done。遗留：/top 页 i18n 文案为中文硬编码（多语言 key 后续补）。