# Phase 10. 마에스트로 정보 수정 및 학생 목록 고도화

## 목표

`/maestros/[maestroId]` 상세 화면에서 마에스트로 정보를 직접 수정할 수 있는 폼을 추가하고, 학생 목록을 서버 사이드 페이지네이션과 이름 검색이 가능한 형태로 완성한다.

---

## 1. 마에스트로 상세 화면 수정 폼 구현

### 사전 조사 결과 (기존 mouse-typing 코드 확인 완료)

| 조사 항목 | 파일 위치 | 결과 |
|---|---|---|
| 이름 중복 검사 기준 | `server/maestro/update_maestro_info.php` | **중복 검사 없음** — 이름을 그대로 UPDATE. chocoadmin에서 신규 추가. |
| 이메일 변경 처리 | `server/maestro/update_maestro_info.php` | 변경 시 이메일 안내 메일 발송 + `maestro_log` 기록. 메일은 Phase 11에서 구현. |
| 입장코드 수정 컬럼 | `server/maestro/set_allow_edit_entercode.php` | `maestro.AllowEditEnterCode`: `0`(비허용) / `1`(허용). 로그 기록 없음. |
| 상태/계정유형 변경 로그 | `server/admin/` 전체 | 기존 관리자에서 상태/계정유형/사용가능일을 직접 수정하는 기능 없음. 신규 기능이므로 신규 로그 타입 정의. |

정의한 신규 로그 타입 (기존 코드에 없음):

| Type | 대상 필드 | Remark 형식 |
|---|---|---|
| `update_maestro_status` | `ActivateStatus` | `{prev} -> {new}` (숫자) |
| `update_maestro_account_type` | `AccountType` | `{prev} -> {new}` (숫자) |
| `update_maestro_available_date` | `AvailableActivateDateTime` | `{YYYY-MM-DD} -> {YYYY-MM-DD}` |
| `update_maestro_allow_enter_code` | `AllowEditEnterCode` | `{prev} -> {new}` (0 or 1) |

### API 구현: `PATCH /api/maestros/[id]` ✅

파일: `app/api/maestros/[id]/route.ts` (기존 GET과 동일 파일에 PATCH 추가)
서비스 레이어: `lib/maestros.ts`에 `updateMaestroSchema`, `UpdateMaestroPayload`, `updateMaestro()` 추가

**요청 스키마 (Zod)**

| 필드 | 타입 | 규칙 |
|---|---|---|
| `name` | `string` | 1자 이상, trim |
| `email` | `string` | 이메일 형식 |
| `activateStatus` | `0 \| 1 \| 2 \| 100` | `ACTIVATE_STATUSES` 상수 |
| `accountType` | `1 \| 2 \| 3 \| 4 \| 5` | 유료 타입만 허용 (`PaidAccountType`) |
| `availableActivateDateTime` | `string` | ISO datetime 또는 `YYYY-MM-DD` 형식 |
| `allowEditEnterCode` | `0 \| 1` | 정수 |

모든 필드는 optional — 전달된 필드만 업데이트한다.

**처리 순서**

1. `withApiHandler`로 인증 자동 검사
2. 대상 maestro 존재 확인 (`findUnique`) — 없으면 404
3. `name`이 포함된 경우: 동일 이름의 다른 마에스트로 존재 여부 확인 — 있으면 409
4. 변경 필드 추출 (전달값 vs 현재값 비교, 동일한 값이면 변경 대상에서 제외)
5. 변경 필드가 없으면 200 + `{ changed: false }` 반환 (DB 업데이트 및 로그 기록 생략)
6. 트랜잭션: `maestro` 업데이트 + `maestro_log` INSERT (변경된 필드별로 각각 로그 기록)
7. 성공 응답: 200 + `{ changed: true }`

**응답 정책**

| 상황 | HTTP | 비고 |
|---|---|---|
| 변경 없음 | 200 | `{ changed: false }` |
| 성공 | 200 | `{ changed: true }` |
| 이름 중복 | 409 | 자기 자신은 중복으로 처리하지 않음 |
| 존재하지 않는 마에스트로 | 404 | |
| 유효하지 않은 값 | 400 | Zod 파싱 실패 |
| 인증 없음 | 401 | `withApiHandler` 처리 |

### UI 구현: 수정 폼 ✅

파일: `app/(admin)/maestros/[maestroId]/MaestroEditForm.tsx` (신규 Client Component)

현재 상세 페이지(`page.tsx`)의 "기본 정보" 섹션을 읽기 전용 표시에서 편집 가능한 폼으로 교체한다.

**필드 구성**

| 필드 | 컴포넌트 | 비고 |
|---|---|---|
| 이름 | `<Input type="text">` | |
| 이메일 | `<Input type="email">` | |
| 상태 | `<Select>` | `ACTIVATE_STATUS_LABELS` 기반 |
| 계정유형 | `<Select>` | `ACCOUNT_TYPE_LABELS` 기반, 유료 타입만 |
| 사용 가능일 | `<Input type="datetime-local">` | |
| 입장코드 수정 | `<Select>` | 허용(1) / 비허용(0) |

**제출 흐름**

