건강검진 지표 추세 분석 시스템
용도
여러 해에 걸친 다양한 형태(전자 PDF / 스캔본 / 사진)의 건강검진 보고서를 통합하여 표준화된 지표 시계열로 변환하고, 추세 분석 보고서 + 대화형 건강 관리 작업 대시보드를 생성합니다. 모든 처리는 로컬에서 이루어지며, 자동으로 개인정보를 비식별화하고, 동적으로 확장 가능합니다(새 보고서를 추가하면 파이프라인을 다시 실행하기만 하면 됩니다).
트리거 단어
-历年体检报告 / 多年度体检报告 / 历年的体检报告 / 历年体检
- 体检报告数据化 / 体检数据解析 / 体检报告解析
- 体检指标趋势 / 指标趋势分析 / 指标趋势
- 历年体检指标对比 / 体检指标对比 / 逐年对比 / 逐年变化
- 化验单分析 / 化验单解读 / 检验报告分析
- 体检报告扫描件 / 扫描件体检报告 / 扫描件 OCR
- 体检报告照片 / 照片版体检报告 / 手机拍的体检报告
- 健康管理工作台 / 健康管理看板 / 健康数据看板 / 可视化看板
- 血糖趋势 / 血糖变化 / 尿酸偏高 / 血脂趋势 / 血压趋势
- 体检异常指标 / 异常指标解读 / 指标异常
- 新增体检报告 / 新报告接入 / 加入新一年体检
- 体检数据脱敏 / 脱敏数据集 / 脱敏版 / 可分享数据集
환경 준비
# 의존성 (이미 설치된 경우 생략 가능): pymupdf 필수; Pillow(사진 합성), pyobjc-framework-Vision/Quartz(OCR, macOS 전용)는 선택 사항
export REPORT_DIR=/path/to/体检报告目录 # 보고서 저장 디렉토리 (PDF 또는 연도별 폴더+JPG 포함)
export WORK_DIR=/path/to/工作数据目录 # 데이터 산출물 디렉토리 (data/ 와 output/ 자동 생성)
export PY=/path/to/python # 의존성이 설치된 python 인터프리터 사용 권장
Step 0 (매 새 세션 첫 번째 단계, 필수):
$PY scripts/check_deps.py # 원클릭 의존성 검사: 무엇이 부족한지, 어떤 스크립트에 영향을 미치는지, 설치 방법
$PY scripts/check_deps.py --json # 기계 판독 가능, 자동화 소비용
종료 코드 0 = 필수 의존성 모두 준비 완료, 시작 가능; 1 = 필수 의존성 부족 (메인 흐름 차단, 안내에 따라 설치); 선택 의존성 누락은 해당 입력 형태에만 영향을 미치며, 전자 PDF 메인 경로는 차단하지 않습니다.
실행 흐름
모든 스크립트는 --help를 지원하며, 매개변수가 환경 변수보다 우선합니다; 매개변수 없이 실행 = 환경 변수의 원래 동작을 따릅니다.
- 입력 형태 식별:
REPORT_DIR탐색- 루트 디렉토리
*.pdf에 텍스트 레이어 있음 → 전자 버전 (parse_reports.py처리) - 루트 디렉토리
*.pdf에 텍스트 레이어 없음 → 스캔본 (vision_ocr.py+extract.py) - 연도별 하위 디렉토리
YYYY体检报告/*.JPG→ 사진 버전 (make_year_pdfs.py합성 → OCR →extract.py)
- 루트 디렉토리
- 전자 PDF 파싱 (좌표 위치 지정 방식, 열 경계는
references/解析与口径.md참조):$PY scripts/parse_reports.py # → data/reports_raw.json $PY scripts/parse_reports.py --year 2027 --dry-run # 단일 연도 테스트 실행, 디스크에 쓰지 않음 - 사진 버전 PDF 합성 + OCR + 추출 (JPG 디렉토리 / 스캔본이 있는 경우):
$PY scripts/make_year_pdfs.py --year 2015-2020 # 연도별 여러 JPG → 단일 PDF (가로 촬영 자동 회전 보정) $PY scripts/vision_ocr.py <pdf> data/ocr_2022.json # 스캔본/사진 OCR → 좌표 포함 JSON $PY scripts/extract.py --year 2022 # OCR 결과 → 지표 (전략 자동 판단) $PY scripts/extract.py --years 2015-2020 # 여러 연도 dict 형식 OCR (약어 + 참조 범위 역추론)extract.py연도별로 매개변수화되어 있어, 새 연도 추가 시 코드 수정 불필요:data/ocr_<年份>.json에 넣고 바로--year <年份>실행. 전략 기본값auto(입력 JSON 최상위가 dict →abbr, list →row),--strategy로 강제 지정 가능. - 정규화 + 데이터셋 구축 (이름/단위 매핑, 오염 데이터 필터링, OCR 자동 주입, 비식별화 버전 생성):
$PY scripts/build_dataset.pydata/dataset_std.json(전체 버전, 로컬 제어) +data/anonymized/anonymized_dataset_anon_shareable.json(비식별화 버전, 별도 하위 디렉토리 + 읽기 전용 444 + 공유 가능) - 추세 분석 (당해 연도 기준으로 이상 판단, 유의미한 변화 ≥20% 또는 ≥참조 폭 30%, 호전/악화, 최근 3년 집중):
$PY scripts/trend_analysis.py # 기본 최근 3년 $PY scripts/trend_analysis.py --focus-years 2020,2023,2026 - 산출물 생성:
$PY scripts/report_generator.py # output/体检指标趋势分析报告.md (기본 **본문 비식별화 활성화**) $PY scripts/build_dashboard.py # output/health_dashboard.html (단일 파일 오프라인)
새 보고서 연동 가이드
새 연도 건강검진 보고서를 추가할 때는 형태에 따라 해당 분기를 따릅니다 (자세한 내용은 references/新报告接入指南.md 참조):
- 보고서 배치:
REPORT_DIR루트 디렉토리에*.pdf를 넣거나, 연도 디렉토리YYYY体检报告/를 만들어 JPG를 넣습니다. - 형태 식별: PDF 텍스트 레이어 확인 (
get_text()길이 >0 = 전자 버전)- 전자 버전 → 바로
parse_reports.py실행; 열 경계가 비정상적이면 먼저 1페이지 좌표 샘플을 출력합니다. - 스캔본/사진 →
make_year_pdfs.py→vision_ocr.py→extract.py --year <年份>(연도별 새 스크립트를 만들지 마세요)
- 전자 버전 → 바로
- 사전 보충 (미등록 지표가 있는 경우):
indicator_dict.py의NAME_MAP에 매핑 한 줄 추가 (로그는data/unrecognized에서 확인)$PY scripts/indicator_dict.py --search 尿酸 # 이미 등록되었는지 확인 (별칭 포함) $PY scripts/indicator_dict.py --validate # 사전 무결성 자체 검사 (유령 별칭/중복 키) $PY scripts/indicator_dict.py --count # 현재 표준 지표 총 개수 - 파이프라인 재실행: build_dataset → trend_analysis → report_generator → build_dashboard
- 검수: 새 연도가
trend_analysis.json["years"]및 대시보드 타임라인에 나타나는지 확인; 주요 지표 3개의 값을 보고서와 일치하는지 샘플링 확인; 비식별화 버전을 생성하고 검증
핵심 규칙
- 개인정보 강제 제약 (무관용): 전체 로컬 처리, 스킬 내에 외부 네트워크 호출 전혀 없음; 작업 완료 시 반드시 비식별화 버전을 생성하고 검증 (이름/신분증 번호/전화번호/주소/병원명 미포함), 공유 시에는
data/anonymized/anonymized_dataset_anon_shareable.json만 사용 (전체 버전dataset_std.json과 디렉토리 분리 강제 격리, 읽기 전용 444, 전체 버전 실수 공유 방지) - 비식별화 검증이 디스크 쓰기보다 우선:
build_dataset.py의_write_anon_verified()는 비식별화 버전을 디스크에 쓰는 유일한 진입점입니다——먼저 메모리에서 검증하고, 통과한 후에만 디스크에 씁니다. 비식별화 버전은 디스크에 쓰자마자 읽기 전용 444로 설정됩니다. 만약 쓰기 후에 검증하면, PII가 포함된 파일이 이미 디스크에 남아 있고 수정할 수 없게 되어[FAIL]은 단순 사후 경고에 불과합니다. 이 진입점을 우회하여 직접_write_anon()을 호출하는 것을 금지합니다;--skip-verify는 문제 해결 용도로만 사용하며, 산출물은 공유할 수 없습니다. - 보고서 본문 비식별화:
report_generator.py의mask_identity_text는 기본적으로 활성화됨 (기관명, 의사 이름, 휴대폰 번호, 신분증 번호 마스킹);--no-mask로만 해제하며, 로컬에서 원문 대조용으로만 사용하고 산출물은 절대 공유하지 마세요. - 새 연도 보고서 추가:
REPORT_DIR에 넣고 → 2→6단계를 다시 실행하기만 하면 됩니다; 사전에 없는 지표는data/unrecognized에 기록되며,indicator_dict.py의NAME_MAP에 한 줄만 추가하면 됩니다. - OCR 데이터 위치 지정: OCR로 추출된 지표는 차트 표시에만 사용되며 (회색 Ⓞ 표시), 유의미한 변화 판단에 참여하지 않아 통계 오염을 방지합니다.
- 추세 집중: 전체 추세와 처음/마지막 비교는 집중 연도만을 기반으로 합니다 (기본 최근 3년,
--focus-years로 재정의 가능), 과거 데이터는 표시 배경으로만 사용됩니다. - 기준 일관성: 이상 판단은 해당 연도 보고서 자체 참조 범위를 사용합니다 (시약 변경에 자동 적응, 예: 직접 빌리루빈 2025년부터 0.0–4.0 → 1.7–6.8)
산출물
output/体检指标趋势分析报告.md— 지표 요약표, 이상 강조, 전문가 해설, 계층별 제안 (생활 습관/식이/운동/진료 지표), 방법론output/health_dashboard.html— 건강 개요, 호전/악화 그룹 필터링, 꺾은선 그래프 + 참조 범위 밴드, 시간 범위 전환 (단일 파일, 외부 의존성 없음)data/anonymized/anonymized_dataset_anon_shareable.json— 공유 가능한 비식별화 데이터셋
스크립트 목록
| 스크립트 | 용도 | 주요 매개변수 |
|---|---|---|
check_deps.py | 의존성 자체 검사 (Step 0) | --json --quiet |
parse_reports.py | 전자 PDF 파싱 | --report-dir --data-dir --year --out --dry-run |
make_year_pdfs.py | 연도별 JPG → PDF | --report-dir --year --out-dir --dry-run |
vision_ocr.py | 스캔본/사진 OCR | pdf out (위치 매개변수) --dpi --quiet |
extract.py | OCR 결과 → 지표 (매개변수화) | --year --strategy --ocr-json --out --data-dir --quiet |
build_dataset.py | 정규화 + 비식별화 버전 | --work-dir --data-dir --out --skip-verify --dry-run |
trend_analysis.py | 추세 판단 | --work-dir --focus-years --out --dry-run |
report_generator.py | Markdown 보고서 | --work-dir --out --no-mask --dry-run |
build_dashboard.py | HTML 대시보드 | --work-dir --data-dir --out --quiet |
indicator_dict.py | 지표 사전 (import 됨) | --list --search --count --validate --category (직접 실행 시에만 적용) |
종료 코드는 세 가지 상태로 통일: 0 성공 / 1 실행 중 실패 / 2 매개변수 또는 전제 조건 불만족.
참조 문서
| 문서 | 내용 |
|---|---|
references/新报告接入指南.md | 새 형태/새 연도 보고서 연동의 전체 단계 및 문제 해결 |
references/解析与口径.md | 전자 PDF의 열 경계 좌표, 기준 정의 |
references/OCR方法学.md | 스캔본/사진 OCR 전략, 약어 매핑 테이블 유지 관리 |
evals/ | 8개 회귀 평가 (3개 개인정보 방어선 포함), eval_loop.py --run으로 실행 가능 |
사용 예시 (전체 세션)
사용자: "2027년 건강검진 보고서를 추가하고 추세 분석을 업데이트해 주세요."
- Step 0:
python3 scripts/check_deps.py→ 필수 의존성 모두 준비 완료 REPORT_DIR확인: 새 파일体检报告_270510004567.pdf발견 (전자 버전, 텍스트 레이어 완전함)- 소규모 샘플로 열 경계 확인: 1페이지 좌표 출력,
references/解析与口径.md와 일치 → 조정 불필요 - 파이프라인 실행:
export REPORT_DIR=体检报告 WORK_DIR=/path/to/work python3 scripts/parse_reports.py python3 scripts/build_dataset.py python3 scripts/trend_analysis.py python3 scripts/report_generator.py python3 scripts/build_dashboard.py - 파싱 로그 확인: 새 연도 98개 지표, 1개 미인식 이름 →
indicator_dict.py --search로 미등록 확인 후NAME_MAP에 1줄 추가 후 build_dataset 재실행 - 검수:
trend_analysis.json["years"]에 2027 포함; 대시보드 타임라인에 2027 나타남; 혈당/지질/BMI 값 보고서와 일치 샘플링 확인;grep으로 비식별화 버전에 개인정보 없음 확인 - 전달: 보고서 + 대시보드 경로를 사용자에게 알림; 2027년 각 이상 지표의 변화와 제안 설명
비용 절감 규율 (실행 시 강제)
- 소규모 샘플 우선: 새 형식 파싱 전에 먼저 1페이지 좌표 샘플을 출력하여 열 경계를 확인한 후 전체 처리 (전체 파일 덤프 방지)
- 출력 압축: 디버깅 명령은 통일
| head -N/python -c로 정밀 추출, 큰 JSON 파일 전체 cat 금지 - 서브 에이전트 격리: 큰 파일 읽기/형식 탐지는 Explore 서브 에이전트에 위임, 메인 스레드는 결론만 수신
- 검증은 최종 스크린샷 한 번만 수행, 중간 반복은 DOM/JS 검사로 대체
Changelog
| 버전 | 날짜 | 변경 사항 |
|---|---|---|
| 1.1.0 | 2026-08-29 | 엔지니어링 집중 개선: ① 모든 10개 스크립트 --help + argparse + 세 가지 종료 코드 지원 (개선 전 0/10, 최악); ② check_deps.py 의존성 자체 검사 추가 및 Step 0에 포함; ③ 연도별 하드코딩된 extract_2015_2020.py / extract_2022.py를 매개변수화된 extract.py --year로 통합 (새 연도 연동 시 코드 수정 불필요, 출력 형식은 기존 스크립트와 필드별 일치); ④ ## 触发词 섹션 12개 + evals/ 8개 회귀 평가 추가 (3개 개인정보 방어선用例 포함); ⑤ 개인정보 보호 수정: 비식별화 버전을 '메모리에서 먼저 검증, 통과 후에만 디스크에 쓰기'로 변경 (기존은 디스크에 쓴 후 검증하여, PII 적중 시 개인정보가 포함된 파일이 이미 디스크에 있고 읽기 전용이어서 [FAIL]은 단순 사후 경고에 불과했음); ⑥ trend_analysis.py에서 측정 항목이 손실되는 데드 코드 수정 (measurement_items가 추가 후 재설정되어 키별 중복 제거로 변경) |
| 1.0.3 | 2026-08-23 | P2 M-1 개선 (스킬 안전): 비식별화 버전 강제 격리——anonymized_dataset.json → data/anonymized/anonymized_dataset_anon_shareable.json (별도 하위 디렉토리 + 읽기 전용 444 + _anon_shareable 명명 표시), 전체 버전과 비식별화 버전 혼합 보관으로 인한 실수 공유 방지; build_dataset.py에 _write_anon() 추가 (tmp+replace 원자적 쓰기 + chmod 444); report_generator 개인정보 보호 고지 경로 동기화 |
| 1.0.2 | 2026-08-17 | P1 개선: build_dataset.py 끝에 verify_anonymized 자동 검증 추가 (신분증 번호/휴대폰 번호/이메일/병원명 정규식 스캔, 적중 시 오류와 함께 종료) |
| 1.0.1 | 2026-08-17 | P0 개선: report_generator.py에 mask_identity_text 비식별화 함수 추가 (휴대폰 번호/신분증 번호/의사 서명 마스킹 + 기관 일반화), 요약/결론 텍스트 표시 계층 비식별화; 개인정보 보호 고지를 실제 출력과 일치시킴 |
| 1.0.0 | 2026-08-16 | 초기 버전: 건강검진 지표 추세 분석 시스템 |