# pepole-mgr

**Repository Path**: dog/pepole-mgr

## Basic Information

- **Project Name**: pepole-mgr
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-02
- **Last Updated**: 2025-09-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">
  <h1>🏢 员工管理系统</h1>
  <p>基于 React + Flask 的现代化员工管理系统</p>
  <p>
    <img src="https://img.shields.io/badge/React-19.1.1-blue" alt="React" />
    <img src="https://img.shields.io/badge/TypeScript-5.8.2-blue" alt="TypeScript" />
    <img src="https://img.shields.io/badge/Flask-2.3.3-green" alt="Flask" />
    <img src="https://img.shields.io/badge/MySQL-5.7+-orange" alt="MySQL" />
  </p>
</div>

## 📋 项目简介

员工管理系统是一个功能完整的全栈Web应用，采用前后端分离架构，提供员工信息管理、考勤记录、工资管理等核心功能。系统集成了AI能力，支持智能生成职位描述，提升管理效率。

## ✨ 功能特性

### 🧑‍💼 员工管理
- 员工信息的增删改查 (CRUD)
- 员工头像上传和展示
- 部门职位管理
- 入职日期和薪资管理
- AI智能生成职位描述

### ⏰ 考勤管理
- 考勤记录查询和添加
- 签到签退时间记录
- 考勤状态统计（出勤、缺勤、迟到）
- 考勤数据可视化

### 💰 工资管理
- 工资记录管理
- 基本工资、奖金、扣款计算
- 实发工资自动计算
- 工资发放历史记录

### 📊 数据统计
- 员工总数统计
- 今日出勤统计
- 月度工资统计
- 数据可视化图表

### 🔐 用户认证
- 安全的用户登录系统
- Session-based认证
- 密码哈希存储
- 登录状态管理

## 🛠️ 技术栈

### 前端技术
- **框架**: React 19.1.1 + TypeScript 5.8.2
- **构建工具**: Vite 6.2.0
- **UI组件**: 自定义组件 + 响应式设计
- **图表库**: Recharts 3.1.2
- **HTTP客户端**: Fetch API
- **状态管理**: React Hooks

### 后端技术
- **框架**: Flask 2.3.3
- **数据库**: MySQL 5.7+
- **ORM**: SQLAlchemy 3.0.5
- **认证**: Session-based认证
- **跨域**: Flask-CORS 4.0.0
- **密码安全**: Werkzeug 2.3.7
- **配置管理**: python-dotenv 1.0.0

### AI集成
- **AI服务**: Google Gemini API
- **功能**: 智能生成职位描述

## 🚀 快速开始

### 环境要求

- **Node.js**: 16.0+
- **Python**: 3.8+
- **MySQL**: 5.7+
- **npm/pnpm**: 最新版本

### 1. 克隆项目

```bash
git clone <repository-url>
cd gemini-employee-management-system
```

### 2. 前端设置

```bash
# 安装依赖
npm install
# 或使用 pnpm
pnpm install

# 设置环境变量（可选）
# 创建 .env.local 文件并添加：
# VITE_API_BASE_URL=http://127.0.0.1:5000/api
```

### 3. 后端设置

```bash
# 进入后端目录
cd backend

# 创建虚拟环境
python3 -m venv venv

# 激活虚拟环境
# macOS/Linux:
source venv/bin/activate
# Windows:
venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt
```

### 4. 数据库配置

```bash
# 创建MySQL数据库
mysql -u root -p
CREATE DATABASE ems_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

# 设置环境变量（可选）
export DATABASE_URL="mysql+mysqlconnector://root:password@localhost/ems_db"
export SECRET_KEY="your-secret-key-here"
```

### 5. 初始化数据库

```bash
# 在backend目录下
flask init-db
```

### 6. 启动服务

#### 启动后端服务
```bash
# 在backend目录下
python run.py
# 或
flask run
```

后端服务将在 `http://127.0.0.1:5000` 启动

#### 启动前端服务
```bash
# 在项目根目录下
npm run dev
# 或
pnpm dev
```

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

### 7. 访问系统

打开浏览器访问 `http://localhost:5173`

**默认登录账户**:
- 用户名: `admin`
- 密码: `admin123`

## 📖 使用说明

### 🔐 系统登录

