> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lexq.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 변경 영향 시뮬레이션

> 배포 전 과거 실행 데이터에 대해 정책 버전을 실행하여 영향도를 측정합니다.

## 변경 영향 시뮬레이션이란?

\*\*변경 영향 시뮬레이션(Impact Simulation)\*\*은 과거 실행 데이터에 대해 정책 버전을 실행한 후, 베이스라인 버전과 결과를 비교합니다. 배포 전 **회귀 테스트 스위트**입니다.

<Info>
  **변경 영향 시뮬레이션 vs 드라이런:** [드라이런](/ko/guides/dry-run)은 **하나의 입력**을 테스트합니다. 변경 영향 시뮬레이션은 **수백\~수천 개**의 입력을 한 번에 테스트하고 집계 지표를 생성합니다. 개발 중에는 드라이런을, 배포 전에는 변경 영향 시뮬레이션을 사용하세요.
</Info>

## 결과 항목

| 지표         | 설명                    |
| ---------- | --------------------- |
| **매칭률**    | 하나 이상의 규칙이 매칭된 입력의 비율 |
| **규칙별 통계** | 각 규칙의 매칭 횟수와 지표 기여도   |
| **지표 델타**  | 베이스라인과 후보 간 집계 출력 차이  |
| **정책 영향도** | 매칭 건수/비율/지표 값 델타      |

## 시뮬레이션 실행

```bash theme={null}
lexq analytics simulation start --json '{
  "policyVersionId": "<후보-버전-id>",
  "dataset": {
    "type": "HISTORICAL",
    "source": "EXECUTION_LOGS",
    "from": "2025-01-01",
    "to": "2025-01-31"
  },
  "options": {
    "baselinePolicyVersionId": "<베이스라인-버전-id>",
    "includeRuleStats": true,
    "maxRecords": 10000,
    "metricConfig": {
      "targetVariable": "payment_amount__delta",
      "aggregationType": "SUM"
    }
  }
}'
```

<Info>
  `metricConfig.targetVariable`은 응답의 어떤 키든 가리킬 수 있습니다 — input facts, mutated facts, 또는 `generatedVariables` (`MUTATE_FACT`와 `INCREMENT_FACT`가 생성하는 `{key}__delta` 키 포함). 버전 간 집계 동작을 비교하고 싶은 변수를 선택하세요.
</Info>

비동기 실행. 상태가 `COMPLETED`가 될 때까지 폴링:

```bash theme={null}
lexq analytics simulation status --id <simulationId>
```

## 데이터셋 유형

| 유형           | 소스               | 설명                   |
| ------------ | ---------------- | -------------------- |
| `HISTORICAL` | `EXECUTION_LOGS` | 과거 실행 입력 재실행         |
| `MANUAL`     | `REQUEST_BODY`   | 요청 본문에 직접 제공         |
| `UPLOADED`   | `S3_BUCKET`      | S3의 CSV/JSON 데이터셋 사용 |

## 파일 업로드 데이터셋

CSV 또는 JSON 파일을 업로드하여 시뮬레이션 입력으로 사용합니다. 실행 이력이 아닌 커스텀 테스트 데이터가 있을 때 유용합니다.

### 지원 형식

<Tabs>
  <Tab title="CSV">
    첫 행은 Fact 키를 포함하는 헤더여야 합니다. 이후 행은 각각 하나의 테스트 레코드입니다.

    ```csv theme={null}
    payment_amount,customer_tier,is_first_purchase
    150000,VIP,true
    50000,REGULAR,false
    80000,VIP,false
    ```

    **타입 추론:** 숫자, 불리언(`true`/`false`), 문자열이 자동 감지됩니다. 빈 값은 `null`이 됩니다. 따옴표로 감싼 필드 내 쉼표도 지원됩니다.
  </Tab>

  <Tab title="JSON">
    각 객체가 하나의 Facts 세트인 JSON 배열입니다.

    ```json theme={null}
    [
        {"payment_amount": 150000, "customer_tier": "VIP", "is_first_purchase": true},
        {"payment_amount": 50000, "customer_tier": "REGULAR", "is_first_purchase": false}
    ]
    ```

    단건 객체 형식도 지원됩니다 (1건 배열로 래핑):

    ```json theme={null}
    {"facts": {"payment_amount": 150000, "customer_tier": "VIP"}}
    ```
  </Tab>
