一个前端CLAUDE.md

技术栈

• 框架: Nuxt 4, Vue 3.5, TypeScript 6
• UI: Nuxt UI v4（Reka UI + Tailwind CSS v4），Dashboard 系列组件（UDashboardPanel, UDashboardNavbar, UDashboardSidebar, UDashboardSearch, UDashboardToolbar）
• 表格: @tanstack/table-core，UTable 集成排序/筛选/分页/行选择
• 工具库: @vueuse/core（createSharedComposable, useBreakpoints）, date-fns, scule, zod
• 图表: @unovis/vue（仅客户端渲染，见 HomeChart.client.vue / HomeChart.server.vue）

Nuxt UI v4 核心规范

• 必须 在 app.vue 和 error.vue 中使用 <UApp> 包裹页面
• 禁止 使用 Tailwind 原生色名（red, green, gray），必须 使用语义化别名：primary, secondary, success, info, warning, error, neutral
• 弹窗统一用 v-model:open，内容放 #body 插槽
• 自定义组件样式在 app.config.ts 中用 slots 和 defaultVariants 配置
• Dashboard 页面必须 用 <UDashboardPanel> 包裹，<template #header> 放 <UDashboardNavbar>，<template #body> 放页面内容

编码规范

核心架构：Composable + 三类数据

"一个视图组件对应一个逻辑 Composable"，强制分离逻辑与视图。

在 Composable 中用 reactive() 声明三类数据：

前缀	用途	特点
pageStaticData	静态/配置数据	页面生命周期内不变：字典项、常量
pageStatusData	状态/响应式数据	驱动视图：loading、tableData、errorMsg
pageSubmitData	提交数据	与接口契约严格一致

必须 暴露 initPage() 作为初始化和重置入口：

async function initPage() {
  _initStaticData(); _initStatusData(); _initSubmitData()
  await fetchTableData()
}

函数规范

• 最少代码原则：用最少的代码实现功能，不写一行多余的代码。
• 避免 watch / computed ：尽量用函数直接返回值替代 computed，用事件回调替代 watch，减少响应式链路复杂度。
• 公共函数 ：暴露给组件，包含副作用。私有函数 ：_ 开头，纯函数，无副作用。
• 复杂逻辑遵循 校验 → 处理 → 提交 三步。
• 特例：仅完全静态无交互的纯展示页才可把 script 直接写在 .vue 中。

命名约定

• 组件: PascalCase；Composable: use 开头与组件同名；文件/目录: kebab-case
• 变量: camelCase；私有函数: _ 开头；类型/接口: PascalCase

组件规范

• .vue 只负责模板结构、样式绑定、事件绑定、UI 状态展示。
• 拆分：单组件 ≤300 行，>3 个 v-if 分支拆子组件，重复 UI 块抽取。
• 通信：父传子 defineProps，子传父 defineEmits（事件 kebab-case），跨层级 Pinia 或 provide/inject。
• 禁止 ：直接修改 props、使用 $refs 操作子组件。

TypeScript

• 必须 import type 导入纯类型。类型不 被 Nuxt 自动导入，需显式 import，使用 ~/types 别名
• 严禁 any、as 强制断言（API 响应转换除外）

错误处理模式

• 私有函数 ：只调 API，throw 向上传递。公共函数 ：try-catch，转为友好信息写入 pageStatusData.errorMsg。
• 错误信息对用户友好，不直接展示技术错误。

API 对接

• 所有业务 API 通过 useAPI() 访问后端 http://localhost:48080/admin-api/
• 后端响应统一格式：{ code: 0, data: ..., msg: ... }，code === 0 || 200 表示成功
• server/api/ 目录保留原有 mock 端点（模板页面使用），与后端 API 互不冲突
• 数据变更后需调用 refresh() 刷新关联数据

Git 提交

<type>(<scope>): <subject>
类型: feat / fix / refactor / style / docs / chore