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

package/ai-workflows/03-complex-form-async-cascade.md

@@ -0,0 +1,350 @@
+# Workflow 3: 复杂表单 + 异步验证 + 级联 Select + Upload
+
+> **基于**：console 真实业务代码（User 模块 / Faas 模块）提炼  
+> **覆盖 baseline 失败任务**：Task 11（带验证表单）/ Task 12（级联 Select）/ Task 13（Upload 文件上传）/ Task 14（异步验证）/ Task 17（综合场景）  
+> **集成 typescriptPitfalls**：Form 5 条 / Select 5 条 / DatePicker 4 条 / Upload 4 条
+
+---
+
+## 何时使用
+
+单张表单页面同时包含以下 3 项及以上：
+
+```
+文本 / 数字输入  +  Select 级联  +  文件上传  +  异步唯一性校验  +  DatePicker  +  条件显隐字段
+```
+
+**典型业务**：新建订单 / 用户注册 / 资产登记 / 合同上传 / 工单创建
+
+**不要用此模板的场景**：
+- 只有文本输入（≤ 3 个字段）→ 用简单 Form
+- 只读详情展示（无编辑）→ 用 Descriptions
+- 动态多行录入 → 用 Workflow 4（DynamicMultiBox）
+
+---
+
+## 关键模式（与脑补的区别）
+
+| 错误模式（AI 常犯） | 正确模式 |
+|------------------|--------|
+| ❌ `rules: { validate: { maxLength: 10 } }`（驼峰 L） | ✅ `rules: { validate: { maxlength: 10 } }`（小写 l）— src 现状不一致 |
+| ❌ `const formRef = useRef(null)` → `formRef.current.check()` 报 unknown | ✅ `useRef<FormRefObject>({} as FormRefObject)` |
+| ❌ `InputType: 'text'` HTML 风格控件类型 | ✅ `InputType: 'default'`（Para UI 字符串输入是 `'default'`） |
+| ❌ `list: [{ label: '选项A', name: 'a' }]` 用于 Select | ✅ Select 子项用 `value` 字段；radioGroup/checkGroup 用 `name` |
+| ❌ `onChange={setLang}` 直接传 setter（签名不匹配） | ✅ `onChange={(val, _e) => setLang(val ?? '')}` 带第二参数 |
+| ❌ `value={'2024-01-01'}` 传字符串给 DatePicker | ✅ `value={dayjs('2024-01-01')}` 必须传 Dayjs 对象 |
+
+---
+
+## 完整代码（自包含，可直接复制）
+
+```tsx
+import React, { FunctionComponent, useRef, useState, useCallback } from 'react';
+import dayjs from 'dayjs';
+import type { Dayjs } from 'dayjs';
+import { Form, Button, DatePicker } from '@para-ui/core';
+import { Message } from '@para-ui/core/Message';
+import { FormRefObject, SelectOptionBase } from '@para-ui/core';
+import type { UploadFile, configListProps } from '@para-ui/core';
+import Select from '@para-ui/core/Select';
+import Upload from '@para-ui/core/Upload';
+
+// === 业务数据类型 ===
+interface OrderForm {
+  title: string;
+  category: string;
+  subCategory: string;
+  assignee: string;
+  dueDate: Dayjs | null;
+  attachments: UploadFile[];
+}
+
+// === 级联 Select 数据 ===
+// ✅ SelectOptionBase 从 @para-ui/core 导入（不是 @para-ui/core/Select）
+interface CategoryOpt extends SelectOptionBase {
+  catName: string;
+  catCode: string;
+}
+
+const CATEGORY_LIST: CategoryOpt[] = [
+  { catName: '硬件', catCode: 'hw' },
+  { catName: '软件', catCode: 'sw' },
+  { catName: '服务', catCode: 'svc' }
+];
+
+const SUB_CATEGORY_MAP: Record<string, CategoryOpt[]> = {
+  hw: [{ catName: '服务器', catCode: 'hw-srv' }, { catName: '网络', catCode: 'hw-net' }],
+  sw: [{ catName: '操作系统', catCode: 'sw-os' }, { catName: '中间件', catCode: 'sw-mw' }],
+  svc: [{ catName: '咨询', catCode: 'svc-con' }, { catName: '培训', catCode: 'svc-trn' }]
+};
+
+// === 异步唯一性校验（模拟，实际调 API） ===
+const checkTitleUnique = async (title: string): Promise<boolean> => {
+  await new Promise(r => setTimeout(r, 300));
+  return title !== 'duplicate-title'; // 模拟：该标题已存在
+};
+
+// === 主组件 ===
+const OrderCreateForm: FunctionComponent = () => {
+  // ✅ FormRefObject 必须显式类型声明，否则 current 推断为 unknown
+  const formRef = useRef<FormRefObject>({} as FormRefObject);
+
+  const [category, setCategory] = useState<string>('');
+  const [subCategory, setSubCategory] = useState<string>('');
+  const [dueDate, setDueDate] = useState<Dayjs | null>(null);
+  const [attachments, setAttachments] = useState<UploadFile[]>([]);
+  const [submitting, setSubmitting] = useState<boolean>(false);
+
+  // 级联：切换父类时重置子类
+  const handleCategoryChange = (val: string | undefined, _e: React.SyntheticEvent): void => {
+    setCategory(val ?? '');
+    setSubCategory(''); // 级联清空子类
+  };
+
+  const handleSubCategoryChange = (val: string | undefined, _e: React.SyntheticEvent): void => {
+    setSubCategory(val ?? '');
+  };
+
+  // 提交：先 check，再异步校验标题唯一性，最后提交
+  const handleSubmit = useCallback(async (): Promise<void> => {
+    // ✅ check() 返回 false | object，不是 boolean 也不抛异常
+    const values = formRef.current.check?.();
+    if (!values) return; // false 表示校验失败
+
+    // 异步校验
+    const isUnique = await checkTitleUnique(values.title as string);
+    if (!isUnique) {
+      Message.error('工单标题已存在，请换一个');
+      return;
+    }
+
+    setSubmitting(true);
+    try {
+      const orderData: OrderForm = {
+        title: values.title as string,
+        category,
+        subCategory,
+        assignee: values.assignee as string,
+        dueDate,
+        attachments
+      };
+      await mockApi.createOrder(orderData);
+      Message.success('工单已创建');
+    } finally {
+      setSubmitting(false);
+    }
+  }, [category, subCategory, dueDate, attachments]);
+
+  // ✅ 显式声明 configListProps 类型，避免 rules.message 可选字段与 index signature 冲突
+  const configList: configListProps = [
+    {
+      name: 'title',
+      label: '工单标题',
+      // ✅ 控件类型用 InputType（不是 type，type 是布局覆盖）
+      InputType: 'default',
+      rules: {
+        validate: {
+          required: true,
+          // ✅ maxlength 小写 L；minLength 驼峰 L（src 现状不一致）
+          maxlength: 100,
+          minLength: 2
+        },
+        message: {
+          required: '请输入工单标题',
+          maxlength: '标题不超过 100 字',
+          minLength: '标题至少 2 字'
+        }
+      }
+    },
+    {
+      name: 'assignee',
+      label: '经办人',
+      InputType: 'default',
+      rules: {
+        validate: { required: true },
+        message: { required: '请输入经办人' }
+      }
+    }
+  ];
+
+  return (
+    <div style={{ maxWidth: 600 }}>
+      <Form
+        form={formRef}
+        configList={configList}
+        type="vertical"
+      />
+
+      {/* 级联 Select：父类 */}
+      <div style={{ marginBottom: 16 }}>
+        <label>分类</label>
+        <Select<string>
+          list={CATEGORY_LIST}
+          value={category || undefined}
+          // ✅ 数据源字段名不是 label/value 时必须传 showName/showValue
+          showName="catName"
+          showValue="catCode"
+          allowClear
+          placeholder="请选择分类"
+          onChange={handleCategoryChange}
+        />
+      </div>
+
+      {/* 级联 Select：子类（依赖父类） */}
+      <div style={{ marginBottom: 16 }}>
+        <label>子分类</label>
+        <Select<string>
+          list={category ? SUB_CATEGORY_MAP[category] ?? [] : []}
+          value={subCategory || undefined}
+          showName="catName"
+          showValue="catCode"
+          allowClear
+          placeholder={category ? '请选择子分类' : '请先选择分类'}
+          disabled={!category}
+          onChange={handleSubCategoryChange}
+        />
+      </div>
+
+      {/* DatePicker：必须传 Dayjs 对象，不能传字符串 */}
+      <div style={{ marginBottom: 16 }}>
+        <label>截止日期</label>
+        <DatePicker
+          value={dueDate}
+          onChange={(date: Dayjs | null) => setDueDate(date)}
+          // ✅ disabledDate 参数是 Dayjs，用 Dayjs API 不用 Date 方法
+          disabledDate={(cur: Dayjs) => cur && cur.isBefore(dayjs().startOf('day'))}
+        />
+      </div>
+
+      {/* Upload：onChange 签名是 (files: UploadFile[]) => void，不是 antd 的 {file,fileList} */}
+      <div style={{ marginBottom: 24 }}>
+        <label>附件</label>
+        <Upload
+          fileList={attachments}
+          onChange={(files: UploadFile[]) => setAttachments(files)}
+          multiple
+          accept=".pdf,.doc,.docx,.xlsx"
+        />
+      </div>
+
+      <Button
+        variant="contained"
+        loading={submitting}
+        onClick={handleSubmit}
+      >
+        提交工单
+      </Button>
+      <Button
+        style={{ marginLeft: 8 }}
+        onClick={() => formRef.current.reset?.()}
+      >
+        重置
+      </Button>
+    </div>
+  );
+};
+
+export default OrderCreateForm;
+
+// === 占位 Mock ===
+const mockApi = {
+  createOrder: async (data: OrderForm): Promise<void> => { void data; }
+};
+```
+
+---
+
+## 5 个真实陷阱（来自 M2/M3 修复实证）
+
+### ❌ 陷阱 1：Form rules.validate 大小写不一致（src 现状）
+```tsx
+// 错（校验规则被忽略，不报 TS 错但校验不生效）
+rules: { validate: { maxLength: 10, minlength: 2 } }
+//                   ↑ 驼峰L        ↑ 全小写
+
+// 对（严格按 src/FormItem/index.tsx:54-60 字段名）
+rules: { validate: { maxlength: 10, minLength: 2 } }
+//                   ↑ 小写l         ↑ 驼峰L
+// 记忆口诀：max 小 / min 大（不一致是 src 历史问题，无法改变）
+```
+**实证来源**：Form component.json `typescriptPitfalls[2]`，Task 11/14 失败根因之一。
+
+### ❌ 陷阱 2：FormRefObject 未显式类型声明
+```tsx
+// 错：useRef(null) → current 推断为 unknown → check() 报类型错
+const formRef = useRef(null);
+formRef.current.check?.();  // 报 TS 错：null 上不存在 check
+
+// 对：显式声明 FormRefObject 类型
+import { FormRefObject } from '@para-ui/core';
+const formRef = useRef<FormRefObject>({} as FormRefObject);
+// check() 返回 false（失败）或 object（成功）—— 不抛异常
+const values = formRef.current.check?.();
+if (!values) return;  // false 表失败
+```
+**实证来源**：Form component.json `typescriptPitfalls[0]`，Task 11 失败根因。
+
+### ❌ 陷阱 3：Select 数据源字段名忘传 showName/showValue
+```tsx
+// 错：自定义字段名不传 showName/showValue → 下拉无文字，onChange 返回 undefined
+<Select list={[{ catName: '硬件', catCode: 'hw' }]} value={category} onChange={...} />
+// 问题：Select 默认读 label/value 字段，catName/catCode 不被识别
+
+// 对：非 label/value 字段名时必须声明
+<Select
+  list={CATEGORY_LIST}
+  showName="catName"    // ← 显示字段名
+  showValue="catCode"   // ← 取值字段名
+  value={category || undefined}
+  onChange={(val, _e) => setCategory(val ?? '')}
+/>
+```
+**实证来源**：Select component.json `commonMisconceptions[0]`，Task 12 失败根因。
+
+### ❌ 陷阱 4：DatePicker value 传字符串而非 Dayjs 对象
+```tsx
+// 错：传字符串 → 组件内部格式化失败，日期显示异常
+const [date, setDate] = useState('2024-01-01');
+<DatePicker value={date} onChange={(d) => setDate(d)} />
+//           ↑ 字符串，不是 Dayjs
+
+// 对：必须用 dayjs() 转换；清空用 null
+const [date, setDate] = useState<Dayjs | null>(null);
+<DatePicker
+  value={date}
+  onChange={(d: Dayjs | null) => setDate(d)}
+  // disabledDate 参数也是 Dayjs，用 Dayjs API
+  disabledDate={(cur: Dayjs) => cur.isBefore(dayjs().startOf('day'))}
+/>
+```
+**实证来源**：DatePicker component.json `typescriptPitfalls[0]` + `typescriptPitfalls[3]`，Task 13 失败根因。
+
+### ❌ 陷阱 5：Upload onChange 签名与 antd 不同
+```tsx
+// 错（antd 风格：解构对象）
+<Upload onChange={({file, fileList}) => setList(fileList)} />
+// 报 TS 类型错：实际传入的是数组 UploadFile[]，不是对象
+
+// 对：Para UI Upload onChange 直接接收 UploadFile[]
+<Upload
+  fileList={attachments}
+  onChange={(files: UploadFile[]) => setAttachments(files)}
+/>
+// 注意：UploadFile.status 只有 'error' | 'done' | 'removed'，没有 'uploading'
+// 上传中状态用 showLoading/loading prop 控制 UI
+```
+**实证来源**：Upload component.json `typescriptPitfalls[0]` + `typescriptPitfalls[1]`，Task 13/17 失败根因。
+
+---
+
+## 真实参考
+
+| 关键模式 | 参考位置 |
+|---------|--------|
+| `FormRefObject` 声明 + `check()` 返回值 | Form/component.json typescriptPitfalls[0][3] |
+| `maxlength`/`minLength` 大小写陷阱 | Form/component.json typescriptPitfalls[2] |
+| `InputType` vs `type` 字段区分 | Form/component.json typescriptPitfalls[1] |
+| Select `showName`/`showValue` 必传场景 | Select/component.json commonMisconceptions[0] |
+| Select `onChange` 第二参数 `e` 签名 | Select/component.json typescriptPitfalls[0] |
+| DatePicker value 必须是 Dayjs | DatePicker/component.json typescriptPitfalls[0] |
+| Upload onChange 是数组而非 antd 对象 | Upload/component.json typescriptPitfalls[0] |

