adspecs 0.1.39 → 0.1.41

package/references/vue3-front-standard/gushen-components.md

@@ -0,0 +1,174 @@
+# Gushen 前端组件规则
+
+本工程依赖：
+
+- `@gushen/gushen-common-components`
+- `@gushen/gushen-form-render`
+
+当前目标工程未安装 `@gushen/gushen-work-flow`。如果需求涉及工作流组件（如 `flow-container`、`flow-ea-buttons`、`flow-commit`），先确认依赖、注册方式和运行时子应用边界，不要直接生成组件用法。
+
+使用组件前，优先读取组件源码：`node_modules/@gushen/gushen-common-components/src/packages/components`。
+
+## 全局注册
+
+`src/core/initMain.ts` 已执行：
+
+```ts
+import GsComponents from '@gushen/gushen-common-components'
+instance.use(GsComponents)
+```
+
+因此 `gs-*` 公共组件可直接在模板中使用。当前本地全局组件仅包含 `GsIconDialog`、`GsIcon`、`SvgIcon`、`UploadImg`，注册位置为 `src/components/global-register.ts`。
+
+常见公共组件分类：
+
+- 表格：`GsTable`、`GsCustomizeTable`、`GsVxeTable`、`GsSuperTable`
+- 查询/输入：`GsSearchBar`、`GsInput`、`GsSelect`、`GsRadio`、`GsSwitch`
+- 选择器：`GsSelectTreeTable`、`GsPersonnelSelector`、`GsDepartmentSelector`、`GsPageSelect`、`GsDialogSelector`
+- 上传/导入导出：`GsUpload`、`GsAttachmentList`、`UploadImg`、`GsImportData`、`GsExportData`
+- 弹层/布局：`GsDialog`、`GsDrawer`、`GsCard`、`GsGridLayout`
+
+## `GsCustomizeTable` / `gs-table`
+
+源码路径：`node_modules/@gushen/gushen-common-components/src/packages/components/GsCustomizeTable`。
+
+### 推荐用途
+
+- 后端分页列表页。
+- 需要列设置、表头查询、刷新、导入导出、关键字搜索的业务列表。
+- 页面模板统一从 `page-template-index.md` 选择；本规则只说明组件 API 和约束。
+
+### 核心配置
+
+组件级常用 props：
+
+- `gridConfig`：核心表格配置，和源码 `defaultConfig()` 合并。
+- `queryParams`：请求参数，常见结构为 `{ params: { pageIndex, pageRows, params: {} }, queryUrl }`。
+- `fixedParams`：固定参数，搜索重置时保留。
+- `tableParams`：表头搜索附加参数。
+- `method`：请求方法，默认 `post`。
+- `tableHeight` / `maxHeight`：高度控制。
+- `reserveSelection`：跨页保留勾选，需配合 `rowKey`。
+- `readonly`：只读禁用交互。
+- `isParamsOutSearch`：为 true 时抛出 `paramsOutSearch`，由父组件接管请求。
+- `reqBeforeHandler` / `resDataHandler`：请求前和响应数据处理钩子。
+
+常用顶层配置来自 `common/defaultConfig.js`：
+
+- `columns`：列配置。
+- `queryUrl`：远程查询接口。
+- `selectable`：是否显示勾选列。
+- `showIndex`：是否显示序号列。
+- `slotArr`：需要自定义插槽渲染的列字段。
+- `needPagination` / `paged`：是否分页。
+- `hideSearchBtn`：是否隐藏表头查询切换。
+- `showSetting`：是否显示列设置。
+- `showRefresh`：是否显示刷新按钮。
+- `importable` / `exportable`：是否启用导入导出。
+- `enableCustomizeFilter`：是否启用高级筛选。
+- `isVirtualList`：是否启用虚拟滚动。
+- `localstorageName`：列设置缓存 key。
+- `rowKey`：跨页勾选、虚拟列表建议设置，默认常用 `id`。
+- `showKeyWordSearch`：是否显示关键字搜索。
+- `isScrollRequest`：是否启用滚动加载。
+
+列默认配置来自 `common/columnDefaultConfig.js`：
+
+- `prop`、`label`、`width`、`align`、`headerAlign`、`fixed`。
+- `isShow`、`hidden`、`hiddenFlag` 控制显示。
+- `sortable` 默认 `true`。
+- `showOverflowTooltip` 默认 `true`。
+- `dataType` 默认 `string`。
+- `dictCode` 可配合字典数据做显示转换。
+- `list` 可提供下拉选项。
+- `component`、`componentAttr`、`list` 可用于表头搜索控件。
+- `sortableType: 'all'` 表示远程排序。
+- `hideSearh` 用于禁用表头搜索（源码拼写如此）。
+
+### 插槽
+
+- `#table-title`：表格标题。
+- `#btn`：表格头部左侧按钮。
+- `#btn-r`：头部浮动按钮区域。
+- `#expand`：展开行。
+- `#pager`：自定义分页区域。
+- 字段插槽：字段名必须加入 `slotArr`，例如 `slotArr: ['readStatus', 'action']` 后可写 `#readStatus`、`#action`。
+
+### 事件
+
+常用事件：
+
+- `@inited`：表格初始化完成，返回表格实例。
+- `@updateTableData`：表格数据更新。
+- `@update:tableTotal`：总数更新。
+- `@requestError`：请求异常。
+- `@pageChange`、`@sizeChange`：分页变化。
+- `@row-click`：行点击。
+- `@select-all`：全选变化。
+- `@sort-change`：排序变化。
+- `@header-dragend`：列宽拖拽结束。
+- `@needSearchChange`：表头查询开关变化。
+- `@paramsOutSearch`：外部接管查询参数。
+- `@import-success`、`@exportSuccess`：导入导出成功。
+
+### 实例方法
+
+通过 `ref` 可调用：
+
+- `refresh(hasLoading, isClearSelection = true)`：刷新数据。
+- `getData(...)`：按当前配置查询。
+- `outSearch(isKeepPage?, noLike?, hasLoading?, index?)`：外部搜索条件变化后触发查询。
+- `tableSearch(isKeepPage?, index?)`：表头查询。
+- `getSelection()`：获取勾选行。
+- `setRowSelection(row, flag, key?)`：切换指定行选中。
+- `getCurrentParams()`：获取当前请求参数。
+- `resetTable()` / `init()` / `doTableLayout()`：重置、初始化、重排布局。
+- `setFirstRow()`：选中首行并触发 `getfirstdata`。
+
+### 生成代码约束
+
+- 普通值展示优先使用列配置和 `dictCode`，不要为了纯文本显示滥用插槽。
+- 需要 `el-tag`、按钮、链接、富文本等复杂渲染时，字段必须加入 `slotArr`。
+- 操作列使用 `prop: 'action'`、`fixed: 'right'`，并加入 `slotArr`。
+- 表头查询字段使用 `component`、`componentAttr`、`list`；字典字段优先配置 `dictCode`。
+- 每个列表页设置唯一 `localstorageName`，避免列设置缓存串页。
+- 外部查询条件变化后更新 `queryParams.params.params`，再调用 `tableRef.value?.outSearch(false)`；普通刷新调用 `tableRef.value?.refresh(true)`。
+- 勾选场景必须设置 `rowKey`。
+
+## `GsTable`
+
+源码路径：`node_modules/@gushen/gushen-common-components/src/packages/components/GsTable/index.vue`。
+
+- 适合简单本地或远程表格。
+- `columns` 控制列，`options`/工具配置控制搜索、刷新、列设置、选择列、序号列、加减行。
+- `#header` 放头部按钮，`#cell` 用于可编辑或自定义单元格。
+- 旧代码中 `<gs-table :columns="columns" :options="options" :remote="remoteData">` 是可参考写法。
+
+## `GsSearchBar`
+
+源码路径：`node_modules/@gushen/gushen-common-components/src/packages/components/GsSearchBar/index.vue`。
+
+- `searchConfig.items` 描述查询项，字段名使用 `field`。
+- `fixedParams` 会合并进查询参数。
+- `btnPosition` 支持 `top` / `bottom`。
+- 查询项 `type` 直接映射 Element Plus 组件，如 `el-input`、`el-select`、`el-cascader`。
+- `el-select` 的选项使用 `options: [{ label, value }]`。
+- `#prepend`、`#append` 可插入按钮。
+- 事件：`@search="handleSearch"`、`@reset="handleReset"`、`@expand="handleExpand"`。
+- 可通过实例方法 `setFormItemValue(field, value)` 设置查询字段。
+
+## 上传与图片
+
+- 本地全局 `UploadImg` 来自 `src/components/UploadImg/index.vue`。
+- 公共组件库也提供 `GsUpload`、`UploadImg`，使用前对照源码确认事件和字段。
+- 文件上传 API 参考 `src/api/attachment.ts` 和 `src/components/GsUpload`。
+
+## 动态表单
+
+- 依赖 `@gushen/gushen-form-render` 已安装。
+- 动态表单组件来自 `@gushen/gushen-form-render`，常用注册名是 `FormRender` / `<form-render>`；不存在 `GsForm` 业务组件。
+- 当前 `src/core/initMain.ts` 中插件注册是注释状态；新增 `<FormRender />` 前，先确认是否需要解除注释：
+  - `import GushenFormRender from '@gushen/gushen-form-render'`
+  - `import '@gushen/gushen-form-render/lib/gushen-form-render.css'`
+  - `instance.use(GushenFormRender)`
+- 现有动态表单入口：`src/views/dynamic-form/index.vue`。

