6단계: 최소 관리자 Dashboard 완성하기

핵심 요약

이번 단계에서는 기능을 늘리지 않고 관리자가 로그인 후 사용할 화면의 뼈대만 완성합니다.

관리자 Dashboard
├── Header
├── Sidebar
│   └── Dashboard
├── 본문 영역
│   ├── 관리자 이메일
│   ├── role
│   └── 백엔드 연결 상태
└── Logout

메뉴를 여러 개 미리 만들지 않습니다. 첫 실제 메뉴는 7단계에서 하나만 추가합니다.

이번 단계의 Vibe Coding 작업 지시서

학습용 간단한 지시 설명서

05단계 인증과 API를 변경하지 말고 최소 관리자 Dashboard UI를 완성해 줘.
AdminLayout, Sidebar, Header와 Dashboard 페이지를 분리하고 Sidebar에는 Dashboard만 표시해 줘.
관리자 이메일, role과 백엔드 상태를 표시하고 데스크톱·모바일·키보드 사용성을 확인해 줘.
가짜 통계, 추가 메뉴와 외부 UI 컴포넌트 라이브러리는 넣지 마.
변경 전·후 Gate와 프런트엔드 build 결과를 보고해 줘.

정식 작업 지시서

다음 코드 블록 전체가 06단계 구현의 유일한 정식 작업 지시서입니다. 내용을 줄이거나 별도의 상세 프롬프트로 복제하지 않고 docs/work-orders/06-minimal-admin-dashboard.md에 저장합니다.

# 06단계 정식 작업 지시서

## 단계별 상세 지시
루트 AGENTS.md, 요구사항과 docs/work-orders/06-minimal-admin-dashboard.md를 먼저 읽어 줘.
05단계 로그인, 세션, 보호 경로, 새로고침과 Logout 검증 및 관련 기록이 완료되었는지 확인하고 실패하면 UI 작업을 시작하지 않는다.

애플리케이션 구현 범위는 `frontend/`이다. 정식 작업 지시서는 `docs/work-orders/`에 저장하며, 검증 기록 문서 갱신은 사용자가 WebUI 확인을 마친 뒤 별도 프롬프트로 수행한다.
백엔드, 데이터베이스, 세션 API와 쿠키 설정을 변경하지 않는다.
변경 전에 기존 컴포넌트와 경로 구조, 변경 파일과 웹 브라우저 검증 항목을 보고한다.

AdminLayout, AdminSidebar, AdminHeader와 AdminDashboardPage를 역할별로 분리한다.
Sidebar 메뉴는 Dashboard 하나만 둔다.
`docs/requirements/admin-platform.md`와 `Attachments/admin-dashboard-reference-ui.webp`를 참고하여 화면 구성과 색상 방향을 적용한다. 참고 목업을 실제 구현 완료 화면이나 고정된 픽셀 규격으로 취급하지 않는다.
Sidebar의 데스크톱 고정 상태와 모바일 열기·닫기 상태, 현재 메뉴, 마우스 올림 상태와 키보드 포커스가 서로 구분되게 구현한다.
메뉴 선택 후 공통 AdminLayout 안의 본문 영역에 해당 경로의 페이지가 표시되는 구조를 확정한다.
하위 메뉴를 추가하지는 않지만 07단계 이후 펼침·접힘 구조를 수용할 수 있도록 책임과 상태 경계를 정한다.
상태 책임의 세부 배치는 작성자의 구현 의도에 맞게 변경할 수 있다. 접근성과 기존 인증 흐름을 보존하면서 변경 이유를 기록한다.
React Router의 `Outlet`을 사용하여 07단계 이후 추가되는 중첩 경로의 페이지를 공통 `AdminLayout` 본문에 표시할 수 있게 한다.
현재 세션에서 받은 관리자 이메일과 role을 표시한다.
보호된 백엔드 상태는 실제 API 결과에 따라 처리 중, 성공과 오류를 구분한다.
Logout 동작을 유지한다.
데스크톱과 지정한 모바일 폭에서 사용할 수 있는 화면 구성으로 만든다.
키보드 포커스, `nav` 레이블, `aria-current`와 오류 메시지를 확인한다.

가짜 통계, 동작하지 않는 메뉴, 외부 UI 컴포넌트 라이브러리와 Text Tool을 미리 추가하지 않는다. 프로젝트에 이미 설치된 Lucide 아이콘은 새 의존성을 추가하지 않는 범위에서 사용할 수 있다.
인증 실패를 프런트엔드에서 우회하지 않는다.

변경 전·후 Gate, 프런트엔드 `typecheck`와 `build`, 로그인, 새로고침, Dashboard와 Logout을 검증한다.
`Console`, `Network`, 키보드와 모바일 결과는 완료 보고에 통과, 실패와 미수행으로 구분한다. 이 작업에서는 검증 기록 문서를 갱신하지 않는다.
회귀나 접근성 실패가 남으면 07단계 메뉴를 추가하지 않는다.

## 완료 보고 형식

