mica-admin: Skill for Claude Code

mica-admin-web 前端开发

Vue 3.5 + Naive UI 2.44 + Vite 6 + TS 5.7 + Tailwind 4 + Pinia 3。Vben Admin 5.x 已源码本地化到 vben/，由 vite.config.ts 的 vbenResolver() 解析 @vben/*、@vben-core/* 别名。

目录约定

src/api/<module>/<res>.ts     # 接口层（system / monitor / oss / core）
src/views/<module>/<res>/index.vue   # 页面
src/store/                    # 业务 Pinia store（单文件直接 export）
src/adapter/                  # UI 适配层（naive discrete api、组件注册、form、vxe-table）
src/utils/                    # format-date、export-excel、rsa
src/locales/langs/{zh-CN,en-US}/

路径别名是 #/ → src/（不是 @/）。

完整可复制模板见 references/crud-page.md。

硬性约定

响应处理 — src/api/request.ts 已配 defaultResponseInterceptor({ successCode: 0, codeField: 'code', dataField: 'data' })。后端成功 code = 0，成功时返回裸数据体。api 是共享实例，业务接口直接 import { api } from '#/api/request'。

分页 — 后端返回 MyBatis-Plus IPage（{ records, total }），接口层必须用 parsePage<T>() 统一成 { list, total }，页面只消费 { list, total }：

const data = await api.get<any>('/api/system/banner', { params });
return parsePage<BannerItem>(data);

错误处理 — 全局拦截器已处理 401/403/超时并弹 notification，{ msg } 已提升为 Error.message。页面里 catch 只需 console.error，不要重复弹错误提示。需要自己接管时请求 config 传 { skipErrorHandler: true }。

Excel 导出 — 用 exportExcel({ api, url, filename, params })（#/utils/export-excel），对应后端 @ResponseExcel 的 download 接口。

弹窗 — 用 useVbenModal（@vben-core/popup-ui）：const [Modal, modalApi] = useVbenModal({ onConfirm })，modalApi.setState({ title }).open() / .close() / .lock() / .unlock()。确认框用 dialog.warning()（#/adapter/naive），不要用原生 confirm()。

表格 — NDataTable + 独立 NPagination。选择用 :checked-row-keys + @update:checked-row-keys，不要用 :selection / @update:selection-keys。列渲染用 h()，状态列用 NTag，操作列 fixed: 'right'。

权限 — 按钮用指令 v-access:code="'system:banner:add'"；h() 里渲染的操作按钮用 useAccess() 的 hasAccessByCodes([...])。权限码与后端 sys_menu.perms 完全一致，动作用 list/query/add/edit/del/export（:del 不是 :remove）。