# `app/core/data_parse/parse.py` 函数结构分析报告 ## 概述 `parse.py` 是 DataOps 平台中的核心数据解析模块，主要负责名片图像识别、文本解析、重复记录处理、酒店管理等功能。该文件包含了完整的数据解析和处理系统，涵盖从图像识别、AI文本解析、重复检测到数据管理的完整流程。 ## 函数调用关系图 ```mermaid graph TD     %% 数据模型类     A[BusinessCard] --> A1[to_dict]     B[DuplicateBusinessCard] --> B1[to_dict]     C[ParseTaskRepository] --> C1[to_dict]     D[HotelPosition] --> D1[to_dict]     E[HotelGroupBrands] --> E1[to_dict]     %% 图像解析核心流程     F[extract_text_from_image] --> G[ocr_extract_text]     F --> H[parse_text_with_deepseek]     H --> I[extract_json_from_text]     H --> J[extract_fields_from_text]     %% 名片处理主流程     K[process_business_card_image] --> L[parse_text_with_qwen25VLplus]     M[add_business_card] --> N[check_duplicate_business_card]     M --> O[get_minio_client]     M --> P[update_career_path]     M --> Q[create_main_card_with_duplicates]     %% 重复记录处理     N --> R[mobile_numbers_overlap]     N --> S[normalize_mobile_numbers]     Q --> T[merge_mobile_numbers]     Q --> P     %% 重复记录管理     U[process_duplicate_record] --> P     U --> V[get_duplicate_records]     W[get_duplicate_record_detail] --> B     X[fix_broken_duplicate_records] --> B     %% 网页解析流程     Y[process_webpage_with_QWen] --> Z[process_single_talent_card]     Z --> N     Z --> AA[download_and_upload_image_to_minio]     AA --> O     %% 名片业务操作     BB[update_business_card] --> CC[search_business_cards_by_mobile]     BB --> DD[get_business_card]     BB --> P     EE[get_business_cards] --> A     FF[update_business_card_status] --> A     %% 图数据库查询     GG[query_neo4j_graph] --> HH[parse_text_with_deepseek]     II[talent_update_tags] --> JJ[talent_get_tags]     %% 酒店职位管理     KK[get_hotel_positions_list] --> D     LL[add_hotel_positions] --> D     MM[update_hotel_positions] --> D     NN[query_hotel_positions] --> D     OO[delete_hotel_positions] --> D     %% 酒店品牌管理     PP[get_hotel_group_brands_list] --> E     QQ[add_hotel_group_brands] --> E     RR[update_hotel_group_brands] --> E     SS[query_hotel_group_brands] --> E     TT[delete_hotel_group_brands] --> E     %% 解析任务管理     UU[get_parse_tasks] --> C     VV[get_parse_task_detail] --> C     %% 工具函数     O --> |MinIO连接| WW[MinIO Client]     H --> |AI解析| XX[DeepSeek API]     L --> |AI解析| YY[Qwen API]     GG --> |AI生成| XX     %% 分组样式     subgraph "数据模型层"         A         B         C         D         E     end     subgraph "图像解析"         F         G         H         I         J         K         L     end     subgraph "名片处理"         M         N         O         P         Q         R         S         T     end     subgraph "重复记录处理"         U         V         W         X     end     subgraph "网页解析"         Y         Z         AA     end     subgraph "业务操作"         BB         CC         DD         EE         FF     end     subgraph "图数据库"         GG         II         JJ     end     subgraph "酒店管理"         KK         LL         MM         NN         OO         PP         QQ         RR         SS         TT     end     subgraph "任务管理"         UU         VV     end ``` ## 详细功能模块分析 ### 1. 数据模型类（Database Models） #### 1.1 主要模型类 | 模型类 | 用途 | 主要字段 | |--------|------|----------| | `BusinessCard` | 名片信息数据模型 | name_zh/en, title_zh/en, mobile, email, hotel_zh/en, address_zh/en, career_path 等 | | `DuplicateBusinessCard` | 重复名片处理数据模型 | main_card_id, suspected_duplicates, duplicate_reason, processing_status | | `ParseTaskRepository` | 解析任务存储库数据模型 | task_name, task_status, task_type, task_source, parse_result | | `HotelPosition` | 酒店职位数据模型 | department_zh/en, position_zh/en, level_zh/en | | `HotelGroupBrands` | 酒店品牌组数据模型 | group_name_zh/en, brand_name_zh/en, positioning_level_zh/en | #### 1.2 共同特性 - 每个模型都包含 `to_dict()` 方法用于数据序列化 - 包含创建时间、更新时间、状态等标准字段 - 支持中英文双语字段 ### 2. 核心解析功能模块 #### 2.1 图像文本提取流程 ``` extract_text_from_image() [主入口]     ├── ocr_extract_text()           # OCR文本提取     └── parse_text_with_deepseek()   # AI解析         ├── extract_json_from_text() # JSON内容提取         └── extract_fields_from_text() # 字段信息提取 ``` **主要函数说明：** - **`extract_text_from_image(image_data)`**:   - 主入口函数，协调OCR和AI解析流程   - 输入：图像二进制数据   - 输出：提取的名片信息字典 - **`ocr_extract_text(image_data)`**:   - 使用pytesseract进行OCR文本提取   - 支持多语言识别 - **`parse_text_with_deepseek(text)`**:   - 使用DeepSeek API解析文本中的名片信息   - 构建专业的提示语进行信息提取   - 支持中英文双语信息分离 #### 2.2 AI解析功能 ``` AI解析模块 ├── parse_text_with_deepseek()    # DeepSeek文本解析 ├── parse_text_with_qwen25VLplus() # Qwen图像直接解析 ├── extract_json_from_text()      # JSON内容提取工具 └── extract_fields_from_text()    # 字段提取工具 ``` ### 3. 名片处理业务逻辑 #### 3.1 重复检测与处理流程 ``` 重复检测流程 check_duplicate_business_card()     ├── mobile_numbers_overlap()    # 检查手机号重叠     ├── normalize_mobile_numbers()  # 标准化手机号     └── 返回检测结果和处理建议 创建记录流程 create_main_card_with_duplicates()     ├── merge_mobile_numbers()      # 合并手机号     ├── update_career_path()        # 更新职业轨迹     └── 创建主记录和重复记录标记 ``` **重复检测逻辑：** 1. 基于姓名和手机号进行匹配 2. 支持手机号部分重叠检测 3. 提供更新、创建新记录、标记重复等处理策略 #### 3.2 名片业务操作 | 函数名 | 功能 | 主要调用 | |--------|------|----------| | `update_business_card()` | 更新名片信息 | `search_business_cards_by_mobile()`, `get_business_card()`, `update_career_path()` | | `get_business_cards()` | 获取名片列表 | 直接查询BusinessCard模型 | | `update_business_card_status()` | 更新名片状态 | 状态字段更新 | | `search_business_cards_by_mobile()` | 按手机号搜索 | 模糊匹配查询 | | `get_business_card()` | 获取单个名片详情 | ID精确查询 | ### 4. 重复记录管理 #### 4.1 重复记录处理流程 ``` 重复记录处理 process_duplicate_record()     ├── 获取重复记录详情     ├── 根据action执行不同操作：     │   ├── merge_to_suspected  # 合并到疑似重复记录     │   ├── keep_main          # 保留主记录     │   └── ignore             # 忽略处理     └── 更新处理状态 ``` #### 4.2 重复记录管理函数 - **`get_duplicate_records(status=None)`**: 获取重复记录列表，支持状态过滤 - **`get_duplicate_record_detail(duplicate_id)`**: 获取重复记录详细信息 - **`fix_broken_duplicate_records()`**: 修复损坏的重复记录关联 ### 5. 图数据库查询 #### 5.1 Neo4j图查询流程 ``` 图数据库查询流程 query_neo4j_graph()     ├── 步骤1：获取所有人才标签列表     ├── 步骤2：使用DeepSeek匹配查询需求与标签     ├── 步骤3：生成Cypher查询语句     └── 步骤4：执行查询并返回结果 ``` #### 5.2 人才标签管理 - **`talent_update_tags(data)`**: 批量更新人才标签关系 - **`talent_get_tags(talent_id)`**: 获取指定人才的标签列表 ### 6. 酒店管理功能 #### 6.1 酒店职位管理 | 函数名 | 功能 | 描述 | |--------|------|------| | `get_hotel_positions_list()` | 获取职位列表 | 支持分页和条件过滤 | | `add_hotel_positions()` | 添加酒店职位 | 新增职位记录 | | `update_hotel_positions()` | 更新职位信息 | 修改现有职位 | | `query_hotel_positions()` | 查询特定职位 | 根据ID获取详情 | | `delete_hotel_positions()` | 删除职位 | 软删除（状态标记） | #### 6.2 酒店品牌管理 | 函数名 | 功能 | 描述 | |--------|------|------| | `get_hotel_group_brands_list()` | 获取品牌列表 | 支持分页和过滤 | | `add_hotel_group_brands()` | 添加酒店品牌 | 新增品牌记录 | | `update_hotel_group_brands()` | 更新品牌信息 | 修改现有品牌 | | `query_hotel_group_brands()` | 查询特定品牌 | 根据ID获取详情 | | `delete_hotel_group_brands()` | 删除品牌 | 软删除（状态标记） | ### 7. 解析任务管理 #### 7.1 任务管理功能 - **`get_parse_tasks(page, per_page, task_type, task_status)`**:   - 获取解析任务列表   - 支持分页、类型过滤、状态过滤   - 按创建时间倒序排列 - **`get_parse_task_detail(task_name)`**:   - 根据任务名称获取详细信息   - 返回完整的任务执行结果 ### 8. 工具函数 #### 8.1 数据处理工具 | 函数名 | 功能 | 使用场景 | |--------|------|----------| | `normalize_mobile_numbers()` | 标准化手机号码 | 去重并限制最多3个 | | `mobile_numbers_overlap()` | 检查手机号重叠 | 重复检测时使用 | | `merge_mobile_numbers()` | 合并手机号码 | 重复记录合并时使用 | | `get_minio_client()` | 获取MinIO客户端 | 文件存储操作 | #### 8.2 外部服务集成 - **MinIO 对象存储**: 用于存储名片图片和网页内容 - **DeepSeek AI**: 用于文本解析和Cypher语句生成 - **Qwen AI**: 用于图像直接解析 - **Neo4j 图数据库**: 用于人才关系图查询 ## 架构特点 ### 1. 分层架构设计 ``` API接口层 (routes.py)     ↓ 业务逻辑层 (parse.py主要函数)     ↓ 数据访问层 (数据模型类)     ↓ 外部服务层 (AI服务、存储服务、数据库) ``` ### 2. 模块化设计原则 - **功能模块相对独立**: 图像解析、重复检测、酒店管理等功能模块相互独立 - **依赖注入**: 通过函数参数传递依赖，降低模块间耦合度 - **接口标准化**: 统一的返回格式和错误处理机制 ### 3. 错误处理与日志 - **完整的异常处理**: 大多数函数都包含try-catch异常处理 - **详细的日志记录**: 关键操作都有详细的日志记录 - **标准化错误响应**: 统一的错误码和消息格式 ### 4. AI集成策略 - **多模型支持**: 集成DeepSeek和Qwen等多个AI模型 - **智能降级**: Qwen失败时自动降级到OCR+DeepSeek方案 - **提示工程**: 精心设计的提示语提高解析准确率 ## 性能优化建议 1. **缓存机制**: 对频繁查询的酒店品牌、职位信息增加缓存 2. **批量处理**: 重复检测可以考虑批量处理提高效率 3. **异步处理**: 图片上传和AI解析可以考虑异步处理 4. **数据库优化**: 对查询频繁的字段添加索引 ## 总结 `parse.py` 文件是一个功能完整、架构清晰的数据解析处理系统。它成功地将图像识别、AI文本解析、数据管理、重复检测等复杂功能整合在一起，形成了一个高度模块化、可维护的系统架构。通过合理的函数调用关系设计，实现了各功能模块间的低耦合高内聚，为后续的功能扩展和维护提供了良好的基础。