@brms/ai-skills 0.1.0

package/skills/brms-vxe-plus-developer/references/vxe-plus-knowledge/04-example-map.md

@@ -0,0 +1,488 @@
+# 04-Embedded Examples
+
+本文件是给 AI 直接复制和改造的场景样例库。每个样例都尽量自包含；“来源”只用于回到工程中核对，不是使用本文档的必要条件。
+
+## 标准查询页
+
+适用：查询条件 + 查询结果表格，最常见页面。
+
+```vue
+<template>
+  <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>
+</template>
+
+<script setup lang="ts">
+import { nextTick, reactive, ref } from 'vue'
+
+const xForm = ref<any>()
+const xGrid = ref<any>()
+
+const formData = reactive({
+  formulaCode: '',
+  formulaName: '',
+  formulaStatus: '',
+})
+
+const formOptions = reactive({
+  id: 'inqu_status',
+  data: formData,
+  titleWidth: 120,
+  items: [
+    { field: 'formulaCode', title: '价格公式编号', itemRender: { name: 'VxeInput' } },
+    { field: 'formulaName', title: '价格公式名称', itemRender: { name: 'VxeInput' } },
+    {
+      field: 'formulaStatus',
+      title: '状态',
+      itemRender: {
+        name: 'formSelect',
+        props: {
+          codeSet: 'BRMERP.bm.formulaStatus',
+          clearable: true,
+        },
+      },
+    },
+  ],
+})
+
+const tableFormConfig = reactive({
+  id: 'inqu_status',
+  data: formData,
+})
+
+const serviceConfig = reactive({
+  serviceName: 'BMBR01',
+  queryMethod: 'pageQueryLike',
+})
+
+const columns = reactive([
+  { field: 'formulaCode', title: '价格公式编号', minWidth: 140 },
+  { field: 'formulaName', title: '价格公式名称', minWidth: 180, showOverflow: true },
+  {
+    field: 'formulaStatus',
+    title: '状态',
+    editRender: {
+      name: 'tableSelect',
+      enabled: false,
+      props: { codeSet: 'BRMERP.bm.formulaStatus' },
+    },
+  },
+])
+
+const gridEvents = reactive({
+  toolbarButtonClick: ({ code, row }) => {
+    if (code === 'VIEW') {
+      openDetail(row)
+    }
+  },
+})
+
+function btnClick(btn: { code: string }) {
+  if (btn.code === 'QUERY') {
+    xGrid.value.reload()
+  }
+  if (btn.code === 'RESET') {
+    xForm.value.getFormInstance().reset()
+    nextTick(() => xGrid.value.reload())
+  }
+}
+
+function openDetail(row: any) {
+  console.log(row)
+}
+</script>
+```
+
+来源：`project/base/src/views/BM/BR/BMBR01.vue`。注意：真实来源里可能有历史 helper，新代码优先使用上面的直接 `itemRender` 写法。
+
+## 查询参数补充与响应转换
+
+适用：查询参数不只来自表单字段，还要额外传 attr、业务类型、路由参数；响应行需要转换。
+
+```vue
+<VxePlusTable
+  id="SMSW0101_result"
+  ref="xGrid"
+  :columns="columns"
+  :form-config="tableFormConfig"
+  :service-config="serviceConfig"
+  :transform-params="transformParams"
+  :transform-response="transformResponse"
+/>
+```
+
+```ts
+import type { EiInfo } from '@eplat/ei'
+
+const formData = reactive({
+  orgId: '',
+  goodsName: '',
+  qty: true,
+  qtyButton: 'Y',
+})
+
+const tableFormConfig = reactive({
+  id: 'inqu_status',
+  data: formData,
+})
+
+const serviceConfig = reactive({
+  serviceName: 'SMSW0101',
+  queryMethod: 'query',
+})
+
+function transformParams(formEi: EiInfo) {
+  formEi.setAttr({
+    qtyButton: formData.qtyButton,
+  })
+  formEi.set('inqu_status-0-businessType', 'SW_OUTSTOCK')
+  return formEi
+}
+
+function transformResponse(rows: any[]) {
+  return rows.map(row => ({
+    ...row,
+    h2oValueBase: Number(row.h2oValueBase || 0) * 100,
+  }))
+}
+```
+
+来源：`project/base/src/views/SM/SW/SMSW0101.vue`。关键点：`transformParams` 修改传入的 `formEi`，不要重新 new 空 EiInfo。
+
+## 接口字典下拉
+
+适用：字典选项不是固定 codeset，而是通过服务查询。
+
+```ts
+import { getCodeSetByService } from '@/utils/eiTools'
+
+const formOptions = reactive({
+  id: 'inqu_status',
+  data: formData,
+  items: [
+    {
+      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',
+          clearable: true,
+          filterable: true,
+        },
+      },
+    },
+  ],
+  rules: {
+    orgId: [{ required: true, message: '请选择所属账套' }],
+  },
+})
+```
+
+表格列里同样可以用 `tableSelect`：
+
+```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',
+    },
+  },
+}
+```
+
+来源：`project/base/src/views/SM/SW/SMSW0101.vue`。
+
+## 表单弹窗选择
+
+适用：表单字段通过弹窗选中一行后回填。
+
+```ts
+import CustomerDialog from '@/views/UM/UC/UMUC9902.vue'
+
+{
+  field: 'customerName',
+  title: '客户名称',
+  itemRender: {
+    name: 'formSelectDialog',
+    props: {
+      component: CustomerDialog,
+      fields: 'customerName,customerCode',
+      dialogFields: 'corpName,corpCode',
+      componentParam: {
+        param: {
+          corpType: 'CUSTOMER',
+        },
+      },
+    },
+  },
+}
+```
+
+规则：
+
+- `fields` 是当前表单要被回填的字段。
+- `dialogFields` 是弹窗选中行中的字段。
+- 两边数量和顺序必须一致。
+- 字段不确定时，先查看弹窗组件返回行结构。
+
+来源：`project/base/src/views/SM/SW/SMSW0101.vue`、`project/base/src/views/AM/AF/component/AMAF0601/Bidding/formConfig.ts`。
+
+## 表格弹窗选择
+
+适用：可编辑表格某一列通过弹窗回填多个字段。
+
+```ts
+import FeeTypeDialog from './FeeTypeDialog.vue'
+
+const columns = reactive([
+  {
+    field: 'feeTypeName',
+    title: '费用类型',
+    editRender: {
+      name: 'tableSelectDialog',
+      props: {
+        component: FeeTypeDialog,
+        fields: 'feeTypeName,cgFeeTypeCode',
+        dialogFields: 'estimationFeeTypeName,ceEstimationFeeTypeCode',
+      },
+    },
+  },
+])
+```
+
+来源：`project/base/src/views/AM/AF/component/AMAF0601/Record/columns.ts`。
+
+## 可编辑表格新增、删除、保存
+
+适用：表格支持行编辑，保存时统一提交表格数据。
+
+```vue
+<VxePlusTable
+  id="A1P01601_result"
+  ref="xGrid"
+  :columns="columns"
+  :form-config="tableFormConfig"
+  :service-config="serviceConfig"
+  :is-edit="true"
+  :edit-rules="editRules"
+  :toolbar-buttons="toolbarButtons"
+  v-on="gridEvents"
+/>
+```
+
+```ts
+import { EiBlock, EiCommunicator, EiInfo } from '@eplat/ei'
+import { ElMessage } from 'element-plus'
+
+const xGrid = ref<any>()
+
+const toolbarButtons = ref([
+  { name: '新增', code: 'ADD' },
+  { name: '保存', code: 'SAVE', status: 'success' },
+  { name: '删除', code: 'DELETE', status: 'danger' },
+])
+
+const editRules = reactive({
+  itemName: [{ required: true, message: '名称必填' }],
+  itemValue: [{ required: true, message: '值必填' }],
+})
+
+const columns = reactive([
+  { field: 'itemName', title: '名称', editRender: { name: 'VxeInput' } },
+  { field: 'itemValue', title: '值', editRender: { name: 'VxeInput' } },
+])
+
+const gridEvents = reactive({
+  toolbarButtonClick: async ({ code, $grid }) => {
+    if (code === 'ADD') {
+      const { row } = await $grid.insertAt({ id: '' }, -1)
+      await $grid.setEditRow(row)
+    }
+
+    if (code === 'DELETE') {
+      const rows = $grid.getCheckboxRecords()
+      if (!rows.length) {
+        ElMessage.warning('请选择数据')
+        return
+      }
+      await $grid.removeCheckboxRow()
+    }
+
+    if (code === 'SAVE') {
+      await handleSave()
+    }
+  },
+})
+
+async function handleSave() {
+  const $grid = xGrid.value.getGridInstance()
+  await $grid.fullValidate()
+  const { tableData } = $grid.getTableData()
+
+  const ei = new EiInfo()
+  ei.addBlock(EiBlock.build('result', tableData))
+  await EiCommunicator.send('A1P01601', 'save', ei)
+  xGrid.value.reload()
+}
+```
+
+来源：`project/base/src/views/A1/P0/A1P01601.vue`。注意：真实接口可能要求新增、修改、删除分 block，必须按接口调整。
+
+## 选中行确认提交
+
+适用：表格勾选若干行，附加表单信息后调用确认接口。
+
+```ts
+import { EiBlock, EiCommunicator, EiInfo } from '@eplat/ei'
+import { ElMessage, ElMessageBox } from 'element-plus'
+
+async function handleConfirm() {
+  const checkboxRecords = xGrid.value?.getCheckboxRecords()
+  const resultBlock = checkboxRecords?.getBlock?.('result')
+
+  if (!resultBlock || resultBlock.rows.length === 0) {
+    ElMessage.error('请选择要确认的记录')
+    return
+  }
+
+  if (!formData.warehouseName) {
+    ElMessage.error('请选择仓库信息')
+    return
+  }
+
+  checkboxRecords.addBlock(EiBlock.build('inqu', [formData]))
+
+  await ElMessageBox.confirm('确定要执行确认操作吗？')
+  await EiCommunicator.send('SMSW0101', 'confirm', checkboxRecords)
+  xGrid.value.reload()
+}
+```
+
+如果 `getCheckboxRecords()` 返回普通数组，则改为：
+
+```ts
+const rows = xGrid.value.getGridInstance().getCheckboxRecords()
+const ei = new EiInfo()
+ei.addBlock(EiBlock.build('result', rows))
+ei.addBlock(EiBlock.build('inqu', [formData]))
+await EiCommunicator.send('SMSW0101', 'confirm', ei)
+```
+
+来源：`project/base/src/views/SM/SW/SMSW0101.vue`。
+
+## 条件显隐与联动
+
+适用：某个字段根据其他字段显示，或字段变化时更新辅助参数。
+
+```ts
+const formData = reactive({
+  reasonType: '',
+  otherReason: '',
+  qty: true,
+  qtyButton: 'Y',
+})
+
+const formOptions = reactive({
+  id: 'inqu_status',
+  data: formData,
+  items: [
+    {
+      field: 'reasonType',
+      title: '原因类型',
+      itemRender: {
+        name: 'formSelect',
+        props: { codeSet: 'brmerp.demo.reasonType' },
+      },
+    },
+    {
+      field: 'otherReason',
+      title: '其他原因',
+      visibleMethod: ({ data }) => data.reasonType === 'OTHER',
+      itemRender: { name: 'VxeInput' },
+    },
+    {
+      field: 'qty',
+      title: '只看可出库',
+      itemRender: {
+        name: 'VxeCheckbox',
+        events: {
+          change({ data }) {
+            data.qtyButton = data.qty ? 'Y' : 'N'
+          },
+        },
+      },
+    },
+  ],
+})
+```
+
+来源：`project/base/src/views/SM/SW/SMSW0101.vue`、`project/base/src/views/AM/AF/component/AMAF0601/Bidding/formConfig.ts`。
+
+## 复杂页面参考原则
+
+后端驱动表单/表格、复合详情页、多 tab 多表格页面不要作为默认模板。AI 只有在需求明确包含“动态字段”“动态列”“详情总线”“多子模块保存”时才参考这些模式。
+
+最小可复制骨架：
+
+```ts
+provide('__DETAIL_METHODS__', {
+  getData,
+  validate,
+  saveDetail,
+  reloadDetail,
+})
+
+const detailInfo = ref({})
+
+async function reloadDetail() {
+  const ei = new EiInfo()
+  ei.set('inqu_status-0-id', route.query.id)
+  const res = await EiCommunicator.send('DETAIL01', 'detail', ei)
+  detailInfo.value = res.getBlock('result')?.getMappedRows()?.[0] || {}
+}
+```
+
+来源：`project/base/src/views/A1/P1/A1P11011.vue`、`project/base/src/views/PM/PC/component/PMPC0101/`、`project/base/src/views/AB/BP/ABBP0201.vue`。
+
+## Demo 使用边界
+
+`project/base/src/views/demo/index.vue` 适合查组件能力，例如导入导出、renderer 名称、特殊 props。它不是业务页面最佳实践。

