# 患者首页 PDF 处理工作流_Gitea版

## Gitea 仓库

仓库地址：

```text
https://gitea.huijutec.cn/admin/HIS.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 存储约定

数据库连接信息只放在本地 `.env` 或运行环境变量中，不写入 Gitea。需要配置：

```text
PGHOST
PGPORT
PGDATABASE
PGUSER
PGPASSWORD
PGTABLE
```

脚本会在首次写入时自动创建或迁移 `PGTABLE` 指向的宽表，`payload` 中的顶层信息会展开为独立列；不再保存 `payload`、`parsed_at`、`created_at`、`updated_at`。

脚本会为表和全部字段写入 PostgreSQL 注释，数据库客户端中可直接查看每列含义。

网页端会按需在主表中创建两个 JSONB 日志列：

- `review_logs`：记录人工保存时间、修改字段、修改前后值和人工备注。
- `audit_logs`：记录抽查来源、抽查状态、抽查备注和更新时间。

历史辅助日志表会自动迁移进主表并删除，最终只保留 `PGTABLE` 指向的一张业务表。

核心列包括：

- `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.git
   cd HIS
   ```

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 "$MINERU_URL"
   ```

   也可以先单独转 Markdown：

   ```bash
   python3 数据处理工作区/05_备用读取/05_备用PDF转Markdown_Mineru.py \
     -s 待处理-患者首页PDF \
     -t 数据处理结果区/06_Mineru_MD \
     -u "$MINERU_URL"
   ```

5. 正式处理并写入 PostgreSQL：

   ```bash
   export PGPASSWORD='从安全渠道获取数据库密码'
   python3 数据处理工作区/02_解析入库/02_患者首页PDF解析与入库.py \
     --write-postgres \
     --pg-host "$PGHOST" \
     --pg-port 5432 \
     --pg-database "$PGDATABASE" \
     --pg-user "$PGUSER" \
     --pg-table "$PGTABLE"
   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`，默认密码请在本地 `.env` 中通过 `REVIEW_ADMIN_PASSWORD` 设置。设置页创建的本地用户会同步作为登录账号，并按权限控制各页面。

   页面顶部显示数据库连接状态、总记录数、需复核数、PDF 数量；顶部页签包括概览、复核、抽查、抽查一览、设置，设置内合并用户与权限、数据库状态和目录信息。复核页默认进入“全部复核数据”，包含需复核、自动修正、已人工复核/已人工修改；左侧选择病例，中间查看 PDF，右侧以表格方式编辑摘录字段。点击“复核并保存”后会同步写回 PostgreSQL，把 `manual_corrected` 标记为 `true`，自动把 `review_status` 标记为 `reviewed`；`Patient_Lists.has_front_page/front_page_id/front_page_source_file` 由数据库触发器按住院号自动维护。

   复核提示会定位到右侧模块和字段：需要核对的位置标红，无关模块默认收起。人工备注下方会显示修改记录表，主表 `review_logs` 记录修改时间、修改字段、修改前后值和人工备注。

   设置页的 AI 核验按钮可分别配置模型/Thinking 和隐私模式。“AI当前项”“AI后5项”“AI后全部”默认均开启隐私模式；关闭某个按钮的隐私模式后，该按钮对应任务会允许上传基本信息、地址联系人等相关局部内容用于核验和修正。

   抽查页可从已人工复核或自动通过记录中随机抽样；右侧和复核页一样显示并可编辑全部结构化信息，下方有人工备注和修改记录。随机抽取不会写入“待抽查”记录，只有点击“归类通过并保存”“归类异常并保存”“归类不确定并保存”后，才把通过、异常、不确定记录写入主表 `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 "$PGHOST" \
     --pg-port 5432 \
     --pg-database "$PGDATABASE" \
     --pg-user "$PGUSER" \
     --pg-table "$PGTABLE"
   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 "$PGHOST" \
     --pg-port 5432 \
     --pg-database "$PGDATABASE" \
     --pg-user "$PGUSER" \
     --pg-table "$PGTABLE"
   unset PGPASSWORD
   ```

回写后，程序会更新可修正字段，并把 `manual_corrected` 标记为 `true`；`manual_review_notes` 会追加进入 `review_notes`。

4. 做数据库体检：

   ```bash
   export PGPASSWORD='从安全渠道获取数据库密码'
   python3 数据处理工作区/04_质量体检/04_字段核验与数据库体检.py \
     --pg-host "$PGHOST" \
     --pg-port 5432 \
     --pg-database "$PGDATABASE" \
     --pg-user "$PGUSER" \
     --pg-table "$PGTABLE"
   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。