adspecs 0.1.32 → 0.1.34

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

@@ -1,1443 +0,0 @@
-# 前端编码规范
-
-> **版本**: 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>` 零错误
-- [ ] 关键逻辑加中文注释，复杂分支说明「为什么这么写」
-
----
-
-**文档结束**
-
-*本文档作为前端开发的标准规范，所有开发人员必须严格遵守。*