docs: 归属M1/M2/M3十二项PROGRESS（C-02~C-06/E-03~E-05/D-01/D-02/I-01/S-01）

PLANNING/PROGRESS_C-02.md

@@ -0,0 +1,42 @@
+# PROGRESS_C-02 · 工具热榜 + 最近使用
+
+> 日期 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 后续补）。