前端约定

优先参考的代码来源

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

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

Vue 模板从 @/utils/request 引入 request，从 @/utils/api-types 引入 AxiosPromise，从 @/api/types 引入 PageResult。
React 模板从 @/api/request 引入 request，从 @/api/types 引入 R、PageResult。
本模块类型：Vue 模板从 @/api/<module>/<business>/types 引入，React 模板从 ./types 引入。
Vue 列表接口通常返回 AxiosPromise<PageResult<Vo>>；React 列表接口通常返回 request<R<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}

定义 VO、Form、Query。
Form 通常继承 BaseEntity。
非树表页面的 Query 通常继承 PageQuery。
各类 ID 字段通常用 string | number。
Java 数值类型通常映射为 number。
Boolean 映射为 boolean。
其他生成字段默认多为 string。
存在日期范围查询时保留 params：Vue 模板通常是 params?: any，React 模板通常是 params?: Record<string, unknown>。

使用 <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。

使用 index.tsx，组件默认导出 <BusinessName>Page。
页面主体优先沿用 Ant Design Pro：PageContainer、ProTable、ModalForm、ProColumns、ActionType。
表单优先使用 Form.useForm<Form>()，弹窗开关优先使用 ahooks 的 useBoolean。
权限通过 useUserStore 取 userInfo，再用 hasPermi(userInfo, ['module:business:action']) 生成 canAdd、canEdit、canRemove、canExport。
表格选择使用 useTableSelection<VO>(row => row.id)；表格刷新使用 actionRef.current?.reload() 或 reloadAndRest?.()。
字典使用 useDict 和 dictOptions，展示使用 DictTag。
日期范围使用 useDateRangeQuery，在 ProTable 的 request 中由 toPageQuery(params) 转查询参数后再应用范围字段。
导出使用 useTableExport，路径保持 /<module>/<business>/export。
文件、图片、富文本组件使用 React 工程已有的 FileUpload、ImageUpload、ImagePreview、RichTextEditor。

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 导出的下载方法。

React ProTable 页面通过 request 回调加载列表并返回 toTableData(res)；新增、修改、删除成功后调用 actionRef 刷新。
React 弹窗提交函数根据主键判断调用新增还是更新，成功后 message.success('操作成功') 并重置表单。

优先保持生成器的页面布局结构，不在 Vue 和 React 之间互相移植组件体系。
Vue 保留 v-hasPermi="['module:business:add']" 这类权限指令。
Vue 继续使用仓库已有组件：right-toolbar、pagination、dict-tag、image-preview、image-upload、file-upload、editor。
React 继续使用仓库已有组件：RowActions、DictTag、ImagePreview、ImageUpload、FileUpload、RichTextEditor。
已有页面对时间列使用 parseTime 时，新页面保持一致。
Vue BETWEEN 日期查询继续使用 el-date-picker，脚本侧通过 useDateRangeQuery 生成 dateRangeXxx、applyXxxDateRange、resetXxxDateRange。
React BETWEEN 日期查询继续使用 ProTable 的 dateTimeRange 搜索列，查询侧通过 useDateRangeQuery 写入 params。

生成器风格页面不要突然换成完全不同的状态管理方式，除非该前端目录本身已经这么做。
模块已使用字典时，不要把选项文案硬编码到页面里。
不要让 API 函数名和路由段偏离后端约定。
后端 BO/service 依赖 begin/end 参数时，不要从查询对象里删掉 params 和日期范围处理。
不要把 Vue 的 proxy、v-hasPermi、Element Plus 组件写进 React 页面，也不要把 React 的 ProTable、ModalForm、Ant Design 权限判断写进 Vue 页面。