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

package/ai-workflows/09-batch-operation-export-progress.md

@@ -0,0 +1,367 @@
+# Workflow 9: 批量操作 + 导出进度
+
+> **基于**：console/src/package/Service/src/content.tsx（导出 / 多选 / PopConfirm 异步链）  
+> **覆盖 baseline 失败任务**：Task 9（批量操作）/ Task 29（导出进度）/ Task 31（Upload + 进度）  
+> **集成 typescriptPitfalls**：Message 子路径导入（M2 实证）/ PopConfirm onOk 闭包取 id / Progress type 与 status 组合 / Modal onSubmit 异步 / Upload onChange 签名
+
+---
+
+## 何时使用
+
+管理后台同时需要以下能力中的 2 项及以上：
+
+```
+表格多选  +  批量确认删除/停用  +  单行/批量导出进度轮询  +  文件导入（Upload + 进度条）
+```
+
+**典型业务**：订单批量处理 / 资产批量导出 / 用户批量停用 / 数据文件导入
+
+**不要用此模板的场景**：
+- 单行删除无批量 → 用 Workflow 1（CRUD 列表）
+- 无进度展示需求（导出即时完成）→ 用基础 Button + PopConfirm
+
+---
+
+## 关键模式（与脑补的区别）
+
+| 错误模式（AI 常犯） | 正确模式 |
+|------------------|--------|
+| ❌ `import { Message } from '@para-ui/core'` 命令式 API 从主路径导入 | ✅ **`import { Message } from '@para-ui/core/Message'`**（M2 修复实证，主路径无命令式方法）|
+| ❌ `onOk={(val) => doDelete(val)}` 以为 onOk 带参数 | ✅ **`onOk={() => doDelete(id)}`** onOk 无参数，id 从外部闭包获取 |
+| ❌ `<Progress type='circle' status='active' />` active 动画用在 circle | ✅ **`<Progress type='line' status='active' />`** active 动画只对 type='line' 生效 |
+| ❌ `<Progress type='line' width={300} />` 用 width 控制 line 宽度 | ✅ **用容器 `<div style={{width:300}}>` 包裹**，line 模式 width prop 无效 |
+| ❌ Upload `onChange={({file, fileList}) => ...}` antd 风格解构 | ✅ **`onChange={(files) => ...}`** Para UI Upload onChange 参数直接是 `UploadFile[]` |
+| ❌ Modal `onOk={async () => submit()}` 用 onOk 异步 | ✅ **`onSubmit={async () => submit()}`** onSubmit 支持 Promise，onOk 已 deprecated |
+
+---
+
+## 完整代码（自包含，可直接复制）
+
+```tsx
+import React, { FunctionComponent, useState, useCallback } from 'react';
+import { Table, Button, PopConfirm, Progress, Modal, Upload } from '@para-ui/core';
+// 关键：Message 命令式 API 必须从子路径导入（M2 修复实证）
+import { Message } from '@para-ui/core/Message';
+import type { HeadDataProps } from '@para-ui/core';
+import type { UploadFile } from '@para-ui/core';
+
+interface OrderRow {
+  id: string;
+  orderNo: string;
+  amount: number;
+  status: 'pending' | 'paid' | 'refunded';
+  createdAt: string;
+}
+
+// 导出任务状态
+interface ExportTask {
+  taskId: string;
+  progress: number;       // 0-100
+  status: 'running' | 'done' | 'failed';
+  downloadUrl?: string;
+}
+
+const OrderBatchPage: FunctionComponent = () => {
+  const [refresh, setRefresh] = useState<number>(0);
+  const refreshData = (): void => setRefresh(Math.random());
+
+  // 多选 state
+  const [checkValue, setCheckValue] = useState<string[]>([]);
+
+  // 导出进度
+  const [exportTask, setExportTask] = useState<ExportTask | null>(null);
+  const [exportLoading, setExportLoading] = useState<boolean>(false);
+
+  // 导入 Modal
+  const [importOpen, setImportOpen] = useState<boolean>(false);
+  const [importFiles, setImportFiles] = useState<UploadFile[]>([]);
+  const [importProgress, setImportProgress] = useState<number>(0);
+  const [importing, setImporting] = useState<boolean>(false);
+
+  // ---- 批量删除 ----
+  // PopConfirm onOk 无参数，id 从外部闭包获取（不要传 val 参数）
+  const handleBatchDelete = async (): Promise<void> => {
+    const ids = [...checkValue];   // 从外部闭包取，不是 onOk 参数
+    await mockApi.batchDelete(ids);
+    Message.success(`已删除 ${ids.length} 条订单`);
+    setCheckValue([]);
+    refreshData();
+  };
+
+  // ---- 导出（带进度轮询）----
+  const handleExport = async (): Promise<void> => {
+    setExportLoading(true);
+    try {
+      const { taskId } = await mockApi.startExport(checkValue);
+      setExportTask({ taskId, progress: 0, status: 'running' });
+      // 轮询进度
+      const poll = setInterval(async () => {
+        const result = await mockApi.queryExportProgress(taskId);
+        setExportTask(result);
+        if (result.status !== 'running') {
+          clearInterval(poll);
+          setExportLoading(false);
+          if (result.status === 'done') {
+            Message.success('导出完成，可下载文件');
+          } else {
+            Message.error('导出失败，请重试');
+          }
+        }
+      }, 1500);
+    } catch {
+      setExportLoading(false);
+      Message.error('导出启动失败');
+    }
+  };
+
+  // ---- 导入（Upload + Progress）----
+  // Upload onChange 签名是 (files: UploadFile[]) => void，不是 antd 的 ({file,fileList}) => void
+  const handleImportFileChange = (files: UploadFile[]): void => {
+    setImportFiles(files);
+  };
+
+  // Modal onSubmit 支持 async Promise（onOk 已 deprecated，不支持 Promise 返回值）
+  const handleImportSubmit = async (): Promise<void> => {
+    if (importFiles.length === 0) {
+      Message.warn('请先选择文件');
+      return;
+    }
+    setImporting(true);
+    setImportProgress(0);
+    try {
+      // 模拟上传进度
+      await mockApi.uploadImport(importFiles[0], (pct: number) => {
+        setImportProgress(pct);
+      });
+      Message.success('导入成功');
+      setImportOpen(false);
+      setImportFiles([]);
+      setImportProgress(0);
+      refreshData();
+    } catch {
+      Message.error('导入失败');
+    } finally {
+      setImporting(false);
+    }
+  };
+
+  const headData: HeadDataProps<OrderRow>[] = [
+    { name: 'orderNo', label: '订单号', width: 160 },
+    { name: 'amount', label: '金额', width: 100,
+      render: (row) => `¥${row.amount.toFixed(2)}`
+    },
+    { name: 'status', label: '状态', width: 100,
+      render: (row) => ({ pending: '待支付', paid: '已支付', refunded: '已退款' }[row.status])
+    },
+    { name: 'createdAt', label: '下单时间', sort: true, width: 150 }
+  ];
+
+  return (
+    <div>
+      {/* 顶部批量操作区 */}
+      <div style={{ marginBottom: 16, display: 'flex', gap: 8, alignItems: 'center' }}>
+        <Button onClick={() => setImportOpen(true)} variant="outlined">导入</Button>
+
+        {checkValue.length > 0 && (
+          <>
+            <span style={{ alignSelf: 'center' }}>已选 {checkValue.length} 项</span>
+
+            {/* PopConfirm：onOk 无参，id 从闭包取 */}
+            <PopConfirm
+              title="确认批量删除"
+              type="error"
+              okButtonDanger={true}
+              onOk={handleBatchDelete}
+            >
+              <Button>批量删除</Button>
+            </PopConfirm>
+
+            <Button onClick={handleExport} disabled={exportLoading}>
+              {exportLoading ? '导出中...' : '批量导出'}
+            </Button>
+          </>
+        )}
+      </div>
+
+      {/* 导出进度展示 */}
+      {exportTask && (
+        <div style={{ marginBottom: 16 }}>
+          {/* active 动画只对 type='line' 生效；line 宽度用容器控制，不用 width prop */}
+          <div style={{ width: 400 }}>
+            <Progress
+              type="line"
+              percent={exportTask.progress}
+              status={
+                exportTask.status === 'failed' ? 'exception'
+                  : exportTask.status === 'done' ? 'success'
+                  : 'active'   // active 动画仅 type='line' 支持
+              }
+            />
+          </div>
+          {exportTask.status === 'done' && exportTask.downloadUrl && (
+            <a href={exportTask.downloadUrl} download style={{ marginTop: 8, display: 'block' }}>
+              点击下载导出文件
+            </a>
+          )}
+        </div>
+      )}
+
+      {/* 表格 */}
+      <Table<OrderRow>
+        rowKey="id"
+        data={mockData}
+        headData={headData}
+        refresh={refresh}
+        check={true}
+        setCheck={(arr: string[]) => setCheckValue(arr)}
+        pagination={true}
+        paginationType="complex"
+      />
+
+      {/* 导入 Modal */}
+      {/* onSubmit 支持 async，onOk 已 deprecated 且不支持 Promise */}
+      <Modal
+        open={importOpen}
+        title="批量导入订单"
+        onSubmit={handleImportSubmit}
+        onClose={() => { setImportOpen(false); setImportFiles([]); setImportProgress(0); }}
+        okButtonProps={{ loading: importing, children: '开始导入' }}
+      >
+        {/* Upload fileList prop 控制受控列表；onChange 参数是 UploadFile[]，不是 {file,fileList} 对象 */}
+        <Upload
+          accept=".xlsx,.csv"
+          maxCount={1}
+          onChange={handleImportFileChange}
+          fileList={importFiles}
+        />
+        {importing && (
+          <div style={{ marginTop: 16, width: '100%' }}>
+            <Progress type="line" percent={importProgress} status="active" />
+          </div>
+        )}
+      </Modal>
+    </div>
+  );
+};
+
+export default OrderBatchPage;
+
+// === 占位 Mock ===
+const mockData: OrderRow[] = [];
+const mockApi = {
+  batchDelete: async (ids: string[]): Promise<void> => { void ids; },
+  startExport: async (_ids: string[]): Promise<{ taskId: string }> => ({ taskId: 'mock-task' }),
+  queryExportProgress: async (_id: string): Promise<ExportTask> => ({
+    taskId: 'mock-task', progress: 100, status: 'done', downloadUrl: '/file.xlsx'
+  }),
+  uploadImport: async (_file: UploadFile, _onProgress: (pct: number) => void): Promise<void> => {}
+};
+```
+
+---
+
+## 5 个真实陷阱（来自 M2/M3 修复实证）
+
+### ❌ 陷阱 1：Message 从主路径导入，命令式 API 全部 undefined（M2 修复实证）
+
+```tsx
+// 错（最常见，M2 Stage 第一轮全军覆没的根因）
+import { Message } from '@para-ui/core';
+Message.success('操作成功');  // 运行报错：Message.success is not a function
+
+// 对：命令式 API 必须从子路径导入
+import { Message } from '@para-ui/core/Message';
+Message.success('操作成功');  // 正确
+Message.error('操作失败');
+Message.warn('请注意');
+```
+
+### ❌ 陷阱 2：PopConfirm onOk 期望接收 id 参数
+
+```tsx
+// 错（PopConfirm onOk 签名是 () => void，不传任何参数）
+<PopConfirm onOk={(id) => handleDelete(id)}>   // id 永远是 undefined
+  <Button>删除</Button>
+</PopConfirm>
+
+// 对：id 从外部闭包获取（Service/content.tsx 行 116-121 实证）
+const del = (row: OrderRow) => async () => {
+  await mockApi.deleteOrder(row.id);   // row.id 来自闭包
+  Message.success('已删除');
+  refreshData();
+};
+<PopConfirm onOk={del(row)}>
+  <Button>删除</Button>
+</PopConfirm>
+```
+
+### ❌ 陷阱 3：Progress active 动画用在 circle，type 与 status 组合错误
+
+```tsx
+// 错（active 动画仅 line 模式支持，circle 传 active 静默无效）
+<Progress type="circle" percent={60} status="active" />
+// 旋转动画不出现，不报错，容易忽视
+
+// 错（用 width prop 控制 line 宽度）
+<Progress type="line" percent={60} width={300} />
+// line 模式 width 控制的是 circle 画布尺寸，对 line 无效
+
+// 对
+<div style={{ width: 300 }}>
+  <Progress type="line" percent={60} status="active" />
+</div>
+// 导出完成状态
+<Progress type="line" percent={100} status="success" />
+// 导出失败状态
+<Progress type="line" percent={exportPct} status="exception" />
+```
+
+### ❌ 陷阱 4：Upload onChange 用 antd 风格解构，拿到 undefined
+
+```tsx
+// 错（antd 习惯）
+<Upload onChange={({ file, fileList }) => {
+  setFiles(fileList);  // fileList: undefined，解构失败
+}} />
+
+// 对：Para UI Upload onChange 第一参直接是 UploadFile[]
+<Upload onChange={(files: UploadFile[]) => {
+  setFiles(files);  // files 是 UploadFile 数组
+}} />
+
+// 另一个陷阱：UploadFile.status 只有 'error'|'done'|'removed'，没有 'uploading'
+// 上传中状态用 showLoading/loading prop 控制，不是检查 file.status === 'uploading'
+```
+
+### ❌ 陷阱 5：Modal 用 onOk 做异步提交，onOk 不等待 Promise
+
+```tsx
+// 错（onOk 已 deprecated，类型不含 Promise<void>）
+<Modal onOk={async () => {
+  await doSubmit();     // Modal 不等待这个 Promise，按钮不会 loading
+  setOpen(false);
+}} />
+
+// 对：用 onSubmit，支持 async Promise<void>
+<Modal
+  onSubmit={async () => {
+    await doSubmit();   // Modal 等待 Promise，按钮自动 loading
+    setOpen(false);
+  }}
+  okButtonProps={{ loading: submitting }}
+/>
+```
+
+---
+
+## 真实参考
+
+**Para 团队真实业务代码**：`console/src/package/Service/src/content.tsx`
+
+| 关键模式 | 行号 |
+|---------|------|
+| `import { Message } from '@para-ui/core/Message'` 子路径导入 | 8 |
+| `del(row)` 闭包工厂函数 → PopConfirm onOk | 116-121 |
+| `setExportInfo` + `setExportModuleOpen(true)` 触发导出流程 | 149-155 |
+| `importModule` + `onImportFinish` 导入完成刷新 | 158-172 |
+| `checkValue` + `setCheckValue` 多选管理 | 62, 568-570 |