@teamix-evo/skills 0.2.0 → 0.4.0

package/src/teamix-evo-code-uni-manager/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: teamix-evo-code-uni-manager
+description: |
+  Enforce teamix-evo coding conventions in uni-manager (hybrid-cloud / multi-tenant console) consumer apps — reuse-first against `@teamix-evo/ui` registry + `biz-ui/uni-manager` (um-topbar / CloudBadge), API code under `src/services/` with tenant / region context propagation, `src/` layering and import boundaries.
+  TRIGGER when: user asks to "新增 / 重构 / 写一个" 组件 / 页面 / 接口 / 钩子 / 工具 / hook in a hybrid-cloud / 专有云 / 多租户 / 多区域 console; phrases like "create a CRUD page"、"add an API call"、"extract a hook"、"refactor this fetch"、"调一下接口"、"加个组件"、"加个按钮"; file write under `src/pages/**`、`src/components/**`、`src/services/**`、`src/hooks/**`; AI is about to write any new `.tsx` / `.ts` file in a teamix-evo-installed uni-manager-variant project.
+  SKIP: pure visual / layout design questions about an already-existing screen with no code change (defer to teamix-evo-design-uni-manager); teamix-evo lifecycle (init / update / uninstall) — those go to teamix-evo-manage; changes only to design tokens / styles / theme — those go to ESLint and `tokens.overrides.css`.
+  Coordinates with: teamix-evo-design-uni-manager (run alongside when the change also creates a UI screen — design handles the visual side, this skill handles file placement and reuse).
+---
+
+# teamix-evo-code-uni-manager
+
+This skill bundles the **AI-readable engineering conventions** for **uni-manager-variant** consumer business apps — products that target hybrid-cloud / 专有云 / 多租户 / 多区域 management consoles. It complements [`teamix-evo-design-uni-manager`](../teamix-evo-design-uni-manager/SKILL.md) — design tells AI _what a screen should look like_; this skill tells AI _where the code should live, what to reuse before writing new code, and how to thread tenant / region / cloud-provider context through the layers_.
+
+<!-- teamix-evo:managed:start id="core" -->
+
+## When to use
+
+Activate this skill whenever AI is about to **write or refactor code** inside a uni-manager-variant consumer app. Common signals:
+
+- "新增一个 xxx 页面 / 列表页 / 详情页（控制台 / 工作台 / 多云资源）"
+- "加一个 xxx 接口 / 调用 xxx API（多租户 / 跨云 / 跨账号）"
+- "写一个 xxx 组件"
+- "把这段重构一下"
+- "create a CRUD page for 多云实例"
+- "add an API call to list instances across regions"
+- Any time AI is about to create a new file under `src/pages/`、`src/components/`、`src/services/`、`src/hooks/` in a hybrid-cloud console
+
+If the task is purely about _visual design_ of a screen, use [`teamix-evo-design-uni-manager`](../teamix-evo-design-uni-manager/SKILL.md) instead — or run both in tandem.
+
+## What this skill does
+
+Before AI writes or commits code, it performs an **8-step gated flow**. Steps 1-4 are baseline (always run); steps 5-7 are topic gates (run when the task touches that topic); step 8 is the final self-review.
+
+1. **Reuse-first check** — read [`reuse-first.md`](reuse-first.md). Before creating any new component, query the `@teamix-evo/ui` registry (via MCP `list_components` / `find_components`), the **biz-ui/uni-manager** layer (um-topbar / CloudBadge / ContextSwitcher placeholders), and grep the local project. Only write new code when no reuse path exists. **组件兜底铁律**：找不到时优先 ui 原子件组合，**禁止**自撸基础件。
+2. **Layering check** — read [`api-layering.md`](api-layering.md). Any code that talks to a backend goes under `src/services/<domain>.ts`; multi-tenant / multi-region / multi-cloud context (tenantId / regionId / cloudProvider) is **propagated through `lib/http.ts` interceptors**, not as ad-hoc params per call. Components never call `fetch` / `axios` directly. Data hooks live in `src/hooks/` and consume services.
+3. **Directory check** — read [`file-structure.md`](file-structure.md). Place the new file under the right top-level folder; uni-manager-specific shells (TenantContext / RegionContext / CloudBadge) have conventional locations.
+4. **Forms gate** — if the task involves a form, read [`forms-and-validation.md`](forms-and-validation.md). `react-hook-form` + `zod`; schema lives at `src/services/<domain>.schema.ts`. Dangerous operations (delete / release / destroy) **must** route through `useDangerConfirm` (input resource name).
+5. **Error/loading gate** — if the task adds a page or data hook, read [`error-and-loading.md`](error-and-loading.md). Ensure global ErrorBoundary, page-level fallback, and three-state handling (`isPending` / `isError` / data) are in place; mutations report success/error via `toast`. Cross-cloud resource-not-found has a dedicated fallback.
+6. **Routing gate** — if the task adds a route or page-entry, read [`routing-and-codesplit.md`](routing-and-codesplit.md). Pages use `React.lazy`; auth/role guards live in `src/routes/guards.tsx`; **list-page filters MUST sync `tenantId` / `regionId` / `cloudProvider` into URL search params**; um-topbar context switch rewrites the current URL.
+7. **Testing gate** — read [`testing.md`](testing.md). Pure functions and zod schemas are **mandatory** to test; tenant-context-aware http handlers must be covered by msw.
+8. **Self-review** — run [`checklist.md`](checklist.md). Every item must pass before declaring the change done.
+
+## Inputs the user provides
+
+- Intent: "add a page", "add a service call", "refactor X", "extract a hook", etc.
+- Optional: domain entity (`instance`、`database`、`tenant`、`workorder`、`audit-log`)
+- Optional: existing file the change should land near
+- Optional: cloud-provider scope（only-aliyun / multi-cloud / private-only）
+
+## Outputs
+
+- Code placed under the conventional path
+- Reuse decisions explicitly logged ("reused `Button` from `@teamix-evo/ui`" / "reused `um-topbar` from `biz-ui/uni-manager`" / "no match found, wrote a new `OrderCard`")
+- Tenant / region / cloud context propagation logged
+- Pass / fail status against [`checklist.md`](checklist.md)
+
+## How to invoke (typical flow)
+
+1. Parse user intent → identify which artifact is being created (page / component / service / hook / util / form / route)
+2. Read [`reuse-first.md`](reuse-first.md) and run the reuse query (MCP first, then biz-ui/uni-manager, then local grep)
+3. Read [`file-structure.md`](file-structure.md) to pick the destination directory
+4. If the change touches network / backend, read [`api-layering.md`](api-layering.md) — confirm tenant / region / cloud headers are injected via interceptor
+5. If the change involves a form, read [`forms-and-validation.md`](forms-and-validation.md) — for dangerous operations, plug `useDangerConfirm`
+6. If the change adds a page / data hook, read [`error-and-loading.md`](error-and-loading.md) for fallback / Skeleton / toast wiring
+7. If the change adds a route or page entry, read [`routing-and-codesplit.md`](routing-and-codesplit.md) — confirm tenant / region URL sync
+8. Decide test coverage per [`testing.md`](testing.md); write `*.test.ts(x)` next to source
+9. Write the code; cite each reuse / new-write decision in the response
+10. Run through [`checklist.md`](checklist.md); list pass / fail explicitly
+
+## Files in this skill
+
+| File                                                   | Purpose                                                                                              |
+| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
+| [`reuse-first.md`](reuse-first.md)                     | 复用决策流（ui 原子件 + biz-ui/uni-manager + 本项目）；组件兜底铁律                                  |
+| [`file-structure.md`](file-structure.md)               | 顶层 `src/` 目录骨架、归属、import 边界、命名、全局态分级（含 TenantContext / RegionContext）        |
+| [`api-layering.md`](api-layering.md)                   | API 三层结构 + 多租户 / 多区域 / 跨云上下文注入                                                      |
+| [`forms-and-validation.md`](forms-and-validation.md)   | `react-hook-form` + `zod`；危险操作走 `useDangerConfirm`（输入资源名称确认）                         |
+| [`error-and-loading.md`](error-and-loading.md)         | 全局 / 页面 ErrorBoundary、三态、Suspense、toast、跨云资源专属 fallback                              |
+| [`routing-and-codesplit.md`](routing-and-codesplit.md) | `React.lazy`、guards、404/403/500、tenant/region/cloud 进 URL search params、um-topbar 切换 URL 改写 |
+| [`testing.md`](testing.md)                             | `vitest` + RTL + msw、就近 test、tenant-context handler 覆盖                                         |
+| [`checklist.md`](checklist.md)                         | 多段自检，含 uni-manager 红线（自建 topbar / 不带租户上下文 / 危险操作未输入名称）                   |
+
+## Relationship to other skills
+
+- [`teamix-evo-design-uni-manager`](../teamix-evo-design-uni-manager/SKILL.md) — visual / interaction rules for uni-manager screen generation. Run **alongside** this skill when the task includes UI; this skill never overrides design on visual concerns.
+- [`teamix-evo-code-opentrek`](../teamix-evo-code-opentrek/SKILL.md) — sister code skill for OpenTrek variant. The two skills share 80% of conventions (file structure / layering / forms / testing); uni-manager-specific deltas are in this skill's SKILL/reuse-first/api-layering/routing/checklist.
+- [`teamix-evo-manage`](../teamix-evo-manage/SKILL.md) — lifecycle (`init` / `update` / `uninstall` / `skills add`). Out of scope here.
+
+## Why these conventions（uni-manager 视角）
+
+- **Single source for UI** — `@teamix-evo/ui` 89 原子件 + `biz-ui/uni-manager`（当前 1 实物 um-topbar，其余如 CloudBadge / ContextSwitcher 是概念占位）。Re-implementing 顶部 topbar / 基础件会破坏一致性三件套（UM1/UM2/UM3）。
+- **Stable seams for change** — tenant / region / cloud 上下文集中在 `lib/http.ts` interceptor 与 `contexts/TenantContext.tsx`，新增云厂商或区域不需要改 89 处 service 调用。
+- **Predictable file location** — 所有 uni-manager 项目目录形状一致；新接手的人 5 分钟内能找到「租户切换在哪管」「跨云列表怎么写」「危险操作怎么二次确认」。
+
+<!-- teamix-evo:managed:end -->

