998211c483
- 从服务器拉取完整代码 - 按框架规范整理项目结构 - 配置 Drone CI 测试环境部署 - 包含后端(FastAPI)、前端(Vue3)、管理端 技术栈: Vue3 + TypeScript + FastAPI + MySQL
159 lines
4.4 KiB
Markdown
159 lines
4.4 KiB
Markdown
# 员工同步功能实施总结
|
||
|
||
## 功能概述
|
||
从公司钉钉员工表（neuron_new.v_钉钉员工表）同步在职员工数据到考培练系统，实现员工数据的自动化管理。
|
||
|
||
## 实施日期
|
||
2025-11-11
|
||
|
||
## 数据源信息
|
||
- **外部数据库**: 120.77.144.233:29613
|
||
- **数据库名**: neuron_new
|
||
- **表名**: v_钉钉员工表
|
||
- **同步条件**: 是否在职=1
|
||
|
||
## 数据映射规则
|
||
|
||
### 1. 用户基础信息
|
||
- **username**: 手机号（登录账号）
|
||
- **phone**: 手机号
|
||
- **email**: 邮箱（若为空则生成：{手机号}@rxm.com）
|
||
- **full_name**: 员工姓名
|
||
- **password**: 统一初始密码为 `123456`
|
||
|
||
### 2. 角色映射
|
||
- **是否领导=1** → role='manager' （管理者）
|
||
- **其他** → role='trainee' （学员）
|
||
|
||
### 3. 部门同步
|
||
- **所属部门** → 自动创建Team（team_type='department'）
|
||
- **是否领导=1** → 设为团队负责人（leader_id）
|
||
|
||
### 4. 岗位同步
|
||
- **职位** → 自动创建Position并关联用户（PositionMember）
|
||
|
||
## 数据库结构调整
|
||
|
||
### users表修改
|
||
```sql
|
||
ALTER TABLE users MODIFY COLUMN email VARCHAR(100) NULL COMMENT '邮箱（可选）';
|
||
```
|
||
- 将email字段从NOT NULL改为NULL
|
||
- 支持没有邮箱的员工注册
|
||
|
||
### 相关文件修改
|
||
- `app/models/user.py` - ORM模型
|
||
- `app/schemas/user.py` - Pydantic Schema
|
||
- `scripts/alter_users_email_nullable.sql` - SQL迁移脚本
|
||
|
||
## 核心代码实现
|
||
|
||
### 1. 员工同步服务
|
||
**文件**: `app/services/employee_sync_service.py`
|
||
|
||
**核心功能**:
|
||
- 连接外部数据库获取员工数据
|
||
- 数据清洗和转换
|
||
- 批量创建用户、团队、岗位
|
||
- 建立关联关系
|
||
- 错误处理和日志记录
|
||
|
||
### 2. API接口
|
||
**文件**: `app/api/v1/endpoints/employee_sync.py`
|
||
|
||
**接口列表**:
|
||
- `POST /api/v1/employee-sync/sync` - 执行员工同步
|
||
- `GET /api/v1/employee-sync/preview` - 预览待同步数据
|
||
- `GET /api/v1/employee-sync/status` - 查询系统统计信息
|
||
|
||
**权限要求**: 仅管理员（role='admin'）可执行
|
||
|
||
### 3. 用户清理脚本
|
||
**文件**: `scripts/cleanup_users.py`
|
||
|
||
**功能**: 删除除admin外的所有用户，为员工同步做准备
|
||
|
||
## 同步结果
|
||
|
||
### 数据统计
|
||
- ✅ **总用户数**: 117人（包括1个admin）
|
||
- ✅ **管理者**: 5人（是否领导=1）
|
||
- ✅ **学员**: 111人
|
||
- ✅ **团队**: 34个（部门）
|
||
- ✅ **岗位**: 53个
|
||
|
||
### 同步时长
|
||
约41.7秒
|
||
|
||
### 已知问题
|
||
在关联用户和团队时出现`MissingGreenlet`错误，但不影响主要数据同步。团队和岗位已正确创建，只是用户-团队关联可能需要后续完善。
|
||
|
||
## 测试验证
|
||
|
||
### 登录测试
|
||
- ✅ 管理员登录: `admin` / `admin123`
|
||
- ✅ 员工登录: `{手机号}` / `123456`
|
||
|
||
**测试示例**:
|
||
```bash
|
||
# 员工登录（何平-护士长）
|
||
curl -X POST "https://kpl.ireborn.com.cn/api/v1/auth/login" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"username":"18677238080","password":"123456"}'
|
||
```
|
||
|
||
## 使用指南
|
||
|
||
### 执行员工同步
|
||
1. 使用admin账号登录获取token
|
||
2. 调用同步API:
|
||
```bash
|
||
curl -X POST "https://kpl.ireborn.com.cn/api/v1/employee-sync/sync" \
|
||
-H "Authorization: Bearer {TOKEN}" \
|
||
-H "Content-Type: application/json"
|
||
```
|
||
|
||
### 预览待同步数据
|
||
```bash
|
||
curl -X GET "https://kpl.ireborn.com.cn/api/v1/employee-sync/preview" \
|
||
-H "Authorization: Bearer {TOKEN}"
|
||
```
|
||
|
||
### 查询系统状态
|
||
```bash
|
||
curl -X GET "https://kpl.ireborn.com.cn/api/v1/employee-sync/status" \
|
||
-H "Authorization: Bearer {TOKEN}"
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. **数据安全**: 仅管理员可执行同步操作
|
||
2. **初始密码**: 所有新用户初始密码为`123456`，建议首次登录后修改
|
||
3. **邮箱生成**: 若员工无邮箱，自动生成格式为`{手机号}@rxm.com`
|
||
4. **幂等性**: 支持重复执行，已存在的用户会被跳过
|
||
5. **事务保护**: 使用数据库事务确保数据一致性
|
||
|
||
## 后续优化建议
|
||
|
||
1. 修复用户-团队关联的异步问题
|
||
2. 添加增量同步功能（只同步新增或变更的员工）
|
||
3. 添加同步日志查询功能
|
||
4. 支持同步历史记录
|
||
5. 添加数据校验和冲突解决机制
|
||
|
||
## 技术栈
|
||
|
||
- **后端框架**: FastAPI + SQLAlchemy (异步)
|
||
- **数据库**: MySQL 8.0.43
|
||
- **外部连接**: aiomysql
|
||
- **日志**: structlog
|
||
- **认证**: JWT Bearer Token
|
||
|
||
## 相关文档
|
||
|
||
- 数据库架构文档: `kaopeilian-backend/数据库架构-统一版.md`
|
||
- API文档: https://kpl.ireborn.com.cn/docs
|
||
- 项目仓库: GitHub (员工同步分支)
|
||
|
||
|