- 생성하거나 변경한 파일
- 실행한 명령과 실제 결과
- 통과, 실패와 미수행 검증
- 요구사항별 구현 내용과 변경 이유
- 남은 제한, 위험과 다음 단계 진행 가능 여부

정식 작업 지시서 저장과 실행 순서

다음 순서는 Windows 관리 PC의 VS Code에서 Remote SSH로 개발 서버에 연결한 상태를 기준으로 합니다. 앞 단계가 실패했거나 기존 변경과 충돌하면 다음 번호로 넘어가지 않습니다.

1. 프로젝트와 이전 단계 상태 확인

VS Code의 원격 터미널에서 프로젝트 루트로 이동하고 현재 상태를 확인합니다.

cd /home/apple2ne1/projects/vibe-coding-platform
pwd
git status --short

pwd에 /home/apple2ne1/projects/vibe-coding-platform이 표시되고 git status --short 다음에 아무 변경 목록 없이 셸 프롬프트가 다시 나타나면 프로젝트 경로와 깨끗한 작업 트리를 확인한 것입니다.

AI 코딩 에이전트에게 변경을 맡기기 전에 이전 단계의 완료 기록과 현재 사용자 변경을 구분합니다. 예상하지 못한 변경이 있으면 보존 방법을 먼저 결정합니다.

2. 정식 작업 지시서 저장

VS Code에서 docs/work-orders/06-minimal-admin-dashboard.md를 만들고, 위 정식 작업 지시서 코드 블록의 내용을 빠짐없이 저장합니다. 간단한 지시서와 정식 작업 지시서를 서로 다른 실행 Prompt로 보내지 않습니다.

mkdir -p docs/work-orders
touch docs/work-orders/06-minimal-admin-dashboard.md

VS Code의 Explorer에서 docs/work-orders 폴더를 펼치면 새로 만든 06-minimal-admin-dashboard.md 파일을 확인할 수 있습니다.

VS Code의 Explorer에서 docs/work-orders/06-minimal-admin-dashboard.md를 선택해 열고, 위 정식 작업 지시서 코드 블록 전체를 복사해 붙여넣은 뒤 Ctrl+S로 저장합니다.

저장한 다음 VS Code 원격 터미널에서 파일 내용과 변경 사항을 확인합니다.

test -s docs/work-orders/06-minimal-admin-dashboard.md
git diff -- docs/work-orders/06-minimal-admin-dashboard.md

test -s 다음에 오류 없이 셸 프롬프트가 표시되면 파일이 비어 있지 않은 것입니다. 새 파일을 아직 Git에 추가하지 않았다면 git diff -- 파일명에 내용이 표시되지 않을 수 있으므로, VS Code 편집기에서도 정식 작업 지시서 전체가 저장되었는지 확인합니다.

저장한 파일에 목표, 허용 범위, 제외 범위, 완료 조건, 검증과 중단 조건이 모두 포함되어 있는지 직접 확인합니다.

3. 작업 지시서 Git 기준점 기록

위 정식 작업 지시서 코드 블록 전체를 지정한 파일에 저장한 뒤, 해당 파일만 먼저 커밋하여 구현 기준을 고정합니다.

cd /home/apple2ne1/projects/vibe-coding-platform
git status --short
test -s docs/work-orders/06-minimal-admin-dashboard.md
git add -- docs/work-orders/06-minimal-admin-dashboard.md
git diff --cached --name-only
git diff --cached --check
git commit -m "docs: add 06 step work order"

스테이징 파일 목록에 docs/work-orders/06-minimal-admin-dashboard.md 하나만 표시되고 git diff --cached --check가 오류 없이 종료되면 기준점 커밋을 진행합니다. 다른 파일이 표시되거나 검사가 실패하면 커밋하지 않고 Codex에 표시된 파일과 오류를 전달해 수정을 요청합니다.

커밋 식별자와 함께 1 file changed 및 새 파일 생성 결과가 표시되고 셸 프롬프트가 다시 나타나면 작업 지시서 기준점 기록이 완료된 것입니다.

4. Codex CLI 실행과 공통 프롬프트 전달

프로젝트 루트에서 Codex CLI를 실행합니다.

codex -C /home/apple2ne1/projects/vibe-coding-platform

Codex CLI에 단계별 구현 조건을 다시 길게 복사하지 않고 다음 공통 Prompt를 전달합니다. 선행 조건이나 기록이 맞지 않아도 사용자가 원인을 직접 판정하지 않습니다. Codex가 안전하게 해결할 수 있는 문제는 기존 작업을 보존하면서 바로잡고 다시 검사합니다.

루트 AGENTS.md, docs/requirements/admin-platform.md와
docs/work-orders/06-minimal-admin-dashboard.md를 먼저 읽어 줘.

이 문서는 비전공자가 따라 하는 단계별 실습이야.
사용자에게 Git 상태, 문서 충돌이나 오류 원인을 직접 판정하게 하지 마.

먼저 다음 내용을 확인해 줘.

