skillDesk/docs/superpowers/specs/2026-06-09-sqlite-fastapi-vue-hello-world-design.md

SQLite + FastAPI + Vue Hello World 예제 설계

목표

SQLite 데이터베이스에 저장된 문자열 'hello world'를 Python FastAPI 백엔드가 읽고, Vue 프론트엔드가 API를 호출해 화면에 표시하는 최소 동작 예제를 만든다.

범위

이번 예제는 다음 범위를 포함한다.

• SQLite DB 파일 생성
• 메시지 테이블 생성과 샘플 데이터 삽입
• FastAPI에서 SQLite 데이터를 읽는 API 구현
• Vue에서 API를 호출해 화면에 문자열 출력
• 실행 방법 문서화

이번 예제는 다음 범위를 포함하지 않는다.

• 사용자 입력 폼
• CRUD 전체 기능
• 인증/권한
• 상태관리 라이브러리
• 배포 구성

구조

예제는 프론트엔드와 백엔드를 분리한 최소 구조로 만든다.

skillDesk/
├── backend/
│   ├── main.py
│   ├── init_db.py
│   ├── requirements.txt
│   └── app.db
├── frontend/
│   ├── package.json
│   ├── vite.config.js
│   └── src/
│       ├── App.vue
│       └── main.js
└── README.md

데이터 흐름

1. backend/init_db.py가 SQLite 데이터베이스 파일을 만들고 messages 테이블을 생성한다.
2. 초기 데이터로 'hello world' 한 건을 삽입한다.
3. backend/main.py의 GET /api/message 엔드포인트가 SQLite에서 첫 메시지를 읽는다.
4. Vue 앱이 페이지 로드 시 /api/message를 호출한다.
5. 응답 JSON의 메시지를 화면에 렌더링한다.

백엔드 설계

기술 선택

• Python
• FastAPI
• sqlite3 표준 라이브러리
• uvicorn

엔드포인트

GET /api/message

응답 예시:

{
  "message": "hello world"
}

DB 스키마

테이블명: messages

컬럼:

• id INTEGER PRIMARY KEY AUTOINCREMENT
• content TEXT NOT NULL

CORS

개발 중 Vue dev server에서 FastAPI API를 호출할 수 있도록 최소 CORS 설정을 추가한다.

프론트엔드 설계

기술 선택

• Vue 3
• Vite

동작

• 앱이 마운트되면 FastAPI API를 호출한다.
• 로딩 중에는 간단한 로딩 문구를 표시한다.
• 성공하면 DB에서 받은 'hello world'를 표시한다.
• 실패하면 간단한 에러 문구를 표시한다.

화면 구성

예제는 최소 화면만 구성한다.

• 제목
• API에서 받은 메시지 출력 영역
• 로딩/에러 상태 문구

실행 흐름

1. Python 가상환경 생성 및 의존성 설치
2. SQLite 초기화 스크립트 실행
3. FastAPI 서버 실행
4. Vue 의존성 설치
5. Vue 개발 서버 실행
6. 브라우저에서 메시지 표시 확인

검증 기준

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

• SQLite DB 파일이 생성된다.
• messages 테이블에 'hello world'가 저장된다.
• GET /api/message 호출 시 JSON 응답이 반환된다.
• Vue 화면에서 'hello world'가 보인다.
• 백엔드와 프론트엔드 실행 방법이 README에 정리된다.

오류 처리

최소 예제이므로 복잡한 예외 처리 대신 아래 수준만 포함한다.

• DB에 메시지가 없으면 기본 에러 응답 반환
• 프론트엔드 fetch 실패 시 에러 문구 표시

구현 원칙

• 예제는 최대한 짧고 이해하기 쉬워야 한다.
• 구조는 실제 앱 구조와 유사하게 분리한다.
• 과도한 추상화는 하지 않는다.
• 의존성은 최소화한다.