xiaozhi-admin-ui/.codex/skills/frontend-crud-coding/references/frontend.md

# 前端约定

## 优先参考的代码来源

- 关联后端工程中的生成器模板：
  `ruoyi-modules/ruoyi-gen/src/main/resources/vm/ts/*.vm`
  `ruoyi-modules/ruoyi-gen/src/main/resources/vm/vue/*.vm`
- `src/api/system/user/index.ts`
- `src/api/system/user/types.ts`
- `src/views/system/user/index.vue`
- `src/views/demo/demo/index.vue`
- `src/views/system/*`
- `src/views/workflow/*`
- `src/components/*`
- `src/assets/styles/components/*`

## 基础栈与格式

- 技术栈是 Vue 3 + TypeScript + Element Plus + Vite。
- 请求统一通过 `@/utils/request`。
- API 返回值类型常用 `AxiosPromise<T>`。
- 项目默认 2 空格缩进。
- 使用单引号和分号。
- 不要在一个页面里混入与仓库不一致的格式和写法。

## 决策顺序

写代码时按下面顺序取样：

1. 当前业务目录下最近似页面。
2. 当前模块下最近似 API/types 文件。
3. 当前项目的公共组件、公共工具、公共样式。
4. 关联后端工程的 generator 模板。
5. 通用 Vue 3 / Element Plus 默认写法。

如果上述规则冲突，优先相信当前项目真实代码。

## API 文件规则

- 标准 CRUD 的 API、types、列表页骨架可以先参考后端生成器模板，再根据当前前端项目风格落地。
- API 文件通常放在 `src/api/<module>/<business>/index.ts`。
- 同目录维护 `types.ts`。
- 常见 import 形式：
  `import request from '@/utils/request';`
  `import { AxiosPromise } from 'axios';`
  `import { XxxForm, XxxQuery, XxxVO } from './types';`
  `import { PageResult } from '@/api/types';`
- 列表接口通常返回 `AxiosPromise<PageResult<XxxVO>>`。
- 详情接口返回 `AxiosPromise<XxxVO>` 或更复杂的 `InfoVO`。
- 特殊请求参数沿用现有实现，例如：
  `parseStrEmpty(userId)`
  `headers: { isEncrypt: true, repeatSubmit: false }`
  `params` 用于 query string，`data` 用于 body。
- 当前仓库部分模块会在文件底部 `export default { ... }`，已有模块使用这种形式时继续保持一致。

### API 文件建议结构

标准 CRUD 一般按这个顺序组织：

1. import 区
2. 列表接口
3. 详情接口
4. 新增接口
5. 修改接口
6. 删除接口
7. 特殊接口
8. 可选的 `export default`

### API 常见判断

- 如果后端是列表分页接口，前端通常返回 `AxiosPromise<PageResult<XxxVO>>`。
- 如果后端返回复合结构，例如 `user + roles + posts`，单独定义 `InfoVO`。
- 如果接口需要加密或关闭重复提交，直接在 `headers` 里表达，不要另起封装。

## 类型文件规则

- 类型文件通常定义 `Query`、`VO`、`Form`，必要时补 `InfoVO`、`ResetPwdForm` 等扩展类型。
- `Query` 一般继承 `PageQuery`。
- `VO` 常继承 `BaseEntity`。
- ID 字段通常使用 `string | number`。
- 列表页多选 ID 常用 `Array<string | number>`。
- 数组字段在表单里常直接用 `string[]`、`number[]` 或宽松类型，优先跟随现有模块。

### 类型拆分建议

- `VO` 面向列表和详情展示。
- `Form` 面向新增和编辑。
- `Query` 面向列表筛选。
- `InfoVO` 面向详情页、编辑页、弹窗预加载等复合返回结构。

### 类型字段策略

- 能明确写出类型时，不要偷懒用 `any`。
- 只有在当前模块已有宽松写法或后端返回非常不稳定时，才保留 `any`。
- 如果列表和表单字段明显不同，不要强行复用一个接口类型。

## Vue 页面结构规则

- 标准 CRUD 页可先参考生成器的 `index.vue.vm` 骨架，再按本仓库现有页面补强。
- 页面优先使用 `<script setup name="Xxx" lang="ts">`。
- 常见列表页结构：
  搜索区卡片、表格区卡片、工具栏、分页、编辑弹窗。
- 常见页面状态包括：
  `loading`、`showSearch`、`ids`、`single`、`multiple`、`total`。
- 表单和查询对象通常通过 `reactive<PageData<Form, Query>>({...})` 管理。
- 弹窗状态通常使用：
  `const dialog = reactive<DialogOption>({ visible: false, title: '' });`
- 表单 ref 通常命名为 `queryFormRef`、`xxxFormRef`。
- 复杂页面可补充树面板、导入弹窗、子弹窗、路由跳转逻辑。

### 标准页面骨架

标准页面通常包含这些区域：

1. 搜索区
2. 表格区
3. 工具栏
4. 分页
5. 编辑弹窗

复杂页面可以额外增加：