1. 현재 단계와 목표
2. Git 상태와 보존해야 할 기존 변경
3. 이전 단계 완료 여부와 문서 간 현재 단계 기록
4. 생성하거나 변경할 파일
5. 실행할 자동 검사와 사용자가 확인할 WebUI 또는 대체 검사
6. 위험, 충돌과 중단 조건

선행 조건이나 단계 기록이 맞지 않으면 보고만 하고 멈추지 말고 원인을 확인해 줘.
현재 코드와 확인된 검증 기록으로 이전 단계 완료를 확인할 수 있는데 README.md,
docs/requirements/admin-platform.md, docs/development-guides/local-development.md 또는
docs/development-guides/webui-gate.md의 단계 기록만 오래되었거나 서로 다르면,
요구사항과 기존 기록을 삭제하지 말고 실제 상태에 맞게 서로 일치시킨 뒤 다시 검사해 줘.

누락된 문서 생성, 잘못된 경로·파일명, 안전한 설정 수정처럼 현재 단계 범위에서 복구할 수 있는 문제는
기존 사용자 변경을 보존하면서 직접 복구하고 관련 검사를 다시 실행해 줘.
파일 삭제, 기존 변경 덮어쓰기, Git Reset, Secret 입력, sudo 권한이나 사용자의 실제 WebUI 확인처럼
사용자 결정이나 조작이 꼭 필요한 일은 임의로 진행하지 마.
그 경우에는 사용자가 해야 할 행동 한 가지만 쉬운 문장으로 설명하고, 복사할 명령이 있으면 코드 블록 하나로 제공한 뒤 결과를 기다려 줘.

선행 조건이 해결되면 별도의 재요청을 기다리지 말고 정식 작업 지시서의 허용 범위만 구현해 줘.
제외 범위와 다음 단계 기능은 추가하지 마.
실행하지 못한 검사는 통과로 기록하지 말고 필수 검사 실패를 완료로 판정하지 마.

자동 검사가 끝나면 사용자가 직접 확인해야 할 WebUI 또는 대체 검사만 번호가 있는 짧은 목록으로 안내해 줘.
검증 결과 기록, 스테이징과 커밋은 사용자가 실제 확인을 마친 뒤 별도 Prompt로 요청할 것이므로 지금 실행하지 마.

마지막에는 비전공자도 이해할 수 있게 다음 내용만 보고해 줘.

1. 자동으로 해결한 문제
2. 구현한 내용과 변경 파일
3. 통과·실패·미수행 검사
4. 사용자가 지금 확인할 항목
5. 다음 절차 진행 가능 여부

코드 블록 전체를 Codex CLI에 붙여 넣고 Enter를 누릅니다. 다음 화면처럼 현재 단계와 목표부터 위험·충돌·중단 조건까지 공통 프롬프트가 전달되었는지 확인합니다.

Codex가 구현과 자동 검사를 마치면 통과·실패·미수행 검사와 사용자가 확인할 WebUI 항목을 보고합니다. 스테이징과 커밋은 실행하지 않았습니다라는 안내와 다음 절차 진행 가능 여부를 확인한 뒤 다음 단계로 이동합니다.

5. Codex의 자동 확인·복구 후 구현

위 프롬프트는 사전 확인에서 안전하게 해결할 수 있는 문제를 발견하면 Codex가 기존 작업을 보존하면서 직접 복구하고 다시 검사한 뒤 구현을 계속하도록 요청합니다. 사용자는 Git 상태, 문서 간 단계 충돌과 명령 오류를 직접 판정하지 않습니다.

Codex가 사용자 조작이 필요한 문제를 발견하면 한 번에 한 가지 행동만 안내합니다. 안내된 명령이나 WebUI 확인을 수행한 뒤 결과 전체를 같은 Codex CLI 대화에 붙여 넣습니다. Codex가 다음 절차 진행 가능이라고 보고하면 아래 구현 결과 확인으로 이동합니다. 진행 불가라고 보고하면 임의로 다음 단계로 넘어가지 않고, 마지막 보고 전체를 그대로 Codex에 다시 전달하여 해결을 계속 요청합니다.

구현 결과 WebUI 실행과 확인

06단계는 05단계의 로그인·세션·보호 Route를 변경하지 않고 관리자 화면 구성을 완성하는 단계입니다. 서비스 준비 → 로그인 → 데스크톱 화면 → 모바일·키보드 조작 → 새로고침·로그아웃 순서로 확인합니다.

WebUI가 열리지 않거나 기능이 동작하지 않으면 자동 검사만으로 완료 처리하지 않습니다. 백엔드와 프런트엔드 터미널의 오류 및 웹 브라우저 개발자 도구의 Console·Network 결과를 Codex에 전달하여 해결합니다. 실제 암호, SESSION_SECRET, 운영 환경의 세션 ID와 쿠키 값은 전달하지 않습니다.

1. MySQL과 환경 변수 준비 상태 확인

05단계 마지막에 중지한 MySQL을 다시 시작하고 SESSION_SECRET 저장 여부를 확인합니다. 다음 명령은 SESSION_SECRET의 실제 값을 출력하지 않습니다.

