# IKEv2 쇼핑몰 주문 연동 매핑 문서

본 문서는 `mylib/ikev2_ipsec.secrets_update.php` 기준으로,
쇼핑몰에서 전달한 주문 payload가 실제로 어디에 저장/반영되는지 정리한 운영 매핑표입니다.

---

## 1) 핵심 원칙

- `ipsec.secrets`:
  - **인증/접속 메타** 저장
  - 예: `user_id`, `password`, `expire`, `memo`, `admin`, `created/updated`
- `IKEv2SellerOffice4U/data/user_billing.json`:
  - **과금유형/단가/정액요금** 저장
  - 예: `type`, `cost_per_gb`, `cost_per_hour`, `fixed_price`, `currency`

즉, 과금유형은 기본적으로 `ipsec.secrets` 한 줄 텍스트가 아니라 `user_billing.json`에서 관리됩니다.

---

## 2) payload 필드 매핑표

| payload 필드 | 필수 | 사용 위치 | 반영 방식 |
|---|---:|---|---|
| `request_id` | Y | 감사 로그/응답 | 응답 JSON 및 audit log 기록 |
| `ts` | Y | 보안 검증 | 타임스탬프 만료 검사(±300초) |
| `nonce` | Y | 보안 검증 | 재전송 방지 저장(`ikev2_nonce_store.json`) |
| `vpn_user_id` | Y | `ipsec.secrets` + billing key | 사용자 식별자 |
| `vpn_user_pw` | 조건부 | `ipsec.secrets` | 신규 사용자 생성 시 필수, 기존 사용자 정책/만료 갱신은 생략 가능 |
| `expire` / `expire_date` | N | `ipsec.secrets` | `expire:YYYY-mm-dd HH:ii:ss` 메타로 반영 |
| `memo` | N | `ipsec.secrets` | `memo:` 메타로 반영 (자동 source tag 추가 가능) |
| `admin` | N | `ipsec.secrets` | `admin:` 메타로 반영 (없으면 `shop_auto` 또는 `manual_api`) |
| `od_id` | N | `memo`/감사로그 | 자동주문 추적 태그(`[od:...]`) |
| `it_id` | N | `memo`/감사로그 | 상품 추적 태그(`[it:...]`) |
| `source` / `provision_source` | N | `memo`/감사로그 | 없으면 `od_id/it_id` 기반 추론(`auto_shop_order`) |
| `billing` (object) | N | `user_billing.json` | 그대로 사용 (`type` 없으면 `usage`) |
| `billing_type` / `charge_type` | N | `user_billing.json` | `billing` 미제공 시 과금유형 생성 |
| `cost_per_gb` | N | `user_billing.json` | usage 단가 |
| `cost_per_hour` | N | `user_billing.json` | usage 단가 |
| `fixed_price` | N | `user_billing.json` | monthly/yearly 정액값 |
| `currency` | N | `user_billing.json` | 통화 단위 |
| `operation` | N | 처리 분기 참고 | `upsert` 기본값 (정책 갱신 시 비번 생략 허용 분기 보조) |

---

## 3) ipsec.secrets 예상 결과 (과금유형별)

아래 예시는 **동일 포맷**으로 저장될 수 있는 대표 샘플입니다.

### A. 종량제(usage)
`vpn1001 : EAP "Abc!9281" # expire:2026-04-11 23:59:59|memo:[source:auto_shop_order][od:20260312-0001][it:IKE-USE-30D]|admin:shop_auto|created:2026-03-12 15:20:11`

### B. 월정액(monthly)
`vpn1002 : EAP "Qwe@5510" # expire:2026-04-12 23:59:59|memo:[source:auto_shop_order][od:20260312-0002][it:IKE-MONTH-1]|admin:shop_auto|created:2026-03-12 15:21:03`

### C. 연정액(yearly)
`vpn1003 : EAP "Zxc#7442" # expire:2027-03-12 23:59:59|memo:[source:auto_shop_order][od:20260312-0003][it:IKE-YEAR-1]|admin:shop_auto|created:2026-03-12 15:22:19`

> 주의: 위 3줄은 **과금 유형별로 줄 포맷이 달라지지 않습니다.**
> 과금 차이는 `user_billing.json`에 저장된 값으로 구분됩니다.

---

## 4) user_billing.json 예상 저장 예시

### usage 예시
```json
{
  "vpn1001": {
    "type": "usage",
    "cost_per_gb": 500,
    "cost_per_hour": 100,
    "currency": "KRW"
  }
}
```

### monthly 예시
```json
{
  "vpn1002": {
    "type": "monthly",
    "fixed_price": 9900,
    "currency": "KRW"
  }
}
```

### yearly 예시
```json
{
  "vpn1003": {
    "type": "yearly",
    "fixed_price": 99000,
    "currency": "KRW"
  }
}
```

---

## 5) 권장 payload 샘플

### usage 주문
```json
{
  "request_id": "req-20260312-001",
  "ts": 1773300000,
  "nonce": "n-abc-001",
  "source": "auto_shop_order",
  "od_id": "20260312-0001",
  "it_id": "IKE-USE-30D",
  "vpn_user_id": "vpn1001",
  "vpn_user_pw": "Abc!9281",
  "expire_date": "2026-04-11 23:59:59",
  "billing": {
    "type": "usage",
    "cost_per_gb": 500,
    "cost_per_hour": 100,
    "currency": "KRW"
  }
}
```

### monthly 주문
```json
{
  "request_id": "req-20260312-002",
  "ts": 1773300100,
  "nonce": "n-abc-002",
  "source": "auto_shop_order",
  "od_id": "20260312-0002",
  "it_id": "IKE-MONTH-1",
  "vpn_user_id": "vpn1002",
  "vpn_user_pw": "Qwe@5510",
  "expire": "2026-04-12 23:59:59",
  "billing": {
    "type": "monthly",
    "fixed_price": 9900,
    "currency": "KRW"
  }
}
```

### yearly 주문
```json
{
  "request_id": "req-20260312-003",
  "ts": 1773300200,
  "nonce": "n-abc-003",
  "source": "auto_shop_order",
  "od_id": "20260312-0003",
  "it_id": "IKE-YEAR-1",
  "vpn_user_id": "vpn1003",
  "vpn_user_pw": "Zxc#7442",
  "expire": "2027-03-12 23:59:59",
  "billing": {
    "type": "yearly",
    "fixed_price": 99000,
    "currency": "KRW"
  }
}
```

---

## 관련 규격 문서
- 쇼핑몰 백엔드 액션 요청 규격: `ikev2_shop_to_vpn_backend_action_request_spec.md`
