前端约定

优先参考的代码来源

当前 boot4 仓库通常只含后端与 generator 前端模板；如果前端工程不在当前 root，先以 generator 模板约定为准，再对照用户提供的前端目录或相邻仓库。

gen_table.frontend_type 存字符串，值直接对应 vm 下的模板目录，例如 vue、react。
生成器按 vm/<frontendType>/api.ts.vm、types.ts.vm、index.*.vm、index-tree.*.vm 查找模板。
页面输出后缀由页面模板文件名决定：index.vue.vm 输出 index.vue，index.tsx.vm 输出 index.tsx。
新增其他前端时优先只新增 vm/<frontendType> 目录和对应 VM 文件，不在 Java 代码里增加数字枚举或硬编码分支。

从 @/utils/request 引入 request。
从 @/utils/api-types 引入 AxiosPromise。
从 @/api/types 引入 PageResult。
从 @/api/<module>/<business>/types 引入本模块类型。
列表接口通常返回 AxiosPromise<PageResult<Vo>>。
常规接口命名和路由保持： listXxx -> GET /<module>/<business>/list getXxx -> GET /<module>/<business>/{id} addXxx -> POST /<module>/<business> updateXxx -> PUT /<module>/<business> delXxx -> DELETE /<module>/<business>/{id or ids}

使用 <script setup lang="ts">。
常见 import 来自本模块 API 和本地 types。
新版生成器优先使用 hooks：useLoading、useSearchToggle、useSearchReset、useTableSelection、useFormDialog，日期范围使用 useDateRangeQuery。
字典通常通过 toRefs<any>(useDict(...)) 解构。
常见状态包括：列表数组、loading、buttonLoading、showSearch、ids、single、multiple、total。
查询和表单状态通常放在 reactive<PageData<Form, Query>>({...}) 中，并通过 toRefs(data) 暴露。
弹窗状态优先由 useFormDialog 返回的 dialog、openDialog、showDialog、closeDialog 管理。
表单引用通常命名为 queryFormRef 和 <business>FormRef。

getList 负责通过 withLoading 设置 loading、处理日期范围参数、调用列表接口、回填 rows 和 total。
handleQuery 通常先把 pageNum 重置为 1，再重新查询。
resetQuery 优先使用 useSearchReset，通过 resetExtras 清空日期范围，再重新加载。
handleSelectionChange 优先使用 useTableSelection 返回的方法，更新 ids、single、multiple。
handleAdd 先重置表单，再通过 openDialog 打开弹窗。
handleUpdate 先重置并查详情，再 Object.assign(form.value, res.data)，最后通过 showDialog 打开弹窗。
submitForm 校验表单、切换 buttonLoading、根据主键判断调用新增还是更新、提示成功并刷新列表。
handleDelete 使用 modal.confirm(...) 确认，再调用删除接口并刷新。
handleExport 使用 download as requestDownload 从 @/utils/request 导出的下载方法。

优先保持生成器的页面布局结构：搜索区卡片、表格区卡片、工具栏、分页、弹窗表单。
保留 v-hasPermi="['module:business:add']" 这类权限指令。
继续使用仓库已有组件：right-toolbar、pagination、dict-tag、image-preview、image-upload、file-upload、editor。
已有页面对时间列使用 parseTime 时，新页面保持一致。
BETWEEN 日期查询继续使用 el-date-picker，脚本侧通过 useDateRangeQuery 生成 dateRangeXxx、applyXxxDateRange、resetXxxDateRange。