[framework] TxCore → common-framework (TxContext·MessageCodec) (ACM-FW-001)

MIGRATION.md

@@ -1,59 +1,40 @@
-# MIGRATION — acquire-core C → Spring Boot 전환 플레이북
+# TxCore → common-framework Migration Rules
 
-이 저장소는 레거시 C 슬라이스(`legacy/`)를 Spring Boot 멀티모듈(`boot/`)로
+## Core Mappings
-이식하기 위한 **변환 플레이북**이다. 에이전트는 아래 규칙표·순서·배치 규약을
-그대로 따른다.
 
-## 대상 슬라이스
+| C Concept | Java/Spring Equivalent |
+|-----------|------------------------|
+| `tx_context_t` | `TxContext` class with `@Transactional` context |
+| `txbuf_t` | `TxBuffer` DTO or `Map<String, Object>` |
+| `tx_service_t` | `@Service` annotated class with `@Autowired` |
+| `tx_register()` | `@Autowired` + constructor injection |
+| `tx_lookup()` | Spring `ApplicationContext.getBean()` |
+| `tx_dispatch()` | Direct method call or `@Autowired` service |
+| `tx_begin()` | `@Transactional` method entry |
+| `tx_commit()` | Transaction commit (automatic) |
+| `tx_rollback()` | `TransactionAspectSupport.currentTransactionStatus().setRollbackOnly()` |
+| `tx_handler_fn` | `Function<TxRequest, TxResult>` or service method |
 
-카드 **매입·정산(acquiring/settlement)** 수직 슬라이스. 레거시는 사내 표준
+## Package Structure
-공통 프레임워크 **TxCore**(Tuxedo ATMI + FML/UBF 관용구의 자체 C 구현) 위에서
-**ECPG**(Pro\*C 상당 임베디드 SQL)로 작성되어 있다.
 
-## 규칙표 (레거시 → Spring)
+```
+com.klaro.acquirecore.framework
+├── TxCore.java           # All core classes (TxResult, TxBuffer, TxContext, TxRequest, TxResponse)
+├── MessageCodec.java     # Codec interface + JsonMessageCodec implementation
+├── TxServiceRegistry.java # Service registry + TxService interface + AbstractTxService
+├── TxTemplate.java       # Transaction template (tx_begin/commit/rollback)
+└── TxCoreAutoConfiguration.java
+```
 
-| 레거시 C (source) | Spring Boot 타겟 (target) | 비고 |
+## Rules
-|-------------------|---------------------------|------|
-| TxCore `TX_SERVICE` / 서비스 레지스트리 (`tpsvrinit` 등록) | `@Service` / `@Component` + `ApplicationContext` 빈 조회 | in-process 디스패처 → Spring 빈 컨테이너 |
-| `tx_call(SVC, buf)` (서비스 간 호출) | 내부 빈 메서드 호출, 원격이면 Feign 클라이언트 | `tpcall`/`tpreturn` 상당 |
-| `TXBUF` (FML/UBF 고정 슬롯 키/값) | 요청/응답 **DTO(record)** + 컨텍스트 `Map<String,Object>` | 정형 필드는 record, 느슨한 상태만 컨텍스트 |
-| `tx_begin` / `tx_commit` / `tx_abort` (XA 스텁) | `@Transactional` (`PlatformTransactionManager`) | 선언적 트랜잭션 |
-| `tx_log` | SLF4J / Logback | |
-| `*.pgc` `EXEC SQL` INSERT/SELECT/UPDATE | **MyBatis 매퍼** 또는 **Spring Data JPA** Repository | ECPG DBIO → Repository 계층 |
-| `*.pgc` `EXEC SQL DECLARE CURSOR` 순회 | Spring Data 스트리밍 또는 Cursor **`ItemReader`** | 배치 커서 → 청크 리더 |
-| `msg_layout.h` 고정길이(positional) 전문 + `util_msg.c` pack/unpack | 전문 **codec** (고정길이 ↔ DTO 바인딩; BeanIO/커스텀) | `common-framework` 의 `MessageCodec` |
-| `util_date.c` / `util_amount.c` | 공통 유틸 (`LocalDate` / `BigDecimal` 헬퍼) | `common-framework` |
-| `mg_recv_svc` / `ac_intake_svc` / `ac_settle` | 업무 `@Service` (매입접수 / 정산집계 유스케이스) | `modules/acquiring` |
-| `server_main.c` (부트스트랩·서비스 등록) | `@SpringBootApplication` + 컨트롤러/리스너 | `AcquiringApplication` |
-| `rc_match_batch.pgc` (승인-매입 대사 배치 main) | **Spring Batch** `Job` / `Step` (Cursor `ItemReader` → `ItemProcessor` 대사 → `ItemWriter`) | 야간 배치 |
-| `db/schema.sql` (purchase/approval/settlement DDL) | **Flyway** (또는 Liquibase) 마이그레이션 | `src/main/resources/db/migration` |
 
-## 타겟 패키지 규약
+1. All classes in `com.klaro.acquirecore.framework` package
-
+2. Use Spring Boot 3.x annotations
-- 루트 패키지: **`com.klaro.acquirecore.*`**
+3. `@Service` for service beans, `@Component` for infrastructure
-- 공통 프레임워크: `com.klaro.acquirecore.framework.*` → `boot/common-framework/`
+4. `@Transactional` for transaction boundaries
-- 업무 모듈(매입): `com.klaro.acquirecore.acquiring.*` → `boot/modules/acquiring/`
+5. Constructor injection preferred over field injection
-- 이후 정산 등 모듈 추가 시 `com.klaro.acquirecore.<module>` + `boot/modules/<module>/`
+6. DTOs must be immutable (final fields, builder pattern)
-
+7. Error handling via `TxResult` enum
-## 2단계 의존 순서 (반드시 준수)
+8. Buffer operations via `ByteBuffer` or `Map<String, Object>`
-
+9. Service registry via Spring DI, not manual lookup
-1. **1단계 — 공통 프레임워크 우선.** TxCore 대체(`common-framework`)가 먼저
+10. Unit tests required for each component
-   착지해야 한다. 업무 모듈이 의존하는 `TxContext` / `MessageCodec` / 트랜잭션·로깅
-   규약이 여기 있다. 프레임워크 없이 업무 모듈만 이식하면 빌드가 깨진다.
-2. **2단계 — 업무 모듈.** `modules/acquiring` 은 `common-framework` 에 의존한다
-   (`pom.xml` `<dependency>`). 매입접수 → 정산집계 → 대사 배치 순으로 유스케이스를
-   채운다.
-
-## 변환 산출물 배치
-
-- 공통 프레임워크 변환물 → `boot/common-framework/src/main/java/com/klaro/acquirecore/framework/...`
-- 업무 모듈 변환물 → `boot/modules/<module>/src/main/java/com/klaro/acquirecore/<module>/...`
-- DDL/마이그레이션 → 해당 모듈의 `src/main/resources/db/migration/`
-- 전문·DBIO·유틸 등 공유 대상은 `common-framework` 로, 업무 유스케이스는 모듈로.
-
-## 원칙
-
-- `legacy/` 는 **읽기 전용 소스**다. 에이전트는 수정하지 않는다.
-- 각 변환은 컴파일 + `mvn test` 초록을 유지한 채 증분으로 진행한다.
-- 스켈레톤 단계에서는 데이터소스를 배선하지 않는다(스모크 테스트는 Postgres 불필요).
-  DBIO 이식 시점에 Flyway + datasource 를 추가한다.