@brms/ai-skills 0.1.0

package/skills/brms-vxe-plus-developer/references/vxe-plus-knowledge/01-mental-model.md

@@ -0,0 +1,150 @@
+# 01-Mental Model For AI
+
+本文件用于让 AI 快速判断页面结构和组件契约。生成代码前先按本页做分类，不要直接复制最复杂样例。
+
+## 组件分工
+
+`VxePlusForm`：独立表单渲染组件。
+
+```vue
+<VxePlusForm ref="xForm" :form-options="formOptions" />
+```
+
+`VxePlusTable`：表格、分页、查询代理、编辑、按钮、导入导出组件。
+
+```vue
+<VxePlusTable
+  id="PAGE_result"
+  ref="xGrid"
+  :columns="columns"
+  :form-config="tableFormConfig"
+  :service-config="serviceConfig"
+/>
+```
+
+关键区分：
+
+- `VxePlusForm :form-options` 用于渲染表单。
+- `VxePlusTable :form-config` 用于表格查询参数来源。
+- 两者经常共享同一个 `formData`，但 prop 名不同。
+
+## 页面类型判断
+
+标准查询页：
+
+- 一个查询 `BxContainer` + `VxePlusForm`
+- 一个结果 `BxContainer` + `VxePlusTable`
+- 查询按钮执行 `xGrid.value.reload()`
+- 重置按钮执行表单 reset，再 reload 或清空
+
+详情表单页：
+
+- 一个或多个 `VxePlusForm`
+- 保存时显式校验表单并构造 `EiInfo`
+- 不一定有 `VxePlusTable`
+
+可编辑表格页：
+
+- `VxePlusTable :is-edit="true"`
+- 有 `editRules`
+- 新增、删除、保存按钮在 `toolbarButtonClick`
+- 保存前必须校验表格
+- 复杂保存显式构造 `EiInfo`
+
+弹窗选择页：
+
+- 页面本身通常也是 `VxePlusTable`
+- 被 `formSelectDialog` 或 `tableSelectDialog` 打开
+- 必须确认 `fields` 与 `dialogFields` 一一对应
+
+复合详情页：
+
+- 多个表单、多张表格、tabs 或步骤
+- 可能通过 `provide/inject` 共享详情数据和保存方法
+- 只在当前需求确实复杂时参考，不要作为普通页面默认模板
+
+## 标准查询页骨架
+
+```vue
+<BxContainer id="INQU" title="查询条件" :form-ref="xForm" @btn-click="btnClick">
+  <VxePlusForm ref="xForm" folding :form-options="formOptions" />
+</BxContainer>
+
+<BxContainer title="查询结果">
+  <VxePlusTable
+    id="BMBR01_result"
+    ref="xGrid"
+    :columns="columns"
+    :form-config="tableFormConfig"
+    :service-config="serviceConfig"
+    :show-checkbox="true"
+    v-on="gridEvents"
+  />
+</BxContainer>
+```
+
+```ts
+const formData = reactive({})
+
+const formOptions = reactive({
+  id: 'inqu_status',
+  data: formData,
+  items: [],
+})
+
+const tableFormConfig = reactive({
+  id: 'inqu_status',
+  data: formData,
+})
+
+const serviceConfig = reactive({
+  serviceName: 'BMBR01',
+  queryMethod: 'pageQueryLike',
+})
+
+function btnClick(btn) {
+  if (btn.code === 'QUERY') {
+    xGrid.value.reload()
+  }
+  if (btn.code === 'RESET') {
+    xForm.value.getFormInstance().reset()
+    xGrid.value.reload()
+  }
+}
+```
+
+## id 与 EiInfo block
+
+`VxePlusTable` 根据 `id` 推导表格 block：
+
+```ts
+id="BMBR01_result" -> tableId = "result"
+```
+
+`VxePlusTable` 根据 `form-config.id` 推导查询条件 block：
+
+```ts
+tableFormConfig.id || 'inqu_status'
+```
+
+所以后端返回 block、表格 id、`transformResponse` 必须一致。请求细节读 [05-request-and-eiinfo.md](./05-request-and-eiinfo.md)。
+
+## 配置拆分
+
+业务页常见拆分：
+
+- `.vue`：页面流程、按钮事件、请求动作、路由跳转
+- `formConfig.ts`：表单字段配置
+- `columns.ts`：表格列配置、编辑规则
+
+新生成代码可以拆分，但不要为了拆分而新增不必要 helper。AI 优先保留当前模块已有组织方式。
+
+## 数据对象
+
+常见三类数据：
+
+- 表单显示数据：`formOptions.data`
+- 表格查询数据：`tableFormConfig.data`
+- 表格行数据：`xGrid.value.getGridInstance().getTableData().tableData`
+
+查询页通常让 `formOptions.data` 和 `tableFormConfig.data` 指向同一个 `formData`。

