도감 (Dogam)

트레이딩 카드·포토카드·피규어 등 수집품을 IP · 시리즈 · 아이템 계층으로 관리하는 웹 앱. 보유 현황 추적, 레어도 시각 효과, 앨범 큐레이션, 가중치 기반 수집률 통계, 슬리브/카드 규격 관리를 제공한다.

• 계층형 컬렉션 관리 — IP → 시리즈 → 아이템 구조로 수집품을 정리
• 보유 현황 추적 — 보유/미보유, 수량, 구매가, 상태, 획득일 기록
• 레어도 시스템 — 12종 시각 효과(EffectOverlays), 프레임, 가중치 기반 수집률 + 고급 커스텀 CSS(실제 CSS·&/::before/@keyframes를 레어도별 스코프 주입)
• 인앱 위키(도움말) — 헤더 📖 버튼으로 Wiki/ 문서를 앱 안에서 열람(marked 렌더)
• 세트(Set) — 시리즈 템플릿/공유 — 한 팩의 카드 목록을 재사용 단위로 만들어 ① 시리즈로 적용, ② .dogamset.json 파일 공유(내보내기/가져오기), ③ 아이템 이름 자동완성에 활용 (→ 세트 기능)
• 변형 그룹 보기 — 같은 번호(레어도 변형)를 한 그룹으로 묶어 보기(그리드·리스트 공통 토글)
• 아이템 대량 추가 — 빠른 연속 입력 + 링크 크롤링 가져오기, 같은 이름 자동 그룹화(bulkadd.jsx)
• 앨범 큐레이션 — 아이템을 자유롭게 묶어 테마 앨범 구성
• 이미지 업로드 — 서버에서 WebP 재인코딩(max 1200px, q82), 크롭 지원
• 슬리브 / 카드 규격 — 슬리브·키트·카드 표준 규격 관리(sleeve.jsx)
• 인증 — 로컬 계정 + Kakao / Google OAuth, 사용자별 데이터 격리
• 테마 & Tweaks — 다크/라이트 테마, 실시간 UI 실험용 Tweaks 패널

              ┌──────────────────────── Docker Compose ────────────────────────┐
브라우저 ──▶  │  nginx (dogam-app, :3000→80)                                     │
              │   ├─ 정적 서빙: frontend/Dogam.html + *.jsx (Babel 런타임 변환)  │
              │   ├─ /uploads/  → 볼륨 이미지 직접 서빙                          │
              │   └─ /api/      → 프록시 ─────────────┐                          │
              │                                       ▼                          │
              │  Hono API (dogam-api, :3001 내부)  ── SQLite + /uploads 볼륨     │
              └─────────────────────────────────────────────────────────────────┘

프론트엔드는 빌드 단계가 없다. 브라우저에서 Babel Standalone이 <script type="text/babel"> JSX를 런타임 변환한다. 파일 수정 후 새로고침만으로 반영된다(프로덕션 성능 비용은 감수 사항).

사전 요구: Docker Desktop (Compose v2).

# 1) 시크릿 설정
cp .env.example .env
#   .env 의 JWT_SECRET / JWT_REFRESH_SECRET 를 실제 랜덤 값으로 교체 (필수)
#   (선택) KAKAO_* / GOOGLE_* 에 OAuth 키 입력 — 미설정 시 소셜 로그인만 비활성

# 2) 빌드 후 실행  ── ⚠️ 항상 --build 권장
docker compose up -d --build

# 3) 접속
#   http://localhost:3000   (API 는 동일 오리진 /api 로 프록시)

# 중지
docker compose down

JWT 시크릿 생성 예시:

node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"

--build 를 빼지 말 것. docker compose up 만 하면 이전 이미지(옛 정적 파일·옛 nginx.conf)가 재사용되어 변경이 반영되지 않으며, 이는 403 Forbidden 의 흔한 원인이다. (트러블슈팅 참고)

npx http-server ./frontend -p 3000 --mime '{"jsx":"text/javascript"}'

비로그인 상태에서는 frontend/data.jsx 의 샘플 데이터(INITIAL_DB)로 동작한다.

.env 는 .gitignore 에 포함되어 커밋되지 않는다. 실제 시크릿을 저장소에 올리지 말 것.

