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

package/ai-workflows/06-modal-drawer-form-workflow.md

@@ -0,0 +1,385 @@
+# Workflow 6: Modal / Drawer 嵌套 Form 工作流
+
+> **覆盖 baseline 失败任务**：Task 16（Form check() 返回 false | object）/ Task 18（Drawer 受控不自动关闭）/ Task 21（Modal onDismiss 类型）
+> **集成 typescriptPitfalls**：Form 5 条（FormRefObject / InputType / check 返回类型 / list key / rules.validate 大小写）+ Modal 4 条（onDismiss 类型 / closeOnBackdrop 正向命名 / onSubmit async / actions 返回 ReactNode[]）+ Drawer 4 条（DrawerProps 显式导入 / size='medium' / onClose 联合类型 / placement + 尺寸互斥）
+
+---
+
+## 何时使用
+
+需要在弹框中完成数据填写 + 校验 + 提交的场景：
+
+```
+用户打开 Modal/Drawer → Form 填写数据 → check() 校验 → 调用 API → 关闭弹框 + 刷新列表
+```
+
+**典型业务**：新建用户 / 编辑订单信息 / 创建资产 / 更新任务配置
+
+**选择 Modal vs Drawer**：
+- **Modal**：字段少（< 6 项）、一次性操作、需要强遮挡感
+- **Drawer**：字段多（>= 6 项）、需要同时看到背景列表、编辑详情页
+
+**不要用此模板的场景**：
+- 只读展示信息 → 用 Descriptions 或 Modal 纯展示
+- 需要多步骤流程 → 用 Steps + 页面级表单
+- 危险操作二次确认 → 用 Workflow 5（PopConfirm）
+
+---
+
+## 关键模式（与脑补的区别）
+
+| 错误模式（AI 常犯） | 正确模式 |
+|------------------|--------|
+| ❌ `const formRef = useRef(null); formRef.current.check()` | ✅ **`useRef<FormRefObject>({} as FormRefObject)` + 通过 `form={formRef}` 传入**（不是 JSX `ref` 属性！Form 用 `form` prop 接收 ref；类型必须显式声明，否则 current 是 null） |
+| ❌ `const ok = formRef.current.check?.(); if (!ok) throw new Error('fail')` | ✅ **`const values = formRef.current.check?.(); if (!values) return;`**（check 返回 `false \| object`，不抛异常，object 包含字段值） |
+| ❌ `configList: [{ name: 'type', label: '类型', type: 'select' }]` | ✅ **`configList: [{ name: 'type', label: '类型', InputType: 'select' }]`**（控件类型字段叫 `InputType`，`type` 是布局覆盖） |
+| ❌ `<Drawer onClose={(e: React.MouseEvent) => setOpen(false)} />` | ✅ **`onClose={(e: React.MouseEvent \| React.KeyboardEvent) => setOpen(false)}`**（ESC 触发时 e 是 KeyboardEvent） |
+| ❌ `<Drawer open={isOpen} />` 期望关闭 | ✅ **业务方必须在 onOk/onCancel/onClose 里调 `setOpen(false)`**（Drawer 不自动关闭，onOk/onCancel 只触发回调） |
+| ❌ `<Modal disableBackdropClick={false} />` | ✅ **`<Modal closeOnBackdrop={true} />`**（正向命名；disableBackdropClick 默认 true 即禁用，与多数库直觉相反） |
+
+---
+
+## 完整代码（自包含，可直接复制）
+
+```tsx
+import React, { FunctionComponent, useRef, useState } from 'react';
+import { Button, Drawer, Form, Modal } from '@para-ui/core';
+import { Message } from '@para-ui/core/Message';
+import type { DrawerProps, FormRefObject } from '@para-ui/core';
+
+// ---- 业务类型 ----
+interface OrderFormValues {
+  name: string;
+  type: 'standard' | 'express';
+  amount: number;
+  remark: string;
+}
+
+// ---- 模拟 API ----
+const mockApi = {
+  createOrder: async (data: OrderFormValues): Promise<void> => {
+    void data;
+    await new Promise<void>(res => setTimeout(res, 800));
+  },
+  updateOrder: async (id: string, data: OrderFormValues): Promise<void> => {
+    void id; void data;
+    await new Promise<void>(res => setTimeout(res, 600));
+  },
+};
+
+// ---- Form configList（控件类型字段叫 InputType，不是 type）----
+const buildOrderConfig = (readonly = false) => [
+  {
+    name: 'name',
+    label: '订单名称',
+    InputType: 'input' as const,
+    rules: {
+      validate: {
+        required: true,
+        maxlength: 50,   // ⚠️ maxlength 小写 l（src 现状，与 minLength 驼峰 L 不一致）
+      },
+    },
+    disabled: readonly,
+  },
+  {
+    name: 'type',
+    label: '配送类型',
+    InputType: 'select' as const,
+    // select 的 list 子项用 { label, value }，不是 { label, name }
+    list: [
+      { label: '标准配送', value: 'standard' },
+      { label: '加急配送', value: 'express' },
+    ],
+    rules: { validate: { required: true } },
+    disabled: readonly,
+  },
+  {
+    name: 'amount',
+    label: '数量',
+    InputType: 'number' as const,
+    rules: {
+      validate: {
+        required: true,
+        minLength: 1,   // ⚠️ minLength 驼峰 L（src 现状）
+      },
+    },
+    disabled: readonly,
+  },
+  {
+    name: 'remark',
+    label: '备注',
+    InputType: 'textarea' as const,
+    disabled: readonly,
+  },
+];
+
+// ============================================================
+// 子组件 A：Modal 新建订单（字段少、一次性）
+// ============================================================
+interface CreateOrderModalProps {
+  open: boolean;
+  onFinish: (saved: boolean) => void;
+}
+
+const CreateOrderModal: FunctionComponent<CreateOrderModalProps> = ({ open, onFinish }) => {
+  // FormRefObject 必须显式类型声明，否则 ref.current 是 unknown
+  const formRef = useRef<FormRefObject>({} as FormRefObject);
+  const [submitting, setSubmitting] = useState(false);
+
+  const handleSubmit = async (): Promise<void> => {
+    // check() 返回 false | object，不抛异常——失败时直接 return
+    const values = formRef.current.check?.();
+    if (!values) return;
+
+    setSubmitting(true);
+    try {
+      await mockApi.createOrder(values as OrderFormValues);
+      Message.success('订单已创建', 2000);
+      formRef.current.reset?.();
+      onFinish(true);    // 通知父组件关闭 + 刷新
+    } catch {
+      Message.error('创建失败，请重试', 4000);
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  return (
+    <Modal
+      open={open}
+      title="新建订单"
+      width={520}
+      confirmLoading={submitting}
+      // onSubmit 支持 async（onOk 已 deprecated）
+      onSubmit={handleSubmit}
+      onCancel={() => onFinish(false)}
+      // 正向命名：closeOnBackdrop 替代 disableBackdropClick={false}
+      closeOnBackdrop={false}
+      closeOnEsc={false}
+      destroyOnClose={true}     // 关闭后重置 Form 状态
+    >
+      <Form
+        form={formRef}
+        configList={buildOrderConfig()}
+      />
+    </Modal>
+  );
+};
+
+// ============================================================
+// 子组件 B：Drawer 编辑订单（字段多，保持背景可见）
+// ============================================================
+interface EditOrderDrawerProps extends Pick<DrawerProps, 'open'> {
+  orderId: string;
+  initialValues?: Partial<OrderFormValues>;
+  onFinish: (saved: boolean) => void;
+}
+
+const EditOrderDrawer: FunctionComponent<EditOrderDrawerProps> = ({
+  open,
+  orderId,
+  initialValues,
+  onFinish,
+}) => {
+  const formRef = useRef<FormRefObject>({} as FormRefObject);
+  const [submitting, setSubmitting] = useState(false);
+
+  const handleOk = async (): Promise<void> => {
+    const values = formRef.current.check?.();
+    if (!values) return;
+
+    setSubmitting(true);
+    try {
+      await mockApi.updateOrder(orderId, values as OrderFormValues);
+      Message.success('订单已更新', 2000);
+      onFinish(true);
+    } catch {
+      Message.error('更新失败', 4000);
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  return (
+    <Drawer
+      open={open}
+      title="编辑订单"
+      size="medium"               // 合法值：'small' | 'medium' | 'large' | 'auto'（不是 'mid'）
+      placement="right"
+      // placement='right' 时传 width 有效；传 height 无效（互斥）
+      // onClose 参数是联合类型：MouseEvent | KeyboardEvent（ESC 键触发时）
+      onClose={(_e: React.MouseEvent | React.KeyboardEvent) => onFinish(false)}
+      // Drawer 不会自动关闭！onOk / onCancel 只触发回调，业务方必须自行 setOpen(false) / onFinish
+      onOk={handleOk}
+      onCancel={() => onFinish(false)}
+      confirmLoading={submitting}
+      destroyOnClose={true}
+    >
+      <Form
+        form={formRef}
+        configList={buildOrderConfig()}
+        backData={initialValues as Record<string, unknown>}
+      />
+    </Drawer>
+  );
+};
+
+// ============================================================
+// 父组件：统一管理 Modal + Drawer 的 open state
+// ============================================================
+const OrderPage: FunctionComponent = () => {
+  const [openCreate, setOpenCreate] = useState(false);
+  const [openEdit, setOpenEdit] = useState(false);
+  const [editingOrderId, setEditingOrderId] = useState<string>('');
+  const [refresh, setRefresh] = useState(0);
+  const refreshData = (): void => setRefresh(Math.random());
+
+  const handleEditOpen = (orderId: string): void => {
+    setEditingOrderId(orderId);
+    setOpenEdit(true);
+  };
+
+  return (
+    <div style={{ padding: 24 }}>
+      <div style={{ display: 'flex', gap: 8, marginBottom: 16 }}>
+        <Button onClick={() => setOpenCreate(true)}>新建订单</Button>
+        <Button variant="outlined" onClick={() => handleEditOpen('order-001')}>
+          编辑示例订单
+        </Button>
+      </div>
+
+      <div style={{ color: '#999', fontSize: 12 }}>刷新计数: {refresh}</div>
+
+      {/* Modal：新建，字段少，强遮挡 */}
+      <CreateOrderModal
+        open={openCreate}
+        onFinish={(saved) => {
+          setOpenCreate(false);
+          if (saved) refreshData();
+        }}
+      />
+
+      {/* Drawer：编辑，字段多，保持背景列表可见 */}
+      {openEdit && (
+        <EditOrderDrawer
+          open={openEdit}
+          orderId={editingOrderId}
+          initialValues={{ name: '示例订单', type: 'standard', amount: 10 }}
+          onFinish={(saved) => {
+            setOpenEdit(false);
+            setEditingOrderId('');
+            if (saved) refreshData();
+          }}
+        />
+      )}
+    </div>
+  );
+};
+
+export default OrderPage;
+```
+
+---
+
+## 5 个真实陷阱（来自 M2/M3 修复实证）
+
+### ❌ 陷阱 1：`useRef(null)` 导致 check() 报 unknown 类型错误，或用 JSX `ref` 而非 `form` prop
+
+```tsx
+// 错（Task 16 失败根因 1：ref 类型推断失败）
+const formRef = useRef(null);
+formRef.current.check?.();   // TS: 类型 null 上不存在属性 check
+
+// 错（根因 2：Form 不接受 JSX ref 属性，必须用 form prop）
+<Form ref={formRef} configList={...} />
+// TS2322: Property 'ref' does not exist on type 'IntrinsicAttributes & FormProps'
+
+// 对：显式声明 FormRefObject 类型 + 通过 form prop 传入
+import type { FormRefObject } from '@para-ui/core';
+const formRef = useRef<FormRefObject>({} as FormRefObject);
+<Form form={formRef} configList={...} />   // ✅ form prop 不是 ref
+formRef.current.check?.();   // check?: () => false | Record<string, unknown>
+```
+
+### ❌ 陷阱 2：`check()` 失败时抛异常或返回 undefined
+
+```tsx
+// 错（Task 16 失败：假设 check 抛异常或返回 boolean）
+try {
+  formRef.current.check?.();
+  await submit();
+} catch (validationError) {
+  // check 失败不抛异常，catch 永远不触发
+}
+
+// 对：check 返回 false（失败）或 object（成功，含字段值）
+const values = formRef.current.check?.();
+if (!values) return;    // false → 校验失败，直接 return
+await submit(values as OrderFormValues);  // object → 校验成功
+```
+
+### ❌ 陷阱 3：Form configList 控件类型字段名写错 `type`
+
+```tsx
+// 错（Task 16 常见：type 在 FormItem 是布局覆盖，不是控件类型）
+configList={[
+  { name: 'category', label: '类别', type: 'select', list: [...] }
+  // type='select' 被解释为布局 override，下拉框不渲染
+]}
+
+// 对：控件类型字段叫 InputType
+configList={[
+  { name: 'category', label: '类别', InputType: 'select', list: [...] }
+]}
+```
+
+### ❌ 陷阱 4：`select` 的 list 子项用 `name` 而非 `value`
+
+```tsx
+// 错（DEFECT-008：select 内部读 value 字段，name 被忽略）
+configList={[{
+  name: 'type', InputType: 'select',
+  list: [{ label: '标准', name: 'standard' }]   // name 被忽略，选中后 onChange 不传值
+}]}
+
+// 对：select → value 字段；radioGroup/checkGroup 才用 name
+configList={[{
+  name: 'type', InputType: 'select',
+  list: [{ label: '标准', value: 'standard' }]  // ✅
+}]}
+```
+
+### ❌ 陷阱 5：Drawer 期望 onOk/onCancel 后自动关闭
+
+```tsx
+// 错（Task 18 失败根因）
+// 用户点"确定" → Drawer.onOk 触发 → 业务回调被调 → Drawer 不关闭
+// src/Drawer/index.tsx: onOk 只触发回调，不修改 open 状态
+<Drawer open={isOpen} onOk={() => handleSave()} />
+// 点确定后 Drawer 一直在，用户困惑
+
+// 对：业务方在回调里显式关闭
+<Drawer
+  open={isOpen}
+  onOk={async () => {
+    await handleSave();
+    setIsOpen(false);   // 必须！Drawer 不自动关闭
+  }}
+  onCancel={() => setIsOpen(false)}   // 取消也必须手动关闭
+  onClose={() => setIsOpen(false)}    // ESC/遮罩关闭路径
+/>
+```
+
+---
+
+## 真实参考
+
+**Para 团队真实业务代码**（console 路径，因仓库隔离，以下是任务说明中的引用路径）：
+
+| 关键模式 | 所在文件 | 说明 |
+|---------|---------|------|
+| Drawer + Form 组合 | `console/src/package/User/src/formDrawer/` | 受控 Drawer + FormRefObject + check() |
+| 多 config 共享 Drawer | `console/src/package/Group/src/formDrawer/` | 同一 Drawer 复用不同 configList |
+| Form check() 失败 return 模式 | `src/Form/component.json` do[2] | `const values = formRef.current.check?.(); if (!values) return;` |
+| Drawer size='medium' | `src/Drawer/component.json` typescriptPitfalls[1] | 合法值 'small'\|'medium'\|'large'\|'auto' |
+| Modal closeOnBackdrop 正向命名 | `src/Modal/component.json` do[5] | R6 §B6 阶段 1 引入，替代 disableBackdropClick |