跳转至

三项目复现与重构方案：clock、pc_monitor、paddleocrproject

更新时间：2025-11-11 作者：Lifu

背景与目标

  • 目标：基于现有三个项目（clock、pc_monitor、paddleocrproject）的文档与代码结构，制定一份“可操作、可复现、可重构”的实施方案，后续可按本文一步步复现实例或对原项目进行工程化重构。
  • 交付物：
  • 可成功运行的三项目最小可用版本（MVP）与核心功能清单
  • 标准化的环境/依赖/运行脚本
  • 基于单元测试与手动验收清单的验证结果
  • 重构路线图（阶段划分与优先级）

通用环境与约定

  • 操作系统：Windows 10/11
  • Python：建议 3.10+（按项目最低要求兼容调整）
  • 虚拟环境：python -m venv .venv，激活后安装依赖
  • 目录约定：
  • clock：C:\Users\YourName\clock
  • pc_monitor：C:\Users\YourName\code\cmd\pc_monitor
  • paddleocrproject：C:\Users\YourName\code\paddleocrproject
  • 依赖安装一律在虚拟环境中进行，避免污染全局
  • 统一日志与配置位置，尽量不需要管理员权限运行

项目一：clock（防睡眠/托盘/GUI）

1) 项目概述

  • 目的：防止系统休眠（移动鼠标/系统API），提供 GUI 与 CLI，集成系统托盘控制与任务栏自动隐藏设置，含日志与配置管理。
  • 关键模块（自检自描述）：
  • keep_awake_core.py：防睡眠核心逻辑（定时器/方法选择）
  • keep_awake_gui.py / keep_awake_cli.py：GUI 与命令行入口
  • config_manager.py：配置加载/保存（默认与兼容）
  • log_manager.py：日志输出（控制台/文件）
  • taskbar_manager.py：任务栏自动隐藏开关（注册表 + Explorer 重启）
  • system_activity_checker.py / power_activity_analyzer.py：系统/电源活动检测
  • 启动脚本：start_gui.bat、start_cli.bat；图标 keepico.ico

2) 环境与依赖

  • requirements.txt（摘要）：
  • PyQt6>=6.4.0（GUI）
  • 可选：pyautogui（更强鼠标控制）
  • 安装：
  • 创建并激活 venv
  • pip install -r requirements.txt

3) 运行与验证

  • GUI：python keep_awake_gui.py
  • CLI：python keep_awake_cli.py（如提供子命令：start/stop/status）
  • 托盘验证：关闭窗口应最小化到托盘；双击托盘图标恢复
  • 任务栏自动隐藏：GUI 勾选后应立即生效（必要时重启 Explorer）
  • 日志验证：滚动策略、生存期与错误记录

4) 重构/复现计划（建议里程碑）

  • M1 最小可用（1-2 天）
  • 复现 core + CLI；支持两种防睡眠方法；通过日志自检
  • 配置默认值与兼容处理；添加基本单测（核心定时器/状态）
  • M2 GUI 与托盘（1-3 天）
  • 复现 GUI 主面板与托盘菜单；集成 start/stop/状态显示
  • 引入 taskbar_manager，提供自动隐藏开关；异常路径弹窗 + 日志
  • M3 工程化（1-2 天）
  • 日志滚动与等级统一；打包脚本（pyinstaller 可选）
  • 完整 README + 示例配置；错误矩阵与排障指引

5) 验收清单

  • 30 分钟稳定运行，CPU/内存占用可接受
  • 两种防睡眠方式均生效；GUI 控件与托盘交互正确
  • 任务栏隐藏/恢复成功、可持久化
  • 单测通过（核心逻辑、配置、关键异常）

项目二：pc_monitor（电源/系统/网络/相机/报告/GUI）

1) 项目概述

  • 功能（来源：README）：
  • 电源监控（交流/电池、拔出事件、低电量告警）
  • 系统监控（启动/关闭、运行时间、CPU/内存/磁盘）
  • 网络监控（DNS 连通性检测）
  • 自动拍照（事件触发，延迟与质量可配）
  • 日志系统（轮转/大小限制/多级别）
  • 报告生成（HTML，包含 24 小时事件与截图）
  • GUI + 托盘 + 通知；完整配置管理与自启动

2) 目录与模块

pc_monitor/
├── main.py               # 入口
├── config.json           # 配置
├── requirements.txt      # 依赖
├── config_manager.py     # 配置管理
├── logger.py             # 日志
├── power_monitor.py      # 电源监控
├── system_monitor.py     # 系统监控
├── camera_capture.py     # 相机
├── report_generator.py   # 报告
├── gui.py                # GUI
└── autostart.py          # 自启动

3) 环境与依赖

  • 建议 Python 3.8+
  • pip install -r requirements.txt
  • Windows 首次运行需允许相机权限

4) 运行与验证

  • python main.py 或 start.bat
  • 仪表盘：电源/CPU/内存/运行时长/最近事件
  • 事件日志：时间序列表；刷新可见最新
  • 拍摄照片：列表与“打开文件夹”；保存到 captures/
  • 报告：点击按钮或定时任务生成 HTML 到 reports/
  • 托盘：关闭窗口 → 最小化到托盘；双击恢复；右键菜单可退出

