# DDL vs Entity Mismatch - Action Items

## CRITICAL ISSUES (Requires Immediate Action)

### 1. Missing Entity Classes (2 tables without Java entities)

#### Issue 1a: PartnerExchangeRatePolicy Entity Missing
- **DDL Table:** `partner_exchange_rate_policies` (lines 1154-1176 in CRYPTOMENTS_V2_DDL.sql)
- **Status:** NO Java entity exists
- **Impact:** Cannot persist/query exchange rate policy configurations via ORM
- **Action Required:** Create `PartnerExchangeRatePolicy.java` entity class

**DDL Structure to implement:**
```sql
CREATE TABLE partner_exchange_rate_policies (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    partner_id BIGINT NOT NULL,
    rate_type VARCHAR(20) NOT NULL DEFAULT 'INHERIT',  -- INHERIT | FIXED
    fixed_rate DECIMAL(20,4) DEFAULT NULL,
    created_at DATETIME(6),
    updated_at DATETIME(6),
    UNIQUE KEY uk_partner (partner_id)
)
```

---

#### Issue 1b: RelayerContract Entity Missing
- **DDL Table:** `relayer_contracts` (lines 648-683 in CRYPTOMENTS_V2_DDL.sql)
- **Status:** NO Java entity exists
- **Impact:** Cannot manage relayer contract deployments (address, owner, status, ABI version)
- **Action Required:** Create `RelayerContract.java` entity class

**DDL Structure to implement:**
```sql
CREATE TABLE relayer_contracts (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    network_id BIGINT NOT NULL,
    contract_address VARCHAR(255) NOT NULL,
    owner_address_id BIGINT NOT NULL,
    deploy_tx_hash VARCHAR(255) NOT NULL,
    abi_version VARCHAR(20) NOT NULL DEFAULT '1.0',
    status VARCHAR(20) NOT NULL DEFAULT 'ACTIVE',  -- ACTIVE | PAUSED | DEPRECATED
    paused_at DATETIME(6),
    paused_reason VARCHAR(500),
    created_at DATETIME(6),
    updated_at DATETIME(6),
    UNIQUE KEY uk_network (network_id)
)
```

---

### 2. Withdrawal.java - Missing Critical Fields

**File:** `/sessions/vibrant-epic-noether/mnt/cryptoments/common/src/main/java/com/cryptoments/common/entity/Withdrawal.java`

#### Issue 2a: Missing relayerWalletId Field
- **DDL Column:** `relayer_wallet_id BIGINT` (line 1309)
- **Purpose:** Track which relayer executed the withdrawal transaction
- **Status:** Entity does NOT have this field
- **Criticality:** HIGH - Required for withdrawal audit trail and relayer accountability
- **Action Required:** Add field to Withdrawal.java:
  ```java
  /** relayer_wallets.id — 출금 실행 Relayer */
  private Long relayerWalletId;
  ```

#### Issue 2b: Missing errorMessage Field  
- **DDL Column:** `error_message TEXT` (line 1320)
- **Purpose:** Store failure error messages for debugging and user communication
- **Status:** Entity does NOT have this field
- **Added in:** v1.3 (must be backward compatible)
- **Criticality:** MEDIUM - Important for error tracking and support
- **Action Required:** Add field to Withdrawal.java:
  ```java
  /** 실패 시 에러 메시지 */
  private String errorMessage;
  ```

---

## HIGH PRIORITY ISSUES (Should Fix Soon)

### 3. WebhookDeliveryLog.java - JSON Handling

**File:** `/sessions/vibrant-epic-noether/mnt/cryptoments/common/src/main/java/com/cryptoments/common/entity/WebhookDeliveryLog.java`

#### Issue 3: request_payload Type Mismatch
- **DDL Column:** `request_payload JSON NOT NULL` (line 1428)
- **Entity Type:** `String requestPayload`
- **Status:** Type mismatch - DDL uses JSON, Entity uses String
- **Impact:** Must verify JSON serialization/deserialization at persistence layer
- **Action Required:** 
  - Verify that the MyBatis/ORM layer properly serializes String to JSON when saving
  - Verify that the MyBatis/ORM layer properly deserializes JSON to String when loading
  - Consider adding @JsonRawValue annotation if needed
  - OR: Change to use a JSON library annotation (e.g., @Type(type = "json"))

**Note:** This is acceptable if properly handled at the ORM level, but should be verified.

---

## MEDIUM PRIORITY ISSUES (Worth Checking)

### 4. WalletBalance.java - Decimal Precision

**File:** `/sessions/vibrant-epic-noether/mnt/cryptoments/common/src/main/java/com/cryptoments/common/entity/WalletBalance.java`

#### Issue 4: balance Field Precision
- **DDL Column:** `balance DECIMAL(36,18) NOT NULL DEFAULT 0` (line 476)
- **Entity Type:** `BigDecimal balance`
- **Status:** Using Java BigDecimal for DECIMAL(36,18) - generally OK but verify
- **Action Required:** 
  - Verify that BigDecimal correctly handles 36 integer digits + 18 fractional digits
  - Consider adding @Column annotation with precision/scale if ORM requires it
  - Test edge cases with very large balances
  - Verify rounding behavior matches DB expectations

---

## VERIFIED CORRECT (No Action Needed)

The following entities are correctly synchronized with DDL v1.4:

✓ **Currency.java** 
- Successfully includes `contractAddress` field added in v1.4
- All 13 columns present

✓ **Partner.java**
- All 30 columns present
- Sensitive fields properly marked @JsonIgnore

✓ **PartnerChainConfig.java**
- All 7 columns present

✓ **PartnerAximSettings.java**
- All 10 columns present

✓ **PaymentLink.java**
- All 17 columns present

✓ **AximPayment.java**
- All 20 columns present

✓ **CurrencyPrice.java**
- All 12 columns present with correct decimal precision

✓ **Deposit.java**
- All 25 columns present
- Correctly handles GENERATED ALWAYS net_amount column

✓ **NonceTracker.java**
- All 8 columns present

✓ **Removed Tables**
- `currency_networks` correctly removed from DDL v1.4

---

## IMPLEMENTATION CHECKLIST

- [ ] Create PartnerExchangeRatePolicy.java entity
- [ ] Create RelayerContract.java entity  
- [ ] Add relayerWalletId field to Withdrawal.java
- [ ] Add errorMessage field to Withdrawal.java
- [ ] Verify WebhookDeliveryLog.java JSON serialization
- [ ] Verify WalletBalance.java BigDecimal precision
- [ ] Run comprehensive entity validation tests
- [ ] Update any ORM mapping files if needed
- [ ] Test with sample data from all 13 entities

---

## REFERENCES

- DDL File: `/sessions/vibrant-epic-noether/mnt/outputs/CRYPTOMENTS_V2_DDL.sql` (v1.4)
- Entity Directory: `/sessions/vibrant-epic-noether/mnt/cryptoments/common/src/main/java/com/cryptoments/common/entity/`
- Full Comparison Report: `DDL_ENTITY_COMPARISON_REPORT.md` (this directory)