> ## 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.

# 팩트 정의

> 팩트는 규칙이 평가하는 입력 변수입니다. 팩트를 정의, 타이핑, 관리하는 방법을 알아보세요.

## 팩트 정의란?

\*\*팩트 정의(Fact Definition)\*\*는 규칙이 조건과 액션에서 참조할 수 있는 입력 변수를 선언합니다. 함수 파라미터처럼 이름, 타입, 필수 여부를 정의합니다. 팩트는 **테넌트 전체**에서 공유됩니다.

## 사전 등록 팩트

모든 테넌트는 계정 생성 시 2개의 팩트가 미리 등록되어 있습니다:

| 키           | 타입           |  필수 | 설명      |
| ----------- | ------------ | :-: | ------- |
| `user_id`   | STRING       |     | 사용자 식별자 |
| `user_tags` | LIST\_STRING |     | 사용자 태그  |

편의를 위해 제공되는 팩트일 뿐, 특별히 보호되지 않습니다. 일반 커스텀 팩트와 동일하게 이름 변경, 타입 변경, 삭제가 가능합니다. 등록 없이 즉시 조건과 액션에서 사용할 수 있습니다.

## 커스텀 팩트

사전 등록된 2개 팩트 외의 모든 입력 변수는 사용 전에 등록하는 것이 좋습니다 ([미등록 팩트](#미등록-팩트) 참고). 예를 들어 `customer_tier`, `order_region`, `product_category` 등은 커스텀 팩트입니다.

```bash theme={null}
lexq facts create --key customer_tier --name "고객 등급" --type STRING
lexq facts create --key order_region --name "주문 지역" --type STRING --required
lexq facts create --key customer_email --name "고객 이메일" --type STRING --pii
```

## 지원 타입

| 타입            | JSON           | 예시               |
| ------------- | -------------- | ---------------- |
| `STRING`      | `"문자열"`        | `"VIP"`          |
| `NUMBER`      | `숫자`           | `100000`         |
| `BOOLEAN`     | `true / false` | `true`           |
| `LIST_STRING` | `["a", "b"]`   | `["KR", "US"]`   |
| `LIST_NUMBER` | `[1, 2]`       | `[10000, 20000]` |

## 명명 규칙

팩트 키는 `snake_case`를 따릅니다. 키는 **대소문자를 구분**합니다.

* ✅ `payment_amount`, `customer_tier`, `user_region`
* ❌ `paymentAmount`, `Payment-Amount`

## 필수 vs 선택 팩트

* **필수 팩트**: 모든 실행 요청에 반드시 존재해야 합니다. 누락 시 `INVALID_INPUT` 오류.
* **선택 팩트**: 생략 가능. 누락 시 조건이 `false`로 평가됩니다.

## PII 팩트

팩트는 콘솔의 **관리 → Fact Definitions**에서, 또는 CLI의 `--pii` 플래그로 **PII**(개인식별정보)로 지정할 수 있습니다. 지정은 값을 읽는 방식을 바꿀 뿐, 룰 실행에는 영향이 없습니다.

* 룰은 평소처럼 실제 값으로 평가합니다. 마스킹은 사람과 통합을 향한 것이지 엔진을 향한 것이 아닙니다.
* **모든 읽기 표면**(의사결정 출처, 실행 이력 상세, export)에서 값은 `••••••`로 마스킹되어 도착하고, `maskedKeys`가 마스킹된 키 목록을 알려줍니다.
* 마스킹된 값의 열람은 콘솔 전용이며 감사됩니다. 값이 보이기 전에 감사 행이 먼저 기록됩니다. 전체 계약은 [의사결정 출처(Decision Provenance)](/ko/guides/decision-provenance)를 참조하십시오.

<Tip>
  이메일, 전화번호, 계정 식별자 같은 팩트는 생성 시점에 PII로 지정하십시오. 플래그를 켜는 순간부터 마스킹이 적용되고, 룰 변경은 필요 없습니다.
</Tip>

## 미등록 팩트

팩트를 팩트 정의로 등록하기 **전에도** 규칙에서 그 키를 참조할 수 있습니다. LexQ는 먼저 등록하도록 강제하지 않지만, 규칙을 저장할 때마다 스키마에 없는 참조 키를 알려줍니다.

규칙을 `create` 또는 `update` 할 때마다 LexQ는 규칙의 조건과 액션을 스캔해 **미등록 팩트** — 어떤 팩트 정의에도 선언되지 않은 키 — 를 반환합니다. 각 항목에는 추론된 타입, 제안된 표시 이름, 참조 위치(조건/액션)가 포함됩니다.

이는 **의도된 비차단** 동작입니다. 미등록 팩트가 저장·발행·배포를 막지 않습니다. 규칙은 작성된 그대로 저장되고 실행됩니다 — 실행 시 값이 전달되면 조건이 정상 평가되고, 누락되면 조건이 매칭되지 않을 뿐입니다.

등록 전까지 비활성화되는 것:

| 미등록                       | 등록됨                                               |
| ------------------------- | ------------------------------------------------- |
| 값 타입 검증 없음                | 선언된 `STRING` / `NUMBER` / … 기준으로 검증               |
| 콘솔 규칙 편집기 자동완성 없음         | 입력 시 키 제안                                         |
| requirements analyzer 미집계 | `lexq analytics requirements` 및 드라이런 필수 팩트 화면에 표시 |

경고는 규칙을 작성하는 모든 곳에 표시됩니다 — CLI(stderr), 콘솔 규칙 편집기 및 배포 다이얼로그, MCP 도구.

### 확인 및 등록

저장 응답에 미등록 팩트가 포함되지만, 버전 전체를 언제든 조회할 수도 있습니다:

```bash theme={null}
lexq facts unregistered --group-id <gid> --version-id <vid>
```

유지할 팩트를 등록하세요:

```bash theme={null}
lexq facts create --key order_region --name "주문 지역" --type STRING
```

<Info>
  등록은 항상 명시적 단계입니다 — LexQ는 규칙이 키를 참조한다고 해서 팩트를 자동으로 생성하지 않습니다. 스키마는 규칙 작성의 부산물이 아니라 의도적인 계약으로 유지됩니다.
</Info>

## 팩트 관리

```bash theme={null}
lexq facts list
lexq facts create --key order_total --name "주문 합계" --type NUMBER --required
lexq facts update --id <factId> --name "총 주문 금액"
lexq facts delete --id <factId>
```

<Tip>
  `lexq analytics requirements` (CLI) 또는 Engine API의 `GET /groups/{groupId}/requirements` 엔드포인트를 사용하여 배포된 버전이 필요로 하는 팩트를 확인하세요.
</Tip>

<Warning>
  팩트를 삭제해도 기존 규칙에서 자동으로 제거되지 않습니다. 삭제 전에 항상 규칙 의존성을 확인하세요.
</Warning>

## 다음 단계

<CardGroup cols={2}>
  <Card title="정책 규칙" icon="list-check" href="/ko/guides/policy-rules">
    규칙 조건과 액션에서 팩트를 사용하세요.
  </Card>

  <Card title="정책 실행" icon="bolt" href="/ko/api/execution">
    실행 시 팩트가 어떻게 전달되는지 확인하세요.
  </Card>
</CardGroup>