</Tabs>

**최대 파일 크기:** 10 MB

### 템플릿 다운로드

어떤 컬럼이 필요한지 모르겠다면, 해당 버전의 필수 Facts를 기반으로 예시값이 채워진 템플릿을 다운로드하세요:

<Tabs>
  <Tab title="콘솔">
    **새 시뮬레이션** 다이얼로그에서 데이터셋 유형을 \*\*파일 업로드 (CSV / JSON)\*\*로 선택합니다. "템플릿 다운로드" 아래의 **CSV** 또는 **JSON** 버튼을 클릭합니다.
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    lexq analytics dataset template \
    --group-id <groupId> \
    --version-id <versionId> \
    --format csv \
    --output template.csv
    ```
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    GET /api/v1/partners/analytics/groups/{groupId}/versions/{versionId}/dataset-template?format=csv
    ```
  </Tab>
</Tabs>

### 업로드 및 시뮬레이션 실행

<Tabs>
  <Tab title="콘솔">
    1. **Impact Simulations** → **New Simulation** 이동
    2. 정책 그룹과 대상 버전 선택
    3. **Dataset Type**을 \*\*파일 업로드 (CSV / JSON)\*\*로 설정
    4. 파일을 드래그 앤 드롭하거나 클릭하여 선택
    5. **Uploaded** 배지 확인
    6. **Start Simulation** 클릭
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    # 1단계: 파일 업로드
    lexq analytics dataset upload --file ./my-data.csv
    # → path: datasets/my-tenant/a1b2c3d4e5f6.csv

    # 2단계: 업로드된 경로로 시뮬레이션 시작
    lexq analytics simulation start --json '{
        "policyVersionId": "<versionId>",
        "dataset": {
            "type": "UPLOADED",
            "source": "S3_BUCKET",
            "path": "datasets/my-tenant/a1b2c3d4e5f6.csv"
        },
        "options": {
            "includeRuleStats": true,
            "maxRecords": 10000
        }
    }'
    ```
  </Tab>

  <Tab title="MCP">
    ```
    1. lexq_dataset_template → 예상 형식 확인
    2. lexq_dataset_upload → 인라인 CSV/JSON 콘텐츠 업로드
    3. lexq_simulation_start → 반환된 path로 type UPLOADED 시뮬레이션 시작
    ```
  </Tab>
</Tabs>

## 모범 사례

1. **항상 베이스라인을 설정하세요.** 델타 비교를 위해 필수입니다.
2. **최소 7일의 날짜 범위를 사용하세요.**
3. **`maxRecords` 5,000\~10,000으로 시작하세요.**
4. **모든 프로덕션 배포 전에 시뮬레이션을 실행하세요.**

<Warning>
  변경 영향 시뮬레이션은 과거 입력 팩트에 대해 규칙을 재실행합니다. 외부 부작용(웹훅, 알림)은 항상 모킹되며, 같은 보장이 [의사결정 재실행(Decision Replay)](/ko/guides/decision-replay)에도 적용됩니다.
</Warning>

## 다음 단계

<CardGroup cols={2}>
  <Card title="드라이런" icon="flask-vial" href="/ko/guides/dry-run">
    개발 중 빠른 단일 입력 검증.
  </Card>

  <Card title="A/B 테스트" icon="shuffle" href="/ko/guides/ab-testing">
    라이브 트래픽으로 버전을 비교합니다.
  </Card>
</CardGroup>