package/references/vue3-front-standard/page-development-rules.md

@@ -0,0 +1,262 @@
+# 页面开发规则
+
+## 默认页面形态
+
+新增业务页面优先使用：
+
+- Vue 3 `script setup lang="ts"`。
+- Element Plus 布局组件。
+- `@gushen/gushen-common-components` 的表格、查询栏、上传等组件。
+- `src/api/<module>/index.ts` 管理请求。
+- `src/lang/modules/<module>/{zh-cn,en-us,zh-tw}.ts` 管理文案。
+
+维护已有旧页面时，可以保留 Options API；新增页面不要主动复制旧页面里的 `console.log`、`@ts-nocheck`、硬编码文案和隐式 any。
+
+## 列表页
+
+推荐结构：
+
+```text
+src/views/<module>/<page>/
+├── index.vue
+├── components/
+│   └── <可选子组件>.vue
+└── config/
+    └── gridConfig.ts
+```
+
+列表页默认使用 `GsCustomizeTable` / `<gs-table>`：
+
+- 查询按钮放在表格 `#btn` 或页面顶部查询区。
+- 列配置单独抽到 `config/gridConfig.ts`，复杂列通过 `slotArr` 开启插槽。
+- 列表请求函数放在 `src/api/<module>/<page>/index.ts`。
+- 成功判断用 `reqIsSucceed`，不要写死单一成功码，除非维护旧接口已有固定协议。
+
+## 表单页
+
+推荐结构：
+
+```text
+src/views/<module>/<page>/
+├── index.vue
+└── components/
+    └── BasicForm.vue
+```
+
+表单规则：
+
+- 使用 `el-form`、`el-row`、`el-col` 组织字段。
+- 新增/编辑共用表单组件，通过 `disabled` 或 `readonly` 控制只读。
+- 保存入参按后端要求包裹 `{ params: formData }`。
+- 表单初始化、回显映射、保存映射拆成小函数。
+- 复杂弹窗或选择器优先封装为独立子组件，不要在主页面堆大量弹窗逻辑。
+
+## 流程页面
+
+流程表单模板统一从 `page-template-index.md` 选择，不再以当前工程旧页面作为模板入口。
+
+流程页面需要保留方法契约：
+
+- `get_process_variables()`：返回流程变量。
+- `ap_save()`：保存草稿，返回 Promise。
+- 包装页通过 props 接收 `isSubmit`、`editStatus`、`bpm_businessKey`、`taskServiceParams`、`curTaskName`。
+
+## 动态表单页
+
+参考：`src/views/dynamic-form/index.vue`。
+
+- 当前页面只挂载 `<FormRender ref="formRenderRef" />`。
+- 使用 IntersectionObserver 在页面可见时向事件总线发送当前路由信息。
+- 使用前确认 `@gushen/gushen-form-render` 插件是否已在 `src/core/initMain.ts` 注册。
+
+## 路由与菜单
+
+- 普通业务页默认由后台菜单动态加载，只需确保页面路径存在。
+- 菜单 `menuUrl` / `originalAddr` 会在 `src/permission.ts` 中映射到 `@/views${componentPath}/index.vue`。
+- 例如后台菜单路径 `/test-menu/demo1` 对应 `src/views/test-menu/demo1/index.vue`。
+- 静态壳内页面才补 `src/router/index.ts`。
+- 新增路由 meta 至少包含 `title`、`enTitle`、`noCache`、`hideInMenu`、`isBootstrap`。
+- 动态表单菜单通过 `parameter.menu_type === 'DYNAMIC_FORM'` 进入固定 `FormRender` 容器，一般不新建手写业务页。
+
+## 样式
+
+- 页面根节点使用唯一 class，例如 `<section class="xxx-page">`。
+- 页面级样式使用 `<style scoped lang="scss">`。
+- 不要把布局高度写死到固定 px；优先使用 flex 和 `min-height: 0`。
+
+## 生成后自检
+
+- 页面能被路由加载。
+- API 路径、请求方法、参数包装与现有接口一致。
+- 表格远程刷新、分页、勾选、操作列能闭环。
+- 用户可见文案进入语言包。
+- 无新增 TypeScript / Vue 诊断。
+
+## 常见问题与修复指南
+
+以下是开发过程中已验证的高频问题及修复方案，生成页面时务必逐项检查。
+
+### 1. gs-table 操作列不显示
+
+**现象**：表格渲染正常，但操作列（`prop: 'action'`）和自定义内容列（如状态 Tag）显示空白。
+
+**根因**：`GsTable` 组件的 `#cell` 插槽仅在列的 `editable: true` 时才渲染。源码逻辑：
+
+```ts
+// GsTable/index.vue
+if (type === "cell") {
+    const { editable } = column || {};
+    return editable === true;
+}
+```
+
+**修复**：需要自定义内容渲染的列必须加 `editable: true`：
+
+```ts
+{ prop: 'forecastStatus', label: '状态', editable: true },
+{ prop: 'action', label: '操作', searchable: false, editable: true },
+```
+
+### 2. gs-table 数据请求方式选择
+
+**原则**：优先使用项目中已验证的 `:columns` + `:options` + `:remote` 模式（参照 `mdmCustomer`），而非 `GsCustomizeTable` 的 `:grid-config` + `:query-params` 模式。
+
+**原因**：两种组件的数据响应格式不同：
+- `GsCustomizeTable` 内部期望 `res.data.data` 是行数组 + `res.data.count` 是总数
+- `:remote` 模式由开发者自行处理响应格式转换，兼容性更好
+
+```html
+<gs-table
+  ref="tableRef"
+  :columns="columns"
+  :options="tableOptions"
+  :remote="remoteData"
+>
+  <template #header>
+    <el-button type="primary" @click="openAddDialog">新增</el-button>
+  </template>
+  <template #cell="{ column, row }">
+    <template v-if="column.prop === 'action'">
+      <!-- 操作按钮 -->
+    </template>
+  </template>
+</gs-table>
+```
+
+`remoteData` 函数必须返回 `{ data: rows[], total: number, number: pageIndex, size: pageRows }` 格式：
+
+```ts
+async function remoteData(otherParams: any = {}) {
+  const { number, size, params } = otherParams || {}
+  const res = await findPagination({ pageIndex: number, pageRows: size, params })
+  if (res.code === 800) {
+    const d = res.data || {}
+    return { data: d.rows || [], number, size, total: Number(d.total) || 0 }
+  }
+  return { data: [], number, size, total: 0 }
+}
+```
+
+### 3. Mock 模式下 GET 请求的查询参数丢失
+
+**现象**：详情页打开后空白，控制台报 `Cannot read properties of undefined (reading 'data')`。
+
+**根因**：axios 的 `params` 配置项在所有请求拦截器执行**之后**才拼接到 URL。Mock 拦截器运行时 URL 上没有查询参数，导致 mock router 提取不到 `id` 等参数。
+
+```ts
+// ❌ 错误：params 在拦截器之后拼接，mock 拿不到 id
+export function getById(id: number) {
+  return request({ url: '/api/forecast/get-id', method: 'get', params: { id } })
+}
+
+// ✅ 正确：参数直接拼在 URL 上
+export function getById(id: number) {
+  return request({ url: `/api/forecast/get-id?id=${id}`, method: 'get' })
+}
+```
+
+**适用范围**：所有 GET 请求的 mock API 都必须将参数直接拼入 URL 字符串，不能依赖 axios 的 `params` 配置。
+
+### 4. 语言包 key 结构与 i18n 引用不匹配
+
+**现象**：页面上显示原始 key 名（如 `forecast-order.listTitle`）而非翻译文案。
+
+**根因**：语言包模块通过 `import.meta.glob` 自动加载，文件夹名作为模块 key（如 `forecast-order`）。`$t('forecast-order.listTitle')` 按**嵌套对象路径**解析，而非扁平 key。语言包必须使用嵌套对象结构：
+
+```ts
+// ✅ 正确：嵌套对象，$t('forecast-order.status.DRAFT') 可以解析
+export default {
+  status: { DRAFT: '草稿', SUBMITTED: '已提交' },
+  msg: { saveSuccess: '保存成功' },
+}
+
+// ❌ 错误：扁平 key，$t('forecast-order.status.DRAFT') 无法解析为 'forecast-order'['status']['DRAFT']
+export default {
+  'status.DRAFT': '草稿',
+  'msg.saveSuccess': '保存成功',
+}
+```
+
+**自检清单**：
+- 所有 `$t('forecast-order.xxx')` 引用能在语言包中找到对应嵌套路径
+- 特别注意模板字符串中的动态 key：`` $t(`forecast-order.status.${val}`) ``
+- 语言包有 `{ immediate: true }` 的 watch 不能遗漏语言初始化时机
+
+### 5. mock 菜单路由出现双斜杠 `//`
+
+**现象**：点击左侧菜单跳转报错，URL 变成 `//forecast-order`。
+
+**根因**：`permission.ts` 的 `generatePath` 函数拼接路由时 `parentPath=''`，结果为 `'' + '/' + '/forecast-order'` = `'//forecast-order'`。去双斜杠逻辑需要 `!item.originalAddr` 为 `true` 才生效。
+
+**修复**：mock 菜单中 `originalAddr` 设为 `null`，不需要该字段：
+
+```ts
+export const mockMenus = [
+  {
+    menuId: 1001,
+    menuCode: 'forecast-order',
+    menuUrl: '/forecast-order',
+    menuName: '销售预测',
+    originalAddr: null,  // ← 关键：不能设为非空值
+    children: [],
+    // ...
+  },
+]
+```
+
+### 6. drawer/dialog 组件 v-model 循环同步
+
+**现象**：弹窗打开后空白，或者关闭后无法再打开。
+
+**根因**：手动用 `ref` + `watch` 同步 `props.visible ↔ internal visible` 加上 `el-drawer v-model` 内部也有自己的响应式逻辑，造成循环触发或事件丢失。
+
+**修复**：直接用 `:model-value` + `@update:model-value` 模式，不创建内部 visible ref：
+
+```html
+<el-drawer
+  :model-value="props.visible"
+  @update:model-value="onVisibleChange"
+>
+```
+
+```ts
+function onVisibleChange(val: boolean) {
+  if (!val) { /* 清理状态 */ }
+  emit('update:visible', val)
+}
+```
+
+### 7. 硬编码文案遗漏
+
+**现象**：表单校验错误提示、ElMessage 弹窗消息、el-drawer 标题等始终显示中文，不随语言切换变化。
+
+**检查范围**：
+- `el-form` 的 `:rules` 中 `message` 字段
+- `ElMessage.success/warning/error()` 调用
+- `ElMessageBox.confirm()` 的 `title`、`message`
+- 弹窗/抽屉的 `:title` 属性
+- 表格列配置中 `placeholder`、`searchOptions.loop` 的 `label`
+- `'是'/'否'`、`'确定'/'取消'` 等通用词
+
+**修复**：以上所有位置统一使用 `t('module.key')` 或 `$t('module.key')`。需要先在语言包中定义对应 key。
+