adspecs 0.1.40 → 0.1.41

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。
+

package/references/vue3-front-standard/page-template-index.md

@@ -0,0 +1,374 @@
+# 页面模板索引
+
+本文件是页面生成的唯一模板入口。模板均从丰富参考工程中提炼为“模式”，只描述可迁移结构、组件组合和生成要点；不要在生成代码或规则中引用参考工程的绝对路径。
+
+## 使用原则
+
+- 生成页面前先在本文件选择模板模式，再按 `page-development-rules.md` 落到目标工程路径。
+- 目标工程页面通常放在 `src/views/<menuUrl>/index.vue`，由后台菜单动态加载。
+- API 放在 `src/api/<module>/<page>/index.ts`，语言包放在 `src/lang/modules/<module>/`。
+- 不直接复制旧页面，不迁移参考工程的接口前缀、业务编码、绝对路径和专属本地组件。
+- 目标工程没有的依赖或组件必须替换为已有组件，或先明确补依赖。
+
+## 1. 查询栏 + 高级表格 + 弹窗表单
+
+适用场景：普通 CRUD 列表、配置列表、调度任务、消息模板、基础资料维护。
+
+推荐结构：
+
+```text
+src/views/<module>/<page>/
+├── index.vue
+├── searchConfig.ts
+├── gridConfig.ts
+└── components/
+    ├── AddForm.vue
+    ├── EditForm.vue
+    └── DetailDrawer.vue
+```
+
+生成要点：
+
+- 顶部使用 `GsSearchBar`，查询项放在 `searchConfig`。
+- 主表使用 `GsCustomizeTable`，列配置放在 `gridConfig`。
+- 外部查询更新 `queryParams.params.params` 后调用 `tableRef.value?.outSearch(false)`。
+- 新增、编辑、调试、详情等动作放入独立弹窗/抽屉组件。
+- 操作列使用 `slotArr: ['action']`，批量按钮放在 `#btn`。
+
+## 2. 单表 CRUD + 导入导出
+
+适用场景：字典类型、消息模板、系统参数、基础资料维护、带批量导入导出的业务列表。
+
+推荐结构：
+
+```text
+src/views/<module>/<page>/
+├── index.vue
+├── gridConfig.ts
+└── components/
+    ├── AddDialog.vue
+    ├── EditDialog.vue
+    └── BatchUpload.vue
+```
+
+生成要点：
+
+- 表格开启 `selectable`、`rowKey`、唯一 `localstorageName`。
+- 工具栏包含新增、导入、导出；导出以选中行 ID 组装请求。
+- 导入成功后刷新表格。
+- 复杂字段用字段插槽渲染，普通字典字段优先使用 `dictCode`。
+- 保存、删除、导入、导出都要有 loading 或禁用态防重复点击。
+
+## 3. 左树右详情 Tab
+
+适用场景：菜单管理、组织机构、分类目录、资源配置、主从层级维护。
+
+推荐结构：
+
+```text
+src/views/<module>/<page>/
+├── index.vue
+└── components/
+    ├── TreePanel.vue
+    ├── BasicInfoTab.vue
+    ├── ResourceTab.vue
+    └── PermissionTab.vue
+```
+
+生成要点：
+
+- 左侧固定宽度树，包含系统筛选、关键字过滤、新增按钮。
+- 右侧根据当前节点显示 `el-tabs`，每个 Tab 独立组件。
+- 当前节点通过 props 下发，子组件通过事件通知父组件刷新树。
+- Tab 是否显示由按钮权限、节点类型和租户/所有者条件共同决定。
+- 保留 `currentNode`、`defaultExpandedKeys`、`filterText`、`loading` 等状态。
+
+## 4. 左列表右内联编辑
+
+适用场景：模板中心、导入导出模板、打印模板、文档模板、需要边选边编辑的配置中心。
+
+推荐结构：
+
+```text
+src/views/<module>/<page>/
+├── index.vue
+└── components/
+    ├── TemplateListPanel.vue
+    ├── TemplateSearchBar.vue
+    ├── InlineEditor.vue
+    └── UseHistoryDialog.vue
+```
+
+生成要点：
+
+- 左侧为可分页模板列表，右侧为详情/编辑区。
+- `selectedItem` 控制右侧显示，`isEditing` 控制只读/编辑态。
+- 顶部工具栏在查看态显示编辑/删除，在编辑态显示保存/取消。
+- 右侧编辑区可用 `el-scrollbar` 包裹，避免页面整体滚动。
+- 新增时构造临时选中项，保存成功后刷新左侧列表并选中最新项。
+
+## 5. 权限控制多 Tab 中心
+
+适用场景：权限中心、配置中心、模板中心、模块化后台页面。
+
+推荐结构：
+
+```text
+src/views/<module>/<page>/
+├── index.vue
+└── tabs/
+    ├── FirstTab.vue
+    ├── SecondTab.vue
+    └── ThirdTab.vue
+```
+
+生成要点：
+
+- 父组件只负责 Tab 容器、权限判断和公共数据加载。
+- `authTabs` 由 `isHaveBtnAuth(code)` 过滤生成，默认激活第一个可见 Tab。
+- 公共数据通过 `provide` 下发给 Tab 子组件。
+- 每个 Tab 自己负责列表、表单、弹窗和 API。
+- 对首次切换才需要初始化的 Tab，在 `tab-change` 中调用子组件方法。
+
+## 6. 动态组件配置中心
+
+适用场景：系统配置中心、按权限展示多个配置模块、每个配置模块相互独立的页面。
+
+推荐结构：
+
+```text
+src/views/<module>/<page>/
+├── index.vue
+└── components/
+    ├── ConfigA.vue
+    ├── ConfigB.vue
+    └── ConfigC.vue
+```
+
+生成要点：
+
+- `tabList` 由权限和运行配置计算得到。
+- 使用 `<component :is="item.key" />` 渲染配置组件。
+- 无可见 Tab 时展示 `el-empty`。
+- 适合每个配置模块彼此独立、只共享少量全局配置的场景。
+
+## 7. 分段抽屉表单
+
+适用场景：任务配置、消息渠道、第三方接入、复杂基础资料。
+
+推荐结构：
+
+```text
+src/views/<module>/<page>/components/
+└── FormDrawer.vue
+```
+
+生成要点：
+
+- 使用抽屉或弹窗承载大表单，表单内用分段标题分组。
+- 每段用 `el-divider` 或统一分段标题组件。
+- 字段按 12/24 栅格组织，复杂字段条件显示。
+- 保存按钮带 `saveLoading`，保存成功后关闭并 emit `refresh`。
+- 复杂子选择器、Cron、代码编辑器等放入二级弹窗组件。
+
+## 8. 调度任务与 Cron 配置
+
+适用场景：定时任务、计划任务、推送任务、需要启动/停止/执行一次的任务管理。
+
+推荐结构：
+
+```text
+src/views/<module>/<page>/
+├── index.vue
+├── gridConfig.ts
+├── searchConfig.ts
+└── components/
+    ├── TaskForm.vue
+    ├── TriggerDialog.vue
+    └── CodeEditorDialog.vue
+```
+
+生成要点：
+
+- 列表操作列包含编辑、复制、删除、执行一次、查看日志、启动/停止。
+- 表单按“基础配置 / 调度配置 / 执行配置 / 高级配置”分段。
+- Cron 字段使用只读输入框触发 Cron 弹窗。
+- `scheduleType` 改变时联动清空或校验 `scheduleConf`。
+- 启停、执行一次等动作需要二次确认或 loading。
+
+## 9. 日志列表 + 详情抽屉 + 分析面板
+
+适用场景：接口日志、登录日志、审计日志、用户行为日志、调用统计。
+
+推荐结构：
+
+```text
+src/views/<module>/<page>/
+├── index.vue
+├── config/
+│   └── gridConfig.ts
+└── components/
+    ├── ParamsDrawer.vue
+    ├── LinkDrawer.vue
+    └── DataViewDrawer.vue
+```
+
+生成要点：
+
+- 列表 Tab 使用 `GsCustomizeTable`，可自定义 `#pager` 加首页/末页按钮。
+- 查询条件可放在 `#btn-r` 或独立筛选栏。
+- 大字段如 request/response/exception 只显示“详情”按钮，点击打开抽屉。
+- 分析 Tab 展示统计卡片、趋势图、Top 列表。
+- 图表依赖不存在时，先降级为统计卡片 + 表格，不要强行引入新依赖。
+
+## 10. 开放 API 列表 + 编辑页切换
+
+适用场景：接口管理、API 编排、服务接口定义、请求/响应参数维护。
+
+推荐结构：
+
+```text
+src/views/<module>/<page>/
+├── index.vue
+└── components/
+    ├── ParamTable.vue
+    ├── DebugDialog.vue
+    └── ApiImportDialog.vue
+```
+
+生成要点：
+
+- 页面用 `isEditing` / `mode` 在列表区和编辑区之间切换。
+- 列表区使用表格，支持增量/全量导入、导出、调试。
+- 编辑区包含基础表单 + 请求参数表 + 响应参数表。
+- 返回列表时刷新数据并重置表单。
+- 参数表作为子组件维护增删改，父组件保存时统一组装 payload。
+
+## 11. 权限矩阵 / 授权选择器
+
+适用场景：字段权限、数据权限、接口权限、人员授权、组织授权。
+
+推荐结构：
+
+```text
+src/views/<module>/<page>/
+├── index.vue
+└── components/
+    ├── OrgTreePanel.vue
+    ├── PermissionListPanel.vue
+    ├── GrantDialog.vue
+    └── ConditionTable.vue
+```
+
+生成要点：
+
+- 左侧组织/角色/用户树，右侧权限列表或矩阵。
+- 权限数据通常需要系统、菜单、角色、组织等固定参数。
+- 授权弹窗要支持已选回显和确认后局部刷新。
+- 条件配置可用表格维护，复杂表达式再引入编辑器。
+
+## 12. 规则设计 / 多模式编辑器
+
+适用场景：规则引擎、表达式配置、低代码规则编排、条件动作设计。
+
+推荐结构：
+
+```text
+src/views/<module>/<page>/
+├── index.vue
+└── components/
+    ├── VisualDesigner.vue
+    ├── ExpressionEditor.vue
+    ├── CodeEditor.vue
+    └── ExecutionDrawer.vue
+```
+
+生成要点：
+
+- 根据路由 query 或页面状态选择设计模式。
+- 父组件统一加载规则对象、保存、执行。
+- 视觉设计、表达式、代码编辑拆成互斥子组件。
+- 执行前先保存或校验当前编辑内容。
+- 若目标工程缺少编辑器依赖，先生成普通文本域或只读 JSON 预览，不直接引用外部编辑器组件。
+
+## 13. 基础资料表单
+
+适用场景：个人信息、密码修改、简单基础资料、只读/编辑切换的小表单。
+
+推荐结构：
+
+```text
+src/views/<module>/<page>/
+├── index.vue
+└── components/
+    └── BasicForm.vue
+```
+
+生成要点：
+
+- 使用 `el-form` + `el-row` + `el-col`。
+- 简单页面可以直接在 `index.vue` 放表单；字段超过一屏时拆 `BasicForm.vue`。
+- 头像、附件、图片类字段优先使用目标工程已有上传组件。
+- 保存前校验表单，保存成功后提示并按需刷新用户信息或返回列表。
+- 密码类表单必须包含确认字段校验和 loading 防重复提交。
+
+## 14. 流程表单包装页
+
+适用场景：流程引擎嵌入业务表单、审批页内保存草稿、发起流程。
+
+推荐结构：
+
+```text
+src/views/<module>/<page>/
+├── index.vue
+└── components/
+    └── BusinessForm.vue
+```
+
+生成要点：
+
+- 包装页接收 `isSubmit`、`editStatus`、`bpm_businessKey`、`taskServiceParams`、`curTaskName`。
+- 业务表单实现 `get_process_variables()` 和 `ap_save()`。
+- `editStatus` 和路由参数共同决定字段是否可编辑。
+- 保存草稿返回 Promise，供流程引擎调用。
+- 流程标识、系统类型、租户字段不要硬编码，优先从配置或 props 传入。
+
+## 15. 动态表单入口
+
+适用场景：后台表单设计器配置出的动态表单页面。
+
+推荐结构：
+
+```text
+src/views/<module>/<page>/index.vue
+```
+
+生成要点：
+
+- 使用 `FormRender` 前确认 `@gushen/gushen-form-render` 插件是否已注册。
+- 动态表单页面通常不写业务字段，只负责挂载渲染器和同步路由标题。
+- 如果菜单参数已经声明动态表单，优先走 `permission.ts` 的动态表单路由处理，不新建手写 CRUD。
+
+## API 模板模式
+
+新增 API 时按业务复杂度选择：
+
+- 标准 CRUD：`findPagination`、`save`、`update`、`getById`、`delete`。
+- 导入导出：列表查询、模板下载、导入上传、导出下载、历史记录。
+- 树结构：树查询、节点新增、节点更新、节点删除、拖拽排序。
+- 授权类：主体查询、权限查询、授权保存、授权删除、回显详情。
+- 日志类：分页查询、详情查询、统计总数、趋势、TopN。
+
+API 生成约束：
+
+- 不复用参考工程接口前缀；先参考目标工程同模块 API 风格。
+- POST 保存/更新通常使用 `{ params }` 包装。
+- 文件下载使用 Blob 时要释放 URL。
+- 用户可见错误和成功提示走 i18n。
+
+## 不建议直接迁移的模式
+
+- 依赖专有设计器、Monaco、打印设计器、复杂工作流 SDK 的页面：目标工程未必具备依赖，应先确认包和注册方式。
+- 深度绑定平台权限模型、租户模型、接口导入协议的页面：只迁移结构，不迁移字段和接口。
+- 大量 Options API mixin 的旧页面：新页面优先用 `script setup` 重写结构。
+- 使用参考工程专属本地组件的页面：必须替换为目标工程已有组件或先补组件。

