本项目是专为医院文书管理、病案科、住院服务中心等一线岗位设计的轻量级纸质流转件数字化工具。它不替代HIS或EMR，而是聚焦「入院证、检验单、手术同意书」等高频手写/打印流转件，在无专用扫描仪、无系统对接权限、无IT支持的现实条件下，用手机拍照+本地OCR完成从图像到结构化台账的闭环。核心机制是：拍照后自动识别关键字段（住院号、姓名、科室、日期、诊断），按文档类型分类归档，生成可查、可导、可追溯的SQLite本地台账；全部能力封装为命令行（CLI）、网页界面（Streamlit）、REST API三套入口，技术栈完全开源可控，OCR用Tesseract（chi_sim中文包），数据库用SQLite，导出支持CSV/Excel/PDF/JSON，隐私字段默认脱敏，配置项开放在config/目录下，所有逻辑模块（图片预处理、字段提取、标准化、文档分类、历史追踪）均独立可调。

定位与能力范围

我们不做通用OCR平台，也不做云端SaaS服务。本系统只解决一个具体问题：当护士站堆着一摞刚收进来的入院证，当检验科窗口贴着几十张待分拣的化验单，当手术室前台反复核对手写同意书上的患者信息时，如何跳过人工抄录、跳过Excel中转、跳过二次录入，让一张照片直接变成一条带时间戳、带来源、带置信度的台账记录。

因此能力边界非常明确：
- 只处理静态图像（JPG/PNG）和单页PDF，不支持多页PDF批量拆分或视频帧提取；
- 只识别中文为主、中英混排的医疗文书，不覆盖手写体训练模型或小语种；
- 字段提取基于规则+关键词匹配（如“入院”“住院证”触发入院证类型，“手术”“同意书”触发手术同意书类型），不依赖大语言模型微调；
- 台账存储完全本地化，数据库为单文件SQLite，无网络依赖、无账户体系、无中心服务器；
- 不提供OCR模型训练能力，但预留了field_mapping.json和document_types.json两个配置文件，供用户自定义科室别名、诊断缩写映射、新增文档类型及必填字段。

这决定了它适合三类使用者：
1. 没有IT支持的小型医院/社区卫生中心，靠一台笔记本+手机就能跑起来；
2. 需要临时补位的质控员或病案管理员，在正式系统上线前快速建立过渡台账；
3. 有定制化需求的信息科工程师，可基于现有模块快速扩展字段或对接内部系统。

核心功能与使用方式

系统提供四种并行使用路径，按使用习惯自由切换，数据互通、状态同步：

使用方式	启动命令	典型场景	优势
命令行（CLI）	python -m src.cli scan xxx.jpg	批量处理历史积压图片、集成进脚本自动化流程	响应快、可管道传递、适合定时任务
网页界面（Streamlit）	streamlit run src/web_app.py	护士站现场拍照上传、实时查看统计图表、导出日报PDF	无需记忆命令、所见即所得、支持拖拽多图
REST API（FastAPI）	uvicorn src.api:app --port 8000	对接院内微信小程序、嵌入现有OA审批流、供第三方报表工具调用	接口标准（Swagger文档完备）、支持并发上传、可加Nginx反向代理
示例数据快速体验	python scripts/generate_samples.py && python scripts/init_project.py	首次安装验证环境、培训新人操作、演示给科室负责人看效果	5分钟跑通全流程，无需准备真实图片

所有路径共享同一套后台逻辑：图片经Pillow预处理（灰度化、二值化、倾斜校正）→ Tesseract OCR识别文本 → 文档分类器匹配document_types.json中的关键词 → 字段提取器定位住院号/姓名/科室等 → 字段标准化器应用field_mapping.json中的别名映射 → 隐私脱敏器按配置执行掩码 → 最终存入data/ledger.db并记录完整操作时间线。

环境与运行依赖

系统对运行环境要求极低，Windows/macOS/Linux均可部署，关键依赖只有两项：Tesseract OCR引擎和Python 3.10+。

Tesseract安装方式因系统而异，但目标一致：让终端能执行tesseract --version并看到版本号，且tesseract --list-langs输出包含chi_sim：

tesseract --list-langs
# 输出应含：
# List of available languages:
# chi_sim
# eng

中文语言包必须显式安装，仅装Tesseract主程序不等于支持中文识别。各系统安装要点如下：

系统	安装命令或步骤	验证要点
Windows	下载Tesseract安装包（UB-Mannheim镜像），勾选chi_sim语言包；手动将chi_sim.traineddata放入安装目录的tessdata/子文件夹	tesseract --list-langs  必须显示 chi_sim
Linux（Debian/Ubuntu）	sudo apt install tesseract-ocr tesseract-ocr-chi-sim	apt list --installed | grep tesseract  应含 -chi-sim 包
macOS（Homebrew）	brew install tesseract && brew install tesseract-lang （后者含中文包）	tesseract --list-langs  输出含 chi_sim

