176 lines
4.1 KiB
Markdown
176 lines
4.1 KiB
Markdown
# 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`는 마지막 규칙만 허용한다.
|
|
|
|
## 표준값 규칙
|
|
|
|
- 저장값은 항상 하나의 표준 문자열이어야 한다.
|
|
- 표준 문자열은 코드에서 다시 해석하지 않아도 되도록 짧고 일관되게 유지한다.
|
|
- 별칭, 공백, 한국어/영문 혼용은 입력 단계에서만 흡수한다.
|
|
|