# 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 天聚合；两者差异为预期（明细只从双写上线日起算），文档以此为准。

## 验证
```bash
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 后续补）。