adspecs 0.1.33 → 0.1.34

package/.adspecs/paths.json

@@ -8,7 +8,7 @@
     "sow_dir": "docs/05-sow",
     "prd_dir": "docs/20-prd",
     "design_dir": "docs/30-system-design",
-    "test_report_dir": "docs/80-development",
+    "test_report_dir": "docs/80-development/802-test",
     "export_dir": "docs/90-export",
     "front_demo_dir": "front-demo",
     "front_prototype_dir": "web-ui",

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
     {
       "name": "adspecs",
       "description": "AI Coding研发协同开发插件",
-      "version": "0.1.33",
+      "version": "0.1.34",
       "source": "./",
       "author": {
         "name": "Qingwen Chen",

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "adspecs",
   "displayName": "adspecs AI Plugin",
   "description": "AI first工程规范驱动开发插件",
-  "version": "0.1.33",
+  "version": "0.1.34",
   "author": {
     "name": "Qingwen Chen",
     "email": "cqinwn@qq.com",

package/.codebuddy-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "adspecs",
   "displayName": "adspecs AI 工程规范驱动开发插件",
-  "version": "0.1.33",
+  "version": "0.1.34",
   "description": "AI-first specification-driven development plugin for ECP platform full-lifecycle development",
   "descriptionZh": "AI优先的工程规范驱动开发插件，覆盖需求分析、PRD、系统设计、任务拆解、TDD、代码评审、Wiki同步全流程",
   "author": {

package/.qoder-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "adspecs",
   "displayName": "adspecs AI 工程规范驱动开发插件",
-  "version": "0.1.33",
+  "version": "0.1.34",
   "description": "AI-first specification-driven development plugin for ECP platform full-lifecycle development",
   "descriptionZh": "AI优先的工程规范驱动开发插件，覆盖需求分析、PRD、系统设计、任务拆解、TDD、代码评审、Wiki同步全流程",
   "author": {

package/.workbuddy-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "adspecs",
   "displayName": "adspecs AI 工程规范驱动开发插件",
-  "version": "0.1.33",
+  "version": "0.1.34",
   "description": "AI-first specification-driven development plugin for ECP platform full-lifecycle development",
   "descriptionZh": "AI优先的工程规范驱动开发插件，覆盖需求分析、PRD、系统设计、任务拆解、TDD、代码评审、Wiki同步全流程",
   "author": {

package/CLAUDE.md

@@ -138,7 +138,7 @@ Skills support configurable output directories via `.adspecs/paths.json` in the
     "sow_dir": "docs/05-sow",
     "prd_dir": "docs/20-prd",
     "design_dir": "docs/30-system-design",
-    "test_report_dir": "docs/80-development",
+    "test_report_dir": "docs/80-development/802-test",
     "session_log_dir": "docs/80-development/800-log",
     "export_dir": "docs/90-export",
     "wiki_dir": "wiki"
@@ -156,7 +156,7 @@ Skills support configurable output directories via `.adspecs/paths.json` in the
 | `sow_dir`             | `docs/05-sow`                   | adspecs-write-sow                                                                                                                   |
 | `prd_dir`             | `docs/20-prd`                   | adspecs-prd, adspecs-plan (input), adspecs-front-spec (input), wiki-update (source)                                                 |
 | `design_dir`          | `docs/30-system-design`         | adspecs-plan (output), adspecs-tasks, adspecs-front-spec (output), adspecs-front-tasks, adspecs-utest (input), wiki-update (source) |
-| `test_report_dir`     | `docs/80-development`           | adspecs-utest (test reports)                                                                                                        |
+| `test_report_dir`     | `docs/80-development/802-test`      | adspecs-utest (unit test reports, saved by module subdirectory)                                                                     |
 | `session_log_dir`     | `docs/80-development/800-log`   | session-logger (AI session logs, triggered by keyword / PreCompact / session end)                                                    |
 | `export_dir`          | `docs/90-export`                | adspecs-export-word (Word 导出输出)                                                                                                 |
 | `wiki_dir`            | `wiki`                          | wiki-update (output target)                                                                                                         |

package/README.md

@@ -391,7 +391,7 @@ Skill 支持通过 `.adspecs/paths.json` 自定义输出目录：
     "sow_dir": "docs/05-sow",
     "prd_dir": "docs/20-prd",
     "design_dir": "docs/30-system-design",
-    "test_report_dir": "docs/80-development",
+    "test_report_dir": "docs/80-development/802-test",
     "export_dir": "docs/90-export",
     "front_demo_dir": "front-demo",
     "front_prototype_dir": "web-ui",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adspecs",
-  "version": "0.1.33",
+  "version": "0.1.34",
   "description": "AI first 工程规范驱动开发插件 — 支持 npm 安装和 CLI 初始化",
   "bin": {
     "adspecs": "bin/adspecs.js"

package/references/ant6-front-standard/02-/347/273/204/344/273/266/350/247/204/350/214/203.md

@@ -187,3 +187,10 @@ render: (_, record) => dateFormatter(record.createTime) || '-',
 > **注意**：如果后端 `createTime` 可能是 number/Date，统一用 `new Date(value).getTime()` 包装再比较。
 
 ---
+
+## 4、<Alert />组件使用规范
+
+- Ant Design 6 中 `Alert` 的 `message` 属性已弃用，控制台报 `[antd: Alert] message is deprecated. Please use title instead.`
+- **严禁**写 `<Alert message="..." />`，**必须**改为 `<Alert title="..." />`
+- 全仓库排查命令：`grep -rn "Alert" web-ui/src --include="*.tsx" | grep "message="`
+- 已清理范围：本体模块（detail 编辑锁提示条、BindingTab、GraphTab、CleanupModal、VersionDiffDrawer、YamlTab 等）——新增代码必须遵守，勿让该警告回潮

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
 
 ---