# DB DDL 및 VO, XML Mapper 변경사항 정리

작업일: 2025-11-21

## 개요

테이블 DDL의 컬럼 추가 및 변경에 따라 관련 VO, XML Mapper, API 매핑 메소드를 전반적으로 확인 및 수정하였습니다.

---

## 1. tb_car_ledger_frmbk (자동차 등록 원부 갑)

### 1.1 DDL 변경사항
- **추가된 컬럼**:
  - `DRIV_SRGBTRY_IDNTF_NO` (varchar(20)) - 구동축전지 식별번호

- **기존 컬럼**: PRCS_IMPRTY_RSN_CD, PRCS_IMPRTY_RSN_DTLS
  - 기존 VO 및 Mapper에서 잘못된 컬럼명 사용 중이었음 (PROCESS_IMPRTY_RESN_CODE → PRCS_IMPRTY_RSN_CD)

### 1.2 VmisCarLedgerFrmbkVO.java 수정사항

**파일 경로**: `src/main/java/go/kr/project/api/model/response/VmisCarLedgerFrmbkVO.java`

#### 추가된 필드
```java
private String drivSrgbtryIdntfNo;      // DRIV_SRGBTRY_IDNTF_NO
```

#### 수정된 필드 (필드명 변경)
```java
// 변경 전
private String processImprtyResnCode;   // PROCESS_IMPRTY_RESN_CODE (잘못된 컬럼명)
private String processImprtyResnDtls;   // PROCESS_IMPRTY_RESN_DTLS (잘못된 컬럼명)

// 변경 후
private String prcsImprtyRsnCd;         // PRCS_IMPRTY_RSN_CD
private String prcsImprtyRsnDtls;       // PRCS_IMPRTY_RSN_DTLS
```

#### fromNewResponseMaster 메소드 수정

NewLedgerResponse의 실제 필드명에 맞게 getter 메소드 호출 수정:

```java
// 변경 전 (잘못된 getter 메소드명 - 구버전 필드명 사용)
.ledgerIndivNo(response.getLedgerIndvdlzNo())      // ❌
.carmdlAsortCd(response.getVhctyAsortCode())       // ❌
.atmbNm(response.getCnm())                         // ❌
.colorCd(response.getColorCode())                  // ❌
.nopltSpcfctCd(response.getNmplStndrdCode())       // ❌
.usgSeCd(response.getPrposSeCode())                // ❌
.acqsAmt(response.getAcqsAmount())                 // ❌
.regDtlCd(response.getRegistDetailCode())          // ❌
.frstRegYmd(response.getFrstRegistDe())            // ❌
.veagEndYmd(response.getCaagEndde())               // ❌
.yridnw(response.getPrye())                        // ❌
.fbctnYmd(response.getYblMd())                     // ❌
.drvngDstnc(response.getTrvlDstnc())               // ❌
... (등 60여 개 필드)

// 변경 후 (올바른 getter 메소드명 - 신규 필드명 사용)
.ledgerIndivNo(response.getLedgerIndivNo())        // ✅
.carmdlAsortCd(response.getCarmdlAsortCd())        // ✅
.atmbNm(response.getAtmbNm())                      // ✅
.colorCd(response.getColorCd())                    // ✅
.nopltSpcfctCd(response.getNopltSpcfctCd())        // ✅
.usgSeCd(response.getUsgSeCd())                    // ✅
.acqsAmt(response.getAcqsAmt())                    // ✅
.regDtlCd(response.getRegDtlCd())                  // ✅
.frstRegYmd(response.getFrstRegYmd())              // ✅
.veagEndYmd(response.getVeagEndYmd())              // ✅
.yridnw(response.getYridnw())                      // ✅
.fbctnYmd(response.getFbctnYmd())                  // ✅
.drvngDstnc(response.getDrvngDstnc())              // ✅
.issuNo(response.getIssuNo())                      // ✅ 추가
.frstTrnsfrYmd(response.getFrstTrnsfrYmd())        // ✅ 추가
.drivSrgbtryIdntfNo(response.getDrivSrgbtryIdntfNo()) // ✅ 추가
... (등 64개 필드)
```

