# bpo-fastapi

**Repository Path**: duixiangyu/bpo-fastapi

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-17
- **Last Updated**: 2026-01-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BPO FastAPI 项目 - 门禁考勤数据上传系统

## 项目概述
这是一个基于 FastAPI 的门禁考勤数据上传系统，用于从海康威视门禁设备获取刷卡记录，并定期批量上传至 BPO 系统。项目支持定时任务调度，可自动处理未上传的数据。

## 技术栈
- FastAPI: Web 框架
- SQLAlchemy: ORM 框架
- SQL Server: 数据库
- APScheduler: 任务调度
- Pydantic: 数据校验

## 功能特性
- 从门禁设备获取员工刷卡记录（包括员工邮箱、ID、姓名、刷卡时间、设备信息等）
- 自动将考勤数据上传至 BPO 系统
- 支持定时批量上传任务
- 数据上传状态跟踪（成功/失败）
- 完整的日志记录

## 依赖安装

在开始前，请安装所需的依赖包：

```bash
pip install -r requirements.txt
```

## 环境配置

### 1. 安装 ODBC 驱动
要连接 SQL Server，您需要安装 Microsoft ODBC Driver 17 for SQL Server：
- Windows: 从 Microsoft 官网下载安装
- Linux: 使用包管理器安装
- macOS: 使用 Homebrew 安装

### 2. 环境变量配置
复制 `.env.example` 文件为 `.env` 并根据您的数据库和 BPO 系统设置修改值：

```bash
cp .env.example .env
```

编辑 `.env` 文件中的数据库连接参数：
- `SQLSERVER_USER`: 数据库用户名 (默认: sa)
- `SQLSERVER_PASSWORD`: 数据库密码
- `SQLSERVER_SERVER`: 服务器地址 (默认: 192.168.184.23)
- `SQLSERVER_PORT`: 端口号 (默认: 1433)
- `SQLSERVER_DATABASE`: 数据库名称 (默认: master)

BPO 系统配置参数：
- `BPO_AK`: BPO 系统访问密钥
- `BPO_SK`: BPO 系统秘密密钥
- `VENDOR_CODE`: 供应商代码
- `WORKSITE_CODE`: 工作站点代码
- `BPO_URL`: BPO 系统地址
- `UPLOAD_API`: 上传接口路径
- `SCHEDULE_CRON`: 定时任务执行时间（默认: '45 14 * * *'）

## 启动应用

### 直接运行:
```bash
python run_app.py
```

### 或使用 uvicorn:
```bash
uvicorn main:app --host 127.0.0.1 --port 8000 --reload
```

## API 接口

- `POST /start-upload`: 手动触发上传任务

## Docker 部署

### 构建并运行
```bash
# 构建镜像
docker build -t bpo-fastapi .

# 使用 docker-compose 运行（包含数据库）
docker-compose up -d
```

## 项目结构

```
bpo-fastapi/
│
├── main.py              # 主应用文件
├── run_app.py           # 应用启动脚本
├── database.py          # 数据库连接配置
├── config/
│   ├── database_config.py  # 数据库配置
│   ├── bpo_config.py       # BPO 系统配置
│   └── log_config.py       # 日志配置
├── models/
│   └── hk_data.py       # 海康威视数据模型
├── core/
│   ├── bpo.py           # BPO 系统交互逻辑
│   └── job.py           # 定时任务逻辑
├── bpoapi/
│   └── bpo_api.py       # BPO API 接口
├── requirements.txt     # 依赖包列表
├── Dockerfile           # Docker 构建文件
└── docker-compose.yml   # Docker Compose 配置
```

## 数据流程

1. 从门禁系统获取员工刷卡记录
2. 记录保存到本地 SQL Server 数据库
3. 系统根据配置的定时规则（cron 表达式）自动上传数据
4. 数据上传后更新记录状态（成功/失败）
5. 如有失败记录，可在后续运行中重试

## 定时任务

系统使用 APScheduler 实现定时任务功能，默认配置为每天下午 2:45 执行数据上传任务。
可以通过修改 `SCHEDULE_CRON` 环境变量来自定义执行时间。

## 使用说明

1. 首先确保 SQL Server 服务正在运行
2. 安装所需的 ODBC 驱动和 Python 包
3. 根据您的数据库和 BPO 系统配置修改环境变量
4. 运行应用，系统将自动创建数据库表并启动定时任务
5. 可通过 POST 请求 `/start-upload` 手动触发上传任务

## 注意事项

- 在生产环境中，请确保使用安全的数据库凭据和 BPO 系统认证信息
- 根据需要调整数据库连接池大小
- 适当处理数据库异常和 BPO 系统连接错误
- 定期监控上传日志以确保数据同步正常