# ems

**Repository Path**: codebase-xsy/ems

## Basic Information

- **Project Name**: ems
- **Description**: 员工管理系统，基于 Spring Boot 3 + React 19 全栈实现
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-30
- **Last Updated**: 2026-08-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# EMS (Employee Management System)

员工管理系统，基于 Spring Boot 3 + React 19 全栈实现。

## 技术栈

### 后端

- **框架**: Spring Boot 3.5.14
- **ORM**: MyBatis Plus 3.5.5
- **数据库**: MySQL 8.0
- **缓存**: Redis 8.8.0
- **安全**: Spring Security + JWT
- **文档**: SpringDoc OpenAPI (Swagger)
- **JDK**: Java 17

### 前端

- **框架**: React 19.2.6
- **语言**: TypeScript 6.0.2
- **构建工具**: Vite 8.0.12
- **路由**: React Router DOM 7.16.0
- **状态管理**: Zustand 5.0.14
- **数据请求**: React Query (TanStack) 5.100.14
- **表单**: React Hook Form 7.76.1 + Zod 4.4.3
- **UI**: Tailwind CSS 4.3.0
- **图标**: Lucide React 1.17.0

## 项目结构

```
ems/
├── src/main/java/com/example/ems/    # 后端代码
│   ├── aspect/                       # AOP 切面
│   ├── common/                       # 通用类
│   ├── config/                       # 配置类
│   ├── controller/                   # 控制器
│   ├── dto/                          # 数据传输对象
│   ├── entity/                       # 实体类
│   ├── interceptor/                  # 拦截器
│   ├── mapper/                       # MyBatis Mapper
│   ├── service/                      # 业务层
│   └── utils/                        # 工具类
├── src/main/resources/
│   └── application.yaml              # 配置文件
├── ems-frontend/                     # 前端代码
│   ├── src/
│   │   ├── api/                      # API 接口封装
│   │   ├── components/               # 组件
│   │   │   ├── guards/               # 路由守卫
│   │   │   ├── layout/               # 布局组件
│   │   │   └── ui/                   # UI 组件
│   │   ├── features/                 # 功能模块
│   │   │   ├── auth/                 # 登录认证
│   │   │   ├── dashboard/            # 仪表板
│   │   │   ├── departments/          # 部门管理
│   │   │   └── employees/            # 员工管理
│   │   ├── hooks/                    # 自定义 Hooks
│   │   ├── router/                   # 路由配置
│   │   ├── stores/                   # 状态管理
│   │   ├── types/                    # TypeScript 类型定义
│   │   └── utils/                    # 工具函数
│   └── package.json
├── docker/
│   └── mysql/
│       └── init.sql                  # 数据库初始化脚本
├── docker-compose.yml                # Docker 编排文件
└── pom.xml                           # Maven 配置
```

## 快速启动

### 前置要求

- JDK 17+
- Maven 3.6+
- Node.js 20+
- npm 或 pnpm
- Docker & Docker Compose

### 1. 启动基础设施（MySQL + Redis）

```bash
docker-compose up -d
```

这将启动：
- MySQL 8.0 (端口: 3306)
- Redis 8.8.0 (端口: 6379)

### 2. 启动后端

```bash
# 编译项目
mvn clean compile -DskipTests

# 启动应用
mvn spring-boot:run
```

后端将在 `http://localhost:8080` 启动。

### 3. 启动前端

打开新的终端窗口：

```bash
# 进入前端目录
cd ems-frontend

# 安装依赖
npm install

# 启动开发服务器
npm run dev
```

前端将在 `http://localhost:5173` 启动。

### 4. 访问应用

- **前端应用**: http://localhost:5173
- **API 文档**: http://localhost:8080/swagger-ui.html

## 缓存架构

项目采用 **Redis + Spring Cache** 实现缓存功能，符合 Cache Aside 模式。

### 缓存策略

| 功能 | 实现方式 |
|------|---------|
| **缓存模式** | Cache Aside（旁路缓存） |
| **缓存 Key 格式** | `{cacheName}::{key}` |
| **缓存命名空间** | `employee`, `department` |
| **过期时间** | 1小时 |
| **缓存穿透防护** | 缓存空值 |
| **缓存一致性** | 写操作后删除缓存（`@CacheEvict`） |

### 缓存 Key 示例

```
employee::1          # 单个员工缓存
employee::list       # 员工列表缓存
department::5        # 单个部门缓存
department::list     # 部门列表缓存
```

## API 接口

### 员工管理

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | `/employees` | 获取所有员工 |
| GET | `/employees/{id}` | 根据 ID 获取员工 |
| GET | `/employees/page` | 分页查询员工 |
| POST | `/employees` | 新增员工 |
| PUT | `/employees/{id}` | 更新员工 |
| DELETE | `/employees/{id}` | 删除员工 |

### 部门管理

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | `/departments` | 获取所有部门 |
| GET | `/departments/{id}` | 根据 ID 获取部门 |
| POST | `/departments` | 新增部门 |
| PUT | `/departments/{id}` | 更新部门 |
| DELETE | `/departments/{id}` | 删除部门 |

## 配置说明

### 应用配置 ([application.yaml](src/main/resources/application.yaml))

```yaml
server:
  port: 8080

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/ems_db
    username: root
    password: mysql123456
  redis:
    host: localhost
    port: 6379
```

### Docker 配置 ([docker-compose.yml](docker-compose.yml))

包含 MySQL 和 Redis 服务，支持数据持久化。

## 开发指南

### 后端开发

```bash
# 编译项目
mvn clean compile

# 运行测试
mvn test

# 打包项目
mvn clean package -DskipTests
```

### 前端开发

```bash
cd ems-frontend

# 安装依赖
npm install

# 启动开发服务器（支持热更新）
npm run dev

# 类型检查
tsc -b

# 代码检查
npm run lint

# 构建生产版本
npm run build

# 预览生产构建
npm run preview
```

### 停止服务

```bash
# 停止后端应用（Ctrl+C）

# 停止前端应用（Ctrl+C）

# 停止 Docker 服务
docker-compose down

# 停止并删除数据卷（慎用）
docker-compose down -v
```

## License

MIT