# 项目结构说明

## 目录结构

```
src/
├── assets/                 # 静态资源
│   └── react.svg
├── components/             # 通用组件
│   └── common/
│       ├── PermissionButton.tsx    # 权限按钮
│       └── PermissionWrapper.tsx   # 权限包装器
├── config/                 # 配置文件
│   ├── api.ts             # API 配置（前缀、超时等）
│   └── menuIds.ts         # 菜单 ID 常量
├── contexts/               # React Context
│   └── AuthContext.tsx    # 权限上下文
├── hooks/                  # 自定义 Hooks
│   └── usePermission.ts   # 权限检查 Hook
├── layouts/                # 布局组件
│   ├── Header.tsx         # 顶部导航
│   ├── MainLayout.tsx     # 主布局
│   └── Sidebar.tsx        # 侧边栏
├── pages/                  # 页面组件
│   └── ContentPage.tsx    # 内容页面
├── services/               # API 服务层
│   ├── api.ts             # API 统一导出
│   ├── BaseService.ts     # 基础服务类
│   ├── index.ts           # 服务总导出
│   └── modules/           # 业务模块
│       ├── content.ts     # 内容管理
│       ├── role.ts        # 角色管理
│       ├── system.ts      # 系统管理
│       └── user.ts        # 用户管理
├── types/                  # 类型定义
│   ├── axios.d.ts         # Axios 类型
│   └── menu.ts            # 菜单类型
├── utils/                  # 工具函数
│   ├── http/              # HTTP 请求封装
│   │   ├── Axios.ts       # Axios 封装类
│   │   ├── axiosTransform.ts  # 转换器接口
│   │   ├── checkStatus.ts     # 状态码检查
│   │   ├── helper.ts          # 辅助函数
│   │   └── index.ts           # 主入口
│   ├── message.ts         # 消息提示
│   ├── sign.ts            # 请求签名
│   └── tenant.ts          # 多租户管理
├── App.css
├── App.tsx                 # 应用根组件
├── index.css
└── main.tsx                # 应用入口

docs/                       # 文档目录
├── API_GUIDE.md           # API 使用指南
├── AXIOS_MIGRATION.md     # Axios 迁移说明
├── HTTP_COMPARISON.md     # HTTP 封装对比
├── PERMISSION_GUIDE.md    # 权限系统指南
├── PROJECT_STRUCTURE.md   # 项目结构说明（本文件）
├── PROXY_GUIDE.md         # 代理配置指南
└── QUICK_START.md         # 快速开始

public/                     # 公共资源
└── vite.svg

.env.example               # 环境变量示例
.env.development           # 开发环境配置
.env.production            # 生产环境配置
vite.config.ts             # Vite 配置
tsconfig.json              # TypeScript 配置
package.json               # 项目依赖
```

## 核心模块说明

### 1. HTTP 请求层 (`src/utils/http/`)

完整复刻 JeecgBoot 的 axios 封装：

- **Axios.ts** - VAxios 封装类，提供请求方法
- **axiosTransform.ts** - 定义转换器接口
- **checkStatus.ts** - HTTP 状态码检查和错误提示
- **helper.ts** - 辅助函数（时间戳、参数格式化等）
- **index.ts** - 主入口，配置拦截器和转换器

### 2. 服务层 (`src/services/`)

按业务模块组织的 API 服务：

- **BaseService.ts** - 基础服务类，提供通用 CRUD
- **api.ts** - 统一导出所有 API
- **modules/** - 业务模块
  - **system.ts** - 登录、权限、字典、上传
  - **user.ts** - 用户管理
  - **role.ts** - 角色管理
  - **content.ts** - 内容管理

### 3. 权限系统 (`src/contexts/`, `src/hooks/`, `src/components/common/`)

完整的权限管理方案：

- **AuthContext.tsx** - 权限上下文，管理菜单和权限数据
- **usePermission.ts** - 权限检查 Hook
- **PermissionButton.tsx** - 带权限控制的按钮
- **PermissionWrapper.tsx** - 权限包装器组件

### 4. 布局系统 (`src/layouts/`)

三栏布局结构：

- **MainLayout.tsx** - 主布局容器
- **Header.tsx** - 顶部导航，动态菜单
- **Sidebar.tsx** - 侧边栏，树形菜单

### 5. 工具函数 (`src/utils/`)

- **message.ts** - 消息提示（使用 Notification）
- **sign.ts** - 请求签名（MD5）
- **tenant.ts** - 多租户管理

### 6. 配置文件 (`src/config/`)

- **api.ts** - API 配置（前缀、超时、BASE_URL）
- **menuIds.ts** - 菜单 ID 常量

## 技术栈

- **React 19** - UI 框架
- **TypeScript** - 类型安全
- **Vite** - 构建工具
- **Axios** - HTTP 请求
- **Contentful F36** - UI 组件库
- **Crypto-JS** - 加密库（MD5 签名）

## 核心特性

1. ✅ **Axios 封装** - 完整复刻 JeecgBoot
2. ✅ **请求签名** - MD5 签名防篡改
3. ✅ **多租户支持** - 自动添加租户 ID
4. ✅ **权限管理** - 动态菜单 + 按钮权限
5. ✅ **Cookie 认证** - 自动携带 Cookie
6. ✅ **错误处理** - 统一的错误提示
7. ✅ **代理配置** - 开发环境跨域处理

## 开发规范

### 1. 组件组织

- `layouts/` - 布局组件
- `pages/` - 页面组件
- `components/common/` - 通用组件

### 2. 服务层组织

- `services/api.ts` - 系统级 API
- `services/modules/` - 按业务模块组织

### 3. 命名规范

- 组件：PascalCase（如 `UserList.tsx`）
- 文件：camelCase（如 `userService.ts`）
- 常量：UPPER_SNAKE_CASE（如 `API_PREFIX`）

### 4. 类型定义

- 所有接口都应该有类型定义
- 类型文件放在 `src/types/` 目录

## 环境变量

```bash
# .env.development
VITE_API_BASE_URL=http://localhost:8080

# .env.production
VITE_API_BASE_URL=https://api.example.com
```

## 常用命令

```bash
# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

# 构建生产版本
pnpm build

# 预览生产版本
pnpm preview

# 代码检查
pnpm lint
```

## 相关文档

- [API 使用指南](./API_GUIDE.md)
- [权限系统指南](./PERMISSION_GUIDE.md)
- [代理配置指南](./PROXY_GUIDE.md)
- [快速开始](./QUICK_START.md)