3단계: Express API 연결하기

핵심 요약

이전 2단계에서는 React 안에 미리 적어 둔 임시 관리자 값과 사용자가 입력한 값을 비교해 로그인 성공 여부를 판단했습니다. 이번 단계에서는 이 판정 작업을 React가 아니라 Express 백엔드가 담당하도록 옮깁니다.

웹 브라우저 :5173
        ↓
React 로그인 Form
        ↓
POST /api/auth/login
        ↓
Vite 프록시
        ↓
Express :3000
        ↓
JSON 응답
        ↓
관리자 대시보드 또는 오류 표시

웹 브라우저는 계속 5173번 포트로만 접속합니다. 3000번 포트는 Vite 개발 서버의 프록시가 API 요청을 Express 백엔드로 전달할 때 사용합니다.

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

학습용 간단한 지시 설명서

02단계 기능을 보존하면서 Express 5와 TypeScript 백엔드를 추가해 줘.
GET /api/health와 POST /api/auth/login만 만들고 Vite /api 프록시로 연결해 줘.
프런트엔드의 임시 암호 비교는 제거하고 로그인 API의 처리 중, 성공와 오류 상태를 표시해 줘.
MySQL, 세션, Redis, Nginx와 Docker는 추가하지 마.
변경 전·후 공통 WebUI Gate, 백엔드 typecheck, 프런트엔드 build, curl과 웹 브라우저 `Network` 결과를 보고해 줘.

정식 작업 지시서

다음 코드 블록 전체가 docs/work-orders/03-express-api-connection.md에 들어갈 완성 예문이자 03단계 구현의 유일한 정식 작업 지시서입니다. 지금은 내용을 읽어 두고, 아래 2. 정식 작업 지시서 저장에서 파일을 만든 다음 코드 블록의 첫 줄부터 마지막 줄까지 빠짐없이 복사합니다.

# 03단계 정식 작업 지시서

## 단계별 상세 지시
루트 AGENTS.md와 docs/requirements/admin-platform.md를 먼저 읽어 줘.
현재 읽고 있는 이 파일을 03단계의 유일한 정식 작업 지시서로 사용해 줘.
02단계 완료 확인표와 공통 WebUI Gate가 통과했는지 확인하고, 실패 상태면 구현을 시작하지 마.

허용 범위는 backend/, API 호출에 필요한 frontend/ 파일과 Vite 프록시 설정이다.
변경 전에 현재 구조, API 계약, 변경 예정 파일과 검증 명령을 보고해 줘.

Express 5와 TypeScript 백엔드를 127.0.0.1:3000에서 실행한다.
GET /api/health와 POST /api/auth/login만 구현한다.
로그인 API는 학습용 임시 관리자 판정을 백엔드에서 수행하되 실제 인증이 아님을 명시한다.
Vite의 /api 요청을 127.0.0.1:3000으로 프록시한다.
프런트엔드 Source의 임시 암호 비교를 제거하고 상대 경로로 로그인 API를 호출한다.
프런트엔드에 처리 중, 성공와 오류 상태를 구분하여 표시한다.
응답와 로그에 암호나 인증정보를 포함하지 않는다.

MySQL, 세션, Redis, Nginx, Docker와 Compose 구성을 추가하지 않는다.
02단계 경로, Dashboard와 로그out 화면을 관련 없이 재설계하지 않는다.

변경 전·후에 03단계 적용 범위의 공통 WebUI Gate를 실행한다.
백엔드 typecheck, 프런트엔드 build, health와 로그인 curl, 웹 브라우저의 `Console`과 `Network`를 확인한다.
검사 결과는 완료 보고에 통과, 실패와 미수행으로 구분한다. 검증 기록 문서 갱신은 사용자가 WebUI 확인을 마친 뒤 별도 프롬프트로 수행하므로 이 작업에서는 실행하지 않는다.
검사가 실패하면 완료로 판정하거나 04단계 MySQL 작업을 시작하지 말고 원인과 남은 작업을 보고한다.

## 완료 보고 형식

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

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

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

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

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

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

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

2. 정식 작업 지시서 저장

docs/work-orders/03-express-api-connection.md는 이 절차에서 처음 생성합니다. 파일 위치는 현재 Obsidian 문서가 있는 Vault가 아니라, 01단계에서 만든 개발 서버의 /home/apple2ne1/projects/vibe-coding-platform/docs/work-orders/ 폴더입니다.

