pharmacy-stats-api/docs/REFACTOR_PLAN.md

pharmacy-stats-api 모듈화 리팩토링 계획서

작성일: 2026-04-08 작성 시점 배경: v1_pharmit3000.py 를 QT-POS sales_stats_dialog.py 와 1:1 동기화 완료 직후. 이번 마이그레이션을 통해 "두 프로젝트 간 통계 로직 중복" 이라는 근본 문제가 드러났고, 다음 동기화 때는 수동 포팅이 반복되지 않도록 구조를 재설계한다.

---

1. 현재 구조와 문제점

1.1 현재 레이아웃

pharmacy-stats-api/
├── app.py                      322 lines  ← Flask 라우트 + 라벨 dict + 유틸
├── config.py                    22 lines  ← DB 커넥션 설정
├── queries/
│   ├── v1_pharmit3000.py       368 lines  ← 커넥션/캐시/쿼리/집계/유틸 전부
│   └── v2_pmplus20.py          ~250 lines ← v1 구버전 복제 (미동기화)
└── templates/stats.html

그리고 외부 의존 중복:

pharmon-web/
└── sales_stats_dialog.py       (_GUBUN_LABEL, _build_margin_cache,
                                 _query, _calc_age, _empty_row, _add …)

1.2 구체적 문제

#	문제	증상
P1	로직 중복 — pharmon-web sales_stats_dialog.py 의 쿼리/공식/캐시 빌더가 queries/v1_pharmit3000.py 에 통째로 복제됨	QT-POS 에서 버그 고치면 stats-api 도 수동 포팅 필요 (이번 CD_SUNAB 이중계산 버그가 정확히 이 케이스)
P2	라벨 dict 3중 중복 — _GUBUN_LABEL (pharmon-web) / GUBUN_LABEL (app.py) / 프론트 js	보훈 세분화(4_1~4_4) 추가 때 한 군데 놓침 → 날 UI 노출
P3	단일 파일 비대화 — v1_pharmit3000.py 368줄에 커넥션, 캐시, SQL, 집계, 유틸이 섞임	테스트 단위 분리 불가, 변경 시 diff 가독성 낮음
P4	엔드포인트 6개 × 2버전 중복 — app.py 의 v1/v2 라우트가 거의 동일 (day_from/to 파싱, 에러처리, label 붙이기)	라우트 추가 시 12곳 수정
P5	v2 (PMPLUS20) 미동기화 — v1 은 2026-04-08 재작성했지만 v2 는 구버전 로직 그대로	v1/v2 비교 API 가 사실상 무의미
P6	테스트 없음 — GPPOS 공식 (sales_amt, ins_drug, claim_amt), _calc_age 등이 regression 없이 수동 검증에만 의존	다음 리팩토링 때 수치 틀어져도 못 잡음
P7	DB 연결 구문 하드코드 — v1_* / v2_* 각자 get_connection() 작성	드라이버 변경 시 양쪽 수정

---

2. 목표 아키텍처

2.1 설계 원칙

1. Single Source of Truth: 통계 공식·라벨·나이계산 같은 "도메인 로직" 은 한 곳에서만 정의하고, pharmon-web(PyQt) 과 pharmacy-stats-api(Flask) 가 동일 모듈을 import.
2. Version 경계를 버전 모듈 안으로 가둔다: v1(PharmIT3000) / v2(PMPLUS20) 차이는 "SQL 과 컬럼 매핑" 뿐 — 공통 집계/공식 로직은 버전 무관.
3. 레이어 분리: db → core → queries → api 의 단방향 의존. 상위 레이어만 하위를 import.
4. 과도한 추상화 금지: 당장 중복 제거에 필요한 만큼만 쪼갠다. ORM 이나 Repository 패턴은 도입하지 않는다 (MSSQL 읽기 전용, 쿼리 복잡도 낮음).

2.2 목표 레이아웃