package/ai-workflows/04-array-field-form.md

@@ -0,0 +1,281 @@
+# Workflow 4: 数组字段表单 DynamicMultiBox
+
+> **基于**：console 真实业务代码（Faas 模块 / 参数配置模块）提炼  
+> **覆盖 baseline 失败任务**：Task 15（动态多行表单 DynamicMultiBox）  
+> **集成 typescriptPitfalls**：M2 修复 DynamicMultiBox 6 条 typescriptPitfalls 全部集成
+
+---
+
+## 何时使用
+
+表单中需要动态增减行数的多行录入场景：
+
+```
+批量参数录入  /  联系人列表  /  规则条件配置  /  可排序步骤  /  字段自定义
+```
+
+**典型业务**：订单明细 / 角色权限规则 / 资产联系人 / 工作流步骤
+
+**不要用此模板的场景**：
+- 固定字段表单（行数固定）→ 用 Form（Workflow 3）
+- 只读数组展示 → 用 Table
+- 树形结构（有嵌套子级）→ 用 Tree
+
+---
+
+## 关键模式（与脑补的区别）
+
+| 错误模式（AI 常犯） | 正确模式 |
+|------------------|--------|
+| ❌ `onAdd={(list) => setValueList(list)}` 单参数 | ✅ `onAdd={(list, errs) => { setValueList(list); setErrors(errs); }}` 双参数 |
+| ❌ `errRow[cfg.name] = ''`（IConfig.name 可能是 undefined） | ✅ `if (cfg.name) errRow[cfg.name] = ''` narrow 后再索引 |
+| ❌ `rest as Contact`（unknown 索引签名直接 as） | ✅ `rest as unknown as Contact`（unknown 中转）|
+| ❌ `{ inputType: 'text' }` HTML 小写风格 | ✅ `{ inputType: 'TextField' }` PascalCase（严格枚举） |
+| ❌ 不传泛型 `<DynamicMultiBox>` | ✅ 传泛型 + interface 加 index signature `[key: string]: unknown` |
+| ❌ `titleMode='single'` 误解为"只第一行有标题" | ✅ `single` = 整表 1 个合并标题；每列独立标题用 `all`（默认） |
+
+---
+
+## 完整代码（自包含，可直接复制）
+
+```tsx
+import React, { FC, useState, useMemo } from 'react';
+import DynamicMultiBox from '@para-ui/core/DynamicMultiBox';
+import type { IConfig, IErrors, IValueList } from '@para-ui/core/DynamicMultiBox/interface';
+
+// === 业务数据类型 ===
+// ✅ 泛型 T 必须满足 Record<string, unknown> 约束 → 加 index signature
+interface ContactItem {
+  name: string;
+  phone: string;
+  email: string;
+  role: string;
+  [key: string]: unknown;  // ← 必须加，否则 TS2344 不满足 DynamicMultiBox 泛型约束
+}
+
+// === 工具：初始化 errors 空占位行 ===
+// ✅ IConfig.name 是 string | undefined → narrow 后再索引（M1 TS2538 修复）
+const buildEmptyErrors = (
+  valueList: IValueList[],
+  fieldConfig: IConfig[]
+): IErrors[] =>
+  valueList.map(row => {
+    const errRow: IErrors = { id: row.id };
+    fieldConfig.forEach(cfg => {
+      if (cfg.name) errRow[cfg.name] = '';  // ← narrow，不是 errRow[cfg.name!] 也行
+    });
+    return errRow;
+  });
+
+// === 业务类型转换 ===
+// ✅ IValueList 解构后 rest 是 unknown 索引签名 → as unknown as 中转（M2 TS2352 修复）
+const toContacts = (valueList: IValueList[]): ContactItem[] =>
+  valueList.map(({ id, ...rest }) => rest as unknown as ContactItem);  // void id 不需要时
+const toValueList = (contacts: ContactItem[]): IValueList[] =>
+  contacts.map((c, i) => ({ id: String(i + 1), ...c }));
+
+// === 字段配置 ===
+// ✅ inputType 必须 PascalCase（'TextField' / 'Select' / 'Switch' 等），不是 HTML 小写
+const FIELD_CONFIG: IConfig[] = [
+  { name: 'name', label: '姓名', inputType: 'TextField', required: true },
+  { name: 'phone', label: '电话', inputType: 'TextField' },
+  { name: 'email', label: '邮箱', inputType: 'TextField' },
+  {
+    name: 'role',
+    label: '角色',
+    inputType: 'Select',
+    // ✅ Select 类型子项用 list 字段（component.json idealProps.config 说明）
+    list: [
+      { label: '主联系人', value: 'primary' },
+      { label: '抄送人', value: 'cc' },
+      { label: '审批人', value: 'approver' }
+    ]
+  }
+];
+
+// === 包装组件（对外以 ContactItem[] 受控）===
+interface ContactsFormProps {
+  contacts: ContactItem[];
+  onChange: (contacts: ContactItem[]) => void;
+}
+
+const ContactsEntryForm: FC<ContactsFormProps> = ({ contacts, onChange }) => {
+  // ✅ 双 state：valueList + errors 都必须维护（wrapperPattern 核心）
+  const [valueList, setValueList] = useState<IValueList[]>(
+    () => toValueList(contacts)
+  );
+  const [errors, setErrors] = useState<IErrors[]>(
+    () => buildEmptyErrors(toValueList(contacts), FIELD_CONFIG)
+  );
+
+  return (
+    <DynamicMultiBox
+      config={FIELD_CONFIG}
+      valueList={valueList}
+      errors={errors}
+      // ✅ titleMode='all'（默认）= 每列独立 label；不要写 'single'（整表 1 个合并标题）
+      titleMode="all"
+      isSort
+      onChange={(next) => {
+        setValueList(next);
+        onChange(toContacts(next));
+      }}
+      // ✅ onAdd 必须接收双参数，errors 同步（M3 修复）
+      onAdd={(next, nextErrors) => {
+        setValueList(next);
+        setErrors(nextErrors);
+        onChange(toContacts(next));
+      }}
+      // ✅ onDelete 必须接收双参数（M3 修复）
+      onDelete={(next, nextErrors) => {
+        setValueList(next);
+        setErrors(nextErrors);
+        onChange(toContacts(next));
+      }}
+      onSort={(newList) => {
+        setValueList(newList);
+        onChange(toContacts(newList));
+      }}
+    />
+  );
+};
+
+// === 页面使用示例 ===
+const OrderContactsPage: FC = () => {
+  const [contacts, setContacts] = useState<ContactItem[]>([
+    { name: '张三', phone: '13800000001', email: 'zhang@example.com', role: 'primary', [Symbol.iterator]: undefined }
+  ]);
+
+  // useMemo 避免每次 render 都重建（contacts 作为依赖）
+  const initialContacts = useMemo<ContactItem[]>(() => [
+    { name: '', phone: '', email: '', role: '' }
+  ], []);
+
+  void initialContacts;
+
+  return (
+    <div>
+      <h3>联系人配置</h3>
+      <ContactsEntryForm
+        contacts={contacts}
+        onChange={setContacts}
+      />
+      <div style={{ marginTop: 16 }}>
+        当前联系人数：{contacts.length}
+      </div>
+    </div>
+  );
+};
+
+export default OrderContactsPage;
+```
+
+---
+
+## 5 个真实陷阱（来自 M2 修复实证）
+
+### ❌ 陷阱 1：onAdd / onDelete 只传单参数（errors 不同步）
+```tsx
+// 错（M2 DynamicMultiBox commonMisconceptions.M3 根因）
+onAdd={(valueList) => setValueList(valueList)}
+// 问题：errors state 与 valueList 行数不同步 → 新行渲染时查 errors 失败
+// TS 不会报错（callback 参数可少传），但逻辑错误
+
+// 对：必须双参数 + 双 setState
+onAdd={(valueList, errors) => {
+  setValueList(valueList);
+  setErrors(errors);         // ← errors 已含新行空占位，直接用
+}}
+onDelete={(valueList, errors) => {
+  setValueList(valueList);
+  setErrors(errors);
+}}
+```
+**实证来源**：DynamicMultiBox/component.json `commonMisconceptions.M3`，Task 15 失败根因。
+
+### ❌ 陷阱 2：`IConfig.name` 直接用作对象索引（TS2538）
+```tsx
+// 错（M2 DynamicMultiBox r23FailingScenarios.scenario_003 根因）
+const buildEmptyErrors = (valueList: IValueList[], fieldConfig: IConfig[]) =>
+  valueList.map(row => {
+    const errRow: IErrors = { id: row.id };
+    fieldConfig.forEach((cfg) => {
+      errRow[cfg.name] = '';  // TS2538: 'undefined' cannot be used as an index type
+    });                         // IConfig.name 是 string | undefined！
+    return errRow;
+  });
+
+// 对：narrow 后再索引
+fieldConfig.forEach((cfg) => {
+  if (cfg.name) errRow[cfg.name] = '';  // narrow
+  // 或：errRow[cfg.name!] = '';  // 非空断言（已知 name 必有值时）
+});
+```
+**实证来源**：DynamicMultiBox/component.json `typescriptPitfalls[0]`，R23 DynamicMultiBox-003 失败。
+
+### ❌ 陷阱 3：IValueList 解构后直接 as 业务类型（TS2352）
+```tsx
+// 错（M2 DynamicMultiBox r23FailingScenarios.scenario_006 根因）
+const toContact = (item: IValueList): Contact =>
+  (({ id, ...rest }) => rest as Contact)(item);
+// TS2352: Conversion may be a mistake because neither type sufficiently overlaps
+// rest 被推断为 { [x: string]: unknown }，直接 as Contact 被 TS 5.x 拒绝
+
+// 对：unknown 中转
+const toContact = (item: IValueList): Contact =>
+  (({ id, ...rest }) => rest as unknown as Contact)(item);  // 先转 unknown 再转目标
+// 或显式字段映射（更安全）：
+const toContact = ({ name, phone, email }: IValueList): Contact => ({ name, phone, email } as Contact);
+```
+**实证来源**：DynamicMultiBox/component.json `typescriptPitfalls[1]`，R23 DynamicMultiBox-006 失败。
+
+### ❌ 陷阱 4：inputType 用 HTML 小写风格
+```tsx
+// 错（运行时不渲染，TS 报类型错）
+const config: IConfig[] = [
+  { name: 'age', label: '年龄', inputType: 'number' },  // ← HTML 风格
+  { name: 'memo', label: '备注', inputType: 'text' },   // ← HTML 风格
+  { name: 'active', label: '激活', inputType: 'checkbox' }  // ← HTML 风格
+];
+
+// 对：PascalCase 严格枚举（IInputType union）
+const config: IConfig[] = [
+  { name: 'age', label: '年龄', inputType: 'InputNumber' },   // ← PascalCase
+  { name: 'memo', label: '备注', inputType: 'TextField' },    // ← 不是 'text'
+  { name: 'active', label: '激活', inputType: 'Switch' }      // ← 不是 'checkbox'
+  // 完整枚举：'TextField'|'Select'|'Switch'|'InputNumber'|'InputLang'|'ComboSelect'|'DatePicker'|'custom'
+];
+```
+**实证来源**：DynamicMultiBox/component.json `idealProps.config.description`，Task 15 失败根因。
+
+### ❌ 陷阱 5：泛型业务类型缺少 index signature（TS2344）
+```tsx
+// 错
+interface Param { foo: string }  // 没有 index signature
+<DynamicMultiBox<Param> config={config} valueList={valueList} />
+// TS2344: Type 'Param' does not satisfy the constraint 'Record<string, unknown>'.
+// Index signature for type 'string' is missing in type 'Param'.
+
+// 对：加 index signature
+interface Param {
+  foo: string;
+  [key: string]: unknown;  // ← 必须加，满足 T extends Record<string, unknown> 约束
+}
+// 或：type Param = { foo: string } & Record<string, unknown>
+<DynamicMultiBox<Param> config={config} valueList={valueList} />  // 编译通过
+```
+**实证来源**：DynamicMultiBox/component.json `typescriptPitfalls[5]`，Task 15 高频错误。
+
+---
+
+## 真实参考
+
+| 关键模式 | 参考位置 |
+|---------|--------|
+| 双 state 联动（valueList + errors） | DynamicMultiBox/component.json `commonPatterns.wrapperPattern` |
+| `onAdd`/`onDelete` 双参数签名 | DynamicMultiBox/component.json `commonMisconceptions.M3` |
+| `IConfig.name` narrow 写法 | DynamicMultiBox/component.json `typescriptPitfalls[0]` |
+| `as unknown as` 业务类型中转 | DynamicMultiBox/component.json `typescriptPitfalls[1]` |
+| `inputType` PascalCase 枚举 | DynamicMultiBox/component.json `typescriptPitfalls[2]` |
+| index signature 约束 | DynamicMultiBox/component.json `typescriptPitfalls[5]` |
+| `titleMode` 语义 | DynamicMultiBox/component.json `titleModeBehavior` |