mju309/baseball-automation

Fork 0

Files

minjiu 296adf3073 first jiwoos commit

2026-05-02 11:12:13 +09:00

4.1 KiB

Raw Permalink Blame History

Standard Mapping Schema

이 문서는 mapping_overrides 폴더의 매핑 파일을 하나의 공통 형태로 정리하기 위한 기준입니다.

목표:

매핑 파일마다 다른 키 이름과 구조를 줄인다
단순 치환, 우선순위 룰, 그룹 선택 규칙을 같은 방식으로 읽게 한다
코드 적용 전 사람이 검토하기 쉬운 형태를 유지한다

공통 원칙

모든 파일은 schema_version을 가진다.
모든 규칙은 가능한 한 ordered 목록으로 표현한다.
먼저 매칭되는 규칙이 우선한다.
최종 저장값은 항상 표준값 1개다.
예외 규칙은 일반 규칙보다 뒤가 아니라 우선순위 숫자로 조정한다.

공통 헤더

모든 JSON 매핑 파일은 아래 공통 헤더를 가진다.

{
  "schema_version": "1.0",
  "kind": "alias_map",
  "id": "team_name_map",
  "description": "팀명 별칭을 표준 팀명으로 정규화한다",
  "field": "team_name"
}

필드 의미:

schema_version: 스키마 버전
kind: 파일 타입
id: 사람이 읽는 식별자
description: 파일 목적 설명
field: 이 매핑이 적용되는 대상 필드

스키마 종류

1. `alias_map`

단순 문자열 치환용 스키마다.

{
  "schema_version": "1.0",
  "kind": "alias_map",
  "id": "game_type_map",
  "field": "game_type",
  "entries": [
    { "source": "와일드카드", "target": "wildcard" },
    { "source": "준플레이오프", "target": "semi_playoff" },
    { "source": "플레이오프", "target": "playoff" },
    { "source": "한국시리즈", "target": "korean_series" }
  ]
}

권장 사용처:

팀명
경기 구분
구장명
투구 결과처럼 문자열이 1:1로 대응되는 경우

2. `ordered_rule_map`

우선순위가 필요한 문자열 룰용 스키마다.

{
  "schema_version": "1.0",
  "kind": "ordered_rule_map",
  "id": "batter_result_map",
  "field": "batter_result",
  "default": { "target": "아웃" },
  "rules": [
    {
      "priority": 100,
      "when": {
        "text_contains_any": ["병살", "더블플레이"]
      },
      "then": { "target": "병살-아웃" }
    },
    {
      "priority": 90,
      "when": {
        "result_type_in": ["walk"]
      },
      "then": { "target": "포볼" }
    }
  ]
}

권장 조건 키:

text_contains
text_contains_any
text_contains_all
event_type_in
result_type_in
last_pitch_contains_any
role_in

권장 결과 키:

target: 표준 출력값
group: 선택 그룹 이름
note: 사람이 읽는 설명

3. `group_map`

판독/선택형 UI처럼 결과 그룹이 따로 필요한 규칙용 스키마다.

{
  "schema_version": "1.0",
  "kind": "group_map",
  "id": "review_item_map",
  "field": "review_item",
  "items": [
    {
      "priority": 100,
      "when": { "text_contains_any": ["홈런"] },
      "item": "홈런타구 페어 파울",
      "result_group": ["페어", "파울"]
    },
    {
      "priority": 10,
      "fallback": true,
      "item": "기타",
      "result_group": ["인정", "불인정"]
    }
  ]
}

권장 사용처:

합의판정 항목
결과 버튼 2개 이상이 붙는 UI

4. `special_rules`

JSON으로 표현하기 어려운 예외는 문서로 남긴다.

권장 항목:

조건
예외 사유
UI 처리 순서
금지 규칙

현재 파일의 표준화 방향

pitch_result_map.json
- alias_map으로 정리
batter_result_map.json
- ordered_rule_map으로 정리
runner_event_map.json
- ordered_rule_map으로 정리
review_item_map.json
- group_map으로 정리
special_rules.md
- special_rules 문서로 유지

우선순위 규칙

숫자가 큰 규칙이 먼저다.
같은 priority면 위에서 아래 순서가 우선이다.
fallback: true는 마지막 규칙만 허용한다.

표준값 규칙

저장값은 항상 하나의 표준 문자열이어야 한다.
표준 문자열은 코드에서 다시 해석하지 않아도 되도록 짧고 일관되게 유지한다.
별칭, 공백, 한국어/영문 혼용은 입력 단계에서만 흡수한다.

4.1 KiB Raw Permalink Blame History