### 1.3 CarLedgerFrmbkMapper_maria.xml 수정사항

**파일 경로**: `src/main/resources/mybatis/mapper/api/CarLedgerFrmbkMapper_maria.xml`

#### updateCarLedgerFrmbk 수정
```xml
<!-- 추가 -->
<if test="drivSrgbtryIdntfNo != null">DRIV_SRGBTRY_IDNTF_NO = #{drivSrgbtryIdntfNo},</if>

<!-- 수정 -->
<!-- 변경 전 -->
<if test="processImprtyResnCode != null">PROCESS_IMPRTY_RESN_CODE = #{processImprtyResnCode},</if>
<if test="processImprtyResnDtls != null">PROCESS_IMPRTY_RESN_DTLS = #{processImprtyResnDtls},</if>

<!-- 변경 후 -->
<if test="prcsImprtyRsnCd != null">PRCS_IMPRTY_RSN_CD = #{prcsImprtyRsnCd},</if>
<if test="prcsImprtyRsnDtls != null">PRCS_IMPRTY_RSN_DTLS = #{prcsImprtyRsnDtls},</if>
```

---

## 2. tb_car_ledger_frmbk_dtl (자동차 등록 원부 갑 상세)

### 2.1 DDL 변경사항
- **추가된 컬럼**:
  - `HSHLDR_NM` (varchar(75)) - 세대주명
  - `HSHLDR_IDECNO` (varchar(500)) - 세대주개인암호화번호

### 2.2 VmisCarLedgerFrmbkDtlVO.java 수정사항

**파일 경로**: `src/main/java/go/kr/project/api/model/response/VmisCarLedgerFrmbkDtlVO.java`

#### 추가된 필드
```java
private String hshldrNm;                // HSHLDR_NM
private String hshldrIdecno;            // HSHLDR_IDECNO
```

#### 매핑 메소드 수정 (listNewFromExchange)

NewLedgerResponse.Record 클래스의 필드명이 변경됨에 따라 매핑 메소드 수정:

```java
// 변경 전 (잘못된 필드명)
.szrRmvDtlSn(record.getMainchk())
.chgTaskSeCd(record.getChangeJobSeCode())
.mainNo(record.getMainno())
.sno(record.getSubno())
.spcablMttr(record.getDtls())
.aplyRcptNo(record.getRqrcno())
.ledgerIndivNo(record.getLedgerIndvdlzNo())
.chgTaskSeNm(record.getGubunNm())
.chgYmd(record.getChangeDe())
.dtlSn(record.getDetailSn())

// 변경 후 (올바른 필드명)
.szrRmvDtlSn(record.getSzrRmvDtlSn())
.chgTaskSeCd(record.getChgTaskSeCd())
.mainNo(record.getMainNo())
.sno(record.getSno())
.spcablMttr(record.getSpcablMttr())
.hshldrNm(record.getHshldrNm())              // 신규 추가
.hshldrIdecno(record.getHshldrIdecno())      // 신규 추가
.aplyRcptNo(record.getAplyRcptNo())
.ledgerIndivNo(record.getLedgerIndivNo())
.chgTaskSeNm(record.getChgTaskSeNm())
.chgYmd(record.getChgYmd())
.dtlSn(record.getDtlSn())
```

#### 매핑 메소드 수정 (fromRecord)

동일하게 NewLedgerResponse.Record 매핑 수정 및 신규 필드 추가

### 2.3 CarLedgerFrmbkMapper_maria.xml 수정사항

**파일 경로**: `src/main/resources/mybatis/mapper/api/CarLedgerFrmbkMapper_maria.xml`

#### insertCarLedgerFrmbkDtl 수정
```xml
<!-- 컬럼 추가 -->
HSHLDR_NM,
HSHLDR_IDECNO,

<!-- VALUES 추가 -->
#{hshldrNm},
#{hshldrIdecno},
```

---

## 3. tb_car_ffnlg_trgt (자동차 과태료 대상)

### 3.1 변경사항
- DDL과 VO(CarFfnlgTrgtVO.java) 비교 결과 일치함
- 수정 불필요

---

## 4. tb_car_bass_matter_inqire (자동차 기본 사항 조회)

