@brms/ai-skills 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brms/ai-skills",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Shared BRMS AI skills and project sync tooling.",
   "type": "module",
   "bin": {

package/skills/brms-vxe-plus-developer/SKILL.md

@@ -41,6 +41,8 @@ Then load only the needed knowledge files:
 - `03-vxe-plus-table.md`: `VxePlusTable`, columns, editable grids, toolbar buttons.
 - `04-example-map.md`: embedded code examples and offline `sources/project/base/src/views` examples.
 - `05-request-and-eiinfo.md`: EiInfo query/save/transform rules.
+- `06-eiinfo-data-format.md`: raw EiInfo JSON shape; use it for `__blocks__`, `rows` mapping, `attr.count`, and `__sys__` errors.
+- `07-development-tips.md`: approval-detail flag, dynamic button visibility, and cross-page refresh patterns.
 - `90-anti-patterns.md`: final hard-stop checks.
 
 If the business project also has `doc/components/vxe-plus-knowledge`, use it as a project-local supplement. If it is missing, use local docs such as `doc/vibeCoding/README.md`, `libs/components/src`, and neighboring pages under the confirmed `project/*/src/views` as supplement.
@@ -93,8 +95,11 @@ Do not load every source example by default. Search within the confirmed project
 - New generated real pages should not import `useForm()` solely to get helper renderers.
 - `VxeDatePicker type="month"` must not use `valueFormat: 'MM'`; use `valueFormat: 'yyyy-MM'` plus `labelFormat: 'MM'`.
 - Table actions belong in `toolbarButtons` / `toolbarButtonClick` unless the existing page has a clear different pattern.
+- For approval-detail, button visibility, and cross-page refresh behavior, prefer existing project patterns: `__approveFlag__`, `btnSetVisible`, and `pageRefreshStore`.
 - Do not add operation/action columns by default.
 - Do not generate REST `http.*` calls when the interface is EiInfo.
+- EiInfo response business data is read from `__blocks__` through `getBlock(blockName)?.getMappedRows()`; errors/status come from `__sys__` or `getStatus()` / `getMsg()`.
+- For EiInfo request construction, do not mix `set()` path writes and `EiBlock.build()` / `addBlock()` on the same `EiInfo` instance.
 - Do not add compatibility code for old data unless explicitly requested.
 - For attachment upload/view, use the shared project flow such as `useFileUpload().openFileBFSS0001` when available.
 

package/skills/brms-vxe-plus-developer/references/resource-index.md

@@ -20,6 +20,8 @@ Load only the reference needed for the current task.
 - `references/vxe-plus-knowledge/03-vxe-plus-table.md`: table columns, edit mode, toolbar buttons, slots.
 - `references/vxe-plus-knowledge/04-example-map.md`: embedded examples for direct copying and adaptation.
 - `references/vxe-plus-knowledge/05-request-and-eiinfo.md`: EiInfo query/save/transform behavior.
+- `references/vxe-plus-knowledge/06-eiinfo-data-format.md`: raw EiInfo JSON shape, `__blocks__` data mapping, and `__sys__` error fields.
+- `references/vxe-plus-knowledge/07-development-tips.md`: approval-detail flag, button visibility, and cross-page refresh patterns.
 - `references/vxe-plus-knowledge/90-anti-patterns.md`: hard-stop mistakes.
 
 ## Offline Source Examples
@@ -41,3 +43,7 @@ Use focused search terms:
 - `toolbarButtonClick`
 - `EiCommunicator.send`
 - `valueFormat`
+- `__approveFlag__`
+- `btnSetVisible`
+- `setRefreshFlag`
+- `checkRefreshFlag`

package/skills/brms-vxe-plus-developer/references/review-checklist.md

@@ -30,12 +30,15 @@ Use this reference before handing real BRMS VxePlus code to a newcomer or review
 - `transformParams` does not create a new empty EiInfo unless intentionally discarding defaults.
 - `transformResponse(rows)` expects mapped rows, not a full EiInfo, under the normal `serviceConfig` path.
 - Complex save/confirm/delete builds explicit `EiInfo` blocks matching the backend contract.
+- The same `EiInfo` instance does not mix `set()` path writes with `EiBlock.build()` / `addBlock()` construction.
+- Raw EiInfo JSON handling reads business data from `__blocks__`, maps rows through columns or `getMappedRows()`, and reads errors from `__sys__`.
 - No speculative old-data compatibility was added.
 
 ## Example And Knowledge Checks
 
 - The implementation can point to a nearby real `project/*/src/views` example or a packaged offline source under `references/vxe-plus-knowledge/sources/project/base/src/views`.
 - Any deviation from the knowledge-base pattern is explained by local module code or interface contract.
+- Approval-detail behavior, dynamic button visibility, and cross-page refresh were checked against `references/vxe-plus-knowledge/07-development-tips.md` when relevant.
 - Known anti-patterns from `references/vxe-plus-knowledge/90-anti-patterns.md` were checked.
 
 ## Validation Checks

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

@@ -2,6 +2,8 @@
 
 AI 写 `VxePlusTable` 页面时，必须先确认请求形态。这个项目主流后端通信不是普通 REST，而是 `@eplat/ei` 的 `EiInfo` / `EiBlock`。
 
+本文件关注请求链路和生成写法。需要判断原始 JSON 结构、`__blocks__` 中的二维数组如何映射、或 `__sys__` 错误信息时，继续读 [06-eiinfo-data-format.md](./06-eiinfo-data-format.md)。
+
 ## 表格查询默认链路
 
 ```vue
@@ -100,6 +102,15 @@ const res = await EiCommunicator.send('BMBR01', 'query', ei)
 const rows = res.getBlock('result')?.getMappedRows() || []
 ```
 
+字段很少，或多个 block 都只是补少量字段时，可以连续使用 `set()` 快速构建：
+
+```ts
+const ei = new EiInfo()
+ei.set('inqu_status-0-level', 1)
+ei.set('result-0-level', 1)
+await EiCommunicator.send('ABBP02', 'query', ei)
+```
+
 有 block 数据：
 
 ```ts
@@ -111,6 +122,8 @@ ei.addBlock(EiBlock.build('inqu', [formData]))
 await EiCommunicator.send('SMSW0101', 'confirm', ei)
 ```
 
+重要：当前 EiInfo 库里 `set()` 和 `EiBlock.build()` / `addBlock()` 不能在同一个 `EiInfo` 对象上混用。一个对象已经使用 `set()` 后，不要再 `addBlock(EiBlock.build(...))`；已经使用 build/addBlock 后，也不要再用 `set()` 追加字段。需要额外字段时，把字段放进同一个 build 数据对象里，或改为全量 set-only 构建。
+
 ## 选中行提交
 
 有些 `VxePlusTable` 暴露方法可能直接返回 EiInfo 或封装后的 block 数据。复制前必须看当前页面真实写法，不要假设一定是普通数组。

package/skills/brms-vxe-plus-developer/references/vxe-plus-knowledge/06-eiinfo-data-format.md

@@ -0,0 +1,276 @@
+# 06-EiInfo Data Format
+
+This file records the JSON shape behind `@eplat/ei`. Use it when generated code needs to inspect raw responses, debug block names, handle service errors, or explain why `getMappedRows()` is required.
+
+## Practical Reading Rule
+
+For BRMS page development, the useful response data is usually in `__blocks__`.
+
+Other top-level fields such as `serviceName`, `methodName`, `baseUserInfo`, `__version__`, `UUID`, and project/session metadata are real metadata, but generated page code normally should not depend on them unless the local page already does.
+
+Error and status information is in `__sys__`. When an interface fails or returns business errors, check `__sys__.status`, `__sys__.msg`, `__sys__.detailMsg`, `__sys__.msgKey`, and `__sys__.traceId`.
+
+## Raw JSON Shape
+
+```ts
+type EiInfoJson = {
+  __blocks__?: Record<string, EiBlockJson>
+  __sys__?: {
+    status?: number
+    msg?: string
+    detailMsg?: string
+    msgKey?: string
+    traceId?: string
+    name?: string
+    descName?: string
+  }
+  [metadata: string]: unknown
+}
+
+type EiBlockJson = {
+  meta?: {
+    columns?: Array<{
+      pos: number
+      name: string
+      descName?: string
+      [metadata: string]: unknown
+    }>
+    attr?: Record<string, unknown>
+    desc?: string
+  }
+  attr?: Record<string, unknown>
+  rows?: unknown[][]
+}
+```
+
+Example shape:
+
+```json
+{
+  "__blocks__": {
+    "inqu_status": {
+      "meta": {
+        "columns": [
+          { "pos": 0, "name": "cuUnitCodeLike", "descName": " " }
+        ],
+        "attr": {},
+        "desc": ""
+      },
+      "attr": {},
+      "rows": [[""]]
+    },
+    "result": {
+      "meta": {
+        "columns": [
+          { "pos": 0, "name": "modifiedUserName", "descName": " " },
+          { "pos": 1, "name": "modifiedTime", "descName": " " }
+        ],
+        "attr": {},
+        "desc": ""
+      },
+      "attr": {
+        "offset": 0,
+        "limit": 10,
+        "count": 2454,
+        "orderBy": ""
+      },
+      "rows": [["Zhang San", "2026-06-05 16:41:40"]]
+    }
+  },
+  "__sys__": {
+    "status": 0,
+    "msg": "",
+    "detailMsg": "",
+    "traceId": "..."
+  }
+}
+```
+
+## Block Data Mapping
+
+Raw block rows are two-dimensional arrays. Do not read them by hard-coded indexes in page code.
+
+Mapping rule:
+
+```ts
+const columns = block.meta.columns
+const row = block.rows[0]
+const mapped = {
+  [columns[0].name]: row[columns[0].pos],
+  [columns[1].name]: row[columns[1].pos],
+}
+```
+
+In real code, prefer the library method:
+
+```ts
+const rows = res.getBlock('result')?.getMappedRows() || []
+```
+
+`getMappedRows()` converts:
+
+```ts
+[
+  ['Zhang San', '2026-06-05 16:41:40']
+]
+```
+
+into:
+
+```ts
+[
+  {
+    modifiedUserName: 'Zhang San',
+    modifiedTime: '2026-06-05 16:41:40',
+  }
+]
+```
+
+## Common Blocks
+
+Common names, not absolute rules:
+
+- `inqu_status`: query form conditions.
+- `result`: table result rows.
+- `${tableId}_filter`: header filter block generated by table query.
+- `inqu`: business form block used by some save/confirm interfaces.
+
+The real backend contract wins over these defaults. If the interface or neighboring page uses another block name, follow that contract.
+
+## Request Construction
+
+For single fields, `EiInfo.set()` uses a three-part path:
+
+```ts
+const ei = new EiInfo()
+ei.set('inqu_status-0-bpProposalMainCode', formData.bpProposalMainCode)
+```
+
+The path means:
+
+```text
+<blockName>-<rowIndex>-<columnName>
+```
+
+When there are only a few fields, or multiple blocks each need only a few fields, repeated `set()` calls are the fastest clear construction style:
+
+```ts
+const ei = new EiInfo()
+ei.set('inqu_status-0-level', 1)
+ei.set('result-0-level', 1)
+await EiCommunicator.send('ABBP02', 'query', ei)
+```
+
+For row collections, build blocks explicitly:
+
+```ts
+const ei = new EiInfo()
+ei.addBlock(EiBlock.build('result', rows))
+ei.addBlock(EiBlock.build('inqu_status', [formData]))
+await EiCommunicator.send('ABBP02', 'save', ei)
+```
+
+`EiBlock.build('result', rows)` creates `meta.columns` from object keys and stores values in `rows` as arrays. Consumers should still read through `getMappedRows()` after receiving a response.
+
+## Construction Mode Trap
+
+The current EiInfo library has a construction bug: do not mix `set()` path writes and `EiBlock.build()` / `addBlock()` on the same `EiInfo` instance.
+
+Choose one mode per object:
+
+```ts
+// Good: set-only mode.
+const queryEi = new EiInfo()
+queryEi.set('inqu_status-0-level', 1)
+queryEi.set('result-0-level', 1)
+```
+
+```ts
+// Good: build-only mode.
+const saveEi = new EiInfo()
+saveEi.addBlock(EiBlock.build('result', rows))
+saveEi.addBlock(EiBlock.build('inqu_status', [formData]))
+```
+
+Do not write:
+
+```ts
+// Bad: mixed construction mode on the same EiInfo object.
+const ei = new EiInfo()
+ei.set('inqu_status-0-level', 1)
+ei.addBlock(EiBlock.build('result', rows))
+```
+
+And do not write:
+
+```ts
+// Bad: mixed construction mode on the same EiInfo object.
+const ei = new EiInfo()
+ei.addBlock(EiBlock.build('result', rows))
+ei.set('inqu_status-0-level', 1)
+```
+
+If both a row collection and extra single fields are required, prefer putting the single fields into another built block:
+
+```ts
+const ei = new EiInfo()
+ei.addBlock(EiBlock.build('result', rows))
+ei.addBlock(EiBlock.build('inqu_status', [{
+  level: 1,
+  ...formData,
+}]))
+```
+
+If the backend explicitly requires `set()` style fields, keep the whole object in set-only mode and set every required field path explicitly.
+
+## Table Query Response
+
+For `VxePlusTable id="ABBP02_result"`, the table data block is usually `result`.
+
+The response data usually lives at:
+
+```ts
+const block = res.getBlock('result')
+const rows = block?.getMappedRows() || []
+const total = block?.getAttr?.().count ?? 0
+```
+
+Raw JSON equivalent:
+
+```ts
+const block = json.__blocks__?.result
+const total = block?.attr?.count
+```
+
+Do not use unrelated top-level metadata as table rows.
+
+## Error Handling
+
+`EiCommunicator.send()` may throw transport errors, and successful HTTP responses may still carry business status in `__sys__`.
+
+When local code handles status explicitly, use the `EiInfo` methods or raw `__sys__`:
+
+```ts
+const res = await EiCommunicator.send('ABBP02', 'query', ei)
+const status = res.getStatus?.()
+const message = res.getMsg?.() || res.getDetailMsg?.()
+```
+
+Raw response equivalent:
+
+```ts
+const status = json.__sys__?.status
+const message = json.__sys__?.msg || json.__sys__?.detailMsg
+const traceId = json.__sys__?.traceId
+```
+
+Do not treat an empty `result` block as an error by itself. Empty rows can be a valid query result.
+
+## Generation Rules
+
+- Prefer `res.getBlock(blockName)?.getMappedRows()` over raw `__blocks__` access in Vue page code.
+- Use raw `__blocks__` only for debugging, documentation, or when the local utility already returns plain JSON.
+- Never hard-code row array indexes like `row[0]` for business fields when column names are available.
+- Read `block.attr.count` for table totals; do not count the current page rows as total.
+- Read `__sys__` / `getStatus()` / `getMsg()` for errors; do not infer errors from missing optional metadata.
+- Preserve backend block names exactly when service docs or neighboring pages specify them.

package/skills/brms-vxe-plus-developer/references/vxe-plus-knowledge/07-development-tips.md

@@ -0,0 +1,113 @@
+# 07-Development Tips
+
+本文件记录真实 BRMS `project/*` 页面里常见但不属于 VxePlus/EiInfo 核心契约的开发技巧。遇到审批详情、动态按钮显隐、跨页面返回刷新时优先读本文件。
+
+这些技巧来自 `D:/Git/AI/eplat-vue-base` 的真实源码核对。复制到其他项目时仍要先检查目标项目是否有同名组件、store、按钮编码和页面标识。
+
+## 审批详情页判断 `__approveFlag__`
+
+用途：识别当前页面或子组件是否处于审批详情/只读详情场景。常见影响包括表单只读、表格只读、隐藏新增/保存/提交等操作。
+
+推荐写法：在详情根页面根据路由或业务状态 provide，在子组件、form config、table/form wrapper 中 inject。
+
+```ts
+// 根页面
+provide('__approveFlag__', route.query.status === 'true' ? true : undefined)
+```
+
+```ts
+// 子组件或组合式配置
+const approveFlag = inject<boolean | undefined>('__approveFlag__', undefined)
+```
+
+生成注意：
+
+- 不要自己发明新的审批态字段名，优先搜索目标项目里的 `__approveFlag__`。
+- `true` 表示审批详情/只读倾向；`undefined` 通常表示普通页面，避免强行传 `false` 改变已有组件默认逻辑。
+- 如果目标页面已有 `isApprovePage`、`approveFlag`、`editable` 等本地状态，优先沿用本地命名和计算方式。
+- 只读态不仅是表单禁用，也经常需要配合 `btnSetVisible` 隐藏按钮。
+
+源码核对点：
+
+- `project/base/src/views/AB/BP/ABBP0201.vue`: uses `provide('__approveFlag__', route.query.status === 'true' ? true : undefined)`.
+- `project/base/src/views/AB/BP/component/ABBP02/formConfig.ts`: injects `__approveFlag__` inside form config composition.
+- `libs/components/src/components/table/src/table.tsx`: table wrapper injects `__approveFlag__`.
+- `libs/components/src/components/form/src/form.tsx`: form wrapper injects `__approveFlag__`.
+
+## 按钮显隐 `btnSetVisible`
+
+用途：根据审批态、页面状态、业务条件动态显示/隐藏 `BxContainer` 或 `VxePlusTable` 按钮。
+
+推荐写法：
+
+```ts
+detailContainer.value?.btnSetVisible?.(['SAVE', 'SUBMIT', 'TEMP'], false)
+xGrid.value?.btnSetVisible?.(['ADD', 'DELETE', 'SAVE'], editable.value)
+```
+
+`visible` 默认是 `true`，传 `false` 表示隐藏。
+
+生成注意：
+
+- 按钮编码必须来自真实按钮配置，例如 `toolbarButtons`、后端按钮配置、已有页面调用，不要猜编码。
+- `BxContainer` 按钮通常按 `nodeCode` 匹配；`VxePlusTable` toolbar 按钮通常按 `code` 匹配。调用层都暴露为 `btnSetVisible(codes, visible)`。
+- 只是禁用按钮时用 `btnSetDisable`；要从界面上隐藏才用 `btnSetVisible`。
+- 在 `watch`、数据加载回调、`onMounted` 或状态变化后调用时，要确保 ref 已经可用，建议使用可选链。
+- 审批态页面隐藏按钮时，优先集中在一个状态同步函数里处理，不要把同一批按钮散落到多个 watcher 里。
+
+源码核对点：
+
+- `project/base/src/components/bx-container/bx-container-v2.vue`: `btnSetVisible(codes, visible = true)` updates container button visibility.
+- `project/base/src/components/bx-container/bx-container.vue`: exposes `btnSetVisible`.
+- `libs/components/src/hooks/useToolbarConfig.ts`: table toolbar exposes `btnSetVisible`.
+- `libs/components/src/components/table/src/table.tsx`: table exposes toolbar methods.
+- `project/base/src/views/AB/BP/ABBP0202.vue`: uses container `btnSetVisible` to switch detail actions.
+- `project/base/src/views/JM/JR/JMJR0101.vue`: uses container `btnSetVisible` for formula status actions.
+
+## 页面刷新标记 `pageRefreshStore`
+
+用途：从详情页、编辑页、弹窗页或其他页面跳转/返回后，让目标列表页在 `onActivated` 中按需刷新。适用于 KeepAlive 页面之间的“保存成功后回到列表刷新表格”。
+
+推荐写法：触发方设置标记，目标方检查标记并刷新。
+
+```ts
+// 触发方：保存、提交、生效、删除成功后
+const pageRefreshStore = usePageRefreshStore()
+pageRefreshStore.setRefreshFlag('SMSO0102')
+```
+
+```ts
+// 目标方：KeepAlive 激活时刷新
+const pageRefreshStore = usePageRefreshStore()
+
+onActivated(() => {
+  if (pageRefreshStore.checkRefreshFlag('SMSO0102'))
+    xGrid.value?.reload()
+})
+```
+
+生成注意：
+
+- `setRefreshFlag()` 和 `checkRefreshFlag()` 的 key 必须一致。
+- key 可以是页面名，也可以是更细的业务标识，例如 `JMJR0101.refreshTable`；优先沿用目标模块已有约定。
+- `checkRefreshFlag()` 检查到 `true` 后会重置标记，避免重复刷新。
+- 不要用全局事件或直接跨页面拿 ref 替代该 store，除非目标项目没有 `usePageRefreshStore`。
+- 如果页面没有 KeepAlive 或没有 `onActivated`，先检查本地路由/页面生命周期，不要机械套用。
+
+源码核对点：
+
+- `project/base/src/stores/modules/pageRefresh.ts`: defines `setRefreshFlag(pageName)` and `checkRefreshFlag(pageName)`.
+- `project/base/src/views/SM/SO/SMSO0101.vue`: calls `setRefreshFlag('SMSO0102')` after confirm.
+- `project/base/src/views/SM/SO/SMSO0102.vue`: uses `onActivated` + `checkRefreshFlag('SMSO0102')` + `xGrid.reload()`.
+- `project/base/src/views/JM/JR/JMJR0101.vue`: uses `setRefreshFlag('JMJR0101.refreshTable')`.
+- `project/base/src/views/JM/JR/JMJR01/right.vue`: checks `JMJR0101.refreshTable` and reloads.
+
+## When To Use
+
+Use these tips when the requirement says:
+
+- 审批详情、审批态、只读详情、查看详情。
+- 隐藏/显示/禁用某些按钮。
+- 保存后返回列表刷新、关闭详情后刷新、跨页面触发表格 reload。
+
+Do not introduce these patterns into a simple page unless the behavior is actually required by the requirement or neighboring module style.

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

@@ -12,8 +12,10 @@
 2. 写表单前读 [02-vxe-plus-form.md](./02-vxe-plus-form.md)：只复制直接组件契约，不复制历史二次封装。
 3. 写表格前读 [03-vxe-plus-table.md](./03-vxe-plus-table.md)：确认 `id`、`form-config`、`service-config`、编辑列、按钮事件。
 4. 写请求前必须读 [05-request-and-eiinfo.md](./05-request-and-eiinfo.md)：确认 EiInfo block、分页、响应 block、保存提交方式。
-5. 找样例读 [04-example-map.md](./04-example-map.md)：按场景复制内嵌样例，再按来源路径核对真实业务差异。
-6. 交付前读 [90-anti-patterns.md](./90-anti-patterns.md)：检查高频错误。
+5. 需要判断原始返回、block 映射或接口错误时读 [06-eiinfo-data-format.md](./06-eiinfo-data-format.md)：真实数据主要在 `__blocks__`，错误信息看 `__sys__`。
+6. 遇到审批态、按钮显隐、跨页面刷新时读 [07-development-tips.md](./07-development-tips.md)：确认 `__approveFlag__`、`btnSetVisible`、`pageRefreshStore`。
+7. 找样例读 [04-example-map.md](./04-example-map.md)：按场景复制内嵌样例，再按来源路径核对真实业务差异。
+8. 交付前读 [90-anti-patterns.md](./90-anti-patterns.md)：检查高频错误。
 
 ## 最高优先级约束
 
@@ -21,6 +23,9 @@
 - `VxePlusTable` 的查询表单配置使用 `:form-config`，它不是独立 `VxePlusForm` 的属性。
 - 新写代码不要引入新的 `useForm` 二次封装层。历史页面里的 `src/hooks/useForm.ts` 只能作为识别既有代码的词典，不作为推荐样板。
 - 表格请求优先走 `serviceConfig` + `transformParams` / `transformResponse`。复杂保存优先显式构造 `EiInfo`。
+- EiInfo 原始返回中业务数据主要在 `__blocks__`；错误/状态信息看 `__sys__` 或 `getStatus()` / `getMsg()`。
+- 同一个 `EiInfo` 对象不要混用 `set()` 路径写入和 `EiBlock.build()` / `addBlock()` 构建。
+- 审批详情、按钮显隐、跨页面刷新优先沿用项目已有的 `__approveFlag__`、`btnSetVisible`、`pageRefreshStore`。
 - 没有用户明确要求兼容旧数据时，不写字段回退、旧格式兼容、双路径兼容。
 
 ## 框架源码边界