# Standard Mapping Schema

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

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

## 공통 원칙

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

## 공통 헤더

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

```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`

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

```json
{
  "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`

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

```json
{
  "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처럼 결과 그룹이 따로 필요한 규칙용 스키마다.

```json
{
  "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`는 마지막 규칙만 허용한다.

## 표준값 규칙

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