# Post-Migration Checklist — v1 → v2 마이그레이션 후 필수 작업

**작성일**: 2026-04-01
**적용 대상**: `migrate_v1_to_v2.py` 실행 후

---

## 개요

마이그레이션 스크립트는 **데이터 이관**만 수행합니다.
운영 시스템이 정상 동작하려면 아래 후속 작업이 필요합니다.

---

## P0 — 마이그레이션 직후 즉시 (서비스 시작 전)

### 1. Monitor 주소 등록

마이그레이션된 HOT/MASTER 지갑의 `monitor_registered = 0`으로 설정됩니다.
블록체인 모니터에 주소를 재등록해야 입금 감지가 가능합니다.

```sql
-- 미등록 지갑 확인
SELECT wallet_type, network_id, COUNT(*)
FROM wallet_addresses
WHERE monitor_registered = 0 AND status = 'ACTIVE'
GROUP BY wallet_type, network_id;
```

**조치**: Admin Console → 지갑 관리 → Monitor 등록 일괄 실행, 또는 `MonitorRegistrationService` 호출.

### 2. Nonce Tracker 초기화

마이그레이션에서 `nonce_tracker`는 스킵됩니다.
NonceManager에 auto-init 로직이 구현되어 있으므로 **별도 초기화 불필요** — 첫 TX 발생 시 체인에서 자동 조회하여 생성됩니다.

**확인만**: GAS/RELAYER 지갑이 정상적으로 nonce를 획득하는지 첫 집금/출금 시 로그 확인.

### 3. 인프라 지갑 확인 (GAS / RELAYER)

인프라 지갑(GAS, RELAYER)은 마이그레이션 대상이 아닙니다. v2에서 별도 생성되어 있어야 합니다.

```sql
-- 인프라 지갑 존재 확인
SELECT wallet_type, network_id, address, status
FROM wallet_addresses
WHERE wallet_type IN ('GAS', 'RELAYER')
ORDER BY network_id, wallet_type;
```

**조치**: 누락된 네트워크가 있으면 Admin Console → 인프라 지갑 생성 API 호출.

---

## P1 — 서비스 시작 후 1일 이내

### 4. HOT 지갑 Approve 재설정

v1 approve (`gasless_prerequisites`)는 마이그레이션하지 않았습니다.
v2 컨트랙트가 다르므로 새로 approve가 필요합니다.

**동작 방식**: Approve는 입금 후 첫 집금 시점에 `CollectionBatchRunner`가 자동 트리거합니다.
- HOT 지갑에 `wallet_approvals` 행이 없으면 PENDING으로 생성
- `ApprovalPoller` → `ApprovalProcessor`가 순차 처리 (GAS 지원 → approve TX)
- **수동 개입 불필요** — 입금이 발생하면 자연스럽게 진행

**확인**: 첫 입금 후 `wallet_approvals` 테이블에 PENDING → COMPLETED 전환 확인.

```sql
-- approve 진행 상태 확인
SELECT wa.wallet_address_id, wal.address, wal.network_id, wa.status, wa.tx_hash
FROM wallet_approvals wa
JOIN wallet_addresses wal ON wa.wallet_address_id = wal.id
ORDER BY wa.created_at DESC
LIMIT 20;
```

### 5. Approve Nonce 관리

Approve TX는 HOT 지갑에서 직접 전송하며 (Relayer가 아님), `ApprovalProcessor`가 체인 provider의 auto-nonce를 사용합니다.
`NonceManager`를 사용하지 않으며, `ApprovalPoller`의 순차 처리로 nonce 충돌이 방지됩니다.

**별도 조치 불필요** — 현재 구조에서 안전합니다.

### 6. Axim Pay Webhook URL 변경

v2 서버 URL이 변경되었으므로 Axim Pay 연동 설정을 업데이트해야 합니다.

**조치**:
1. Axim Pay 관리 콘솔에서 webhook URL을 v2 open-api 서버 주소로 변경
2. 파트너별 `partner_axim_settings` 확인 — `is_enabled = 1`인 파트너 목록

```sql
SELECT pas.partner_id, p.name, pas.is_enabled
FROM partner_axim_settings pas
JOIN partners p ON p.id = pas.partner_id
WHERE pas.is_enabled = 1;
```

### 7. External Wallet 재연동

v1 `external_wallet_mappings` / `axim_wallet_connections`는 마이그레이션하지 않았습니다.
파트너가 Axim Pay 앱에서 외부 지갑을 다시 연결해야 합니다.

**조치**: 해당 파트너에게 재연동 안내.

---

## P2 — 서비스 안정화 후 (1주 이내)

### 8. 잔액 온체인 동기화

마이그레이션된 `wallet_balances`는 v1 마지막 상태 기준입니다.
온체인 실제 잔액과 차이가 있을 수 있습니다.

**조치**: Admin Console → 지갑 잔액 동기화 실행, 또는 scheduler의 balance sync 배치.

### 9. Webhook Delivery 재시도 큐 확인

`webhook_delivery_logs`에서 `PENDING`/`RETRYING` 상태 레코드는 마이그레이션되었지만, reference_id가 v1 transaction ID입니다.

```sql
-- 미완료 콜백 확인
SELECT status, COUNT(*) FROM webhook_delivery_logs
WHERE status IN ('PENDING', 'RETRYING')
GROUP BY status;
```

**조치**: 미완료 건이 있으면 수동 재발송하거나, v2에서 재생성할지 판단.

### 10. Partner 콘솔 로그인 테스트

마이그레이션된 파트너 계정으로 Partner Console 로그인 확인.
`password_hash` 호환성 검증.

### 11. Auto-Increment 정합성 확인

Phase 20에서 AUTO_INCREMENT를 동기화하지만, 이후 수동 INSERT가 있었다면 충돌 가능.

```sql
-- 주요 테이블 AUTO_INCREMENT 확인
SELECT TABLE_NAME, AUTO_INCREMENT
FROM information_schema.TABLES
WHERE TABLE_SCHEMA = 'cryptoments_db'
  AND TABLE_NAME IN ('partners', 'wallet_addresses', 'deposits', 'withdrawals')
ORDER BY TABLE_NAME;
```

---

## 배제 항목 요약 (재확인)

| 항목 | 사유 | 후속 조치 |
|------|------|----------|
| FEE/SYSTEM 지갑 | v2에서 GAS/RELAYER로 별도 생성 | P0 #3 확인 |
| nonce_tracker | 온체인 자동 초기화 | P0 #2 확인 |
| external_wallets | v2에서 Axim 재연동 | P1 #7 |
| axim_payments | v2에서 새로 시작 | — |
| wallet_approvals | v2 컨트랙트 불일치 | P1 #4 자동 처리 |
| deposit_reservations | v1 예약 만료/완료 | — |
| gas_cost_records | v2에서 새로 집계 | — |
| collection_queue | 실시간 처리 | — |
| currency_prices | 실시간 시세 | — |
| payment_links | 스킵 | — |
| partner_telegram_configs | 신규 봇으로 이동 | — |

---

## 마이그레이션 실행 순서

```bash
# 1. DRY RUN — 건수 확인
python3 v2-docs/migrate_v1_to_v2.py --dry-run

# 2. 실제 실행
python3 v2-docs/migrate_v1_to_v2.py

# 3. P0 체크리스트 순서대로 확인
# 4. 서비스 시작
# 5. P1/P2 체크리스트 진행
```