1. 저장 버튼 클릭 → 확인 다이얼로그 표시
2. 확인 → `PATCH /api/maestros/[id]` 호출, 저장 버튼 비활성화
3. 성공 → 성공 토스트 + `router.refresh()`로 화면 갱신
4. 실패 → 실패 토스트 (이름 중복 409 응답 시 "이미 사용 중인 이름입니다." 별도 메시지)

---

## 2. 학생 목록 구현

### API 구현: `GET /api/maestros/[id]/students` ✅

파일: `app/api/maestros/[id]/students/route.ts` (신규)
서비스 레이어: `lib/maestros.ts`에 `studentSearchSchema`, `MaestroStudentsResult`, `getMaestroStudents()` 추가

**쿼리 파라미터**

| 파라미터 | 타입 | 기본값  | 설명 |
|---|---|------|---|
| `page` | number | `1`  | 페이지 번호 |
| `pageSize` | `10 \| 20 \| 50` | `10` | 페이지 크기 |
| `q` | string | `""` | 이름 검색 (`LIKE %q%`) |

**응답 형식**

```ts
{
  items: Array<{
    playerID: number;
    name: string;
    enterCode: string;
    accountType: number | null;
  }>;
  page: number;
  pageSize: number;
  totalCount: number;
  totalPages: number;
  q: string;
}
```

**처리 순서**

1. `withApiHandler`로 인증 검사
2. maestro 존재 확인 — 없으면 404
3. 쿼리 파라미터 Zod 파싱
4. `player` 테이블에서 `MaestroID` 조건 + 이름 `LIKE` 검색 + 페이지네이션 조회
5. 정렬: `PlayerID DESC`

### UI 구현: 학생 목록 ✅

현재 "학생 목록 요약" 섹션(최근 20명 고정)을 서버 사이드 페이지네이션 목록으로 교체한다.

파일: `app/(admin)/maestros/[maestroId]/StudentsSection.tsx` (신규 Client Component)

**구성 요소**

- 이름 검색 입력 (`<Input>`) + 검색 버튼
- 전체 학생 수 표시 (`전체 N명`)
- 학생 목록 테이블 (`PlayerID`, `이름`, `입장코드`)
- 페이지네이션 컨트롤 — 마에스트로 목록과 동일한 슬라이딩 윈도우 형식 (현재 페이지 ±2, 처음/끝 이동, ±5 그룹 이동)
- 빈 목록 상태: "등록된 학생이 없습니다."
- 검색 결과 없음 상태: "검색 결과가 없습니다."

**동작**

- 검색어 입력 후 Enter 또는 검색 버튼 클릭으로 조회 (실시간 debounce 없음)
- 검색어 변경 시 page를 1로 초기화
- 페이지 이동은 URL query string 없이 컴포넌트 state로 관리

---

## 3. 검증 ✅

| 항목 | 방법 | 기대 결과 | 실행 결과 |
|---|---|---|---|
| 이름 중복 저장 실패 | 다른 마에스트로와 동일한 이름으로 저장 시도 | 409, "이미 사용 중인 이름입니다." | ✅ 409 + `{"message":"이미 사용 중인 이름입니다."}` |
| 이름 자기 자신과 동일 | 현재 이름 그대로 저장 | 변경 없음 처리 또는 중복 아님으로 정상 처리 | ✅ 200 + `{"changed":false}` |
| 정보 수정 성공 후 DB 반영 | 이름 / 이메일 / 상태 / 계정유형 / 사용 가능일 / 입장코드 수정 변경 후 DB 직접 조회 | 변경값 반영 확인 | ✅ 모든 필드 DB 반영 확인 |
| maestro_log 기록 확인 | 정보 수정 성공 후 `maestro_log` 조회 | 변경 필드별 `Type`, `Remark` 형식이 §1 정의와 일치 | ✅ 6개 Type 모두 정확한 형식으로 기록됨 |
| 변경 없는 저장 | 현재 값 그대로 저장 시도 | `{ changed: false }` 응답, `maestro_log` 미기록 | ✅ 200 + `{"changed":false}`, 로그 없음 |
| 학생 목록 페이지네이션 | 학생 수가 pageSize 초과인 마에스트로에서 다음 페이지 이동 | 정확한 레코드 표시, `totalCount` 일치 | ✅ 823명 마에스트로: totalPages=83, page=2 정상 |
| 학생 목록 이름 검색 | 존재하는 이름 일부로 검색 | 해당 학생만 필터링 | ✅ `q=최건` → totalCount=1, 해당 학생만 반환 |
| 학생 목록 검색 결과 없음 | 존재하지 않는 이름으로 검색 | 빈 상태 메시지 표시 | ✅ totalCount=0, items=[] |
| 비인증 접근 차단 | 세션 없이 `PATCH /api/maestros/[id]`, `GET /api/maestros/[id]/students` 호출 | 401 응답 | ✅ 401 + `{"message":"Unauthorized"}` |

### 부가 수정 사항

- `proxy.ts` matcher 수정: `api/auth` → `api/` (API 라우트 전체를 미들웨어 제외 대상으로 변경)
  - 기존: API 라우트에 미들웨어가 개입하여 307 리다이렉트 반환
  - 수정 후: API 라우트는 `withApiHandler`가 직접 401 처리