변경 영향 시뮬레이션

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

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

변경 영향 시뮬레이션 vs 드라이런: 드라이런은 하나의 입력을 테스트합니다. 변경 영향 시뮬레이션은 수백~수천 개의 입력을 한 번에 테스트하고 집계 지표를 생성합니다. 개발 중에는 드라이런을, 배포 전에는 변경 영향 시뮬레이션을 사용하세요.

결과 항목

지표	설명
매칭률	하나 이상의 규칙이 매칭된 처리 레코드의 비율. 분모에서 오류 레코드는 빠집니다. 매칭 판정 자체가 불가능했기 때문입니다
규칙별 통계	각 규칙의 매칭 횟수와 지표 기여도
지표 델타	비교 기준 버전과 대상 버전 간 집계 출력 차이
정책 영향도	매칭 건수/비율/지표 값 델타
변화 분포	값이 바뀐 레코드 수, 오른 건수와 내린 건수, 그리고 각 방향에서 가장 크게 움직인 한 건

변화 분포 읽기

집계 델타 하나는 여럿이 조금씩 움직인 경우, 하나가 크게 움직인 경우, 양방향으로 크게 움직여 상쇄된 경우가 전부 같아 보입니다. 셋의 위험이 전혀 다르므로 분포가 총량과 함께 모양을 냅니다.

필드	뜻
`changedRecords`	두 버전 사이에서 값이 달라진 레코드 수
`increasedRecords` · `decreasedRecords`	같은 수를 방향으로 나눈 것
`largestIncrease` · `largestDecrease`	각 방향에서 가장 크게 움직인 한 건
`measuredRecords`	대상 변수가 양쪽 버전 모두에 있는 레코드 수. AVG가 이 수로 나눕니다

measuredRecords는 변화 카운트의 분모가 아닙니다. 두 수가 서로 다른 모집단 위에 있습니다. 변화 카운트는 처리된 전 레코드에서 세고 변수가 없는 것을 0으로 봅니다. measuredRecords는 양쪽에 변수가 실제로 있는 레코드만 셉니다. 한쪽에만 있는 레코드는 변화에는 들어가고 측정에는 안 들어가므로 changedRecords가 measuredRecords보다 클 수 있습니다.

객체 전체가 null인 경우가 둘입니다. 비교 기준 버전을 지정하지 않았을 때와, 이 필드가 생기기 전에 끝난 실행일 때입니다. 저장된 결과를 그대로 돌려주므로 이전 실행에는 이 키가 없습니다. largestIncrease와 largestDecrease는 집계가 COUNT면 null입니다. 그때 레코드별 차가 -1, 0, +1 셋뿐이라 어느 한 건이 다른 건보다 더 움직였다고 말할 수 없기 때문입니다.

시뮬레이션 실행

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": "paymentAmount__delta",
      "aggregationType": "SUM"
    }
  }
}'

metricConfig.targetVariable은 응답의 어떤 키든 가리킬 수 있습니다. input facts, mutated facts, 또는 generatedVariables가 대상이며, MUTATE_FACT가 생성하는 {key}__delta 키도 포함합니다. 버전 간 집계 동작을 비교하고 싶은 변수를 선택하세요.

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

lexq analytics simulation status --id <simulationId>

데이터셋 유형

유형	소스	설명
`HISTORICAL`	`EXECUTION_LOGS`	지정한 기간의 과거 실행 입력을 재실행합니다. 대상 버전이 속한 정책 그룹의 실행만 읽습니다
`MANUAL`	`REQUEST_BODY`	요청 본문에 직접 제공
`UPLOADED`	`S3_BUCKET`	S3의 CSV/JSON 데이터셋 사용

레코드 상한

options.maxRecords는 시뮬레이션 한 번이 처리할 레코드 수를 정합니다.

항목	값
하드 캡	시뮬레이션당 100,000건
기본 표본(`maxRecords` 생략)	`HISTORICAL`·`UPLOADED`는 1,000건, `MANUAL`은 전수