pharmacy-stats-api/
├── app.py                  ← create_app() factory + main. 라우트 직접 정의 안함
├── config.py               ← PHARMIT3000_CONFIG, PMPLUS20_CONFIG
├── requirements.txt
├── docs/
│   ├── REFACTOR_PLAN.md            (이 문서)
│   ├── PMPLUS20_MIGRATION_GUIDE.md
│   └── MODULE_BOUNDARY.md          (레이어 경계 설명, 2단계 때 작성)
│
├── db/                     ← 레이어 1. 순수 DB 커넥션
│   ├── __init__.py
│   └── connection.py       ← get_connection(cfg), query(conn_cfg, sql, params)
│
├── core/                   ← 레이어 2. 버전 독립 도메인 로직 (★재사용 핵심★)
│   ├── __init__.py
│   ├── labels.py           ← GUBUN_LABEL, TIME_LABEL, PAY_LABEL, AGE_LABEL
│   ├── formula.py          ← GPPOS 공식: sales_amt, ins_drug, ins_prep, claim_amt
│   ├── aggregator.py       ← empty_row(), add_row(), StatsAccumulator 클래스
│   ├── margin.py           ← build_margin_cache() — 쿼리 주입형 (Callable[[sql,params],rows])
│   ├── age.py              ← calc_age(panum, ref_date)
│   └── classifier.py       ← classify_gubun(), classify_time(), classify_pay()
│
├── queries/                ← 레이어 3. 버전별 SQL + core 조합
│   ├── __init__.py
│   ├── v1_pharmit3000.py   ← PS_MAIN SQL + get_sales_stats() (core 호출)
│   └── v2_pmplus20.py      ← TBSID040_03 SQL + get_sales_stats() (core 호출)
│
├── api/                    ← 레이어 4. Flask Blueprint
│   ├── __init__.py
│   ├── common.py           ← _default_from/to, _parse_date, 공통 응답 래퍼
│   ├── v1.py               ← Blueprint("v1", url_prefix="/v1")
│   ├── v2.py               ← Blueprint("v2", url_prefix="/v2")
│   └── compare.py          ← Blueprint("compare", url_prefix="/api")
│
├── templates/
│   └── stats.html
│
└── tests/                  ← 레이어 2 로직 regression 테스트
    ├── test_formula.py     ← sales_amt/ins_drug 공식 (QT-POS 스크린샷 고정값)
    ├── test_age.py         ← 1900/2000 세기, 윤년
    ├── test_labels.py      ← 보훈 4_1~4_4 매핑
    └── test_margin.py      ← last_cost > user_price*5 경계

2.3 의존 그래프

