Skip to main content

​
fact 정의란?

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

​
사전 등록 fact

모든 테넌트는 계정 생성 시 2개의 fact가 미리 등록되어 있습니다: 편의를 위해 제공되는 fact일 뿐, 특별히 보호되지 않습니다. 이름 변경·타입 변경·삭제가 커스텀 fact와 똑같은 규칙을 따릅니다. 아무 규칙도 참조하지 않으면 지우거나 타입을 바꿀 수 있고, 참조하는 규칙이 있으면 막힙니다. 등록 없이 즉시 조건과 액션에서 쓸 수 있습니다.

​
커스텀 fact

사전 등록된 2개 fact 외의 모든 입력 변수는 사용 전에 등록하는 것이 좋습니다 (미등록 fact 참고). 예를 들어 customerTier, orderRegion, productCategory 등은 커스텀 fact입니다.

​
지원 타입

​
명명 규칙

fact 키는 영문자로 시작하고, 그 뒤에 영문자, 숫자, 언더스코어를 쓸 수 있습니다. 키는 대소문자를 구분하므로 paymentAmount와 paymentamount는 서로 다른 fact입니다. 표기는 직접 정하세요. LexQ가 만드는 fact와 이 문서의 예시는 camelCase를 쓰지만, 엔진은 어떤 표기든 받고 이미 만든 키는 그대로 동작합니다.
  • ✅ paymentAmount, customerTier, userRegion
  • ✅ payment_amount, PAYMENT_AMOUNT (유효합니다. 이 문서가 쓰지 않을 뿐입니다)
  • ❌ Payment-Amount, PAYMENT AMOUNT, 1stPurchase, _internal

​
필수 vs 선택 fact

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

​
PII fact

fact는 콘솔의 관리 → Fact Definitions에서, 또는 CLI의 --pii 플래그로 PII(개인식별정보)로 지정할 수 있습니다. 지정은 값을 읽는 방식을 바꿀 뿐, 규칙 실행에는 영향이 없습니다.
  • 규칙은 평소처럼 실제 값으로 평가합니다. 마스킹은 사람과 통합을 향한 것이지 엔진을 향한 것이 아닙니다.
  • 모든 읽기 표면(의사결정 출처, 실행 이력 상세, export)에서 값은 ••••••로 마스킹되어 도착하고, maskedKeys가 마스킹된 키 목록을 알려줍니다.
  • 마스킹된 값의 열람은 콘솔 전용이며 감사됩니다. 값이 보이기 전에 감사 행이 먼저 기록됩니다. 전체 계약은 의사결정 출처(Decision Provenance)를 참조하십시오.
이메일, 전화번호, 계정 식별자 같은 fact는 생성 시점에 PII로 지정하십시오. 플래그를 켜는 순간부터 마스킹이 적용되고, 규칙 변경은 필요 없습니다.

​
미등록 fact

fact를 fact 정의로 등록하기 전에도 규칙에서 그 키를 참조할 수 있습니다. LexQ는 먼저 등록하도록 강제하지 않지만, 규칙을 저장할 때마다 스키마에 없는 참조 키를 알려줍니다. 규칙을 create 또는 update 할 때마다 LexQ는 규칙의 조건과 액션을 스캔해 미등록 fact(어떤 fact 정의에도 선언되지 않은 키)를 반환합니다. 각 항목에는 추론된 타입, 제안된 표시 이름, 참조 위치(조건/액션)가 포함됩니다. 이는 의도된 비차단 동작입니다. 미등록 fact가 저장·발행·배포를 막지 않습니다. 규칙은 작성된 그대로 저장되고 실행됩니다. 실행 시 값이 전달되면 조건이 정상 평가되고, 누락되면 조건이 매칭되지 않을 뿐입니다. 등록 전까지 비활성화되는 것: 경고는 규칙을 작성하는 모든 곳에 표시됩니다: CLI(stderr), 콘솔 규칙 편집기와 배포 다이얼로그, MCP 도구.

​
확인 및 등록

저장 응답에 미등록 fact가 포함되지만, 버전 전체를 언제든 조회할 수도 있습니다:
유지할 fact를 등록하세요:
등록은 항상 명시적 단계입니다. LexQ는 규칙이 키를 참조한다고 해서 fact를 자동으로 생성하지 않습니다. 스키마는 규칙 작성의 부산물이 아니라 의도적인 계약으로 유지됩니다.

​
fact 관리

lexq analytics requirements (CLI) 또는 Engine API의 GET /groups/{groupId}/requirements 엔드포인트를 사용하여 배포된 버전이 필요로 하는 fact를 확인하세요.
규칙이 참조하는 fact는 삭제할 수 없고 타입도 바꿀 수 없습니다. 둘 다 409로 거절되며(삭제는 FD-006, 타입 변경은 FD-007) 참조 중인 규칙 수를 함께 알려줍니다. 참조를 먼저 걷거나 새 fact를 만드세요.버전 상태와 무관합니다. 초안이 참조해도 배포된 버전과 똑같이 막힙니다. 이름 변경과 필수 여부 전환은 언제나 열려 있습니다.

​
다음 단계

정책 규칙

규칙 조건과 액션에서 fact를 사용하세요.

정책 실행

실행 시 fact가 어떻게 전달되는지 확인하세요.