5) 重构/复现计划（建议里程碑）

  • M1 最小可用（1-2 天）
  • 事件总线 + 日志；电源/系统/网络最小监控；相机拍照流水线
  • 配置与默认值；基础 GUI 面板（状态/日志）
  • M2 报告与托盘（1-2 天）
  • HTML 报告模板与生成；托盘交互与通知；日志轮转
  • M3 健壮性与生态（1-2 天）
  • 相机占用/异常恢复；自启动/权限提示；单测与端到端验收脚本

6) 验收清单

  • 电源拔出触发拍照；低电量告警可见
  • 报告按时/按需可生成，包含截图与统计
  • 日志轮转与大小限制生效
  • GUI/托盘交互与通知可靠

项目三：paddleocrproject（PDF → 文本/JSON 队列批处理 + GUI 监控）

1) 项目概述（来源：README_使用说明.md / 使用说明.md）

  • 使命：在 CPU 环境下对 PDF 进行批量 OCR，输出 txt 与页脚/页码 JSON；提供队列/监控/报告能力；修复黑窗口闪烁（统一使用 pythonw + CREATE_NO_WINDOW）。
  • 主要目录：
  • ocr_app（CLI/核心逻辑，如 enqueue/run-worker/status/report 等）
  • scripts（gui_panel / run_batches / queue_monitor / sample_ocr / small_batch_test）
  • outputs（pocr_txt、runs/...）/ logs（worker/runner/monitor/failed）/ state（queue.db/pause.flag）/ reports
  • tests（布局/双栏排序单测）
  • 顶层：restart_gui.py / check_status.py / start_gui.py / start_worker.py

2) 环境与依赖（CPU）

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -U pip
python -m pip install -U paddlepaddle paddleocr pymupdf
python -c "import fitz; from paddleocr import PaddleOCR; print('OK')"

3) 快速使用

  • 启动 GUI：python restart_gui.py
  • 查看状态：python check_status.py
  • 启动 Worker：python start_worker.py

4) CLI 常用命令（ocr_app）

  • 目录初始化：.\.venv\Scripts\python -m ocr_app.cli init
  • 单文件 OCR：.\.venv\Scripts\python -m ocr_app.cli ocr-one --pdf <file.pdf> --zoom 1.6 --header-ratio 0.06 --footer-ratio 0.08
  • 入队（去重）：.\.venv\Scripts\python -m ocr_app.cli enqueue --dir yaodian_2bu --limit 200 --dedup
  • 运行 Worker：.\.venv\Scripts\python -m ocr_app.cli run-worker --max-jobs 200 --zoom 1.6 --header-ratio 0.06 --footer-ratio 0.08 --job-timeout 240
  • 报告：.\.venv\Scripts\python -m ocr_app.cli report --out reports/queue_speed_report.md --fold-by-name

5) 设计要点（已实现/需复现）

  • GUI 监控：500ms 计数刷新 + 2s 日志聚合；打开目录/帮助菜单
  • 队列模型：SQLite queue.db；可暂停（state/pause.flag）；run_batches 自动分批
  • OCR 策略：PaddleOCR mobile，PyMuPDF 渲染；页眉过滤 header_ratio；页脚捕获 footer_ratio → JSON
  • 日志：控制台 INFO + 文件 DEBUG（utf-8-sig，PowerShell 5 兼容）
  • 单测：双栏布局排序（tests/test_layout_order.py）100% 通过

6) 重构/复现计划（建议里程碑）

  • M1 最小流水线（1-3 天）
  • ocr-one + 目录初始化 + 基础日志；生成 txt 与 JSON
  • M2 队列与监控（1-2 天）
  • enqueue/run-worker/status/report；GUI 面板与黑窗修复策略
  • M3 工程化（1-2 天）
  • run_batches 全库挂机；日志 Tail 与查询优化；故障恢复与告警（可选）

7) 验收清单

  • 20 个 PDF 小批量跑通，报告生成；JSON 页脚/页码数据完备
  • 队列模式 200 任务流畅，GUI 指标刷新无阻塞
  • 日志编码正确，PowerShell 5/终端不乱码

通用工程化建议

  • 统一日志格式：time | level | module | message；文件滚动策略统一
  • 统一配置策略：默认值 + schema 校验 + 版本兼容；示例配置随仓库提供
  • 打包与启动脚本：pyinstaller（可选）；start_gui/start_cli/start_worker 标准化
  • 单元测试优先：核心算法/状态机/配置；再覆盖 GUI 关键交互（pytest-qt）
  • 文档即代码：README 更新规范；新增 CHANGELOG；关键命令速查表

附录：一键复现清单（示例）

clock（GUI）

cd C:\Users\YourName\clock
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
python keep_awake_gui.py

pc_monitor（监控 + 报告）

cd C:\Users\YourName\code\cmd\pc_monitor
pip install -r requirements.txt
python main.py

paddleocrproject（队列批处理 + GUI）

cd C:\Users\YourName\code\paddleocrproject
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -U pip
python -m pip install -U paddlepaddle paddleocr pymupdf
python restart_gui.py
python start_worker.py

— 完 —