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 用带尾斜杠的正则，两边都会误伤前端路由。

二、目标（交付物）

前端冲突路由改名（推荐方案 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 路由，可复用）
代理收窄：vite 代理不再是宽前缀——改为精确路径清单 / 正则白名单（先枚举后端真实 URL：chunyu_project/config/urls.py + 各 app urls.py，以枚举结果为准）。
生产 nginx 同步：nginx-docker.conf 同样收窄，并覆盖 /article/:id、/user/:id、/api/* 五条数据页的冲突段。
回归脚本：提交一个可重复运行的 73 路由检查脚本（如 scripts/check_routes.mjs），检测逻辑三件套：① 是否返回 Django 404/JSON（劫持）② #root 是否空（白屏）③ 正文长度。
全量更新 navigation(...) / 跳转引用 / 语言包中的路径引用。

三、执行步骤

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 复用

五、验收命令（参考）

# 后端
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。

4.1 KiB Raw Blame History Unescape Escape