cd /home/apple2ne1/projects/vibe-coding-platform
docker compose up -d mysql
docker compose ps mysql
grep -q '^SESSION_SECRET=.' backend/.env && echo "SESSION_SECRET 저장 확인 완료" || echo "SESSION_SECRET 확인 필요"

MySQL의 상태가 healthy이고 SESSION_SECRET 저장 확인 완료가 표시되어야 합니다. starting이면 잠시 기다린 뒤 docker compose ps mysql을 다시 실행합니다. unhealthy, exited 또는 SESSION_SECRET 확인 필요가 표시되면 다음 단계로 넘어가지 않고 출력 결과를 Codex에 전달합니다.

2. 백엔드와 프런트엔드 다시 실행

VS Code에서 터미널을 두 개 열고 각각 다음 명령을 실행합니다.

# 터미널 1: 백엔드
cd /home/apple2ne1/projects/vibe-coding-platform/backend
npm run dev

# 터미널 2: 프런트엔드
cd /home/apple2ne1/projects/vibe-coding-platform/frontend
npm run dev

백엔드 터미널에 Backend listening on http://127.0.0.1:3000이 표시되고, 프런트엔드 터미널에 http://서버-IP:5173 형식의 Vite 접속 주소가 표시되어야 합니다. 오류가 나타나면 WebUI 확인을 시작하지 않고 실제 인증정보를 제외한 오류 출력을 Codex에 전달합니다.

3. 로그인과 데스크톱 관리자 화면 확인

Windows 관리 PC의 웹 브라우저에서 http://서버-IP:5173을 엽니다. 이 문서의 검증 환경에서는 http://192.168.1.231:5173을 사용합니다.

04단계에서 준비한 공개 실습용 관리자 이메일 admin@example.test와 암호 vibe-admin-04-demo로 로그인한 뒤 다음 항목을 확인합니다.

1. /admin으로 이동하고 로그인 화면으로 되돌아가지 않습니다.
2. Header, Sidebar와 본문 영역이 서로 겹치지 않고 구분됩니다.
3. Sidebar에는 동작하는 Dashboard 항목 하나만 표시됩니다.
4. 현재 관리자 이메일과 role이 실제 세션 정보와 맞게 표시됩니다.
5. 백엔드 연결 상태가 무조건 성공으로 고정되지 않고 실제 결과에 따라 표시됩니다.
6. 가짜 통계, 동작하지 않는 메뉴와 다음 단계 기능이 미리 추가되지 않았습니다.

4. 모바일 화면과 키보드 조작 확인

웹 브라우저 개발자 도구의 기기 화면 전환 기능을 사용하여 모바일 너비에서도 확인합니다. 특정 기기 이름보다 화면이 좁아졌을 때 실제로 사용할 수 있는지를 기준으로 판단합니다.

먼저 사이드바가 닫힌 상태에서 제목, 본문 카드, 메뉴 버튼과 Logout이 화면 안에 표시되는지 확인합니다.

메뉴 버튼을 선택하면 사이드바가 열리고 현재 메뉴인 Dashboard가 구분되어 표시되어야 합니다.

1. 메뉴 열기 버튼으로 Sidebar를 열고 닫을 수 있습니다.
2. Sidebar가 본문을 읽거나 조작할 수 없게 가리지 않습니다.
3. 메뉴를 선택하면 모바일 메뉴가 의도한 방식으로 닫히고 본문이 표시됩니다.
4. Tab 키로 메뉴, 주요 버튼과 Logout에 차례대로 이동할 수 있습니다.
5. 현재 메뉴 표시, 마우스 올림 상태와 키보드 포커스가 서로 구분됩니다.
6. 키보드만으로 메뉴 선택과 로그아웃을 실행할 수 있습니다.

화면이 겹치거나 가로 스크롤 때문에 주요 기능을 사용할 수 없고, 키보드 포커스가 보이지 않으면 완료로 판정하지 않습니다.

모바일 화면에서도 Logout을 선택하면 로그인 화면으로 이동하고 Network의 logout 요청이 성공 상태인 2xx로 응답하는지 확인합니다.

다시 로그인한 뒤 관리자 화면이 표시되고 Network의 login과 me 요청이 성공했는지 확인합니다. me가 캐시 검증 결과인 304로 표시되는 것은 오류가 아닙니다.

5. 인증 흐름 유지와 종료 확인

관리자 화면에서 F5를 눌러 새로 고친 뒤 /admin 화면과 로그인 상태가 유지되는지 확인합니다. 개발자 도구에서는 다음 항목을 확인합니다.

1. Console에 이번 화면 구현으로 발생한 오류가 없습니다.
2. Network에서 /api/auth/me와 보호된 백엔드 요청이 의도한 상태로 응답합니다.
3. Logout을 선택하면 로그인 화면으로 이동합니다.
4. 로그아웃 뒤 /admin을 다시 직접 열면 보호된 화면이 아니라 로그인 화면으로 이동합니다.

