릴리스: v0.1.6 MariaDB 개발 환경 및 저장소 설정 정리

2026-03-19 14:48:03 +09:00
commit 0c30ae5cb3
52 changed files with 9346 additions and 0 deletions
--- a/docs/convention.md
+++ b/docs/convention.md
@@ -0,0 +1,22 @@
+# 코딩 컨벤션
+
+## 공통
+- 문서와 사용자 응답은 한국어로 작성한다.
+- JavaScript는 세미콜론 없이 현재 코드 스타일을 유지한다.
+- 새 주석이 필요할 경우 JSDoc 형식을 사용한다.
+- 경로, 주소, 운영 설정은 하드코딩보다 환경변수 기반 구성을 우선한다.
+- Git 커밋 메시지는 한국어로 작성한다.
+- 버전 릴리스가 포함된 작업은 `docs/update.md`의 버전 표기와 Git 태그를 함께 맞춘다.
+
+## 프런트엔드
+- API 호출은 `frontend/src/lib/api.js` 또는 런타임 유틸을 통해 통합한다.
+- 정적 파일 URL 조합은 `toApiUrl()`로 처리한다.
+- 화면 상태는 `ref`, `computed`, `onMounted` 중심의 단순한 Composition API 패턴을 유지한다.
+
+## 백엔드
+- 라우트 검증은 `zod`로 처리한다.
+- 파일 업로드명은 ASCII 안전 문자열을 사용한다.
+- 인증/권한 분기는 미들웨어(`requireAuth`, `requireAdmin`)로 분리한다.
+- DB 저장 전에는 배포 환경에 종속되는 값(예: 로컬 절대 URL)이 들어가지 않도록 정규화한다.
+- 사용자 프로필처럼 “선택 후 저장” 흐름이 필요한 기능은 파일 선택과 실제 저장 요청을 분리한다.
+- 관리자 지정 데이터와 사용자 커스텀 데이터는 테이블과 업로드 경로를 분리해서 관리한다.
--- a/docs/history.md
+++ b/docs/history.md
@@ -0,0 +1,28 @@
+# 의사결정 이력
+
+## 2026-03-19
+- 초기 저장소는 빠른 구현을 위해 `lowdb(JSON 파일)`를 채택했다.
+- 인증은 JWT 대신 서버 세션(`express-session` + `session-file-store`)을 사용했다.
+- 업로드 파일은 외부 스토리지 없이 로컬 디스크(`backend/uploads/`)에 저장하기로 했다.
+
+## 2026-03-19 v0.1.3
+- 배포 환경 호환성을 위해 프런트엔드의 API 기준 주소를 환경변수(`VITE_API_ORIGIN`)로 통합했다.
+- NAS/리버스 프록시 환경을 고려해 CORS 및 세션 쿠키 옵션을 환경변수 기반으로 전환했다.
+- 파일명 깨짐과 URL 이식성 문제를 줄이기 위해 업로드 파일명을 ASCII 기반으로 생성하도록 변경했다.
+- 게임 이미지 경로는 저장 시 상대 경로(`/uploads/...`)를 유지하는 방향으로 정리했다.
+- 현재 단계에서는 구조 변경 비용을 고려해 DB를 유지하되, 운영/확장성 요구가 커지기 전 RDB 이관 판단이 필요하다고 기록했다.
+
+## 2026-03-19 v0.1.4
+- 운영 편의성과 NAS 환경에서의 데이터 조회 필요성 때문에 저장소를 MariaDB(MySQL 호환) 기준으로 전환했다.
+- 관리자 지정 아이템과 사용자 커스텀 이미지는 책임과 수명 주기가 다르므로 별도 테이블(`game_items`, `custom_items`)로 분리했다.
+- 작성자 식별성을 위해 공개 티어표에 닉네임을 표시하고, 프로필에서 닉네임을 수정할 수 있게 했다.
+- 아바타 업로드는 즉시 반영보다 “선택 후 저장” 흐름이 맞다고 판단해 미리보기와 실제 저장을 분리했다.
+- 관리자 페이지는 게임 선택 후 상세 관리가 열리는 단계형 흐름으로 바꾸는 것이 실사용에 더 안전하다고 결정했다.
+
+## 2026-03-19 v0.1.5
+- 로컬 개발과 운영 환경의 차이를 줄이기 위해 기본 로컬 개발 DB도 MariaDB로 고정했다.
+- 로컬 실행 편의를 위해 `docker-compose.yml`에 `mariadb`와 `phpMyAdmin` 서비스를 추가했다.
+- 백엔드 기본 `dev/start/migrate` 스크립트는 로컬 MariaDB 기준 값으로 정리하고, lowdb는 예외용 fallback 스크립트로만 남겼다.
+
+## 2026-03-19 v0.1.6
+- 저장소 운영 규칙을 정리하면서 Git 작성자 정보는 프로젝트 기준 계정으로 통일하고, 커밋 메시지는 한국어로 남기기로 결정했다.
--- a/docs/local-mariadb.md
+++ b/docs/local-mariadb.md
@@ -0,0 +1,46 @@
+# 로컬 MariaDB 실행 가이드
+
+## 목표
+- 로컬 개발 환경도 서버와 같은 `MariaDB(MySQL 호환)` 기반으로 맞춘다.
+- 데이터 확인은 `phpMyAdmin`으로 직접 한다.
+
+## 1. DB 컨테이너 실행
+프로젝트 루트에서 아래 명령으로 실행한다.
+
+```bash
+docker compose up -d mariadb phpmyadmin
+```
+
+## 2. 접속 정보
+- MariaDB 호스트: `127.0.0.1`
+- MariaDB 포트: `3307`
+- DB 이름: `tier_cursor`
+- 계정: `tier_cursor`
+- 비밀번호: `tier_cursor1234`
+- phpMyAdmin: `http://localhost:8081`
+
+## 3. 백엔드 실행
+아래 명령은 로컬 MariaDB 기준 환경변수를 포함한다.
+
+```bash
+cd backend
+npm run dev
+```
+
+## 4. 프런트엔드 실행
+```bash
+cd frontend
+VITE_API_ORIGIN=http://localhost:5179 npm run dev
+```
+
+## 5. 기존 lowdb 데이터 이관
+MariaDB 컨테이너와 백엔드 의존성이 준비된 뒤 아래 명령을 실행한다.
+
+```bash
+cd backend
+npm run migrate:lowdb
+```
+
+## 메모
+- 긴급 확인용으로만 `npm run dev:lowdb`를 남겨두었고, 기본 개발 기준은 MariaDB다.
+- NAS 배포 시에도 동일하게 MariaDB를 사용하므로 로컬과 운영 간 DB 계층 차이를 줄일 수 있다.
--- a/docs/map.md
+++ b/docs/map.md
@@ -0,0 +1,50 @@
+# 파일-화면 매핑 가이드
+
+## `/`
+- 화면 파일: `frontend/src/views/HomeView.vue`
+- 역할: 게임 목록 표시, 게임 카드 클릭 이동, 새 게임 제안 모달
+- 연동 API: `GET /api/games`, `POST /api/games/suggest`
+
+## `/games/:gameId`
+- 화면 파일: `frontend/src/views/GameHubView.vue`
+- 역할: 선택한 게임 정보 표시, 공개 티어표 목록 표시, 작성자 닉네임 노출, 새 티어표 작성 진입
+- 연동 API: `GET /api/games/:gameId`, `GET /api/tierlists/public`
+
+## `/editor/:gameId/new`, `/editor/:gameId/:tierListId`
+- 화면 파일: `frontend/src/views/TierEditorView.vue`
+- 역할: 티어 그룹 편집, 관리자 아이템/커스텀 아이템 드래그 앤 드롭, 저장, 공개 여부 설정, PNG 다운로드
+- 연동 API: `GET /api/games/:gameId`, `GET /api/tierlists/:id`, `POST /api/tierlists/custom-items`, `POST /api/tierlists`
+
+## `/login`
+- 화면 파일: `frontend/src/views/LoginView.vue`
+- 역할: 로그인/회원가입 전환, 첫 가입 안내
+- 연동 API: `GET /api/auth/meta`, `POST /api/auth/login`, `POST /api/auth/signup`
+
+## `/me`
+- 화면 파일: `frontend/src/views/MyTierListsView.vue`
+- 역할: 내 티어표 목록 조회, 편집 화면으로 이동
+- 연동 API: `GET /api/tierlists/me`
+
+## `/admin`
+- 화면 파일: `frontend/src/views/AdminView.vue`
+- 역할: 게임 추가, 게임 선택 후 썸네일 업로드, 관리자 아이템 추가, 현재 아이템 목록 확인
+- 연동 API: `POST /api/admin/games`, `POST /api/admin/games/:gameId/thumbnail`, `POST /api/admin/games/:gameId/images`
+
+## `/profile`
+- 화면 파일: `frontend/src/views/ProfileView.vue`
+- 역할: 프로필 표시, 작성자 닉네임 수정, 아바타 미리보기 후 저장
+- 연동 API: `GET /api/auth/me`, `POST /api/auth/profile`
+
+## 공통 레이아웃
+- 앱 셸 파일: `frontend/src/App.vue`
+- 역할: 상단 내비게이션, 로그인 상태 반영, 아바타 메뉴, 관리자 메뉴 노출 제어
+
+## 백엔드 진입점
+- 서버 엔트리: `backend/index.js`
+- 데이터 초기화: `backend/src/db.js`
+- 로컬 DB 실행 설정: `docker-compose.yml`
+- 로컬 MariaDB 가이드: `docs/local-mariadb.md`
+- 인증 라우트: `backend/src/routes/auth.js`
+- 게임 라우트: `backend/src/routes/games.js`
+- 티어표 라우트: `backend/src/routes/tierlists.js`
+- 관리자 라우트: `backend/src/routes/admin.js`
--- a/docs/spec.md
+++ b/docs/spec.md
@@ -0,0 +1,113 @@
+# 기술 명세
+
+## 현재 아키텍처
+- 프런트엔드: Vue 3 + Vite + Pinia + Vue Router
+- 백엔드: Express 5
+- 데이터 저장소: MariaDB(MySQL 호환)
+- 세션 저장소: `session-file-store` 기반 파일 세션
+- 업로드 저장소: 로컬 파일 시스템(`backend/uploads/`)
+
+## 데이터 저장 구조
+- 메인 데이터베이스: MariaDB `tier_cursor` (기본값)
+- 세션 파일: `backend/.sessions/*.json`
+- 업로드 파일:
+  - 게임 이미지: `backend/uploads/games/`
+  - 아바타: `backend/uploads/avatars/`
+  - 커스텀 아이템: `backend/uploads/custom/`
+  - 시드 이미지: `backend/uploads/seeds/`
+- 레거시 마이그레이션 소스: `backend/data/db.json`
+
+## DB 스키마
+- `users`
+  - `id`: string
+  - `email`: string
+  - `nickname`: string
+  - `passwordHash`: string
+  - `isAdmin`: boolean
+  - `avatarSrc`: string
+  - `createdAt`: number
+- `games`
+  - `id`: string
+  - `name`: string
+  - `thumbnailSrc`: string
+  - `createdAt`: number
+- `gameItems`
+  - `id`: string
+  - `gameId`: string
+  - `src`: string
+  - `label`: string
+  - `createdAt`: number
+- `customItems`
+  - `id`: string
+  - `ownerId`: string
+  - `src`: string
+  - `label`: string
+  - `createdAt`: number
+- `tierLists`
+  - `id`: string
+  - `authorId`: string
+  - `gameId`: string
+  - `title`: string
+  - `description`: string
+  - `isPublic`: boolean
+  - `groups`: `{ id, name, itemIds[] }[]`
+  - `pool`: `{ id, src, label, origin }[]`
+  - `createdAt`: number
+  - `updatedAt`: number
+- `gameSuggestions`
+  - `id`: string
+  - `name`: string
+  - `createdAt`: number
+
+## 주요 API
+- 인증
+  - `POST /api/auth/signup`
+  - `POST /api/auth/login`
+  - `POST /api/auth/logout`
+  - `GET /api/auth/me`
+  - `GET /api/auth/meta`
+  - `POST /api/auth/profile`
+- 게임
+  - `GET /api/games`
+  - `GET /api/games/:gameId`
+  - `POST /api/games/suggest`
+- 티어표
+  - `GET /api/tierlists/public`
+  - `GET /api/tierlists/me`
+  - `GET /api/tierlists/:id`
+  - `POST /api/tierlists/custom-items`
+  - `POST /api/tierlists`
+- 관리자
+  - `POST /api/admin/games`
+  - `POST /api/admin/games/:gameId/thumbnail`
+  - `POST /api/admin/games/:gameId/images`
+
+## 운영 환경 변수
+- 프런트엔드
+  - `VITE_API_ORIGIN`: API 및 업로드 파일 절대 기준 주소
+- 백엔드
+  - `DB_CLIENT`: 기본 개발 기준은 `mariadb`
+  - `DB_HOST`: MariaDB 호스트
+  - `DB_PORT`: MariaDB 포트
+  - `DB_USER`: MariaDB 계정
+  - `DB_PASSWORD`: MariaDB 비밀번호
+  - `DB_NAME`: 데이터베이스명
+  - `PORT`: 서버 포트
+  - `SESSION_SECRET`: 세션 서명 키
+  - `CORS_ORIGINS`: 허용할 프런트 도메인 목록(쉼표 구분)
+  - `TRUST_PROXY`: 프록시 홉 수
+  - `SESSION_COOKIE_SECURE`: `true`면 HTTPS 전용 쿠키
+  - `SESSION_COOKIE_SAME_SITE`: 기본 `lax`
+
+## NAS 배포 메모
+- 현재 구조는 MariaDB/MySQL 계열이므로 NAS에 MariaDB를 올리면 phpMyAdmin 또는 Adminer로 직접 데이터 확인이 가능하다.
+- 추천 구성:
+  - MariaDB 컨테이너 또는 NAS 패키지 설치
+  - phpMyAdmin 또는 Adminer 설치
+  - 앱은 환경변수로 해당 DB에 연결
+- 레거시 `db.json` 데이터는 `node backend/scripts/migrate-lowdb-to-mariadb.js`로 이관한다.
+
+## 로컬 개발 기준
+- 기본 로컬 개발도 `docker compose`로 띄운 MariaDB를 사용한다.
+- 기본 백엔드 실행 스크립트 `backend/package.json`의 `dev`, `start`, `migrate:lowdb`는 로컬 MariaDB(`127.0.0.1:3307`) 기준으로 맞춰져 있다.
+- 예외적으로만 `dev:lowdb`, `start:lowdb`를 사용한다.
--- a/docs/todo.md
+++ b/docs/todo.md
@@ -0,0 +1,18 @@
+# 할 일 및 이슈
+
+## 즉시 확인 필요
+- 관리자 화면에 게임 제안(`gameSuggestions`) 조회/처리 UI가 아직 없다.
+- MariaDB 실제 서버가 준비되면 `backend/scripts/migrate-lowdb-to-mariadb.js`를 실행해 기존 `db.json` 데이터를 이관해야 한다.
+- 기존 `backend/data/db.json`의 절대 로컬 URL/깨진 파일명 데이터는 마이그레이션 후 수동 정리가 필요할 수 있다.
+
+## 배포 전 작업
+- NAS 실제 도메인 기준으로 `VITE_API_ORIGIN`, `CORS_ORIGINS`, `SESSION_SECRET`, `SESSION_COOKIE_SECURE`, `TRUST_PROXY` 값을 설정한다.
+- MariaDB 접속 정보 `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_NAME`를 설정한다.
+- HTTPS를 사용할 경우 `SESSION_COOKIE_SECURE=true`로 설정하고 리버스 프록시 헤더 전달을 확인한다.
+- `backend/uploads/`, `backend/.sessions/`, MariaDB 백업 정책을 정한다.
+- 로컬 docker compose와 NAS MariaDB 사이의 버전 차이가 크지 않도록 유지한다.
+
+## 중기 개선
+- 게임/이미지/티어표 삭제 및 수정 이력 관리 기능을 추가한다.
+- 자동 테스트와 최소한의 배포 체크리스트를 만든다.
+- 관리자용 게임 제안 승인/반려, 아이템 삭제/정렬 UI를 추가한다.
--- a/docs/update.md
+++ b/docs/update.md
@@ -0,0 +1,52 @@
+# 업데이트 로그
+
+## 2026-03-19 v0.1.0
+- **초기 스캐폴딩**: `frontend/`에 Vue3(Vite, JavaScript) 프로젝트 생성
+- **라우팅/화면 골격**: 게임 선택(`/`), 게임 허브(`/games/:gameId`), 에디터(`/editor/:gameId/...`), 로그인(`/login`), 내 티어표(`/me`), 관리자(`/admin`) 라우트 추가
+- **레이아웃**: 상단 네비게이션 + 기본 다크 UI 스타일 적용
+- **백엔드 골격**: `backend/`에 Express 서버 추가(세션 기반 인증, 게임/티어표 API, 업로드 경로)
+- **저장소**: 네이티브 DB 대신 파일 DB(`lowdb`)로 유저/게임/이미지/티어표 데이터 영속화
+- **에디터 핵심 기능(1차)**: 그룹 이름/순서 편집, 아이템 드래그&드롭(풀↔그룹), 커스텀 이미지 추가, 보드 PNG 다운로드, 백엔드 저장/불러오기 연결
+- **관리자 UI(1차)**: admin 전용 게임 추가 + 게임별 기본 이미지 업로드/목록 화면 추가
+- **버그 수정**: Vite 포트 변경(5174 등) 시 백엔드 CORS가 막히는 문제 해결(로컬 5170~5179 허용)
+- **네비/권한 UX**: 관리자 메뉴는 admin 로그인 시에만 노출, 로그인 대신 아바타 버튼/메뉴 노출
+- **프로필**: `/profile` 페이지 추가, 아바타 업로드 API(`/api/auth/avatar`) 및 표시 지원
+- **에디터 버그 수정**: 드래그 시 아이템들이 “묶음”으로 같이 움직이던 문제 해결(드롭 영역 DOM 구조/Sortable 옵션 수정), 드롭 영역 overflow/배치 레이아웃 개선
+
+## 2026-03-19 v0.1.1
+- **티어표 메타데이터 개선**: 제목 미입력 시 저장 시점에 게임 이름 기반 자동 제목 적용, 설명(선택) 필드 추가
+- **시간 정보 표시**: 내 티어표/공개 목록에서 저장 시간(createdAt)과 업데이트 시간(updatedAt)을 시:분:초까지 표시
+- **에디터 UX 수정**: 빈 티어 칸 안내 문구가 첫 드래그 배치를 가리던 문제 수정(오버레이 처리), 제목 상단에 게임 이름 표시
+
+## 2026-03-19 v0.1.2
+- **로그인 UI 개선**: 로그인 카드 중앙 배치, 중복 타이틀 제거, 입력 overflow 수정, 엔터로 로그인/회원가입 제출
+- **안내문 조건화**: “첫 회원가입 계정은 admin” 문구는 유저가 0명일 때만 표시(`/api/auth/meta`)
+- **게임 목록 UI 개선**: 게임 카드에 썸네일 표시, 중복 텍스트 제거, “새로운 게임 제안” 모달 추가
+- **관리자 기능 추가**: 게임 썸네일 업로드 API(`/api/admin/games/:gameId/thumbnail`) 및 UI 추가
+- **에디터 레이아웃 개선**: 등급(그룹) 라벨 칼럼 확장으로 텍스트 잘림 방지, 설명 입력 1줄, 정렬을 좌측 기준으로 조정
+
+## 2026-03-19 v0.1.3
+- **배포 설정 개선**: 프런트엔드의 API/정적 파일 주소 하드코딩(`http://localhost:5179`)을 `VITE_API_ORIGIN` 기반으로 통합
+- **백엔드 운영 설정 추가**: `CORS_ORIGINS`, `TRUST_PROXY`, `SESSION_COOKIE_SECURE`, `SESSION_COOKIE_SAME_SITE`, `SESSION_SECRET` 환경변수 기반으로 NAS/리버스 프록시 배포 대응
+- **업로드 파일명 안정화**: 한글 원본 파일명 기반 저장을 제거하고 ASCII 안전 파일명으로 저장하도록 변경
+- **티어표 데이터 정규화**: 게임 이미지 경로가 절대 로컬 URL로 저장되지 않도록 저장/조회 시 `/uploads/...` 상대 경로로 정규화
+- **프로젝트 점검 결과 문서화**: DB 구조, 화면-파일 매핑, 코딩 규칙, 기술 명세, 남은 위험 요소를 `docs/`에 신규 정리
+
+## 2026-03-19 v0.1.4
+- **DB 마이그레이션 준비**: 런타임 저장소를 `MariaDB(MySQL 호환)` 기준으로 재구성하고 `backend/scripts/migrate-lowdb-to-mariadb.js` 마이그레이션 스크립트 추가
+- **데이터 구조 분리**: 관리자 지정 아이템은 `game_items`, 유저 커스텀 이미지는 `custom_items`로 분리
+- **프로필 개선**: 작성자 닉네임 저장 지원, 아바타는 파일 선택 시 미리보기만 변경되고 저장 버튼 클릭 시 실제 반영되도록 수정
+- **공개 티어표 목록 개선**: 공개 티어표 목록에 작성자 닉네임(없으면 이메일) 표시
+- **관리자 UI 개편**: 게임 선택 전에는 우측 관리 패널을 숨기고, 선택 후에만 썸네일/아이템 관리가 보이도록 단계형 흐름으로 수정
+- **관리자 레이아웃 수정**: 새 게임 입력 필드와 카드 셀 overflow 문제를 줄이도록 `box-sizing`, 썸네일/아이템 카드 레이아웃 정리
+- **커스텀 아이템 저장 흐름 수정**: 에디터의 커스텀 이미지는 저장 시 서버 업로드 후 티어표에 반영되도록 변경
+
+## 2026-03-19 v0.1.5
+- **로컬 개발 환경 정렬**: 기본 백엔드 실행 기준을 lowdb가 아닌 로컬 MariaDB로 전환
+- **개발용 인프라 추가**: 루트 `docker-compose.yml`에 `MariaDB + phpMyAdmin` 추가
+- **실행 문서 정리**: `README.md`, `docs/local-mariadb.md`, `docs/spec.md`에 로컬 MariaDB 실행 절차 반영
+- **Fallback 분리**: `backend/package.json`에 `dev:lowdb`, `start:lowdb` 예외 스크립트 추가
+
+## 2026-03-19 v0.1.6
+- **저장소 메타데이터 정리**: Git 작성자 정보를 프로젝트 계정 기준으로 통일하고, 초기 릴리스 커밋 메시지를 한국어 기준으로 재작성
+- **버전 관리 규칙 보강**: 커밋 메시지 한국어 작성 및 문서 버전과 Git 태그를 함께 맞추는 규칙을 문서에 반영