# SQLite + FastAPI + Vue 포트 설정 분리 설계

## 목표

현재 CRUD 예제의 백엔드와 프론트 실행 포트를 문서와 코드에서 더 분리해, 로컬 포트 충돌이 있어도 최소 수정으로 다시 실행할 수 있게 만든다.

## 배경

기존 예제는 아래 주소를 기본값으로 사용한다.

- 백엔드 API: `http://127.0.0.1:8000`
- 프론트 정적 서버: `http://127.0.0.1:5173`

실행 중 실제로 `8000`, `5173` 포트가 이미 사용 중이어서 새 서버를 같은 포트에 띄우지 못했다. 따라서 포트를 바꾸는 방법이 코드와 문서에 더 명확히 드러나야 한다.

## 범위

이번 작업은 다음을 포함한다.

- 프론트엔드의 API 주소 상수 구조를 분리
- 백엔드 포트 변경 방법을 README에 명시
- 프론트 정적 서버 포트 변경 방법을 README에 명시
- 기본 포트와 대체 포트 예시를 함께 제공

이번 작업은 다음을 포함하지 않는다.

- 별도 설정 파일 도입
- `.env` 기반 환경변수 시스템 추가
- 프론트 번들러 도입
- 런타임 자동 포트 탐지

## 접근 방식

### 1. 프론트 상수 분리

`frontend/src/main.js`의 API 주소를 하나의 긴 문자열 대신 아래 상수로 분리한다.

- `API_HOST`
- `API_PORT`
- `API_BASE_URL`

예시 구조:

```javascript
const API_HOST = 'http://127.0.0.1'
const API_PORT = '8000'
const API_BASE_URL = `${API_HOST}:${API_PORT}/api`
```

이렇게 하면 백엔드 포트를 `8001` 같은 값으로 바꿀 때 한 줄만 수정하면 된다.

### 2. 백엔드 실행 포트는 명령에서 제어

백엔드는 FastAPI 코드 내부에서 포트를 고정하지 않는다. 실행 포트는 `uvicorn` 명령의 `--port` 옵션으로 제어한다.

기본 실행:

```bash
uvicorn backend.main:app --host 127.0.0.1 --port 8000
```

대체 실행:

```bash
uvicorn backend.main:app --host 127.0.0.1 --port 8001
```

### 3. 프론트 정적 서버 포트는 명령에서 제어

프론트 정적 서버도 코드가 아니라 실행 명령에서 포트를 선택한다.

기본 실행:

```bash
python3 -m http.server 5173 -d frontend
```

대체 실행:

```bash
python3 -m http.server 5174 -d frontend
```

## README 문서화 방식

README에는 아래 내용을 포함한다.

- 기본 포트 실행 예시
- 포트 충돌 시 대체 실행 예시
- 프론트에서 `API_PORT` 값을 어디서 바꾸는지 설명
- 백엔드와 프론트 포트는 서로 독립적으로 바꿀 수 있다는 점

## 데이터 흐름

1. 사용자가 백엔드를 원하는 포트로 실행한다.
2. 프론트는 `API_HOST`와 `API_PORT`를 조합해 API 주소를 만든다.
3. 프론트 정적 서버는 별도 포트에서 독립적으로 제공된다.
4. 포트 충돌 시 백엔드와 프론트 포트를 각각 따로 변경할 수 있다.

## 오류 처리

- 프론트가 잘못된 백엔드 포트를 가리키면 기존처럼 fetch 에러 문구를 보여준다.
- README에 포트 불일치 점검 순서를 넣어 사용자가 원인을 쉽게 찾을 수 있게 한다.

## 검증 기준

다음 조건을 만족하면 성공이다.

- 프론트 코드에서 백엔드 포트를 한 곳만 바꿔도 API 주소가 함께 변경된다.
- README만 읽어도 기본 포트와 대체 포트 실행 방법을 이해할 수 있다.
- 기존 CRUD 기능은 변경 없이 유지된다.
- 포트 충돌 상황에서 사용자가 다음 행동을 바로 선택할 수 있다.

## 구현 원칙

- 기존 CRUD 구조를 유지한다.
- 설정 분리를 위해 새 시스템을 과하게 도입하지 않는다.
- 실행 문서는 실제 충돌 상황을 해결하는 데 바로 도움이 되도록 쓴다.