Python依赖通过requirements.txt一键安装，无编译依赖，pip install -r requirements.txt即可完成。初始化只需运行python scripts/init_project.py，它会自动创建data/目录、初始化SQLite库、加载默认配置。

数据与扩展配置

所有业务规则和映射关系均通过JSON配置文件驱动，无需修改代码即可适配不同医院的书写习惯：

• document_types.json

  定义文档类型识别逻辑：每种类型（如“入院证”）声明其关键词（["入院","住院证"]）和必填字段（["hospital_id","name","department"]）。新增一种单据，只需在此文件添加新条目；

• field_mapping.json

  统一字段口径：将“心内科”“心内”“心血管内科”映射为标准科室名；把“冠心”“冠心病”“CHD”归一为“冠心病”；支持性别字段的中英文变体转换；

• ocr_config.json

  控制识别精度：psm 6（按块识别）适合表格类单据，psm 3（全自动页面分析）适合自由排版；timeout 30防止卡死；fallback_to_mock true确保Tesseract异常时仍返回模拟结果，不中断流程；

• web_config.json

  调节界面行为：是否允许导出、默认每页显示条数、主题明暗模式等。

这些配置不是“高级选项”，而是日常运维的常规动作。比如某院检验单常写“血常规”，另一家写“CBC”，只需在field_mapping.json的diagnosis_normalization里追加一行，下次识别就自动归一。

限制与说明

我们坦诚说明当前能力边界，避免误用导致预期落差：

• OCR准确率取决于原始图像质量

  ：手机拍摄需保持纸面平整、光线均匀、无反光遮挡；模糊、倾斜超过15度、文字被印章覆盖时，识别率会下降，此时CLI的--verbose参数可输出原始OCR文本供人工复核；

• 不支持手写体专项优化

  ：Tesseract对印刷体识别稳定，对手写体仅作基础字符切分，若单据大量手写内容（如医生签名栏、患者手填地址），建议仅提取印刷部分字段；

• SQLite单文件数据库有并发写入限制

  ：Web界面多人同时上传、CLI与API并行写入时，可能触发数据库忙等待（database is locked），生产环境高并发场景建议改用PostgreSQL（需自行修改ledger_db.py中的连接器）；

• PDF支持限于单页扫描件

  ：不解析PDF元数据、不处理扫描PDF的OCR层缺失问题，若上传的是纯文本PDF，Tesseract仍可识别；若为未OCR的扫描PDF，需确保Tesseract能正确提取图像帧；

• 隐私脱敏为可选开关

  ：默认开启，但可通过CLI的--no-mask、API的enable_privacy=false、Web界面的滑块关闭，关闭后姓名、身份证号、电话等字段将明文存储。

这些问题在FAQ中有对应解决方案，例如OCR不准时调整psm参数、数据库锁时增加重试逻辑、手写字段缺失时启用人工补录模式（CLI支持--no-save仅输出结果供核对）。

工程结构与模块职责

项目采用清晰分层架构，每个src/下的Python模块承担单一职责，便于理解、调试与二次开发：

模块文件	主要职责	典型可调点
image_processor.py	图片预处理：缩放、去噪、二值化、透视校正	可替换OpenCV增强算法
ocr_engine.py	封装Tesseract调用，处理超时、异常、语言参数	可接入PaddleOCR或百度OCR作为备选
document_classifier.py	基于关键词匹配文档类型，返回类型名与置信度	可扩展为轻量级文本分类模型
field_extractor.py	正则+模板匹配提取住院号、姓名等字段	可按医院格式定制正则表达式
field_normalizer.py	应用field_mapping.json进行科室/诊断/性别归一	映射表热更新无需重启
privacy_masker.py	按配置执行姓名、证件号、电话脱敏	脱敏规则可自定义掩码长度
batch_processor.py	控制多图并行处理，支持进度显示与失败重试	--workers 参数可调线程数
history_tracker.py	记录每次扫描的原始图、OCR文本、提取结果、操作人（CLI无用户概念，Web/API可扩展）	时间戳精确到毫秒

这种解耦设计意味着：如果你只需要CLI批量扫描功能，可删掉web_app.py和api.py；如果只想用OCR引擎，可单独导入ocr_engine.py；如果要对接医院LDAP做登录认证，只需在web_app.py中插入身份验证中间件，所有扩展都在已有框架内发生，不破坏核心流水线。

项目地址：
https://github.com/nexorin9/paper-flow-tracker