add 增加 ai编程支持 支持codex与claude的skill
This commit is contained in:
疯狂的狮子Li
@@ -0,0 +1,112 @@
|
||||
# 使用案例
|
||||
|
||||
## 案例 1：新增标准 CRUD 页面
|
||||
|
||||
### 用户提问示例
|
||||
|
||||
```text
|
||||
使用 $frontend-crud-coding 为 system/client 补一套前端 CRUD 页面。
|
||||
后端接口已经有 /system/client/list、/system/client/{id}、POST /system/client、PUT /system/client、DELETE /system/client/{ids}。
|
||||
请参考 generator 模板和现有的 system/user、system/config 页面风格实现。
|
||||
```
|
||||
|
||||
### 期望执行方式
|
||||
|
||||
- 先看 `src/api/system/client/*` 是否已存在。
|
||||
- 再看 `src/views/system/client/index.vue` 是否为空或缺失。
|
||||
- 参考同目录系统模块页面，确定是否需要搜索卡片、表格卡片、弹窗、导出按钮。
|
||||
- 再参考关联后端工程中的 generator 模板，补齐基础骨架。
|
||||
|
||||
### 期望产物
|
||||
|
||||
- `src/api/system/client/index.ts`
|
||||
- `src/api/system/client/types.ts`
|
||||
- `src/views/system/client/index.vue`
|
||||
|
||||
## 案例 2：把 generator 模板落成当前项目风格
|
||||
|
||||
### 用户提问示例
|
||||
|
||||
```text
|
||||
使用 $frontend-crud-coding 按 generator 模板为 demo/order 生成一个标准页面，但不要直接复制模板，要改成当前前端项目现有样式壳和工具链写法。
|
||||
```
|
||||
|
||||
### 期望执行方式
|
||||
|
||||
- 先看 generator 的 `ts/types/index.vue` 模板。
|
||||
- 再看 `src/views/demo/demo/index.vue`、`src/views/system/user/index.vue` 的实际风格差异。
|
||||
- 生成的页面要使用当前项目里的 `right-toolbar`、`pagination`、`proxy?.$modal`、`proxy?.download` 等。
|
||||
|
||||
## 案例 3：修改已有列表页
|
||||
|
||||
### 用户提问示例
|
||||
|
||||
```text
|
||||
使用 $frontend-crud-coding 修改 system/user 页面：
|
||||
1. 新增一个创建时间快捷筛选
|
||||
2. 导出按钮放到更多菜单中
|
||||
3. 保持现有样式和交互不变
|
||||
```
|
||||
|
||||
### 期望执行方式
|
||||
|
||||
- 优先阅读现有 `src/views/system/user/index.vue`。
|
||||
- 判断这是“已有页面增强”，不是“重新生成页面”。
|
||||
- 保留树筛选、导入导出、列显隐、角色分配等现有能力。
|
||||
- 增量修改，而不是重写整个页面。
|
||||
|
||||
## 案例 4：补齐复杂业务页面
|
||||
|
||||
### 用户提问示例
|
||||
|
||||
```text
|
||||
使用 $frontend-crud-coding 为 workflow/category 增加导入、导出和状态切换功能，参考 system/user 的完整页面能力，但保持 workflow 模块自己的风格。
|
||||
```
|
||||
|
||||
### 期望执行方式
|
||||
|
||||
- 优先看 `src/views/workflow/category/index.vue`。
|
||||
- 再看 `src/views/system/user/index.vue` 里复杂列表页的做法。
|
||||
- 只迁移需要的能力，不把用户模块专属逻辑照搬到 workflow 页面。
|
||||
|
||||
## 案例 5：只补 API 和 types
|
||||
|
||||
### 用户提问示例
|
||||
|
||||
```text
|
||||
使用 $frontend-crud-coding 为 monitor/cache 补全前端 API 和 types，页面先不改。
|
||||
```
|
||||
|
||||
### 期望执行方式
|
||||
|
||||
- 只维护 `src/api/monitor/cache/index.ts` 和 `src/api/monitor/cache/types.ts`。
|
||||
- 仍然要与后端路由、现有 API 风格、返回类型保持一致。
|
||||
|
||||
## 案例 6：推荐的高质量任务描述
|
||||
|
||||
下面这种描述最容易得到稳定结果：
|
||||
|
||||
```text
|
||||
使用 $frontend-crud-coding 在当前前端项目中新增一个 `/system/notice` 列表页增强：
|
||||
1. 保留现有页面
|
||||
2. 新增状态筛选和导出
|
||||
3. API 路径沿用后端现有接口
|
||||
4. 参考 system/user 的工具栏与导出交互
|
||||
5. 参考 generator 模板补齐缺失的 types 定义
|
||||
```
|
||||
|
||||
## 不推荐的任务描述
|
||||
|
||||
下面这种描述太模糊，容易让产物偏离项目：
|
||||
|
||||
```text
|
||||
帮我写个后台页面
|
||||
```
|
||||
|
||||
更好的写法至少要补充：
|
||||
|
||||
- 模块名
|
||||
- 业务名
|
||||
- 后端接口前缀
|
||||
- 是新增还是修改
|
||||
- 想参考哪个现有页面
|
||||
@@ -0,0 +1,241 @@
|
||||
# 前端约定
|
||||
|
||||
## 优先参考的代码来源
|
||||
|
||||
- 关联后端工程中的生成器模板：
|
||||
`ruoyi-modules/ruoyi-generator/src/main/resources/vm/ts/*.vm`
|
||||
`ruoyi-modules/ruoyi-generator/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 组织方式。
|
||||
- 不要为了省事删掉权限控制、导出、导入、树筛选、日期范围等现有交互能力。
|
||||
|
||||
## 交付前自检
|
||||
|
||||
交付前至少检查这些点：
|
||||
|
||||
- 页面能否完整走通查询、新增、编辑、删除、导出流程。
|
||||
- 类型是否与接口返回结构一致。
|
||||
- 是否保留了原页面已有的权限和交互能力。
|
||||
- 是否沿用了当前模块已有的组件和样式壳。
|
||||
- 是否只是“生成器裸页”，如果是，需要继续补齐到当前项目风格。
|
||||
Reference in New Issue
Block a user