# TimeSync

**Repository Path**: Agions/TimeSync

## Basic Information

- **Project Name**: TimeSync
- **Description**: TimeSync（时间同步）— 智能工时与考勤管理系统 | NestJS 10 + TypeScript 5 + MongoDB 7
- **Primary Language**: TypeScript
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2024-02-05
- **Last Updated**: 2026-05-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TimeSync 智能工时与薪资管理系统

[![NestJS](https://img.shields.io/badge/NestJS-10-e0234e?style=flat-square&logo=nestjs&logoColor=white)](https://nestjs.com/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-3178c6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![MongoDB](https://img.shields.io/badge/MongoDB-7-47a248?style=flat-square&logo=mongodb&logoColor=white)](https://www.mongodb.com/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

TimeSync（时间同步）是一套现代化的智能工时与考勤管理系统，帮助企业高效管理员工考勤、工时记录和薪资计算。

## 🌟 系统特点

- **智能考勤管理**：支持地理位置验证、人脸识别和指纹打卡，确保考勤记录真实可靠
- **灵活的工时记录**：支持多种工作模式，包括固定工时、弹性工作制和远程办公
- **精准薪资计算**：自动计算基本工资、加班费、奖金和扣除项，确保薪资准确无误
- **强大的数据分析**：提供多维度的统计报表，帮助管理者做出明智决策
- **安全可靠**：采用JWT认证机制，确保数据安全性
- **易于集成**：提供标准REST API，方便与其他系统集成

## 🔧 技术栈

- **后端**：NestJS 10 + TypeScript 5（strict mode）
- **数据库**：MongoDB 7 + Mongoose 7
- **认证**：JWT (JSON Web Token) + Passport
- **API文档**：Swagger (OpenAPI)
- **容器化**：Docker + Docker Compose
- **架构**：DDD 分层架构（Controller → Service → Repository）

## 💻 核心功能模块

### 用户认证模块
- 用户注册、登录、登出
- JWT 令牌认证 + 刷新令牌机制
- 密码加密（bcryptjs）
- 角色权限管理（员工/经理/管理员）

### 考勤打卡模块
- 上下班打卡（支持地理位置验证）
- 打卡记录查询（日/周/月）
- 打卡统计（工时计算、迟到早退统计）
- 地理围栏设置（定义有效打卡范围）
- 管理员手动添加打卡记录

### 个人信息管理模块
- 用户基本信息管理
- 头像上传与管理
- 个人设置保存（通知偏好、界面偏好）
- 账号安全设置

### 部门管理模块
- 部门 CRUD 操作
- 部门地理位置配置
- 部门员工关联

## 📁 项目结构

```
src/
├── common/
│   ├── decorators/      # 自定义装饰器（CurrentUser, Roles）
│   ├── filters/         # 异常过滤器
│   ├── guards/          # 权限守卫（RolesGuard）
│   ├── interceptors/    # 拦截器（ResponseInterceptor）
│   ├── types/           # 全局类型定义（user, attendance, department）
│   └── utils/           # 工具函数（ObjectId验证、分页查询、日期处理）
├── config/              # 配置模块
├── modules/
│   ├── attendance/      # 考勤模块
│   │   ├── attendance-core.service.ts    # 核心打卡功能
│   │   ├── attendance-query.service.ts   # 查询统计功能
│   │   ├── attendance-admin.service.ts   # 管理员功能
│   │   ├── attendance.controller.ts
│   │   ├── attendance.module.ts
│   │   ├── dto/         # 数据传输对象
│   │   └── schemas/     # Mongoose Schema
│   ├── auth/            # 认证模块
│   │   ├── auth.service.ts
│   │   ├── auth.controller.ts
│   │   ├── auth.module.ts
│   │   ├── guards/      # JWT/Local 守卫
│   │   └── strategies/  # Passport 策略
│   └── users/           # 用户模块
│       ├── users.service.ts
│       ├── users.controller.ts
│       ├── users.module.ts
│       ├── dto/
│       └── schemas/
└── main.ts              # 应用入口
```

## ⚙️ 安装与运行

### 前置要求
- Node.js >= 18
- MongoDB >= 6.0
- pnpm / npm / yarn

### 安装依赖
```bash
pnpm install
# 或
npm install --legacy-peer-deps
```

### 环境变量
复制 `.env.example` 为 `.env`，配置以下变量：
```env
PORT=5000
DATABASE_URI=mongodb://localhost:27017/timesync
JWT_SECRET=your-secret-key
JWT_EXPIRES_IN=1d
```

### 运行应用
```bash
# 开发模式
pnpm run start:dev

# 生产模式
pnpm run build
pnpm run start:prod
```

### 使用 Docker
```bash
docker-compose up -d
```

## 🧪 测试

```bash
# 单元测试
pnpm run test

# e2e 测试
pnpm run test:e2e

# 测试覆盖率
pnpm run test:cov
```

## 📖 API 文档

启动应用后，访问 http://localhost:5000/docs 查看 Swagger API 文档。

### 主要 API 端点

| 模块 | 端点 | 说明 |
|------|------|------|
| 认证 | `POST /auth/login` | 用户登录 |
| 认证 | `POST /auth/register` | 用户注册 |
| 认证 | `POST /auth/refresh` | 刷新令牌 |
| 用户 | `GET /users` | 获取用户列表 |
| 用户 | `GET /users/profile` | 获取当前用户信息 |
| 考勤 | `POST /attendance/clock` | 打卡 |
| 考勤 | `GET /attendance/daily` | 获取当日打卡记录 |
| 考勤 | `GET /attendance/stats` | 获取打卡统计 |
| 部门 | `GET /users/departments/all` | 获取部门列表 |

## 🏗️ 架构设计

### 分层架构
```
Controller (路由层)
    ↓
Service (业务逻辑层)
    ↓
Model/Schema (数据访问层)
```

### 类型安全
- TypeScript strict mode 启用
- 所有 DTO 和 Schema 使用 `!` 断言确保类型安全
- 统一的类型定义（`common/types/`）

### 代码复用
- 通用工具函数（`common/utils/`）
  - `validateObjectId`: MongoDB ObjectId 验证
  - `paginatedQuery`: 通用分页查询
  - `calculateDistance`: 地理位置距离计算

## 📄 许可证

本项目基于 [MIT 许可证](LICENSE) 开源。

## 👥 贡献

欢迎提交 Issue 和 Pull Request！

## 📧 联系方式

- 作者：Agions