# 检验信息同步系统开发

**Repository Path**: xxq_cube/experience-sync-engine

## Basic Information

- **Project Name**: 检验信息同步系统开发
- **Description**: 检验信息同步系统开发
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-22
- **Last Updated**: 2026-05-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 赛宝-飞书 校准数据同步系统

专为**中国赛宝实验室校准结果发布系统**与**企业内部飞书设备台账**设计的单向自动同步工具。

- 自动从赛宝系统提取最新校准结果（含 OCR 验证码自动登录）
- 按"管理号 → 设备新编号"精准匹配飞书表格记录
- **永不删除**飞书表格中的任何设备记录（仅更新、不新增、不删除）
- 同步完成后飞书消息卡片推送通知（含更新明细）
- 支持 Cookie 持久化，7 天内免重新登录

## 功能概览

| 功能 | 说明 |
|------|------|
| 自动登录 | Playwright + ddddocr 识别验证码，自动登录赛宝系统 |
| 全量拉取 | 通过 API 劫持技术一次拉取全部 593+ 条校准记录 |
| 精准匹配 | 赛宝 `managerNumber` → 飞书 `设备新编号` 匹配 |
| 增量更新 | 仅更新有变化的 4 个字段，跳过无变化记录 |
| 消息推送 | 同步完成后推送飞书卡片消息，包含统计和明细 |
| Cookie 复用 | 登录凭证持久化，7 天内免重新登录 |

## 同步字段映射

| 赛宝 API 字段 | → | 飞书表格列 |
|---|---|---|
| `managerNumber` (管理号) | → | 设备新编号（匹配键） |
| `createDate` (校准日期) | → | 校准日期 |
| `validityPeriod` (有效期) | → | 有效期 |
| `certificateCode` (证书编号) | → | 校准证号 |
| `measureResult` (校准结论) | → | 验收结果 |
| 当前时间 | → | 最后同步时间 |

## 项目结构

```
saibao_feishu_sync/
├── main.py              # 主入口
├── auth.py              # 赛宝登录（验证码OCR + Cookie管理）
├── fetcher.py           # 赛宝数据拉取（API劫持全量获取）
├── feishu.py            # 飞书多维表格API + 消息推送
├── sync.py              # 同步业务逻辑（匹配、变更检测、通知）
├── config.py            # 配置加载
├── logger.py            # 日志配置
├── .env.example         # 配置模板
├── requirements.txt     # Python依赖
├── data/
│   ├── cookies/         # 赛宝登录Cookie存储
│   ├── backup/          # CSV备份
│   └── reports/         # 报告输出
└── logs/                # 运行日志
```

## 快速开始

### 1. 环境要求

- Python 3.10+
- Windows / macOS / Linux

### 2. 安装

```bash
cd saibao_feishu_sync
pip install -r requirements.txt
playwright install chromium
```

### 3. 配置

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

编辑 `.env`，填写以下配置：

**赛宝系统**（必填）
- `SAIBAO_LOGIN_URL` — 赛宝登录页地址
- `SAIBAO_QUERY_URL` — 校准数据查询页地址
- `SAIBAO_USERNAME` — 登录账号
- `SAIBAO_PASSWORD` — 登录密码

**飞书应用**（必填）
- `FEISHU_APP_ID` — 应用 App ID
- `FEISHU_APP_SECRET` — 应用 App Secret
- `FEISHU_BITABLE_APP_TOKEN` — 多维表格文档 token
- `FEISHU_BITABLE_TABLE_ID` — 数据表 table_id
- `FEISHU_CHAT_ID` — 群聊 ID，用于接收同步通知

**飞书应用所需权限**
| 权限 | 用途 |
|------|------|
| `bitable:app` | 读写多维表格 |
| `im:message` | 推送同步通知消息 |

在飞书开放平台 → 应用 → 权限管理中开启后，**必须发布新版本**才生效。

### 4. 运行

```bash
python -m saibao_feishu_sync.main
```

可选参数：
- `--mode full` — 全量对比模式
- `--log-level DEBUG` — 调试日志

### 5. 定时运行（Windows）

使用 Windows 任务计划程序，创建每日定时任务：
- 程序：`python.exe`
- 参数：`-m saibao_feishu_sync.main`
- 起始于：项目目录路径

## 技术栈

| 模块 | 技术 |
|------|------|
| 浏览器自动化 | Playwright |
| 验证码 OCR | ddddocr |
| 飞书 API | lark-oapi SDK |
| 数据处理 | pandas |
| 日志 | loguru |
| 消息推送 | 飞书消息卡片 |

## 核心设计

### API 劫持全量拉取
通过 Playwright `page.route()` 拦截赛宝查询 API 的 POST 请求，将 `pageSize` 从 20 修改为 1000，一次请求获取全部数据，避免翻页逻辑。

### 变更检测
以"管理号/设备新编号"为 key 匹配飞书表格记录，逐个字段对比新旧值，仅当 校准日期/有效期/校准证号/验收结果 任一字段有变化时才更新。无变化则跳过，减少飞书 API 调用量。

### 消息通知
同步完成后通过飞书 IM API 发送卡片消息到指定群聊，包含：
- 拉取/更新/跳过/错误 数量统计
- 更新时间
- 每条更新记录的设备编号及字段变更详情

## License

内部使用