> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 前端概览

前端位于 `web/`，是基于 React 19 和 TypeScript 的单页应用。Vite 8 负责开发服务与构建，Ant Design 6 提供主要界面组件，Zustand 管理全局状态。

## 开发命令

```bash
cd web
pnpm install
pnpm dev       # 启动开发服务
pnpm build     # TypeScript 检查与生产构建
pnpm lint      # Oxlint 代码检查
pnpm preview   # 预览生产构建
```

## 源码分层

| 目录                     | 职责                               |
| ---------------------- | -------------------------------- |
| `src/pages/`           | 业务页面，同时参与文件系统路由生成                |
| `src/api/`             | 按 `system`、`common`、`ai` 等领域组织接口 |
| `src/components/`      | 表格、表单、上传、权限按钮等复用组件               |
| `src/domain/`          | 业务数据类型                           |
| `src/stores/`          | 用户、全局配置和字典等 Zustand 状态           |
| `src/layout/`          | 后台整体布局、导航和内容区域                   |
| `src/locales/`         | `zh_CN` 与 `en_US` 界面翻译           |
| `src/utils/request.ts` | Axios 实例、请求去重、认证和错误处理            |

## 接口地址

开发环境在 `web/.env.development` 中配置：

```dotenv
VITE_BASE_URL=http://localhost:8000
```

生产环境使用 `web/.env.production`。修改环境变量后需要重启 Vite。

## 请求约定

页面通常在 `src/api/` 中定义请求函数，而不是在组件内直接创建 Axios 实例：

```ts
import createAxios from '@/utils/request';

export function queryDept() {
  return createAxios({
    url: '/system/dept',
    method: 'get',
  });
}
```

请求封装会自动附加 `Authorization: Bearer <token>` 和 `User-Language`，并统一处理 401、重复请求和业务错误。后端响应结构见[接口响应约定](/backend/api-conventions.md)。