package/skills/brms-vxe-plus-developer/references/vxe-plus-knowledge/02-vxe-plus-form.md

@@ -0,0 +1,302 @@
+# 02-VxePlusForm
+
+本文件只记录 AI 可以稳定复制的 `VxePlusForm` 契约。不要把业务侧 `useForm()` helper 当成推荐写法；它是历史代码里的二次封装，AI 新生成页面时继续套一层会更容易混淆属性名和请求形态。
+
+## 推荐生成形态
+
+```vue
+<VxePlusForm
+  id="inqu_status"
+  ref="xForm"
+  folding
+  :form-options="formOptions"
+/>
+```
+
+```ts
+const formData = reactive({
+  formulaCode: '',
+  formulaName: '',
+  createdTimeStart: '',
+  createdTimeEnd: '',
+})
+
+const formOptions = reactive({
+  id: 'inqu_status',
+  data: formData,
+  titleWidth: 120,
+  rules: {
+    formulaCode: [{ required: true, message: '请输入价格公式编号' }],
+  },
+  items: [
+    { field: 'formulaCode', title: '价格公式编号', itemRender: { name: 'VxeInput' } },
+    { field: 'formulaName', title: '价格公式名称', itemRender: { name: 'VxeInput' } },
+    {
+      field: 'createdTime',
+      title: '创建日期',
+      itemRender: {
+        name: 'dateRange',
+        props: {
+          startDate: 'createdTimeStart',
+          endDate: 'createdTimeEnd',
+        },
+      },
+    },
+  ],
+})
+```
+
+## 可复制字段渲染器
+
+直接写 `itemRender`，不要为了少写几行再封装 helper。
+
+```ts
+{ field: 'name', title: '名称', itemRender: { name: 'VxeInput' } }
+{ field: 'remark', title: '备注', itemRender: { name: 'VxeTextarea' } }
+{ field: 'enabled', title: '是否启用', itemRender: { name: 'VxeCheckbox' } }
+```
+
+字典下拉：
+
+```ts
+{
+  field: 'formulaStatus',
+  title: '状态',
+  itemRender: {
+    name: 'formSelect',
+    props: {
+      codeSet: 'BRMERP.bm.formulaStatus',
+      clearable: true,
+    },
+  },
+}
+```
+
+接口字典：
+
+```ts
+import { getCodeSetByService } from '@/utils/eiTools'
+
+{
+  field: 'orgId',
+  title: '所属账套',
+  itemRender: {
+    name: 'formSelect',
+    props: {
+      codeSet: 'BMBE0000.queryBookOrgByListByPurOrg',
+      promiseFn: params => getCodeSetByService({
+        serviceName: 'BMBE0000',
+        methodName: 'queryBookOrgByListByPurOrg',
+        params,
+        blockName: 'bookResult',
+        value: 'orgId',
+        label: 'bookAndOrgDeptName',
+      }),
+      backfillFields: 'bookId,groupId,deptId,companyId',
+    },
+  },
+}
+```
+
+日期范围：
+
+```ts
+{
+  field: 'createdTime',
+  title: '创建日期',
+  itemRender: {
+    name: 'dateRange',
+    props: {
+      startDate: 'createdTimeStart',
+      endDate: 'createdTimeEnd',
+    },
+  },
+}
+```
+
+## VxeDatePicker month valueFormat 限制
+
+`VxeDatePicker` 在 `type: 'month'` 模式下，不要使用 `valueFormat: 'MM'`。
+
+错误配置：
+
+```ts
+{
+  field: 'expiryMonth',
+  title: '到期月份',
+  itemRender: {
+    name: 'VxeDatePicker',
+    props: {
+      type: 'month',
+      valueFormat: 'MM',
+      clearable: true,
+    },
+  },
+}
+```
+
+现象：选择月份后 modelValue 会变成 `"06"` 这类纯月份字符串，但输入框无法回显，面板也无法正确高亮选中月份。
+
+根因：`vxe-pc-ui` 底层依赖 `xe-utils` 解析日期。格式化方向可以把 Date 格式化成纯月份：
+
+```ts
+xeUtils.toDateString(new Date(2026, 5, 15), 'MM') // "06"
+```
+
+但解析方向无法从纯月份字符串还原 Date：
+
+```ts
+xeUtils.toStringDate('06', 'MM') // Invalid Date
+```
+
+`valueFormat` 会影响 modelValue、回显解析和面板选中匹配，所以它必须包含足够的日期信息。任何不包含年份的格式，例如 `MM`、`dd`，都不要作为 `valueFormat` 使用。
+
+正确配置：用 `valueFormat` 存储可解析值，用 `labelFormat` 控制 UI 显示。
+
+```ts
+{
+  field: 'expiryMonth',
+  title: '到期月份',
+  itemRender: {
+    name: 'VxeDatePicker',
+    props: {
+      type: 'month',
+      valueFormat: 'yyyy-MM',
+      labelFormat: 'MM',
+      clearable: true,
+    },
+  },
+}
+```
+
+分工：
+
+- `valueFormat`：控制 modelValue 格式，影响存储值、回显解析、面板选中匹配。
+- `labelFormat`：控制输入框显示文本，只影响 UI 展示。
+
+弹窗选择：
+
+```ts
+{
+  field: 'customerName',
+  title: '客户名称',
+  itemRender: {
+    name: 'formSelectDialog',
+    props: {
+      component: UMUC9902,
+      fields: 'customerName',
+      dialogFields: 'corpName',
+      componentParam: {
+        param: {
+          corpType: 'CUSTOMER',
+        },
+      },
+    },
+  },
+}
+```
+
+`fields` 是当前表单字段，`dialogFields` 是弹窗选中行字段，多个字段用逗号并保持一一对应。
+
+## 显隐、禁用、事件
+
+显隐写在 item 上：
+
+```ts
+{
+  field: 'otherReason',
+  title: '其他原因',
+  visibleMethod: ({ data }) => data.reasonType === 'OTHER',
+  itemRender: { name: 'VxeInput' },
+}
+```
+
+禁用写在渲染器 props 上：
+
+```ts
+{
+  field: 'outstockType',
+  title: '出库单类型',
+  itemRender: {
+    name: 'formSelect',
+    props: {
+      codeSet: 'brmerp.sm.outstockType',
+      disabled: true,
+      readonly: true,
+    },
+  },
+}
+```
+
+字段事件直接挂 `itemRender.events`：
+
+```ts
+{
+  field: 'qty',
+  title: '只看可出库',
+  itemRender: {
+    name: 'VxeCheckbox',
+    events: {
+      change({ data }) {
+        data.qtyButton = data.qty ? 'Y' : 'N'
+      },
+    },
+  },
+}
+```
+
+## 校验
+
+简单校验放在 `formOptions.rules`。
+
+```ts
+const formOptions = reactive({
+  id: 'inqu_status',
+  data: formData,
+  rules: {
+    outstockType: [{ required: true, message: '请选择出库单类型' }],
+  },
+  items,
+})
+```
+
+提交前用组件实例校验：
+
+```ts
+await xForm.value.getFormInstance().validate()
+```
+
+字段必填校验必须写在 `formOptions.rules`，按字段名配置。不要把 `required: true` 写在 `items` 中，也不要用 `titlePrefix: { content: '必填' }` 代替校验；这些写法不会稳定触发表单校验。
+字段级异步校验优先寻找同模块已有 `rules` 写法，不要凭空发明规则结构。
+
+## 数据读取原则
+
+请求查询时，`VxePlusTable` 会读取 `:form-config="{ id, data }"` 里的 `data` 并组装为 EiInfo。不要为查询再手工遍历表单字段。
+
+保存详情表单时，如果页面只需要提交可见字段，可以按 `formOptions.items` 白名单提取；如果后端需要完整详情对象，就提交完整 `formData`。不要无条件提交整份 `formData`，也不要无条件只提交可见字段，先看当前业务接口契约。
+
+历史代码里的 `getFormData(baseFields, formData)` 可以帮助识别旧页面意图，但新生成代码不要把 `useForm().getFormData` 当标准依赖引入。
+
+## 插槽
+
+字段默认插槽常用 `${field}_default`，标题插槽常用 `${field}_title`。
+
+```vue
+<VxePlusForm :form-options="formOptions">
+  <template #fileCount_default="{ data }">
+    <el-button type="primary" @click="handleUpload(data)">
+      附件管理
+    </el-button>
+  </template>
+</VxePlusForm>
+```
+
+## 历史 helper 识别规则
+
+如果编辑的既有文件已经大量使用 `useForm()`，可以局部沿用以减少改动，但不要把它作为新文件样板扩散。遇到 helper 时按含义还原为直接配置：
+
+- `commonVxeInput()` -> `{ name: 'VxeInput' }`
+- `commonVxeTextarea()` -> `{ name: 'VxeTextarea' }`
+- `commonFormSelect(codeSet)` -> `{ name: 'formSelect', props: { codeSet } }`
+- `commonDateRange(start, end)` -> `{ name: 'dateRange', props: { startDate: start, endDate: end } }`
+- `commonSelectDialog(...)` -> `{ name: 'formSelectDialog', props: ... }`

