@teamix-evo/skills 0.3.0 → 0.4.0

package/src/teamix-evo-code-uni-manager/routing-and-codesplit.md

@@ -0,0 +1,450 @@
+# 路由与代码分包规范（uni-manager）
+
+> **核心约定**:页面级 `React.lazy` 默认分包,鉴权 / 角色守卫集中在 `src/routes/`,404 / 401 / 403 必有兜底。**uni-manager 额外约定:tenantId / regionId / cloudProvider 同步到 URL search params,um-topbar 切换上下文时改写 URL。**
+
+---
+
+## 路由库选型
+
+teamix-evo uni-manager preset 默认 `react-router-dom@6`(Data Router 模式,业界主流)。
+
+| 候选                             | 何时选                               |
+| -------------------------------- | ------------------------------------ |
+| `react-router-dom@6` Data Router | **默认**。中后台 / SPA / 多页应用    |
+| `@tanstack/react-router`         | 类型安全要求极高、复杂 search params |
+| 文件路由(Next.js / Remix)        | 不在本 preset 范围                   |
+
+**一个项目只用一种**。已经用了 react-router 就不要混入 tanstack-router。
+
+---
+
+## §1 · 路由文件组织
+
+```
+src/routes/
+├── index.tsx              # createBrowserRouter 声明(单一来源)
+├── guards.tsx             # AuthGuard、RoleGuard、TenantContextGuard
+├── paths.ts               # 路径常量集中(避免魔法字符串)
+└── lazy.tsx               # 统一的 lazy() 工厂,可选
+```
+
+**约定**:
+
+- 路由声明**只在** `src/routes/index.tsx`,不要散在多个 layout / page 里
+- 页面文件**默认 default export**,便于 `React.lazy`
+- 嵌套路由用 `children`,layout 用 `<Outlet />`
+
+### 标准声明
+
+```tsx
+// src/routes/index.tsx
+import { createBrowserRouter } from 'react-router-dom';
+import { lazy } from 'react';
+import { ConsoleLayout } from '@/layouts/ConsoleLayout';
+import { AuthGuard, TenantContextGuard } from './guards';
+import { PageErrorFallback } from '@/components/PageErrorFallback';
+
+const DashboardPage = lazy(() => import('@/pages/dashboard'));
+const InstanceListPage = lazy(() => import('@/pages/instances'));
+const InstanceDetailPage = lazy(() => import('@/pages/instances/[id]'));
+const LoginPage = lazy(() => import('@/pages/login'));
+const NotFoundPage = lazy(() => import('@/pages/_not-found'));
+
+export const router = createBrowserRouter([
+  {
+    path: '/login',
+    element: <LoginPage />,
+  },
+  {
+    element: (
+      <AuthGuard>
+        <TenantContextGuard>
+          <ConsoleLayout />
+        </TenantContextGuard>
+      </AuthGuard>
+    ),
+    errorElement: <PageErrorFallback />,
+    children: [
+      { path: '/', element: <DashboardPage /> },
+      { path: '/instances', element: <InstanceListPage /> },
+      { path: '/instances/:id', element: <InstanceDetailPage /> },
+    ],
+  },
+  { path: '*', element: <NotFoundPage /> },
+]);
+```
+
+---
+
+## §2 · 代码分包(默认开启)
+
+### 规则
+
+- **每个页面文件**用 `React.lazy()` 引入 → vite 自动 chunk
+- 重型第三方库(图表、富文本、PDF、地图、监控可视化)用动态 import 包一层组件
+- 同一 layout 下的多个 page 自动共享 layout chunk —— 不需要手动配
+
+### 不分包的例外
+
+- 登录页 / 错误页 / 404 → **不分包**(否则首屏要等 chunk 加载)
+- 主 layout / um-topbar / Sidebar → **不分包**(立即用到)
+- < 5 KB 的小页面 → 分不分都行,默认分
+
+### 动态 import 重型库
+
+```tsx
+// ❌ 顶部 import:整个图表库进首屏 bundle
+import { LineChart } from 'recharts';
+
+// ✅ 用到时再加载
+const LineChart = lazy(() =>
+  import('recharts').then((m) => ({ default: m.LineChart })),
+);
+
+<Suspense fallback={<ChartSkeleton />}>
+  <LineChart data={data} />
+</Suspense>;
+```
+
+---
+
+## §3 · Suspense 配合
+
+每个 lazy 页面**必须**有 Suspense 兜底,否则首次进入会抛错。
+
+最佳实践:在 layout / route 配置里挂一次,所有 children 共享:
+
+```tsx
+// src/layouts/ConsoleLayout.tsx
+import { Outlet } from 'react-router-dom';
+import { Suspense } from 'react';
+import { Topbar } from 'biz-ui/uni-manager/um-topbar';
+
+export function ConsoleLayout() {
+  return (
+    <div className="flex h-screen flex-col">
+      <Topbar />
+      <div className="flex flex-1 overflow-hidden">
+        <Sidebar />
+        <main className="flex-1 overflow-auto">
+          <Suspense fallback={<PageSkeleton />}>
+            <Outlet />
+          </Suspense>
+        </main>
+      </div>
+    </div>
+  );
+}
+```
+
+---
+
+## §4 · 鉴权 / 角色 / 租户上下文守卫
+
+### 模式:守卫组件包路由
+
+```tsx
+// src/routes/guards.tsx
+import { Navigate, useLocation, useSearchParams } from 'react-router-dom';
+import { useEffect } from 'react';
+import { useCurrentUser } from '@/hooks/useCurrentUser';
+import { useTenant } from '@/hooks/useTenant';
+import { useRegion } from '@/hooks/useRegion';
+
+export function AuthGuard({ children }: { children: React.ReactNode }) {
+  const { data: user, isPending } = useCurrentUser();
+  const location = useLocation();
+
+  if (isPending) return <PageSkeleton />;
+  if (!user) {
+    return <Navigate to="/login" state={{ from: location.pathname }} replace />;
+  }
+  return <>{children}</>;
+}
+
+export function RoleGuard({
+  roles,
+  children,
+}: {
+  roles: string[];
+  children: React.ReactNode;
+}) {
+  const { data: user } = useCurrentUser();
+  if (!user || !roles.some((r) => user.roles.includes(r))) {
+    return <Navigate to="/_forbidden" replace />;
+  }
+  return <>{children}</>;
+}
+
+/**
+ * uni-manager 专用:URL search params 与 active tenant/region 双向同步。
+ * - URL 有 ?tenant=t-x → 切到 t-x(若用户有权)
+ * - URL 没有但有 active → 写回 URL(分享/刷新可还原)
+ */
+export function TenantContextGuard({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const [searchParams, setSearchParams] = useSearchParams();
+  const { tenant, setTenant, isAvailable } = useTenant();
+  const { region, setRegion } = useRegion();
+
+  useEffect(() => {
+    const urlTenant = searchParams.get('tenant');
+    const urlRegion = searchParams.get('region');
+
+    // URL → state(优先)
+    if (urlTenant && urlTenant !== tenant?.id) {
+      if (isAvailable(urlTenant)) {
+        setTenant(urlTenant);
+      } else {
+        // URL 中租户不可用:回退并清掉 URL 参数
+        searchParams.delete('tenant');
+        setSearchParams(searchParams, { replace: true });
+      }
+    }
+    if (urlRegion && urlRegion !== region?.id) {
+      setRegion(urlRegion);
+    }
+
+    // state → URL(状态先有,URL 没写)
+    const next = new URLSearchParams(searchParams);
+    if (tenant && !next.get('tenant')) next.set('tenant', tenant.id);
+    if (region && !next.get('region')) next.set('region', region.id);
+    if (next.toString() !== searchParams.toString()) {
+      setSearchParams(next, { replace: true });
+    }
+  }, [
+    searchParams,
+    tenant,
+    region,
+    setTenant,
+    setRegion,
+    setSearchParams,
+    isAvailable,
+  ]);
+
+  if (!tenant) return <PageSkeleton />; // 还没初始化好
+  return <>{children}</>;
+}
+```
+
+### 反模式
+
+- ❌ 每个页面顶部都写 `if (!user) navigate('/login')` —— 抽到守卫
+- ❌ 把角色判断写在 sidebar / button 的渲染逻辑里(只能藏入口,无法防直接访问 URL)—— 路由层判 + UI 层判,**两层都要**
+- ❌ 守卫里直接 fetch 用户信息 —— 走 `useCurrentUser` hook,享受缓存
+- ❌ 切租户时只改 active-context 不改 URL —— 刷新就丢
+
+---
+
+## §5 · 必须存在的兜底路由
+
+每个项目**必须**有这三个页面,放在 `src/pages/_xxx/`(下划线前缀,表示非业务路由):
+
+| 路径                | 文件                             | 触发场景                          |
+| ------------------- | -------------------------------- | --------------------------------- |
+| `*` (404)           | `src/pages/_not-found/index.tsx` | 任何未匹配的 URL                  |
+| `/_forbidden` (403) | `src/pages/_forbidden/index.tsx` | 角色无权访问 / 租户无权访问该资源 |
+| `/_error` (500)     | `src/pages/_error/index.tsx`     | router `errorElement` 兜底        |
+
+未登录(401)由 `AuthGuard` 重定向到 `/login`,**不**单独建页面。
+
+---
+
+## §6 · search params 与状态同步
+
+列表页的筛选 / 分页 / 排序参数**必须**写进 URL,刷新 / 分享 / 浏览器后退都要还原:
+
+```tsx
+import { useSearchParams } from 'react-router-dom';
+
+function InstanceListPage() {
+  const [searchParams, setSearchParams] = useSearchParams();
+  const status = searchParams.get('status') ?? 'all';
+  const page = Number(searchParams.get('page') ?? 1);
+
+  const { data } = useInstanceList({ status, page });
+
+  return (
+    <Toolbar
+      status={status}
+      onStatusChange={(s) =>
+        setSearchParams({ status: s, page: '1' }, { replace: true })
+      }
+    />
+  );
+}
+```
+
+复杂场景用 [`nuqs`](https://nuqs.47ng.com/) 做类型化包装,业界常见。
+
+反模式:
+
+- ❌ 筛选状态只放 `useState` —— 刷新就丢
+- ❌ 分页放 store —— 多 tab 各自分页会互相污染
+
+---
+
+## §7 · 导航与跳转
+
+```tsx
+import { useNavigate, Link } from 'react-router-dom';
+
+// 声明式(链接)
+<Link to={`/instances/${instance.id}`}>查看</Link>;
+
+// 命令式(mutation success)
+const navigate = useNavigate();
+mutation.mutate(values, {
+  onSuccess: (instance) => navigate(`/instances/${instance.id}`),
+});
+```
+
+约束:
+
+- 静态跳 → `<Link>`(可右键打开新 tab)
+- 动态跳(提交后) → `useNavigate()`
+- **不要** `window.location.href = ...`(整页刷新,丢状态)
+- 外链 → 普通 `<a href target="_blank" rel="noopener noreferrer">`
+
+---
+
+## §8 · uni-manager 专属:tenant/region/cloud URL 同步
+
+### 三套 search params 的标准约定
+
+| 参数       | 值                          | 由谁写           | 由谁读                               |
+| ---------- | --------------------------- | ---------------- | ------------------------------------ |
+| `?tenant=` | tenantId                    | um-topbar 切换时 | TenantContextGuard / TenantProvider  |
+| `?region=` | regionId                    | um-topbar 切换时 | TenantContextGuard / RegionProvider  |
+| `?cloud=`  | cloudProvider(aws/aliyun..) | 跨云页面 toolbar | 跨云 service hook(覆盖 active cloud) |
+
+### um-topbar 集成示例
+
+`biz-ui/uni-manager/um-topbar` 暴露 `onTenantChange` / `onRegionChange` 钩子,业务工程**必须**在这里改写 URL:
+
+```tsx
+// src/layouts/ConsoleLayout.tsx
+import { Topbar } from 'biz-ui/uni-manager/um-topbar';
+import { useSearchParams } from 'react-router-dom';
+import { useTenant } from '@/hooks/useTenant';
+import { useRegion } from '@/hooks/useRegion';
+
+export function ConsoleLayout() {
+  const [searchParams, setSearchParams] = useSearchParams();
+  const { tenant, setTenant } = useTenant();
+  const { region, setRegion } = useRegion();
+
+  return (
+    <Topbar
+      tenant={tenant}
+      region={region}
+      onTenantChange={(t) => {
+        setTenant(t.id); // 1. 写 active-context + invalidate query
+        const next = new URLSearchParams(searchParams);
+        next.set('tenant', t.id);
+        setSearchParams(next); // 2. URL 同步
+      }}
+      onRegionChange={(r) => {
+        setRegion(r.id);
+        const next = new URLSearchParams(searchParams);
+        next.set('region', r.id);
+        setSearchParams(next);
+      }}
+    />
+  );
+}
+```
+
+> 顺序很重要:**先**改 active-context(让正在飞的请求被取消 / 后续请求带新 header),**再**改 URL(否则 URL 改完触发 guard,guard 看到 URL/state 不一致又改一次,产生抖动)。
+
+### 跨页面跳转保留上下文
+
+业务页面跳转时,URL 中的 `tenant` / `region` 需要继承:
+
+```tsx
+// ✅ 用工具函数保留 search
+import { withContextSearch } from '@/lib/url';
+
+navigate(withContextSearch(`/instances/${id}`));
+// 等价于 /instances/i-1?tenant=t-x&region=cn-hangzhou
+
+// ❌ 直接拼会丢上下文
+navigate(`/instances/${id}`);
+```
+
+```ts
+// src/lib/url.ts
+import { getActiveTenant, getActiveRegion } from '@/lib/active-context';
+
+export function withContextSearch(path: string): string {
+  const url = new URL(path, window.location.origin);
+  const tenant = getActiveTenant();
+  const region = getActiveRegion();
+  if (tenant && !url.searchParams.has('tenant'))
+    url.searchParams.set('tenant', tenant.id);
+  if (region && !url.searchParams.has('region'))
+    url.searchParams.set('region', region.id);
+  return url.pathname + url.search;
+}
+```
+
+---
+
+## 反模式速查
+
+| 反模式                             | 为什么禁               | 应该                                   |
+| ---------------------------------- | ---------------------- | -------------------------------------- |
+| 全部页面顶部 `import` 不 lazy      | 首屏 bundle 爆炸       | `React.lazy` 每页                      |
+| Lazy 但没 Suspense 兜底            | 进入页面报错           | Layout 挂一次 Suspense                 |
+| 鉴权写在每个 page 里               | 散乱、易漏             | 守卫组件 + 路由层                      |
+| 路由声明分散在多处                 | 难维护、易循环         | 唯一在 `src/routes/index.tsx`          |
+| 列表筛选状态不进 URL               | 刷新 / 分享 / 后退失效 | `useSearchParams`                      |
+| `window.location.href` 跳转        | 整页刷新               | `useNavigate` / `<Link>`               |
+| 路由 path 写魔法字符串             | 改路径漏改             | 抽 `src/routes/paths.ts` 集中          |
+| 自建 Topbar 替代 um-topbar         | UM1 红线               | 用 `biz-ui/uni-manager/um-topbar`      |
+| 切租户只改 state 不写 URL          | 刷新丢上下文           | `TenantContextGuard` + topbar 双向同步 |
+| 切租户先改 URL 再改 active-context | guard 抖动             | 先 setTenant,再 setSearchParams        |
+| 跳转时不带 tenant/region search    | 跳后丢上下文           | `withContextSearch(path)` 工具函数     |
+
+---
+
+## 进阶:Loader / Action(react-router v6.4+)
+
+如果项目愿意采用 Data Router 的 `loader` / `action` 模式,可把数据预取下沉到路由层:
+
+```tsx
+{
+  path: '/instances/:id',
+  element: <InstanceDetailPage />,
+  loader: async ({ params }) => {
+    return queryClient.ensureQueryData({
+      queryKey: ['instance', getActiveTenant()?.id, params.id],
+      queryFn: () => getInstance(params.id!),
+    });
+  },
+}
+```
+
+收益:页面切换时数据并行加载(不是渲染后才发请求),首屏更快。
+
+**慎用**:loader 写多了和 hook 形成两套数据流,需团队约定清楚。建议先用 hook + Suspense,熟练后再考虑 loader。
+
+---
+
+## AI 必须输出的路由日志
+
+```
+## 路由 / 分包改动
+
+- src/routes/index.tsx: 注册 /instances、/instances/:id(均 React.lazy)
+- src/pages/instances/index.tsx: default export(便于 lazy)
+- 守卫: ✅ 包在 AuthGuard + TenantContextGuard 下
+- Suspense: ✅ ConsoleLayout 已挂一次,新增页面共用
+- search params: ✅ status / page 用 useSearchParams
+- uni-manager 上下文: ✅ tenant / region 同步到 URL,um-topbar 切换改写
+- 跳转保留上下文: ✅ 用 withContextSearch 工具函数
+- 兜底: ✅ * → NotFoundPage、/_forbidden、/_error 已存在
+```