완성된 위치는 다음과 같습니다.

/home/apple2ne1/projects/vibe-coding-platform/
└── docs/
    └── work-orders/
        └── 03-express-api-connection.md

방법 1: VS Code 작업

Explorer에서 work-orders를 마우스 오른쪽 버튼으로 클릭하고 New File을 선택합니다.

파일 이름을 03-express-api-connection.md로 지정합니다.

방법 2: 터미널 작업

먼저 VS Code 원격 터미널이 프로젝트 루트에 있는지 확인하고 파일을 만듭니다.

cd /home/apple2ne1/projects/vibe-coding-platform
mkdir -p docs/work-orders
touch docs/work-orders/03-express-api-connection.md

mkdir -p는 docs/work-orders 폴더가 이미 있으면 그대로 사용하고, 없으면 새로 만듭니다. touch는 그 안에 빈 03-express-api-connection.md 파일을 만듭니다.

다음 순서로 파일 내용을 저장합니다.

1. VS Code의 Explorer에서 프로젝트 루트 아래의 docs, work-orders 폴더를 차례로 펼칩니다.
2. 03-express-api-connection.md를 선택하여 편집기에서 엽니다.

1. 이 문서 위쪽의 정식 작업 지시서 아래에 있는 markdown 코드 블록에서 # 03단계 정식 작업 지시서부터 마지막 남은 제한, 위험과 다음 단계 진행 가능 여부까지 모두 복사합니다.
2. 빈 03-express-api-connection.md에 붙여넣고 Ctrl+S로 저장합니다.

학습용 간단한 지시 설명서는 파일에 넣지 않습니다. 코드 블록을 감싸는 “` `markdown “과 마지막 “ ` “`도 파일 내용에 넣지 않습니다. 저장한 파일은 다음과 같이 시작해야 합니다.

# 03단계 정식 작업 지시서

## 단계별 상세 지시
루트 AGENTS.md와 docs/requirements/admin-platform.md를 먼저 읽어 줘.
현재 읽고 있는 이 파일을 03단계의 유일한 정식 작업 지시서로 사용해 줘.

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

test -s docs/work-orders/03-express-api-connection.md && echo "작업 지시서 저장 완료" || echo "파일이 없거나 비어 있습니다"
sed -n '1,12p' docs/work-orders/03-express-api-connection.md
git diff -- docs/work-orders/03-express-api-connection.md

첫 명령에서 작업 지시서 저장 완료가 출력되고, 두 번째 명령에서 # 03단계 정식 작업 지시서로 시작하는 내용이 표시되어야 합니다. 파일이 없거나 비어 있습니다가 출력되거나 내용이 다르면 다음 절차로 넘어가지 말고 파일 위치와 복사 범위를 다시 확인합니다.

이제 03-express-api-connection.md가 실제로 생성되었으므로, 3번에서 이 파일만 Git 기준점으로 기록한 뒤 4번에서 Codex에 읽도록 요청할 수 있습니다.

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

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

git status --short
test -s docs/work-orders/03-express-api-connection.md
git add -- docs/work-orders/03-express-api-connection.md
git diff --cached --name-only
git diff --cached --check
git commit -m "docs: add 03 step work order"

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

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

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

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

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

루트 AGENTS.md, docs/requirements/admin-platform.md와
docs/work-orders/03-express-api-connection.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 또는 대체 검사만 번호가 있는 짧은 목록으로 안내해 줘.
검증 결과 기록, 스테이징과 커밋은 사용자가 실제 확인을 마친 뒤 별도 프롬프트로 요청할 것이므로 지금 실행하지 마.

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

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

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

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

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

구현 결과 WebUI 실행과 확인

이 단계에서 WebUI를 확인할 수 있으면 구현 결과를 웹 브라우저에서 확인합니다. 화면 변경이 없는 단계에서는 정식 작업 지시서에 지정된 API, 데이터베이스, Compose 또는 자동 검사처럼 해당 단계에 맞는 검사를 실행합니다. WebUI 확인이 필수인데 화면이 열리지 않거나 기능이 동작하지 않으면 다른 검사의 통과 여부만으로 다음 단계로 이동하지 않고, 오류와 실행 결과를 Codex에 전달하여 해결합니다.

사용자가 지금 확인할 항목

