# GreatScanner

**Repository Path**: yihiko/GreatScanner

## Basic Information

- **Project Name**: GreatScanner
- **Description**: GreatScanner 是一款集成 OCR 文字识别、多格式文件转换（图转 Word/Excel/PDF）、分布式用户认证、文件备份与历史管理、智能物体计数 等功能的综合扫描处理工具。
- **Primary Language**: C++
- **License**: MulanPSL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 20
- **Forks**: 7
- **Created**: 2025-08-08
- **Last Updated**: 2025-09-03

## Categories & Tags

**Categories**: doc-tools

**Tags**: Qt, boost, MySQL, Redis, Grpc

## README

- # GreatScanner

  ## 项目简介

  GreatScanner 是一款集成 **OCR 文字识别**、**多格式文件转换（图转 Word/Excel/PDF）**、**分布式用户认证**、**文件备份与历史管理**、**智能物体计数** 等功能的综合扫描处理工具。项目采用 C++（后端）+ Qt（客户端）技术栈，支持高并发服务、本地 / 云端协同处理，以及全局快捷键、截图识别等便捷操作。

  ## 核心功能模块

  | 模块           | 核心能力                                                     |
  | -------------- | ------------------------------------------------------------ |
  | **界面与交互** | 自定义控件（CardView、RoundProgressBar 等）、Flow 动态布局、系统托盘、全局快捷键（Alt+S 截图） |
  | **OCR 识别**   | 基于 PaddleOCR/OpenCV 的文字提取、截图识别（共享内存传输，无文件 I/O 开销） |
  | **文件转换**   | 图片转 Word/Excel/PDF、PDF 水印添加、卡片（矩形）识别        |
  | **物体计数**   | 基于 OpenCV 分水岭算法的物体计数，支持边缘 / 区域两种标记模式，实时显示标记结果 |
  | **证件检测**   | 基于 YOLOv8-Pose 训练自定义卡片角点定位模型，并用opencv透视矫正 |
  | **用户认证**   | 注册 / 登录 / 密码重置（邮箱验证码 + Redis 存储）、密码 BCrypt 哈希加密 |
  | **分布式服务** | GateServer（登录网关）、VerifyServer（验证码服务）、ResServer（资源备份）、StatusServer（负载均衡） |
  | **数据存储**   | MySQL（用户 / 文件元数据）、Redis（验证码 / Token）、SQLite（本地操作历史）、连接池管理 |
  | **搜索与管理** | Trie 树自动补全、Jieba 中文分词搜索（工具 / 历史记录 / 备份页面）、分页加载历史记录 |
  
  ## 技术栈
  
  | 分类       | 技术 / 框架                                                  |
  | ---------- | ------------------------------------------------------------ |
  | 后端开发   | C++17、Asio（异步网络）、gRPC（服务通信）、Protobuf（数据序列化）、MySQL/Redis/SQLite |
  | 客户端开发 | Qt 5/6（界面、网络、IPC）、Qt Pdf 模块（水印）、共享内存 IPC |
  | 识别与算法 | OpenCV（图像处理）、PaddleOCR（文字识别）、YOLOv8-Pose（角点检测）、Jieba（中文分词）、Trie 树（搜索补全） |
  | 性能优化   | IO 线程池（TCP/HTTP 分离）、无锁日志队列、数据库连接池、文件分片传输（64KB 块） |
  
  ## 项目开发历程（2025.2 - 2025.8）
  
  ### 1. 基础构建阶段（2025.2.20 - 2025.3.20）
  
  - 实现 `imgeditor` 窗口与自定义控件（CardView、Panel、RoundProgressBar 等）
  - 开发动态布局 `FlowLayout`，支持窗口大小自适应
  - 初步实现 `tasklist` 窗口（后续弃用）
  
  ### 2. 服务端核心开发（2025.3.28 - 2025.4.1）
  
  - 基于 Asio 实现 `CServer` 服务端，支持 IO 线程池（提升并发）
  - 开发 MySQL 连接池 + DAO/Mgr 层（自动管理连接，简化事务调用）
  - 实现 HTTP/TCP 双协议支持，修复端口冲突问题（独立 acceptor 分离服务）
  - 升级日志系统为无锁队列，支持单例模式与格式化输出
  
  ### 3. 用户认证与客户端功能（2025.4.2 - 2025.4.14）
  
  - Qt 客户端：`HttpClient` 单例、注册 / 登录 / 密码重置界面
  - 服务端：用户注册 / 登录事务、BCrypt 密码哈希（异步计算，避免阻塞）
  - 新增 Verify 服务：邮箱验证码（SMTP）+ Redis 过期存储（10 分钟有效）
  
  ### 4. OCR 与文件处理（2025.4.16 - 2025.6.17）
  
  - 集成 OpenCV/PaddleOCR，实现卡片识别、文字提取功能
  - 优化架构：Qt 本地进程池处理 OCR 任务，结果云端备份（减少网络传输）
  - 实现图片转 Word/Excel/PDF 核心功能，修复排版与编码问题
  
  ### 5. 交互优化与搜索（2025.6.19 - 2025.7.26）
  
  - 新增选区截图（支持箭头 / 图形标注）、全局快捷键（Alt+S 触发）
  - 开发搜索引擎框架：Trie 树自动补全、Jieba 中文分词（支持多页面精准搜索）
  - 优化单例模板（支持有参构造）、修复全局热键崩溃问题
  
  ### 6. 数据管理与分布式（2025.7.27 - 2025.8.18）
  
  - SQLite 本地历史记录：`file_info` 表存储操作记录，`BaseDao` 封装 CRUD 接口
  - 分布式架构：拆分 GateServer/VerifyServer/ResServer，gRPC 跨服务通信
  - 文件分片传输：上传 / 下载分块（64KB），支持跨 ResServer 文件转发（grpc 内部流式传输）
  - 验证码服务重构：Node.js 实现 SMTP 邮件发送（解决中文乱码问题）
  
  ### 7.物体计数功能（2025.8.19 - 2025.8.21）
  
  #### （1）物体计数功能（2025.8.19 - 2025.8.21）
  
  - **算法实现**：基于 OpenCV 分水岭算法，支持边缘检测和区域标记两种模式
  - **性能优化**：处理速度从 9000ms 降至 280ms（优化标记计算逻辑）
  - 交互设计：
    - 新增 `CountResItem` 图元，实时显示标记结果且不影响原图
    - 支持降噪参数调节，计算结果缓存（避免重复运算）
    - 子线程运算（`moveToThread`），防止阻塞 UI
  
  #### （2）证件检测功能（2025.8.22-8.24）
  
  - 模型训练：基于 YOLOv8-Pose 预训练模型（`yolov8s-pose.pt`），训练自定义卡片角点定位模型
    - 数据集：500+ 张卡片图片，标注四角关键点
    - 训练参数：epoch=50、imgsz=640、batch=16，启用数据增强
  - **与Python端交互模式**：Qt端使用QProcess传参调用py脚本实现识别
  - **效果验证**：训练曲线收敛正常，验证集角点定位准确率满足需求（示例图见项目路径 `keypoint_detection/card_corner_detection/exp5`）
  
  ## 关键架构设计
  
  ### 分布式服务架构
  
  ```mermaid
  sequenceDiagram
      participant Client as client
      participant GateServer as GateServer
      participant VerifyServer as VerifyServer
      participant Redis as Redis
      participant EmailService as 邮箱服务
      participant StatusServer as StatusServer
      participant ResServer as ResServer
      participant MySQL as MySQL
  
      Client->>GateServer: 注册/登录请求
      GateServer->>VerifyServer: gRPC 验证码请求
      VerifyServer->>Redis: 存储验证码（10分钟过期）
      VerifyServer->>EmailService: 发送验证码
      Client->>GateServer: 提交验证码+凭证
      GateServer->>StatusServer: 请求 ResServer 分配
      StatusServer->>Redis: 生成 Token
      GateServer->>Client: 返回 ResServer 地址+Token
      Client->>ResServer: TCP 长连接（文件上传/下载）
      ResServer->>MySQL: 存储文件元数据
      ResServer->>Redis: 验证 Token
  ```
  
  ## 快速启动
  
  ### 1. 环境依赖
  
  - 编译工具：MSVC 2019+/GCC 9+（支持 C++17）
  - 依赖库：Qt 5.15+/6.x、Asio 1.24+、MySQL 8.0、Redis 6.0、PaddleOCR 2.6+、Ultralytics（YOLOv8）
  - 其他：Jieba 分词库、gRPC 1.50+、Protobuf 3.21+
  
  ### 2. 部署步骤
  
  1. 服务端启动：
     - 启动 Redis/MySQL，创建用户 / 文件元数据表（见 `2025.7.28` 章节 SQL 脚本）
     - 启动 `StatusServer`（负载均衡）、`VerifyServer`（Node.js 脚本）、`ResServer`（资源服务）、`GateServer`（登录网关）
  2. 客户端启动：
     - Qt 编译客户端项目，配置服务端地址（`config.json`）
     - 运行客户端，通过邮箱注册账号，登录后使用 OCR / 文件转换功能
  
  ### 3. 常用功能触发
  
  - **截图识别**：按下 `Alt+S` 选择区域，自动识别文字
  - **文件转换**：导入图片，选择「转 Word/Excel/PDF」，结果保存在本地 / 云端
  - **历史记录**：在「历史页面」查看本地操作记录，支持关键词搜索
  
  ## 后续规划
  
  1. 完善断点续传功能（基于现有分片协议扩展）
  2. 优化 OCR 识别精度
  3. 支持公式识别
  4. 增加链接分享下载功能