package/src/teamix-evo-code-uni-manager/api-layering.md

@@ -0,0 +1,370 @@
+# API 数据层规范（uni-manager）
+
+> **核心原则**：组件不直接 fetch。所有与后端通信的代码都落在 `src/services/`，通过 `src/hooks/` 暴露给组件。
+>
+> **uni-manager 增强**：多租户 / 多区域 / 跨云上下文（tenantId / regionId / cloudProvider）通过 **`src/lib/http.ts` 的 request interceptor 自动注入**，service 函数与 hook 不感知；只有"显式跨上下文"的少数 API 才在调用处显式覆盖。
+
+---
+
+## 三层结构
+
+```
+┌────────────────────────────────────┐
+│  src/pages/, src/components/       │  组件层：消费 hook，渲染 UI
+│  - 不调用 fetch / axios            │
+│  - 不直接读 process.env             │
+│  - 不拼 URL                        │
+│  - 不直接读 tenantId / regionId    │  ← uni-manager 强化：通过 useTenant() / useRegion() hook 读
+└──────────────┬─────────────────────┘
+               │ 仅通过 hook
+               ▼
+┌────────────────────────────────────┐
+│  src/hooks/use<Domain>*.ts         │  Hook 层：状态管理 + 缓存
+│  - 包装请求生命周期                 │
+│  - 处理缓存 / 重试 / 失效           │
+│  - 不写具体的 URL / payload 拼装    │
+│  - queryKey 含 tenantId / regionId │  ← uni-manager 强化：键值带上下文
+└──────────────┬─────────────────────┘
+               │ 调用纯函数
+               ▼
+┌────────────────────────────────────┐
+│  src/services/<domain>.ts          │  Service 层：请求纯函数
+│  - 输入参数 → 输出 Promise<T>      │
+│  - 拼 URL / 序列化 / 反序列化       │
+│  - 不依赖 React                    │
+│  - 不显式拼 tenantId / regionId    │  ← uni-manager：让 interceptor 注入
+└──────────────┬─────────────────────┘
+               │
+               ▼
+┌────────────────────────────────────┐
+│  src/lib/http.ts                   │  传输层：axios / fetch wrapper
+│  - 鉴权 / baseURL / 错误归一化      │
+│  - **租户 / 区域 / 云厂商 header 注入**  ← uni-manager 集中点
+│  - 全局 interceptor                │
+└────────────────────────────────────┘
+```
+
+---
+
+## §1 · `src/services/` 约定
+
+### 文件组织
+
+按**领域**（domain）拆，**不**按 HTTP 动词拆。
+
+```
+src/services/
+├── instance.ts       # 实例领域：list / get / create / start / stop / release
+├── database.ts       # 数据库领域
+├── tenant.ts         # 租户管理（meta，不是上下文）
+├── region.ts         # 区域元数据
+├── audit-log.ts      # 操作日志
+└── index.ts          # 统一 re-export（可选）
+```
+
+❌ 不要按动词拆：`getInstances.ts` / `createInstance.ts` —— 会爆文件数。
+
+### 函数签名约定（uni-manager）
+
+```ts
+// src/services/instance.ts
+import { http } from '@/lib/http';
+import type {
+  Instance,
+  InstanceListParams,
+  CreateInstanceInput,
+} from '@/types/instance';
+
+// ✅ 标准：service 不显式拼 tenantId / regionId / cloudProvider
+//    interceptor 会从当前 TenantContext 读取并加 header
+export async function listInstances(
+  params: InstanceListParams,
+): Promise<Instance[]> {
+  const { data } = await http.get('/api/instances', { params });
+  return data.list;
+}
+
+export async function getInstance(id: string): Promise<Instance> {
+  const { data } = await http.get(`/api/instances/${id}`);
+  return data;
+}
+
+export async function createInstance(
+  input: CreateInstanceInput,
+): Promise<Instance> {
+  const { data } = await http.post('/api/instances', input);
+  return data;
+}
+
+// ✅ 显式跨上下文：少数场景需要"在 A 租户读 B 租户的数据"
+//    通过 axios config 的 headers 显式覆盖
+export async function listInstancesAcrossTenants(
+  params: InstanceListParams,
+  contextOverride: { tenantId: string; regionId?: string },
+): Promise<Instance[]> {
+  const { data } = await http.get('/api/instances', {
+    params,
+    headers: {
+      'X-Tenant-Id': contextOverride.tenantId,
+      ...(contextOverride.regionId && {
+        'X-Region-Id': contextOverride.regionId,
+      }),
+    },
+  });
+  return data.list;
+}
+```
+
+要点：
+
+- **纯函数**（不依赖 React 上下文，可以在 SSR / Node 测试中单独跑）
+- **类型来自 `src/types/`**，不要在 service 文件里就地定义 domain 类型
+- **错误不在 service 层处理** —— 抛出去给 hook / 全局 interceptor 处理（归一化在 `src/lib/http.ts`）
+- **不写 console.log / 业务弹窗**
+- **不显式拼 tenantId / regionId** —— 让 interceptor 注入；显式覆盖只用于跨上下文场景
+
+### 反模式
+
+- ❌ `fetch('https://api.example.com/...')` 写死 host
+- ❌ 每个 service 函数加 `tenantId: string` 参数 —— 应该走 interceptor
+- ❌ service 函数返回 `{ loading, data, error }`（那是 hook 该做的）
+- ❌ 在 service 里 `import { toast } from 'sonner'`
+- ❌ 一个 service 函数同时拼 URL、做业务计算、改全局 store
+
+---
+
+## §2 · `src/hooks/` 约定
+
+### 命名
+
+- Query 类：`useInstanceList`、`useInstance(id)`、`useUserProfile`
+- Mutation 类：`useCreateInstance`、`useReleaseInstance`、`useUpdateUser`
+
+### 实现（以 `@tanstack/react-query` 为例 — uni-manager 增强 queryKey）
+
+```ts
+// src/hooks/useInstanceList.ts
+import { useQuery } from '@tanstack/react-query';
+import { listInstances } from '@/services/instance';
+import { useTenant } from '@/contexts/TenantContext';
+import { useRegion } from '@/contexts/RegionContext';
+import type { InstanceListParams } from '@/types/instance';
+
+export function useInstanceList(params: InstanceListParams) {
+  const { tenantId } = useTenant();
+  const { regionId } = useRegion();
+  return useQuery({
+    // ✅ queryKey 含 tenantId / regionId，租户切换自动失效
+    queryKey: ['instances', tenantId, regionId, params],
+    queryFn: () => listInstances(params),
+    staleTime: 30_000,
+  });
+}
+```
+
+```ts
+// src/hooks/useCreateInstance.ts
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { createInstance } from '@/services/instance';
+import { useTenant } from '@/contexts/TenantContext';
+
+export function useCreateInstance() {
+  const qc = useQueryClient();
+  const { tenantId } = useTenant();
+  return useMutation({
+    mutationFn: createInstance,
+    // ✅ 仅失效当前租户的列表，不影响其他租户缓存
+    onSuccess: () =>
+      qc.invalidateQueries({ queryKey: ['instances', tenantId] }),
+  });
+}
+```
+
+### 反模式
+
+- ❌ Hook 里再次拼 URL（违反"service 拼 URL"边界）
+- ❌ queryKey 不包含 tenantId / regionId —— 切换租户后旧数据被复用
+- ❌ 一个 hook 调多个 service 把数据缝合 —— 缝合应该在 service 层
+- ❌ Hook 里写业务跳转 / 路由切换 —— 由组件接 `mutation.onSuccess` callback 处理
+- ❌ 在 hook 里手动加 `tenantId` 到 service 入参 —— 走 interceptor
+
+---
+
+## §3 · `src/lib/http.ts` 约定（uni-manager 关键集中点）
+
+**全局只能有一份 http 实例**。提供：
+
+- `baseURL`（从 env）
+- 鉴权 header 注入
+- **租户 / 区域 / 云厂商 header 注入**（uni-manager 核心）
+- 错误归一化
+- 请求 ID / trace header
+
+```ts
+// src/lib/http.ts
+import axios from 'axios';
+import {
+  getActiveTenant,
+  getActiveRegion,
+  getActiveCloudProvider,
+} from '@/lib/active-context';
+
+export const http = axios.create({
+  baseURL: import.meta.env.VITE_API_BASE,
+  timeout: 15_000,
+});
+
+http.interceptors.request.use((config) => {
+  // 鉴权
+  const token = localStorage.getItem('token');
+  if (token) config.headers.Authorization = `Bearer ${token}`;
+
+  // ✅ uni-manager 核心：注入上下文 header
+  //    若调用方已在 config.headers 里显式覆盖（跨上下文场景），则保留覆盖值
+  const tenantId = config.headers['X-Tenant-Id'] ?? getActiveTenant()?.id;
+  const regionId = config.headers['X-Region-Id'] ?? getActiveRegion()?.id;
+  const cloud = config.headers['X-Cloud-Provider'] ?? getActiveCloudProvider();
+
+  if (tenantId) config.headers['X-Tenant-Id'] = tenantId;
+  if (regionId) config.headers['X-Region-Id'] = regionId;
+  if (cloud) config.headers['X-Cloud-Provider'] = cloud;
+
+  return config;
+});
+
+http.interceptors.response.use(
+  (res) => res,
+  (err) => {
+    const message = err.response?.data?.message ?? err.message;
+    return Promise.reject(new Error(message));
+  },
+);
+```
+
+```ts
+// src/lib/active-context.ts
+// 在 React 树外读取上下文（vanilla TS）
+// 由 TenantContext / RegionContext 在 mount 时注入
+let activeTenant: { id: string } | null = null;
+let activeRegion: { id: string } | null = null;
+let activeCloud: string | null = null;
+
+export function setActiveTenant(t: { id: string } | null) {
+  activeTenant = t;
+}
+export function setActiveRegion(r: { id: string } | null) {
+  activeRegion = r;
+}
+export function setActiveCloudProvider(c: string | null) {
+  activeCloud = c;
+}
+
+export function getActiveTenant() {
+  return activeTenant;
+}
+export function getActiveRegion() {
+  return activeRegion;
+}
+export function getActiveCloudProvider() {
+  return activeCloud;
+}
+```
+
+```tsx
+// src/contexts/TenantContext.tsx
+import { createContext, useContext, useEffect, useState } from 'react';
+import { setActiveTenant } from '@/lib/active-context';
+
+const TenantContext = createContext<{
+  tenantId: string;
+  setTenant: (id: string) => void;
+} | null>(null);
+
+export function TenantProvider({ children }: { children: React.ReactNode }) {
+  const [tenantId, setTenantIdState] = useState(
+    () => localStorage.getItem('activeTenantId') ?? '',
+  );
+  useEffect(() => {
+    setActiveTenant(tenantId ? { id: tenantId } : null);
+    localStorage.setItem('activeTenantId', tenantId);
+  }, [tenantId]);
+  return (
+    <TenantContext.Provider value={{ tenantId, setTenant: setTenantIdState }}>
+      {children}
+    </TenantContext.Provider>
+  );
+}
+
+export function useTenant() {
+  const ctx = useContext(TenantContext);
+  if (!ctx) throw new Error('useTenant must be used within TenantProvider');
+  return ctx;
+}
+```
+
+### 反模式
+
+- ❌ 在 service 里再 `import axios` 直接用（应该用 `http`）
+- ❌ 多份 `http` 实例
+- ❌ 把 tenantId / regionId 放到每个 service 的 url query 里（应该走 header）
+- ❌ 把 tenantId 当 React state 在每个组件里 prop drilling
+- ❌ tenantId 切换后不清 query cache —— 要么 queryKey 含 tenantId（推荐），要么显式 `qc.clear()`
+
+---
+
+## §4 · 类型分层
+
+```
+src/types/
+├── instance.ts       # Instance、InstanceStatus、InstanceListParams、CreateInstanceInput
+├── tenant.ts         # Tenant、TenantContext
+├── region.ts         # Region、CloudProvider
+└── api.ts            # 通用 ApiResponse<T>、Pagination<T>
+```
+
+- **Domain 类型**放 `src/types/<domain>.ts`，被 service / hook / component 共享
+- **API 入参 / 出参类型**：与 domain 类型分开命名
+- **不要**让组件 props 类型直接 `import` service 的内部类型
+
+---
+
+## §5 · 何时可以打破
+
+某些场景**允许**绕过本规范，但需要在代码注释里说明原因：
+
+| 场景                                   | 允许                                            |
+| -------------------------------------- | ----------------------------------------------- |
+| 静态资源 fetch                         | 组件直接 `fetch` 可，不用进 service             |
+| 第三方 SDK（地图、支付）有自己的客户端 | 包装层放 `src/lib/<sdk>.ts`                     |
+| 跨租户管理员视图（显式覆盖 header）    | service 接 `contextOverride` 参数（见 §1 示例） |
+| 一次性的诊断 / 调试代码                | 临时 fetch 可，但 PR 合并前必须清理或归位       |
+
+---
+
+## §6 · 上下文切换的级联失效
+
+当用户在 um-topbar 切换租户 / 区域 / 云厂商时，**必须**：
+
+1. 写入 `localStorage.activeTenantId / activeRegionId`
+2. `TenantContext` / `RegionContext` 同步更新
+3. **react-query cache** 中所有以 `[domain, tenantId, ...]` 开头的 queryKey 自动失效（因为 key 变了）
+4. URL 同步改写：`?tenantId=xxx&regionId=yyy`（见 [routing-and-codesplit.md](routing-and-codesplit.md) §6）
+5. 当前页面有未保存表单时，**先弹 AlertDialog 二次确认**（见 design-uni-manager flows.md §1.E）
+
+---
+
+## AI 必须输出的层级日志
+
+完成涉及网络 / 后端的改动时，AI 必须在响应里写明：
+
+```
+## 数据层改动
+
+- src/types/instance.ts: 新增 `InstanceListParams`、`InstanceStatus`
+- src/services/instance.ts: 新增 `listInstances`、`releaseInstance`（纯函数，使用 `@/lib/http`，不显式拼 tenantId）
+- src/hooks/useInstanceList.ts: 包 `useQuery`，queryKey=['instances', tenantId, regionId, params]
+- src/pages/instances/index.tsx: 仅消费 `useInstanceList`，不直接 fetch；URL 同步 tenantId / regionId
+- src/lib/http.ts: 已有 interceptor 注入 X-Tenant-Id / X-Region-Id，无需修改
+```
+
+每一层都点到名，且**租户 / 区域上下文如何流过**也要说清，才算合规。

