1

docs/technical/PROFILE_MAIN_ROUTE_VITE_PROXY_FIX_2026-05-02.md

@@ -0,0 +1,37 @@
+# Profile 主链 Vite 代理修复
+
+## 1. 问题
+
+“我的”和“存档”页面在本地开发环境报：
+
+```text
+Unexpected token '<', "<!doctype "... is not valid JSON
+```
+
+这不是后端返回了坏 JSON，而是前端请求 `/api/profile/*` 时没有命中 Vite 代理，Vite 将请求按 SPA fallback 返回了 `index.html`。`requestJson` 随后对 HTML 执行 `JSON.parse`，首字符 `<` 触发该错误。
+
+## 2. 现有约束
+
+DDD 路由矩阵已冻结 profile 主链：
+
+1. “我的”与存档读取统一走 `/api/profile/*`。
+2. 旧 `/api/runtime/profile/*` 已取消挂载，不允许前端回退到旧路径。
+3. 后端 `api-server` 已挂载 `/api/profile/dashboard`、`/api/profile/save-archives` 等路由，问题只在本地 Vite 代理层。
+
+## 3. 修复
+
+`vite.config.ts` 在现有 `/api/auth`、`/api/runtime` 等代理旁补齐：
+
+```ts
+'/api/profile': {
+  target: runtimeServerTarget,
+  changeOrigin: true,
+  secure: false,
+},
+```
+
+这样 profile 主链请求在 `npm run dev:web` 下会直接转发到 Rust API server，不再落到前端入口页。
+
+## 4. 回归
+
+新增 `src/config/viteProxyConfig.test.ts`，断言 Vite server proxy 必须包含 `/api/profile`。后续若再调整 profile route 或代理配置，先更新本文和测试，再改工程实现。