api/*  ──┐
         ▼
    queries/v1, v2
         │
         ▼
    core/*  ──┐
              ▼
           db/*
              ▼
         config.py

core/ 는 DB 를 직접 호출하지 않고, margin.build_margin_cache(rows, query_fn) 처럼 콜러블을 주입받는다. → core 는 pharmon-web 에서도 그대로 import 가능 (핵심 재사용 포인트).

---

3. pharmon-web 과의 공유 전략

3.1 3가지 옵션 비교

옵션	방법	장점	단점	권장
A. 복붙 유지	지금처럼 수동 동기화	0 작업	또 틀어짐. 매번 이번 같은 사고	×
B. 로컬 경로 import	pharma-stats-core 를 별도 폴더로 두고 양쪽에서 sys.path 또는 editable install (pip install -e ../pharma-stats-core)	저비용, 즉시 동기화, PyInstaller 에서도 hidden-import 처리만 추가하면 됨	배포 환경에서 경로 신경써야 함	★ 2단계에서 채택
C. 독립 패키지 + git submodule	pharma-stats-core 독립 repo, 둘 다 submodule 로 포함	버전 고정 가능, 장기적으로 깔끔	초기 설정 비용, PyInstaller 빌드 스크립트 수정	3단계 (선택적)

3.2 최종 그림 (옵션 B 채택 시)

c:\Users\청춘약국\source\
├── pharma-stats-core\          ← 신규 (core/ 를 여기로 이전)
│   ├── pyproject.toml          (editable install 용)
│   └── pharma_stats_core/
│       ├── __init__.py
│       ├── labels.py
│       ├── formula.py
│       ├── aggregator.py
│       ├── margin.py
│       ├── age.py
│       └── classifier.py
│
├── pharmacy-stats-api\
│   └── queries/v1_pharmit3000.py   ← `from pharma_stats_core import ...`
│
└── pharmon-web\
    └── sales_stats_dialog.py       ← `from pharma_stats_core import ...`

pharmon-web PyInstaller 영향:

• pos_gui.spec 에 hiddenimports=['pharma_stats_core.formula', ...] 추가
• datas=[('../pharma-stats-core/pharma_stats_core', 'pharma_stats_core')] 로 번들 포함
• 또는 editable install 후 PyInstaller 가 정상 탐색하도록 --collect-all pharma_stats_core

---

4. 마이그레이션 로드맵 (3단계)

▶ 1단계: pharmacy-stats-api 내부 정리 (독립 진행, pharmon-web 손대지 않음)

목표: P2, P3, P4, P7 해결. pharmon-web 과의 중복(P1)은 아직 손대지 않음.

순서	작업	영향 파일	검증
1-1	db/connection.py 생성, get_connection(cfg) 하나로 통합	신규	스모크: v1/api/stats 기존과 동일 응답
1-2	core/labels.py 로 GUBUN_LABEL 이전, app.py 에서 import	app.py, core/labels.py	/v1/api/stats/insurance 라벨 동일
1-3	core/age.py, core/aggregator.py 추출 (_calc_age, _empty_row, _add)	v1_pharmit3000.py 에서 제거	수치 동일
1-4	core/formula.py 에 GPPOS 공식 함수로 추출 — calc_sales_amt(row), calc_ins_drug(row) 등	v1_pharmit3000.py	기존 응답 diff 0
1-5	core/margin.py 에 build_margin_cache(rows, query_fn) 추출 (DB 주입형)	v1_pharmit3000.py	1/3 스크린샷 수치 재검증
1-6	core/classifier.py 에 gubun/time/pay 분류 로직 추출	v1_pharmit3000.py	보험별/시간별/결제별 모두 동일
1-7	api/v1.py, api/v2.py, api/compare.py Blueprint 로 분리. app.py 는 factory 만	app.py, api/*.py	모든 엔드포인트 동일 응답
1-8	api/common.py 에 _default_from/to, stats_response(result, version) 헬퍼	v1.py/v2.py 중복 제거	회귀 없음
1-9	tests/test_formula.py 추가 — QT-POS 1/3 스크린샷 수치를 고정값 assert	tests/	pytest tests/ 통과

1단계 완료 조건:

• v1_pharmit3000.py 가 < 150 줄 (현재 368 줄)
• app.py 가 < 50 줄
• 모든 엔드포인트 응답이 리팩토링 전과 1:1 동일 (기준: 2026-04-08 기준 1/3~4/8 응답)
• pytest green

1단계에서 하지 않는 것:

• pharmon-web 수정 — 아직 core/ 는 stats-api 내부에 머무름
• v2 로직 재작성 — 구조만 맞추고 내용은 유지

---

▶ 2단계: pharma-stats-core 분리 (pharmon-web 통합)

목표: P1 해결. 양쪽이 같은 코어를 import.

순서	작업	검증
2-1	c:\Users\청춘약국\source\pharma-stats-core\ 신규 폴더, pharma_stats_core/ 패키지 + pyproject.toml	pip install -e . 성공
2-2	pharmacy-stats-api/core/* → pharma_stats_core/* 로 이동, stats-api 에서 editable install	stats-api 전 엔드포인트 회귀 0
2-3	pharmon-web sales_stats_dialog.py 의 _GUBUN_LABEL, _calc_age, _empty_row, _add, _build_margin_cache, GPPOS 공식을 pharma_stats_core import 로 교체	QT-POS 통계 다이얼로그 기존 스크린샷과 1:1 동일
2-4	pharmon-web PyInstaller spec 업데이트 (hiddenimports / --collect-all)	번들 exe 에서 통계 정상 동작
2-5	pharma-stats-core 에 tests/ 이관, CI 없이 로컬 pytest 만	green
2-6	docs/MODULE_BOUNDARY.md 작성 — "core 는 Qt/Flask 둘 다 의존 금지" 원칙 문서화	문서 리뷰

2단계 완료 조건:

• pharmon-web 에서 grep "GUBUN_LABEL\|_calc_age\|_build_margin_cache" → sales_stats_dialog.py 에 없음 (전부 core 경유)
• stats-api v1/v2 응답 회귀 0
• QT-POS 통계 다이얼로그 회귀 0 (스크린샷 수치 동일)
• PyInstaller 빌드 성공 + 런타임 정상

---

▶ 3단계: v2 (PMPLUS20) 재동기화 + 선택적 확장

목표: P5, P6 해결.

순서	작업
3-1	queries/v2_pmplus20.py 를 v1 과 동일 패턴으로 재작성. SQL 만 v2 테이블(TBSID040_03) 로 바뀌고, 집계/공식은 pharma_stats_core 그대로 사용
3-2	v2 의 테이블/컬럼 매핑 차이 (MPRE_TYPE → PreGubun, DRUG_SEQ → PreSerial 등) 를 queries/v2_pmplus20.py 상단에서 row 딕셔너리 normalize 로 흡수 → core 에는 "v1 스키마" 하나만 존재
3-3	/api/compare 가 실제로 v1/v2 매출 비교 의미있는 수치 반환
3-4	(선택) pharma-stats-core 를 git submodule 또는 별도 repo 로 승격 — 옵션 C 전환

---

5. 리스크 & 완화

리스크	영향	완화
1단계 리팩토링 중 수치 틀어짐	매출 통계 오차	각 단계마다 1/3 스크린샷 기준값을 tests/test_formula.py 에 고정 후 비교
pharmon-web PyInstaller 에서 core 못 찾음	QT-POS 통계 다이얼로그 에러	2-4 단계에서 dev 빌드로 먼저 검증, hidden import 리스트는 ANALYSIS_02_libraries.md 패턴 참고
v2 포팅이 미뤄져 compare API 망가짐	비교 기능 부정확	3단계 전까지 compare 엔드포인트에 "v2 is legacy, may differ" 경고 플래그 붙여둠
1단계에서 너무 많이 쪼개서 과설계	읽기 어려워짐	core 파일당 < 100줄 목표, 기능별로 1파일 1책임. 억지로 클래스화 하지 않음
editable install 이 한글 경로 문제 일으킴	pip install -e 실패	실패 시 sys.path.append('../pharma-stats-core') fallback (pharmon-web 에 이미 패턴 있음)

---

6. 이번 마이그레이션에서 배운 것 (설계 근거)

2026-04-08 작업을 통해 확인한 사실:

1. QT-POS 가 Source of Truth: 통계 로직은 pharmon-web 에서 먼저 수정되고, stats-api 는 후행 동기화. → core 는 pharmon-web 의 인터페이스를 기준으로 설계한다.
2. GPPOS 공식은 절대 단순화 금지: sales_amt = PRICE_C+PRICE_P+S_FASTMON+S_TEMP3+SE_PRICE_C+SE_PRICE_P+SE_BOHUN_C — 7항 가산 공식. 중간에 하나라도 빠지면 1원 단위 오차 발생. → core/formula.py 는 docstring 에 GPPOS2 델파이 레거시 근거 명시.
3. CD_SUNAB 1:N 함정: LEFT JOIN 하면 행 중복 → 금액 이중계산. 반드시 OUTER APPLY TOP 1 패턴. → core 가 아닌 queries/v1 쪽 SQL 에 고정.
4. 보훈 세분화 키는 문자열 '4_1': 숫자 아님. dict 키. → core/labels.py + core/classifier.py 둘 다에서 문자열로만 처리.
5. 라벨 누락은 UI 에 raw 코드 노출: dict.get(code, code) fallback 이 역설적으로 버그 은폐. → 2-2 단계에서 라벨 통합 후, 미매핑 코드는 ? 대신 로그 경고 남기는 것도 검토.

---

7. 의사결정 필요 항목

다음 사항은 1단계 시작 전에 사용자 확답 필요:

• 1단계를 언제 시작할지 — 지금 바로? 아니면 QT-POS 추가 기능 작업 후?
• editable install vs sys.path — pharmon-web 한글 경로(청춘약국) 에서 pip install -e 검증 필요. 실패 시 sys.path 경로 주입 방식으로 폴백.
• 테스트 기준값 스냅샷 — 2026-04-08 1/3 데이터를 "황금 데이터" 로 고정할지, 아니면 매 분기 갱신할지.
• v2 폐기 여부 — PMPLUS20 마이그레이션이 현재 진행 중이 아니라면 v2 모듈을 stub 으로 두는 것도 옵션.

---

8. 참고

• pharmon-web 분석 문서: pharmon-web/docs/ANALYSIS_03_database.md (MSSQL 스키마)
• pharmon-web 분석 문서: pharmon-web/docs/ANALYSIS_02_libraries.md (PyInstaller hidden imports)
• 이번 v1 동기화 변경점: queries/v1_pharmit3000.py 상단 docstring 1~32줄
• GPPOS 델파이 원본 참고: Unit_Statistics.pas (pharmon-web 레거시)