@para-ui/core 5.0.0-beta.9 → 5.0.1

package/ai-workflows/05-popconfirm-async-message-queue.md

@@ -0,0 +1,333 @@
+# Workflow 5: PopConfirm 异步链 + Message 队列
+
+> **覆盖 baseline 失败任务**：Task 19（PopConfirm 受控模式）/ Task 20（onOk 异步）/ Task 23（Message duration 参数）/ Task 25（Message 子路径导入）
+> **集成 typescriptPitfalls**：Message 6 条（子路径导入 / duration 第二参 / 无 loading / 无 onClose / clear 可选链 / 无 JSX 用法）+ PopConfirm 4 条（onOk 无参 / 受控需 controllable / type 枚举 / countdown 单位）
+
+---
+
+## 何时使用
+
+单页面存在多个危险操作（删除 / 禁用 / 批量清除），每个操作需要：
+
+```
+用户点击按钮 → PopConfirm 二次确认 → 调用异步 API → Message 反馈结果
+```
+
+**典型业务**：用户管理删除 / 资产禁用启用 / 订单批量撤销 / 任务强制终止
+
+**不要用此模板的场景**：
+- 非危险操作（读操作、导出等）→ 直接操作即可，无需二次确认
+- 需要填写额外信息再确认 → 换 Modal + Form
+- 复杂条件判断后才能删除 → 先请求状态接口，再打开 PopConfirm
+
+---
+
+## 关键模式（与脑补的区别）
+
+| 错误模式（AI 常犯） | 正确模式 |
+|------------------|--------|
+| ❌ `import { Message } from '@para-ui/core'` | ✅ **`import { Message } from '@para-ui/core/Message'`**（子路径！直接从 core 导入拿到的是 JSX 组件，无 success/error 方法） |
+| ❌ `Message.success({ text: '已删除', duration: 3000 })` | ✅ **`Message.success({ text: '已删除' }, 3000)`**（duration 是独立第 2 参数，不是 MsgTypeProps 字段） |
+| ❌ `Message.loading('处理中...')` | ✅ **`Message.info({ text: '处理中...', close: false }, 0)`**（Message 无 loading 方法，用 info + duration=0 模拟） |
+| ❌ `onOk={async (e) => doDelete(e)}` | ✅ **`onOk={() => doDelete(id)}`**（onOk 签名 `() => void`，无参数，id 从闭包获取） |
+| ❌ `<PopConfirm open={isOpen} onClose={...} />` | ✅ **`<PopConfirm open={isOpen} controllable={true} onClose={...} />`**（受控必须同时传 `controllable={true}`） |
+| ❌ `<PopConfirm type='danger' />` | ✅ **`<PopConfirm type='error' okButtonDanger={true} />`**（type 枚举无 'danger'；危险操作用 type='error' + okButtonDanger） |
+
+---
+
+## 完整代码（自包含，可直接复制）
+
+```tsx
+import React, { FunctionComponent, useState } from 'react';
+import { Button, PopConfirm, Switch } from '@para-ui/core';
+import { Message } from '@para-ui/core/Message';   // ⚠️ 必须子路径导入！从 @para-ui/core 导入拿到 JSX 组件，无 success/error 方法
+
+// ---- 业务类型 ----
+interface TaskRow {
+  id: string;
+  name: string;
+  status: 'running' | 'stopped';
+}
+
+// ---- 模拟 API ----
+const mockApi = {
+  deleteTask: async (id: string): Promise<void> => {
+    void id;
+    await new Promise<void>(res => setTimeout(res, 800));
+  },
+  toggleTask: async (id: string, enabled: boolean): Promise<void> => {
+    void id; void enabled;
+    await new Promise<void>(res => setTimeout(res, 600));
+  },
+  batchDelete: async (ids: string[]): Promise<void> => {
+    void ids;
+    await new Promise<void>(res => setTimeout(res, 1200));
+  },
+};
+
+const mockTasks: TaskRow[] = [
+  { id: 't1', name: '数据同步任务', status: 'running' },
+  { id: 't2', name: '备份任务', status: 'stopped' },
+];
+
+// ---- 主组件 ----
+const TaskManagePage: FunctionComponent = () => {
+  const [tasks, setTasks] = useState<TaskRow[]>(mockTasks);
+
+  // 每行独立的 loading map，避免多个操作互相干扰
+  const [deletingMap, setDeletingMap] = useState<Record<string, boolean>>({});
+  const [togglingMap, setTogglingMap] = useState<Record<string, boolean>>({});
+
+  // 批量删除 loading
+  const [batchDeleting, setBatchDeleting] = useState(false);
+  const [selectedIds, setSelectedIds] = useState<string[]>([]);
+
+  // ---- 单条删除 ----
+  // onOk 是 () => void，无参数，id 从闭包传入
+  const handleDelete = (id: string): void => {
+    setDeletingMap(prev => ({ ...prev, [id]: true }));
+    mockApi.deleteTask(id)
+      .then(() => {
+        // duration 是第 2 参数，不是 MsgTypeProps 字段
+        Message.success({ text: '任务已删除' }, 2000);
+        setTasks(prev => prev.filter(t => t.id !== id));
+      })
+      .catch(() => {
+        Message.error({ text: '删除失败，请重试' }, 4000);
+      })
+      .finally(() => {
+        setDeletingMap(prev => ({ ...prev, [id]: false }));
+      });
+  };
+
+  // ---- 启用 / 停止切换（Switch + PopConfirm 组合）----
+  const handleToggle = (row: TaskRow): void => {
+    setTogglingMap(prev => ({ ...prev, [row.id]: true }));
+    const willEnable = row.status === 'stopped';
+    mockApi.toggleTask(row.id, willEnable)
+      .then(() => {
+        Message.success(willEnable ? '任务已启动' : '任务已停止', 2000);
+        setTasks(prev =>
+          prev.map(t =>
+            t.id === row.id ? { ...t, status: willEnable ? 'running' : 'stopped' } : t
+          )
+        );
+      })
+      .catch(() => {
+        Message.error('操作失败，请重试', 3000);
+      })
+      .finally(() => {
+        setTogglingMap(prev => ({ ...prev, [row.id]: false }));
+      });
+  };
+
+  // ---- 批量删除 ----
+  const handleBatchDelete = (): void => {
+    if (selectedIds.length === 0) return;
+    setBatchDeleting(true);
+    // loading 场景：Message 无 loading 方法，用 info + duration=0 模拟
+    Message.info({ text: `正在删除 ${selectedIds.length} 个任务...`, close: false }, 0);
+    mockApi.batchDelete(selectedIds)
+      .then(() => {
+        Message.clear?.();   // clear 是可选方法，用可选链调用
+        Message.success(`已删除 ${selectedIds.length} 个任务`, 3000);
+        setTasks(prev => prev.filter(t => !selectedIds.includes(t.id)));
+        setSelectedIds([]);
+      })
+      .catch(() => {
+        Message.clear?.();
+        Message.error('批量删除失败，请重试', 4000);
+      })
+      .finally(() => {
+        setBatchDeleting(false);
+      });
+  };
+
+  return (
+    <div style={{ padding: 24 }}>
+      <h2>任务管理</h2>
+
+      {/* 批量操作区 */}
+      {selectedIds.length > 0 && (
+        <div style={{ marginBottom: 16, display: 'flex', gap: 8, alignItems: 'center' }}>
+          <span>已选 {selectedIds.length} 项</span>
+          <PopConfirm
+            title={`确认删除选中的 ${selectedIds.length} 个任务？`}
+            content="此操作不可恢复，请谨慎操作。"
+            type="error"
+            okButtonDanger={true}
+            okText="确认删除"
+            onOk={handleBatchDelete}         // () => void，无参数
+            okButtonProps={{ loading: batchDeleting }}
+          >
+            <Button variant="outlined">批量删除</Button>
+          </PopConfirm>
+        </div>
+      )}
+
+      {/* 任务列表 */}
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 12 }}>
+        {tasks.map(task => (
+          <div
+            key={task.id}
+            style={{
+              display: 'flex', alignItems: 'center', gap: 16,
+              padding: '12px 16px', border: '1px solid #e0e0e0', borderRadius: 6
+            }}
+          >
+            {/* 多选 */}
+            <input
+              type="checkbox"
+              checked={selectedIds.includes(task.id)}
+              onChange={e => {
+                setSelectedIds(prev =>
+                  e.target.checked
+                    ? [...prev, task.id]
+                    : prev.filter(id => id !== task.id)
+                );
+              }}
+            />
+
+            <span style={{ flex: 1 }}>{task.name}</span>
+            <span style={{ width: 60, color: task.status === 'running' ? '#4caf50' : '#999' }}>
+              {task.status === 'running' ? '运行中' : '已停止'}
+            </span>
+
+            {/* 停止运行中任务需要确认（高危：okButtonDanger + type='error'） */}
+            {task.status === 'running' ? (
+              <PopConfirm
+                title="确认停止任务？"
+                content="停止后任务将暂停执行，可手动重新启动。"
+                type="warning"
+                okText="停止"
+                onOk={() => handleToggle(task)}   // 闭包获取 task，onOk 无参数
+              >
+                <Switch
+                  checked={true}
+                  onChange={() => { /* 由 PopConfirm.onOk 驱动，此处不直接切换 */ }}
+                />
+              </PopConfirm>
+            ) : (
+              // 启动操作风险低，直接切换无需确认
+              <Switch
+                checked={false}
+                onChange={() => handleToggle(task)}
+              />
+            )}
+
+            {/* 删除操作：高危，倒计时强制用户等待 */}
+            <PopConfirm
+              title="确认删除此任务？"
+              content="删除后数据无法恢复。"
+              type="error"
+              okButtonDanger={true}
+              countdown={true}
+              countdownTime={3}              // 单位是秒，不是毫秒！
+              onOk={() => handleDelete(task.id)}
+              okButtonProps={{ loading: deletingMap[task.id] }}
+            >
+              <Button
+                variant="text"
+                disabled={togglingMap[task.id]}
+              >
+                删除
+              </Button>
+            </PopConfirm>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+};
+
+export default TaskManagePage;
+```
+
+---
+
+## 5 个真实陷阱（来自 M2/M3 修复实证）
+
+### ❌ 陷阱 1：从 `@para-ui/core` 直接导入 Message，丢失所有静态方法
+
+```tsx
+// 错（Task 25 失败根因，M2 实证）
+import { Message } from '@para-ui/core';
+Message.success('已删除');
+// TS2339: Property 'success' does not exist on type '() => Element'
+// 从 core 拿到的是 JSX 组件默认导出，不是 MessageObject 实例
+
+// 对
+import { Message } from '@para-ui/core/Message';   // 子路径！
+Message.success('已删除', 2000);
+```
+
+### ❌ 陷阱 2：把 duration 写进 MsgTypeProps 对象
+
+```tsx
+// 错（Task 23 失败根因，R23 Message-005 fail）
+Message.success({ text: '已删除', duration: 3000 });
+// TS2353: Object literal may only specify known properties,
+// and 'duration' does not exist in type 'MsgTypeProps'
+
+// 对：duration 是 Message.{type}() 的独立第 2 参数
+Message.success({ text: '已删除' }, 3000);
+// 或字符串简写
+Message.success('已删除', 3000);
+```
+
+### ❌ 陷阱 3：使用不存在的 `Message.loading`
+
+```tsx
+// 错（M2 实证：Message 只有 info/success/warn/error 4 个静态方法）
+Message.loading('处理中...');
+// TypeError: Message.loading is not a function
+
+// 对：用 info + duration=0 + close=false 模拟 loading
+Message.info({ text: '处理中...', close: false }, 0);
+// 完成后清除：
+Message.clear?.();   // ⚠️ clear 是可选方法，必须用可选链调用
+Message.success('完成', 2000);
+```
+
+### ❌ 陷阱 4：`onOk` 假设接收参数，或尝试在 onOk 内手动关闭弹框
+
+```tsx
+// 错（Task 19/20 失败：PopConfirm.onOk 签名是 () => void，无参数）
+<PopConfirm onOk={async (e) => { await doDelete(e.id); setOpen(false); }} />
+// 1. onOk 无参数，e 永远是 undefined
+// 2. 非受控模式下 handleOk 已自动关闭，无需 setOpen(false)
+
+// 对：id 从外部闭包获取，无需手动关闭
+<PopConfirm onOk={() => doDelete(task.id)} />
+```
+
+### ❌ 陷阱 5：受控模式只传 `open` 不传 `controllable={true}`
+
+```tsx
+// 错（Task 19 失败：非受控模式下 open prop 被忽略）
+<PopConfirm open={isOpen} onClose={() => setIsOpen(false)} />
+// open 被忽略，popup 以内部状态驱动
+// src/Popconfirm/index.tsx:175: controllable && setInOpen(open)
+// 没有 controllable=true，setInOpen 不被调用
+
+// 对：受控模式必须同时传 controllable={true}
+<PopConfirm
+  open={isOpen}
+  controllable={true}
+  onClose={() => setIsOpen(false)}
+/>
+```
+
+---
+
+## 真实参考
+
+**Para 团队真实业务代码**（因路径隔离，以下是样板文件中引用的 console 路径）：
+
+| 关键模式 | 所在文件 | 说明 |
+|---------|---------|------|
+| PopConfirm + Switch loading 实证 | `console/src/package/Service/src/content.tsx` | useAsync loading 状态驱动 Switch/按钮 loading |
+| Message 子路径导入 | 样板 `01-crud-list-multi-drawer.md` line 43 | `import { Message } from '@para-ui/core/Message'` |
+| onOk 闭包获取 id | `src/PopConfirm/component.json` events.onOk | `onOk={() => doDelete(id)}` 实证 |
+| countdown 秒单位 | `src/PopConfirm/component.json` typescriptPitfalls[3] | countdownTime 默认值 5 = 5 秒 |
+| Message.clear 可选链 | `src/Message/component.json` typescriptPitfalls[5] | `Message.clear?.()` |