### 4.1 VmisCarBassMatterInqireVO.java 수정사항

**파일 경로**: `src/main/java/go/kr/project/api/model/response/VmisCarBassMatterInqireVO.java`

#### fromOldRequest 메소드 수정

OldBasicRequest의 구조가 헤더 정보(외부 클래스)와 요청 데이터(record 배열)로 분리되어 있음을 반영:

```java
// 변경 전 (잘못된 구조 - request에서 직접 가져옴)
.dmndLevyStdde(request.getLevyStdde())       // ❌ request에 없음
.dmndInqireSeCode(request.getInqireSeCode()) // ❌ request에 없음
.dmndVhrno(request.getVhrno())               // ❌ request에 없음
.dmndVin(request.getVin())                   // ❌ request에 없음

// 변경 후 (올바른 구조 - request.record[0]에서 가져옴)
OldBasicRequest.Record record = request.getRecord().get(0);
.dmndLevyStdde(record.getLevyStdde())       // ✅ record[0]에서 가져옴
.dmndInqireSeCode(record.getInqireSeCode()) // ✅ record[0]에서 가져옴
.dmndVhrno(record.getVhrno())               // ✅ record[0]에서 가져옴
.dmndVin(record.getVin())                   // ✅ record[0]에서 가져옴
```

#### OldBasicRequest 구조 설명

```
OldBasicRequest
├─ 헤더 정보 (외부 클래스)
│  ├─ infoSysId
│  ├─ infoSysIp
│  ├─ sigunguCode
│  ├─ cntcInfoCode
│  ├─ chargerId
│  ├─ chargerIp
│  └─ chargerNm
└─ record[] (요청 데이터 배열)
   └─ [0]
      ├─ levyStdde      (부과기준일)
      ├─ inqireSeCode   (조회구분코드)
      ├─ vhrno          (자동차등록번호)
      └─ vin            (차대번호)
```

---

## 5. NewLedgerResponse 클래스 변경

### 5.1 외부 클래스 필드명 변경사항
**파일 경로**: `src/main/java/go/kr/project/api/model/response/NewLedgerResponse.java`

외부 클래스(마스터 정보)의 필드명이 API 응답 규격에 맞게 변경됨:

#### 주요 변경된 필드 (일부)
```java
// 변경 전 (구버전 필드명)
private String ledgerIndvdlzNo;    // LEDGER_INDVDLZ_NO
private String vhctyAsortCode;     // VHCTY_ASORT_CODE
private String cnm;                // CNM
private String colorCode;          // COLOR_CODE
private String nmplStndrdCode;     // NMPL_STNDRD_CODE
private String prposSeCode;        // PRPOS_SE_CODE
private String acqsAmount;         // ACQS_AMOUNT
private String registDetailCode;   // REGIST_DETAIL_CODE
private String frstRegistDe;       // FRST_REGIST_DE
private String caagEndde;          // CAAG_ENDDE
private String prye;               // PRYE
private String yblMd;              // YBL_MD
private String trvlDstnc;          // TRVL_DSTNC

// 변경 후 (신버전 필드명)
private String ledgerIndivNo;      // LEDGER_INDIV_NO ✅
private String carmdlAsortCd;      // CARMDL_ASORT_CD ✅
private String atmbNm;             // ATMB_NM ✅
private String colorCd;            // COLOR_CD ✅
private String nopltSpcfctCd;      // NOPLT_SPCFCT_CD ✅
private String usgSeCd;            // USG_SE_CD ✅
private String acqsAmt;            // ACQS_AMT ✅
private String regDtlCd;           // REG_DTL_CD ✅
private String frstRegYmd;         // FRST_REG_YMD ✅
private String veagEndYmd;         // VEAG_END_YMD ✅
private String yridnw;             // YRIDNW ✅
private String fbctnYmd;           // FBCTN_YMD ✅
private String drvngDstnc;         // DRVNG_DSTNC ✅
```

**영향**: VmisCarLedgerFrmbkVO.fromNewResponseMaster 메소드의 모든 getter 호출 변경 필요

### 5.2 Record 내부 클래스 변경사항

Record 내부 클래스의 필드명이 API 규격에 맞게 변경됨:

