@sayren/store-sdk 0.47.0 → 0.49.0

package/src/schemas/condition-tree.ts

@@ -0,0 +1,358 @@
+import * as z from "zod";
+
+/**
+ * 조건 트리 (이슈 #222) — 규칙(필드 · 연산자 · 값)을 `and`·`or` 그룹으로 묶은 JSON이다. **도메인을 모른다.**
+ * 쓰는 쪽(쿠폰 등)이 필드 카탈로그(`ConditionFieldDef`)와 평가 컨텍스트를 주고, 이 파일은 형식 검증·정규화·평가만 한다.
+ *
+ * - 형식은 react-querybuilder와 같은 `{ combinator, rules: [{ field, operator, value }] }`다. CEL 같은 식 문자열은 쓰지 않는다.
+ * - 평가는 fail-closed다 — 카탈로그에 없는 필드, 컨텍스트에 없는 값(`undefined`), 읽지 못하는 값은 그 규칙을 거짓으로 둔다.
+ * - 정규형(`canonicalizeConditionGroup`)은 저장·비교의 기준이다. 화면 키(`id`)를 벗기고 키 순서를 고정하고 집합 값을 정렬한다.
+ */
+
+export type ConditionCombinator = "and" | "or";
+
+/** 규칙 값 — JSON 스칼라나 스칼라 목록(`in` 목록, `between`의 `[from, to]`, 비운 끝은 null). 공개 응답에 그대로 실리므로 직렬화되는 값만 둔다 */
+export type ConditionValue = number | boolean | string | null | (number | string | null)[];
+
+export interface ConditionRule {
+  field: string;
+  operator: string;
+  value: ConditionValue;
+}
+
+export interface ConditionGroup {
+  combinator: ConditionCombinator;
+  rules: ConditionNode[];
+}
+
+export type ConditionNode = ConditionRule | ConditionGroup;
+
+export function isConditionGroup(node: ConditionNode): node is ConditionGroup {
+  return typeof node === "object" && node !== null && "combinator" in node;
+}
+
+/**
+ * 값 형식 — 연산자와 값의 모양을 함께 정한다.
+ * - `integer`: 정수(`=`·`>=`·`<=`, `between`은 `[이상, 이하]`)
+ * - `boolean`: 참·거짓(`=`)
+ * - `idSet`: 문자열 id(`in` — 값 목록 중 하나. 사실 값이 목록이면 하나라도 겹치면 참)
+ * - `enumSet`: 정해진 선택지(`in`)
+ * - `timeRange`: `HH:MM` 구간(`between` — `[시작, 끝]`, 끝 제외. 시작이 끝보다 크면 자정을 넘는 구간)
+ */
+export type ConditionValueType = "integer" | "boolean" | "idSet" | "enumSet" | "timeRange";
+
+export type ConditionOperator = "=" | ">=" | "<=" | "between" | "in";
+
+export const CONDITION_OPERATORS_BY_TYPE: Readonly<
+  Record<ConditionValueType, readonly ConditionOperator[]>
+> = {
+  integer: ["=", ">=", "<=", "between"],
+  boolean: ["="],
+  idSet: ["in"],
+  enumSet: ["in"],
+  timeRange: ["between"],
+};
+
+/** 필드 정의 — `Ctx`는 쓰는 쪽의 평가 컨텍스트다 */
+export interface ConditionFieldDef<Ctx> {
+  name: string;
+  type: ConditionValueType;
+  /** 허용 연산자 — 생략하면 값 형식의 연산자 전부 */
+  operators?: readonly ConditionOperator[];
+  /** `enumSet`의 선택지 */
+  options?: readonly string[];
+  /** `integer`의 범위(포함) */
+  min?: number;
+  max?: number;
+  /** 컨텍스트에서 사실 값을 읽는다. 모르면 `undefined`(규칙은 거짓) */
+  resolve: (ctx: Ctx) => unknown;
+}
+
+export type ConditionCatalog<Ctx> = ReadonlyMap<string, ConditionFieldDef<Ctx>>;
+
+export function conditionCatalog<Ctx>(
+  fields: readonly ConditionFieldDef<Ctx>[],
+): ConditionCatalog<Ctx> {
+  return new Map(fields.map((field) => [field.name, field]));
+}
+
+/** 형식 한도 — 정상 입력은 닿지 않는 폭주 방어선이다 */
+export interface ConditionLimits {
+  /** 그룹 깊이(최상위 = 1) */
+  maxDepth: number;
+  /** 트리 전체의 규칙 수 */
+  maxRules: number;
+  /** 집합 값 하나의 원소 수 */
+  maxSetSize: number;
+}
+
+export const DEFAULT_CONDITION_LIMITS: ConditionLimits = {
+  maxDepth: 3,
+  maxRules: 50,
+  maxSetSize: 500,
+};
+
+// ─── zod 형식 ─────────────────────────────────────────
+
+/** 규칙 형식 — 값 모양은 카탈로그 검증(`conditionIssues`)이 본다 */
+/** 값의 형식만 본다. 필드 타입에 맞는지(정수·목록 길이 등)는 `conditionIssues`가 본다 */
+export const conditionValueSchema: z.ZodType<ConditionValue> = z.union([
+  z.number(),
+  z.boolean(),
+  z.string().max(200),
+  z.null(),
+  z
+    .array(z.union([z.number(), z.string().max(200), z.null()]))
+    .max(DEFAULT_CONDITION_LIMITS.maxSetSize),
+]);
+
+export const conditionRuleSchema = z.strictObject({
+  field: z.string().min(1).max(100),
+  operator: z.string().min(1).max(20),
+  value: conditionValueSchema,
+});
+
+/**
+ * 그룹 형식 — 깊이 3(`DEFAULT_CONDITION_LIMITS.maxDepth`)까지만 받는 고정 단계 스키마다. 재귀(`z.lazy`)로 두면 수천 단계로
+ * 중첩한 본문이 파싱 중에 스택을 넘는다. 더 깊으면 형식 오류(400)다
+ */
+const groupOf = (child: z.ZodType) =>
+  z.strictObject({
+    combinator: z.enum(["and", "or"]),
+    rules: z.array(child).max(100),
+  });
+const level3 = groupOf(conditionRuleSchema);
+const level2 = groupOf(z.union([conditionRuleSchema, level3]));
+export const conditionGroupSchema = groupOf(
+  z.union([conditionRuleSchema, level2]),
+) as unknown as z.ZodType<ConditionGroup>;
+
+// ─── 검증 ─────────────────────────────────────────────
+
+export interface ConditionIssue {
+  /** 트리 안 경로(`rules.0.value`) */
+  path: (string | number)[];
+  code: "DEPTH" | "TOO_MANY_RULES" | "UNKNOWN_FIELD" | "FIELD_NOT_ALLOWED" | "OPERATOR" | "VALUE";
+  field?: string;
+}
+
+const TIME_PATTERN = /^([01]\d|2[0-3]):[0-5]\d$/;
+
+function isInteger(value: unknown, def: { min?: number; max?: number }): value is number {
+  return (
+    typeof value === "number" &&
+    Number.isInteger(value) &&
+    (def.min === undefined || value >= def.min) &&
+    (def.max === undefined || value <= def.max)
+  );
+}
+
+function valueValid<Ctx>(
+  def: ConditionFieldDef<Ctx>,
+  operator: string,
+  value: unknown,
+  limits: ConditionLimits,
+): boolean {
+  switch (def.type) {
+    case "integer":
+      if (operator === "between") {
+        return (
+          Array.isArray(value) &&
+          value.length === 2 &&
+          isInteger(value[0], def) &&
+          isInteger(value[1], def) &&
+          value[0] <= value[1]
+        );
+      }
+      return isInteger(value, def);
+    case "boolean":
+      return typeof value === "boolean";
+    case "idSet":
+    case "enumSet":
+      return (
+        Array.isArray(value) &&
+        value.length > 0 &&
+        value.length <= limits.maxSetSize &&
+        value.every((v) => typeof v === "string" && v.length > 0 && v.length <= 200) &&
+        (def.type === "idSet" || value.every((v) => def.options?.includes(v as string)))
+      );
+    case "timeRange":
+      return (
+        Array.isArray(value) &&
+        value.length === 2 &&
+        value.every((v) => typeof v === "string" && TIME_PATTERN.test(v)) &&
+        value[0] !== value[1]
+      );
+  }
+}
+
+/**
+ * 카탈로그로 트리를 검증한다 — 문제가 없으면 빈 배열. `allowed`를 주면 그 필드만 쓸 수 있다(쓰는 자리별 제한).
+ * zod `superRefine`에서 이 결과를 그대로 이슈로 옮긴다.
+ */
+export function conditionIssues<Ctx>(
+  group: ConditionGroup,
+  catalog: ConditionCatalog<Ctx>,
+  options: { allowed?: (field: string) => boolean; limits?: ConditionLimits } = {},
+): ConditionIssue[] {
+  const limits = options.limits ?? DEFAULT_CONDITION_LIMITS;
+  const issues: ConditionIssue[] = [];
+  let ruleCount = 0;
+  const walk = (node: ConditionGroup, depth: number, path: (string | number)[]) => {
+    if (depth > limits.maxDepth) {
+      issues.push({ path, code: "DEPTH" });
+      return;
+    }
+    node.rules.forEach((child, index) => {
+      const at = [...path, "rules", index];
+      if (isConditionGroup(child)) {
+        walk(child, depth + 1, at);
+        return;
+      }
+      ruleCount += 1;
+      const def = catalog.get(child.field);
+      if (!def) {
+        issues.push({ path: [...at, "field"], code: "UNKNOWN_FIELD", field: child.field });
+        return;
+      }
+      if (options.allowed && !options.allowed(child.field)) {
+        issues.push({ path: [...at, "field"], code: "FIELD_NOT_ALLOWED", field: child.field });
+        return;
+      }
+      const operators = def.operators ?? CONDITION_OPERATORS_BY_TYPE[def.type];
+      if (!operators.includes(child.operator as ConditionOperator)) {
+        issues.push({ path: [...at, "operator"], code: "OPERATOR", field: child.field });
+        return;
+      }
+      if (!valueValid(def, child.operator, child.value, limits)) {
+        issues.push({ path: [...at, "value"], code: "VALUE", field: child.field });
+      }
+    });
+  };
+  walk(group, 1, []);
+  if (ruleCount > limits.maxRules) issues.push({ path: [], code: "TOO_MANY_RULES" });
+  return issues;
+}
+
+// ─── 정규형 ───────────────────────────────────────────
+
+/** 정규형 — 화면 키 등 모르는 키를 버리고 키 순서를 고정하고 `in` 값의 중복을 없애 정렬한다. 저장·잠금 비교·스냅샷이 같은 함수다 */
+export function canonicalizeConditionGroup(group: ConditionGroup): ConditionGroup {
+  return {
+    combinator: group.combinator,
+    rules: group.rules.map((node) =>
+      isConditionGroup(node) ? canonicalizeConditionGroup(node) : canonicalizeConditionRule(node),
+    ),
+  };
+}
+
+export function canonicalizeConditionRule(rule: ConditionRule): ConditionRule {
+  const value =
+    rule.operator === "in" && Array.isArray(rule.value)
+      ? [...new Set(rule.value as string[])].sort()
+      : rule.value;
+  return { field: rule.field, operator: rule.operator, value };
+}
+
+/** 트리에 나온 필드 이름 — 쓰는 쪽이 필요한 사실 값만 읽는 데 쓴다 */
+export function conditionFields(group: ConditionGroup): Set<string> {
+  const fields = new Set<string>();
+  const walk = (node: ConditionGroup) => {
+    for (const child of node.rules) {
+      if (isConditionGroup(child)) walk(child);
+      else fields.add(child.field);
+    }
+  };
+  walk(group);
+  return fields;
+}
+
+// ─── 평가 ─────────────────────────────────────────────
+
+function minutesOf(time: string): number | null {
+  if (!TIME_PATTERN.test(time)) return null;
+  const [h, m] = time.split(":").map(Number) as [number, number];
+  return h * 60 + m;
+}
+
+function ruleHolds<Ctx>(rule: ConditionRule, catalog: ConditionCatalog<Ctx>, ctx: Ctx): boolean {
+  const def = catalog.get(rule.field);
+  if (!def) return false;
+  const fact = def.resolve(ctx);
+  if (fact === undefined || fact === null) return false;
+  const { operator, value } = rule;
+  switch (def.type) {
+    case "integer": {
+      if (typeof fact !== "number" || Number.isNaN(fact)) return false;
+      if (operator === "=") return typeof value === "number" && fact === value;
+      if (operator === ">=") return typeof value === "number" && fact >= value;
+      if (operator === "<=") return typeof value === "number" && fact <= value;
+      if (operator === "between" && Array.isArray(value)) {
+        const [from, to] = value as [unknown, unknown];
+        return typeof from === "number" && typeof to === "number" && fact >= from && fact <= to;
+      }
+      return false;
+    }
+    case "boolean":
+      return operator === "=" && typeof value === "boolean" && fact === value;
+    case "idSet":
+    case "enumSet": {
+      if (operator !== "in" || !Array.isArray(value)) return false;
+      const wanted = value as unknown[];
+      const facts = Array.isArray(fact) ? fact : [fact];
+      return facts.some((f) => wanted.includes(f));
+    }
+    case "timeRange": {
+      if (operator !== "between" || !Array.isArray(value) || typeof fact !== "string") return false;
+      const at = minutesOf(fact);
+      const from = typeof value[0] === "string" ? minutesOf(value[0]) : null;
+      const to = typeof value[1] === "string" ? minutesOf(value[1]) : null;
+      if (at === null || from === null || to === null) return false;
+      // 끝 제외. 시작 > 끝이면 자정을 넘는 구간(22:00~02:00)
+      return from < to ? at >= from && at < to : at >= from || at < to;
+    }
+  }
+}
+
+/** 노드 하나를 평가한다. 빈 그룹은 참(조건 없음)이다 */
+export function evaluateConditionNode<Ctx>(
+  node: ConditionNode,
+  catalog: ConditionCatalog<Ctx>,
+  ctx: Ctx,
+): boolean {
+  if (!isConditionGroup(node)) return ruleHolds(node, catalog, ctx);
+  if (node.rules.length === 0) return true;
+  return node.combinator === "and"
+    ? node.rules.every((child) => evaluateConditionNode(child, catalog, ctx))
+    : node.rules.some((child) => evaluateConditionNode(child, catalog, ctx));
+}
+
+export interface ConditionEvaluation {
+  passed: boolean;
+  /**
+   * 최상위가 `and`일 때 실패한 최상위 노드(앞에서부터). 쓰는 쪽이 사유 코드를 고르는 데 쓴다.
+   * 최상위가 `or`이면 어느 하나를 탓할 수 없어 비어 있다.
+   */
+  failed: ConditionNode[];
+}
+
+export function evaluateCondition<Ctx>(
+  group: ConditionGroup,
+  catalog: ConditionCatalog<Ctx>,
+  ctx: Ctx,
+): ConditionEvaluation {
+  if (group.combinator === "and" || group.rules.length <= 1) {
+    const failed = group.rules.filter((child) => !evaluateConditionNode(child, catalog, ctx));
+    return { passed: failed.length === 0, failed };
+  }
+  return { passed: evaluateConditionNode(group, catalog, ctx), failed: [] };
+}
+
+/** 하나라도 맞는가 — 평평한 규칙 목록(포함·제외 대상)용. 빈 목록은 거짓이다 */
+export function anyConditionHolds<Ctx>(
+  rules: readonly ConditionRule[],
+  catalog: ConditionCatalog<Ctx>,
+  ctx: Ctx,
+): boolean {
+  return rules.some((rule) => ruleHolds(rule, catalog, ctx));
+}