FDE를 위해 API 문서와 실제 응답이 어디서 어긋났는지 판단해주는 CLI입니다.

{"type":"object","properties":{"spec_no":{"type":["string","null"]},"obs_no":{"type":["string","null"]},"verdict":{"type":"string","enum":["in_sync","type_mismatch","missing_in_response","undocumented_field","type_unspecified","endpoint_unmapped","duplicate_spec"]},"doc_type":{"type":["string","null"]},"observed_type":{"type":["string","null"]},"evidence":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"agg":{"type":["string","null"]},"value":{},"quote":{"type":["string","null"]}},"required":["field","value"]}},"next_action":{"type":"string"}},"required":["spec_no","obs_no","verdict","doc_type","observed_type","evidence","next_action"]}

[
  {
    "spec_no": "SP-001",
    "verdict": "in_sync",
    "doc_type": "string",
    "observed_type": "string",
    "evidence": [
      {
        "field": "field_path",
        "value": "order_id"
      },
      {
        "field": "field_type",
        "value": "string"
      },
      {
        "field": "observed_type",
        "value": "string"
      }
    ],
    "next_action": "문서와 응답이 같습니다. 그대로 둡니다.",
    "obs_no": null
  },
  {
    "spec_no": "SP-007",
    "verdict": "in_sync",
    "doc_type": "number",
    "observed_type": "number",
    "evidence": [
      {
        "field": "field_path",
        "value": "price"
      },
      {
        "field": "field_type",
        "value": "number"
      },
      {
        "field": "observed_type",
        "value": "number"
      }
    ],
    "next_action": "문서와 응답이 같습니다. 그대로 둡니다.",
    "obs_no": null
  },
  {
    "spec_no": "SP-002",
    "verdict": "type_mismatch",
    "doc_type": "number",
    "observed_type": "string",
    "evidence": [
      {
        "field": "field_type",
        "value": "number"
      },
      {
        "field": "observed_type",
        "value": "string"
      },
      {
        "field": "sample_count",
        "value": 1200
      }
    ],
    "next_action": "문서는 숫자인데 응답은 문자열입니다. 파트너 파싱이 깨지므로 문서와 응답 중 어느 쪽을 고칠지 먼저 정합니다.",
    "obs_no": null
  },
  {
    "spec_no": "SP-004",
    "verdict": "missing_in_response",
    "doc_type": "string",
    "observed_type": null,
    "evidence": [
      {
        "field": "field_path",
        "value": "coupon_code"
      },
      {
        "field": "is_required",
        "value": false
      }
    ],
    "next_action": "문서에는 있는데 응답에 한 번도 안 나왔습니다. 선택 필드라 삭제할지 문서에 조건을 적을지 정합니다.",
    "obs_no": null
  },
  {
    "spec_no": null,
    "verdict": "undocumented_field",
    "doc_type": null,
    "observed_type": "string",
    "evidence": [
      {
        "field": "field_path",
        "value": "settlement_batch_id"
      },
      {
        "field": "sample_count",
        "value": 1200
      }
    ],
    "next_action": "응답에는 늘 나오는데 문서에 명세가 없습니다. 공개할 필드인지 확인한 뒤 문서에 추가합니다.",
    "obs_no": "OB-005"
  },
  {
    "spec_no": "SP-008",
    "verdict": "type_unspecified",
    "doc_type": null,
    "observed_type": "number",
    "evidence": [
      {
        "field": "field_type",
        "value": null
      },
      {
        "field": "observed_type",
        "value": "number"
      }
    ],
    "next_action": "문서에 타입이 비어 있어 대조하지 못했습니다. 맞다고 세지 않고 문서에 타입을 채웁니다.",
    "obs_no": null
  },
  {
    "spec_no": "SP-009",
    "verdict": "endpoint_unmapped",
    "doc_type": "string",
    "observed_type": null,
    "evidence": [
      {
        "field": "endpoint_raw",
        "value": "GET /v1/webshops",
        "quote": "/v1/webshops"
      }
    ],
    "next_action": "실제 엔드포인트 목록에 없습니다. 폐기된 문서인지 확인한 뒤 문서에서 내립니다.",
    "obs_no": null
  },
  {
    "spec_no": "SP-002",
    "verdict": "duplicate_spec",
    "doc_type": "number",
    "observed_type": "string",
    "evidence": [
      {
        "field": "spec_no",
        "agg": "count",
        "value": 2
      }
    ],
    "next_action": "같은 명세 번호가 두 번 등록됐습니다. 앞 건으로만 판정하고 뒤 건을 문서에서 뺍니다.",
    "obs_no": null
  }
]

[자동 검증 · 1주차] 1. verdict가 enum 일곱 값 안에 있는지 확인합니다. 2. spec_no·obs_no·verdict·doc_type·observed_type·evidence·next_action 칸이 모두 있고, 둘 중 하나 이상이 채워져 있는지 확인합니다. 3. sample_count가 0보다 큰지 확인합니다. 4. field_type이 null이면 verdict가 type_unspecified인지 확인합니다. 5. evidence의 field가 두 입력 표의 컬럼에 실재하는지 확인합니다. 6. evidence의 quote가 그 행 endpoint_raw의 일부인지 확인합니다. 7. next_action이 존댓말로 끝나는지 확인합니다. [판정 규칙] 0. 판정 단위는 엔드포인트와 필드 경로의 짝입니다. 문서에만 있으면 obs_no를 비우고, 응답에만 있으면 spec_no를 비웁니다. 1. 엔드포인트 표기은 대소문자와 띄어쓰기, 구분자를 없애 소문자로 모은 뒤 observed_responses의 endpoint_id와 맞춥니다. 맞는 것이 없으면 미매핑으로 남기고 그 행은 나머지 판정에서 뺍니다. 2. 같은 행 번호가 두 번 들어오면 앞 건만 남기고 뒤 건은 적재 단계에서 사유와 함께 뺍니다. [수동 검증] 1. 문서에 없는 필드가 공개해도 되는 값인지 제품 담당자가 확인합니다. 2. SP-003·SP-005처럼 엔드포인트 표기가 흔들렸지만 표준으로 맞춰진 행은 미매핑 사유를 달지 않는 것이 맞는지 확인합니다. [평가 러너 · 2주차] 1. 버전별로 나눠 필드가 사라지거나 추가된 시점이 하나로 특정되는지 셉니다. 2. 명세와 정답을 작성자가 만든 합성 기준이라 이 수치는 성능 측정이 아니라 데모 조건 동작입니다.