# Classpage 가져오기 형식

이 문서는 `classpage`에서 학생별 별점을 이 앱으로 가져올 때, 어떤 형식으로 주면 가장 편한지 설명합니다.

## 1. 가장 추천하는 형식

가장 추천하는 형식은 `CSV`입니다.

```csv
student_key,classroom,number,student_id,student_name,star_rating,priority_score,grade,grade_level,department_name,position,is_helper,exclude_from_seat,exclude_from_cleaning,special_cleaning_zone,absent_today,cleaning_count,seat_constraint_group,cleaning_constraint_group,selection_order,note
2-3|13|김민지,2-3,13,2026-2-3-13,김민지,5,7,,2,환경부,부장,true,false,false,,false,0,A,B,1,학급회장
2-3|14|박준호,2-3,14,2026-2-3-14,박준호,3,2,,2,체육부,차장,false,false,false,복도,false,1,,A,0,
```

이 헤더 이름을 그대로 쓰면 앱에서 가장 안정적으로 읽습니다.

## 2. 필수 열

아래 두 개만 있어도 앱은 동작합니다.

- `student_name`: 학생 이름
- `star_rating`: 별점 (`1`~`5`)

예:

```csv
student_name,star_rating
김민지,5
박준호,3
이서윤,4
```

## 3. 선택 열

아래 열은 있으면 더 정확하게 활용할 수 있습니다.

- `grade`: 성적 (`0`~`100`)
- `grade_level`: classpage 명단의 학년 값
- `department_name`: 부서명
- `position`: 직급/역할
- `is_helper`: 학급도우미 여부
- `exclude_from_seat`: 자리배치 제외 여부
- `exclude_from_cleaning`: 청소 제외 여부
- `special_cleaning_zone`: 특별구역 또는 특별구역 여부
- `absent_today`: 오늘 제외 여부
- `cleaning_count`: 누적 청소 횟수
- `seat_constraint_group`: 같은 분단을 피하고 싶은 좌석 분리 그룹
- `cleaning_constraint_group`: 같은 청소조를 피하고 싶은 청소 분리 그룹
- `selection_order`: QR 학생 직접 선택 순번
- `priority_score`: classpage 원점수에 가까운 우선도 참고값

## 4. 각 열이 실제로 어디에 쓰이는가

- `student_name`
  자리배치표와 청소표에 표시됩니다.
- `star_rating`
  자리배치 우선순위와 일부 청소 면제 정책에 반영됩니다.
- `grade`
  자리배치에서 성적 가중치 설정에 반영됩니다.
- `department_name`
  부서 기준 청소분담을 할 때 사용됩니다.
- `position`
  학급 운영 역할을 함께 확인할 때 사용됩니다.
- `is_helper`
  학급도우미 면제 정책을 켜면 청소 후보에서 제외됩니다.
- `exclude_from_seat`
  자리배치 대상에서 제외됩니다.
- `exclude_from_cleaning`
  청소 후보에서 제외됩니다.
- `absent_today`
  오늘 결석하거나 임시 제외할 학생을 빼는 용도입니다.
- `cleaning_count`
  청소를 공평하게 분배하기 위한 누적 횟수입니다.
- `special_cleaning_zone`, `cleaning_constraint_group`
  특별구역 제외/분리 배정 같은 청소 운영 규칙에 사용합니다.
- `selection_order`
  QR 학생 직접 선택 모드를 쓸 때 학생 차례입니다. `1`이면 첫 번째, `2`면 두 번째입니다. 비워 두거나 `0`이면 QR 직접 선택 대상이 아닙니다.

## 5. 불리언 값은 어떻게 써야 하는가

아래 값들은 모두 같은 뜻으로 읽습니다.

참으로 읽는 값:

- `true`
- `yes`
- `예`
- `1`

거짓으로 읽는 값:

- `false`
- `no`
- `아니오`
- `0`

## 6. 헤더 이름을 꼭 똑같이 써야 하나요?

가능하면 권장 헤더를 그대로 쓰는 것이 좋습니다.
그래도 아래 비슷한 이름들은 같이 읽도록 넣어 두었습니다.

- `student_name`, `studentName`, `name`
- `star_rating`, `rating`, `stars`
- `grade`, `score`, `academicScore`
- `department_name`, `department`, `dept`
- `is_helper`, `helper`, `classHelper`

## 7. 실제 추천 예시

### 최소 예시

```csv
student_name,star_rating
김민지,5
박준호,3
이서윤,4
```

### 실사용 예시

```csv
student_key,classroom,number,student_id,student_name,star_rating,priority_score,grade,grade_level,department_name,position,is_helper,exclude_from_seat,exclude_from_cleaning,special_cleaning_zone,absent_today,cleaning_count,seat_constraint_group,cleaning_constraint_group,selection_order,note
2-3|13|김민지,2-3,13,2026-2-3-13,김민지,5,7,,2,환경부,부장,true,false,false,,false,0,A,B,1,학급회장
2-3|14|박준호,2-3,14,2026-2-3-14,박준호,3,2,,2,체육부,차장,false,false,false,복도,false,1,,A,0,
2-3|15|이서윤,2-3,15,2026-2-3-15,이서윤,4,4,,2,학습부,,false,false,false,,false,0,,,2,
2-3|16|최도윤,2-3,16,2026-2-3-16,최도윤,2,-1,,2,홍보부,,false,false,true,,false,2,,,0,청소 제외
```

## 8. 운영 팁

- 처음에는 `student_name`, `star_rating`만 넣고 시작해도 됩니다.
- 자리배치가 어느 정도 굳어지면 `grade`를 추가하는 식으로 확장하면 됩니다.
- 청소까지 제대로 쓰려면 `department_name`, `is_helper`, `cleaning_count`를 같이 넣는 것이 좋습니다.
- QR 순번 선택까지 하려면 `selection_order`를 같이 주면 앱에서 바로 반영할 수 있습니다.

## 9. 함께 보면 좋은 파일

- 템플릿 CSV: [`classpage-import-template.csv`](../samples/classpage-import-template.csv)
- 앱 전체 설명: [`README.md`](../README.md)
- 초보자용 설명서: [`guide.html`](../guide.html)