package/src/teamix-evo-code-uni-manager/checklist.md

@@ -0,0 +1,193 @@
+# 编码自检清单（uni-manager）
+
+> AI 写完 / 改完代码后，**必须**逐项核对。任何一项未通过都不应交付，需要先修复或显式告诉用户哪条不通过、为什么。
+
+---
+
+## 1. 复用判定 ✓
+
+- [ ] 新建 UI 组件前，查过 `@teamix-evo/ui` 注册表（MCP `list_components` / `find_components`）
+- [ ] 新建 UI 组件前，查过 `biz-ui/uni-manager`（um-topbar 等）+ §2 概念占位拼装表
+- [ ] 新建 UI 组件前，grep 过本项目 `src/components/`
+- [ ] 新建工具函数前，grep 过 `src/utils/` `src/lib/` `src/hooks/`
+- [ ] 没有重复实现 ui 包已经提供的能力（Button、Input、Dialog、DataTable 等）
+- [ ] 没有 fork ui 包源码改样式（改样式应当走 design token）
+- [ ] **组件兜底铁律**：找不到现成实物时优先 ui 原子件组合，未自撸基础件
+- [ ] 响应里**显式列出**复用决策日志
+
+## 2. 数据层分层 ✓
+
+- [ ] 组件**没有**直接调 `fetch` / `axios`
+- [ ] 组件**没有**直接读 `import.meta.env` / `process.env`
+- [ ] 所有后端调用都落在 `src/services/<domain>.ts`，且是纯函数
+- [ ] Service 函数**不依赖 React**（没有 `useXxx`、没有 `useState`）
+- [ ] Service 函数**不弹通知 / 不跳路由**
+- [ ] Service 函数**不显式拼 `tenantId` / `regionId` / `cloudProvider`** —— 走 interceptor 注入
+- [ ] 数据 hook 在 `src/hooks/`，使用统一的数据库（react-query / swr，不混用）
+- [ ] 数据 hook 的 `queryKey` 含 `tenantId` / `regionId`（确保切换上下文时 cache 自动失效）
+- [ ] 全局只有一份 http 实例，在 `src/lib/http.ts`
+- [ ] `lib/http.ts` interceptor 已注入 `X-Tenant-Id` / `X-Region-Id` / `X-Cloud-Provider`
+
+## 3. 目录归位 ✓
+
+- [ ] 新文件位于约定的顶层目录（`pages/`、`components/`、`services/`、`hooks/`、`stores/`、`types/`、`utils/`、`lib/`、`contexts/`）
+- [ ] **没有**新增同义层（如 `views/`、`api/`、`helpers/`）
+- [ ] 仅在单个页面使用的组件 / hook 放在 `src/pages/<id>/_components/` 或 `_hooks/`（下划线前缀）
+- [ ] 跨页面复用的组件 / hook 才升到 `src/components/` `src/hooks/`
+- [ ] 跨云 / 跨租户专属组件放在 `src/components/cloud/`（CloudBadge / RegionBadge / ContextSwitcher）
+- [ ] 危险操作组件放在 `src/components/danger/` 或 `src/hooks/useDangerConfirm.ts`
+- [ ] React Hook 在 `hooks/`，不在 `utils/`
+- [ ] 类型声明文件没有运行时代码（纯类型）
+
+## 4. 命名 ✓
+
+- [ ] 目录 kebab-case（`instance-detail/`）
+- [ ] React 组件文件 PascalCase.tsx，文件名 = 组件名
+- [ ] Hook 文件 camelCase.ts，以 `use` 开头（`useInstanceList.ts`）
+- [ ] Service 文件按 domain 命名（`instance.ts`），不按 HTTP 动词
+- [ ] 名字能让下次复用时被 grep 命中（`InstanceStatusBadge` ✓ / `MyBadge` ❌）
+
+## 5. Import 边界 ✓
+
+- [ ] 跨目录 import 走 `@/*` 别名
+- [ ] **未发生反向依赖**：
+  - `components/` 没有 import `pages/`
+  - `services/` 没有 import `hooks/` `components/` `pages/`
+  - `hooks/` 没有 import `pages/`
+  - `utils/` `lib/` `types/` 没有 import 业务层
+- [ ] 页面私有目录（`_components/` `_hooks/`）**没有**被其他页面 import
+
+## 6. 类型 ✓
+
+- [ ] Domain 类型放 `src/types/<domain>.ts`
+- [ ] Service 函数有显式的入参 / 返回 `Promise<T>` 类型
+- [ ] 没有 `any`
+- [ ] Hook 的返回类型由 `react-query` / `swr` 自动推断
+
+## 7. 依赖卫生 ✓
+
+- [ ] 没有引入与项目内现有库**功能重复**的新依赖
+- [ ] 日期 / 数据请求 / 表单 / 状态等核心库**全项目统一**
+- [ ] 没有 `import` 未在 `package.json` 声明的包
+
+## 8. 副作用与可测性 ✓
+
+- [ ] Service 函数是纯函数
+- [ ] 工具函数（`src/utils/`）是纯函数
+- [ ] 没有在模块顶层（import 时）发请求 / 弹通知 / 改全局状态
+- [ ] 异步操作有错误处理路径
+
+## 9. 表单与校验 ✓
+
+（若改动涉及表单 — 详见 [`forms-and-validation.md`](forms-and-validation.md)）
+
+- [ ] 表单状态用 `react-hook-form`，**未用** `useState` 拼字段
+- [ ] 校验用 `zod` schema，schema 落 `src/services/<domain>.schema.ts`
+- [ ] 类型从 schema 推导（`z.infer<...>`）
+- [ ] 错误信息写在 schema 里
+- [ ] 提交走 mutation hook
+- [ ] 字段级 / 通用错误分别处理
+- [ ] 表单组件使用 `@teamix-evo/ui` 的 `Form` / `FormField`
+- [ ] **危险操作**（删除 / 释放 / 销毁）走 `useDangerConfirm`，要求**输入资源名称**确认（不接受只输 ID）
+
+## 10. 错误与加载态 ✓
+
+（若改动包含 UI / 数据 hook — 详见 [`error-and-loading.md`](error-and-loading.md)）
+
+- [ ] App 根**存在**全局 `ErrorBoundary` + `Toaster`
+- [ ] 全局 `onError` 调 `reportError`
+- [ ] 数据 hook 三态全处理：`isPending` → Skeleton、`isError` → 错误面板 + 重试、data → 内容
+- [ ] **未用** `useState<boolean>` + `useEffect` 自管 loading
+- [ ] Mutation 成功 → `toast.success` + 跳转 / invalidate；失败 → `toast.error`
+- [ ] Skeleton 撑住布局
+- [ ] 长操作（> 1s）按钮 `disabled`
+- [ ] 跨云资源 404 用专属 fallback（"该资源在当前云厂商 / 区域不存在，请检查 um-topbar 上下文"）
+
+## 11. 路由与代码分包 ✓
+
+（若改动涉及路由 — 详见 [`routing-and-codesplit.md`](routing-and-codesplit.md)）
+
+- [ ] 新页面用 `React.lazy()` 引入
+- [ ] Lazy 路由有 `<Suspense fallback>` 兜底
+- [ ] 鉴权 / 角色判断在 `src/routes/guards.tsx`
+- [ ] 路由声明集中在 `src/routes/index.tsx`
+- [ ] 404 / 403 / 500 兜底路由存在
+- [ ] 列表筛选 / 分页用 `useSearchParams`
+- [ ] **`tenantId` / `regionId` / `cloudProvider` 同步进 URL search params**（uni-manager 强化）
+- [ ] um-topbar 切换上下文时改写当前 URL，而不是 push 新历史
+- [ ] 跳转用 `<Link>` / `useNavigate`，**未用** `window.location.href`
+
+## 12. 测试覆盖 ✓
+
+（详见 [`testing.md`](testing.md)）
+
+- [ ] 新增纯函数有同名 `*.test.ts`（**必测**）
+- [ ] 新增 zod schema 有 `parse` 成功 / 失败用例（**必测**）
+- [ ] 关键业务路径（创建实例 / 切租户 / 删除资源）有组件 / hook 测试（**必测**）
+- [ ] 测试文件就近放在 `<source>.test.ts(x)`
+- [ ] 用 `msw` mock 后端
+- [ ] **msw handler 验证 X-Tenant-Id / X-Region-Id header**（uni-manager 强化）
+- [ ] 测试名是行为描述
+- [ ] 跳过测试时显式说明原因
+
+## 13. 与 design 规范的协作 ✓
+
+（若改动包含 UI）
+
+- [ ] 视觉部分按 [`teamix-evo-design-uni-manager`](../teamix-evo-design-uni-manager/SKILL.md) 自检过 token / 间距 / 圆角 / 动效
+- [ ] 没有硬编码颜色 / 间距 / 字号
+- [ ] 一致性三件套（UM1/UM2/UM3）满足：
+  - UM1：用 `um-topbar`，未自建顶部栏
+  - UM2：PageHeader 结构一致（标题 24px / 面包屑紧贴 / 操作右对齐）
+  - UM3：跨云资源在列表 / 详情有 CloudBadge
+
+---
+
+## ⚠️ 红线（一票否决）
+
+任何一条触发即必须重写或回退：
+
+1. **组件直接 fetch / axios** —— 数据层未分层
+2. **新建 Button / Input / Dialog 等基础组件** —— 重造 ui 包能力
+3. **services 函数依赖 React** —— 边界穿透
+4. **services 函数显式拼 tenantId / regionId 在 url query** —— 应走 header interceptor
+5. **`src/views/` 与 `src/pages/` 并存** —— 同义层污染
+6. **响应里没有复用决策日志** —— 流程未跑通
+7. **反向依赖**（service 引 hook、component 引 page）
+8. **多份 http 实例** —— 鉴权 / 上下文 header 无法统一
+9. **没有全局 ErrorBoundary** —— 异常直接白屏给用户
+10. **表单用 `useState` 拼字段** —— 弃 react-hook-form + zod
+11. **页面顶部 import 不 lazy + 没有 Suspense**
+12. **纯函数 / zod schema 无单测**
+13. **`alert()` / `window.location.href` 出现在业务代码**
+14. **uni-manager 红线 — 自建全局 topbar** —— 违反 UM1，必须用 `um-topbar`
+15. **uni-manager 红线 — 危险操作只用 ID 确认或不二次确认** —— 必须输入资源名称
+16. **uni-manager 红线 — 跨云资源列表 / 详情不带 CloudBadge** —— 违反 UM3
+17. **uni-manager 红线 — queryKey 不含 tenantId / regionId** —— 切租户后旧数据被复用，污染数据
+
+---
+
+## AI 输出格式建议
+
+完成改动时，在响应末尾附：
+
+```markdown
+## 编码合规自检（uni-manager）
+
+- 复用判定: ✅ 复用 ui Button / DataTable + biz-ui/uni-manager um-topbar；🆕 新写 InstanceStatusBadge（业务状态映射）
+- 数据层: ✅ services/instance.ts 纯函数；✅ hooks/useInstanceList.ts queryKey 含 tenantId / regionId；✅ 组件未 fetch；✅ http.ts interceptor 已注入上下文
+- 目录: ✅ 页面在 pages/instances/；✅ 跨云组件在 components/cloud/CloudBadge.tsx
+- 命名: ✅ kebab 目录 / Pascal 组件 / camel hook
+- 边界: ✅ 全部走 @/\*；✅ 无反向依赖
+- 类型: ✅ types/instance.ts 集中声明
+- 表单: ✅ useForm + zodResolver；✅ 删除走 useDangerConfirm（输入名称）
+- 错误/加载: ✅ 三态全处理；✅ ErrorBoundary 已在 App 根；✅ 跨云 404 fallback 已加
+- 路由: ✅ React.lazy + Suspense；✅ tenantId/regionId 进 URL；✅ um-topbar 切换改写 URL
+- 测试: ✅ instance.test.ts msw handler 验证 X-Tenant-Id；✅ schema parse 失败用例已加
+- design 协作: ✅ UM1/UM2/UM3 一致性三件套已自检
+- 红线: ✅ 全过（含 uni-manager UM 4 条红线）
+
+未通过项: 无
+```
+
+如有未通过项，明确写出"❌ 第 X 条：<原因> → <处理方式>"。