# 通用图片表格识别处理程序说明

本目录是一套可复用的图片表格 OCR 处理脚手架。默认只提供通用字段和通用数据库结构；用于 UPP、PACS、HIS 或其他任务前，先复制并修改 `01_任务配置.template.json`。

## 文件顺序

1. `01_任务配置.template.json`：任务名、字段顺序、主唯一键、分类规则、OCR 参数、数据库表名。
2. `02_图片表格OCR归档.py`：处理单个图片批次，输出结构化 JSON、CSV、复核报告和 OCR 缓存。
3. `03_人工复核修正.template.json`：人工修正文件模板。正式修正时复制为 `03_人工复核修正.json`，不要提交真实数据。
4. `04_合并批次结果.py`：扫描 `数据处理结果区`，合并所有 `*-列表归档结果`。
5. `05_同步PostgreSQL单表.py`：把合并结果同步到 PostgreSQL 通用 JSONB 单表。
6. `06_PostgreSQL建表结构.template.sql`：通用表结构模板，正式任务可改成业务正式列。
7. `07_处理程序说明.md`：当前说明。
8. `08_本地运行流程.template.sh`：按顺序执行的本地命令模板。

## 首次使用

```bash
cp 数据处理工作区/01_任务配置.template.json 数据处理工作区/01_任务配置.json
cp 数据处理工作区/03_人工复核修正.template.json 数据处理工作区/03_人工复核修正.json
cp 数据处理工作区/06_PostgreSQL建表结构.template.sql 数据处理工作区/06_PostgreSQL建表结构.sql
```

然后人工修改：

- `project_name`、`record_name`。
- `unique_key`。
- `fields` 字段顺序、字段类型、必填规则、正则规则。
- `classification.folder_rules`。
- `ocr.rows_per_image` 或 `ocr.row_height_px`，如果要启用行数漏识别校验。
- `postgres.table_name` 和 SQL 表名。

## 处理单个批次

```bash
export TENCENTCLOUD_SECRET_ID='填入腾讯云 SecretId'
export TENCENTCLOUD_SECRET_KEY='填入腾讯云 SecretKey'

python3 数据处理工作区/02_图片表格OCR归档.py \
  --config 数据处理工作区/01_任务配置.json \
  --input "待处理-[任务名]图片集群/[批次文件夹名]" \
  --output "数据处理结果区/已处理-[任务名]图片集群/[批次文件夹名]-列表归档结果"
```

只用已有 OCR 缓存重建：

```bash
python3 数据处理工作区/02_图片表格OCR归档.py \
  --config 数据处理工作区/01_任务配置.json \
  --input "待处理-[任务名]图片集群/[批次文件夹名]" \
  --output "数据处理结果区/已处理-[任务名]图片集群/[批次文件夹名]-列表归档结果" \
  --rebuild-from-cache
```

## 合并和入库

```bash
python3 数据处理工作区/04_合并批次结果.py --config 数据处理工作区/01_任务配置.json
```

如需同步 PostgreSQL：

```bash
export WORKFLOW_DB_HOST='数据库主机'
export WORKFLOW_DB_PORT='5432'
export WORKFLOW_DB_NAME='数据库名'
export WORKFLOW_DB_USER='数据库用户'
export WORKFLOW_DB_PASSWORD='数据库密码'

python3 数据处理工作区/05_同步PostgreSQL单表.py \
  --input 数据处理结果区/合并_图片表格_结构化.json \
  --schema 数据处理工作区/06_PostgreSQL建表结构.sql
```

## 输出文件

单批次输出：

- `图片表格_结构化.json`
- `图片表格_记录.jsonl`
- `图片表格_记录.csv`
- `复核报告.json`
- `重复主键报告.json`
- `缺少主键报告.json`
- `merged_images/`
- `raw_ocr/`
- `信息记录/汇总.json`

合并输出：

- `数据处理结果区/合并_图片表格_结构化.json`
- `数据处理结果区/合并_图片表格_记录.jsonl`
- `数据处理结果区/合并_图片表格_记录.csv`
- `数据处理结果区/信息记录/全局汇总.json`
- `数据处理结果区/信息记录/批次汇总.csv`
- `数据处理结果区/信息记录/重复主键报告.json`
- `数据处理结果区/信息记录/缺少主键报告.json`

## 注意

- 腾讯云密钥、数据库密码只放环境变量。
- `03_人工复核修正.json` 可能含真实业务数据，不要提交。
- `raw_ocr/` 和 `merged_images/` 是过程文件，建议保留在本地，便于复核和缓存重建。
- 当前 PostgreSQL 模板采用 `record_data jsonb` 保存业务字段；正式稳定后可把高频查询字段改成独立列。