init

specs/ROUTING.md

@@ -0,0 +1,80 @@
+# 新项目路由与部署规则（多租户路径前缀）
+
+## 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
+