Logout을 선택한 직후 로그인 화면이 표시되고 Network의 logout 요청이 200으로 응답하는지 확인합니다.

인증 흐름이 계속 정상인지 확인하려면 공개 실습용 관리자 이메일과 암호를 다시 입력합니다.

재로그인 뒤 /admin 화면이 다시 표시되고 Network에서 login 요청이 200, me 요청이 성공 상태인지 확인합니다. me의 304는 캐시된 응답을 다시 사용해도 되는지 확인한 결과이므로 인증 오류가 아닙니다.

6. WebUI 검증 완료

위 확인까지 마쳤다면 사용자가 수행할 06단계 WebUI 검증은 끝난 것입니다. 다음 절에서 실습에 사용한 프로세스를 순서대로 중지합니다.

7. 실습 프로세스 중지

WebUI 확인이 끝나면 프런트엔드 → 백엔드 → MySQL 순서로 중지합니다. VS Code의 터미널 목록에서 각 프로세스를 실행한 터미널을 하나씩 선택합니다.

1. 프런트엔드 중지

프런트엔드를 실행한 터미널을 선택하고 q를 입력한 뒤 Enter를 누릅니다. 또는 해당 터미널에서 Ctrl+C를 누릅니다. Vite 실행 메시지 아래에 셸 프롬프트가 다시 표시되면 프런트엔드가 중지된 것입니다.

2. 백엔드 중지

백엔드를 실행한 터미널을 선택하고 Ctrl+C를 누릅니다. Backend listening on http://127.0.0.1:3000 같은 실행 메시지 아래에 셸 프롬프트가 다시 표시되면 백엔드의 tsx watch 프로세스가 중지된 것입니다.

다음 화면처럼 프런트엔드 터미널에는 q 입력 뒤 셸 프롬프트가, 백엔드 터미널에는 ^C 뒤 셸 프롬프트가 표시되면 두 프로세스가 모두 중지된 것입니다.

3. 프런트엔드와 백엔드 포트 확인

별도 터미널에서 3000번과 5173번 포트의 수신 프로세스가 남아 있지 않은지 확인합니다.

if ss -ltn | grep -Eq ':(3000|5173)\b'; then
  echo "확인 필요: 3000 또는 5173 포트의 프로세스가 아직 실행 중입니다"
else
  echo "백엔드와 프런트엔드가 중지되었습니다"
fi

백엔드와 프런트엔드가 중지되었습니다가 표시되면 다음 단계로 이동합니다.

확인 필요가 표시되면 다른 프로세스를 임의로 강제 종료하지 않습니다. VS Code의 터미널 목록에서 이번 실습에 사용한 백엔드·프런트엔드 터미널을 찾아 앞에서 안내한 종료 키를 다시 사용한 뒤 포트를 재확인합니다.

4. MySQL 컨테이너 중지

백엔드와 프런트엔드가 중지된 뒤 MySQL은 데이터를 유지하면서 서비스만 중지합니다.

cd /home/apple2ne1/projects/vibe-coding-platform
docker compose stop mysql
docker compose ps mysql

Stopped가 표시되고 docker compose ps mysql의 실행 목록이 비어 있으면 MySQL 컨테이너가 중지된 것입니다.

상태를 자세히 확인하려면 다음 명령을 실행합니다.

docker compose ps -a mysql

STATUS가 Exited로 표시되면 정상적으로 중지된 것입니다. docker compose stop mysql은 이름 있는 볼륨의 데이터를 유지합니다. 볼륨을 삭제하는 docker compose down -v는 실행하지 않습니다.

8. Codex에 검증 결과 기록 요청

사용자가 위 절차의 WebUI 또는 대체 검사를 마친 뒤에는 여러 기록 파일을 직접 열어 맞추지 않습니다. 검증 결과가 성공이든 실패든 다음 프롬프트 하나를 Codex CLI에 전달하여 확인된 결과와 단계 상태를 정리합니다.

06단계 구현과 검증은 앞 절차에서 완료했어. 검증을 다시 실행하지 말고 현재 작업 기록과 실제 결과만 확인해 줘.
webui-gate.md에는 데스크톱·모바일·키보드와 보호 경로 결과를, local-development.md에는 Dashboard 확인 방법을, README.md에는 완성한 화면 구성·Sidebar·Header 범위를 기록해 줘. 화면 기준이 실제로 변경된 경우에만 admin-platform.md에 이유를 기록하고 변경되지 않았다면 수정하지 마.
실행하지 않은 검사는 통과로 기록하지 말고 기존 기록을 삭제하거나 덮어쓰지 마.
현재 코드와 확인된 결과를 기준으로 README.md, docs/requirements/admin-platform.md,
docs/development-guides/local-development.md와 docs/development-guides/webui-gate.md의
현재 단계와 완료 상태가 서로 다른지도 확인해 줘.
기록만 오래되었거나 충돌하면 요구사항 자체를 바꾸지 말고 실제 상태에 맞게 일치시켜 줘.

