@teamix-evo/skills 0.3.0 → 0.4.0

package/src/teamix-evo-code-uni-manager/error-and-loading.md

@@ -0,0 +1,389 @@
+# 错误与加载态规范（uni-manager）
+
+> **核心约定**:渲染错误用 `ErrorBoundary`,异步加载用 `react-query` 的 `isPending/isError`(必要时叠 `Suspense`),全局兜底必须存在。**不允许**白屏 / 红屏直出给用户。**uni-manager 额外提供跨云资源专属 fallback。**
+
+---
+
+## 三层兜底
+
+```
+┌──────────────────────────────────────────┐
+│  App 根:全局 ErrorBoundary + Toaster     │  最后一道:防白屏 / 兜未捕获
+└──────────────┬───────────────────────────┘
+               │
+┌──────────────────────────────────────────┐
+│  路由 / 关键 widget:页面级 ErrorBoundary │  范围隔离:一页崩不带垮全站
+└──────────────┬───────────────────────────┘
+               │
+┌──────────────────────────────────────────┐
+│  数据 hook:isPending / isError           │  细粒度:每块数据自己的 loading
+└──────────────────────────────────────────┘
+```
+
+---
+
+## §1 · 全局 ErrorBoundary
+
+每个 teamix-evo uni-manager 业务应用**必须**在根挂一个全局 ErrorBoundary,以及一个 toast 容器。
+
+### 推荐实现:`react-error-boundary`
+
+业界主流(2024+,Vercel / shadcn 模板默认),比手写 class component 更易组合。
+
+```tsx
+// src/main.tsx
+import { ErrorBoundary } from 'react-error-boundary';
+import { QueryClientProvider, QueryClient } from '@tanstack/react-query';
+import { Toaster } from '@/components/ui';
+import { GlobalErrorFallback } from '@/components/GlobalErrorFallback';
+import { TenantProvider } from '@/contexts/TenantContext';
+import { RegionProvider } from '@/contexts/RegionContext';
+import { reportError } from '@/lib/monitor';
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: { staleTime: 30_000, retry: 1 },
+    mutations: { retry: 0 },
+  },
+});
+
+createRoot(document.getElementById('root')!).render(
+  <ErrorBoundary
+    FallbackComponent={GlobalErrorFallback}
+    onError={(err, info) => reportError(err, info)}
+  >
+    <QueryClientProvider client={queryClient}>
+      <TenantProvider>
+        <RegionProvider>
+          <App />
+          <Toaster />
+        </RegionProvider>
+      </TenantProvider>
+    </QueryClientProvider>
+  </ErrorBoundary>,
+);
+```
+
+```tsx
+// src/components/GlobalErrorFallback.tsx
+import { Button } from '@teamix-evo/ui';
+
+export function GlobalErrorFallback({
+  resetErrorBoundary,
+}: {
+  resetErrorBoundary: () => void;
+}) {
+  return (
+    <div className="flex min-h-screen items-center justify-center">
+      <div className="text-center">
+        <h1 className="text-2xl font-semibold">页面出错了</h1>
+        <p className="text-muted-foreground mt-2">
+          已记录,可尝试刷新或返回首页
+        </p>
+        <Button className="mt-4" onClick={resetErrorBoundary}>
+          重新加载
+        </Button>
+      </div>
+    </div>
+  );
+}
+```
+
+要点:
+
+- `onError` **必须**调 `reportError` 上报(Sentry / 自家日志)
+- fallback **必须**给用户可执行的下一步动作(重试 / 返回 / 联系支持)
+- 上报 extra **必须**带当前 `tenantId / regionId / cloudProvider`(便于排障)
+- **不要**只显示 "Something went wrong" —— 用户看到等于白屏
+
+---
+
+## §2 · 路由 / 页面级 ErrorBoundary
+
+跨路由的崩溃不应连带全站。在 router 配置或 Layout 里再嵌一层:
+
+```tsx
+// src/routes/index.tsx
+{
+  path: '/instances/:id',
+  element: (
+    <ErrorBoundary FallbackComponent={PageErrorFallback}>
+      <Suspense fallback={<PageSkeleton />}>
+        <InstanceDetailPage />
+      </Suspense>
+    </ErrorBoundary>
+  ),
+}
+```
+
+或使用 react-router v6.4+ 的 `errorElement`(推荐,内置):
+
+```tsx
+{
+  path: '/instances/:id',
+  element: <InstanceDetailPage />,
+  errorElement: <PageErrorFallback />,
+}
+```
+
+---
+
+## §3 · 数据加载态(react-query 范式)
+
+**不要**在组件里用 `useState<boolean>` + `useEffect` 自己管 loading。所有异步数据走 react-query:
+
+```tsx
+function InstanceListPage() {
+  const { data, isPending, isError, error, refetch } = useInstanceList(params);
+
+  if (isPending) return <TableSkeleton rows={10} />;
+  if (isError) return <ErrorPanel message={error.message} onRetry={refetch} />;
+
+  return <InstanceTable data={data} />;
+}
+```
+
+### 三种状态都要处理
+
+| 状态                   | 必须输出                                   |
+| ---------------------- | ------------------------------------------ |
+| `isPending`(首次加载)  | Skeleton / Spinner,**不允许**显示空 div    |
+| `isError`              | 错误面板 + 重试按钮,**不允许**直接 `throw` |
+| `isFetching`(后台刷新) | 表格右上角小转圈即可,不要遮罩              |
+
+### Skeleton vs Spinner 怎么选
+
+| 场景                           | 用                                 |
+| ------------------------------ | ---------------------------------- |
+| 列表 / 卡片 / 详情             | Skeleton(撑住布局,避免 CLS)        |
+| 短动作(按钮提交、< 500ms 加载) | Spinner                            |
+| 全屏切换                       | PageSkeleton 或 logo loading       |
+| 切换租户/区域(invalidate 全表) | 表格遮罩 Skeleton + topbar Spinner |
+
+---
+
+## §4 · Mutation 反馈
+
+```tsx
+const mutation = useCreateInstance();
+
+mutation.mutate(values, {
+  onSuccess: (instance) => {
+    toast.success(`实例 ${instance.id} 已创建`);
+    navigate(`/instances/${instance.id}`);
+  },
+  onError: (err) => {
+    toast.error(err.message); // 已被 lib/http.ts 归一化
+  },
+});
+```
+
+约束:
+
+- 成功 → `toast.success` + 跳转 / invalidate
+- 失败 → `toast.error`,**不要** `alert()`
+- 长操作(> 1s) → 按钮 `disabled` + 文案改"提交中…",**不要**双击重复提交
+- **不要**在 mutation 内部弹 toast —— hook 是数据通道,toast 由组件触发
+- **危险操作(删除 / 释放 / 销毁)走 `useDangerConfirm`**,见 [`forms-and-validation.md`](forms-and-validation.md) §10
+
+---
+
+## §5 · Suspense 数据边界(可选,渐进采用)
+
+react-query v5 支持 `useSuspenseQuery`,可把 loading 转给 `<Suspense>`:
+
+```tsx
+function InstanceListPage() {
+  const { data } = useSuspenseQuery({
+    queryKey: ['instances', tenantId, regionId],
+    queryFn: () => listInstances(),
+  });
+  return <InstanceTable data={data} />; // 不需要 isPending 分支
+}
+
+// 父级:
+<Suspense fallback={<TableSkeleton rows={10} />}>
+  <InstanceListPage />
+</Suspense>;
+```
+
+**何时用**:
+
+- 多个 query 需要"全部 ready 才渲染"时,Suspense 比手写 `if (a.isPending || b.isPending)` 简洁
+- 与 `React.lazy` 配合做代码分包(见 [`routing-and-codesplit.md`](routing-and-codesplit.md))
+
+**何时不用**:
+
+- 单一 query 的简单页面,直接 `isPending` 分支更直观
+- 团队对 Suspense 还不熟 → 先用 `isPending`,慢慢迁
+
+---
+
+## §6 · 全局错误上报
+
+```ts
+// src/lib/monitor.ts
+import * as Sentry from '@sentry/react';
+import {
+  getActiveTenant,
+  getActiveRegion,
+  getActiveCloudProvider,
+} from '@/lib/active-context';
+
+if (import.meta.env.PROD) {
+  Sentry.init({
+    dsn: import.meta.env.VITE_SENTRY_DSN,
+    tracesSampleRate: 0.1,
+  });
+}
+
+export function reportError(err: unknown, extra?: Record<string, unknown>) {
+  const ctx = {
+    tenantId: getActiveTenant()?.id,
+    regionId: getActiveRegion()?.id,
+    cloudProvider: getActiveCloudProvider(),
+    ...extra,
+  };
+  if (import.meta.env.DEV) console.error('[reportError]', err, ctx);
+  Sentry.captureException(err, { extra: ctx });
+}
+
+// window 级未捕获
+window.addEventListener('unhandledrejection', (e) => reportError(e.reason));
+window.addEventListener('error', (e) => reportError(e.error));
+```
+
+要点:
+
+- 所有 ErrorBoundary 的 `onError` **必须**调 `reportError`
+- 上报必须**自动带上当前 tenant/region/cloud 上下文**(不需要 component 显式传)
+- mutation `onError` 在归一化 toast 之外也应调 `reportError`
+- **不要**在 component 里直接 `import * as Sentry` —— 走 `monitor.ts` 这一层包装,便于替换
+
+---
+
+## §7 · 跨云资源专属 fallback(uni-manager 增量)
+
+跨云资源(实例、对象存储桶、网络等)有独有的失败场景:
+
+| 场景                        | HTTP 行为                                       | 推荐 UI                                                                       |
+| --------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------- |
+| 资源被云厂商侧异步删除      | 200 + `{ status: 'NotFound' }` 或 404           | `CloudResourceNotFound`:展示"资源已被删除/迁移" + 当前 cloud/region badge     |
+| 跨云聚合查询某 cloud 失败   | 部分成功(其他 cloud 仍返数据)                   | 表格保留可用数据 + 顶部黄条提示"AWS region us-east-1 暂时不可达,显示部分结果" |
+| 切换租户后旧 URL 资源不可见 | 403 + `{ code: 'TENANT_RESOURCE_NOT_VISIBLE' }` | `CrossTenantNotice`:提示"该资源属于其他租户" + 提供"切换回上一租户"快捷动作   |
+| 区域 metadata 加载失败      | 500 + `{ code: 'REGION_METADATA_UNAVAILABLE' }` | `RegionDegraded`:用上次成功的 region 元数据 + 顶部红条提示"实时数据不可用"    |
+
+### 实现示例
+
+```tsx
+// src/components/cloud/CloudResourceNotFound.tsx
+import { Button } from '@teamix-evo/ui';
+import { CloudBadge } from './CloudBadge';
+import { useNavigate } from 'react-router-dom';
+import { useTenant } from '@/hooks/useTenant';
+import { useRegion } from '@/hooks/useRegion';
+
+interface Props {
+  resourceType: string; // 实例 / 桶 / VPC ...
+  resourceId: string;
+}
+
+export function CloudResourceNotFound({ resourceType, resourceId }: Props) {
+  const navigate = useNavigate();
+  const { tenant } = useTenant();
+  const { region } = useRegion();
+  return (
+    <div className="flex flex-col items-center gap-3 py-12">
+      <h2 className="text-xl font-semibold">{resourceType} 不存在或已被删除</h2>
+      <p className="text-muted-foreground text-sm">
+        ID: <code>{resourceId}</code>
+      </p>
+      <div className="flex items-center gap-2">
+        <CloudBadge tenant={tenant} region={region} />
+      </div>
+      <p className="text-muted-foreground max-w-md text-center text-sm">
+        资源可能已在云厂商侧被释放或迁移。请检查租户/区域上下文,或返回列表查看其他资源。
+      </p>
+      <div className="mt-2 flex gap-2">
+        <Button variant="outline" onClick={() => navigate(-1)}>
+          返回
+        </Button>
+        <Button onClick={() => navigate(`/${resourceType}s`)}>返回列表</Button>
+      </div>
+    </div>
+  );
+}
+```
+
+### 详情页用法
+
+```tsx
+function InstanceDetailPage() {
+  const { id } = useParams();
+  const { data, isPending, isError, error } = useInstance(id!);
+
+  if (isPending) return <PageSkeleton />;
+  if (isError && isCloudResourceNotFound(error)) {
+    return <CloudResourceNotFound resourceType="实例" resourceId={id!} />;
+  }
+  if (isError) return <ErrorPanel message={error.message} />;
+  return <InstanceDetail data={data} />;
+}
+```
+
+要点:
+
+- `isCloudResourceNotFound(err)` 在 `lib/http.ts` 定义,统一识别 `{ status: 'NotFound' }` / 404
+- 跨云聚合查询的部分失败,在 service 层就要返回 `{ ok: [], failed: [{ cloud, region, error }] }` 结构,UI 层只展示
+- **禁止**用通用 `<ErrorPanel>` 兜底跨云资源 404 —— 必须给"上下文相关"提示
+
+---
+
+## 反模式速查
+
+| 反模式                                       | 为什么禁                          | 应该                                              |
+| -------------------------------------------- | --------------------------------- | ------------------------------------------------- |
+| 没有全局 ErrorBoundary                       | 异常直接白屏                      | App 根挂一层                                      |
+| `useState(false)` + `useEffect` 管 loading   | 重复造轮,易漏 cancel              | 走 react-query / useSuspenseQuery                 |
+| 只判 `isLoading` 不判 `isError`              | 错误态显示空白                    | 三态都处理                                        |
+| `if (data) return <>...</> else return null` | 无 skeleton,布局抖动 + CLS        | 加 Skeleton                                       |
+| `alert('保存失败')`                          | 阻断用户、丑、不可样式化          | `toast.error()`                                   |
+| ErrorBoundary 不上报                         | 错过线上 bug                      | `onError` 接 `reportError`                        |
+| reportError 不带 tenant/region 上下文        | 排障无法定位                      | `monitor.ts` 自动注入 active context              |
+| service 里 `try/catch` 吞错                  | 上层失去判断依据                  | 让 error 抛上来,hook / boundary 决定              |
+| 跨云资源 404 用通用 ErrorPanel 兜底          | 用户看不出是上下文问题            | 用 `CloudResourceNotFound` + cloud/region badge   |
+| 跨云聚合查询全或全无                         | 一个 region 失败,其他可用结果丢失 | service 层返结构化结果,UI 显示部分成功 + 失败提示 |
+
+---
+
+## 与 ui 包的边界
+
+`@teamix-evo/ui` 提供:
+
+- `Skeleton` / `TableSkeleton` / `PageSkeleton`
+- `Toaster` + `toast()` API
+- `Spinner`(短动作)
+- `EmptyState`(无数据态,区别于错误态)
+
+**优先用 ui 包**,不要自己撸 spinner / toast。
+
+uni-manager 工程内**额外**提供(后续抽到 biz-ui/uni-manager):
+
+- `CloudResourceNotFound`(跨云资源 404)
+- `CrossTenantNotice`(跨租户访问提示)
+- `RegionDegraded`(区域降级提示)
+
+---
+
+## AI 必须输出的错误处理日志
+
+```
+## 错误 / 加载态
+
+- 全局: ✅ App 根 ErrorBoundary + reportError 已存在(自动带 tenant/region/cloud)
+- 页面: ✅ /instances/:id 加 errorElement + Suspense fallback
+- 数据: ✅ useInstanceList 三态都处理(Skeleton / ErrorPanel / Table)
+- Mutation: ✅ onSuccess toast + navigate;onError toast(已归一化)
+- 跨云 404: ✅ /instances/:id 区分 isCloudResourceNotFound,显示 CloudResourceNotFound
+- 危险操作: ✅ 释放/删除走 useDangerConfirm
+```