DreamOA API - 基于 .NET 10 的开源办公系统后端

一个轻量级、高性能的 OA (Office Automation) 后端 API 解决方案。

🇨🇳 简体中文 | 🇺🇸 English

相关项目

项目	仓库	说明
前端	dream-oa	Flutter 移动端应用
后端	dream-oa-api	本项目

核心功能

• 用户认证：JWT 认证、Token 自动刷新、多设备登录管理
• 考勤打卡：GPS/WiFi/基站/混合定位、打卡记录查询、外勤打卡
• 审批流程：请假/加班/补卡申请、可配置的审批流程、审批历史
• 部门管理：组织架构、部门层级、人员管理
• 节假日管理：节假日日历、工作日计算

技术栈

• 框架: ASP.NET Core 10.0
• ORM: Entity Framework Core 10.0
• 数据库: SQL Server / MySQL (多数据库支持)
• 认证: JWT (JSON Web Token)
• 文档: Swagger / OpenAPI

快速开始

环境要求

• .NET 10.0 SDK
• SQL Server 或 MySQL

安装与运行

1. 克隆项目

   git clone https://github.com/DREAMDREAM66/dream-oa-api.git
   cd dream-oa-api

2. 配置数据库

   复制示例配置文件：

   cp demo-oa/appsettings.example.json demo-oa/appsettings.json

   编辑 demo-oa/appsettings.json，配置数据库连接字符串：

   {
     "ConnectionStrings": {
       "SqlServer": "Server=YOUR_SERVER;Database=YOUR_DATABASE;User Id=YOUR_USER;Password=YOUR_PASSWORD",
       "MySql": "server=YOUR_SERVER;database=YOUR_DATABASE;user=YOUR_USER;password=YOUR_PASSWORD"
     }
   }

3. 运行数据库迁移

   # SQL Server
   dotnet ef database update --context SqlServerOaDbContext --project demo-oa/demo-oa.csproj
   
   # MySQL
   dotnet ef database update --context MySqlOaDbContext --project demo-oa/demo-oa.csproj

4. 运行项目

   dotnet run --project demo-oa/demo-oa.csproj

5. 访问 API 文档

   运行后访问 Swagger 文档：https://localhost:8160/swagger

环境变量配置

除了 appsettings.json，你也可以使用环境变量来配置数据库连接字符串（优先从环境变量获取，fallback 到 appsettings.json）：

# SQL Server 连接字符串
export ConnectionStrings__SqlServer="Server=YOUR_SERVER;Database=YOUR_DATABASE;User Id=YOUR_USER;Password=YOUR_PASSWORD"

优先级：环境变量 > appsettings.json

注意：目前仅 SQL Server 支持环境变量配置，MySQL 请在 appsettings.json 中配置。

项目结构

demo-oa/
├── Controllers/           # API 控制器
├── Services/              # 业务逻辑层
│   └── Interface/         # 服务接口定义
├── Repository/            # 数据访问层
│   └── Interface/         # 仓储接口
├── Models/                # 实体模型和 DTO
├── Data/                  # EF Core DbContext
├── Migrations/            # 数据库迁移
│   ├── SqlServer/
│   └── MySql/
└── appsettings.example.json  # 配置文件模板

API 接口

认证相关

方法	路径	说明
POST	/api/auth/login	用户登录
POST	/api/auth/refresh	刷新 Token
POST	/api/auth/logout	用户登出

考勤相关

方法	路径	说明
POST	/api/checkin/clock-in	上班打卡
POST	/api/checkin/clock-out	下班打卡
GET	/api/checkin/records	查询打卡记录

审批相关

方法	路径	说明
POST	/api/approval/submit	提交申请
POST	/api/approval/approve	审批通过
POST	/api/approval/reject	审批拒绝
GET	/api/approval/my-applications	我的申请
GET	/api/approval/pending	待审批列表

数据库迁移

添加新迁移

# SQL Server
dotnet ef migrations add <MigrationName> --context SqlServerOaDbContext --output-dir Migrations/SqlServer --project demo-oa/demo-oa.csproj

# MySQL
dotnet ef migrations add <MigrationName> --context MySqlOaDbContext --output-dir Migrations/MySql --project demo-oa/demo-oa.csproj

生成生产环境 SQL 脚本

dotnet ef migrations script "<上一次迁移名>" --idempotent --context SqlServerOaDbContext --project demo-oa/demo-oa.csproj --output "<输出路径>"

参与贡献

欢迎提交 Issue 和 Pull Request！

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

提交规范

使用约定式提交格式：

<type>: <description>

类型：feat, fix, refactor, docs, test, chore, perf, ci

许可证

本项目采用 MIT 许可证 开源。

简单来说：你可以自由使用、修改和商用，但请保留原作者版权声明。

详见 LICENSE 文件。