1. 백엔드와 프런트엔드에서 각각 npm run dev를 실행합니다.
2. http://192.168.1.231:5173/login에서 admin@example.com과 비어 있지 않은 암호로 로그인합니다.
3. 처리 중 표시 후 Dashboard와 성공 메시지가 보이는지 확인합니다.
4. 다른 이메일로 오류 메시지가 표시되는지 확인합니다.
5. Console 오류가 없고 Network의 /api/auth/login 응답에 암호가 없는지 확인합니다.
6. 키보드, 데스크톱과 모바일에서도 로그인·로그아웃을 확인합니다.

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

Windows 관리 PC의 웹 브라우저에서 http://서버-IP:5173에 접속한 뒤 이 절의 WebUI와 Network 검증 순서에 따라 로그인 요청이 백엔드로 전달되는지 확인합니다. 정식 작업 지시서 해설은 검증 결과 기록과 커밋까지 마친 뒤 복습할 때 읽습니다.

admin@example.com과 비어 있지 않은 암호로 로그인합니다.

다른 이메일로 오류 메시지가 표시되는지 확인합니다.

WebUI 확인이 끝나면 프런트엔드, 백엔드를 중지합니다.

프런트엔드를 실행한 터미널을 선택하고 다음 중 한 가지 방법으로 Vite를 중지합니다.

q를 입력한 뒤 Enter

또는 해당 터미널에서 Ctrl+C를 누릅니다. 셸 프롬프트가 다시 표시되면 프런트엔드가 중지된 것입니다.

백엔드를 실행한 터미널을 선택하고 다음 키를 누릅니다.

Ctrl+C

Backend listening on http://127.0.0.1:3000 아래에 셸 프롬프트가 다시 표시되면 백엔드의 tsx watch 프로세스가 중지된 것입니다.

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

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

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

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

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

03단계 구현과 검증은 앞 절차에서 완료했어. 검증을 다시 실행하지 말고 현재 작업 기록과 실제 결과만 확인해 줘.
webui-gate.md에는 API와 웹 브라우저 결과를, local-development.md에는 프런트엔드·백엔드 실행과 3000·5173 확인 방법을, README.md에는 API 연결 상태를 기록해 줘. 새 환경변수가 실제로 생긴 경우에만 실제 값 없이 안전한 변수 이름을 예시 파일에 추가해 줘.
실행하지 않은 검사는 통과로 기록하지 말고 기존 기록을 삭제하거나 덮어쓰지 마.
현재 코드와 확인된 결과를 기준으로 README.md, docs/requirements/admin-platform.md,
docs/development-guides/local-development.md와 docs/development-guides/webui-gate.md의
현재 단계와 완료 상태가 서로 다른지도 확인해 줘.
기록만 오래되었거나 충돌하면 요구사항 자체를 바꾸지 말고 실제 상태에 맞게 일치시켜 줘.

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

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

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

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

7. 최종 변경 검토와 Commit

Codex의 완료 보고에서 이번 단계에 변경된 파일을 확인합니다. Windows 관리 PC에서는 자동 검사 결과와 변경 파일 목록을 대조한 뒤, 같은 Codex CLI 대화에 다음 프롬프트를 전달합니다.

이번 단계 완료 보고에서 확인한 변경 파일만 파일 경로를 명시한 git add -- 명령으로 스테이징해 줘.
기존 사용자 변경과 이번 단계 범위 밖의 파일은 스테이징하지 마.
스테이징 뒤에는 git diff --cached --name-only와 git diff --cached --check를 실행하고 결과를 보고해 줘.
검사가 실패하거나 완료 보고와 파일 목록이 다르면 커밋하지 말고 원인만 보고해 줘.

cd /home/apple2ne1/projects/vibe-coding-platform
git status --short
git --no-pager diff --cached --name-only
git diff --cached --check

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

git commit -m "feat: complete 03 step"

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

정식 작업 지시서 해설

이 절은 새로운 작업을 지시하거나 추가 명령을 실행하는 단계가 아닙니다. 정식 작업 지시서 실행, 구현 결과 WebUI·Network 검증, Codex의 검증 기록 갱신과 커밋까지 마친 뒤 읽는 복습용 해설입니다.

