acquire-core-x

실제로 동작하는 카드 매입·정산(card acquiring & settlement) 레거시 시스템 — 상용 카드사 스택(Tuxedo / Pro*C / Oracle / XA)을 오픈소스 등가물(Enduro/X · ECPG/PostgreSQL · XA 2PC) 위에 재현해 진짜로 빌드·부팅·거래가 커밋된다.

목적 — Klaro Forge(자율 마이그레이션 도구)의 대형 전환 대상 픽스처. "Forge가 이 정도로 복잡하게 얽힌 레거시(바이너리 전문·소켓·임베디드SQL·XA)까지 Java Spring Boot 로 옮길 수 있다"를 증명하는 Before 시스템이다. 컴파일만 되는 스텁이 아니라 상용급 TP 미들웨어에서 실제로 도는 시스템이라는 점이 핵심이다.

---

1. 한눈에 (실측)

지표	값
소스 파일 (.pgc/.c/.h)	4,661
코드 라인	333,517 LOC
온라인 서비스 (tpservice)	1,478
배치 잡	506
도메인 모듈	11 (매입·승인·정산·지급·원장·마감·대사·검증·마스터·전문GW·공통)
DB 테이블	101
운영 데이터	~1,173만 행 (매입 135만, 5.5년치, DB ~1.8GB)
ISO 8583 전문 코덱	실제 비트맵·DE 인코딩 (common/acq_iso8583.c)
실제 매입시스템 대비 패리티	≈ 89% (상세)

BAIS(비씨카드 글로벌 매입시스템) RFI 기준 온라인 1,466 · 배치 503 과 1:1 규모.

---

2. 스택

계층	실체	As-Is(상용) 대응
TP 모니터	Enduro/X 7.0.12 (open Tuxedo/ATMI)	Oracle Tuxedo / Tmax ProFrame
전문 버퍼	UBF (≈ FML32)	Tuxedo FML32
DB 접근	ECPG (EXEC SQL)	Pro*C
DB	PostgreSQL 15	Oracle 19c
분산 트랜잭션	XA 2PC (libndrxxaecpg, tmsrv 조율)	Oracle XA
외부 연동	ISO 8583 over TCP (acq_extsw)	밴사/VAN/카드망 회선
컨테이너	docker compose (postgres + endurox app)	—

Oracle 계보: 원본은 Oracle 19c + Pro*C 였다. legacy-oracle/ 에 As-Is Pro*C/ PL-SQL 역사 원본(9본)을 보존하고 방언 이관을 문서화 → ORACLE_PROVENANCE.md. 라이선스: Enduro/X 런타임은 AGPLv3(Mavimax). 내부 테스트 자산으로만 사용.

---

3. 빠른 시작

# 전체 스택 빌드+부팅 (Postgres + Enduro/X 도메인 + 게이트웨이 + 외부망 시뮬레이터)
docker compose -f docker/docker-compose.yml up -d --build

# 업무 포털 (브라우저)
open http://localhost:8090

# 실제 매입 거래 태우기 (6단 XA 체인 → 2PC 커밋)
docker compose -f docker/docker-compose.yml exec app /app/run-driver.sh
#  → >>> COMMIT OK: purchase_id=... status=S

# 외부 카드망 ISO 8583 전문 왕복 (200건)
docker compose -f docker/docker-compose.yml exec app \
  bash -lc 'PGCONN="host=db user=acq password=acq dbname=acq" /app/bin/acq_netdrv 200 localhost 9500'

# 클리어링(정산) 파일 생성 → /app/out/CLR_BC_YYYYMMDD.dat
docker compose -f docker/docker-compose.yml exec app \
  bash -lc 'PGCONN="host=db user=acq password=acq dbname=acq" /app/bin/acq_clrfile 2026-07-19 /app/out'

부팅 시 초기화(대량 시드 포함)에 수 분 소요된다.

---

