# C-01 · 路由/代理前缀冲突修复

| 字段 | 值 |
|---|---|
| 项目 | 可乐工具 · `vscode/chunyu_project_react`（前端）+ `vscode/chunyu_project`（后端） |
| 优先级 | P0 · M1 |
| 建议模型 | deepseek-v4.1-flash（主）/ glm-5.3-flash（全量回归复核） |
| 依赖 | 无 |
| 预估 | 1 天 |

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

2026-09-10 页面健康检查实测：**开发环境 22 条路由、生产环境 7 条路由被 API 代理劫持**——用户刷新页面、收藏链接、分享链接时直接打开 Django 404 或原始 JSON，而不是前端页面。SPA 内部点击导航不受影响，所以**藏得深、咬得狠**。

证据：`vscode/docs/页面健康检查报告.md`（问题清单 1.1 / 1.2）。

根因：前端路由与后端 API 共用了一组顶级路径段（`/api`、`/article`、`/learn`、`/user`、`/bug`、`/chat`、`/history`、`/message`、`/s`、`/search`、`/tool`），vite 代理用**前缀匹配**、生产 nginx 用**带尾斜杠的正则**，两边都会误伤前端路由。

## 二、目标（交付物）

1. **前端冲突路由改名**（推荐方案 A，报告结论"一劳永逸，趁早改便宜"）：
   - `/api` 及其子路由（`/api-directory`、`/api-docs`、`/api-detail/:id`、`/api/ip-location` 等 5 个数据 API 页）→ `/open-api/*`
   - `/article/:id` → `/post/:id`（或 `/article-detail/:id`）
   - `/user/:id` → `/user-home/:id`（项目已有 `/user-home` 路由，可复用）
2. **代理收窄**：vite 代理不再是宽前缀——改为**精确路径清单 / 正则白名单**（先枚举后端真实 URL：`chunyu_project/config/urls.py` + 各 app `urls.py`，以枚举结果为准）。
3. **生产 nginx 同步**：`nginx-docker.conf` 同样收窄，并覆盖 `/article/:id`、`/user/:id`、`/api/*` 五条数据页的冲突段。
4. **回归脚本**：提交一个可重复运行的 73 路由检查脚本（如 `scripts/check_routes.mjs`），检测逻辑三件套：① 是否返回 Django 404/JSON（劫持）② `#root` 是否空（白屏）③ 正文长度。
5. 全量更新 `navigation(...)` / 跳转引用 / 语言包中的路径引用。

## 三、执行步骤

```text
1. 枚举后端真实 API 路径（config/urls.py + 全部 app urls.py），产出一张「API 路径清单」
2. 对照前端 73 条路由，标记全部冲突项（不只报告里那 7 条）
3. 执行改名 + 同步全部引用（grep 旧路径确认零残留）
4. 收窄 vite 代理 → 启动 dev 双端，跑回归脚本至 73/73
5. 收窄 nginx-docker.conf，静态审查冲突模式段
6. 提交：代码 + 回归脚本 + 检查报告（贴进 PROGRESS）
```

## 四、验收标准

- [ ] dev 环境：73 条路由直访全部返回 SPA（无 Django 404/JSON 劫持、无白屏）
- [ ] 生产 nginx 配置：审查确认 7 条冲突段全部让路（含 `/article/:id`、`/user/:id`——核心分享场景）
- [ ] `grep -rn "旧路径"` 零残留（含 App.tsx、页面组件、i18n 词条）
- [ ] API 调用回归正常（登录、文章列表、工具使用等核心接口抽查 via 代理）
- [ ] SPA 内部导航抽查正常（首页→文章→详情）
- [ ] 回归脚本已入库，可被 CI 复用

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

```bash
# 后端
cd chunyu_project && python manage.py runserver 8002
# 前端
cd chunyu_project_react && npm run dev    # 5173

# 路由回归（脚本由本任务交付）
node scripts/check_routes.mjs --base http://127.0.0.1:5173
# 期望输出：PASS 73/73，hijacked=0，blank=0

# 引用残留检查
grep -rn "'/api-docs'\|'/api-directory'\|/article/\|/user/" src/ --include="*.tsx" --include="*.ts" | grep -v open-api
```

## 六、边界（不许做）

- 不动后端 API 的响应结构（纯路由层工作）
- 不重构页面组件内部逻辑
- 不修改 `docs/` 下既有报告
- 新增路由名后必须保留旧路径的**客户端重定向**（302 内的 SPA `Navigate`）——已分享出去的链接不能全死

## 七、交接

交付 = 代码 + `scripts/check_routes.mjs` + **PROGRESS_C-01.md**（含 73/73 输出与占位截图说明）。
格式见 `PLANNING/03-执行协议.md`。