이번 단계에서 왜 Express API를 추가했는지, 프런트엔드와 백엔드의 책임이 어떻게 나뉘는지, 무엇을 확인해야 완료할 수 있는지를 정식 작업 지시서 순서에 맞춰 설명합니다. 실제 생성 파일, HTTP 상태 코드와 JSON 필드는 Codex의 완료 보고 및 현재 프로젝트에서 확인하며, 정식 작업 지시서에 정의되지 않은 구현 세부 사항을 해설에서 임의로 확정하지 않습니다.

1. 이번 단계의 목적과 범위

02단계에서는 React 안에서 학습용 입력 조건을 비교하여 로그인 화면 흐름을 확인했습니다. 03단계에서는 이 판정을 Express 백엔드로 옮기고, 프런트엔드는 API 요청과 화면 상태 표시를 담당하도록 책임을 나눕니다.

이번 단계에서 확정하는 API 경계는 다음 두 엔드포인트입니다.

• GET /api/health: Express 백엔드가 요청에 응답할 수 있는지 확인합니다.
• POST /api/auth/login: 로그인 입력을 받아 학습용 임시 관리자 판정을 수행합니다.

허용 범위는 backend/, API 호출에 필요한 최소 프런트엔드 파일과 Vite 프록시 설정입니다. MySQL, 세션, Redis, Nginx, Docker와 Compose는 추가하지 않습니다. 02단계의 /login, /admin, Dashboard와 로그out 화면도 API 연결에 필요한 범위를 제외하고 다시 설계하지 않습니다.

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

vibe-coding-platform/
├── docs/
│   └── work-orders/
│       └── 03-express-api-connection.md
├── backend/
│   ├── package.json
│   ├── package-lock.json
│   └── src/
│       └── <Express 실행과 API 경로를 담당하는 실제 소스 파일>
└── frontend/
    ├── vite.config.ts
    └── src/
        └── <Login API 호출과 화면 상태를 연결한 실제 소스 파일>

03단계부터 backend/에 Express API 소스가 채워지고, frontend/vite.config.ts는 /api/ 요청을 개발 백엔드로 전달합니다. 백엔드 진입 파일과 프런트엔드 API 모듈 이름은 실제 구현에서 확정한 경로를 사용합니다.

2. 로그인 판정을 백엔드로 옮기는 이유

프런트엔드 코드에 비교 조건을 두면 해당 코드가 웹 브라우저로 전달되므로 사용자가 조건을 확인하거나 우회할 수 있습니다. Express로 판정 위치를 옮기면 화면은 입력과 결과 표시를 담당하고, 백엔드는 요청 검증과 판정을 담당하는 API 경계를 만들 수 있습니다.

그러나 판정 위치가 백엔드로 이동했다는 사실만으로 실제 인증이 완성되지는 않습니다. 현재 단계는 데이터베이스 계정을 조회하지 않고 세션도 발급하지 않는 학습용 구현입니다. 코드와 화면에 실제 인증이 아니라는 안내가 유지되어야 하며, WebUI Gate에서 해당 안내를 확인합니다.

이 API 경계는 04단계에서 임시 판정을 MySQL 계정 조회와 암호 해시 비교로 교체하고, 05단계에서 세션을 연결하기 위한 준비입니다.

3. 요청과 응답의 흐름

웹 브라우저 :5173
  → POST /api/auth/login
Vite 개발 서버의 /api 프록시
  → http://127.0.0.1:3000
Express 백엔드
  → JSON 성공 또는 오류 응답
React 로그인 화면
  ├─ 성공: /admin으로 이동하고 성공 상태 표시
  └─ 실패: 로그인 화면에 오류 상태 표시

프런트엔드는 Express의 절대 주소를 소스에 직접 작성하지 않고 상대 경로 /api/auth/login을 호출합니다. Vite 개발 서버는 /api 요청만 같은 Ubuntu 서버의 127.0.0.1:3000으로 전달합니다.

Express가 127.0.0.1:3000에서만 수신하므로 외부 PC가 백엔드 포트에 직접 접속할 필요가 없습니다. Windows 관리 PC는 계속 5173의 Vite 화면으로 접속하고, API 요청은 Vite 프록시를 통과합니다. 이 구성은 개발 환경의 연결 방식이며 이후 Nginx 통합 환경의 리버스 프록시와는 구분합니다.

4. 구현에서 구분해야 하는 역할

