219 lines
10 KiB
Markdown
219 lines
10 KiB
Markdown
# 기술 명세
|
|
|
|
## 프로젝트 개요
|
|
|
|
- 서비스명: `UNIARE - Union Arena Deck Builder`
|
|
- 현재 버전: `v4.0.11`
|
|
- 프론트: 정적 HTML, CSS, JavaScript
|
|
- 백엔드: Express, SQLite(`better-sqlite3`)
|
|
- 운영: Docker Compose 기반 Nginx + API
|
|
- 지원 언어: 한국어, 일본어, 영어
|
|
- 표시 브랜드는 `UNIARE`이며 `UaDeckApi`, `uadeck_token`, `uadeck.db` 등 내부 레거시 식별자는 호환을 위해 유지한다.
|
|
|
|
## 화면 기능
|
|
|
|
| 경로 | 기능 |
|
|
|---|---|
|
|
| `/` | 시리즈 선택, 언어 전환, 인증 헤더 |
|
|
| `/cardList.html?series=<key>` | 카드 검색·필터, 수량 조절, 키 카드 지정, 덱 편집 |
|
|
| `/cardList.html?d=<shareCode>` | API 공유 덱 불러오기 및 편집 |
|
|
| `/result.html` | 덱 미리보기, PNG 다운로드, 회원 덱 저장 |
|
|
| `/login.html` | 로그인 |
|
|
| `/signup.html` | 회원가입 |
|
|
| `/profile.html` | 이메일·사용자명·아바타·비밀번호·덱 공개 기본값 관리 |
|
|
| `/deckHistory.html` | 내 덱 검색·필터·이름 변경·공개 설정·삭제·불러오기 |
|
|
| `/preset.html` | 공개 사용자 덱 검색·필터·즐겨찾기·불러오기 |
|
|
| `/admin.html` | 회원과 덱 관리 |
|
|
| `/d/<shareCode>` | Nginx에서 `cardList.html?d=<shareCode>`로 연결 |
|
|
|
|
## 검색 노출
|
|
|
|
- 메인 검색 제목은 `UNIARE | 유니온 아레나 덱 빌더`를 사용한다.
|
|
- 메인 설명은 카드 검색, 덱 제작·저장·공유, 공개 덱과 즐겨찾기 기능을 안내한다.
|
|
- JavaScript 실행 전에도 메인 제목과 설명이 HTML에 표시된다.
|
|
- canonical, Open Graph, Twitter Card, WebSite·WebApplication 구조화 데이터를 제공한다.
|
|
- 번역 파일 로딩 실패 시 내부 오류 대신 새로고침 안내를 표시한다.
|
|
|
|
## 카드 데이터
|
|
|
|
- 데이터 위치: `datas/*.js`
|
|
- 실제 시리즈 데이터: `ua01`~`ua54` 중 현재 존재하는 파일과 `uapr.js`
|
|
- 샘플 데이터: `ua99 sample.js`, `ua99 sample mini.js`
|
|
- 모듈 형식: `export const cardList = [...]`
|
|
|
|
```js
|
|
{
|
|
imgSrc: '/ua24/UA24BT_SHY-1-001.png',
|
|
Number: 'UA24BT/SHY-1-001',
|
|
count: 0,
|
|
key: false,
|
|
color: 'Red',
|
|
parallel: false,
|
|
rarity: 'C',
|
|
trigger: null,
|
|
maxCount: 4,
|
|
}
|
|
```
|
|
|
|
- `Number`가 같은 판본은 동일 카드 수량 그룹으로 처리한다.
|
|
- `parallel`은 패러렐 판본 구분에 사용한다.
|
|
- `trigger`는 `null`, `COLOR`, `FINAL`, `SPECIAL` 값을 사용한다.
|
|
- `maxCount`가 없으면 기본 최대 수량은 4장이다.
|
|
|
|
## 이미지
|
|
|
|
- 카드 이미지: `images/<seriesKey>/<fileName>`
|
|
- 폴백 이미지: `/images/uapr/comingsoon.png`
|
|
- 브랜드 자산: `images/assets/`
|
|
- `images/**`는 Git LFS로 관리한다.
|
|
- 아바타와 덱 미리보기는 API 데이터 디렉터리에 저장하며 Git에 포함하지 않는다.
|
|
- 덱 저장 미리보기는 1200px 기준 PNG로 정규화한다.
|
|
- 덱 삭제 시 해당 공유 코드의 미리보기 PNG도 함께 삭제한다.
|
|
- 관리자는 DB에서 참조하지 않는 미리보기 파일을 조회하고 일괄 삭제할 수 있다.
|
|
|
|
## 브라우저 상태
|
|
|
|
| 키 | 용도 |
|
|
|---|---|
|
|
| `lang` | 선택 언어 |
|
|
| `selectedCards` | 편집 중인 덱 |
|
|
| `selectedSeries` | 현재 시리즈 |
|
|
| `uadeck_token` | JWT. 로그인 유지 선택 시 `localStorage`, 미선택 시 `sessionStorage` |
|
|
| `uadeck_user` | 로그인 사용자 캐시. 토큰과 같은 저장소 사용 |
|
|
| `uadeck.deckFavorites` | 비로그인 즐겨찾기 및 로그인 시 최초 이전 대상 |
|
|
|
|
## 인증 및 권한
|
|
|
|
- 비밀번호는 bcrypt 비용 12로 해시한다.
|
|
- JWT 기본 만료는 7일이며 `JWT_EXPIRES`로 변경할 수 있다.
|
|
- 로그인 유지 선택 시 브라우저를 닫아도 인증 정보를 유지하고, 미선택 시 현재 브라우저 세션에서만 유지한다.
|
|
- 인증된 화면 진입 시 `/auth/me` 검증과 함께 `last_login_at`을 갱신한다.
|
|
- `user`는 자신의 프로필과 덱만 수정·삭제할 수 있다.
|
|
- `admin`은 회원 상태·역할·비밀번호와 전체 덱을 관리할 수 있다.
|
|
- 관리자는 자신의 관리자 역할을 해제하거나 자신의 계정을 비활성화할 수 없다.
|
|
- 비공개 덱은 소유자와 관리자만 조회할 수 있다.
|
|
- 비회원은 덱을 서버에 저장하거나 공개 링크를 생성할 수 없다.
|
|
- 로그인 사용자의 즐겨찾기는 계정 DB에 저장되어 브라우저와 기기가 달라도 유지된다.
|
|
- 비로그인 즐겨찾기는 브라우저에 저장하고 로그인 시 유효한 덱만 계정으로 이전한다.
|
|
|
|
## 덱 저장 정책
|
|
|
|
- 공유 코드는 저장 시 생성되는 8자 코드다.
|
|
- 덱 저장과 공개 링크 생성은 로그인한 회원만 사용할 수 있다.
|
|
- 비회원은 덱 구성과 PNG 이미지 다운로드만 사용할 수 있다.
|
|
- 기존 비회원 공유 덱은 호환을 위해 원래 만료일까지 조회할 수 있다.
|
|
- DB의 `cards_json`에는 `{number, count, key}`만 저장한다.
|
|
- API 응답 시 `datas/<series>.js`에서 이미지·색상·희귀도·트리거 정보를 합성한다.
|
|
- 공개 덱 목록은 `share_type='user'`, `is_public=1`, 미만료 조건을 사용한다.
|
|
- `preset` 타입과 관리자 프리셋 API는 레거시 호환용으로 코드에 남아 있으며 현재 공개 덱 화면에서는 사용하지 않는다.
|
|
|
|
## 데이터베이스
|
|
|
|
### `users`
|
|
|
|
| 컬럼 | 설명 |
|
|
|---|---|
|
|
| `id` | 기본 키 |
|
|
| `email`, `username` | 고유 로그인·표시 식별자 |
|
|
| `password_hash` | bcrypt 해시 |
|
|
| `display_name` | 레거시 표시명, 현재 `username`과 함께 갱신 |
|
|
| `avatar_url` | 아바타 API 경로 |
|
|
| `role` | `user` 또는 `admin` |
|
|
| `is_active` | 계정 활성 상태 |
|
|
| `default_deck_public` | 덱 저장 기본 공개 여부 |
|
|
| `skip_deck_public_prompt` | 저장 시 공개 확인 생략 여부 |
|
|
| `last_login_at` | 마지막 로그인 또는 인증 세션 확인 시각 |
|
|
| `created_at`, `updated_at` | 생성·수정 시각 |
|
|
|
|
### `decks`
|
|
|
|
| 컬럼 | 설명 |
|
|
|---|---|
|
|
| `share_code` | 고유 공유 코드 |
|
|
| `share_type` | `user` 또는 레거시 `preset` |
|
|
| `content_hash` | 레거시 프리셋 중복 판별 |
|
|
| `user_id` | 소유 회원, 과거 비회원 덱은 `null` |
|
|
| `series`, `series_name` | 시리즈 키와 표시명 |
|
|
| `name` | 덱 이름 |
|
|
| `cards_json` | 최소 카드 구성 JSON |
|
|
| `is_public` | 공개 여부 |
|
|
| `view_count` | 상세 조회 횟수 |
|
|
| `expires_at` | 과거 비회원 공유 덱의 만료 시각 |
|
|
| `preview_image` | 저장된 미리보기 파일 정보 |
|
|
| `created_at`, `updated_at` | 생성·수정 시각 |
|
|
|
|
### `deck_favorites`
|
|
|
|
| 컬럼 | 설명 |
|
|
|---|---|
|
|
| `user_id` | 즐겨찾기 사용자, 사용자 삭제 시 함께 삭제 |
|
|
| `share_code` | 즐겨찾기 덱, 덱 삭제 시 함께 삭제 |
|
|
| `created_at` | 즐겨찾기 등록 시각 |
|
|
|
|
## API
|
|
|
|
### 공통
|
|
|
|
| Method | Path | 권한 | 기능 |
|
|
|---|---|---|---|
|
|
| GET | `/api/v1/health` | 공개 | API 상태와 버전 |
|
|
|
|
### 인증
|
|
|
|
| Method | Path | 권한 | 기능 |
|
|
|---|---|---|---|
|
|
| POST | `/api/v1/auth/register` | 공개 | 회원가입 |
|
|
| POST | `/api/v1/auth/login` | 공개 | 로그인과 JWT 발급, `last_login_at` 갱신 |
|
|
| GET | `/api/v1/auth/me` | 회원 | 내 정보와 인증 세션 확인, `last_login_at` 갱신 |
|
|
| PUT | `/api/v1/auth/me` | 회원 | 프로필·덱 저장 설정 변경 |
|
|
| POST | `/api/v1/auth/me/password` | 회원 | 비밀번호 변경 |
|
|
| GET | `/api/v1/auth/avatar/:userId` | 공개 | PNG 아바타 |
|
|
|
|
### 덱
|
|
|
|
| Method | Path | 권한 | 기능 |
|
|
|---|---|---|---|
|
|
| GET | `/api/v1/decks/presets` | 공개 | 공개 사용자 덱 목록 |
|
|
| GET | `/api/v1/decks/:shareCode/preview` | 공개 | 덱 미리보기 PNG |
|
|
| GET | `/api/v1/decks/:shareCode` | 조건부 | 공개 덱 또는 소유 덱 상세 |
|
|
| GET | `/api/v1/decks` | 회원 | 내 덱 목록 |
|
|
| POST | `/api/v1/decks` | 회원 | 내 덱 저장과 공개 링크 생성 |
|
|
| PUT | `/api/v1/decks/:shareCode` | 소유자·관리자 | 덱 수정 |
|
|
| DELETE | `/api/v1/decks/:shareCode` | 소유자·관리자 | 덱 삭제 |
|
|
| GET | `/api/v1/decks/favorites` | 회원 | 내 즐겨찾기 코드 목록 |
|
|
| POST | `/api/v1/decks/favorites` | 회원 | 브라우저 즐겨찾기 일괄 이전 |
|
|
| PUT | `/api/v1/decks/favorites/:shareCode` | 회원 | 즐겨찾기 추가 |
|
|
| DELETE | `/api/v1/decks/favorites/:shareCode` | 회원 | 즐겨찾기 제거 |
|
|
|
|
### 관리자
|
|
|
|
| Method | Path | 기능 |
|
|
|---|---|---|
|
|
| GET | `/api/v1/admin/users` | 회원 목록·검색 (`deckPublic`, `deckTotal`, `lastLoginAt` 포함) |
|
|
| GET | `/api/v1/admin/users/:id` | 회원 상세 (`deckPublic`, `deckTotal`, `deckCount`, `lastLoginAt` 포함) |
|
|
| PUT | `/api/v1/admin/users/:id` | 회원 정보·역할·활성 상태 변경 |
|
|
| POST | `/api/v1/admin/users/:id/reset-password` | 비밀번호 초기화 |
|
|
| GET | `/api/v1/admin/decks` | 전체 덱 목록 |
|
|
| DELETE | `/api/v1/admin/decks/:shareCode` | 덱 삭제 |
|
|
| GET | `/api/v1/admin/previews/orphans` | 미참조 덱 미리보기 목록 |
|
|
| DELETE | `/api/v1/admin/previews/orphans` | 미참조 덱 미리보기 일괄 삭제 |
|
|
| POST | `/api/v1/admin/decks/preset` | 레거시 프리셋 생성 |
|
|
|
|
## 스타일
|
|
|
|
- 현재는 Tailwind 유틸리티, 공통 CSS, 페이지 전용 CSS, 일부 인라인 스타일을 혼용한다.
|
|
- 기존 CSS는 `todo.md`의 화면별 체크리스트 순서에 따라 점진적으로 Tailwind로 전환한다.
|
|
- 관리자와 로그인·회원가입 화면은 Tailwind 전환을 완료하고 전용 CSS를 제거했다.
|
|
- 관리자 탭·모달 상태는 JavaScript에서 `border-*`, `text-*`, `hidden`, `flex` 유틸리티를 전환한다.
|
|
- 덱 카드·툴바·프로필·앱 셸 스타일은 `style/components.css`(`@layer components`)에 통합되어 `output.css`로 빌드된다.
|
|
- `style/output.css`는 `style/input.css`에서 생성하는 빌드 산출물이다.
|
|
- 헤더 로고 크기는 `style/brand.css`만 기준으로 사용한다.
|
|
- 기본 글꼴은 Pretendard 계열을 우선 사용한다.
|
|
|
|
## 알려진 제약
|
|
|
|
- `cardList.html`, `result.html`의 인라인 스크립트가 커서 변경 영향 범위가 넓다.
|
|
- `admin.html`은 3개 언어 번역 적용이 완료되지 않았다.
|
|
- Homepage 전용 `GET /api/homepage` 엔드포인트는 아직 구현되지 않았다.
|
|
- 현재 Compose의 컨테이너명(`uniare-api`, `uniare-web`)과 데이터 볼륨명(`uniare-data`)은 고정값이며 환경 변수화되지 않았다.
|