package/skills/brms-vxe-plus-developer/references/vxe-plus-knowledge/05-request-and-eiinfo.md

@@ -0,0 +1,170 @@
+# 05-Requests And EiInfo
+
+AI 写 `VxePlusTable` 页面时，必须先确认请求形态。这个项目主流后端通信不是普通 REST，而是 `@eplat/ei` 的 `EiInfo` / `EiBlock`。
+
+## 表格查询默认链路
+
+```vue
+<VxePlusTable
+  id="SMSW0101_result"
+  :form-config="tableFormConfig"
+  :service-config="serviceConfig"
+  :transform-params="transformParams"
+  :transform-response="transformResponse"
+/>
+```
+
+```ts
+const tableFormConfig = reactive({
+  id: 'inqu_status',
+  data: formData,
+})
+
+const serviceConfig = reactive({
+  serviceName: 'SMSW0101',
+  queryMethod: 'query',
+})
+```
+
+组件内部 `useTableData` 的关键推导：
+
+- `tableId = id.split('_').slice(1).join('_')`，例如 `SMSW0101_result` -> `result`。
+- `formId = formConfig.id || 'inqu_status'`。
+- 查询时把 `formConfig.data` 写入 EiInfo，内部等价于：
+
+```ts
+formEi.set(`${formId}-0-${key}`, value)
+```
+- 分页和排序写入 `EiBlock(tableId).attr`，包含 `currentPage/pageSize` 或 `offset/limit`，以及 `orderBy`。
+- 表头筛选会覆盖同名表单字段，并额外构造 `${tableId}_filter` block。
+- 请求调用：`EiCommunicator.send(serviceName, queryMethod || 'query', requestFormEi)`。
+- 响应读取：`res.getBlock(tableId).getMappedRows()`。
+- 总数读取：`res.getBlock(tableId).getAttr().count`。
+
+## transformParams
+
+`transformParams` 接收到的是已经按默认规则组装好的 `EiInfo`。只在这里补充额外 attr、block 或特殊字段。
+
+```ts
+import type { EiInfo } from '@eplat/ei'
+
+function transformParams(formEi: EiInfo) {
+  formEi.setAttr({
+    qtyButton: formData.qtyButton,
+  })
+  formEi.set('inqu_status-0-businessType', 'SW_OUTSTOCK')
+  return formEi
+}
+```
+
+需要新增 block：
+
+```ts
+import { EiBlock } from '@eplat/ei'
+
+function transformParams(formEi: EiInfo) {
+  formEi.addBlock(EiBlock.build('extra', [{
+    projectId: route.query.projectId,
+  }]))
+  return formEi
+}
+```
+
+不要在 `transformParams` 里重新 new 一个空 EiInfo，除非你明确要丢弃组件默认组装的表单、分页、排序和筛选。
+
+## transformResponse
+
+`serviceConfig` 路径下，`transformResponse` 收到的是 `tableId` block 的 mapped rows 数组。
+
+```ts
+function transformResponse(rows) {
+  return rows.map(row => ({
+    ...row,
+    h2oValueBase: Number(row.h2oValueBase || 0) * 100,
+  }))
+}
+```
+
+不要在这里再 `res.getBlock()`，因为此时通常已经不是完整 `EiInfo`。
+
+## 手工查询
+
+不通过表格代理时，显式构造 EiInfo。
+
+```ts
+import { EiCommunicator, EiInfo } from '@eplat/ei'
+
+const ei = new EiInfo()
+ei.set('inqu_status-0-formulaCode', formData.formulaCode)
+const res = await EiCommunicator.send('BMBR01', 'query', ei)
+const rows = res.getBlock('result')?.getMappedRows() || []
+```
+
+有 block 数据：
+
+```ts
+import { EiBlock, EiCommunicator, EiInfo } from '@eplat/ei'
+
+const ei = new EiInfo()
+ei.addBlock(EiBlock.build('result', rows))
+ei.addBlock(EiBlock.build('inqu', [formData]))
+await EiCommunicator.send('SMSW0101', 'confirm', ei)
+```
+
+## 选中行提交
+
+有些 `VxePlusTable` 暴露方法可能直接返回 EiInfo 或封装后的 block 数据。复制前必须看当前页面真实写法，不要假设一定是普通数组。
+
+常见形态：
+
+```ts
+const checkboxRecords = xGrid.value?.getCheckboxRecords()
+checkboxRecords.addBlock(EiBlock.build('inqu', [formData]))
+await EiCommunicator.send('SMSW0101', 'confirm', checkboxRecords)
+```
+
+如果底层 `$grid.getCheckboxRecords()` 返回普通数组，则需要自己 build block：
+
+```ts
+const $grid = xGrid.value.getGridInstance()
+const rows = $grid.getCheckboxRecords()
+const ei = new EiInfo()
+ei.addBlock(EiBlock.build('result', rows))
+await EiCommunicator.send(serviceName, methodName, ei)
+```
+
+## 保存提交
+
+简单新增可以考虑表格代理保存，但生成代码前必须核对组件源码和当前页面。当前 `useTableData` 的 proxy save 主要把 `insertRecords` build 到 `tableId` block，再调用 `insertMethod || 'insert'`，update/delete 逻辑没有完整实现。
+
+复杂保存推荐显式写：
+
+```ts
+const $grid = xGrid.value.getGridInstance()
+await $grid.fullValidate()
+const { tableData } = $grid.getTableData()
+
+const ei = new EiInfo()
+ei.addBlock(EiBlock.build('result', tableData))
+ei.addBlock(EiBlock.build('inqu_status', [formData]))
+await EiCommunicator.send('A1P01601', 'save', ei)
+xGrid.value.reload()
+```
+
+如果后端要求新增、修改、删除分别放不同 block，就按接口要求命名，不要为了兼容猜测多个 block。
+
+## block 命名规则
+
+常见但不是绝对：
+
+- 查询条件：`inqu_status`
+- 业务表单：`inqu`
+- 表格结果：`result`
+- 表格过滤：`${tableId}_filter`
+- 表格自身分页 attr block：`tableId`，例如 `result`
+
+优先级：接口文档或同服务真实页面 > 当前模块相邻页面 > 组件默认约定。
+
+## 直接 HTTP
+
+项目里也存在 `http.get`、`http.post`、`http.form`，但 `VxePlusTable` 主路径是 EiInfo。只有当前模块已有 REST 写法，或接口明确是 REST 时，才用普通 HTTP。