정식 작업 지시서는 특정 파일 구조를 강제하지 않습니다. 실제 파일명은 현재 프로젝트와 Codex 완료 보고에서 확인하되 다음 역할은 구분되어야 합니다.

• 백엔드 패키지 설정: Express 5, TypeScript, 개발 실행과 typecheck 명령을 관리합니다.
• Express 애플리케이션: JSON 요청 처리와 상태 확인·로그인 엔드포인트를 구성합니다.
• 백엔드 실행 진입점: Express를 127.0.0.1:3000에서 시작합니다.
• 프런트엔드 API 호출 코드: 화면에서 HTTP 요청 처리를 분리하고 상대 /api 경로를 사용합니다.
• Vite 설정: /api 요청을 Express로 전달합니다.
• 로그인 화면: 요청 중·성공·오류 상태를 사용자에게 구분하여 표시합니다.

역할을 분리하면 화면 변경과 API 계약 변경의 영향을 구분하기 쉽고, 다음 단계에서 로그인 판정 방식만 교체하기도 쉬워집니다.

5. API 계약과 보안 경계

정식 작업 지시서는 엔드포인트, 요청 목적과 보안 금지 사항을 확정하지만 정확한 HTTP 상태 코드와 JSON 필드까지 미리 고정하지는 않습니다. 실제 상태 코드, 성공·실패 응답 구조와 사용자 식별 필드는 구현 전에 Codex가 보고한 API 계약과 완료 보고에서 확인합니다.

어떤 계약을 선택했든 다음 원칙은 지켜야 합니다.

• 입력 형식 오류와 로그인 실패를 프런트엔드가 구분하여 처리할 수 있어야 합니다.
• 응답은 계정 존재 여부나 내부 판정 조건을 불필요하게 노출하지 않습니다.
• 응답, 서버 로그와 프런트엔드 상태에 암호나 인증정보를 포함하지 않습니다.
• 성공 응답도 화면 이동에 필요한 최소 정보만 사용합니다.
• HTTP 상태와 JSON 응답이 실제로 합의한 계약과 일치해야 합니다.

문서의 admin@example.com과 비어 있지 않은 암호는 현재 단계에서만 사용하는 공개 실습용 입력 조건입니다. 운영 환경에서 재사용할 수 없으며 실제 인증정보를 입력하지 않습니다.

6. 프런트엔드 상태 처리

사용자가 로그인 폼을 제출하면 프런트엔드는 기본 입력을 확인하고 API 요청을 시작합니다. 요청 중에는 처리 중 상태를 표시하고 중복 제출을 막습니다. 성공 응답이 실제 API 계약을 만족하면 /admin으로 이동하고, 로그인 실패나 연결 오류가 발생하면 사용자가 이해할 수 있는 오류를 표시합니다.

처리 중·성공·오류 상태는 서로 다른 결과입니다. 버튼만 비활성화하거나 모든 실패를 같은 성공 화면으로 처리하지 않으며, 연결 실패도 로그인 실패와 혼동하지 않도록 현재 구현에서 정한 표시 방법을 확인합니다.

7. 변경 전·후 Gate와 자동 검사의 의미

변경 전 Gate는 02단계에서 확인한 /login, /admin, Dashboard와 로그out 흐름을 기준선으로 기록합니다. 변경 후 Gate는 Express API를 연결한 뒤에도 이 흐름이 유지되는지 확인합니다. 두 결과를 비교하면 API 연결 때문에 발생한 회귀를 기존 문제와 구분할 수 있습니다.

각 검사는 서로 다른 구간을 확인합니다.

• 백엔드 typecheck: Express와 TypeScript 코드의 형식 오류를 확인합니다.
• 프런트엔드 빌드: API 호출 코드와 로그인 화면이 빌드 가능한지 확인합니다.
• GET /api/health: Express 프로세스가 127.0.0.1:3000에서 응답하는지 확인합니다.
• 로그인 curl: 구현 전에 확정한 성공·실패 API 계약과 응답의 비밀정보 비노출을 확인합니다.
• Vite 프록시: 5173의 상대 /api 요청이 Express로 전달되는지 확인합니다.
• WebUI와 Network: 처리 중·성공·오류 표시, 실제 요청 주소, 응답 상태와 암호 비노출을 확인합니다.
• Console: 화면 동작 중 예상하지 못한 오류가 발생하지 않는지 확인합니다.
• 키보드·데스크톱·모바일: 02단계의 사용성과 화면 구성이 유지되는지 확인합니다.