- 左侧树筛选
- 导入弹窗
- 二级对话框
- 独立详情页
- 路由跳转按钮
- 列显隐控制

### 页面命名建议

- 页面组件名通常为业务名，例如 `name="User"`、`name="Demo"`。
- 页面根类名尽量带模块语义，例如：
  `system-user-page`
  `demo-demo-page`
  `workflow-category-page`

## 页面行为规则

- `getList` 负责发起列表请求、处理 loading、回填 `rows` 和 `total`。
- `handleQuery` 先把 `pageNum` 置为 `1`，再重新查询。
- `resetQuery` 负责清空查询表单、日期范围、树节点选择，然后重新加载。
- `handleSelectionChange` 更新 `ids`、`single`、`multiple`。
- `handleAdd` 重置表单并打开新增弹窗。
- `handleUpdate` 查详情后回填表单并打开编辑弹窗。
- `submitForm` 使用表单校验，通过后调用新增或修改接口，再提示成功并刷新列表。
- `handleDelete` 通常使用 `proxy?.$modal.confirm(...)` 二次确认。
- `handleExport` 使用 `proxy?.download(...)`。
- 日期范围查询沿用 `proxy?.addDateRange(queryParams.value, dateRange.value)`。
- 需要更稳妥地处理确认框或异步异常时，可沿用 `await-to-js` 的 `to(...)` 风格。

### 页面逻辑建议

- 新增和编辑优先共用一套弹窗和表单。
- `reset()` 与 `cancel()` 分开写，避免关闭弹窗时状态残留。
- `handleUpdate()` 先查详情再 `Object.assign(form.value, res.data)`。
- 删除、状态切换、解锁、重置密码这类危险操作优先保留确认提示。
- 列表页只做列表页职责，复杂复合逻辑优先拆到子组件或独立页面。

## 字典、权限与公共工具

- 字典通常通过：
  `const { xxx_dict } = toRefs<any>(proxy?.useDict('xxx_dict'));`
- 权限指令以仓库现状为准，存在 `v-hasPermi` 和 `v-has-permi` 两种写法；新增代码优先跟随所在目录附近文件，不要在同一文件里混用新的变体。
- 常用公共能力：
  `proxy?.$modal`
  `proxy?.download`
  `proxy?.useDict`
  `proxy?.getConfigKey`
  `checkPermi`
  `useUserStore`

### 权限规则

- 所有增删改导入导出按钮都先看附近页面是否有权限控制。
- 新按钮默认补权限指令，除非它是纯展示行为。
- 如果同目录页面使用 `v-hasPermi`，新代码优先继续用 `v-hasPermi`。
- 如果同目录页面使用 `v-has-permi`，新代码优先继续用 `v-has-permi`。

## 组件与样式规则

- 优先复用公共组件：
  `right-toolbar`
  `pagination`
  `ImageUpload`
  `ImagePreview`
  `FileUpload`
  `Editor`
  `DictTag`
- 页面样式不要堆大量内联样式，优先沿用仓库里的布局类和组件样式。
- 已有页面使用 SCSS 模块片段时，继续沿用：
  `@use '@/assets/styles/components/page-shell' as pageShell;`
  `@include pageShell.xxx;`
- 类名命名保持模块化，例如：
  `system-user-page`
  `demo-demo-page`
  `table-panel`
  `search-panel`
  `toolbar-shell`

### 样式落点建议

- 页面只需要轻量调整时，优先复用已有通用类。
- 页面结构明显复杂时，优先在 `<style lang="scss" scoped>` 中通过 `@use` 复用组件样式片段。
- 不要为了单页需求破坏全局组件样式。

## 与生成器模板的关系

- 关联后端工程生成器给出的前端结构可以作为起点，但真实页面通常更完整，包含：
  树筛选、列显隐、导入导出、更多操作、SCSS 页面壳、复杂表单校验、独立子页面。
- 因此新增页面时，不要只满足“能跑”，要先看所在模块已有页面的复杂度和 UI 组织方式。

### 什么时候优先看 generator

- 新增一个标准单表 CRUD 页面时。
- 当前项目里还没有这个业务对应页面时。
- 你只拿到了后端路由和字段信息时。

### 什么时候优先看现有页面

- 当前模块已经有同类页面时。
- 页面包含树筛选、导入导出、联动弹窗、路由跳转时。
- 任务是“修改已有页面”而不是“新建页面”时。

## 避免事项

- 不要直接把后端仓库里的前端模板原样复制进来。
- 不要跳过 `types.ts`，把类型全堆在页面里。
- 不要绕开 `request` 自己再包一层请求工具。
- 不要引入与仓库现状不一致的 CSS 组织方式。
- 不要为了省事删掉权限控制、导出、导入、树筛选、日期范围等现有交互能力。

## 交付前自检

交付前至少检查这些点：

- 页面能否完整走通查询、新增、编辑、删除、导出流程。
- 类型是否与接口返回结构一致。
- 是否保留了原页面已有的权限和交互能力。
- 是否沿用了当前模块已有的组件和样式壳。
- 是否只是“生成器裸页”，如果是，需要继续补齐到当前项目风格。