quyun-v2/specs/ROUTING.md

新项目路由与部署规则（多租户路径前缀）

1. 路由总览

1.1 约定

• 租户前缀：/t/:tenant_code/（不区分大小写；服务端统一按 lower() 识别）
• API：/t/:tenant_code/v1/...
• Admin SPA：/t/:tenant_code/admin/...
• WeChat SPA：/t/:tenant_code/...（除 v1 与 admin 子路径）

1.2 为什么必须这样分层

• WeChat/后台前端都是 SPA，通常需要一个 catch-all 回退到 index.html
• 同时 API 又需要精确匹配，必须确保 API 路由优先于静态路由

---

2. 后端（HTTP Server）路由注册顺序建议

以 Fiber 为例，推荐顺序：

1. GET /t/:tenant_code/v1/...：注册所有 API（并注入 TenantContext 中间件）
2. GET /t/:tenant_code/admin*：回退到 Admin 的 index.html（并正确设置静态资源 base）
3. GET /t/:tenant_code/*：回退到 WeChat 的 index.html

重点：不要用全局 GET /* 直接接管，否则会吞掉 API 与 admin。

---

3. 前端（Admin）

3.1 Router base

• createWebHistory("/t/<tenant_code>/admin/")

3.2 API baseURL 推导

• 运行时从 location.pathname 提取 tenant_code
• axios baseURL = "/t/<tenant_code>/v1"

3.3 Token

• Authorization: Bearer <token>（租户后台登录返回）

---

4. 前端（WeChat H5）

4.1 Router base

• createWebHistory("/t/<tenant_code>/")

4.2 API baseURL 与 Cookie

• axios baseURL = "/t/<tenant_code>/v1"
• withCredentials = true（携带 cookie 会话）

4.3 未登录跳转

• 401 时跳：/t/<tenant_code>/v1/auth/wechat?redirect=<encodeURIComponent(currentUrl)>

---

5. tenant_code 提取规则（前端共用）

从路径 /t/<tenant_code>/... 提取第二段：

• tenant_code = decodeURIComponent(pathname.split('/')[2] || '')
• 使用时建议 tenant_code.toLowerCase()
• 允许字符集：a-z0-9_-（不允许空）

---

6. OSS Key 规则

• 统一格式：quyun/<tenant_uuid>/<md5>.<ext>
• tenant_uuid 来自 tenants.tenant_uuid
• md5 来自上传文件内容 hash