dogam/
├── frontend/            # 프론트엔드 정적 파일 (nginx 가 그대로 서빙, 빌드 없음)
│   ├── Dogam.html       #   진입점 — 스크립트 로드 순서 정의
│   ├── app.jsx          #   앱 마운트 · reducer · 라우팅 · API 레이어(apiFetch)
│   ├── theme.jsx        #   디자인 토큰 · 레어도 헬퍼 · 프리셋
│   ├── data.jsx         #   샘플 데이터(INITIAL_DB) — 비로그인 폴백
│   ├── atoms.jsx        #   공통 원자 컴포넌트
│   ├── rarity.jsx       #   레어도 효과 · RarityEditor
│   ├── modals.jsx       #   모달 (Crop/Lightbox/IP/Series/Item …)
│   ├── sets.jsx         #   세트(시리즈 템플릿) 라이브러리·편집·적용 마법사
│   ├── bulkadd.jsx      #   아이템 대량 추가(빠른 입력 / 링크 가져오기)
│   ├── screens.jsx      #   화면 (탭·상세 뷰·변형 그룹)
│   ├── sleeve.jsx       #   슬리브/키트/카드 규격 화면
│   ├── admin.jsx        #   마스터 관리자 패널
│   ├── help.jsx         #   인앱 위키 뷰어 (헤더 📖 도움말)
│   └── tweaks-panel.jsx #   개발용 Tweaks 패널
├── backend/             # Hono(TS) API 서버 + SQLite  → docs/10-backend.md
│   └── src/{db,lib,middleware,routes}/
├── nginx.conf           # 정적 서빙 + /api 프록시 + /uploads + JSX MIME
├── Dockerfile           # nginx 이미지 (frontend/ 복사)
├── Dockerfile.api       # Node API 이미지 (멀티스테이지 tsc 빌드)
├── docker-compose.yml   # api + nginx 2서비스
├── .env.example         # 환경 변수 템플릿
├── data/                # 런타임 볼륨: SQLite + 업로드 이미지 (gitignore)
└── docs/                # 개발 문서(01~14·CHANGELOG·점검리포트) · 기획서 · 레퍼런스 · 스크린샷

베이스: /api · 데이터 라우트는 모두 Authorization: Bearer <token> 필수, user_id 스코프.

전체 엔드포인트·DB 스키마·인증 흐름은 docs/10-backend.md 참고.

시리즈 상세에서 ⊞ 대량 추가 버튼으로 여러 아이템을 한 번에 추가한다.

• 빠른 입력: 이름·레어도·타입·번호를 한 줄로 입력하고 Enter 로 연속 추가. 이름 접두사·번호 자동 증가 옵션. 목록에 쌓아 한 번에 저장.
• 링크 가져오기: 상품 페이지 URL 을 붙여넣으면 서버가 크롤링해 수록 카드 목록을 추출 → 체크박스로 선택 + 한글 레어도 매핑(현재 IP 레어도 풀로 연결) 후 저장. **📚 세트로 저장**으로 크롤링 결과를 재사용 가능한 세트로 만들 수도 있다.
  • tcgshop.co.kr 지원, 그 외 사이트는 표/카드코드 휴리스틱(범용 폴백). SSRF 가드 적용.
• 같은 이름 자동 그룹화: 같은 이름·다른 레어도 항목은 같은 번호(sequence)를 부여받아, 시리즈에서 변형 그룹으로 묶여 표시된다(대기 목록에서 그룹이 좌측 바로 시각화).
• 저장은 POST /api/items/bulk(트랜잭션)로 DB 영속화 — 새로고침해도 유지된다.

"미리 준비된 한 팩의 카드 목록"을 세트라는 재사용 단위로 만들어 공유·복제·자동완성에 쓴다. (IP 상세 → 📚 세트 버튼으로 라이브러리 진입)

• 라이브러리/편집 — 내장(공유) 세트 + 개인 세트를 검색·카테고리로 탐색, 직접 만들고 편집(내장은 읽기전용).
• 시리즈로 적용 — 세트의 ▶ 적용 → 대상 IP 선택/생성 + 레어도 매핑 → 시리즈 + 아이템 일괄 생성 (실패 시 자동 롤백). 적용한 세트에 새 버전이 생기면 시리즈에 ⬆ 세트 업데이트 배지가 떠 신규 항목만 추가.
• 공유 — 세트를 .dogamset.json 으로 내보내기/가져오기. 전체 백업(설정 탭 JSON)에도 자동 포함.
• 이름 자동완성 — 아이템 추가(단건/빠른 입력) 시 이름을 입력하면 세트 항목에서 레어도·번호 등을 채워준다.
• API: … /api/sets (CRUD). 적용·자동완성은 기존 /series·/items/bulk 재사용.

설계·데이터 모델·진행 현황은 docs/12-sets.md · docs/13-sets-status.md 참고.

영속성: 이제 IP·시리즈·아이템·앨범의 추가/수정/삭제가 모두 백엔드 DB 에 저장된다 (enhancedDispatch 동기화 레이어 + 엔티티별 extra JSON 컬럼으로 thumbnail/banner/ numberPattern/sequence 등 클라이언트 전용 필드까지 손실 없이 보존). 슬리브 DB 탭(슬리브/키트/규격)은 후속 영속화 대상이다.

