@teamix-evo/skills 0.3.0 → 0.4.0

package/src/teamix-evo-code-uni-manager/forms-and-validation.md

@@ -0,0 +1,459 @@
+# 表单与校验规范（uni-manager）
+
+> **核心约定**:表单状态用 `react-hook-form`,schema 用 `zod`,**永远不要**用一堆 `useState` 拼表单。**uni-manager 额外约定:危险操作走 `useDangerConfirm`(输入资源完整名称才执行),切租户/区域时表单未保存内容必须二次确认。**
+
+---
+
+## 为什么选这个组合(业界事实标准)
+
+| 维度       | react-hook-form + zod                | 多 `useState` 拼           |
+| ---------- | ------------------------------------ | -------------------------- |
+| 重渲染     | 字段级订阅,只渲染变化的字段          | 任意字段变化整个表单重渲染 |
+| 校验       | schema 驱动,前后端共用               | 散落在 onChange 里,易漏    |
+| 复杂表单   | resolver + watch + array fields 内建 | 自己实现一遍               |
+| TypeScript | 从 schema 自动推导类型               | 手写类型,易漂移            |
+
+参考:[React Hook Form](https://react-hook-form.com/) + [Zod](https://zod.dev/) 是 2024+ React 生态默认组合,被 shadcn/ui、Vercel、Linear、Cal.com 等广泛采用。
+
+---
+
+## Schema 落点
+
+```
+src/services/
+├── instance.ts                # 请求函数:listInstances、createInstance
+└── instance.schema.ts         # zod schema:CreateInstanceInput、UpdateInstanceInput
+```
+
+约定:
+
+- **每个 domain 一个 `<domain>.schema.ts`**,与 service 同目录
+- 从 schema 派生类型:`export type CreateInstanceInput = z.infer<typeof CreateInstanceInputSchema>`
+- service 的入参 / 返回类型**优先用** schema 推导,而不是手写 interface
+- **不要**把 schema 写在页面 / 组件文件里 —— schema 是 domain 资产,跨页面复用
+
+### 示例
+
+```ts
+// src/services/instance.schema.ts
+import { z } from 'zod';
+
+export const CreateInstanceInputSchema = z.object({
+  name: z.string().min(2, '名称至少 2 字').max(64),
+  cloudProvider: z.enum(['aws', 'aliyun', 'azure']),
+  region: z.string(),
+  spec: z.object({
+    cpu: z.number().int().positive(),
+    memoryGb: z.number().int().positive(),
+  }),
+  tags: z.record(z.string()).optional(),
+});
+
+export type CreateInstanceInput = z.infer<typeof CreateInstanceInputSchema>;
+```
+
+```ts
+// src/services/instance.ts
+import { http } from '@/lib/http';
+import type { CreateInstanceInput } from './instance.schema';
+import type { Instance } from '@/types/instance';
+
+export async function createInstance(
+  input: CreateInstanceInput,
+): Promise<Instance> {
+  // 不显式拼 tenantId — 走 lib/http.ts interceptor
+  const { data } = await http.post('/api/instances', input);
+  return data;
+}
+```
+
+---
+
+## 表单组件结构
+
+### 简单表单(单页面专用)
+
+放在页面私有目录:
+
+```
+src/pages/instances/new/
+├── index.tsx                       # 路由组件
+└── _components/
+    └── CreateInstanceForm.tsx      # useForm + UI
+```
+
+### 跨页面复用表单
+
+升到 `src/components/forms/<Name>Form.tsx`:
+
+```
+src/components/forms/
+├── TagEditorForm.tsx               # 标签编辑(实例 / 桶 / VPC 都用)
+└── CustomerSearchForm.tsx
+```
+
+### 标准实现模板
+
+```tsx
+// src/pages/instances/new/_components/CreateInstanceForm.tsx
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { useCreateInstance } from '@/hooks/useCreateInstance';
+import {
+  CreateInstanceInputSchema,
+  type CreateInstanceInput,
+} from '@/services/instance.schema';
+import { Button, Input, Form, FormField, FormItem } from '@/components/ui';
+
+export function CreateInstanceForm() {
+  const form = useForm<CreateInstanceInput>({
+    resolver: zodResolver(CreateInstanceInputSchema),
+    defaultValues: {
+      name: '',
+      cloudProvider: 'aliyun',
+      region: '',
+      spec: { cpu: 2, memoryGb: 4 },
+    },
+  });
+  const mutation = useCreateInstance();
+
+  return (
+    <Form {...form}>
+      <form
+        onSubmit={form.handleSubmit((values) => mutation.mutate(values))}
+        className="space-y-4"
+      >
+        <FormField
+          control={form.control}
+          name="name"
+          render={({ field }) => (
+            <FormItem>
+              <Input {...field} />
+            </FormItem>
+          )}
+        />
+        {/* ... 其他字段 */}
+        <Button type="submit" disabled={mutation.isPending}>
+          {mutation.isPending ? '提交中…' : '创建'}
+        </Button>
+      </form>
+    </Form>
+  );
+}
+```
+
+---
+
+## 校验规则
+
+| 场景                                              | 写在哪                                          |
+| ------------------------------------------------- | ----------------------------------------------- |
+| 字段格式(邮箱 / 手机号 / URL / 资源命名规则)      | zod schema(`z.string().email()`)                |
+| 业务规则(库存检查 / 唯一性 / 配额检查)            | service 层,服务端返回错误 → hook 暴露 → UI 显示 |
+| 跨字段约束(开始日期 < 结束日期 / cpu/memory 比例) | zod `.refine()` / `.superRefine()`              |
+| 异步校验(实例名是否被占用)                        | `useQuery` + debounce,**不放 schema**           |
+
+### 反模式
+
+- ❌ 在 `onChange` 里手写 `if (value.length > 20) setError(...)`
+- ❌ 校验报错信息硬编码在组件里("请输入正确的实例名") —— 写在 schema 里,UI 只读
+- ❌ 表单状态用 `useState`,然后再加 `useEffect` 同步校验 —— 直接用 `useForm`
+- ❌ schema 在组件文件里就地定义 —— 抽到 `<domain>.schema.ts`
+- ❌ 提交逻辑写在 `<form onSubmit>` 里直接 fetch —— 走 mutation hook
+
+---
+
+## 表单提交错误如何展示
+
+```tsx
+const mutation = useCreateInstance();
+
+// 提交后:
+mutation.mutate(values, {
+  onError: (err) => {
+    // 1. 字段级错误回填 form(后端返回 { field, message }[])
+    if (isFieldErrors(err)) {
+      err.fields.forEach(({ field, message }) =>
+        form.setError(field as keyof CreateInstanceInput, { message }),
+      );
+      return;
+    }
+    // 2. 通用错误走 toast(全局错误归一化在 lib/http.ts)
+    toast.error(err.message);
+  },
+});
+```
+
+要点:
+
+- 字段级错误 → `form.setError`(高亮对应输入框)
+- 通用错误 → `toast`(由 `lib/http.ts` 已归一化的 `Error.message`)
+- **不要**把后端错误对象塞到 form,先归一化
+
+---
+
+## §9 · 切换租户/区域时未保存内容保护
+
+uni-manager 业务页面常见 — 用户填了一半表单,顺手在 um-topbar 切了租户。**必须**用 React Router 的 `useBlocker` 拦截:
+
+```tsx
+// 在表单组件内
+import { useBlocker } from 'react-router-dom';
+import { AlertDialog } from '@/components/ui';
+
+export function CreateInstanceForm() {
+  const form = useForm<CreateInstanceInput>({...});
+  const isDirty = form.formState.isDirty;
+
+  // 拦截路由变化(包括 search params 改变 → 切租户/区域)
+  const blocker = useBlocker(({ currentLocation, nextLocation }) =>
+    isDirty &&
+    (currentLocation.pathname !== nextLocation.pathname ||
+      currentLocation.search !== nextLocation.search),
+  );
+
+  return (
+    <>
+      <Form {...form}>
+        {/* 表单内容 */}
+      </Form>
+      <AlertDialog
+        open={blocker.state === 'blocked'}
+        title="放弃未保存的内容?"
+        description="切换上下文将丢失当前填写。继续操作前请先保存或确认放弃。"
+        onConfirm={() => blocker.proceed?.()}
+        onCancel={() => blocker.reset?.()}
+        confirmLabel="放弃并切换"
+        cancelLabel="留下"
+      />
+    </>
+  );
+}
+```
+
+要点:
+
+- 仅当 `isDirty` 为 true 时拦截,否则放行
+- AlertDialog 文案明确告知**会丢失什么**
+- 关闭/刷新页面也要拦截:`useBeforeUnload(isDirty ? '...' : null)`
+
+---
+
+## §10 · 危险操作:`useDangerConfirm`(uni-manager 红线)
+
+uni-manager 涉及云资源的删除/释放/销毁/转交租户**禁止**使用普通 `confirm("确定?")` 或简单 `<AlertDialog>`,**必须**走 `useDangerConfirm`:用户输入完整资源名称才能 enable 确认按钮。
+
+### Hook 完整实现
+
+```tsx
+// src/hooks/useDangerConfirm.ts
+import { useState, useCallback } from 'react';
+
+export interface DangerConfirmOptions {
+  /** 操作动词:"释放" / "删除" / "销毁" / "转交" */
+  action: string;
+  /** 资源类型:"实例" / "对象存储桶" / ... */
+  resourceType: string;
+  /** 资源完整名称或 ID(用户必须原样输入) */
+  resourceName: string;
+  /** 额外警告(可选) */
+  warning?: string;
+  /** 实际执行的异步操作 */
+  perform: () => Promise<void> | void;
+}
+
+export interface DangerConfirmState {
+  /** 打开 dialog */
+  open: (opts: DangerConfirmOptions) => void;
+  /** 当前 dialog 配置;null 表示未打开 */
+  current: DangerConfirmOptions | null;
+  /** 关闭(取消) */
+  close: () => void;
+  /** 用户输入框的值 */
+  input: string;
+  setInput: (v: string) => void;
+  /** 执行(必须 input === resourceName 才有效) */
+  confirm: () => Promise<void>;
+  /** 是否可以确认 */
+  canConfirm: boolean;
+  /** 是否正在执行 */
+  isPerforming: boolean;
+}
+
+export function useDangerConfirm(): DangerConfirmState {
+  const [current, setCurrent] = useState<DangerConfirmOptions | null>(null);
+  const [input, setInput] = useState('');
+  const [isPerforming, setIsPerforming] = useState(false);
+
+  const open = useCallback((opts: DangerConfirmOptions) => {
+    setCurrent(opts);
+    setInput('');
+    setIsPerforming(false);
+  }, []);
+
+  const close = useCallback(() => {
+    setCurrent(null);
+    setInput('');
+    setIsPerforming(false);
+  }, []);
+
+  const canConfirm =
+    current !== null && input === current.resourceName && !isPerforming;
+
+  const confirm = useCallback(async () => {
+    if (!canConfirm || !current) return;
+    setIsPerforming(true);
+    try {
+      await current.perform();
+      close();
+    } catch (e) {
+      // 失败不关闭 dialog,让用户看到错误后决定下一步
+      setIsPerforming(false);
+      throw e;
+    }
+  }, [canConfirm, current, close]);
+
+  return {
+    open,
+    current,
+    close,
+    input,
+    setInput,
+    confirm,
+    canConfirm,
+    isPerforming,
+  };
+}
+```
+
+### 配套 Dialog 组件
+
+```tsx
+// src/components/danger/DangerConfirmDialog.tsx
+import { Dialog, DialogContent, Button, Input, Label } from '@/components/ui';
+import { type DangerConfirmState } from '@/hooks/useDangerConfirm';
+
+export function DangerConfirmDialog({ state }: { state: DangerConfirmState }) {
+  const { current, close, input, setInput, confirm, canConfirm, isPerforming } =
+    state;
+  if (!current) return null;
+
+  return (
+    <Dialog open onOpenChange={(o) => !o && close()}>
+      <DialogContent>
+        <h2 className="text-lg font-semibold">
+          {current.action}
+          {current.resourceType} {current.resourceName}
+        </h2>
+        <p className="text-muted-foreground mt-2 text-sm">
+          此操作不可恢复。{current.warning ?? ''}
+        </p>
+        <div className="mt-4 space-y-2">
+          <Label htmlFor="danger-input">
+            请输入 <code>{current.resourceName}</code> 以确认
+          </Label>
+          <Input
+            id="danger-input"
+            value={input}
+            onChange={(e) => setInput(e.target.value)}
+            placeholder={current.resourceName}
+            autoComplete="off"
+          />
+        </div>
+        <div className="mt-6 flex justify-end gap-2">
+          <Button variant="outline" onClick={close} disabled={isPerforming}>
+            取消
+          </Button>
+          <Button
+            variant="destructive"
+            disabled={!canConfirm}
+            onClick={confirm}
+          >
+            {isPerforming ? '执行中…' : `确认${current.action}`}
+          </Button>
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}
+```
+
+### 使用范式
+
+```tsx
+// 列表页释放实例
+function InstanceListPage() {
+  const danger = useDangerConfirm();
+  const release = useReleaseInstance();
+
+  const onClickRelease = (instance: Instance) => {
+    danger.open({
+      action: '释放',
+      resourceType: '实例',
+      resourceName: instance.id,
+      warning: `${instance.cloudProvider}/${instance.region} 区域的资源将立即释放,数据无法恢复。`,
+      perform: async () => {
+        await release.mutateAsync(instance.id);
+        toast.success(`实例 ${instance.id} 已释放`);
+      },
+    });
+  };
+
+  return (
+    <>
+      <Table onRelease={onClickRelease} />
+      <DangerConfirmDialog state={danger} />
+    </>
+  );
+}
+```
+
+### 红线
+
+- ❌ 用 `confirm('确定释放?')` —— 浏览器原生 dialog 一律禁用
+- ❌ 用普通 AlertDialog "确定/取消" 二选一(无输入校验)
+- ❌ resourceName 用 ID 缩写、占位符 `xxx`、显示名(必须用**完整不可歧义**的标识,通常是 ID)
+- ❌ 大批量释放(选中 12 个实例)直接弹一个 dialog —— 列出全部 ID + 输入 "DELETE 12" 类似校验
+
+---
+
+## 与 ui 包的边界
+
+`@teamix-evo/ui` 提供 `Form`、`FormField`、`FormItem`、`FormLabel`、`FormMessage`(shadcn 同款,基于 react-hook-form Context)。
+
+- **必须用 ui 包提供的 Form 组件**,不要自己 `<form>` + `<label>` 手撸
+- 业务表单只负责:schema + 字段 + 提交 callback,UI 一律走 ui 包
+
+uni-manager 工程内**额外**提供(后续抽到 biz-ui/uni-manager):
+
+- `useDangerConfirm` Hook
+- `DangerConfirmDialog` 组件
+- `TagEditorForm`(标签编辑跨多种资源)
+- `RegionSelector`(基于 cloudProvider 联动 region 列表)
+
+---
+
+## 装机指引
+
+如果项目里还没装:
+
+```bash
+pnpm add react-hook-form zod @hookform/resolvers
+```
+
+`@hookform/resolvers` 提供 `zodResolver`,把 zod schema 接入 react-hook-form。
+
+---
+
+## AI 必须输出的表单日志
+
+```
+## 表单改动
+
+- src/services/instance.schema.ts: 新增 CreateInstanceInputSchema(zod)、派生类型
+- src/services/instance.ts: createInstance 入参用派生类型(不显式拼 tenantId)
+- src/pages/instances/new/_components/CreateInstanceForm.tsx: useForm + zodResolver + useBlocker(脏态拦截)
+- src/hooks/useCreateInstance.ts: useMutation 包 createInstance,onError 区分字段级 / 通用
+- 危险操作: ✅ 释放实例走 useDangerConfirm(输入 instance.id 校验)
+- 切租户保护: ✅ 表单 isDirty 时拦截 search 变化
+```

package/src/teamix-evo-code-uni-manager/reuse-first.md

@@ -0,0 +1,188 @@
+# Reuse-First · 组件 / 工具复用决策流（uni-manager）
+
+> 在写**任何**新组件 / Hook / 工具函数之前，AI 必须按本流程跑一遍。"没找到现成的"必须是查询的结论，不能是默认假设。
+>
+> uni-manager 在 OpenTrek 通用流程之上，叠加 **biz-ui/uni-manager** 实物层与"组件兜底铁律"。
+
+---
+
+## 决策树
+
+```
+收到「写一个 xxx」请求
+│
+├── Step 1: 这是 UI 组件吗？
+│   ├── 是 → 走 §1（查 @teamix-evo/ui 注册表）
+│   └── 否 → 跳 Step 2
+│
+├── Step 2: 这是 uni-manager 专属壳层 / 跨云组件吗？
+│   ├── 是 → 走 §2（查 biz-ui/uni-manager + 概念占位拼装表）
+│   └── 否 → 跳 Step 3
+│
+├── Step 3: 这是业务组件 / 页面骨架吗？
+│   ├── 是 → 走 §3（查 @teamix-evo/biz-ui；页面骨架走 design skill 的 patterns/）
+│   └── 否 → 跳 Step 4
+│
+├── Step 4: 这是工具函数 / Hook 吗？
+│   ├── 是 → 走 §4（grep 本项目 + 查常见库）
+│   └── 否 → 跳 Step 5
+│
+└── Step 5: 全部未命中 → 走 §5（写新代码，但要遵守归位规则）
+```
+
+---
+
+## §1 · UI 组件：必须先查 `@teamix-evo/ui` 注册表
+
+`@teamix-evo/ui` 是源码注入式 UI 组件库，**89 个条目**（button、input、dialog、data-table、…）。在写新 UI 组件之前：
+
+### 查询顺序（从快到慢）
+
+1. **MCP `list_components`** —— 一次列全部，扫描是否有同名 / 近义。
+2. **MCP `find_components` query=<关键词>** —— 子串匹配 id / name / description。
+3. **本项目 grep** —— `grep -r "from '@/components/ui'" src/` 看哪些已经装机。
+4. **本项目 `.teamix-evo/ui/manifest.lock.json`** —— 已装机的 ui entry 清单。
+
+### 命中后的处理
+
+| 情况                            | 处理                                              |
+| ------------------------------- | ------------------------------------------------- |
+| 注册表里有，本项目已装          | 直接 `import` 复用，**不要复制源码**              |
+| 注册表里有，本项目未装          | 提示用户跑 `teamix-evo ui add <id>`，装机后再用   |
+| 注册表里有近义但 props 不完全够 | **优先组合**（包一层 wrapper），不要 fork ui 源码 |
+| 注册表里完全没有                | 进 §2 / §5                                        |
+
+### 反模式（禁止）
+
+- ❌ 在 `src/components/` 下重写 `Button` / `Input` / `Dialog`（已经在 ui 包里）
+- ❌ 复制 ui 包源码到 `src/components/` 改样式 —— 改样式应当通过 design token 覆盖
+- ❌ 包 `antd` / `mui` / `chakra` 的同类组件 —— teamix-evo 的设计系统是 shadcn-based，混用会破坏 token 链路
+
+---
+
+## §2 · uni-manager 专属壳层 / 跨云组件：查 `biz-ui/uni-manager`
+
+### 已实装
+
+| 组件          | 包                               | 用途                                                                                    |
+| ------------- | -------------------------------- | --------------------------------------------------------------------------------------- |
+| **um-topbar** | `@teamix-evo/biz-ui/uni-manager` | 全局顶部栏（logo + 租户切换 + 区域 + 用户）；**所有 L1/L2 页面必须用，禁止自建**（UM1） |
+
+### 概念占位（设计文档已定义，代码层尚未抽实物 — AI 在本项目内组合 ui 原子件实现，并按下表命名）
+
+| 概念名                  | 推荐组合                                  | 应该放在哪                                                         |
+| ----------------------- | ----------------------------------------- | ------------------------------------------------------------------ |
+| **CloudBadge**          | `Badge` + 云厂商图标                      | `src/components/cloud/CloudBadge.tsx`                              |
+| **RegionBadge**         | `Badge`                                   | `src/components/cloud/RegionBadge.tsx`                             |
+| **ContextSwitcher**     | `Select` / `Combobox`（含搜索）           | `src/components/cloud/ContextSwitcher.tsx`（如未走 um-topbar）     |
+| **BulkActionBar**       | `Card`(底部) + `Button` 列                | `src/components/list/BulkActionBar.tsx`                            |
+| **OperationLog**        | `Tabs` + `Timeline` + `Pagination`        | `src/components/log/OperationLog.tsx`                              |
+| **ResourceCard**        | `Card` + `DescriptionList` + `CloudBadge` | `src/components/resource/ResourceCard.tsx`                         |
+| **DangerConfirmDialog** | `AlertDialog` + `Input`（输入资源名）     | `src/components/danger/DangerConfirmDialog.tsx`（或走 hook，见下） |
+
+### 组件兜底铁律（最高优先）
+
+> "找不到现成的实物组件" → **优先用 ui 原子件组合**，并按上表的概念名归位。**禁止**：
+>
+> - ❌ 自撸 `Topbar` / `CustomDialog` / `MyButton` 等基础件
+> - ❌ 直接在页面里散写 `<div className="flex ...">` 拼复合形态（应抽到 `components/`）
+> - ❌ 跨页面重复同样组合 3 次以上还不抽组件
+
+### 决策表
+
+| 场景                                | 选择                                                                           |
+| ----------------------------------- | ------------------------------------------------------------------------------ |
+| 全局 topbar / 工作台首屏顶部        | `um-topbar`（biz-ui/uni-manager 实物）                                         |
+| 列表 / 详情页中标识资源云厂商       | `CloudBadge`（本项目内概念组合）                                               |
+| 表单 / 列表跨账号或跨区域上下文切换 | `ContextSwitcher`（在 um-topbar 已就位时勿重复）                               |
+| 列表多选后底部批量操作栏            | `BulkActionBar`                                                                |
+| 资源详情页"操作日志" Tab            | `OperationLog`                                                                 |
+| 危险操作（删除 / 释放 / 销毁）      | `DangerConfirmDialog` 或 `useDangerConfirm` hook（见 forms-and-validation.md） |
+
+---
+
+## §3 · 业务组件：查 `biz-ui`（页面骨架走 design skill 的 patterns/）
+
+| 包                   | 用途                                     | 查询入口                                               |
+| -------------------- | ---------------------------------------- | ------------------------------------------------------ |
+| `@teamix-evo/biz-ui` | 业务化的复合组件（变体感知 + slot 边界） | 本项目 `node_modules/@teamix-evo/biz-ui/manifest.json` |
+
+### 页面骨架来源（列表 / 详情 / 表单 / Console Home）
+
+> ⚠️ **AI 默认不调用 `@teamix-evo/templates` 包**（见 [ADR 0031](../../../docs/adr/0031-skill-templates-decoupling.md)）。页面骨架按下列优先级生成：
+
+1. **首选** —— 读 `teamix-evo-design-uni-manager` skill 的 [`patterns/{list|detail|form|dashboard}-page.md`](../teamix-evo-design-uni-manager/patterns/)，按 Zone Map 与决策树用 ui 原子件 + biz-ui/uni-manager 实物件（`um-topbar`） + 概念占位拼装表**直接拼装**到 `src/pages/<id>/`
+2. **patterns/ 未覆盖时** —— 按业界流行的云管 / 控制台页面架构（antd Pro / aliyun-console / shadcn Examples 等）与用户描述自由实现，**不要回退到 templates 包**
+3. **`@teamix-evo/templates` 包与 CLI 命令仍保留**，但仅在用户**显式**要求时才走 `teamix-evo templates add`
+
+### 决策表
+
+| 场景                                                 | 选择                                                           |
+| ---------------------------------------------------- | -------------------------------------------------------------- |
+| 列表页 / 详情页 / 表单页 / Console Home 骨架         | 读 design skill `patterns/*.md` → ui + biz-ui/uni-manager 拼装 |
+| “带筛选的资源表格”、“带审批流的工单卡片”             | 优先 `biz-ui`                                                  |
+| 一次性的、强领域绑定的组合                           | 写在 `src/components/<domain>/` 里，**不要污染 biz-ui**        |
+| uni-manager 跨云专属（CloudBadge / OperationLog 等） | 走 §2 概念占位拼装表                                           |
+| patterns/ 未覆盖的特殊页面                           | 按业界流行架构 + 用户描述自由实现，**不调用 templates 包**     |
+
+---
+
+## §4 · 工具函数 / Hook：本项目优先，再查通用库
+
+### 顺序
+
+1. **本项目 grep**：
+   ```bash
+   grep -rn "function <近义名>" src/utils/ src/lib/ src/hooks/
+   ```
+2. **`@teamix-evo/*` 是否提供**（少数情况，如格式化、token 工具）
+3. **依赖里的成熟库** —— 例如：
+   - 日期 → `date-fns` / `dayjs`（看项目里已经装哪个，不要再装第三个）
+   - 数据请求 → `@tanstack/react-query` / `swr`
+   - 表单 → `react-hook-form` + `zod`
+   - 工具 → `lodash-es`、`es-toolkit`
+4. **uni-manager 推荐内置 Hook**：
+   - `useTenant()` —— 读当前租户上下文（`src/contexts/TenantContext.tsx`）
+   - `useRegion()` —— 读当前区域
+   - `useCloudProvider()` —— 读当前云厂商
+   - `useDangerConfirm()` —— 危险操作输入名称确认（封装 AlertDialog）
+5. **完全没有现成** → 进 §5
+
+### 反模式
+
+- ❌ 写 `formatDate` 时不看项目用的是 dayjs 还是 date-fns，凭直觉新加一个
+- ❌ 同一项目里既装 `lodash` 又装 `lodash-es` 又装 `es-toolkit`
+- ❌ 自己写防抖 / 节流 / 深拷贝（标准库都有）
+- ❌ 在每个组件里 `useContext(TenantContext)` —— 用 `useTenant()` 包装 hook
+- ❌ 自撸"输入文本一致才能确认"的 Dialog —— 用 `useDangerConfirm`
+
+---
+
+## §5 · 必须新写时的归位规则
+
+走到这一步，代码确实需要新写。归位见 [`file-structure.md`](file-structure.md)；本节只讲**写新代码时**的最小约束：
+
+1. **命名要能让下次复用查得到** —— 起 `InstanceStatusBadge` 而不是 `MyBadge`；`useInstanceList` 而不是 `useList`
+2. **抽象层级别低于一次性页面** —— 跨页面会用的才放 `src/components/`，只在一个页面用的写在 `src/pages/<id>/_components/`
+3. **暴露面尽量窄** —— 默认只 `export` 这次需要的 API，别一次性 `export *`
+4. **写完登记** —— 在 PR 描述里明确“新增 `<path>`，因为 ui / biz-ui / patterns / 本项目均未提供 X 能力”（注：不再以 `templates` 包作为兜底依据，见 [ADR 0031](../../../docs/adr/0031-skill-templates-decoupling.md)）
+5. **uni-manager 专属**：跨云 / 跨租户的 component 必须放 `src/components/cloud/` 或 `src/components/<domain>/`，方便后续抽到 biz-ui/uni-manager
+
+---
+
+## AI 必须输出的决策日志
+
+完成代码改动时，AI **必须**在响应里附一段决策日志，例如：
+
+```
+## 复用决策
+
+- ✅ 复用 `@teamix-evo/biz-ui/uni-manager` 的 `um-topbar`（已装机，UM1 满足）
+- ✅ 复用 `@teamix-evo/ui` 的 `DataTable`、`Button`、`Badge`、`AlertDialog`
+- ✅ 复用本项目 `src/components/cloud/CloudBadge.tsx`（已存在，符合 §2 概念占位）
+- ✅ 复用本项目 hook `useDangerConfirm`（用于"删除实例"二次确认）
+- 🆕 新写 `src/components/cloud/RegionTopologyMap.tsx` —— ui 包提供通用 `ScrollArea`，但区域拓扑图为业务专属，组合一层
+- ✅ 复用 `src/utils/format.ts` 的 `formatBytes`
+```
+
+没有这段日志，任务不算完成。