chocoadmin/docs/phase/phase0.md

Phase 0 작업 계획

1. 목적

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

Phase 0의 목표는 기존 mouse-typing 관리자 기능의 비즈니스 규칙을 확인하고, 신규 choco-admin에서 동일하게 재현해야 할 규칙을 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 파일의 호출 관계를 확인한다.
• 각 화면의 목록 조회 조건, 검색 조건, 정렬 기준, 상태 필터를 확인한다.
• 신규 choco-admin의 화면/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 기록 규칙
• 신규 choco-admin 구현 시 반드시 지켜야 할 규칙
• 기존 코드에는 없지만 신규 구현에서 보완할 사항

완료 기준:

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

5. 조사 방법

권장 검색 명령:

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

파일별 상세 확인:

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 호출부 확인:

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. 완료 체크리스트

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