• 처음 가입한 사용자가 자동으로 "마스터" 가 되고, 이후 가입자는 모두 "일반 사용자" 다. (로컬·소셜 어느 경로든 전체 사용자 0명일 때 첫 가입 → 마스터)
• 마스터는 헤더의 👑 버튼으로 관리자 패널에 들어가 다음을 할 수 있다:

안전장치: 항상 마스터 1명 유지(직접 강등·삭제·정지 불가, 이양만 가능), 자기 자신 정지/삭제 금지, 정지 시 즉시 강제 로그아웃, 가입 'closed' 라도 최초 1명은 항상 가입 가능. 마스터는 계정만 관리하며 타인의 컬렉션 내용은 보지 않는다(집계 수치만).

기존 DB(역할 도입 전)는 마이그레이션 시 가장 먼저 가입한 사용자가 마스터로 승격된다.

대부분 다음 중 하나다.

0. 파일 권한 (13: Permission denied) — nginx 로그에 open() ".../Dogam.html" failed (13: Permission denied) 가 보이면, Windows 호스트에서 COPY 된 정적 파일에 "others read" 비트가 빠져 nginx 워커(user nginx)가 못 읽는 경우다. → Dockerfile 에 RUN chmod -R a+rX /usr/share/nginx/html 로 해결됨. 수정 후 재빌드 필요.
1. 옛 이미지 재사용 — docker compose up 을 --build 없이 실행해 이전 정적 파일/nginx.conf 가 남아 있는 경우.

   docker compose down
   docker compose up -d --build

2. nginx 디렉터리 인덱스 trap — try_files … $uri/ … 가 인덱스 없는 디렉터리에서 403을 반환. → 현재 nginx.conf 는 $uri/ 제거 + location = / 명시 매핑으로 해결됨.
3. 정규식 location 우선순위 — 이미지 정규식 location 이 /uploads/·/api/ 보다 먼저 매칭되어 업로드 이미지가 깨짐(404). → 현재 nginx.conf 는 /uploads/·/api/ 를 ^~ 로 우선 매칭하여 해결됨.

JWT_SECRET·JWT_REFRESH_SECRET 미설정 시 의도적으로 부팅 실패한다. .env 를 확인할 것.

docker compose logs api      # 원인 확인

1. nginx alias + try_files 버그 — 해결됨(root /app 사용).
2. NAS 확장 ACL(Synology 등) — 파일이 /app/uploads/... 에 분명히 있는데도 nginx 로그에 stat() "..." failed (13: Permission denied) 가 찍히면, 볼륨의 확장 ACL 이 컨테이너의 nginx(uid 101) 접근을 막는 경우다(모드비트가 777 이어도 ACL 이 우선). → nginx Dockerfile 에서 워커를 root 로 실행(sed -i 's/^user .*/user root;/' …)해 해결. (api 가 root 로 같은 볼륨에 정상 기록하므로 root 접근은 보장됨.) 진단: docker compose logs --tail=20 dogam | grep stat 로 stat() ... (13: Permission denied) 확인.

사용자·기획 안내(위키) → Wiki/ — 프로젝트 기획, 기능별 설명·유용성·예시, 사용 시나리오, FAQ. 같은 문서를 두 경로로 볼 수 있습니다(둘 다 Wiki/*.md 단일 소스):

• 앱 안 — 헤더 📖 도움말 (배포 환경)
• 독립 공개 페이지 — 배포 오리진의 /wiki/ (예: http://localhost:3000/wiki/) — 앱·로그인 없이 링크로 열람·공유. 각 문서는 …/wiki/#<파일명> 해시 URL로 딥링크된다.

모든 개발/기술 문서는 docs/ 폴더에 통합되어 있습니다(개발 명세 + 기획서·레퍼런스 + 변경 이력 + 점검 리포트).

전 쿼리 prepared statement, 데이터 라우트 requireAuth + user_id 스코프(IDOR 방어), JWT 시크릿 프로덕션 강제, refresh 토큰 회전·SHA-256 해시 저장, scrypt 비밀번호 + timingSafeEqual, 로그인·회원가입 rate limiting, 업로드 sharp 재인코딩 + path traversal 방지, OAuth 토큰 fragment 전달·state DB 관리. 자세한 점검 내역은 docs/점검리포트-2026-06-02.md.

후속 권장: OAuth 키 실값 설정, rate-limit 공유 스토어 이전(다중 인스턴스), 파일 저장소 S3/R2 전환, 프론트 사전 빌드 파이프라인 도입.