자동 검사만 통과하고 실제 로그인 화면이 열리지 않으면 완료로 판정할 수 없습니다. 화면이 동작하더라도 빌드, API 계약, 프록시 또는 비밀정보 검사가 실패하면 다음 단계로 진행하지 않습니다. 실행하지 않은 검사는 미수행으로 기록합니다.

8. 단계 산출물과 검증 기록

docs/work-orders/03-express-api-connection.md는 구현 범위, API 경계, 제외 범위와 완료 조건을 고정하는 기준 문서입니다. 구현 중에는 정식 작업 지시서를 유일한 기준으로 사용하고 검증 기록 문서나 README.md를 미리 완료 상태로 바꾸지 않습니다.

사용자가 실제 WebUI와 Network 검증을 마친 뒤에는 별도의 Codex에 검증 결과 기록 요청 프롬프트를 사용합니다. Codex는 실제 프로젝트, 완료 보고와 사용자 확인 결과를 다시 대조하고 확인된 결과만 관련 문서에 기록합니다.

webui-gate.md에 기록되는 내용

docs/development-guides/webui-gate.md에는 변경 전·후 Gate, 백엔드 typecheck, 프런트엔드 빌드, 상태 확인·로그인 API, Vite 프록시, 처리 중·성공·오류 화면과 Console·Network 결과를 통과·실패·미수행으로 구분하여 기록합니다.

local-development.md에 기록되는 내용

docs/development-guides/local-development.md에는 실제로 확인한 프런트엔드·백엔드 실행 위치와 명령, 5173과 127.0.0.1:3000의 역할, /api/health 확인 방법, Vite 프록시 경로와 두 프로세스의 종료 방법을 기록합니다. 새 환경 변수가 실제로 생겼을 때만 값을 제외한 안전한 변수 이름과 사용 목적을 예시 파일에 반영합니다.

README.md에 기록되는 내용

루트 README.md에는 실제 구현과 검증으로 확인한 03단계 결과만 기록합니다. 정식 작업 지시서에서 요구하지 않았거나 확인하지 않은 응답 필드, 인증 기능, 데이터베이스와 세션을 완료 항목으로 추가하지 않습니다.

## 현재 단계

03단계: Express API 연결하기

## 완료된 기능

- `127.0.0.1:3000`에서 실행되는 Express 백엔드
- `GET /api/health`와 `POST /api/auth/login`
- Vite 프록시를 통한 프런트엔드의 상대 `/api` 요청
- 처리 중·성공·오류 상태를 구분하는 로그인 화면

## 개발 실행

- 프런트엔드: `http://<서버-IP>:5173`
- 백엔드: 서버 내부 `http://127.0.0.1:3000`
- 검증: 백엔드 `typecheck`, 프런트엔드 빌드, API와 공통 WebUI Gate

## 현재 제한

- 로그인 판정은 공개 실습용 임시 조건을 사용합니다.
- 실제 사용자 데이터베이스와 세션은 아직 연결하지 않았습니다.
- 새로고침 뒤 로그인 상태는 유지되지 않습니다.

9. 제한과 다음 단계

03단계 완료는 실제 관리자 인증이 완성되었다는 의미가 아닙니다. 프런트엔드와 백엔드의 책임을 분리하고, 로그인 판정을 교체할 수 있는 API 경계와 검증 방법을 만들었다는 의미입니다.

04단계에서는 백엔드의 임시 관리자 판정을 MySQL 계정 조회와 암호 해시 비교로 교체합니다. 05단계에서는 세션을 추가하여 로그인 상태 유지와 관리자 경로 보호를 구현합니다.

다음 단계

다음 글에서는 백엔드의 임시 관리자 값을 제거하고 MySQL 사용자 테이블과 암호 Hash를 연결합니다.

• 이전: 2단계: Login과 Admin Dashboard 화면 먼저 만들기
• 다음: 4단계: MySQL Admin 계정 연결하기

참고 자료 및 출처

• Express Middleware Guide: Express Middleware와 express.json() 역할 확인. 확인일: 2026-07-26
• Express 5 Migration Guide: Express 5의 Node.js 요구 조건 확인. 확인일: 2026-07-26
• Vite Server Options: server.proxy 동작 확인. 확인일: 2026-07-26