하드 캡을 넘는 maxRecords는 400으로 거절합니다. 조용히 자르지 않습니다. 잘린 채로 돌면 진행률이 잘린 분모를 기준으로 100%가 되므로, 나머지가 버려졌다는 신호가 화면 어디에도 남지 않기 때문입니다. 기본값은 엔진이 크기를 미리 알 수 없는 데이터셋에만 걸립니다. HISTORICAL은 날짜 범위이고 UPLOADED는 오브젝트 스토리지의 파일입니다. MANUAL은 방금 보낸 배열이라 크기가 이미 알려져 있고, 여기에 기본 상한을 걸면 명시적으로 준 데이터를 말없이 버리게 됩니다. 명시한 maxRecords는 MANUAL을 포함해 모든 유형에서 그대로 존중합니다.

표본은 무작위가 아닙니다. HISTORICAL은 날짜 범위를 최신순(createdAt 다음 id, 둘 다 내림차순이라 같은 요청은 언제나 같은 순서로 읽습니다)으로 읽어 앞에서부터 maxRecords가 지정한 수만큼 가져옵니다. UPLOADED는 파일 순서대로 앞에서부터 가져옵니다. 30일 범위가 상한에 걸리면 그 달 전체에 고루 퍼진 표본이 아니라 가장 최근 실행만 측정합니다. 상한이 표본을 뽑아 주기를 기대하지 말고 범위를 좁히세요.

파일 업로드 데이터셋

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

지원 형식

CSV
JSON

첫 행은 Fact 키를 포함하는 헤더여야 합니다. 이후 행은 각각 하나의 테스트 레코드입니다.

paymentAmount,customerTier,isFirstPurchase
150000,VIP,true
50000,REGULAR,false
80000,VIP,false

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

각 객체가 하나의 Facts 세트인 JSON 배열입니다.

[
    {"paymentAmount": 150000, "customerTier": "VIP", "isFirstPurchase": true},
    {"paymentAmount": 50000, "customerTier": "REGULAR", "isFirstPurchase": false}
]

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

{"facts": {"paymentAmount": 150000, "customerTier": "VIP"}}

최대 파일 크기: 10 MB

템플릿 다운로드

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

콘솔
CLI
API

새 시뮬레이션 다이얼로그에서 데이터셋 유형을 **파일 업로드 (CSV / JSON)**로 선택합니다. “템플릿 다운로드” 아래의 CSV 또는 JSON 버튼을 클릭합니다.

lexq analytics dataset template \
--group-id <groupId> \
--version-id <versionId> \
--format csv \
--output template.csv

GET /api/v1/partners/analytics/groups/{groupId}/versions/{versionId}/dataset-template?format=csv

업로드 및 시뮬레이션 실행

콘솔
CLI
MCP

Impact Simulations → New Simulation 이동
정책 그룹과 대상 버전 선택
Dataset Type을 **파일 업로드 (CSV / JSON)**로 설정
파일을 드래그 앤 드롭하거나 클릭하여 선택
Uploaded 배지 확인
Start Simulation 클릭

# 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
    }
}'

lexq_dataset_template → 예상 형식 확인
lexq_dataset_upload → 인라인 CSV/JSON 콘텐츠 업로드
lexq_simulation_start → 반환된 path로 type UPLOADED 시뮬레이션 시작

모범 사례

항상 베이스라인을 설정하세요. 델타 비교를 위해 필수입니다.
최소 7일의 날짜 범위를 사용하세요.
maxRecords를 확인하세요. 빠른 검증은 5,000~10,000으로 시작하세요. 상한에 걸린 결과를 무작위 표본으로 읽기 전에 위의 「레코드 상한」을 보세요.
모든 프로덕션 배포 전에 시뮬레이션을 실행하세요.

변경 영향 시뮬레이션은 과거 입력 fact에 대해 규칙을 재실행하며, 엔진 밖으로 나가는 것은 없습니다. 액션 프리미티브 3종은 fact를 읽고 쓸 뿐입니다. 같은 보장이 의사결정 재실행(Decision Replay)에도 적용됩니다.

시작하기

핵심 개념

기능

변경 영향 시뮬레이션