前端结构

React 与 Vue 模板采用同一套功能划分：按业务域拆分 API 与类型，页面放在 pages/，共享技术代码放在 components/ 与 lib/（Vue 为 stores/、composables/）。

请求层

前端 HTTP 层是一个轻量的原生 fetch 封装 src/api/client.ts，不使用 axios。

基础地址固定为 /api，开发时由 Vite 代理到 localhost:8088。
自动附加 Authorization: Bearer <token>。
收到 401 时清除登录状态并跳转登录页。
统一解析 { code, message, data }，code !== 0 时抛出错误消息。
支持二进制下载、FormData 上传和自定义状态头，用于数据导出、导入与任务轮询。

各业务域的调用拆分在 src/api/ 下：auth.ts、user.ts、role.ts、permission.ts、menu.ts、system.ts、dashboard.ts、ai-model.ts、audit-log.ts、data-management.ts。

React
Vue

// src/api/client.ts（示意）
const BASE_URL = '/api';

export async function request<T>(path: string, options?: RequestInit): Promise<T> {
  const res = await fetch(`${BASE_URL}${path}`, {
    ...options,
    headers: { 'Content-Type': 'application/json', ...options?.headers },
  });
  // 401 → 清除 token 并跳转 /login
  // code !== 0 → throw new Error(message)
  return body.data;
}

// src/api/client.ts（示意）
const BASE_URL = '/api';

export async function request<T>(path: string, options?: RequestInit): Promise<T> {
  const res = await fetch(`${BASE_URL}${path}`, {
    ...options,
    headers: { 'Content-Type': 'application/json', ...options?.headers },
  });
  // 401 → 清除 token 并跳转 /login
  // code !== 0 → throw new Error(message)
  return body.data;
}

路由与鉴权

路由使用 react-router（React）或 vue-router（Vue）。
ProtectedRoute（Vue 为路由守卫）只校验是否已登录；未登录跳转登录页。
侧边栏调用 GET /api/menus/navigation 动态加载；后端按当前用户权限过滤，分组内没有可见菜单时整组隐藏。
菜单顺序、分组、路由和图标来自 menu_groups / menu_items，不再硬编码在 AppSidebar 中。
真正的访问控制在后端：前端隐藏菜单只是体验优化，后端仍按权限点拒绝越权请求。

安全提示：不要只依赖前端路由做权限判断，服务端才是权威。详见权限系统。

状态管理

	React	Vue
认证状态	`lib/auth-context.tsx`	`stores/auth.ts`（Pinia）
站点配置	`lib/site-config.tsx`	`stores/site-config.ts`
主题	`components/theme-provider.tsx`	`stores/theme.ts`

站点配置来自公开接口 GET /api/public/config，用于登录页显示站点名称、维护提示，以及判断是否开放注册。

界面约定与主题

后台界面面向电脑与平板设计；手机访问会显示「请更换设备」的提示组件（UnsupportedViewport）。
提供明暗主题切换（ThemeToggle），偏好会被持久化。
React 版集成 shadcn/ui，Vue 版使用 DaisyUI；表单、表格、分页、确认删除等共享组件位于 components/shared/。

React
Vue

React 版本包含 PWA 支持，构建产物可安装为桌面/移动应用。图标使用 lucide-react。

Vue 版本使用 lucide-vue-next 图标与 use-toast 组合式函数管理提示。注意：模板 package.json 仍列出了 axios 依赖，但全部请求都走 api/client.ts 的 fetch 封装，可以安全移除。

新增一个页面

以 React 为例：

在 src/pages/ 下新建页面组件。
在 router.tsx 注册路由。
为页面定义权限码，并在菜单管理中创建或同步菜单项、设置路由和图标。
在 src/api/ 与 src/types/ 下补充该业务域的调用与类型。

Vue 对应修改 pages/、router/index.ts、api/、types/，菜单配置仍在后台完成。