# 도시철도 열차 운행 데이터 구조 명세

## 1. 시스템 개요

이 시스템은 도시철도 열차 운행 정보를 조회하기 위해 다음 두 가지 요소를 결합한다.

1. 열차번호 규칙 (논리 규칙)
2. 실제 운행시각표 데이터 (Parquet 파일)

열차번호는 열차의 종별과 방향을 판별하는 데 사용되며,
실제 운행 정보는 Parquet 시각표에서 조회한다.

---

## 2. 데이터 저장 구조

운행시각표는 Parquet 파일로 저장되며,
`diagram_type` 기준으로 partition 구조를 사용한다.

### 디렉토리 구조

```
timetable_parquet/
 ├── diagram_type=평일/
 │    └── part-*.parquet
 ├── diagram_type=토요일/
 │    └── part-*.parquet
 └── diagram_type=휴일/
      └── part-*.parquet
```

이 구조를 사용하면 특정 다이어(평일/토요일/휴일)만 빠르게 조회할 수 있다.

---

## 3. Parquet 테이블 스키마

각 Parquet 파일은 다음 컬럼 구조를 가진다.

| 컬럼명          | 타입                | 설명            |
| ------------ | ----------------- | ------------- |
| train_number | int               | 열차번호          |
| station      | string            | 역명            |
| seq          | int               | 역 순번 (운행 순서)  |
| time         | string (HH:MM:SS) | 해당 역 통과 시각    |
| diagram_type | string            | 평일 / 토요일 / 휴일 |

### 예시 데이터

| train_number | station | seq | time     | diagram_type |
| ------------ | ------- | --- | -------- | ------------ |
| 1001         | 노포      | 1   | 05:08:00 | 평일           |
| 1001         | 범어사     | 2   | 05:09:50 | 평일           |
| 1001         | 남산      | 3   | 05:11:40 | 평일           |

---

## 4. 열차번호 규칙

열차번호의 **일의 자리 숫자**로 열차의 종별과 방향을 판별한다.

### 4.1 방향 규칙

| 일의 자리 | 방향 |
| ----- | -- |
| 홀수    | 상선 |
| 짝수    | 하선 |

---

### 4.2 열차종별 규칙

| 일의 자리 | 열차종별  |
| ----- | ----- |
| 1, 2  | 정기열차  |
| 3, 4  | 회송열차  |
| 5, 6  | 시운전열차 |
| 7, 8  | 구간열차  |
| 9     | 임시열차  |

※ 임시열차(9)는 상선만 존재한다.

---

## 5. 기본 조회 절차

### 입력 예시

```
열차번호: 1001
다이어: 평일
```

### 처리 단계

1. 열차번호의 일의 자리 추출
2. 열차종별 및 방향 판별
3. 해당 다이어 partition에서 시각표 조회
4. seq 기준 정렬 후 결과 반환

---

## 6. Python 조회 예시

```python
import pandas as pd

def classify_train_number(train_number: int):
    last_digit = train_number % 10

    direction = "상선" if last_digit % 2 == 1 else "하선"

    if last_digit in (1, 2):
        train_type = "정기"
    elif last_digit in (3, 4):
        train_type = "회송"
    elif last_digit in (5, 6):
        train_type = "시운전"
    elif last_digit in (7, 8):
        train_type = "구간"
    elif last_digit == 9:
        train_type = "임시"
        direction = "상선"
    else:
        train_type = "알수없음"

    return {
        "train_number": train_number,
        "type": train_type,
        "direction": direction
    }


def get_train_timetable(train_number, diagram_type):
    df = pd.read_parquet(
        "timetable_parquet",
        filters=[
            ("diagram_type", "=", diagram_type),
            ("train_number", "=", train_number)
        ]
    )

    return df.sort_values("seq")
```

---

## 7. 시스템 데이터 흐름

```
사용자 질문
   ↓
열차번호 추출
   ↓
열차번호 규칙 적용
   ↓
Parquet 시각표 조회
   ↓
결과 반환
```

---

## 8. 설계 원칙

1. 열차번호 규칙은 데이터가 아닌 **논리 규칙**으로 처리한다.
2. 시각표는 **Parquet partition 구조**로 저장한다.
3. 조회 성능을 위해 JSON 대신 Parquet을 사용한다.
4. 시간 데이터는 `"HH:MM:SS"` 문자열로 통일한다.

---

## 9. 주요 장점

* 빠른 열차 조회
* 다이어별 빠른 필터링
* AI/RAG 시스템과 직접 연동 가능
* 대용량 시각표 처리 가능
