Import sanitized HIS processing tools

2026-05-26 08:51:10 +08:00
commit 7e329f1d85
46 changed files with 19175 additions and 0 deletions
--- a/患者首页处理/工作流_Gitea版.md
+++ b/患者首页处理/工作流_Gitea版.md
@@ -0,0 +1,306 @@
+# 患者首页 PDF 处理工作流_Gitea版
+
+## Gitea 仓库
+
+仓库地址：
+
+```text
+https://gitea.huijutec.cn/admin/HIS_Front_Page.git
+```
+
+仓库只保存程序、文档和配置说明。不要提交原始 PDF、处理结果、明文密码、`.env` 文件，也不再提交加密本地工作流压缩包。
+
+## 仓库内容
+
+```text
+README.md
+工作流_Gitea版.md
+数据可视化网页端/.env.example
+数据可视化网页端/Dockerfile
+数据可视化网页端/docker-compose.yml
+数据可视化网页端/README.md
+数据可视化网页端/app/
+数据处理工作区/01_配置规则/01_科室分类规则.json
+数据处理工作区/02_解析入库/02_患者首页PDF解析与入库.py
+数据处理工作区/03_人工复核/03_人工复核导出与回写.py
+数据处理工作区/04_质量体检/04_字段核验与数据库体检.py
+数据处理工作区/05_备用读取/05_备用PDF转Markdown_Mineru.py
+数据处理工作区/06_图片对照核验/06_PDF转图片与对照核验.py
+数据处理工作区/07_Kimi视觉兜底/07_Kimi图片识别辅助.py
+```
+
+## PostgreSQL 存储约定
+
+目标数据库：
+
+```text
+主机/IP: DB_HOST
+端口: 5432
+数据库名: DB_NAME
+用户名: DB_USER
+表名: Patient_FrontPages
+```
+
+脚本会在首次写入时自动创建或迁移表 `"Patient_FrontPages"`。表是宽表结构，`payload` 中的顶层信息会展开为独立列；不再保存 `payload`、`parsed_at`、`created_at`、`updated_at`。
+
+脚本会为表和全部字段写入 PostgreSQL 注释，数据库客户端中可直接查看每列含义。
+
+网页端会按需在主表中创建两个 JSONB 日志列：
+
+- `review_logs`：记录人工保存时间、修改字段、修改前后值和人工备注。
+- `audit_logs`：记录抽查来源、抽查状态、抽查备注和更新时间。
+
+历史辅助表 `"Patient_FrontPages_review_logs"`、`"Patient_FrontPages_audit_logs"` 会自动迁移进主表并删除，最终只保留 `"Patient_FrontPages"` 一张业务表。
+
+核心列包括：
+
+- `inpatient_no`：患者号/住院号，作为首页与患者列表联动唯一键；这是本程序唯一强制校验条件，不能为空。程序不校验格式，同一非空患者号只允许一条首页，迁移时保留最新记录，后续同号入库或网页写入会覆盖旧首页。
+- `source_file`：PDF 文件名；重复运行以 `inpatient_no` 为准更新。
+- `medical_record_no`：10 位病案号，文本保存，保留前导 0。
+- `front_page_medical_record_no`：10 位首页病案号，文本保存，保留前导 0。
+- `patient_name`、`gender`、`birth_date`、`id_card_no` 等基本信息列。
+- `admission_time`、`discharge_time`、`primary_diagnosis`、`total_cost` 等业务字段列。
+- `major_department`：根据 `数据处理工作区/01_配置规则/01_科室分类规则.json` 从出院科别优先、入院科别兜底映射出的大科室。
+- `discharge_diagnoses`、`operations`、`fee_details`：复杂明细仍以 JSONB 保存；出院诊断已包含主要诊断和其他诊断，不再单独保存 `other_diagnoses`。
+- `quality_status`、`quality_notes`：程序质控结果。
+- `text_extraction_method`：本次使用的文本抽取方式，如 `pdftotext` 或 `mineru_markdown`。
+- `mineru_markdown_dir`：Mineru Markdown 输出目录。
+- `review_status`：`auto_pass`、`auto_corrected` 或 `needs_review`。
+- `review_notes`：需要复核的原因。
+- `manual_corrected`：人工是否已修正，默认 `false`。
+- `auto_corrections`：程序自动修正记录。
+- `review_logs`、`audit_logs`：网页端人工复核与抽查归类记录。
+- `raw_text`：PDF 抽取出的原始文本。
+
+`Patient_Lists` 会自动增加并维护 `has_front_page`、`front_page_id`、`front_page_source_file`。首页 `inpatient_no` 非空时，PostgreSQL 触发器按 `Patient_FrontPages.inpatient_no = Patient_Lists.inpatient_no` 联动；列表没有对应患者号时会自动补建列表记录，并写入主要诊断、入院时间和出院时间；患者号重复时以唯一键覆盖更新，保证一个患者号只有一个病案首页。空患者号记录会在迁移和入库时被删除，PGSQL 会阻止再次写入空患者号。删除首页记录，或把首页 `inpatient_no` 改成其他患者号时，旧患者号的 `has_front_page` 会自动回落为 `false` 并清空首页引用。若同一患者号姓名不一致，以首页表中的非空姓名覆盖 `Patient_Lists.patient_name`；已有列表记录的诊断和入出院时间不被首页联动覆盖。患者号格式核验交由患者目录核验网页端处理。
+
+病案号规则：
+
+- 住院号 = `ZY` + 住院次数 2 位 + 首页病案号 10 位，例如 `ZY020001447443`。
+- `0001906820` 是合法 10 位病案号，前导 0 不能删除。
+- 若 PDF 首页病案号少前导 0，但文件名可还原，例如 `ZY020001447443_ori.pdf` 中可得到 `0001447443`，脚本会把 PDF 值 `01447443` 自动修正为 `0001447443`，并记录到 `auto_corrections`。
+
+## 从 Gitea 拉取后运行
+
+1. 克隆仓库：
+
+   ```bash
+   git clone https://gitea.huijutec.cn/admin/HIS_Front_Page.git
+   cd HIS_Front_Page
+   ```
+
+2. 准备目录：
+
+   ```bash
+   mkdir -p 待处理-患者首页PDF 数据处理结果区 已处理-患者首页PDF
+   ```
+
+3. 放入 PDF：
+
+   ```text
+   待处理-患者首页PDF/
+   ```
+
+4. 本地生成 CSV/JSON：
+
+   ```bash
+   python3 数据处理工作区/02_解析入库/02_患者首页PDF解析与入库.py
+   ```
+
+   默认使用 `--text-source auto`：先用 `pdftotext`，若读取结果异常再调用 Mineru。需要强制 Mineru 时：
+
+   ```bash
+   python3 数据处理工作区/02_解析入库/02_患者首页PDF解析与入库.py \
+     --text-source mineru \
+     --mineru-url "http://MINERU_HOST:4000/extract"
+   ```
+
+   也可以先单独转 Markdown：
+
+   ```bash
+   python3 数据处理工作区/05_备用读取/05_备用PDF转Markdown_Mineru.py \
+     -s 待处理-患者首页PDF \
+     -t 数据处理结果区/06_Mineru_MD \
+     -u "http://MINERU_HOST:4000/extract"
+   ```
+
+5. 正式处理并写入 PostgreSQL：
+
+   ```bash
+   export PGPASSWORD='请填写数据库密码'
+   python3 数据处理工作区/02_解析入库/02_患者首页PDF解析与入库.py \
+     --write-postgres \
+     --pg-host DB_HOST \
+     --pg-port 5432 \
+     --pg-database DB_NAME \
+     --pg-user DB_USER \
+     --pg-table Patient_FrontPages
+   unset PGPASSWORD
+   ```
+
+6. 生成 PDF 图片对照核验页：
+
+   ```bash
+   python3 数据处理工作区/06_图片对照核验/06_PDF转图片与对照核验.py --force
+   ```
+
+   输出位于：
+
+   ```text
+   数据处理结果区/06_PDF图片对照/图片/
+   数据处理结果区/06_PDF图片对照/患者首页_PDF图片对照.html
+   数据处理结果区/06_PDF图片对照/患者首页_PDF图片对照索引.csv
+   ```
+
+   HTML 对照页用于人工左侧看首页图片、右侧看结构化字段；CSV 索引用于快速筛出核心缺项、建议核对缺项和已有复核状态。
+
+7. 启动可视化网页端：
+
+   ```bash
+   docker compose -f 数据可视化网页端/docker-compose.yml up -d --build
+   ```
+
+   浏览器打开：
+
+   ```text
+   http://localhost:8501
+   ```
+
+   首次进入会显示登录界面；默认管理员为 `admin`，默认密码为 `change-me`。设置页创建的本地用户会同步作为登录账号，并按权限控制各页面。
+
+   页面顶部显示数据库连接状态、总记录数、需复核数、PDF 数量；顶部页签包括概览、复核、抽查、抽查一览、设置，设置内合并用户与权限、数据库状态和目录信息。复核页默认进入“全部复核数据”，包含需复核、自动修正、已人工复核/已人工修改；左侧选择病例，中间查看 PDF，右侧以表格方式编辑摘录字段。点击“复核并保存”后会同步写回 PostgreSQL，把 `manual_corrected` 标记为 `true`，自动把 `review_status` 标记为 `reviewed`；`Patient_Lists.has_front_page/front_page_id/front_page_source_file` 由数据库触发器按住院号自动维护。
+
+   复核提示会定位到右侧模块和字段：需要核对的位置标红，无关模块默认收起。人工备注下方会显示修改记录表，主表 `review_logs` 记录修改时间、修改字段、修改前后值和人工备注。
+
+   抽查页可从已人工复核或自动通过记录中随机抽样；右侧和复核页一样显示并可编辑全部结构化信息，下方有人工备注和修改记录。随机抽取不会写入“待抽查”记录，只有点击“归类通过并保存”“归类异常并保存”“归类不确定并保存”后，才把通过、异常、不确定记录写入主表 `audit_logs`；抽查一览展示修改内容、人工备注和更新时间。
+
+   PDF 以 `inline` 方式展示，不再作为附件触发保存。浏览器内核不能彻底禁止用户保存已展示内容。
+
+8. 可选 Kimi 视觉兜底：
+
+   ```bash
+   python3 数据处理工作区/07_Kimi视觉兜底/07_Kimi图片识别辅助.py \
+     --case ZY010001672803_ori \
+     --page page-001.png
+   ```
+
+   Kimi 调用需要本地 `.env` 中配置 `MOONSHOT_API_KEY`。该步骤只在人工触发时上传指定图片，输出到 `数据处理结果区/07_Kimi视觉识别/`，默认不直接覆盖 PostgreSQL。
+
+## 审核流程
+
+每批数据处理后执行：
+
+```bash
+sed -n '1,50p' 数据处理结果区/04_复核与人工校正/患者首页_复核清单.csv
+```
+
+如果复核清单为空，仍建议抽查：
+
+- `数据处理结果区/01_结构化结果/患者首页_结构化结果.csv`
+- `数据处理结果区/02_单份JSON/`
+- `数据处理结果区/03_提取文本/`
+- `数据处理结果区/06_PDF图片对照/患者首页_PDF图片对照.html`
+- `数据处理结果区/06_PDF图片对照/患者首页_PDF图片对照索引.csv`
+- `http://localhost:8501` 可视化网页端
+
+如果出现新模板、扫描件、字段错位、少项漏项或手术操作跨行异常，把对应 PDF 文件名、抽取文本、图片对照索引中的缺项提示交给 Codex 继续补规则。
+
+## PostgreSQL 人工复核流程
+
+1. 导出待复核表：
+
+   ```bash
+   export PGPASSWORD='请填写数据库密码'
+   python3 数据处理工作区/03_人工复核/03_人工复核导出与回写.py export \
+     --pg-host DB_HOST \
+     --pg-port 5432 \
+     --pg-database DB_NAME \
+     --pg-user DB_USER \
+     --pg-table Patient_FrontPages
+   unset PGPASSWORD
+   ```
+
+2. 打开 `数据处理结果区/04_复核与人工校正/患者首页_人工复核表.csv`，人工填写这些列：
+
+   ```text
+   manual_review_notes
+   corrected_medical_record_no
+   corrected_patient_name
+   corrected_major_department
+   corrected_primary_diagnosis
+   corrected_primary_diagnosis_code
+   corrected_total_cost
+   corrected_self_pay_amount
+   mark_review_status
+   ```
+
+3. 回写 PostgreSQL：
+
+   ```bash
+   export PGPASSWORD='请填写数据库密码'
+   python3 数据处理工作区/03_人工复核/03_人工复核导出与回写.py import \
+     --pg-host DB_HOST \
+     --pg-port 5432 \
+     --pg-database DB_NAME \
+     --pg-user DB_USER \
+     --pg-table Patient_FrontPages
+   unset PGPASSWORD
+   ```
+
+回写后，程序会更新可修正字段，并把 `manual_corrected` 标记为 `true`；`manual_review_notes` 会追加进入 `review_notes`。
+
+4. 做数据库体检：
+
+   ```bash
+   export PGPASSWORD='请填写数据库密码'
+   python3 数据处理工作区/04_质量体检/04_字段核验与数据库体检.py \
+     --pg-host DB_HOST \
+     --pg-port 5432 \
+     --pg-database DB_NAME \
+     --pg-user DB_USER \
+     --pg-table Patient_FrontPages
+   unset PGPASSWORD
+   ```
+
+体检输出：
+
+```text
+数据处理结果区/05_质量体检/患者首页_数据库体检报告.txt
+数据处理结果区/05_质量体检/患者首页_字段空值统计.csv
+数据处理结果区/05_质量体检/患者首页_疑似异常记录.csv
+```
+
+## 提交规则
+
+提交到 Gitea 前务必检查：
+
+```bash
+git status --short
+```
+
+不应出现这些内容：
+
+- `待处理-患者首页PDF/`
+- `数据处理结果区/`
+- `已处理-患者首页PDF/`
+- `.env`
+- 含真实密码的环境文件
+- 明文 `工作流_本地使用版.md`
+
+可以提交：
+
+- 脚本
+- `01_~0X_` 前缀的工作区文件
+- README
+- Gitea 工作流文档
+- 不含密码的配置模板
+
+依赖说明：
+
+- 主解析脚本使用 Python 标准库和系统命令 `pdftotext/pdftoppm`。
+- Mineru 备用读取单独需要 `python3 -m pip install requests`。
+- Docker 网页端依赖写在 `数据可视化网页端/Dockerfile` 中，不再维护独立 `requirements.txt`。
+
+## 本地工作流
+
+明文 `工作流_本地使用版.md` 只用于本机执行，不提交到 Gitea；加密压缩包已从仓库删除，后续不再维护该 zip。