# Phase 0 작업 계획

## 1. 목적

`docs/plan/project-plan.md`의 `9. 개발 단계 계획 > Phase 0. 기존 관리자 코드 조사`를 수행하기 위한 실행 계획이다.

Phase 0의 목표는 기존 `mouse-typing` 관리자 기능의 비즈니스 규칙을 확인하고, 신규 `chocoadmin`에서 동일하게 재현해야 할 규칙을 `docs/business-rules.md`에 문서화하는 것이다.

## 2. 조사 대상

기존 서비스 경로:

- `/Users/jisangs/work/jinaju/git/web/mouse-typing`

우선 조사 디렉터리:

- `/Users/jisangs/work/jinaju/git/web/mouse-typing/src/web/admin/`
- `/Users/jisangs/work/jinaju/git/web/mouse-typing/src/web/server/admin/`

주요 서버 파일:

- `login.php`
- `maestro_all_list.php`
- `maestro_registered_list.php`
- `maestro_extension_list.php`
- `extension_maestro.php`
- `maestro_upgrade_list.php`
- `upgrade_maestro.php`
- `register_maestro.php`
- `activate_stage.php`

주요 화면 파일:

- `login.html`
- `admin_all_list.html`
- `admin_register_list.html`
- `admin_extension_list.html`
- `admin_upgrade_list.html`
- `admin_expiration_list.html`
- `admin_header.html`

## 3. 확인해야 할 핵심 질문

### 3-1. 관리자 라우트와 기능 구조

- 관리자 화면별 HTML 파일과 서버 PHP 파일의 호출 관계를 확인한다.
- 각 화면의 목록 조회 조건, 검색 조건, 정렬 기준, 상태 필터를 확인한다.
- 신규 `chocoadmin`의 화면/API 구조와 직접 매핑 가능한 기능 목록을 정리한다.

산출물:

- 기존 화면 -> 기존 서버 파일 -> 신규 화면/API 매핑표

### 3-2. 연장 승인 규칙

- `extension_maestro.php`에서 연장 승인 처리 흐름을 확인한다.
- `maestro_extension.Status` 변경값과 변경 조건을 확인한다.
- `maestro.AvailableActivateDateTime` 계산 방식을 확인한다.
- `maestro.ActivateStatus` 변경 여부와 값을 확인한다.
- 실패/중복 처리 조건이 있는지 확인한다.

현재 `docs/plan/project-plan.md`에 기록된 가정:

- 계정 유형별 차이 없이 1년 연장

검증 기준:

- 기존 코드에서 날짜 계산 로직이 `+1 year`, `+12 month`, 고정 일수 중 무엇인지 확인한다.
- 만료일이 과거인 경우 기준일이 현재일인지 기존 만료일인지 확인한다.

### 3-3. 업그레이드 승인 규칙

- `upgrade_maestro.php`에서 업그레이드 승인 처리 흐름을 확인한다.
- `maestro_upgrade.Status` 변경값과 변경 조건을 확인한다.
- `maestro.AccountType` 변경 기준을 확인한다.
- `maestro.PlayerCount`를 즉시 변경하는지 확인한다.
- 거절 처리 시 변경되는 테이블과 로그를 확인한다.

현재 `docs/plan/project-plan.md`에 기록된 가정:

- `AccountType`만 변경
- `PlayerCount`는 변경하지 않음

검증 기준:

- 승인 SQL에 `PlayerCount` 업데이트가 포함되는지 확인한다.
- 목록 조회 시 `RegisteredAccountType`, `RequestedAccountType`을 어떻게 표시하는지 확인한다.

### 3-4. 관리자 비밀번호 검증 방식

- `login.php`에서 `admin.Password` 검증 SQL을 확인한다.
- MariaDB `PASSWORD()` 함수 사용 여부를 확인한다.
- 세션에 저장되는 관리자 식별자와 권한 정보를 확인한다.
- 실패 응답 형식과 비활성 관리자 처리 여부를 확인한다.

현재 `docs/plan/project-plan.md`에 기록된 가정:

- MariaDB `PASSWORD()` 함수로 저장/검증

검증 기준:

- `WHERE Password = PASSWORD(?)` 형태인지 확인한다.
- `ActivateStatus`, `AccountType` 같은 추가 조건이 있는지 확인한다.

### 3-5. `maestro_log` 기록 형식