4. 업무 포털 (http://localhost:8090)

Xplatform 스타일 MDI 포털. 모든 화면이 실측 데이터 기반이며 #해시로 직접 진입.

시스템 조망 (운영자 관점)

• #sys 시스템 현황 — 헬스 KPI·아키텍처 토폴로지·채널·큐·정산사이클·온보딩·KYC·3자대사·외부망 전문왕복·클리어링파일
• #arch 아키텍처 토폴로지 — 호출그래프 552노드·41 모듈간 경로·6단 체인 하이라이트
• #econ 정산 경제 — 수수료 3층(interchange/scheme/markup)·펀딩 항등식·순액정산·MCC·ISO8583
• #sec 카드보안·규제 — PCI 토큰볼트·3DS/SCA·AVS/CVV·DCC·펀딩지시·규제보고

전환 분석 (Forge 관점)

• #mig 마이그레이션 난이도 — 자동변환 실패지점·Oracle 계보·거래 파급·레거시 인벤토리 (전량 실측)

조회/현황·주요 업무 — 운영 대시보드, 매입/정산/가맹점/원장, 승인·매입·정산 등 1,478 서비스 화면.

---

5. 저장소 구조

acquire-core-x/
├── app/
│   ├── src/
│   │   ├── <mod>/                 # 11 도메인 모듈 (ac au st py lg cl rc vl mm mg cm)
│   │   │   ├── <mod>_svr.pgc      #   모듈 서버 (≈133 서비스 advertise)
│   │   │   ├── svc/*.pgc          #   온라인 서비스 (1 서비스 = 1 파일)
│   │   │   ├── dbio/*.pgc         #   DB 접근 함수 (ECPG)
│   │   │   └── batch/*.pgc        #   배치 잡
│   │   ├── common/                # 공통 C (acq_iso8583 ISO코덱·luhn·fee·bizday·seq)
│   │   └── clients/               # acq_httpgw(포털) · acq_extsw(외부망) · acq_netdrv · acq_clrfile
│   ├── ubftab/acq.fd              # UBF 필드 테이블
│   ├── conf/                      # ndrxconfig.xml, setapp.sh (XA env)
│   ├── ui/index.html              # 업무 포털 (SPA, 인라인)
│   ├── build.sh                   # 재사용 빌드 + ndrxconfig 생성 (모듈 자동발견)
│   └── entrypoint.sh              # 빌드→부팅→게이트웨이·시뮬레이터 기동
├── db/schema.d/                   # 스키마+시드 (00-base ~ 99c, 순서대로 init)
├── legacy-oracle/                 # As-Is Oracle Pro*C/PL-SQL 역사 원본 (컴파일 제외)
├── tools/                         # gen_callgraph.py · gen_metrics.py (소스 자동 집계)
├── docker/                        # docker-compose.yml, endurox.Dockerfile
└── docs/                          # 아래 문서 인덱스

---

6. 문서 인덱스

문서	내용
ARCHITECTURE.md	런타임 토폴로지·도메인 분해·트랜잭션 흐름·데이터모델·외부연동·빌드
PARITY_ANALYSIS.md	실제 매입시스템 대비 도메인별 패리티(≈89%)
GAP_ANALYSIS.md	딥리서치 기반 실제 매입사 구조 대조
MIGRATION_COMPLEXITY.md	마이그레이션 난이도 3축(규모·실패지점·레거시성) 실측
ORACLE_PROVENANCE.md	Oracle 계보 + 방언 이관 매핑
OPS_RUNBOOK.md	비기능(HA/DR·PCI·보존·규제) 설계
service-catalog.md	서비스 카탈로그

---

7. 핵심 설계 제약 (마이그레이션 난제)

• XA 브랜치 격리 — 한 글로벌 트랜잭션의 형제 XA 브랜치는 서로의 미커밋 행을 못 본다. 판정값은 UBF 전문으로 실어 나른다(owner-writes 규율). 위반 시 교착.
• 6단 XA 체인 — ACQUIRE→RECONCILE→SETTLE→ST_MDR→LG_SETTLEPOST→LG_BALCHK 가 하나의 2PC 로 원자 커밋. 모듈내 tpcall 을 위해 서버 카피 4개.
• ISO 8583 와이어 — 비트맵·DE 인코딩·소켓 프레이밍·타임아웃→취소 전문처리.
• 임베디드 SQL 23,000+ 블록·UBF 47,000+ 접근 — 자동 문법변환이 깨지는 지점.

이 제약들이 곧 Forge 마이그레이션의 난이도이며, 지표는 tools/gen_metrics.py 가 소스에서 자동 집계한다("이 숫자 진짜냐"에 코드로 답한다).