#### 추가된 필드
```java
@JsonProperty("HSHLDR_NM")
private String hshldrNm;              // 세대주명

@JsonProperty("HSHLDR_IDECNO")
private String hshldrIdecno;          // 세대주개인암호화번호
```

#### 기존 필드 (필드명 변경)
- `SZR_RMV_DTL_SN`: Mainchk → szrRmvDtlSn
- `CHG_TASK_SE_CD`: ChangeJobSeCode → chgTaskSeCd
- `MAIN_NO`: Mainno → mainNo
- `SNO`: Subno → sno
- `SPCABL_MTTR`: Dtls → spcablMttr
- `APLY_RCPT_NO`: Rqrcno → aplyRcptNo
- `LEDGER_INDIV_NO`: LedgerIndvdlzNo → ledgerIndivNo
- `CHG_TASK_SE_NM`: GubunNm → chgTaskSeNm
- `CHG_YMD`: ChangeDe → chgYmd
- `DTL_SN`: DetailSn → dtlSn

---

## 6. 작업 체크리스트

- [x] DDL 파일 읽기 (tb_car_ffnlg_trgt, tb_car_ledger_frmbk, tb_car_ledger_frmbk_dtl, tb_car_bass_matter_inqire)
- [x] 관련 VO 파일 읽기 및 확인
- [x] 관련 XML mapper 파일 읽기 및 확인
- [x] API 매핑 메소드 확인
- [x] DDL 변경사항과 현재 구현 비교
- [x] VmisCarLedgerFrmbkVO 수정 (필드 추가, 컬럼명 수정)
- [x] VmisCarLedgerFrmbkVO.fromNewResponseMaster 메소드 수정 (NewLedgerResponse 필드명 변경 반영)
- [x] VmisCarLedgerFrmbkDtlVO 수정 (HSHLDR 필드 추가, fromRecord 메소드 수정)
- [x] CarLedgerFrmbkMapper_maria.xml 수정
- [x] VmisCarBassMatterInqireVO.fromOldRequest 메소드 수정 (record 배열 구조 반영)
- [x] 변경사항 MD 파일 작성

---

## 7. 주의사항

### 7.1 필드명 네이밍 규칙
- VO 필드명: camelCase (예: prcsImprtyRsnCd)
- DB 컬럼명: SNAKE_CASE (예: PRCS_IMPRTY_RSN_CD)
- MyBatis mapper에서 자동 매핑됨

### 7.2 API 응답 매핑
- NewLedgerResponse.Record의 필드명은 API 응답 JSON 규격과 일치해야 함
- @JsonProperty 어노테이션으로 명시적 매핑

### 7.3 테스트 필요 항목
- [ ] 자동차 등록 원부 갑 조회 API 테스트
- [ ] 자동차 등록 원부 갑 상세 조회 API 테스트
- [ ] DB INSERT/UPDATE 쿼리 테스트
- [ ] 신규 필드 매핑 정상 동작 확인

---

## 8. 다음 단계

1. VmisCarBassMatterInqireVO의 NewBasicResponse 매핑 추가 필요 여부 확인
2. 통합 테스트 실행
3. 변경사항 배포 전 검증

---

## 변경 파일 목록

```
수정된 파일:
- src/main/java/go/kr/project/api/model/response/VmisCarLedgerFrmbkVO.java
- src/main/java/go/kr/project/api/model/response/VmisCarLedgerFrmbkDtlVO.java
- src/main/java/go/kr/project/api/model/response/VmisCarBassMatterInqireVO.java
- src/main/resources/mybatis/mapper/api/CarLedgerFrmbkMapper_maria.xml

확인된 DDL:
- DB/DDL/vips/tb_car_ledger_frmbk.sql
- DB/DDL/vips/tb_car_ledger_frmbk_dtl.sql
- DB/DDL/vips/tb_car_bass_matter_inqire.sql
- DB/DDL/vips/tb_car_ffnlg_trgt.sql

수정된 Request/Response 모델:
- src/main/java/go/kr/project/api/model/request/OldBasicRequest.java (구조 확인)
- src/main/java/go/kr/project/api/model/response/NewLedgerResponse.java
```