실패나 미수행 결과가 있으면 완료로 만들지 말고 원인과 다음 해결 방법을 기록해 줘.
안전하게 해결할 수 있는 기록 누락이나 충돌은 직접 수정하고 다시 확인해 줘.
사용자 조작이 꼭 필요하면 사용자가 해야 할 행동 한 가지만 쉬운 문장으로 알려 줘.

마지막에는 비전공자도 이해할 수 있게 다음 내용만 보고해 줘.

1. 변경한 파일
2. 파일별로 기록한 실제 결과
3. 현재 단계 완료 기록이 서로 일치하는지
4. 남은 실패·미수행·확인 불가 항목
5. 다음 단계 진행 가능 여부

스테이징과 커밋은 실행하지 마.

코드 블록 전체를 Codex CLI에 붙여 넣고 Enter를 누릅니다. 다음 화면처럼 변경할 기록 파일, 완료 상태 일치 여부와 보고 형식까지 프롬프트가 전달되었는지 확인합니다.

완료 보고에서는 관련 문서가 모두 06단계 완료로 일치하는지, 남은 실패·미수행·확인 불가 항목이 있는지와 07단계 진행 가능 여부를 확인합니다. 스테이징과 커밋은 실행하지 않았습니다라는 안내가 표시되어야 다음 절에서 사용자가 직접 변경 내용을 검토할 수 있습니다.

9. 최종 변경 검토와 커밋

Codex의 완료 보고를 확인한 뒤 사용자가 이번 단계의 변경 파일을 스테이징합니다. Windows 관리 PC에서는 자동 검사 결과와 스테이징 파일 목록을 확인합니다.

cd /home/apple2ne1/projects/vibe-coding-platform
git status --short
git add -- docs/work-orders/06-minimal-admin-dashboard.md frontend/src README.md docs/development-guides/local-development.md docs/development-guides/webui-gate.md
git --no-pager diff --cached --name-only
git diff --cached --check

먼저 git status --short에서 이번 단계에서 변경하거나 추가한 파일만 표시되는지 확인합니다. 빌드 결과처럼 기존 파일이 삭제되고 새 해시 이름의 파일이 추가된 경우에는 Codex의 완료 보고와 실제 빌드 결과가 일치하는지도 확인합니다.

스테이징 파일 목록이 Codex의 완료 보고와 같고 git diff --cached --check가 오류 없이 종료되면 단계 결과를 커밋합니다. 목록이 다르거나 검사가 실패하면 커밋하지 않고 Codex에 출력 결과를 전달해 수정을 요청합니다.

화면 기준이 실제로 변경되어 docs/requirements/admin-platform.md도 수정했다면 위 git add -- 명령 끝에 해당 경로를 추가합니다. git --no-pager diff --cached --name-only에 이번 단계의 변경 파일만 표시되고, git diff --cached --check 다음에 오류 없이 셸 프롬프트가 다시 나타나는지 확인합니다.

git commit -m "feat: complete 06 step"

커밋 식별자와 변경된 파일 수가 표시되고 셸 프롬프트가 다시 나타나면 06단계 커밋이 완료된 것입니다.

문서·검증만 수행한 단계라면 Codex가 완료 보고에 제시한 docs:, test: 또는 chore: 메시지를 사용합니다. 필수 검사가 실패하면 커밋으로 완료 상태를 만들거나 다음 단계 작업 지시서를 실행하지 않습니다.

정식 작업 지시서 해설

이 절은 새로운 작업을 지시하거나 명령을 다시 실행하는 단계가 아닙니다. 정식 작업 지시서 실행, 구현 결과 검증, 검증 기록 갱신과 커밋까지 끝낸 뒤 06단계의 목적과 구현 원리를 되짚는 복습용 해설입니다.

앞에서 실제로 확인한 결과를 기준으로 화면 구성 요소를 나눈 이유, 05단계의 인증 구조가 화면과 연결되는 과정, 반응형 화면과 접근성 요구사항 및 완료 판정 기준을 설명합니다. 이후 단계의 기능을 06단계에서 이미 구현한 것처럼 확대하여 해석하지 않습니다.

1. 이번 단계에서 만든 결과

이번 단계의 목표는 05단계에서 만든 로그인·세션·보호 경로를 변경하지 않고, 로그인한 관리자가 사용할 최소 관리자 화면 구성을 만드는 것입니다. 구현 범위는 프런트엔드이며, 백엔드·데이터베이스·세션 API와 쿠키 설정은 변경하지 않았습니다.

화면은 Header, Sidebar와 본문 영역으로 나누고 데스크톱과 모바일에서 사용할 수 있게 했습니다. Sidebar에는 실제로 동작하는 Dashboard 항목 하나만 두었습니다. 가짜 통계, 동작하지 않는 메뉴, 외부 UI 라이브러리와 다음 단계의 Text Tool을 미리 추가하지 않은 이유는 현재 동작 범위와 이후 변경 범위를 명확히 구분하기 위해서입니다.

06단계에서 채워진 주요 폴더와 파일