- 관리자 변경 액션이 `maestro_log`에 기록되는 모든 지점을 찾는다.
- `Type` 값 목록을 확인한다.
- `Remark` 문자열 형식과 포함 정보, 날짜 형식을 확인한다.
- 로그 작성 시 관리자 ID/이름이 포함되는지 확인한다.

현재 `docs/plan/project-plan.md`에 기록된 `Type` 후보:

- `add_maestro`
- `update_maestro`
- `register_maestro`
- `update_maestro_name`
- `extension_maestro`
- `upgrade_maestro`
- `update_maestro_email`

검증 기준:

- 중복 기재된 값과 실제 미사용 값을 정리한다.
- 각 액션별 `Remark` 예시를 코드 기준으로 문서화한다.

## 4. 작업 순서

### Step 1. 파일 인벤토리 작성

- 관리자 HTML/PHP 파일 목록을 확정한다.
- 각 파일의 역할을 한 줄로 요약한다.
- AJAX 호출 URL, form action, query parameter를 찾는다.

완료 기준:

- `docs/business-rules.md`에 "기존 관리자 파일 맵" 섹션 초안 작성

### Step 2. 로그인 로직 조사

- `login.html`과 `login.php`를 연결해 인증 흐름을 추적한다.
- DB 조회 조건, 비밀번호 검증 방식, 세션 키를 기록한다.
- 신규 NextAuth Credentials Provider에서 재현해야 할 조건을 정리한다.

완료 기준:

- `admin.Password` 검증 방식 확정
- 로그인 성공/실패 조건 문서화

### Step 3. 목록 조회 로직 조사

- 전체 마에스트로 목록, 등록 신청 목록, 연장 신청 목록, 업그레이드 신청 목록 SQL을 확인한다.
- 조인 테이블, 상태 필터, 기본 정렬, 표시 컬럼을 정리한다.
- 신규 API 쿼리 설계에 필요한 컬럼 목록을 분리한다.

완료 기준:

- 신규 목록 API별 필수 SQL 조건 문서화

### Step 4. 등록/활성화 처리 조사

- `register_maestro.php`와 `activate_stage.php`의 상태 변경 로직을 확인한다.
- `maestro.ActivateStatus`, `AvailableActivateDateTime`, `maestro_log` 처리 규칙을 기록한다.
- MVP 범위에 직접 포함되지 않더라도 상세 화면과 로그 해석에 필요한 규칙을 정리한다.

완료 기준:

- 마에스트로 상태값 변경 규칙 문서화

### Step 5. 연장 승인/취소 처리 조사

- `maestro_extension_list.php`에서 목록 조회 조건을 확인한다.
- `extension_maestro.php`에서 승인/취소 처리 SQL을 순서대로 기록한다.
- 트랜잭션 사용 여부와 중복 처리 방지 조건을 확인한다.
- 신규 구현에서 보완해야 할 원자성/중복 방지 항목을 별도로 표시한다.

완료 기준:

- 연장 승인 시 날짜 계산 기준 확정
- 연장 취소 시 상태값과 로그 형식 확정

### Step 6. 업그레이드 승인/거절 처리 조사

- `maestro_upgrade_list.php`에서 목록 조회 조건을 확인한다.
- `upgrade_maestro.php`에서 승인/거절 처리 SQL을 순서대로 기록한다.
- `AccountType`, `PlayerCount`, `maestro_upgrade.Status`, `maestro_log` 변경 규칙을 확인한다.
- 신규 구현에서 보완해야 할 원자성/중복 방지 항목을 별도로 표시한다.

완료 기준:

- 업그레이드 승인 시 변경 컬럼 확정
- 업그레이드 거절 시 상태값과 로그 형식 확정

### Step 7. 비즈니스 규칙 문서 작성

`docs/business-rules.md`를 생성하고 다음 구조로 정리한다.

- 개요
- 기존 관리자 파일 맵
- 상태값 코드표
- 로그인/관리자 인증 규칙
- 마에스트로 목록 조회 규칙
- 등록/활성화 처리 규칙
- 연장 신청 조회/승인/취소 규칙
- 업그레이드 신청 조회/승인/거절 규칙
- `maestro_log` 기록 규칙
- 신규 `chocoadmin` 구현 시 반드시 지켜야 할 규칙
- 기존 코드에는 없지만 신규 구현에서 보완할 사항

완료 기준:

- Phase 1 이후 구현자가 기존 PHP 코드를 다시 열지 않아도 핵심 규칙을 확인할 수 있어야 한다.

## 5. 조사 방법

권장 검색 명령:

```bash
rg -n "maestro_log|extension_maestro|upgrade_maestro|PASSWORD|AvailableActivateDateTime|PlayerCount|ActivateStatus|AccountType|Status" /Users/jisangs/work/jinaju/git/web/mouse-typing/src/web/server/admin
```

파일별 상세 확인:

```bash
sed -n '1,240p' /Users/jisangs/work/jinaju/git/web/mouse-typing/src/web/server/admin/login.php
sed -n '1,260p' /Users/jisangs/work/jinaju/git/web/mouse-typing/src/web/server/admin/extension_maestro.php
sed -n '1,260p' /Users/jisangs/work/jinaju/git/web/mouse-typing/src/web/server/admin/upgrade_maestro.php
```

HTML 호출부 확인:

```bash
rg -n "ajax|fetch|XMLHttpRequest|form|server/admin|extension_maestro|upgrade_maestro|login.php" /Users/jisangs/work/jinaju/git/web/mouse-typing/src/web/admin
```

## 6. 완료 산출물

Phase 0 완료 시 저장소에 다음 문서가 있어야 한다.

- `docs/business-rules.md`
  - 기존 관리자 비즈니스 규칙의 최종 문서
- `docs/phase/phase0.md`
  - Phase 0 수행 계획 문서

필요하면 다음 보조 자료를 `docs/` 아래에 추가한다.

- `docs/admin-file-map.md`
  - 파일 매핑이 길어질 경우 분리
- `docs/sql-notes.md`
  - 기존 SQL 원문 기록이 길어질 경우 분리

## 7. 완료 체크리스트

- [x] `src/web/admin/` 화면 파일과 `src/web/server/admin/` 처리 파일의 연결 관계를 정리했다.
- [x] 연장 승인 시 `AvailableActivateDateTime` 계산 방식을 코드 기준으로 확정했다.
- [x] 연장 승인/취소 시 변경되는 테이블, 컬럼, 상태값, 로그 형식을 정리했다.
- [x] 업그레이드 승인 시 `PlayerCount` 갱신 여부를 코드 기준으로 확정했다.
- [x] 업그레이드 승인/거절 시 변경되는 테이블, 컬럼, 상태값, 로그 형식을 정리했다.
- [x] `admin.Password` 저장/검증 방식을 코드 기준으로 확정했다.
- [x] `maestro_log.Type` 값과 `Remark` 형식을 액션별로 정리했다.
- [x] 기존 코드에 트랜잭션/중복 처리 방지가 부족한 지점을 신규 구현 보완사항으로 표시했다.
- [x] 조사 결과를 `docs/business-rules.md`에 문서화했다.
- [x] `docs/plan/project-plan.md`의 Phase 0 체크리스트를 완료 처리할 수 있는 상태가 되었다.

## 8. 리스크와 주의사항

- 기존 PHP 코드가 트랜잭션 없이 여러 SQL을 순차 실행할 수 있다. 신규 서비스는 기존 결과는 동일하게 유지하되, 변경 액션은 트랜잭션으로 보완한다.
- 기존 코드에 중복 처리 방지 조건이 없더라도 신규 API는 `Status = 1` 조건 확인 후 변경해야 한다.
- MariaDB `PASSWORD()` 함수는 최신 인증용 해시로 적합하지 않다. Phase 0에서는 기존 검증 방식을 정확히 재현하고, 해시 업그레이드는 별도 후속 과제로 분리한다.
- 운영 DB 스키마는 임의 변경하지 않는다.
- 문서화 시 추측과 코드로 확인된 사실을 구분해 적는다.

## 9. 예상 일정

| 순서 | 작업 | 예상 소요 |
|---|---|---:|
| 1 | 파일 인벤토리와 호출 관계 정리 | 30분 |
| 2 | 로그인/인증 로직 조사 | 20분 |
| 3 | 목록 조회 SQL 조사 | 40분 |
| 4 | 등록/활성화 처리 조사 | 30분 |
| 5 | 연장 승인/취소 처리 조사 | 40분 |
| 6 | 업그레이드 승인/거절 처리 조사 | 40분 |
| 7 | `docs/business-rules.md` 작성 및 검토 | 60분 |

총 예상 소요: 약 4시간