adspecs 0.1.12

package/references/ant6-front-standard/05-/345/211/215/347/253/257/347/274/226/347/240/201/350/247/204/350/214/203.md

@@ -0,0 +1,1443 @@
+# 前端编码规范
+
+> **版本**: v3.3
+> **创建日期**: 2026-03-17
+> **更新日期**: 2026-06-05
+> **适用范围**: React 19 + TypeScript 6 + Ant Design 6 + ProComponents 项目
+> **文档目的**: 统一前端编码规范，提升代码质量和团队协作效率
+
+---
+
+## 📋 目录
+
+1. [技术栈基线](#技术栈基线)
+2. [目录结构规范](#目录结构规范)
+3. [命名规范](#命名规范)
+4. [编码风格规范](#编码风格规范)
+5. [React 组件规范](#react-组件规范)
+6. [列表页标准模式（ProTable）](#列表页标准模式protable)
+7. [Modal / Drawer 标准模式](#modal--drawer-标准模式)
+8. [TypeScript 规范](#typescript-规范)
+9. [样式规范](#样式规范)
+10. [路由规范](#路由规范)
+11. [状态管理规范](#状态管理规范)
+12. [API 接口规范](#api-接口规范)
+13. [国际化（i18n）规范](#国际化i18n规范)
+14. [字典系统规范](#字典系统规范)
+15. [权限系统规范](#权限系统规范)
+16. [Mock 规范](#mock-规范)
+17. [上传组件规范](#上传组件规范)
+18. [时间格式化规范](#时间格式化规范)
+19. [性能优化规范](#性能优化规范)
+20. [代码质量标准](#代码质量标准)
+21. [常见问题规范（必读陷阱）](#常见问题规范必读陷阱)
+22. [Vue → React 迁移映射表](#vue--react-迁移映射表)
+
+---
+
+## 一、技术栈基线
+
+| 维度   | 选型                                            | 备注                                                              |
+| ------ | ----------------------------------------------- | ----------------------------------------------------------------- |
+| 框架   | React 19.2 + TypeScript 6                       | strict 模式                                                       |
+| UI     | `antd` ^6.3 + `@ant-design/pro-components` ^3.1 | 列表统一用 `ProTable`                                             |
+| 图标   | `@ant-design/icons`                             | 按需引入；后端图标名通过 `<Icon icon="ep:xxx">` 走 `iconMap` 转换 |
+| 路由   | `react-router` ^7                               | `createBrowserRouter` + 动态路由 patch                            |
+| 状态   | `zustand` ^5                                    | `useAuthStore` / `useAppStore` / `useDictStore`                   |
+| 网络   | `axios` ^1.15                                   | 统一实例 `@/utils/request`                                        |
+| Mock   | `msw` ^2.13                                     | 仅 dev，受 `VITE_MOCK_ENABLED` 控制                               |
+| 国际化 | `react-i18next` ^17                             | 默认中文                                                          |
+| 构建   | Vite 8                                          | `npm run build` 必须通过 `tsc -b && vite build`                   |
+| 风格   | Prettier 单引号 / 分号 / 100 列宽 / 2 空格      | ESLint flat config + `react-hooks`                                |
+
+> **禁用**：Tailwind、CSS-in-JS 库、TanStack Query、Redux、Class 组件、`element-plus` 残留代码。
+
+---
+
+## 二、目录结构规范
+
+```
+src/
+├── api/                # axios 接口模块（按域拆分）
+│   ├── ai/             # /ai/* 接口
+│   ├── infra/
+│   ├── system/
+│   └── auth.ts
+├── components/         # 通用组件（首字母大写文件夹 + index.tsx 默认导出）
+│   ├── Access/         # 权限包裹
+│   ├── DictTag/        # 字典标签
+│   ├── Footer/         # 页脚
+│   ├── Icon/           # iconify → AntD 图标
+│   ├── Message/        # Header 铃铛 + 未读列表
+│   ├── UploadFile/     # UploadFile / UploadImg / UploadImgs
+│   ├── UserSelectForm/
+│   └── DeptSelectForm/
+├── hooks/              # 自定义 hook，use 前缀
+├── layouts/            # 仅一个 AdminLayout
+├── pages/              # 路由对应的页面
+│   ├── ai/             # 与后端菜单 path 完全对齐
+│   ├── infra/
+│   ├── system/
+│   ├── profile/
+│   └── login/
+├── mocks/              # MSW
+│   ├── data/index.ts   # 所有 mock 数据 + 字典 + 菜单
+│   └── handlers/       # 按模块拆 ai.ts / infra.ts / notify.ts ...
+├── router/             # createBrowserRouter + dynamicRoutes
+├── stores/             # zustand store
+├── types/              # 跨模块共享类型
+└── utils/              # request / formatTime / token / menuConverter ...
+```
+
+**关键约定**：
+
+1. **页面路径必须等于后端菜单 `component` 字段**。例如后端返回 `ai/chat/index/index` → 文件必须落在 `src/pages/ai/chat/index/index.tsx`，否则 `dynamicRoutes` 会报 `Component not found` 警告并显示 404。
+2. 子组件统一放在该页面同级 `components/` 下：`pages/<feature>/components/XxxModal.tsx`。
+3. 通用业务组件命名遵循 `components/<PascalCase>/index.tsx`。
+
+---
+
+## 三、命名规范
+
+| 对象          | 规则                            | 示例                                    |
+| ------------- | ------------------------------- | --------------------------------------- |
+| 组件文件      | PascalCase                      | `DeptModal.tsx` / `index.tsx`           |
+| 页面目录      | kebab-case 或保留后端 path      | `chat-role/`、`data-source-config/`     |
+| Hook          | `useXxx.ts`                     | `useAccess.ts`                          |
+| 工具/常量文件 | camelCase                       | `formatTime.ts`、`token.ts`             |
+| 类型          | `XxxVO`/`XxxParams`/`SystemXxx` | `ChatMessageVO`                         |
+| 常量          | UPPER_SNAKE                     | `MAX_AVATAR_MB`                         |
+| API 函数      | 动词 + 资源                     | `getDeptList`、`updateDataSourceConfig` |
+| 普通变量      | camelCase                       | `userName`                              |
+| 布尔变量      | is/has/can/should 开头          | `isValid`, `hasPermission`              |
+
+---
+
+## 四、编码风格规范
+
+### 4.1 代码格式化
+
+- 使用 2 个空格缩进
+- 优先使用单引号，如 `'string'`
+- JSX 属性使用双引号，如 `<div className="container">`
+- 模板字符串使用反引号
+- 使用分号
+- 函数调用和对象字面量末尾使用尾随逗号
+- 每行最多 100 个字符
+
+### 4.2 注释规范
+
+```typescript
+/**
+ * 获取用户列表
+ * @param params - 查询参数
+ * @param params.pageNum - 页码
+ * @param params.pageSize - 每页数量
+ */
+async function getUserList(params: UserPageParams): Promise<User[]> {
+  // 关键业务逻辑必须添加注释
+}
+```
+
+- 关键业务逻辑必须添加注释
+- 复杂算法必须添加说明
+- 临时解决方案需要标记 `// TODO: 说明`
+
+---
+
+## 五、React 组件规范
+
+### 5.1 函数组件结构
+
+```tsx
+// 1. 导入语句（按类型分组：React -> 第三方库 -> 本地模块 -> 样式）
+import { useState, useEffect, useCallback, useRef } from 'react';
+import { Form, Table, Button, Modal, Space } from 'antd';
+import { PlusOutlined } from '@ant-design/icons';
+import { ProTable, type ProColumns, type ActionType } from '@ant-design/pro-components';
+import { getUserList, deleteUser } from '@/api/system/user';
+import type { User } from '@/types/system/user';
+import Access from '@/components/Access';
+
+// 2. 类型定义（复杂类型建议放在 src/types/ 下）
+interface UserListProps {
+  departmentId?: number;
+}
+
+// 3. 组件定义（使用 function 声明）
+export default function UserList({ departmentId }: UserListProps) {
+  // 4. Hooks 调用（按顺序：ref/state -> custom hooks -> effects）
+  const { message, modal } = App.useApp();
+  const actionRef = useRef<ActionType>(undefined);
+  const [loading, setLoading] = useState(false);
+  const [selectedRowKeys, setSelectedRowKeys] = useState<React.Key[]>([]);
+
+  // 5. 事件处理函数
+  const handleDelete = useCallback(async (record: User) => {
+    modal.confirm({
+      title: '确认删除？',
+      okType: 'danger',
+      content: `确认删除「${record.name}」吗？`,
+      onOk: async () => {
+        await deleteUser(record.id!);
+        message.success('删除成功');
+        actionRef.current?.reload();
+      },
+    });
+  }, [message, modal]);
+
+  // 6. 列定义
+  const columns: ProColumns<User>[] = [
+    { title: '名称', dataIndex: 'name', width: 200 },
+    { title: '操作', key: 'action', search: false, render: (_, record) => (
+      <Space>
+        <Access code="system:user:update">
+          <a onClick={() => handleEdit(record)}>编辑</a>
+        </Access>
+        <Access code="system:user:delete">
+          <a style={{ color: '#ff4d4f' }} onClick={() => handleDelete(record)}>删除</a>
+        </Access>
+      </Space>
+    )},
+  ];
+
+  // 7. 渲染
+  return (
+    <ProTable<User>
+      columns={columns}
+      actionRef={actionRef}
+      rowKey="id"
+      request={async (params) => {
+        const { current, pageSize, ...rest } = params;
+        const { data } = await getUserList({ pageNo: current, pageSize, ...rest });
+        return { data: data.list, total: data.total, success: true };
+      }}
+      toolBarRender={() => [
+        <Access code="system:user:create" key="add">
+          <Button type="primary" icon={<PlusOutlined />} onClick={handleAdd}>新增</Button>
+        </Access>,
+      ]}
+    />
+  );
+}
+```
+
+### 5.2 Props 定义
+
+```typescript
+// 使用 interface 定义 props
+interface UserCardProps {
+  user: User;                        // 必填
+  showActions?: boolean;             // 可选
+  size?: 'small' | 'medium' | 'large'; // 带默认值
+  onDelete: (id: number) => void;    // 回调
+  children?: React.ReactNode;        // 子组件
+}
+
+// 使用 destructuring + 默认值
+export default function UserCard({
+  user,
+  showActions = false,
+  size = 'medium',
+  onDelete,
+  children,
+}: UserCardProps) {
+  return <div>{/* ... */}</div>;
+}
+```
+
+### 5.3 组件拆分原则
+
+- 单个组件不超过 300 行，超出按职责拆分
+- 页面内的子组件（Modal、Drawer 等）放在 `src/pages/<feature>/components/` 目录
+- 全局复用组件放在 `src/components/`
+- 避免在组件内部定义类型，应放在 `src/types/` 目录
+
+### 5.4 自定义 Hook 规范
+
+```typescript
+// hooks/useAccess.ts — 以 use 开头
+import { useAuthStore } from '@/stores/useAuthStore';
+
+export function useAccess(code: string): boolean {
+  const hasPermission = useAuthStore((s) => s.hasPermission);
+  return hasPermission(code);
+}
+```
+
+---
+
+## 六、列表页标准模式（ProTable）
+
+> 所有「带筛选 + 分页」的列表都**必须**使用 `ProTable`，**不要再用** `Card + Form + Table`。
+> 树形列表（dept/menu）例外，用本地 `dataSource` + `pagination={false}` + `expandable`。
+
+### 6.1 标准模板
+
+```tsx
+import { useRef, useState } from 'react';
+import { App, Button, Space } from 'antd';
+import { PlusOutlined, DeleteOutlined } from '@ant-design/icons';
+import { ProTable, type ProColumns, type ActionType } from '@ant-design/pro-components';
+import { getXxxPage, deleteXxx, deleteXxxList, type XxxVO } from '@/api/xxx';
+import Access from '@/components/Access';
+import DictTag from '@/components/DictTag';
+import { dateFormatter } from '@/utils/formatTime';
+import { useDictStore } from '@/stores/useDictStore';
+import XxxModal from './components/XxxModal';
+
+const XxxPage: React.FC = () => {
+  const { message, modal } = App.useApp();
+  const actionRef = useRef<ActionType>(undefined);
+  const [selectedRowKeys, setSelectedRowKeys] = useState<React.Key[]>([]);
+  const [modalOpen, setModalOpen] = useState(false);
+  const [editId, setEditId] = useState<number | null>(null);
+  const getDictOptions = useDictStore((s) => s.getDictOptions);
+
+  const reload = () => actionRef.current?.reload();
+
+  const handleDelete = (record: XxxVO) => {
+    modal.confirm({
+      title: '确认删除？', okType: 'danger',
+      content: `确认删除「${record.name}」吗？`,
+      onOk: async () => {
+        await deleteXxx(record.id!);
+        message.success('删除成功'); reload();
+      },
+    });
+  };
+
+  const handleDeleteBatch = () => {
+    modal.confirm({
+      title: '确认批量删除？', okType: 'danger',
+      content: `确认删除选中的 ${selectedRowKeys.length} 项？`,
+      onOk: async () => {
+        await deleteXxxList(selectedRowKeys.map(Number));
+        message.success('删除成功');
+        setSelectedRowKeys([]);
+        reload();
+      },
+    });
+  };
+
+  const columns: ProColumns<XxxVO>[] = [
+    { title: '名称', dataIndex: 'name', width: 200 },
+    {
+      title: '状态', dataIndex: 'status', width: 100,
+      valueType: 'select',
+      valueEnum: Object.fromEntries(
+        getDictOptions('common_status').map((d) => [d.value, { text: d.label }]),
+      ),
+      render: (_, r) => <DictTag type="common_status" value={r.status} />,
+    },
+    {
+      title: '创建时间', dataIndex: 'createTime', width: 180,
+      valueType: 'dateRange',
+      search: {
+        transform: (value) => {
+          if (!Array.isArray(value)) return {};
+          return { createTimeStart: value[0], createTimeEnd: value[1] };
+        },
+      },
+      render: (_, r) => dateFormatter(r.createTime) || '-',
+    },
+    {
+      title: '操作', key: 'action', width: 140, fixed: 'right', search: false,
+      render: (_, record) => (
+        <Space>
+          <Access code="xxx:update">
+            <a onClick={() => { setEditId(record.id!); setModalOpen(true); }}>编辑</a>
+          </Access>
+          <Access code="xxx:delete">
+            <a style={{ color: '#ff4d4f' }} onClick={() => handleDelete(record)}>删除</a>
+          </Access>
+        </Space>
+      ),
+    },
+  ];
+
+  return (
+    <>
+      <ProTable<XxxVO>
+        columns={columns}
+        actionRef={actionRef}
+        rowKey="id"
+        scroll={{ x: 1200 }}
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        request={async (params: any) => {
+          const { current, pageSize, ...rest } = params;
+          const { data } = await getXxxPage({ pageNo: current ?? 1, pageSize: pageSize ?? 10, ...rest });
+          return { data: data.list, total: data.total, success: true };
+        }}
+        pagination={{ defaultPageSize: 10, showSizeChanger: true }}
+        rowSelection={{ selectedRowKeys, onChange: setSelectedRowKeys }}
+        toolBarRender={() => [
+          <Access code="xxx:create" key="add">
+            <Button type="primary" icon={<PlusOutlined />}
+              onClick={() => { setEditId(null); setModalOpen(true); }}>新增</Button>
+          </Access>,
+          <Access code="xxx:delete" key="batch">
+            <Button danger icon={<DeleteOutlined />}
+              disabled={selectedRowKeys.length === 0}
+              onClick={handleDeleteBatch}>批量删除</Button>
+          </Access>,
+        ]}
+      />
+      <XxxModal open={modalOpen} id={editId}
+        onSuccess={() => { setModalOpen(false); reload(); }}
+        onCancel={() => setModalOpen(false)} />
+    </>
+  );
+};
+
+export default XxxPage;
+```
+
+### 6.2 ProTable 列定义关键规则
+
+| 场景          | 写法                                                                                       |
+| ------------- | ------------------------------------------------------------------------------------------ |
+| 隐藏搜索      | `search: false`（**不是** `hideInSearch`）                                                 |
+| 下拉搜索      | `valueType: 'select'` + `valueEnum: Object.fromEntries(getDictOptions(...).map(...))`      |
+| 日期区间      | `valueType: 'dateRange'` + `search.transform` 拆 `xxxStart/xxxEnd`                         |
+| 日期区间渲染  | **必须用 `render`，不要用 `renderText`**                                                   |
+| 长 label 搜索 | `search={{ labelWidth: 'auto' }}`（在 ProTable 上）                                        |
+| request 参数  | 固定加 `// eslint-disable-next-line @typescript-eslint/no-explicit-any` 允许 `params: any` |
+| 树形表        | 去掉 `request`，改用 `dataSource={tree}` + `pagination={false}` + `expandable`             |
+
+---
+
+## 七、Modal / Drawer 使用标准规范
+
+### 7.1 整体布局原则
+
+1、表单较简单（字段 <4个），推荐使用 Modal。
+
+2、表单较复杂（字段 ≥ 4 个）或业务流程需要连续操作时，推荐使用右侧 Drawer 替代 Modal。
+
+> 根据表单字段数量分级选择布局和 Drawer 宽度。
+
+| 字段数量   | 布局                           | Drawer 宽度 | Form layout  | 说明                       |
+| ---------- | ------------------------------ | ----------- | ------------ | -------------------------- |
+| 4 ~ 10 个  | **一栏**，单列                 | **15%**     | `vertical`   | 字段少、简单，垂直单栏即可 |
+| 10 ~ 20 个 | **两栏** `Row`+`Col span={12}` | **30%**     | `horizontal` | 字段较多，两栏紧凑排列     |
+| 21 ~ 30 个 | **三栏** `Row`+`Col span={8}`  | **45%**     | `horizontal` | 字段很多，三栏并排         |
+| > 30 个    | **四栏** `Row`+`Col span={6}`  | **60%**     | `horizontal` | 大批量字段，四栏最大化空间 |
+
+### 7.2 Modal 标准模板
+
+> 表单较简单（字段 <4个），推荐使用 Modal。
+
+```tsx
+interface Props {
+  open: boolean;
+  id: number | null;
+  onSuccess: () => void;
+  onCancel: () => void;
+}
+
+const DEFAULT_FORM = { name: '', status: 0 };
+
+const XxxModal: React.FC<Props> = ({ open, id, onSuccess, onCancel }) => {
+  const { message } = App.useApp();
+  const [form] = Form.useForm();
+  const [confirmLoading, setConfirmLoading] = useState(false);
+  // 保留服务端原始字段，避免编辑时丢掉未在表单里出现的字段
+  const originData = useRef<Partial<XxxVO>>({});
+
+  useEffect(() => {
+    if (!open) return;
+    form.resetFields();
+    originData.current = {};
+    if (id != null) {
+      getXxx(id).then(({ data }) => {
+        originData.current = { ...data };
+        form.setFieldsValue(data);
+      });
+    } else {
+      form.setFieldsValue(DEFAULT_FORM);
+    }
+  }, [open, id, form]);
+
+  const handleOk = async () => {
+    let values: XxxVO;
+    try { values = await form.validateFields(); } catch { return; }
+    setConfirmLoading(true);
+    try {
+      const payload = { ...originData.current, ...values, ...(id != null ? { id } : {}) } as XxxVO;
+      if (id != null) {
+        await updateXxx(payload); message.success('修改成功');
+      } else {
+        await createXxx(payload); message.success('新增成功');
+      }
+      onSuccess();
+    } catch (err) {
+      message.error((err as Error).message || '操作失败');
+    } finally {
+      setConfirmLoading(false);
+    }
+  };
+
+  return (
+    <Modal title={id != null ? '编辑' : '新增'} open={open}
+      confirmLoading={confirmLoading}
+      onOk={handleOk} onCancel={onCancel}
+      width={580} destroyOnHidden>
+      <Form form={form}  initialValues={DEFAULT_FORM}>
+        {/* fields */}
+      </Form>
+    </Modal>
+  );
+};
+```
+
+### 7.3 Drawer 标准模板
+
+> 表单较复杂（字段 ≥ 4 个）或业务流程需要连续操作时，推荐使用右侧 Drawer 替代 Modal。
+
+```tsx
+import { Drawer, Form, Input, Select, InputNumber, DatePicker, Button, Space, Row, Col, message } from 'antd';
+
+interface Props {
+  open: boolean;
+  id: number | null;
+  onSuccess: () => void;
+  onClose: () => void;  // ← Drawer 用 onClose，不用 onCancel
+}
+
+const XxxDrawer: React.FC<Props> = ({ open, id, onSuccess, onClose }) => {
+  const [form] = Form.useForm();
+  const isEdit = id != null;
+
+  useEffect(() => {
+    if (open && id) {
+      getXxx(id).then(({ data }) => {
+        form.setFieldsValue({ ...data, dateField: dayjs(data.dateField) });
+      });
+    } else {
+      form.resetFields();
+    }
+  }, [open, id, form]);
+
+  const handleOk = async () => {
+    try {
+      const values = await form.validateFields();
+      const params = { ...values, id: id || undefined };
+      if (isEdit) {
+        await updateXxx(params);
+      } else {
+        await createXxx(params);
+      }
+      message.success('操作成功');
+      onSuccess();
+    } catch (error) {
+      // Validation failed
+    }
+  };
+
+  return (
+    <Drawer
+      title={isEdit ? '编辑' : '新增'}
+      open={open}
+      onClose={onClose}
+      destroyOnHidden={true}
+      size={600}
+      closable={{ placement: 'end' }}
+      mask={{ closable: false }}
+      styles={{ body: { background: '#f5f5f5' } }}
+      footer={
+        <Space style={{ float: 'right' }}>
+          <Button onClick={onClose}>取消</Button>
+          <Button type="primary" onClick={handleOk}>确定</Button>
+        </Space>
+      }
+    >
+      <Card style={{ border: 'none' }}>
+        <Form form={form} layout="vertical">
+          {/* fields — 根据字段数量选择布局，见 7.1 整体布局原则 */}
+        </Form>
+      </Card>
+    </Drawer>
+  );
+};
+```
+
+
+### 7.4 表单一栏布局
+
+> 字段 4~10 个时使用，Drawer 宽度 256，`layout="vertical"` 垂直单列排列。
+
+```tsx
+// 一栏布局：垂直单列，layout="vertical"，无需 Row/Col
+<Form form={form} layout="vertical">
+  <Form.Item name="fieldA" label="字段A" rules={[{ required: true }]}>
+    <Input />
+  </Form.Item>
+  <Form.Item name="fieldB" label="字段B" rules={[{ required: true }]}>
+    <Select options={[...]} />
+  </Form.Item>
+  <Form.Item name="fieldC" label="字段C" rules={[{ required: true }]}>
+    <InputNumber style={{ width: '100%' }} />
+  </Form.Item>
+  <Form.Item name="fieldD" label="字段D" rules={[{ required: true }]}>
+    <DatePicker style={{ width: '100%' }} />
+  </Form.Item>
+  {/* 继续追加字段即可，无需 Row/Col 包裹 */}
+</Form>
+```
+
+### 7.5 表单两栏布局
+
+> 字段 10~20 个时使用，每行两个 `Col span={12}`，`gutter={16}` 控制列间距。
+
+```tsx
+// 两栏布局：每行两个 Col span={12}，gutter={16} 控制列间距
+<Form form={form} layout="vertical">
+  <Row gutter={16}>
+    <Col span={12}>
+      <Form.Item name="fieldA" label="字段A" rules={[{ required: true }]}>
+        <Input />
+      </Form.Item>
+    </Col>
+    <Col span={12}>
+      <Form.Item name="fieldB" label="字段B" rules={[{ required: true }]}>
+        <Select options={[...]} />
+      </Form.Item>
+    </Col>
+  </Row>
+  <Row gutter={16}>
+    <Col span={12}>
+      <Form.Item name="fieldC" label="字段C" rules={[{ required: true }]}>
+        <InputNumber style={{ width: '100%' }} />
+      </Form.Item>
+    </Col>
+    <Col span={12}>
+      <Form.Item name="fieldD" label="字段D" rules={[{ required: true }]}>
+        <DatePicker style={{ width: '100%' }} />
+      </Form.Item>
+    </Col>
+  </Row>
+  {/* 奇数个字段时，最后一行可只放一个 Col span={12} */}
+  <Row gutter={16}>
+    <Col span={12}>
+      <Form.Item name="fieldE" label="字段E" rules={[{ required: true }]}>
+        <InputNumber style={{ width: '100%' }} />
+      </Form.Item>
+    </Col>
+  </Row>
+</Form>
+```
+
+**关键规则**：
+- 一栏：`layout="vertical"`，无需 `labelCol`/`wrapperCol`，直接排列 `Form.Item`
+- 两栏及以上：Form 设置 `layout="horizontal"` + `labelCol={{ span: 8 }}`，每行 `Row gutter={16}`
+- 每个 `Col span={12}` 放一个 `Form.Item`，输入组件统一 `style={{ width: '100%' }}` 撑满
+- Label 较短的字段可适当调小 `labelCol` 和 `wrapperCol` 比例
+- 奇数字段最后一行放剩余 `Col` 即可（不足不补）
+
+### 7.6 表单三栏布局
+
+> 字段在 20~30 个之间时，使用三栏布局，每行三个 `Col span={8}`。
+
+```tsx
+// 三栏布局：每行三个 Col span={8}，gutter={16}
+<Form form={form} layout="vertical" >
+  <Row gutter={16}>
+    <Col span={8}>
+      <Form.Item name="fieldA" label="字段A" rules={[{ required: true }]}>
+        <Input />
+      </Form.Item>
+    </Col>
+    <Col span={8}>
+      <Form.Item name="fieldB" label="字段B" rules={[{ required: true }]}>
+        <Select options={[...]} />
+      </Form.Item>
+    </Col>
+    <Col span={8}>
+      <Form.Item name="fieldC" label="字段C" rules={[{ required: true }]}>
+        <InputNumber style={{ width: '100%' }} />
+      </Form.Item>
+    </Col>
+  </Row>
+  <Row gutter={16}>
+    <Col span={8}>
+      <Form.Item name="fieldD" label="字段D" rules={[{ required: true }]}>
+        <DatePicker style={{ width: '100%' }} />
+      </Form.Item>
+    </Col>
+    {/* 尾部不足 3 个时按实际数量放即可，无需补空白 Col */}
+  </Row>
+</Form>
+```
+
+### 7.7 表单四栏布局
+
+> 字段超过 30 个时，使用四栏布局，每行四个 `Col span={6}`，Drawer 宽度 1024。
+
+```tsx
+// 四栏布局：每行四个 Col span={6}
+<Form form={form} layout="vertical">
+  <Row gutter={16}>
+    <Col span={6}>
+      <Form.Item name="fieldA" label="字段A" rules={[{ required: true }]}>
+        <Input />
+      </Form.Item>
+    </Col>
+    <Col span={6}>
+      <Form.Item name="fieldB" label="字段B" rules={[{ required: true }]}>
+        <Select options={[...]} />
+      </Form.Item>
+    </Col>
+    <Col span={6}>
+      <Form.Item name="fieldC" label="字段C" rules={[{ required: true }]}>
+        <InputNumber style={{ width: '100%' }} />
+      </Form.Item>
+    </Col>
+    <Col span={6}>
+      <Form.Item name="fieldD" label="字段D" rules={[{ required: true }]}>
+        <DatePicker style={{ width: '100%' }} />
+      </Form.Item>
+    </Col>
+  </Row>
+</Form>
+```
+
+### 7.8 约定
+
+- Props 固定四件套：`open`, `id`, `onSuccess`, `onCancel`（Modal）/ `onClose`（Drawer），**不要**再用 `defineExpose / ref.open()`
+- Drawer 标题统一「新增 / 编辑」，Modal 同理
+- `originData = useRef()` 保留服务端字段，提交时合并：`{ ...originData.current, ...values, id }`
+- 编辑模式下隐藏字段用 `hidden={!!id}` 而非条件渲染（条件渲染会让 `validateFields` 跳过该字段）
+- 用  `destroyOnHidden` 自动清理状态，**不要**手动 reset
+
+---
+
+## 八、TypeScript 规范
+
+### 8.1 类型定义
+
+```typescript
+// 优先使用 interface（可扩展），联合类型 / 工具类型使用 type
+interface User {
+  id: number;
+  name: string;
+  email: string;
+  active: boolean;
+}
+
+// 联合类型
+type Status = 'success' | 'warning' | 'danger';
+
+// API 响应类型（来自 @/types/api，不要重写）
+interface ApiResponse<T> {
+  code: number;
+  message: string;
+  data: T;
+}
+
+interface PageResult<T> {
+  total: number;
+  rows: T[];
+}
+```
+
+### 8.2 类型规则
+
+- **禁用 `any`**；必须时单行 `// eslint-disable-next-line @typescript-eslint/no-explicit-any`
+- API 入参 / 出参 / store 必须显式类型
+- Hook 暴露的 ref 类型用 `forwardRef<Handle, Props>` + `useImperativeHandle`
+- 不要写 `as any`；要么写正确类型，要么 `as unknown as Xxx`
+- 类型文件放在 `src/types/`，按领域组织
+
+---
+
+## 九、样式规范
+
+### 9.1 CSS 文件
+
+- 使用独立的 `.css` 文件，搭配功能名前缀类名（如 `.user-list`）
+- 类名使用 kebab-case
+- 避免使用缩写，如 `.btn` → `.button`
+
+### 9.2 Ant Design 样式定制
+
+- 优先使用 Ant Design 组件的内置属性（`size`, `type`, `variant`）
+- 全局主题定制通过 `ConfigProvider` 的 `theme` 属性
+- 局部覆盖样式使用 CSS 类 + 选择器，避免 `!important`
+- **自定义 SCSS 变量覆盖 → 改用 `ConfigProvider` + `theme.token`**
+
+### 9.3 响应式设计
+
+- 使用 Ant Design 的 `Grid` 组件（`Row` / `Col`）进行响应式布局
+- 断点参考 Ant Design 预设：`xs < 576 < sm < 768 < md < 992 < lg < 1200 < xl`
+- **左右分栏用原生 `display: flex`**，不要用 `Row/Col`（`Row` 默认 `flex-wrap: wrap` 会被换行）
+
+---
+
+## 十、路由规范
+
+### 10.1 路由定义
+
+```typescript
+import { createBrowserRouter } from 'react-router';
+
+const router = createBrowserRouter([
+  { path: '/login', Component: LoginPage },
+  {
+    path: '/',
+    Component: AdminLayout,
+    children: [
+      { path: 'dashboard', Component: DashboardPage },
+      { path: 'profile', Component: ProfilePage },
+      { path: '*', Component: NotFoundPage },
+    ],
+  },
+]);
+```
+
+### 10.2 动态路由注入
+
+- 登录成功后通过 `addDynamicRoutes(menus)` 动态注入路由
+- 使用 `import.meta.glob('@/pages/**/index.{tsx,jsx}')` 实现懒加载
+- 配合 `Suspense` + `Spin` 提供加载态反馈
+- 退出登录时调用 `resetDynamicRoutes()` 清除动态路由
+- **外部链接（http/https 路径）在路由生成时被过滤**
+
+### 10.3 路由导航
+
+```typescript
+import { useNavigate, useSearchParams, useParams } from 'react-router';
+
+const navigate = useNavigate();
+const [searchParams] = useSearchParams();
+const { id } = useParams();
+
+navigate('/user/list');
+navigate(`/user/detail/${id}`);
+navigate(-1); // 返回上一页
+```
+
+### 10.4 路由守卫
+
+- 使用 `<AuthGuard>` 组件保护受保护的路由
+- AuthGuard 检查 token 和 userInfo，未登录则重定向至 `/login`
+- 携带 `redirect` 参数以便登录后自动跳转回原页面
+- AuthGuard 使用 `useRef` 守卫防止重复 fetch
+
+---
+
+## 十一、状态管理规范
+
+### 11.1 Zustand Store 结构
+
+```typescript
+// stores/useAuthStore.ts
+import { create } from 'zustand';
+
+interface AuthState {
+  token: string | null;
+  userInfo: UserInfo | null;
+  roles: string[];
+  permissions: string[];
+  menus: Permission[];
+  setToken: (token: string) => void;
+  login: (username: string, password: string) => Promise<void>;
+  logout: () => void;
+  hasPermission: (code: string) => boolean;
+}
+
+export const useAuthStore = create<AuthState>((set, get) => ({
+  token: null,
+  userInfo: null,
+  roles: [],
+  permissions: [],
+  menus: [],
+  setToken: (token) => set({ token }),
+  login: async (username, password) => {
+    const res = await login({ username, password });
+    set({ token: res.data.accessToken });
+  },
+  logout: () => set({ token: null, userInfo: null, roles: [], permissions: [], menus: [] }),
+  hasPermission: (code) => {
+    const { permissions } = get();
+    return permissions.includes('*:*:*') || permissions.includes(code);
+  },
+}));
+```
+
+### 11.2 Store 使用规范
+
+```typescript
+import { useAuthStore } from '@/stores/useAuthStore';
+
+export default function UserList() {
+  // 选择器模式避免不必要的重渲染
+  const { token, hasPermission } = useAuthStore();
+  const userName = useAuthStore((state) => state.userInfo?.name);
+  const canDelete = hasPermission('system:user:delete');
+
+  return <div>{userName}</div>;
+}
+```
+
+### 11.3 Store 分类
+
+| Store          | 职责                        | 持久化                              |
+| -------------- | --------------------------- | ----------------------------------- |
+| `useAuthStore` | token、用户信息、权限、菜单 | 否（页面刷新清空）                  |
+| `useAppStore`  | 侧边栏折叠状态、暗色模式    | 是（localStorage: `admin-pro-app`） |
+| `useDictStore` | 字典类型到数据的映射        | 否                                  |
+
+---
+
+## 十二、API 接口规范
+
+### 12.1 文件组织
+
+```typescript
+// api/system/user.ts
+import request from '@/utils/request';
+import type { ApiResponse, PageResult, PageParams } from '@/types/api';
+
+export interface UserVO {
+  id?: number;
+  name: string;
+  createTime?: string;
+}
+
+export const getUserPage = (params: PageParams) =>
+  request.get<unknown, ApiResponse<PageResult<UserVO>>>('/system/user/page', { params });
+
+export const getUser = (id: number) =>
+  request.get<unknown, ApiResponse<UserVO>>(`/system/user/get?id=${id}`);
+
+export const createUser = (data: UserVO) =>
+  request.post<unknown, ApiResponse<void>>('/system/user/create', data);
+
+export const updateUser = (data: UserVO) =>
+  request.put<unknown, ApiResponse<void>>('/system/user/update', data);
+
+export const deleteUser = (id: number) =>
+  request.delete<unknown, ApiResponse<void>>(`/system/user/delete?id=${id}`);
+
+export const deleteUserList = (ids: number[]) =>
+  request.delete<unknown, ApiResponse<void>>(`/system/user/delete-list?ids=${ids.join(',')}`);
+```
+
+### 12.2 约定
+
+- `ApiResponse<T>`、`PageParams`、`PageResult<T>` 来自 `@/types/api`，**不要重写**
+- `code === 0` 时拦截器自动解包；`code === 401` 自动跳登录；其余 `Promise.reject` 并 `message.error`
+- 文件下载用 `download(url, params)`（`@/utils/request` 导出，自动 blob + Content-Disposition 解析）
+- Axios 实例超时时间 30s
+- 请求拦截器自动附加 `Bearer` token 和 `tenant-id` 头
+- **Token 刷新**：并发 401 请求排队，刷新 token 后重放
+
+### 12.3 响应码
+
+| code  | 含义                              |
+| ----- | --------------------------------- |
+| `0`   | 成功                              |
+| `401` | 未授权（自动刷新 token 或跳登录） |
+| 其他  | 失败，`message` 为错误提示        |
+
+---
+
+## 十三、国际化（i18n）规范
+
+项目使用 `react-i18next` + `i18next-resources-to-backend` 实现多语言支持，通过 Vite 的 `import.meta.glob` 自动加载所有 locale 文件，**无需手动注册**。
+
+### 13.1 语言包目录结构
+
+```
+src/locales/
+├── zh-CN/              # 简体中文（默认语言）
+│   ├── system/
+│   │   ├── post.ts
+│   │   └── user.ts
+│   ├── mdm/
+│   │   ├── codeRule.ts
+│   │   └── codeMapping.ts
+│   ├── login.ts
+│   ├── common.ts
+│   └── ...
+├── en-US/              # 英文
+│   ├── system/
+│   ├── mdm/
+│   └── ...
+├── ja-JP/              # 日语
+├── fr-FR/              # 法语
+├── es-ES/              # 西班牙语
+├── ar-SA/              # 阿拉伯语
+├── ru-RU/              # 俄语
+└── de-DE/              # 德语
+```
+
+### 13.2 命名空间（Namespace）
+
+- 每个 locale 文件的路径即为命名空间名。例如 `src/locales/zh-CN/mdm/codeRule.ts` 对应 `useTranslation('mdm/codeRule')`。
+- **命名空间路径规则**：按模块目录组织，文件名与业务模块对应。
+- 通用文案放在 `common.ts`（`common` 命名空间），页面/模块级文案放在对应子目录。
+
+### 13.3 语言包文件格式
+
+```typescript
+// src/locales/zh-CN/mdm/codeRule.ts
+export default {
+  table: {
+    id: '编号',
+    ruleName: '规则名称',
+    createTime: '创建时间',
+    action: '操作',
+  },
+  form: {
+    ruleName: '规则名称',
+    inputRuleName: '请输入规则名称',
+    editTitle: '编辑编码规则',
+    addTitle: '新增编码规则',
+  },
+  btn: {
+    add: '新增',
+    edit: '编辑',
+    delete: '删除',
+  },
+  msg: {
+    deleteSuccess: '删除成功',
+    updateSuccess: '更新成功',
+    createSuccess: '创建成功',
+    deleteConfirm: '确认删除该编码规则？',
+  },
+};
+```
+
+**结构约定**：
+- 统一使用嵌套对象，**不导出具名变量**。
+- 按 UI 区域分组：`table`（列标题）、`form`（表单标签/占位符/弹窗标题）、`btn`（按钮文案）、`msg`（提示/确认消息）。
+- key 用 camelCase，不使用中文拼音或缩写。
+
+### 13.4 组件中使用
+
+```tsx
+import { useTranslation } from 'react-i18next';
+
+const { t } = useTranslation('mdm/codeRule');
+
+// 表格列
+{ title: t('table.ruleName'), dataIndex: 'ruleName' }
+
+// 按钮文案
+<Button>{t('btn.add')}</Button>
+
+// 成功提示
+message.success(t('msg.createSuccess'));
+
+// 带插值
+t('msg.deleteConfirm', { name: record.ruleName })
+// 对应语言包中: "确认删除「{{name}}」吗？"
+```
+
+### 13.5 Modal 标题动态化
+
+```tsx
+<Modal title={id ? t('form.editTitle') : t('form.addTitle')} ...>
+```
+
+### 13.6 新增模块步骤
+
+**每新增一个业务模块，必须为所有 8 种语言创建对应的 locale 文件**：
+
+1. 在 `src/locales/<lng>/<module>/` 下创建语言包文件（codeRule.ts、codeMapping.ts 等）
+2. 确保 8 种语言包（zh-CN / en-US / ja-JP / fr-FR / es-ES / ar-SA / ru-RU / de-DE）都包含相同的 key 结构
+3. 组件中使用 `useTranslation('<module>/<file>')` 引用
+
+> **注意**：`i18next` 通过 `import.meta.glob('@/locales/**/*.ts')` 自动加载所有文件，**不需要**在 `src/i18n/index.ts` 中手动注册。
+
+### 13.7 语言切换
+
+用户通过 Header 的语言切换组件切换语言，切换后调用 `i18n.changeLanguage(lng)` 并持久化到 `localStorage('app-language')`。
+
+### 13.8 不支持的语言
+
+`fallbackLng` 配置为 `'zh-CN'`，任何缺失的 key 都会回落到简体中文。
+
+---
+
+## 十四、字典系统规范
+
+字典在登录后由 `AuthGuard` 一次性 `useDictStore.fetchDictData()` 全部缓存到内存，所有页面直接读：
+
+```tsx
+const getDictOptions = useDictStore((s) => s.getDictOptions);
+const getDictLabel = useDictStore((s) => s.getDictLabel);
+
+// 渲染标签
+<DictTag type="common_status" value={record.status} />
+
+// ProTable 搜索下拉
+valueEnum: Object.fromEntries(
+  getDictOptions('ai_platform').map((d) => [d.value, { text: d.label }])
+)
+
+// Form Select 下拉
+options={getDictOptions('system_org_type').map((d) => ({
+  label: d.label, value: Number(d.value),  // ← 字段是 number 时记得转
+}))}
+```
+
+**新增字典必须三处都加**（`src/mocks/data/index.ts`）：
+
+1. `mockDictTypes` — 字典类型表
+2. `mockDictData` — 字典数据表（注意 value 始终是 string）
+3. 业务代码的 `<DictTag type="...">` 与 `getDictOptions('...')`
+
+> **注意**：字典 `value` 在数据库是 string；如果业务字段类型是 number（如 `status: number`），表单 Select 的 `value` 要 `Number(d.value)` 转回去。
+
+---
+
+## 十五、权限系统规范
+
+### 14.1 组件级权限
+
+```tsx
+import Access from '@/components/Access';
+import { useAccess } from '@/components/Access';
+
+// 组件级权限控制
+<Access code="system:user:create">
+  <Button type="primary">新增</Button>
+</Access>
+
+// Hook 级权限控制
+const canUpdate = useAccess('system:menu:update');
+```
+
+### 14.2 权限检查
+
+- 权限码格式：`system:user:create`（模块:资源:操作）
+- `*:*:*` 代表超级管理员，拥有所有权限
+- `checkPermi(permissions[])` 检查是否有**任意一个**权限
+- `checkRole(roles[])` 检查是否有**任意一个**角色（`super_admin` 跳过）
+
+### 14.3 新增菜单+按钮权限三步
+
+1. `mockAdminBackendMenus`（或子菜单数组）加 type=2 菜单 + type=3 子按钮（path 为空，name 中文）
+2. `collectPermissionsFromBackendMenus` 的 `codeMap` 注册 `中文名 → 权限码`
+3. 业务代码用 `<Access code="xxx">` 包裹按钮
+
+---
+
+## 十六、Mock 规范
+
+### 15.1 新建模块步骤
+
+1. `src/mocks/data/index.ts` 加 mock 类型 + seed 数据 + 必要字典
+2. `src/mocks/handlers/<module>.ts` 写 MSW handler，统一 `success(data)` helper
+3. 在 `src/mocks/handlers/index.ts` 注册到 `handlers` 数组
+4. 路径必须以 `/admin-api/` 开头
+
+### 15.2 Handler 模板
+
+```ts
+import { http, HttpResponse } from 'msw';
+
+function success<T>(data: T) {
+  return HttpResponse.json({ code: 0, message: 'ok', data });
+}
+
+http.get('/admin-api/xxx/page', async ({ request }) => {
+  await delay(150);
+  const url = new URL(request.url);
+  const pageNo = Number(url.searchParams.get('pageNo') || '1');
+  const pageSize = Number(url.searchParams.get('pageSize') || '10');
+  // 过滤、分页
+  return success({ list, total });
+}),
+```
+
+> **注意**：MSW handler 路径**必须**带 `/admin-api/` 前缀，否则拦截不到。
+
+---
+
+## 十七、上传组件规范
+
+### 16.1 标准用法
+
+```tsx
+import { Upload } from 'antd';
+import { getAccessToken } from '@/utils/token';
+import { useAuthStore } from '@/stores/useAuthStore';
+
+<Upload
+  name="file"
+  action="/admin-api/infra/file/upload"
+  headers={{
+    Authorization: `Bearer ${getAccessToken() ?? ''}`,
+    'tenant-id': String(useAuthStore.getState().tenantId ?? ''),
+  }}
+  beforeUpload={...}
+  onChange={({ file }) => {
+    if (file.status === 'done') {
+      const resp = file.response as { code?: number; data?: string };
+      if (resp?.code === 0 && resp.data) {
+        form.setFieldsValue({ avatar: resp.data });
+      }
+    }
+  }}
+/>
+```
+
+或直接使用项目封装：`import { UploadFile, UploadImg, UploadImgs } from '@/components/UploadFile'`。
+
+### 16.2 Upload 在 Form 中的正确使用
+
+> AntD `Upload` 不识别 `value` 属性。`<Form.Item name="logo">` 默认会注入 `value` → Upload 报警告。
+
+**正确做法**：外层 `Form.Item` 仅做标签（不带 `name`），里面套一个 `<Form.Item name="logo" noStyle hidden><Input /></Form.Item>` 持有值，Upload 通过 `form.setFieldsValue({ logo: url })` 写入。
+
+---
+
+## 十八、时间格式化规范
+
+**统一使用 `dateFormatter`**，禁止页面内手写 `dayjs().format(...)` 或字符串拼接：
+
+```tsx
+import { dateFormatter } from '@/utils/formatTime';
+
+// ProTable 列
+render: (_, record) => dateFormatter(record.createTime) || '-',
+
+// Descriptions
+<Descriptions.Item label="创建时间">{dateFormatter(data.createTime) || '-'}</Descriptions.Item>
+```
+
+`dateFormatter` 接受 `string | number | Date | null`，统一返回 `YYYY-MM-DD HH:mm:ss`，空值返回空串。
+
+> **注意**：如果后端 `createTime` 可能是 number/Date，统一用 `new Date(value).getTime()` 包装再比较。
+
+---
+
+## 十九、性能优化规范
+
+### 18.1 组件优化
+
+```tsx
+// 路由级代码分割
+import { lazy, Suspense } from 'react';
+import { Spin } from 'antd';
+
+const UserList = lazy(() => import('@/pages/user-list'));
+
+<Suspense fallback={<Spin size="large" />}>
+  <UserList />
+</Suspense>;
+
+// 避免不必要的重渲染
+export const UserItem = React.memo(function UserItem({ user }: { user: User }) {
+  return <div>{user.name}</div>;
+});
+```
+
+### 18.2 Hooks 优化
+
+```tsx
+// useCallback 缓存事件处理函数
+const handleDelete = useCallback(async (id: number) => {
+  await deleteUser(id);
+  fetchList();
+}, [fetchList]);
+
+// useMemo 缓存计算结果
+const filteredUsers = useMemo(
+  () => users.filter((user) => user.active),
+  [users],
+);
+```
+
+### 18.3 列表渲染
+
+```tsx
+// 必须提供稳定的 key
+{users.map((user) => <UserItem key={user.id} user={user} />)}
+```
+
+---
+
+## 二十、代码质量标准
+
+### 19.1 代码复杂度
+
+- 单个函数不超过 50 行
+- 单个文件不超过 300 行，超出按职责拆分
+- 嵌套层级不超过 3 层
+- 圈复杂度不超过 10
+
+### 19.2 错误处理
+
+```typescript
+async function handleSubmit(values: UserFormValues) {
+  try {
+    await createUser(values);
+    message.success('新增成功');
+    closeModal();
+  } catch (error) {
+    // request 拦截器已弹出错误提示，此处可做额外处理
+    console.error('创建用户失败:', error);
+  }
+}
+```
+
+### 19.3 ESLint 规则
+
+- 使用 `typescript-eslint` 进行 TypeScript 感知检查
+- 启用 `eslint-plugin-react-hooks` 检查 Hooks 使用规则
+- 启用 `eslint-plugin-react-refresh` 检查 HMR 兼容性
+- 禁止在 `useEffect` 中遗漏依赖项
+- 提交前必须本地通过：`npx tsc -b` 与 `npx eslint <changed-files>`
+
+### 19.4 构建
+
+- 构建必须通过：`npm run build`（等价于 `tsc -b && vite build`）
+
+---
+
+## 二十一、常见问题规范（必读陷阱）
+
+> 以下均为项目实际踩过的坑，新增代码时必须注意。
+
+### 20.1 `form.validateFields()` 只返回已挂载 Form.Item
+
+- 编辑模式隐藏字段（如 `username/password`）不会被收集
+- 提交时必须 `{ ...originData.current, ...values, id }` 合并
+- 隐藏字段用 `hidden={!!id}`，**不要**用 `{!id && <Form.Item>}`
+
+### 20.2 AntD `Upload` 不识别 `value` 属性
+
+- `<Form.Item name="logo">` 默认会注入 `value` → Upload 报警告
+- **正确做法**：外层 `Form.Item` 仅做标签（不带 `name`），里面套 `<Form.Item name="logo" noStyle hidden><Input /></Form.Item>` 持有值
+
+### 20.3 AntD Tree `onSelect` 点击已选节点返回空数组
+
+- 不要自己做 toggle，直接判断 `keys.length === 0`
+
+### 20.4 AntD Tree 勾选要收集 `halfCheckedKeys`
+
+- 菜单权限分配父节点半选也要提交，用 `onCheck` 的 `info.halfCheckedKeys`
+
+### 20.5 Tree 编辑回显只勾选叶子节点
+
+- 直接 `setCheckedKeys(所有menuIds)` 会让父节点全选 → 子节点都被选
+- 用 `getLeafKeys()` 只勾叶子
+
+### 20.6 `react-hooks/set-state-in-effect`
+
+- `useEffect` 内调 `setState` 或调用内部包含 setState 的函数会被 lint 标记
+- **统一处理**：在 setState 行（或 `void fetchList()` 行）上方加 `// eslint-disable-next-line react-hooks/set-state-in-effect`
+
+### 20.7 MSW 路径必须 `/admin-api/` 前缀
+
+- `baseURL = http://127.0.0.1:48080/admin-api`，handler 不带 `/admin-api/` 拦截不到
+
+### 20.8 flex 代替 Row/Col 做左右分栏
+
+- AntD `Row` 默认 `flex-wrap: wrap`，左侧树+右侧列表会被换行
+- 用原生 `display: flex` + `flexShrink: 0`
+
+### 20.9 Drawer 宽度直接使用 `width` 属性
+
+- Ant Design 6 中 `width` 属性直接可用：`<Drawer width={600}>`
+- 默认宽度 378px，常用值：480 / 520 / 600 / 720
+- 也可用 `size="large"` 取预设（约 736px）
+
+### 20.10 Badge 显示数字而非红点
+
+- `<Badge count={n} overflowCount={99} size="small">` 而非 `dot`
+- count 为 0 时 antd 自动隐藏徽标
+
+### 20.11 `localeCompare` 仅对 string 有效
+
+- 如果后端 `createTime` 可能是 number/Date，统一用 `new Date(v).getTime()` 比较
+
+### 20.12 ProTable `valueType: 'dateRange'` 列必须用 `render` 而非 `renderText`
+
+- `renderText` 会被 valueType 的 dateRange 处理逻辑覆盖，单元格显示空白
+
+### 20.13 页面文件路径必须等于后端菜单 `component`
+
+- 例：后端给 `infra/data-source-config/index` → 文件 `src/pages/infra/data-source-config/index.tsx`
+- 错位会出现 `Component not found` 警告，并 404
+
+### 20.14 mock 菜单注册点要更新 codeMap
+
+- 加新权限按钮时除了菜单数组，还要在 `collectPermissionsFromBackendMenus` 内的 `codeMap` 注册
+
+### 20.15 避免缓存数据为空导致 Select 显示原始 ID
+
+- 父组件应在挂载时一次性加载下拉数据：`useEffect(() => { fetch(); }, [])`，**不要**只在「新增」按钮 onClick 中拉
+
+### 20.16 CRLF/LF 警告
+
+- Windows 上 git add 会提示 `LF will be replaced by CRLF`，无需处理
+
+---
+
+## 二十二、Vue → React 迁移映射表
+
+| Vue (Element Plus)                      | React (Ant Design 6)                                                 |
+| --------------------------------------- | -------------------------------------------------------------------- |
+| `<el-form v-model>`                     | `<Form form={form}>` + `Form.useForm()`                              |
+| `ref.validate()`                        | `await form.validateFields()`（**只返回已挂载字段**）                |
+| `<el-dialog :visible>`                  | `<Modal open={open}>`                                                |
+| `<el-drawer :visible>`                  | `<Drawer open={open} onClose={...}>`                                 |
+| `defineExpose({ open })`                | props: `open, id, onSuccess, onCancel`（Modal）/ `onClose`（Drawer） |
+| `<el-table><el-table-column>`           | `<ProTable columns={[...]} request={...} />`                         |
+| `v-model` 双向绑定                      | `useState` + `value/onChange`                                        |
+| `reactive() / ref()`                    | `useState()`                                                         |
+| `onMounted()`                           | `useEffect(() => {}, [])`                                            |
+| `watch()`                               | `useEffect(() => {}, [dep])`                                         |
+| `computed()`                            | `useMemo()`                                                          |
+| `defineEmits(['success'])`              | `props.onSuccess()`                                                  |
+| `pinia store`                           | `zustand store`                                                      |
+| `v-hasPermi`                            | `<Access code="xxx">`                                                |
+| `v-loading`                             | `<Spin spinning>` 或组件自身 `loading` 属性                          |
+| `message.delConfirm()`                  | `modal.confirm({ title: '确认删除？', okType: 'danger', onOk })`     |
+| `getStrDictOptions / getIntDictOptions` | `getDictOptions(type)` 统一返回                                      |
+| `dateFormatter`                         | 复用项目同名 `dateFormatter`                                         |
+| `el-tree show-checkbox`                 | `<Tree checkable selectable={false}>` + `onClick` 切换               |
+| `v-model:visible` Drawer/Modal          | `open` + `onClose/onCancel`                                          |
+| `el-input v-model`                      | `<Input value/onChange>` 受控                                        |
+| `el-switch v-model`                     | `<Switch checked/onChange>`                                          |
+| 原生 Date                               | `dayjs(value)` 或 `new Date(value).getTime()`                        |
+| 自定义 SCSS 变量覆盖                    | `ConfigProvider` + `theme.token`                                     |
+
+> **Vue 路径 → React 文件**：后端菜单 `component` 字段决定 React 文件位置。`ai/chat/index/index` → `src/pages/ai/chat/index/index.tsx`。
+
+---
+
+## 总结
+
+本规范文档涵盖了 React 19 + TypeScript 6 + Ant Design 6 项目的完整开发规范。团队成员必须严格遵守，以确保代码质量和协作效率。
+
+**重要提醒**：
+1. 所有新代码必须符合本规范
+2. 代码评审时重点检查规范遵守情况
+3. 定期更新规范以适应项目发展
+4. 遇到规范未覆盖的情况，及时讨论并补充
+
+**新模块自检清单**：
+
+- [ ] 文件路径与后端菜单 path 对齐
+- [ ] API、Mock handler、Mock data、菜单、权限码 五处全部更新
+- [ ] 所有时间字段用 `dateFormatter` 渲染
+- [ ] 所有字典字段用 `<DictTag>` + `valueEnum`
+- [ ] 所有按钮用 `<Access code="...">` 包裹
+- [ ] Modal 用 `open/id/onSuccess/onCancel` 四件套 + `originData` 合并
+- [ ] ProTable 而非手撸 Card+Form+Table
+- [ ] `npm run build` 通过
+- [ ] `npx eslint <new-files>` 零错误
+- [ ] 关键逻辑加中文注释，复杂分支说明「为什么这么写」
+
+---
+
+**文档结束**
+
+*本文档作为前端开发的标准规范，所有开发人员必须严格遵守。*