1. 打开浏览器访问 `http://localhost:5173`
2. 在登录页面输入用户名和密码
3. 点击"登录"按钮进入系统主界面

### 🏠 主界面导航

登录成功后，您将看到系统主界面，包含以下主要区域：

- **侧边栏导航**: 包含仪表盘、员工管理、考勤管理、工资管理等模块
- **主内容区**: 显示当前选中模块的详细内容
- **顶部状态栏**: 显示当前用户信息和退出登录按钮

### 📊 仪表盘使用

仪表盘提供系统概览信息：

- **员工总数**: 显示当前系统中的员工数量
- **今日出勤**: 显示今日已签到的员工数量
- **月度工资**: 显示本月工资发放总额
- **数据图表**: 可视化展示各项统计数据

### 👥 员工管理

#### 查看员工列表
1. 点击侧边栏"员工管理"
2. 查看所有员工的基本信息
3. 使用搜索功能快速查找特定员工

#### 添加新员工
1. 点击"添加员工"按钮
2. 填写员工基本信息：
   - 姓名（必填）
   - 邮箱（必填，需唯一）
   - 职位（必填）
   - 部门（必填）
   - 入职日期（必填）
   - 月薪（必填）
   - 头像URL（可选）
   - 职位描述（可选，可使用AI生成）
3. 点击"保存"完成添加

#### 编辑员工信息
1. 在员工列表中点击"编辑"按钮
2. 修改需要更新的信息
3. 点击"保存"确认修改

#### 删除员工
1. 在员工列表中点击"删除"按钮
2. 确认删除操作
3. 系统将同时删除该员工的考勤和工资记录

#### AI生成职位描述
1. 在添加或编辑员工时，点击"AI生成"按钮
2. 系统将根据职位和部门信息自动生成职位描述
3. 可以手动调整生成的内容

### ⏰ 考勤管理

#### 查看考勤记录
1. 点击侧边栏"考勤管理"
2. 查看所有员工的考勤记录
3. 可以按日期范围筛选记录

#### 添加考勤记录
1. 点击"添加考勤"按钮
2. 选择员工和日期
3. 选择考勤状态：
   - **出勤**: 正常上班
   - **缺勤**: 未上班
   - **迟到**: 晚于规定时间上班
4. 如果选择"出勤"或"迟到"，需要填写签到和签退时间
5. 点击"保存"完成记录

#### 考勤状态说明
- **出勤**: 员工正常上班，有完整的签到签退时间
- **缺勤**: 员工未上班，无签到签退时间
- **迟到**: 员工晚于规定时间上班，有签到签退时间

### 💰 工资管理

#### 查看工资记录
1. 点击侧边栏"工资管理"
2. 查看所有员工的工资发放记录
3. 可以按薪资周期筛选记录

#### 添加工资记录
1. 点击"添加工资"按钮
2. 选择员工和薪资周期（格式：YYYY-MM）
3. 填写工资信息：
   - **基本工资**: 员工的基本月薪
   - **奖金**: 额外奖励金额（可选）
   - **扣款**: 需要扣除的金额（可选）
4. 系统自动计算实发工资 = 基本工资 + 奖金 - 扣款
5. 点击"保存"完成记录

#### 工资计算说明
- **实发工资** = 基本工资 + 奖金 - 扣款
- 系统会自动计算并显示最终实发金额
- 支持负数扣款（如加班费等）

### 🔍 数据筛选和搜索

#### 员工搜索
- 在员工管理页面使用搜索框
- 支持按姓名、邮箱、职位、部门搜索
- 实时显示搜索结果

#### 考勤筛选
- 按日期范围筛选考勤记录
- 按考勤状态筛选
- 按员工筛选

#### 工资筛选
- 按薪资周期筛选
- 按员工筛选
- 按金额范围筛选

### 📱 响应式设计

系统支持多种设备访问：

- **桌面端**: 完整功能体验
- **平板端**: 适配触摸操作
- **手机端**: 简化界面，核心功能可用

### ⌨️ 快捷键

- `Ctrl + N`: 快速添加新员工
- `Ctrl + S`: 保存当前表单
- `Esc`: 关闭模态框
- `Enter`: 确认操作

### 💡 使用技巧

