前端开发规范
前端开发规范
约束 am-web/src/（基座管理端）的分层与页面写法。技术栈 Vue 3.5 + TS + Vite + Element Plus + Pinia，表格页基于 ArtDesign Pro 的 useTable/ArtTable 体系。
目录分层
am-web/src/
├── api/{module}/ # 接口封装，一实体一文件，可按业务域分目录
├── views/{module}/ # 页面；列表页 index.vue，子组件放 modules/
├── components/ # 全局复用组件
├── hooks/ store/ router/ directives/ utils/API 层
位置 src/api/{module}.ts（或 src/api/{module}/index.ts）。统一从 @/utils/http 走，返回类型标注 Api.Common.ApiData；GET 用 params、POST 用 data；URL 与后端路由一致；每个方法带 JSDoc（说明/参数/返回）。
方法命名约定：
| 后端 | 前端 | 说明 |
|---|---|---|
index | list | 唯一特例，前端用 list 更贴语义 |
read/save/update/delete/batchDelete/changeStatus | 同名 | 前后端一致，便于排查 |
只写实际用到的方法，不凑空壳。同业务域多实体可拆子目录，index.ts 作入口：import notifyApi from '@/api/notify'、import smsProviderApi from '@/api/notify/sms-provider'。
响应分页键是 page
拦截器按 code 分流、读 msg 做提示，列表分页数据键是 {list, total, page}。旧文档里出现的 current 与后端 ret() 实际产出的 page 不一致，以 page 为准。
视图层
列表页 views/{module}/index.vue 用 <script setup lang="ts">，defineOptions({ name: '{Module}' })（keep-alive 依赖组件名）。标准表格页：
useTable（hooks/core/useTable）拿columns/columnChecks/data/loading/pagination/getData/searchParams/resetSearchParams/handleSizeChange/handleCurrentChange/refreshData，core.apiFn指api.list，apiParams带current/size与搜索默认值，columnsFactory定义列（操作列useSlot: true、fixed: 'right'）。tableOperation（mixins/tableOperation）拿dialogType/dialogVisible/dialogData/showDialog/selectedRows/batchDelete/deleteRow/handleSelectionChange等 CRUD 通用状态。- 搜索栏、弹窗拆成
modules/{module}-search.vue、modules/{module}-dialog.vue独立组件。 - 布局类用
art-full-height、art-table-card适配高度。
按需取舍：useTable/tableOperation 只适合标准 CRUD 列表页。监控/统计/缓存管理等非表格页可 onMounted 里手动 api.getXxx() 加载，不必套模板；只读或特殊交互页同理。
搜索栏参数名
useTable 的 apiParams 用 current/size 作为分页入参（前端分页语义），后端返回结构用 page/total。两者由 useTable 适配，别把入参 current 当成返回 current 去读。
组件
- 搜索组件：
ArtSearchBar+defineModel+defineEmits(['search','reset'])，items声明字段。 - 弹窗组件：
ElDialog+ElForm（formRef.validate()），defineModel<boolean>('visible')，按type切save/update，提交后emit('submit')、关闭并resetFields()。 - 组件名大驼峰、变量小驼峰、常量全大写。
权限与指令
按钮/元素用 v-auth="'system:{module}:{action}'" 控制显隐，值与后端 #[Permission] 的 slug 完全一致。详见权限控制规范。
风格与安全
缩进 2 空格、单引号为主（JSON 双引号）、必加行尾分号、行宽 ≤120、方法间空行。安全：慎用 v-html（XSS）、图片懒加载、列表分页、搜索防抖（默认 500ms）、组件按需加载。