vibe-coding-platform/
├── docs/
│   └── work-orders/
│       └── 06-minimal-admin-dashboard.md
└── frontend/
    └── src/
        ├── <Header와 Sidebar 화면 구성의 실제 소스 파일>
        ├── <Dashboard 본문 화면의 실제 소스 파일>
        └── <반응형 화면과 접근성 스타일 파일>

06단계의 애플리케이션 구현은 frontend/src/에 한정되며, 정식 작업 지시서와 검증 기록은 앞에서 지정한 문서에 별도로 반영됩니다. Header, Sidebar와 Dashboard는 역할별 컴포넌트로 분리하되 실제 파일명과 배치는 기존 프로젝트 구조와 구현 결과를 따릅니다.

2. 참고 목업과 실제 구현의 관계

docs/requirements/admin-platform.md와 Attachments/admin-dashboard-reference-ui.webp는 화면 구성과 색상 방향을 정하는 참고 자료입니다. 참고 이미지를 완성 화면이나 고정된 픽셀 규격으로 그대로 복제하는 것이 목표는 아닙니다.

실제 구현에서는 기존 인증 흐름, 접근성, 데스크톱·모바일 사용성과 이후 메뉴 확장 가능성을 우선합니다. 참고 자료와 다른 부분이 생기면 임의로 숨기지 않고, 변경 이유와 실제 확인 결과를 기록하여 화면 기준이 왜 달라졌는지 알 수 있게 합니다.

3. 화면 구성 요소를 나눈 이유

관리자 화면을 하나의 큰 컴포넌트로 만들지 않고 역할에 따라 나누었습니다.

• AdminLayout은 Header, Sidebar와 본문이 배치되는 공통 틀입니다.
• AdminHeader는 화면 제목, 현재 관리자 정보와 Logout을 표시합니다.
• AdminSidebar는 현재 메뉴 표시와 데스크톱·모바일 메뉴 동작을 담당합니다.
• AdminDashboardPage는 공통 화면 구성 안에서 Dashboard 본문만 담당합니다.

이렇게 역할을 나누면 이후 페이지가 추가되어도 Header와 Sidebar를 반복해서 만들 필요가 없습니다. 현재 메뉴, 모바일 Sidebar 열기·닫기와 이후 하위 메뉴의 펼침·접힘 상태도 어느 구성 요소가 관리할지 구분할 수 있습니다. 구현 구조는 작성자의 의도에 따라 조정할 수 있지만 기존 인증 흐름과 접근성을 보존하고 변경 이유를 남겨야 합니다.

4. 보호 경로와 본문 전환 원리

프런트엔드가 시작되면 기존 인증 흐름으로 현재 사용자를 확인합니다. 로그인하지 않은 사용자가 /admin을 열면 로그인 화면으로 이동하고, 인증된 관리자가 접속하면 공통 AdminLayout을 표시합니다. React Router의 Outlet은 공통 화면 구성을 유지하면서 현재 주소에 해당하는 페이지만 본문 영역에 표시하는 자리입니다.

06단계에는 Dashboard 하나만 연결하지만, 이 구조를 이용하면 07단계 이후 새로운 중첩 경로를 추가해도 공통 화면 구성을 다시 만들지 않고 본문만 전환할 수 있습니다.

프런트엔드의 보호 경로는 관리자 화면 노출과 이동 흐름을 제어하는 사용자 경험 장치입니다. 데이터와 관리자 API를 보호하는 실제 보안 경계는 백엔드의 requireAdmin 미들웨어입니다. 따라서 프런트엔드 검사를 우회하더라도 백엔드가 비로그인 사용자와 권한이 없는 사용자의 요청을 거부해야 합니다.

5. 관리자 정보와 백엔드 상태의 출처

세션에는 userId만 저장됩니다. 화면에 표시되는 관리자 이메일과 role은 세션에 문자열로 저장해 둔 값을 직접 읽는 것이 아니라, GET /api/auth/me가 세션의 userId를 기준으로 현재 MySQL 사용자를 확인한 뒤 반환한 안전한 사용자 정보입니다.

보호된 백엔드 상태도 성공 문자열로 고정하지 않고 실제 구현에서 연결한 보호 API의 요청 상태를 사용합니다. 요청 중에는 처리 중 상태, 정상 응답에는 성공 상태, 요청 실패에는 오류 상태를 구분합니다. 특정 엔드포인트와 응답 형식은 완료된 실제 구현과 검증 기록을 기준으로 하며, 해설만으로 확인하지 않은 API가 존재한다고 가정하지 않습니다.

6. 데스크톱·모바일과 접근성 요구사항

데스크톱에서는 Sidebar가 고정된 상태로 본문과 함께 표시됩니다. 모바일에서는 좁은 화면에서도 본문을 사용할 수 있도록 메뉴 버튼으로 Sidebar를 열고 닫고, 메뉴를 선택하면 의도한 방식으로 닫힌 뒤 본문을 표시합니다. 화면이 겹치거나 가로 스크롤 때문에 주요 기능을 사용할 수 없어서는 안 됩니다.

