012-kaopeilian/知识库/员工同步功能总结.md

员工同步功能实施总结

功能概述

从公司钉钉员工表（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表修改

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

测试示例:

# 员工登录（何平-护士长）
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:

curl -X POST "https://kpl.ireborn.com.cn/api/v1/employee-sync/sync" \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Content-Type: application/json"

预览待同步数据

curl -X GET "https://kpl.ireborn.com.cn/api/v1/employee-sync/preview" \
  -H "Authorization: Bearer {TOKEN}"

查询系统状态

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 (员工同步分支)