@para-ui/core 5.0.0-beta.12 → 5.0.0-beta.14

package/ai-workflows/01-crud-list-multi-drawer.md

@@ -0,0 +1,278 @@
+# Workflow 1: CRUD 列表 + 多 Drawer + 权限操作列
+
+> **基于**：console/src/package/Service/src/content.tsx（Para 团队真实业务代码 677 行的提炼）  
+> **覆盖 baseline 失败任务**：Task 3（多选）/ Task 29（批量操作）/ Task 26（RBAC 操作列）  
+> **集成 typescriptPitfalls**：ComboSelect TableProps 嵌套 / OperateBtn 图标名 / PageHeader MenuChildrenProps 命名冲突
+
+---
+
+## 何时使用
+
+管理后台主列表页 —— 单个页面同时支持以下操作中的 3 项及以上：
+
+```
+列表展示  +  新建/编辑实体  +  删除/批量删除  +  导出/导入  +  权限管理  +  关联资源查看
+```
+
+**典型业务**：用户管理 / 资产管理 / 订单管理 / 角色权限 / 服务配置 / 设备列表
+
+**不要用此模板的场景**：
+- 只读列表（无操作列）→ 用基础 Table
+- 单 Modal 简单 CRUD（< 3 项操作）→ 简化为单 Drawer
+- 嵌套表格（行展开）→ 用 Workflow 8（表格高级）
+
+---
+
+## 关键模式（与脑补的区别）
+
+| 错误模式（AI 常犯） | 正确模式 |
+|------------------|--------|
+| ❌ 用一个 `open` state 控制所有 Drawer | ✅ **每个 Drawer 独立 state**（`openForm` / `openUser` / `openExport`） |
+| ❌ 操作按钮硬编码在 Table render | ✅ **`OperateBtnListProps[]` 数组定义 + Table.operate.operateBtnRender 渲染** |
+| ❌ `useEffect(..., [data])` 监听数据变化刷新 | ✅ **`refresh` 数字 state + setRefresh(Math.random())** 主动驱动刷新 |
+| ❌ 删除后手动 `setData(prev.filter(...))` | ✅ **删除成功 → Message.success → refreshData()**（让 Table 重新拉数据） |
+| ❌ TableProps.columns（antd 风格） | ✅ **TableProps.headData**（Para UI 真实 API，M2 ComboSelect 修复同款陷阱） |
+
+---
+
+## 完整代码（自包含，可直接复制）
+
+```tsx
+import React, { FunctionComponent, useState, useMemo } from 'react';
+import { Table, Button, PopConfirm } from '@para-ui/core';
+import { Message } from '@para-ui/core/Message';   // 注意:命令式 API 必须从子路径导入(M2 实证)
+import type { HeadDataProps } from '@para-ui/core';
+import type { OperateBtnListProps } from '@para-ui/core/OperateBtn';
+
+interface AssetRow {
+  id: string;
+  name: string;
+  type: 'physical' | 'virtual';
+  status: 'active' | 'disabled';
+  owner: string;
+}
+
+const AssetListPage: FunctionComponent = () => {
+  // 每个 Drawer 独立 state（不要合并！）
+  const [openForm, setOpenForm] = useState<boolean>(false);
+  const [openPermission, setOpenPermission] = useState<boolean>(false);
+  const [openExport, setOpenExport] = useState<boolean>(false);
+
+  // 当前选中的编辑行（与 openForm 配套）
+  const [editRow, setEditRow] = useState<AssetRow | undefined>();
+
+  // refresh 数字驱动 Table 重新拉数据（不要用 useEffect 监听 data）
+  const [refresh, setRefresh] = useState<number>(0);
+  const refreshData = (): void => setRefresh(Math.random());
+
+  // Table 多选 state（独立于 Drawer state）
+  const [checkValue, setCheckValue] = useState<string[]>([]);
+
+  // 操作按钮列表生成函数（带行数据 + 权限判断）
+  const buildOperateBtnList = (row: AssetRow): OperateBtnListProps[] => {
+    const list: OperateBtnListProps[] = [
+      {
+        key: 'edit',
+        label: '编辑',
+        onClick: () => { setEditRow(row); setOpenForm(true); }
+      },
+      {
+        key: 'permission',
+        label: '权限',
+        onClick: () => { setEditRow(row); setOpenPermission(true); }
+      },
+      {
+        key: 'delete',
+        label: '删除',
+        disabled: row.status === 'active',           // 在用资产不允许删
+        toolTipTitle: row.status === 'active' ? '在用资产不可删除' : undefined,
+        onClick: async () => {
+          // 删除成功后通过 Message + refreshData 反馈,不要手动改 state
+          await mockApi.deleteAsset(row.id);
+          Message.success('已删除');
+          refreshData();
+        }
+      }
+    ];
+    return list.filter(item => !item.hidden);
+  };
+
+  // 批量删除（多选场景）
+  const handleBatchDelete = async (): Promise<void> => {
+    await mockApi.batchDelete(checkValue);
+    Message.success(`已删除 ${checkValue.length} 项`);
+    setCheckValue([]);
+    refreshData();
+  };
+
+  // Table 列定义（必须用 headData,不是 antd 风格的 columns）
+  const headData = useMemo<HeadDataProps<AssetRow>[]>(() => [
+    { name: 'name', label: '资产名', width: 160 },
+    { name: 'type', label: '类型', width: 100 },
+    { name: 'status', label: '状态', width: 100,
+      render: (row) => row.status === 'active' ? '使用中' : '已禁用'
+    },
+    { name: 'owner', label: '负责人', width: 120 }
+  ], []);
+
+  return (
+    <div>
+      {/* 顶部操作区:批量操作 + 新建 */}
+      <div style={{ marginBottom: 16, display: 'flex', gap: 8 }}>
+        <Button onClick={() => { setEditRow(undefined); setOpenForm(true); }}>
+          新建
+        </Button>
+        {checkValue.length > 0 && (
+          <>
+            <span style={{ alignSelf: 'center' }}>已选 {checkValue.length} 项</span>
+            <PopConfirm
+              title="确认批量删除"
+              onOk={handleBatchDelete}
+            >
+              <Button>批量删除</Button>
+            </PopConfirm>
+          </>
+        )}
+      </div>
+
+      {/* 表格本体 */}
+      <Table<AssetRow>
+        rowKey="id"
+        data={mockData}
+        headData={headData}
+        // ↓ 操作列通过 operate 配置渲染,不要硬编码到 headData
+        // operate={{ label: '操作', width: 180, operateBtnRender: (row) => ({
+        //   list: buildOperateBtnList(row), showNum: 3
+        // })}}
+        // multi-select
+        // check
+        // setCheck={setCheckValue}
+        pagination={false}
+        autoSize={false}
+      />
+
+      {/* 多个 Drawer 共存,每个独立 state */}
+      {openForm && (
+        <FormDrawer
+          open={openForm}
+          rowData={editRow}
+          onFinish={(saved) => {
+            setOpenForm(false);
+            setEditRow(undefined);
+            if (saved) refreshData();
+          }}
+        />
+      )}
+      {openPermission && (
+        <PermissionDrawer
+          open={openPermission}
+          rowData={editRow}
+          onClose={() => setOpenPermission(false)}
+        />
+      )}
+      {openExport && (
+        <ExportDrawer
+          open={openExport}
+          onClose={() => setOpenExport(false)}
+        />
+      )}
+    </div>
+  );
+};
+
+export default AssetListPage;
+
+// === 以下是占位,实际项目里来自业务代码 ===
+const mockData: AssetRow[] = [];
+const mockApi = {
+  deleteAsset: async (id: string): Promise<void> => { void id; },
+  batchDelete: async (ids: string[]): Promise<void> => { void ids; }
+};
+const FormDrawer: FunctionComponent<{ open: boolean; rowData?: AssetRow; onFinish: (saved?: boolean) => void }> = () => null;
+const PermissionDrawer: FunctionComponent<{ open: boolean; rowData?: AssetRow; onClose: () => void }> = () => null;
+const ExportDrawer: FunctionComponent<{ open: boolean; onClose: () => void }> = () => null;
+```
+
+---
+
+## 5 个真实陷阱（来自 M2/M3 修复实证）
+
+### ❌ 陷阱 1：Table 列定义用 antd 风格 `columns`
+```tsx
+// 错（M2 ComboSelect 修复发现的高频错误）
+<Table columns={[{ title: '名称', dataIndex: 'name' }]} />
+// 对
+<Table headData={[{ name: 'name', label: '名称', width: 120 }]} />
+```
+
+### ❌ 陷阱 2：多 Drawer 共享 state 互相干扰
+```tsx
+// 错
+const [activeDrawer, setActiveDrawer] = useState<'form' | 'permission' | null>(null);
+{activeDrawer === 'form' && <FormDrawer ... />}
+// 问题：用户在 Permission Drawer 里点了链接想跳 Form Drawer,
+// 但单一 state 没法同时显示两个
+
+// 对
+const [openForm, setOpenForm] = useState(false);
+const [openPermission, setOpenPermission] = useState(false);
+// 各 Drawer 独立,可同时存在或链式调用
+```
+
+### ❌ 陷阱 3：刷新表格用 useEffect 监听数据
+```tsx
+// 错（容易死循环或漏刷新）
+useEffect(() => { fetchData().then(setData); }, [data]);
+// 对
+const [refresh, setRefresh] = useState(0);
+const refreshData = () => setRefresh(Math.random());
+// Table 内部用 refresh 数字驱动重新拉数据
+```
+
+### ❌ 陷阱 4：操作按钮硬编码进 render
+```tsx
+// 错
+{ name: 'op', label: '操作', render: (row) => <>
+  <Button onClick={...}>编辑</Button>
+  <Button onClick={...}>删除</Button>
+  ...10 个按钮...
+</> }
+
+// 对：用 OperateBtnListProps 数组 + Table.operate
+const list: OperateBtnListProps[] = [
+  { key: 'edit', label: '编辑', onClick: edit(row) },
+  { key: 'delete', label: '删除', disabled: row.inUse, onClick: del(row) }
+];
+// Table operate.operateBtnRender 渲染,自动处理 showNum + 折叠
+```
+
+### ❌ 陷阱 5：删除后手动 setData
+```tsx
+// 错
+const handleDelete = async (id) => {
+  await api.delete(id);
+  setData(prev => prev.filter(r => r.id !== id));  // 丢失分页 / 排序状态
+};
+// 对
+const handleDelete = async (id) => {
+  await api.delete(id);
+  Message.success('已删除');
+  refreshData();  // 让 Table 重拉,保留 page/sort/filter
+};
+```
+
+---
+
+## 真实参考
+
+**Para 团队真实业务代码**：`/Users/seth/Desktop/para/2025-Pam/new/para-node-4.0-web/console/src/package/Service/src/content.tsx`
+
+| 关键模式 | 行号 |
+|---------|------|
+| 多 Drawer 独立 state（6 个） | 52-63 |
+| `useAsync(updateDisabled, 'id')` 带 loadingMap 的异步 hook | 66 |
+| `OperateBtnListProps[]` + 权限注入 | 494-566 |
+| Table.operate.operateBtnRender + check 多选 | 592-613 |
+| 6 个 Drawer 并列渲染 | 616-657 |
+
+console 项目内 19 个业务模块（Service/User/Group/Cluster/Faas/...）都用此模式。