현재 메뉴, 마우스 올림 상태와 키보드 포커스는 서로 다른 상태입니다. 색상이나 테두리 등으로 구분해야 사용자가 현재 위치와 다음에 조작할 항목을 알 수 있습니다. aria-current는 보조 기술에 현재 메뉴를 알려 주며, 접근 가능한 메뉴 이름은 화면을 보지 않고 탐색할 때 항목의 역할을 전달합니다. Tab 키와 키보드만으로 메뉴와 Logout에 이동하여 실행할 수 있어야 합니다.

7. 검증 항목이 의미하는 것

앞의 WebUI 절차와 자동 검사는 서로 다른 범위를 확인합니다. 실제 실행 명령과 결과가 완료 보고에 있는 항목만 통과로 인정하며, 실패하거나 실행하지 않은 항목을 해설만으로 통과한 것으로 간주하지 않습니다.

• 프런트엔드 typecheck는 컴포넌트 속성, 함수 인수와 상태 값 등의 TypeScript 자료형 사용이 올바른지 검사합니다.
• 프런트엔드 build는 배포용 결과물을 실제로 생성할 수 있는지 검사합니다.
• 변경 전·후 WebUI Gate는 05단계 인증 흐름이 화면 변경으로 깨지지 않았는지 비교합니다.
• 로그인과 새로고침 확인은 서버 세션을 이용해 인증 상태와 /admin 화면을 복원하는지 검사합니다.
• 로그아웃 뒤 /admin 직접 접근 확인은 프런트엔드 보호 경로가 비로그인 화면 흐름을 유지하는지 검사합니다.
• 관리자 이메일·role과 백엔드 상태 확인은 화면이 임의의 예시 값이나 항상 성공인 상태를 표시하지 않는지 검사합니다.
• 데스크톱·모바일·키보드 확인은 화면 배치, 메뉴 동작, 포커스 표시와 주요 기능의 접근성을 검사합니다.
• Console과 Network 확인은 화면 오류가 없는지와 실제 인증·보호 API 요청이 의도한 상태로 응답하는지 검사합니다.

화면이 보이더라도 필수 자동 검사, 인증 회귀 검사 또는 접근성 확인이 실패하면 06단계를 완료한 것으로 처리하지 않습니다. 오류를 해결하고 다시 확인한 뒤에만 07단계로 진행합니다.

8. 현재 제한과 다음 단계의 경계

06단계의 Sidebar에는 실제로 동작하는 Dashboard 메뉴 하나만 있습니다. 여러 메뉴와 하위 메뉴를 표시하는 기능은 아직 포함하지 않습니다. 07단계에서는 이번 단계에서 만든 공통 화면 구성과 인증 경계를 유지하면서 첫 번째 실제 기능인 Text Tool 메뉴와 페이지를 추가합니다.

Text Tool의 보호 API, 입력 처리와 결과 표시는 07단계의 구현 범위입니다. 06단계에서는 이를 미리 만들지 않고, 새 메뉴와 중첩 페이지를 수용할 화면 구성 요소와 상태 책임만 준비했습니다.

9. Codex가 갱신하는 단계 산출물과 검증 기록

앞의 8. Codex에 검증 결과 기록 요청에서 Codex는 사용자가 확인한 WebUI 결과와 자동 검사 결과를 실제 상태에 맞게 관련 문서에 기록합니다. 정식 작업 지시서에는 구현 범위와 완료 조건을 유지하고, 검증 뒤의 기록 작업은 별도 프롬프트로 분리합니다.

webui-gate.md에는 데스크톱·모바일·키보드 조작과 보호 경로의 실제 결과를 기록합니다. local-development.md에는 기존 실행 명령을 유지하면서 로그인 후 /admin을 확인하는 순서, 보호된 백엔드 상태와 반응형 화면의 검증 경로를 추가합니다. 화면 기준이 실제로 변경된 경우에만 docs/requirements/admin-platform.md에 이유를 기록합니다.

필수 검증이 모두 통과한 경우에만 루트 README.md에 06단계의 완료 범위와 07단계 진행 가능 여부를 기록합니다. 실패·미수행·확인 불가 항목이 있으면 완료로 기록하지 않고 현재 상태와 다음 해결 방법을 남깁니다.

다음 단계

다음 글에서는 Sidebar에 첫 번째 실제 메뉴인 Text Tool 하나를 추가합니다.

• 이전: 5단계: 세션과 보호된 관리자 경로 만들기
• 다음: 7단계: 첫 번째 Sidebar 메뉴 추가하기

참고 자료 및 출처

• React Router Routing: 선언형 경로, 중첩 경로와 Outlet 구성의 기준 자료. 확인일: 2026-08-26
• Lucide for React: React 컴포넌트 가져오기, 크기·색상·선 굵기 조정과 Tree Shaking 안내. 확인일: 2026-08-26
• Lucide License: ISC License와 라이선스 고지 조건 확인. 확인일: 2026-08-26