package/skills/brms-vxe-plus-developer/references/vxe-plus-knowledge/03-vxe-plus-table.md

@@ -0,0 +1,253 @@
+# 03-VxePlusTable
+
+本文件记录 AI 生成 `VxePlusTable` 时可复制的稳定契约。请求细节见 [05-request-and-eiinfo.md](./05-request-and-eiinfo.md)。
+
+## 推荐生成形态
+
+```vue
+<VxePlusTable
+  id="BMBR01_result"
+  ref="xGrid"
+  :columns="columns"
+  :form-config="tableFormConfig"
+  :service-config="serviceConfig"
+  :show-checkbox="true"
+  :transform-params="transformParams"
+  :transform-response="transformResponse"
+  v-on="gridEvents"
+/>
+```
+
+```ts
+const tableFormConfig = reactive({
+  id: 'inqu_status',
+  data: formData,
+})
+
+const serviceConfig = reactive({
+  serviceName: 'BMBR01',
+  queryMethod: 'pageQueryLike',
+})
+```
+
+`id="BMBR01_result"` 中下划线后的 `result` 是表格数据 block 名；组件内部会用它读取响应 `res.getBlock('result')`。
+
+## 列配置
+
+可以直接写列数组；如果既有文件已经使用 `useTable().createColumns()`，局部沿用即可，但新文件不要为了生成列再新增一层二次封装。
+
+```ts
+const columns = reactive([
+  { field: 'formulaCode', title: '价格公式编号', minWidth: 140 },
+  { field: 'formulaName', title: '价格公式名称', minWidth: 160, showOverflow: true },
+  {
+    field: 'formulaStatus',
+    title: '状态',
+    editRender: {
+      name: 'tableSelect',
+      enabled: false,
+      props: {
+        codeSet: 'BRMERP.bm.formulaStatus',
+      },
+    },
+  },
+])
+```
+
+只展示字典文本但不允许编辑时，`editRender.enabled` 设为 `false`。
+
+## 可编辑列
+
+```ts
+{
+  field: 'toBeAdd',
+  title: '待添加量',
+  align: 'right',
+  headerAlign: 'center',
+  editRender: { name: 'VxeInput' },
+}
+```
+
+表格下拉：
+
+```ts
+{
+  field: 'teamCode',
+  title: '创业团队',
+  editRender: {
+    name: 'tableSelect',
+    props: {
+      codeSet: 'BMBF3002.queryTeam',
+      promiseFn: params => getCodeSetByService({
+        serviceName: 'BMBF3002',
+        methodName: 'queryTeam',
+        params,
+        blockName: 'result',
+        value: 'teamCode',
+        label: 'teamName',
+      }),
+      backfillFields: 'teamName',
+      clearable: true,
+      filterable: true,
+    },
+  },
+}
+```
+
+表格弹窗选择：
+
+```ts
+{
+  field: 'feeTypeName',
+  title: '费用类型',
+  editRender: {
+    name: 'tableSelectDialog',
+    props: {
+      component: FeeTypeDialog,
+      fields: 'feeTypeName,cgFeeTypeCode',
+      dialogFields: 'estimationFeeTypeName,ceEstimationFeeTypeCode',
+    },
+  },
+}
+```
+
+## 编辑校验
+
+简单校验可直接写 `editRules`：
+
+```ts
+const editRules = reactive({
+  toBeAdd: [{ required: true, message: '填写量必填' }],
+})
+```
+
+```vue
+<VxePlusTable
+  :columns="columns"
+  :is-edit="true"
+  :edit-rules="editRules"
+/>
+```
+
+保存前优先使用底层 grid 校验或当前页面已有校验函数。生成代码前先检索同模块 `editRules`、`validate`、`fullValidate`、`validator` 的既有写法。
+
+## 按钮事件
+
+业务按钮常通过 `v-on="gridEvents"` 接收。
+
+```ts
+const gridEvents = reactive({
+  toolbarButtonClick: async ({ code, $grid }) => {
+    switch (code) {
+      case 'ADD':
+        await handleAdd($grid)
+        break
+      case 'SAVE':
+        await handleSave()
+        break
+      case 'DELETE':
+        await handleDelete($grid)
+        break
+    }
+  },
+})
+```
+
+手工按钮：
+
+```ts
+const toolbarButtons = ref([
+  { name: '新增', code: 'ADD' },
+  { name: '保存', code: 'SAVE', status: 'success' },
+  { name: '删除', code: 'DELETE', status: 'danger' },
+])
+```
+
+按钮控制：
+
+```ts
+xGrid.value.btnSetDisable(['ADD', 'DELETE'], true)
+xGrid.value.btnSetVisible(['VIEW_DETAIL'], false)
+```
+
+## 新增、删除、保存
+
+新增行：
+
+```ts
+const $grid = xGrid.value.getGridInstance()
+const { row } = await $grid.insertAt({ id: '' }, -1)
+await $grid.setEditRow(row)
+```
+
+删除未保存行：
+
+```ts
+const $grid = xGrid.value.getGridInstance()
+const records = $grid.getCheckboxRecords()
+if (!records.length) {
+  ElMessage.warning('请选择数据')
+  return
+}
+await $grid.removeCheckboxRow()
+```
+
+复杂保存不要盲目依赖 `commitProxy('save')`。当前组件内部 proxy save 主要处理 insertRecords，update/delete 分支并不完整。涉及新增、修改、删除混合提交时，优先显式构造 `EiInfo` 并调用 `EiCommunicator.send`。
+
+## 查询刷新
+
+```ts
+xGrid.value.reload()
+```
+
+或底层：
+
+```ts
+xGrid.value.getGridInstance().commitProxy('query')
+```
+
+`reload()` 会触发表格请求，参数来自 `:form-config` 的 `data`，再经过 `transformParams`。
+
+## 插槽
+
+列默认插槽：
+
+```vue
+<template #formulaCode_default="{ row }">
+  <el-link type="primary" @click="openDetail(row)">
+    {{ row.formulaCode }}
+  </el-link>
+</template>
+```
+
+如果列配置统一注入 slot：
+
+```ts
+columns.forEach((column) => {
+  column.slots = {
+    ...column.slots,
+    default: `${column.field}_default`,
+  }
+})
+```
+
+表头插槽：
+
+```vue
+<template #goodsCode_header="{ column }">
+  <span class="vxe-cell--required-icon"><i /></span>
+  <span>{{ column.title }}</span>
+</template>
+```
+
+## 导入导出
+
+```vue
+<VxePlusTable
+  :is-import="true"
+  :is-export-template="true"
+  :export-config="{ fileName: '导入模板' }"
+/>
+```
+
+导入导出依赖列配置，生成时必须确认隐藏列、必填列、字典列是否需要出现在模板里。