adspecs 0.1.32 → 0.1.34

package/references/ant6-front-standard/03-/345/210/227/350/241/250/350/247/204/350/214/203.md

@@ -1,147 +1,222 @@
-# 列表规范
-
-> 适用范围: React 19 + TypeScript 6 + Ant Design 6 + ProComponents
-> 版本: v3.3
-
----
-
-## 1、列表页标准模式（ProTable）
-
-> 所有「带筛选 + 分页」的列表都**必须**使用 `ProTable`，**不要再用** `Card + Form + Table`。
-> 树形列表（dept/menu）例外，用本地 `dataSource` + `pagination={false}` + `expandable`。
-
-### 1.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;
-```
-
-### 1.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`             |
-
----
-
+# 列表规范
+
+> 适用范围: React 19 + TypeScript 6 + Ant Design 6 + ProComponents
+> 版本: v3.4
+
+---
+
+## 1、列表页标准模式（ProTable）
+
+> 所有「带筛选 + 分页」的列表都**必须**使用 `ProTable`，**不要再用** `Card + Form + Table`。
+> 树形列表（dept/menu）例外，用本地 `dataSource` + `pagination={false}` + `expandable`。
+
+**三条硬性要求**：
+
+1. **高级筛选区**：`search={{ layout: 'vertical', span: <按筛选项数量分档> }}` —— 表单项 **vertical 布局**（label 在上），**span 按筛选项数量分档**（见 §1.1a）
+2. **操作栏**：若表格有操作列，宽度统一 `width: ACTION_COL_WIDTH`（= **150**，以 `TableActions` 组件导出为准，`fixed: 'right'`，`search: false`）
+3. **操作项展示规则**：操作项 **≤ 3 个平铺展示**；**> 3 个**时前 3 个平铺，其余收进 `...`，**鼠标悬停展开**。展示顺序按**后台菜单功能设置排序**（菜单树的按钮节点 `sort` 升序）；具体显示的项**按用户权限与数据状态动态计算，不得写死**——统一使用通用组件 `<TableActions />`（见 §1.3）
+
+### 1.1a 高级筛选区 span 分档
+
+> vertical 布局下，span 决定每行可容纳的筛选项数量（24 栅格制）。**筛选项数量 N** = 未设 `search: false` 且带 `dataIndex`/`valueType` 的列数（含 `hideInTable: true` 的隐藏搜索列，如日期区间拆分列）。
+
+| 筛选项数量 N | span | 每行项数 | 示例 |
+| ------------ | ---- | -------- | ---- |
+| N ≤ 2        | 8    | 3        | `search={{ layout: 'vertical', span: 8 }}` |
+| N = 3        | 6    | 4        | `search={{ layout: 'vertical', span: 6 }}` |
+| N = 4-6      | 4    | 6        | `search={{ layout: 'vertical', span: 4 }}` |
+
+- **日期区间（dateRange）**：组件约占两栏宽度。当 N = 4-6 且含日期区间时，日期列通过 `order`（Form 排序，数值大者靠后）排到搜索表单**最后**，自然换行到第二行；N ≤ 3（span 8/6）时日期项宽度充足，无需处理
+- **上限**：单页筛选项建议 ≤ 6 项；超过时靠高级筛选区默认「展开/收起」自折叠，不刻意堆满
+
+### 1.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 TableActions, { ACTION_COL_WIDTH, type TableActionItem } from '@/components/TableActions';
+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();
+      },
+    });
+  };
+
+  /**
+   * 操作项定义（顺序即默认展示顺序；权限与数据状态驱动显隐，不写死）：
+   * - permission：按钮权限码（菜单树 type=3 按钮），未授权自动隐藏
+   * - show：数据状态判定（布尔或 (record) => boolean），如「草稿才显示编辑」
+   * - 最终展示顺序由 TableActions 按当前菜单按钮 sort 重排
+   */
+  const buildActionItems = (record: XxxVO): TableActionItem<XxxVO>[] => {
+    const items: TableActionItem<XxxVO>[] = [];
+    const push = (key: string, show: boolean, permission: string, label: string, danger?: boolean) => {
+      if (show) items.push({ key, permission, label, danger, onClick: () => setEditId(record.id!) && setModalOpen(true) });
+    };
+    push('edit', true, 'xxx:update', '编辑');
+    push('delete', record.status !== 'PUBLISHED', 'xxx:delete', '删除', true);
+    return items;
+  };
+
+  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: ACTION_COL_WIDTH, fixed: 'right', search: false,
+      render: (_, record) => <TableActions record={record} items={buildActionItems(record)} />,
+    },
+  ];
+
+  return (
+    <>
+      <ProTable<XxxVO>
+        columns={columns}
+        actionRef={actionRef}
+        rowKey="id"
+        scroll={{ x: 1200 }}
+        // 高级筛选区：表单项 vertical 布局，span 按筛选项数量分档（本示例 3 项 → span 6，见 §1.1a）
+        search={{ layout: 'vertical', span: 6 }}
+        // 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;
+```
+
+### 1.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 上）                                        |
+| 高级筛选区    | `search={{ layout: 'vertical', span: <分档> }}`（表单项垂直，span 按筛选项数量分档，见 §1.1a） |
+| 操作列        | `width: ACTION_COL_WIDTH`（150）+ `fixed: 'right'` + `search: false` + `<TableActions />`；操作项文字较多时可自定义加宽（如 180） |
+| request 参数  | 固定加 `// eslint-disable-next-line @typescript-eslint/no-explicit-any` 允许 `params: any` |
+| 树形表        | 去掉 `request`，改用 `dataSource={tree}` + `pagination={false}` + `expandable`             |
+
+### 1.3 通用操作组件 TableActions
+
+> 路径：`web-ui/src/components/TableActions/index.tsx`
+
+**为什么做成通用组件**：操作项显隐 = 权限 × 数据状态、展示顺序 = 后台菜单 sort、折叠规则 = ≤3 平铺 />3 `...` 悬停展开——这些是所有列表页共通的展示逻辑，若每页手写（如早期 agent-factory 的 renderActions）必然重复且易写死。抽成组件后，页面只需声明「有哪些操作项」及其权限码/状态判定/回调，**展示规则由组件统一保证**。
+
+**Props**：
+
+```ts
+export interface TableActionItem<T = unknown> {
+  key: string;
+  label?: React.ReactNode;   // 按钮文案（显式传优先；否则取菜单按钮 name）
+  permission?: string;       // 权限码（菜单树 type=3 按钮 permission；不传=常显）
+  show?: boolean | ((record: T) => boolean); // 数据状态显隐
+  danger?: boolean;          // 危险操作（红色）
+  color?: string;            // 自定义文字颜色（如橙色警告操作；danger 优先）
+  icon?: React.ReactNode;
+  onClick?: (record: T) => void;
+}
+export interface TableActionsProps<T = unknown> {
+  record: T;
+  items: TableActionItem<T>[];
+  max?: number;              // 平铺上限，默认 3
+  sortByMenu?: boolean;      // 是否按当前菜单按钮 sort 排序，默认 true
+}
+export const ACTION_COL_WIDTH = 150; // 操作栏列宽
+```
+
+**机制**：
+
+1. **过滤**：`permission` 非空且未授权 → 隐藏；`show` 为函数时以 `record` 计算，为 `false` 隐藏
+2. **排序**：`sortByMenu`（默认开）从 `useAuthStore.menus` 取当前路由（`useLocation().pathname` 最长前缀匹配）对应菜单节点的 `type===3` 按钮子节点，按 `sort` 升序得到权限顺序，`items` 按 `permission ?? key` 对齐重排；**菜单树未匹配或无按钮节点时退化为 items 传入顺序**（不报错）
+3. **折叠**：过滤排序后 ≤ `max`（默认 3）平铺；> `max` 前 `max` 个平铺，其余进 `Dropdown trigger={['hover']}`（`...` 悬停展开）
+4. **样式**：`<a>` 链接形式，`danger` 红色（`#ff4d4f`）、`color` 自定义色（danger 优先）
+
+**接入示例**（见 §1.1 模板 `buildActionItems`）：页面定义操作项数组（permission + show + onClick），操作列渲染 `<TableActions record={record} items={buildActionItems(record)} />` 即可。
+
+**注意事项**：
+
+- 排序依赖**后台菜单管理已配置按钮节点及 sort**（系统管理 → 菜单管理，type=按钮）；未配置时按 items 传入顺序展示，不影响功能
+- 操作列宽度默认 `ACTION_COL_WIDTH`（150）；操作项文字较多导致换行时，页面可自定义加宽（如 180），不必拘泥默认值
+- 操作项的「数据状态判定」在页面内实现（如 `getAgentRowActions(record)`），组件不感知业务
+- 危险操作（删除/驳回/废弃等）传 `danger: true`，无需再手动加色
+- 批量操作（toolBarRender 的新增/批量删除）不属于行操作项，不走 TableActions
+
+---

package/references/ant6-front-standard/04-/350/241/250/345/215/225/350/247/204/350/214/203.md

@@ -13,6 +13,13 @@
 
 2、表单较复杂（字段 ≥ 4 个）或业务流程需要连续操作时，推荐使用右侧 Drawer 替代 Modal。
 
+3、在使用drawer抽屉后的表单有需要弹窗选择的弹窗，推荐使用 Modal
+
+4、使用抽屉drawer组件时，必须使用 `closable={{ placement: 'end' }}`和`mask={{ closable: false }}`,其宽度必须使用`size`不能使用`width`
+
+5、使用抽屉drawer组件时，内容区块必须使用<Card></Card>组建包裹
+
+
 > 根据表单字段数量分级选择布局和 Drawer 宽度。
 
 | 字段数量   | 布局                           | Drawer 宽度 | Form layout  | 说明                       |
@@ -307,6 +314,7 @@ const XxxDrawer: React.FC<Props> = ({ open, id, onSuccess, onClose }) => {
 - `originData = useRef()` 保留服务端字段，提交时合并：`{ ...originData.current, ...values, id }`
 - 编辑模式下隐藏字段用 `hidden={!!id}` 而非条件渲染（条件渲染会让 `validateFields` 跳过该字段）
 - 用  `destroyOnHidden` 自动清理状态，**不要**手动 reset
+- Drawer 宽度必须使用`size`不能使用`width`
 
 ---
 

package/references/ant6-front-standard/09-/345/270/270/350/247/201/351/227/256/351/242/230/350/247/204/350/214/203.md

@@ -1,7 +1,7 @@
 # 常见问题规范（必读陷阱）
 
 > 适用范围: React 19 + TypeScript 6 + Ant Design 6 + ProComponents
-> 版本: v3.3
+> 版本: v3.4
 
 ---
 

package/references/ant6-front-standard/index.md

@@ -1,100 +1,101 @@
-# 前端编码规范索引
-
-> **适用范围**: React 19 + TypeScript 6 + Ant Design 6 + ProComponents
-> **版本**: v3.3
-
----
-
-本目录包含 `front-demo`和`web-ui` 两个前端项目的前端开发规则。生成或修改代码前，先按任务类型读取对应规则。
-
-## 文件清单
-
-| 序号 | 文件名                                             | 主要内容                                                                                 |
-| ---- | -------------------------------------------------- | ---------------------------------------------------------------------------------------- |
-| 01   | [01-基础规范.md](./01-基础规范.md)                 | 一 ~  技术栈基线、目录结构、命名、编码风格、TypeScript、样式、Vue→React 迁移映射表、总结 |
-| 02   | [02-组件规范.md](./02-组件规范.md)                 | React 组件规范（函数组件 / Props / Hook）、上传组件、时间格式化                          |
-| 03   | [03-列表规范.md](./03-列表规范.md)                 | ProTable 列表页标准模式（标准模板、列定义规则）                                          |
-| 04   | [04-表单规范.md](./04-表单规范.md)                 | Modal / Drawer 使用标准规范（布局分级、标准模板、一栏~四栏布局）                         |
-| 05   | [05-路由状态接口规范.md](./05-路由状态接口规范.md) | 路由（动态路由 / 守卫）、Zustand 状态管理、API 接口规范                                  |
-| 06   | [06-国际化规范.md](./06-国际化规范.md)             | react-i18next 多语言支持（命名空间、语言包结构、切换）                                   |
-| 07   | [07-字典权限规范.md](./07-字典权限规范.md)         | 字典系统（DictTag / getDictOptions）、权限系统（Access / useAccess）                     |
-| 08   | [08-性能质量规范.md](./08-性能质量规范.md)         | 性能优化（lazy / memo / useMemo）、代码质量标准（复杂度 / ESLint / 构建）                |
-| 09   | [09-常见问题规范.md](./09-常见问题规范.md)         | 项目实际踩坑与解决方案（16 条必读陷阱）                                                  |
-
----
-
-## 按场景推荐阅读
-
-### 新增普通业务页面
-
-1. `01-基础规范.md` — 熟悉技术栈与目录约定
-2. `05-路由状态接口规范.md` — 路由、状态、接口规范
-3. `03-列表规范.md` — ProTable 列表页模板
-4. `04-表单规范.md` — Modal / Drawer 表单模板
-5. `07-字典权限规范.md` — 字典渲染与按钮权限
-
-### 新增列表页
-
-1. `03-列表规范.md` — ProTable 标准模板与列规则
-2. `07-字典权限规范.md` — 字典下拉 + 权限按钮
-3. `02-组件规范.md` — 时间格式化与上传组件
-
-### 新增表单 / 流程页面
-
-1. `04-表单规范.md` — Modal / Drawer 布局分级与标准模板
-2. `05-路由状态接口规范.md` — API 接口规范
-3. `09-常见问题规范.md` — 必读陷阱（validateFields、Upload、Tree 等）
-
-### 国际化 / 字典 / 权限模块
-
-1. `06-国际化规范.md` — i18n 命名空间、语言包结构
-2. `07-字典权限规范.md` — 字典与权限系统
-
-### 代码评审 / 质量检查
-
-1. `08-性能质量规范.md` — 性能与质量标准
-2. `09-常见问题规范.md` — 16 条踩坑清单
-3. `01-基础规范.md` — 命名 / 编码风格 / TypeScript 规范
-
-### 从 Vue 迁移到 React
-
-1. `01-基础规范.md` — 熟悉技术栈与目录约定
-2. `vue迁移到react规范.md` —  Vue → React 迁移映射表
-3. `09-常见问题规范.md` — 常见差异点
-
----
-
-
-## 维护说明
-
-- 拆分后的各文件章节号已独立重编号，每份均从「一」开始，便于独立阅读。
-- 更新规范时，请同步修改对应拆分文件及本索引。
-
-## 总结
-
-本规范文档涵盖了 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>` 零错误
-- [ ] 关键逻辑加中文注释，复杂分支说明「为什么这么写」
-
----
-
-**文档结束**
-
+# 前端编码规范索引
+
+> **适用范围**: React 19 + TypeScript 6 + Ant Design 6 + ProComponents
+> **版本**: v3.3
+
+---
+
+本目录包含 `front-demo`和`web-ui` 两个前端项目的前端开发规则。生成或修改代码前，先按任务类型读取对应规则。
+
+## 文件清单
+
+| 序号 | 文件名                                             | 主要内容                                                                                 |
+| ---- | -------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| 01   | [01-基础规范.md](./01-基础规范.md)                 | 一 ~  技术栈基线、目录结构、命名、编码风格、TypeScript、样式、Vue→React 迁移映射表、总结 |
+| 02   | [02-组件规范.md](./02-组件规范.md)                 | React 组件规范（函数组件 / Props / Hook）、上传组件、时间格式化                          |
+| 03   | [03-列表规范.md](./03-列表规范.md)                 | ProTable 列表页标准模式（标准模板、列定义规则）                                          |
+| 04   | [04-表单规范.md](./04-表单规范.md)                 | Modal / Drawer 使用标准规范（布局分级、标准模板、一栏~四栏布局）                         |
+| 05   | [05-路由状态接口规范.md](./05-路由状态接口规范.md) | 路由（动态路由 / 守卫）、Zustand 状态管理、API 接口规范                                  |
+| 06   | [06-国际化规范.md](./06-国际化规范.md)             | react-i18next 多语言支持（命名空间、语言包结构、切换）                                   |
+| 07   | [07-字典权限规范.md](./07-字典权限规范.md)         | 字典系统（DictTag / getDictOptions）、权限系统（Access / useAccess）                     |
+| 08   | [08-性能质量规范.md](./08-性能质量规范.md)         | 性能优化（lazy / memo / useMemo）、代码质量标准（复杂度 / ESLint / 构建）                |
+| 09   | [09-常见问题规范.md](./09-常见问题规范.md)         | 项目实际踩坑与解决方案（16 条必读陷阱）                                                  |
+
+---
+
+## 按场景推荐阅读
+
+### 新增普通业务页面
+
+1. `01-基础规范.md` — 熟悉技术栈与目录约定
+2. `05-路由状态接口规范.md` — 路由、状态、接口规范
+3. `03-列表规范.md` — ProTable 列表页模板
+4. `04-表单规范.md` — Modal / Drawer 表单模板
+5. `07-字典权限规范.md` — 字典渲染与按钮权限
+
+### 新增列表页
+
+1. `03-列表规范.md` — ProTable 标准模板与列规则
+2. `07-字典权限规范.md` — 字典下拉 + 权限按钮
+3. `02-组件规范.md` — 时间格式化与上传组件
+
+### 新增表单 / 流程页面
+
+1. `04-表单规范.md` — Modal / Drawer 布局分级与标准模板
+2. `05-路由状态接口规范.md` — API 接口规范
+3. `09-常见问题规范.md` — 必读陷阱（validateFields、Upload、Tree 等）
+
+### 国际化 / 字典 / 权限模块
+
+1. `06-国际化规范.md` — i18n 命名空间、语言包结构
+2. `07-字典权限规范.md` — 字典与权限系统
+
+### 代码评审 / 质量检查
+
+1. `08-性能质量规范.md` — 性能与质量标准
+2. `09-常见问题规范.md` — 16 条踩坑清单
+3. `01-基础规范.md` — 命名 / 编码风格 / TypeScript 规范
+
+### 从 Vue 迁移到 React
+
+1. `01-基础规范.md` — 熟悉技术栈与目录约定
+2. `vue迁移到react规范.md` —  Vue → React 迁移映射表
+3. `09-常见问题规范.md` — 常见差异点
+
+---
+
+
+## 维护说明
+
+- 拆分后的各文件章节号已独立重编号，每份均从「一」开始，便于独立阅读。
+- 更新规范时，请同步修改对应拆分文件及本索引。
+
+## 总结
+
+本规范文档涵盖了 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>` 零错误
+- [ ] 关键逻辑加中文注释，复杂分支说明「为什么这么写」
+- [ ] 是否符合09-常见问题规范.md
+
+---
+
+**文档结束**
+
 *本文档作为前端开发的标准规范，所有开发人员必须严格遵守。*