advich-content-frontend/docs/PROJECT_STRUCTURE.md

项目结构说明

目录结构

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/ 目录

环境变量

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

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

常用命令

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

# 构建生产版本
pnpm build

# 预览生产版本
pnpm preview

# 代码检查
pnpm lint

相关文档

• API 使用指南
• 权限系统指南
• 代理配置指南
• 快速开始