1. **批量操作**: 在员工列表中可以选择多个员工进行批量操作
2. **数据导出**: 支持将员工列表、考勤记录、工资记录导出为Excel文件
3. **数据备份**: 定期备份数据库，防止数据丢失
4. **权限管理**: 不同用户角色有不同的操作权限
5. **数据验证**: 系统会自动验证输入数据的格式和完整性

### 🚨 注意事项

1. **数据安全**: 请定期修改默认密码
2. **浏览器兼容**: 建议使用Chrome、Firefox、Safari等现代浏览器
3. **网络连接**: 确保前后端服务正常运行
4. **数据备份**: 重要数据请及时备份
5. **权限控制**: 不要将管理员账户信息泄露给无关人员

### ❓ 常见问题

#### Q: 忘记登录密码怎么办？
A: 请联系系统管理员重置密码，或通过数据库直接修改用户密码哈希值。

#### Q: 如何批量导入员工数据？
A: 目前系统支持单个添加，批量导入功能正在开发中。

#### Q: 考勤记录可以修改吗？
A: 可以，但建议谨慎操作，系统会记录修改历史。

#### Q: 工资记录删除后可以恢复吗？
A: 删除的工资记录无法直接恢复，请谨慎操作。

#### Q: 系统支持多语言吗？
A: 目前系统仅支持中文界面，多语言支持正在规划中。

#### Q: 如何备份系统数据？
A: 可以通过数据库导出功能或直接备份MySQL数据库文件。

### 🔧 故障排除

#### 登录失败
1. 检查用户名和密码是否正确
2. 确认后端服务是否正常运行
3. 检查网络连接是否正常

#### 页面加载缓慢
1. 检查网络连接
2. 清除浏览器缓存
3. 重启前后端服务

#### 数据保存失败
1. 检查必填字段是否完整
2. 确认数据格式是否正确
3. 查看浏览器控制台错误信息

#### 无法连接数据库
1. 检查MySQL服务是否运行
2. 验证数据库连接配置
3. 确认数据库用户权限

### 🎯 最佳实践

#### 数据管理最佳实践
1. **定期备份**: 建议每日自动备份数据库
2. **数据验证**: 输入数据前仔细核对，避免错误数据
3. **权限控制**: 为不同角色分配适当的操作权限
4. **审计日志**: 重要操作应记录操作日志
5. **数据清理**: 定期清理过期或无效数据

#### 系统维护最佳实践
1. **监控系统**: 定期检查系统运行状态
2. **性能优化**: 定期优化数据库查询和索引
3. **安全更新**: 及时更新系统和依赖包
4. **用户培训**: 定期培训用户正确使用系统
5. **文档维护**: 保持文档与系统功能同步

#### 使用效率提升技巧
1. **快捷键使用**: 熟练使用系统快捷键提高操作效率
2. **批量操作**: 尽量使用批量操作减少重复工作
3. **模板功能**: 创建常用数据模板快速录入
4. **搜索技巧**: 使用高级搜索功能快速定位数据
5. **报表导出**: 定期导出重要报表进行离线分析

### 🔄 数据导入导出

#### 数据导出
系统支持以下数据导出功能：

1. **员工数据导出**
   - 格式：Excel (.xlsx)
   - 包含：所有员工基本信息
   - 用途：备份、分析、迁移

2. **考勤数据导出**
   - 格式：Excel (.xlsx)
   - 包含：指定时间范围的考勤记录
   - 用途：考勤分析、工资计算

3. **工资数据导出**
   - 格式：Excel (.xlsx)
   - 包含：指定周期的工资记录
   - 用途：财务分析、税务申报

#### 数据导入（规划中）
未来版本将支持以下导入功能：

1. **员工批量导入**
   - 支持Excel模板导入
   - 数据验证和错误提示
   - 导入结果报告

2. **考勤数据导入**
   - 支持考勤设备数据导入
   - 自动数据格式转换
   - 重复数据检测

### 🔐 安全建议

#### 密码安全
1. **强密码策略**: 使用包含大小写字母、数字、特殊字符的强密码
2. **定期更换**: 建议每3个月更换一次密码
3. **密码保护**: 不要在公共场所输入密码
4. **多因素认证**: 考虑启用多因素认证（未来版本）

#### 数据安全
1. **访问控制**: 限制系统访问权限
2. **数据加密**: 敏感数据加密存储
3. **网络安全**: 使用HTTPS协议传输数据
4. **备份安全**: 备份文件加密存储

