# Phase 1: DDL↔코드 정합성 수정 보고서

**작업일**: 2026-03-16
**기준 문서**: `NODEJS_PHASE1_DDL_ALIGNMENT_GUIDE.md`
**DDL 버전**: v1.4 (`registration_status` COMMENT 반영)
**빌드 결과**: `pnpm run build` — 5개 패키지 모두 SUCCESS

---

## 수정 결과 요약

| 항목 | 심각도 | 상태 | 변경 파일 수 |
|------|--------|------|-------------|
| A-1. RelayerStatus 분리 | HIGH | ✅ | 4 |
| A-3. CollectionStatus COMPLETED→CONFIRMED | MEDIUM | ✅ | 1 |
| A-4. WithdrawalType 값 변경 | MEDIUM | ✅ | 1 |
| A-5. WalletKey key_version→encryption_key_version | LOW | ✅ | 2 |
| A-6. WalletIndexManager last_index→current_index | LOW | ✅ | 2 |
| A-2. WalletAddressStatus SUSPENDED 제거 | LOW | ✅ | 1 |

---

## A-1. RelayerStatus 분리 (HIGH) ✅

### 변경 의도

DDL에서 `relayer_wallets` 테이블은 운영 상태(`status`)와 온체인 등록 상태(`registration_status`)를 **별도 컬럼**으로 관리. 기존 코드는 하나의 `RelayerStatus` 타입으로 혼용.

### 변경 내용

#### `common/src/types/wallet.ts`

```typescript
// Before
export type RelayerStatus = 'REGISTERING' | 'ACTIVE' | 'INACTIVE' | 'DEREGISTERING';

// After — 2개 타입 분리
export type RelayerOperationStatus = 'ACTIVE' | 'PAUSED';
export type RegistrationStatus = 'PENDING' | 'REGISTERING' | 'REGISTERED' | 'DEREGISTERING' | 'REVOKED';
```

`RelayerWallet` 인터페이스에 `contract_address`, `registration_tx_hash`, `registration_status` 필드 추가.

#### `common/src/db/repositories/RelayerWalletRepo.ts`

| 변경 항목 | Before | After |
|----------|--------|-------|
| import | `RelayerStatus` | `RelayerOperationStatus`, `RegistrationStatus` |
| `insert()` | `status: RelayerStatus` | `registration_status?: RegistrationStatus` |
| `updateStatus()` | 단일 메서드 | `updateOperationStatus()` + `updateRegistrationStatus()` 분리 |
| `updateRegistration()` | 하드코딩 유니온 | `RegistrationStatus` 타입 사용 |
| `findActiveRelayer()` | `status = 'ACTIVE'` | `+ registration_status = 'REGISTERED'` 조건 추가 |

#### `relayer-api/src/routes/relayer.ts`

| 기존 호출 | 변경 후 |
|-----------|---------|
| `insert({ status: 'REGISTERING' })` | `insert({ registration_status: 'REGISTERING' })` |
| `updateStatus(id, 'ACTIVE')` | `updateRegistrationStatus(id, 'REGISTERED')` |
| `updateStatus(id, 'INACTIVE')` | `updateRegistrationStatus(id, 'REVOKED')` + `updateOperationStatus(id, 'PAUSED')` |
| `updateStatus(id, 'DEREGISTERING')` | `updateRegistrationStatus(id, 'DEREGISTERING')` |

API 응답에 `registrationStatus` 필드 추가 (list, status, register, unregister).

#### `blockchain-api/src/services/ContractDeployService.ts`

- `addRelayer` TX 실패 롤백: `updateStatus('INACTIVE')` → `updateRegistrationStatus('REVOKED')` + `updateOperationStatus('PAUSED')`
- `removeRelayer` 성공: `updateRegistration(..., 'REVOKED')` + `updateOperationStatus('PAUSED')`

---

## A-3. CollectionStatus: `COMPLETED` → `CONFIRMED` ✅

**파일**: `common/src/types/tx.ts`

```typescript
// Before
| 'COMPLETED'

// After
| 'CONFIRMED'
```

코드에서 `'COMPLETED'` 리터럴 직접 사용처 없음 (TX 확인은 Spring Boot webhook 서버가 처리). 타입 변경만으로 충분.

---

## A-4. WithdrawalType 값 변경 ✅

**파일**: `common/src/types/tx.ts`

```typescript
// Before
export type WithdrawalType = 'USER' | 'REFUND' | 'PARTNER';

// After
export type WithdrawalType = 'USER_PAYOUT' | 'REFUND' | 'PARTNER_WITHDRAW';
```

코드에서 `WithdrawalType` 리터럴 비교/분기 없음. 타입 변경만으로 충분.

---

## A-5. WalletKey: `key_version` → `encryption_key_version` ✅

**파일 2개**:

| 파일 | 변경 |
|------|------|
| `common/src/types/wallet.ts` | `key_version: string` → `encryption_key_version: string` |
| `common/src/db/repositories/WalletKeyRepo.ts` | ORDER BY, INSERT 컬럼명 변경 |

---

## A-6. WalletIndexManager: `last_index` → `current_index` ✅

**파일 2개**:

| 파일 | 변경 |
|------|------|
| `common/src/types/wallet.ts` | `last_index: number` → `current_index: number` |
| `common/src/db/repositories/WalletIndexManagerRepo.ts` | INSERT, SELECT, UPDATE 컬럼명 변경 (3곳) |

---

## A-2. WalletAddressStatus: `SUSPENDED` 제거 ✅

**파일**: `common/src/types/wallet.ts`

```typescript
// Before
export type WalletAddressStatus = 'ACTIVE' | 'INACTIVE' | 'SUSPENDED';

// After
export type WalletAddressStatus = 'ACTIVE' | 'INACTIVE';
```

DDL에 `SUSPENDED` 없음. 코드에서 `'SUSPENDED'` 리터럴 사용처 없음 확인 후 제거.

---

## 변경 파일 목록 (8개)

| 패키지 | 파일 | 항목 |
|--------|------|------|
| common | `src/types/wallet.ts` | A-1, A-2, A-5, A-6 |
| common | `src/types/tx.ts` | A-3, A-4 |
| common | `src/db/repositories/RelayerWalletRepo.ts` | A-1 |
| common | `src/db/repositories/WalletKeyRepo.ts` | A-5 |
| common | `src/db/repositories/WalletIndexManagerRepo.ts` | A-6 |
| relayer-api | `src/routes/relayer.ts` | A-1 |
| blockchain-api | `src/services/ContractDeployService.ts` | A-1 |

---

## 선행 작업 (DB Migration)

```sql
ALTER TABLE relayer_wallets
  MODIFY COLUMN registration_status VARCHAR(20) NOT NULL DEFAULT 'PENDING'
    COMMENT 'PENDING / REGISTERING / REGISTERED / DEREGISTERING / REVOKED';
```