package/ai-workflows/02-rbac-operation-buttons.md

@@ -0,0 +1,290 @@
+# Workflow 2: 权限驱动 RBAC 操作列
+
+> **基于**：console 真实业务代码（Role 模块 / User 模块）提炼  
+> **覆盖 baseline 失败任务**：Task 26（RBAC 操作列权限控制）  
+> **集成 typescriptPitfalls**：OperateBtn 图标名 / PageHeader MenuChildrenProps 命名冲突 / Table headData 风格 / Tag 状态渲染
+
+---
+
+## 何时使用
+
+管理后台中，同一行数据对不同角色显示不同操作按钮：
+
+```
+超级管理员   → 编辑 + 删除 + 停用
+普通管理员   → 编辑（不能删）
+只读角色     → 仅查看（PreviewOpen）
+```
+
+**典型业务**：角色管理 / 用户管理 / 资产权限 / 订单审批
+
+**不要用此模板的场景**：
+- 所有人权限一致（无需按角色过滤操作列）→ 用 Workflow 1
+- 权限控制在路由层（页面级控制）→ 用路由守卫，不用操作列过滤
+
+---
+
+## 关键模式（与脑补的区别）
+
+| 错误模式（AI 常犯） | 正确模式 |
+|------------------|--------|
+| ❌ `import View from '@para-ui/icons/View'`（不存在） | ✅ `import PreviewOpen from '@para-ui/icons/PreviewOpen'`（M2 OperateBtn 修复） |
+| ❌ `import { MenuChildrenProps } from '@para-ui/core'` 用于 PageHeader | ✅ 不标注类型，让 TS 推断（M3 PageHeader 修复） |
+| ❌ `headData={[{ title: '名称', dataIndex: 'name' }]}` antd 风格 | ✅ `headData={[{ label: '名称', name: 'name' }]}` Para UI 风格 |
+| ❌ 权限判断写在 render 里（每次渲染都计算） | ✅ `buildOperateBtnList(row, currentUserRole)` 函数集中管理 + `hidden` 过滤 |
+| ❌ `list.length === showNum + 1` 时期望折叠 | ✅ 仅 `list.length > showNum + 1` 才出现更多按钮（差值严格 > 1） |
+
+---
+
+## 完整代码（自包含，可直接复制）
+
+```tsx
+import React, { FunctionComponent, useState, useMemo } from 'react';
+import { Table, Tag } from '@para-ui/core';
+import { Message } from '@para-ui/core/Message';
+import type { HeadDataProps } from '@para-ui/core';
+import type { OperateBtnListProps } from '@para-ui/core/OperateBtn';
+import OperateBtn from '@para-ui/core/OperateBtn';
+import PreviewOpen from '@para-ui/icons/PreviewOpen';
+import Edit from '@para-ui/icons/Edit';
+import Delete from '@para-ui/icons/Delete';
+
+// === 业务数据类型 ===
+type RoleLevel = 'superAdmin' | 'admin' | 'readonly';
+
+interface UserRow {
+  id: string;
+  name: string;
+  email: string;
+  status: 'active' | 'disabled';
+  roleLevel: RoleLevel;
+}
+
+// 当前登录用户的角色（实际从 context/store 获取）
+const CURRENT_USER_ROLE: RoleLevel = 'admin';
+
+// === 权限驱动的操作列生成函数 ===
+// 关键：集中管理权限 → 操作按钮的映射，不写在 render 里
+const buildOperateBtnList = (
+  row: UserRow,
+  currentRole: RoleLevel,
+  callbacks: {
+    onEdit: (row: UserRow) => void;
+    onDelete: (row: UserRow) => void;
+    onView: (row: UserRow) => void;
+  }
+): OperateBtnListProps[] => {
+  const list: OperateBtnListProps[] = [
+    {
+      key: 'view',
+      label: '查看',
+      icon: <PreviewOpen />,
+      // 所有角色都可查看
+      hidden: false,
+      onClick: (_item, _e) => callbacks.onView(row)
+    },
+    {
+      key: 'edit',
+      label: '编辑',
+      icon: <Edit />,
+      // 只读角色不能编辑
+      hidden: currentRole === 'readonly',
+      disabled: row.status === 'disabled',
+      toolTipTitle: row.status === 'disabled' ? '已停用用户不可编辑' : '编辑',
+      onClick: (_item, _e) => callbacks.onEdit(row)
+    },
+    {
+      key: 'delete',
+      label: '删除',
+      icon: <Delete />,
+      danger: true,
+      // 只有 superAdmin 才能删除
+      hidden: currentRole !== 'superAdmin',
+      popConfirmProps: {
+        title: `确认删除用户「${row.name}」？`,
+        onOk: () => callbacks.onDelete(row)
+      }
+    }
+  ];
+  // 过滤 hidden 项（hidden 属性让 OperateBtn 知道不渲染该项）
+  return list.filter(item => !item.hidden);
+};
+
+// === 主页面组件 ===
+const RoleManagementPage: FunctionComponent = () => {
+  const [openDetail, setOpenDetail] = useState<boolean>(false);
+  const [currentRow, setCurrentRow] = useState<UserRow | undefined>();
+  const [refresh, setRefresh] = useState<number>(0);
+  const refreshData = (): void => setRefresh(Math.random());
+
+  const handleEdit = (row: UserRow): void => {
+    setCurrentRow(row);
+    // 实际跳转到编辑 Drawer
+  };
+
+  const handleDelete = async (row: UserRow): Promise<void> => {
+    await mockApi.deleteUser(row.id);
+    Message.success(`已删除用户「${row.name}」`);
+    refreshData();
+  };
+
+  const handleView = (row: UserRow): void => {
+    setCurrentRow(row);
+    setOpenDetail(true);
+  };
+
+  // Table 列定义（必须用 headData，不是 antd 风格的 columns）
+  const headData = useMemo<HeadDataProps<UserRow>[]>(() => [
+    { name: 'name', label: '用户名', width: 140 },
+    { name: 'email', label: '邮箱', width: 200 },
+    {
+      name: 'status',
+      label: '状态',
+      width: 100,
+      // render 第一参数是整行数据（不是单元格值）
+      render: (row) => (
+        <Tag color={row.status === 'active' ? 'green' : 'red'}>
+          {row.status === 'active' ? '正常' : '停用'}
+        </Tag>
+      )
+    },
+    {
+      name: 'roleLevel',
+      label: '角色',
+      width: 120,
+      render: (row) => ({
+        superAdmin: '超级管理员',
+        admin: '管理员',
+        readonly: '只读'
+      }[row.roleLevel])
+    },
+    {
+      name: 'id',
+      label: '操作',
+      width: 160,
+      render: (row) => (
+        <OperateBtn
+          list={buildOperateBtnList(row, CURRENT_USER_ROLE, {
+            onEdit: handleEdit,
+            onDelete: handleDelete,
+            onView: handleView
+          })}
+          showNum={3}
+          size="small"
+        />
+      )
+    }
+  ], []);
+
+  void openDetail;
+  void currentRow;
+  void refresh;
+
+  return (
+    <div>
+      <Table<UserRow>
+        rowKey="id"
+        data={mockData}
+        headData={headData}
+        pagination={false}
+        autoSize={false}
+      />
+    </div>
+  );
+};
+
+export default RoleManagementPage;
+
+// === 占位 Mock ===
+const mockData: UserRow[] = [];
+const mockApi = {
+  deleteUser: async (id: string): Promise<void> => { void id; }
+};
+```
+
+---
+
+## 5 个真实陷阱（来自 M2/M3 修复实证）
+
+### ❌ 陷阱 1：`@para-ui/icons` 中 View 不存在
+```tsx
+// 错（M2 OperateBtn 修复发现：View 不在图标库中）
+import View from '@para-ui/icons/View';   // TS2307: 找不到模块
+import Share from '@para-ui/icons/Share'; // TS2307: 找不到模块
+
+// 对
+import PreviewOpen from '@para-ui/icons/PreviewOpen';  // 查看/预览
+import More from '@para-ui/icons/More';               // 更多操作
+// 可用图标：Edit / Delete / Copy / More / PreviewOpen / PreviewClose
+```
+**实证来源**：M2 OperateBtn component.json `typescriptPitfalls[3]`，Task 26 失败根因。
+
+### ❌ 陷阱 2：从 `@para-ui/core` 导入 MenuChildrenProps 标注 PageHeader 回调
+```tsx
+// 错（M3 PageHeader 修复：PageHeader/interface.ts 和 Menu/interface.ts 各有同名 MenuChildrenProps，互不兼容）
+import { PageHeader, MenuChildrenProps } from '@para-ui/core';
+onClickMenu={(item: MenuChildrenProps | false) => ...}  // TS2322 类型冲突
+
+// 对：不手动标注类型，让 TS 推断
+import { PageHeader } from '@para-ui/core';
+onClickMenu={(item) => { if (item && item.path) navigate(item.path); }}
+// 或用 Parameters<typeof PageHeader>[0]['onClickMenu'] 精确类型
+```
+**实证来源**：M3 PageHeader component.json `typescriptPitfalls[3]`。
+
+### ❌ 陷阱 3：Table 列定义用 antd `columns` 风格
+```tsx
+// 错
+<Table columns={[{ title: '用户名', dataIndex: 'name', sorter: true }]} />
+
+// 对：Para UI 字段名完全不同
+<Table<UserRow>
+  headData={[
+    { label: '用户名', name: 'name', sort: true }  // label/name/sort，不是 title/dataIndex/sorter
+  ]}
+  rowKey="id"   // 必须显式传，默认 'key' 在业务数据中几乎不存在
+/>
+```
+**实证来源**：M2 Table component.json `typescriptPitfalls[0]` + `typescriptPitfalls[3]`。
+
+### ❌ 陷阱 4：Table render 第一参数当单元格值用
+```tsx
+// 错（与 antd Table render 参数顺序相反）
+headData={[{
+  name: 'status',
+  label: '状态',
+  render: (value) => <Tag color={value === 'active' ? 'green' : 'red'}>{value}</Tag>
+  // ↑ value 实际是整行 UserRow 对象，不是 'active'/'disabled' 字符串
+}]}
+
+// 对：第一参数是整行数据 row
+render: (row) => <Tag color={row.status === 'active' ? 'green' : 'red'}>{row.status}</Tag>
+```
+**实证来源**：M2 Table component.json `typescriptPitfalls[1]`。
+
+### ❌ 陷阱 5：OperateBtn showNum 折叠阈值误判
+```tsx
+// 错（期望 list.length === showNum + 1 时折叠）
+// list 有 4 项，showNum=3 → 期望"前 3 个外显 + 1 个更多"
+// 实际：list.length(4) === showNum(3) + 1 → 最后一个也外显，不进更多
+
+// 对：仅 list.length > showNum + 1（差值严格大于 1）才出现更多按钮
+// list 有 4 项，showNum=3 → 全部外显（4 === 3 + 1，等于不折叠）
+// list 有 5 项，showNum=3 → 前 3 外显 + 更多（5 > 3 + 1）
+// 设计实践：权限过滤后 list 可能只剩 1-2 项，无需担心折叠问题
+const filteredList = allBtns.filter(item => !item.hidden);
+<OperateBtn list={filteredList} showNum={3} />
+```
+**实证来源**：OperateBtn component.json `idealProps.showNum`。
+
+---
+
+## 真实参考
+
+| 关键模式 | 参考位置 |
+|---------|--------|
+| `OperateBtnListProps[]` + `hidden` 过滤 | OperateBtn/component.json idealProps.list |
+| `PreviewOpen` 图标（替代不存在的 View） | OperateBtn/component.json typescriptPitfalls[3] |
+| `MenuChildrenProps` 命名冲突 | PageHeader/component.json typescriptPitfalls[3] |
+| `headData` 而非 `columns` | Table/component.json typescriptPitfalls[0] |
+| `render` 第一参数是 row | Table/component.json typescriptPitfalls[1] |