#### 系统安全
1. **定期更新**: 及时更新系统和依赖包
2. **安全扫描**: 定期进行安全漏洞扫描
3. **日志监控**: 监控异常登录和操作
4. **权限审计**: 定期审计用户权限

### 📈 性能优化建议

#### 数据库优化
1. **索引优化**: 为常用查询字段建立索引
2. **查询优化**: 避免复杂的多表连接查询
3. **分页查询**: 大数据量查询使用分页
4. **连接池**: 合理配置数据库连接池

#### 前端优化
1. **懒加载**: 大列表使用虚拟滚动
2. **缓存策略**: 合理使用浏览器缓存
3. **资源压缩**: 压缩静态资源文件
4. **CDN加速**: 使用CDN加速静态资源

#### 系统监控
1. **性能监控**: 监控系统响应时间
2. **资源监控**: 监控CPU、内存、磁盘使用率
3. **错误监控**: 监控系统错误和异常
4. **用户行为**: 分析用户使用模式

### 🚀 扩展功能规划

#### 即将推出的功能
1. **移动端APP**: 原生移动应用
2. **消息通知**: 邮件和短信通知
3. **报表系统**: 高级报表和分析
4. **工作流**: 审批流程管理
5. **集成接口**: 第三方系统集成

#### 长期规划
1. **微服务架构**: 系统微服务化改造
2. **云原生部署**: 支持Kubernetes部署
3. **AI增强**: 更多AI功能集成
4. **国际化**: 多语言和多地区支持
5. **大数据分析**: 高级数据分析和预测

## 📁 项目结构

```
gemini-employee-management-system/
├── 📁 aidoc/                    # 项目文档
│   ├── API文档.md               # API接口文档
│   ├── 数据库设计.md            # 数据库设计文档
│   ├── 系统架构设计.md          # 系统架构文档
│   └── 部署指南.md              # 部署指南
├── 📁 backend/                  # 后端服务
│   ├── app.py                   # Flask应用主文件
│   ├── models.py                # 数据模型定义
│   ├── database.py              # 数据库初始化
│   ├── cli.py                   # CLI命令
│   ├── config.py                # 配置管理
│   ├── run.py                   # 启动脚本
│   └── requirements.txt         # Python依赖
├── 📁 components/               # React组件
│   ├── Dashboard.tsx            # 仪表盘组件
│   ├── EmployeeList.tsx         # 员工列表组件
│   ├── EmployeeModal.tsx        # 员工编辑模态框
│   ├── AttendanceTracker.tsx    # 考勤跟踪组件
│   ├── PayrollManager.tsx       # 工资管理组件
│   ├── Login.tsx                # 登录组件
│   └── Sidebar.tsx              # 侧边栏组件
├── App.tsx                      # 主应用组件
├── types.ts                     # TypeScript类型定义
├── package.json                 # 前端依赖配置
└── README.md                    # 项目说明文档
```

## 📚 API文档

系统提供完整的RESTful API接口，详细文档请参考：

- [API接口文档](./aidoc/API文档.md)
- [数据库设计文档](./aidoc/数据库设计.md)
- [系统架构设计文档](./aidoc/系统架构设计.md)

### 主要API端点

- **认证**: `/api/login`, `/api/logout`, `/api/check_auth`
- **员工管理**: `/api/employees`
- **考勤管理**: `/api/attendance`
- **工资管理**: `/api/payroll`
- **统计信息**: `/api/stats`

## 🚀 部署指南

### 开发环境
- 前端: Vite开发服务器 (端口5173)
- 后端: Flask开发服务器 (端口5000)
- 数据库: MySQL本地实例

### 生产环境
- 前端: Nginx静态文件服务
- 后端: Gunicorn WSGI服务器
- 数据库: MySQL生产实例
- 反向代理: Nginx

详细部署说明请参考 [部署指南](./aidoc/部署指南.md)

## 🤝 贡献指南

1. Fork 本仓库
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情

## 📞 联系方式

如有问题或建议，请通过以下方式联系：

- 创建 [Issue](../../issues)
- 发送邮件至项目维护者

---

<div align="center">
  <p>⭐ 如果这个项目对你有帮助，请给它一个星标！</p>
</div>