# How to parse Comcigan

> [!WARNING]
> 컴시간알리미 측에선 3rd party 앱을 허용하지 않기 때문에, 이 문서에서 설명할 방법은 언제든지 작동을 멈출 수 있습니다. 또한 이 문서는 오로지 학습 목적으로 작성되었으며, 이를 통해 발생하는 모든 문제에 대해 작성자는 책임지지 않습니다.

이 문서에선 컴시간알리미를 파싱하는 방법에 대해서 설명합니다.

## Getting Started

Base URL: `http://comci.net:4082` (protocol이 `http`인 것에 주의)

컴시간알리미는 일정 주기마다 모든 route와 응답의 구조를 변형합니다. 따라서 `GET /st`을 요청해 응답을 `EUC-KR`로 decode한 뒤, 아래 테이블의 정규표현식을 사용해 route와 code를 추출해야 합니다.

| Name           | RegExp                              |
| -------------- | ----------------------------------- |
| mainRoute      | `(?<=\.\/)\d+(?=\?\d+l)`            |
| searchRoute    | `(?<=\?)\d+(?=l)`                   |
| timetableRoute | `(?<=')\d+(?=_')`                   |
| teacherCode    | `(?<=성명=자료\.자료)\d+`           |
| originalCode   | `(?<=원자료=Q자료\(자료.자료)\d+`   |
| dayCode        | `(?<=일일자료=Q자료\(자료.자료)\d+` |
| subjectCode    | `(?<=자료.자료)\d+(?=\[sb\])`       |

또한 `GET /st`를 제외한 모든 응답은 `Null` 문자들을 포함하고 있기 때문에 이를 제거해야 파싱이 수월합니다. 후술할 내용들은 모두 응답의 `Null` 문자들을 제거한다는 가정하에 작성되었습니다.

## Endpoints

### 학교 검색

학교를 검색하기 위해선 먼저 학교 이름을 EUC-KR로 encode해야 합니다. 이후 `GET /{mainRoute}?{searchRoute}l{인코딩된 학교 이름}`을 요청하면 다음과 같은 응답을 받을 수 있습니다.

```jsonc
{
  "학교검색": [
    {
      12345, // 알 수 없는 값 (comcigan.ts에선 지역 코드로 사용)
      "서울", // 지역 이름
      "ㅇㅇ중학교", // 학교 이름
      12345 // 학교 코드
    },
    ...
  ]
}
```

### 시간표 조회

시간표를 조회하기 위해선 상술한 학교 검색을 통해 학교 코드를 알아내야 합니다. 이후 `{timetableRoute}_{학교 코드}_0_1`을 `base64`로 encode하고, `GET /{mainRoute}?{인코딩된 param}`를 요청하면 다음과 같은 응답을 받을 수 있습니다.

> [!NOTE]
> '원자료'는 원래 일과 시간표, '일자료'는 일일 시간표를 의미합니다. 원자료와 일자료는 다를 수 있고, 특정 교시에 대해선 둘 중 하나만 존재할 수도 있습니다.

```jsonc
{
  "자료{teacherCode}": [
    "*", // 교사의 개인정보 보호를 위해 사용되는 문자
    "ㄱㄴ*",
    "ㄹㅁ*",
    ...
  ],
  "자료{subjectCode}": [
    12, // 과목 개수
    "국어",
    ...
  ],
  "자료{originalCode}": [
    3, // 원자료 학년 개수
    [
      10, // 원자료 1학년 반 개수
      [
        5, // 원자료 1학년 1반 요일 개수
        [
          6, // 원자료 1학년 1반 월요일 교시 개수
          12345, // 원자료 1학년 1반 월요일 1교시 코드
          ...
        ],
        ...
      ],
      ...
    ],
    ...
  ],
  "자료{dayCode}": [
    /* 원자료와 구조 동일 */
  ]
}
```

교시 코드에서 교사와 과목을 알아내기 위해선 다음과 같은 작업이 필요합니다.

1. `teachersLen`을 다음과 같이 정의합니다. (교사 수를 10진수로 표현했을 때의 자릿수를 의미합니다)

$$\lfloor \log_{10}(\text{{amount of teachers}}) \rfloor + 1$$

2. 교사 코드는 다음과 같고, 응답의 `자료{teacherCode}`에서 index `교사 코드`의 값이 교사 이름입니다.

$$ \text{{교시 코드}} \mod 10^{\text{{teachersLen}}} $$

3. 과목 코드는 다음과 같고, 응답의 `자료{subjectCode}`에서 index `과목 코드`의 값이 과목 이름입니다.

$$ \left\lfloor \frac{\text{{교시 코드}}}{10^{\text{{teachersLen}} + 1}} \right\rfloor $$

# Changelog

## 2024-08-10

- User-Agent 관련 내용 삭제 (불필요한 정보)
- route 및 응답 주기 관련 내용 삭제 (불확실한 정보)
- 학교 검색 결과의 1번째 값이 지역 코드가 아닐 수 있다는 것을 명시
- 단어 형태 수정 (디코딩 -> decode)

## 2024-07-16

- 교사 코드 및 과목 코드 계산 방법 변경 (string slice w/ type conversion -> modulo operation, floor division)

## 2024-07-14

- 문서 최초 작성