package/references/vue3-front-standard/project-overview.md

@@ -0,0 +1,48 @@
+# 项目结构与入口规则
+
+## 技术栈
+
+- Vue 3 + TypeScript + Vite。
+- Element Plus 全量注册，Element Plus 图标在 `src/core/initMain.ts` 中全局注册。
+- `@gushen/gushen-common-components` 通过 `instance.use(GsComponents)` 全局注册，并引入组件库 CSS。
+- `@gushen/gushen-form-render` 依赖存在，但当前 `src/core/initMain.ts` 中插件注册被注释；使用 `FormRender` 前先确认是否需要启用插件注册。
+- 当前 `package.json` 未安装 `@gushen/gushen-work-flow`；流程相关页面主要作为壳层/包装层存在，若要直接使用工作流组件，先补依赖并确认注册方式。
+
+## 关键入口
+
+- 应用入口：`src/main.ts`
+- 插件、全局属性、全局组件：`src/core/initMain.ts`
+- 本地全局组件：`src/components/global-register.ts`
+- 路由：`src/router/index.ts`
+- 动态菜单与路由守卫：`src/permission.ts`
+- 页面：`src/views`
+- API：`src/api`
+- 语言包：`src/lang`、`src/lang/modules`
+
+## 代码风格
+
+- 新增 Vue 页面优先使用 Vue 3 `script setup lang="ts"`；维护旧页面时可沿用 Options API。
+- 新增业务代码不要使用 `// @ts-nocheck`。
+- `ref([])`、`reactive({})`、回调参数要显式类型，避免 `vue-tsc` 隐式 `any`。
+- 类型导入使用 `import type`。
+- 不要把 `isc-web-ui` 中依赖本地组件的规则照搬到本工程，除非本工程已有同名组件或先补齐组件。
+
+## 路由规则
+
+- 静态路由集中在 `src/router/index.ts` 的 `routes`。
+- 主布局子页面放在根路由 `/` 的 `children` 中，常用 meta：`title`、`enTitle`、`icon`、`noCache`、`hideInMenu`、`isBootstrap`。
+- 普通业务页优先走后台菜单动态路由：`src/permission.ts` 的 `formatRoutes` 会按 `menuUrl` / `originalAddr` 动态加载 `@/views${componentPath}/index.vue`。
+- 新建业务页通常放在 `src/views/{菜单路径}/index.vue`，菜单平台配置 `menuUrl` 后即可加载；不要默认修改 `src/router/index.ts`。
+- 只有登录页、首页、消息中心、个人中心等壳内固定页才补 `src/router/index.ts`。
+- HTTP 菜单会走 `src/views/third-view.vue` iframe；动态表单菜单通过 `handleDynamicFormRoute` 映射到固定动态表单入口。
+
+## 全局属性
+
+`src/core/initMain.ts` 中注入：
+
+- `this.$http` / `window.$request`：请求工具。
+- `this.reqIsSucceed`：统一成功判断。
+- `this.$bus`：事件总线。
+- `window._config`：运行配置。
+
+新增 Composition API 页面需要使用这些能力时，优先直接 import 对应工具函数；只有维护旧 Options API 页面时才使用 `this.xxx`。