👾 PIXEL MART

일상에 아이템을 장착하세요. 게임을 좋아하는 사람을 위한 픽셀아트 게이밍 데스크 소품 쇼핑몰 + 같은 취향의 동네 이웃과 아이템을 주고받는 PIXEL LOCAL

2차 프로젝트 (2026.10.23 ~ 10.28): 1차에서 인수한 PIXEL MART를 FastAPI 4계층 백엔드로 다시 세우고, 네 명이 각자 Use Case 하나를 화면부터 DB까지 끝까지 만들었어요.

목차

1. 서비스 소개
2. 팀 · 역할
3. 인수 기준
4. 개발 방향과 변경 전·후
5. 기존 app/ vs 이번 src/
6. 4계층 구조도 · 요청 흐름
7. 실행 (uv) · 환경 변수
8. DB 준비
9. 개인별 Use Case
10. 미완료 · Mock 목록
11. 에러 처리 · 보안 · 테스트
12. 부록: 1차 결과물

자료 위치

자료	주소
GitHub 저장소	https://github.com/KANT-2/pixel-mart-v2
배포 (Vercel + Render)	https://pixel-mart-v2.vercel.app
Swagger	배포 https://pixel-mart-v2.vercel.app/api/docs · 로컬 http://localhost:3000/api/docs
CI (GitHub Actions)	https://github.com/KANT-2/pixel-mart-v2/actions/workflows/ci.yml
팀 Notion	(제출 링크 추가 예정)
발표자료	(제출 링크 추가 예정)

1. 서비스 소개

항목	내용
한 줄	취향 기반 커뮤니티 커머스: 쇼핑으로 아이템을 "장착"하고, PIXEL LOCAL에서 같은 동네 덕후를 발견해 주고받고, 그 활동이 하트·뱃지로 쌓여 신뢰가 돼요
대상	게임·서브컬처를 좋아하는 20~30대, 책상을 꾸미고 굿즈를 모으는 사람
콘셉트	다크 아케이드 · 8비트 픽셀아트 · 연두 네온 포인트 · 게임 HUD(하트·코인·퀘스트)
쇼핑	상품 검색·정렬·필터, 상품 상세(포토 리뷰·문의), 찜, 장바구니, 가상 주문(재고·배송비), 배송지·주소 검색, 쿠폰·적립금, 결제수단, 운송장 조회, 취소·구매 확정·반품/교환
플레이어	이메일 가입·로그인, 비밀번호 변경·재설정, 구글 로그인, 픽셀 아바타, 퀘스트·뱃지
PIXEL LOCAL	덕력지도 · 위시맵 · 거래·교환 · 이웃 선물
관리자	주문 배송 단계·취소 처리, 운송장·반품/교환, 상품 문의 답변, 회원·거래글·신고·뱃지·상품·공지·FAQ
범위 밖	실제 결제, 데스크 꾸미기·토너먼트

2. 팀 · 역할

네 명 모두 풀스택으로, 각자 Use Case 하나를 화면 → API → 도메인 규칙 → DB까지 직접 만들었어요.

역할	이름	Use Case	폴더	함께 맡은 일
🛡️ 기사	양성용 (@dydtlsrl)	장바구니에서 주문하기 (재고 · 배송비)	backend/src/orders/	공통 기반(uv · src/ 뼈대 · DB · 마이그레이션) · ERD
🧭 탐험가	채희주 (@kixxuya)	가입 · 로그인 · 로그아웃 (JWT 블랙리스트)	backend/src/auth/	모두가 쓰는 CurrentUser · AdminUser, README · Notion 틀
🏹 궁수	우동현 (@donghyunwoo1222)	관리자 주문 관리 (배송 단계 · 취소 승인/거절)	backend/src/admin_orders/	/admin 화면 틀 (메뉴 · 문지기)
🔮 마법사	김예주 (@kyeju)	상품 문의 → 관리자 답변 (비밀글)	backend/src/questions/	손님 화면 진짜 데이터 연결

팀원별 기여 (2026.10.28 origin/main 기준 · 커밋은 인수 커밋 38720a6 이후, GitHub 화면에서 누른 머지 커밋 포함)

팀원	담당 UC	커밋 수	머지한 PR 수	대표 PR
양성용	주문하기 (재고 · 배송비)	56	21	#43 4계층 기반 · #65 주문 트랜잭션 · #81 동시 주문 재고
채희주	가입 · 로그인 · 로그아웃	109	47	#49 가입·로그인·로그아웃 서비스 · #50 블랙리스트 로그아웃 · #158 배포
우동현	관리자 주문 관리	63	27	#72 단계 넘기기·취소 서비스 · #84 취소 요청 화면 · #171 CSV · 알림 후처리
김예주	상품 문의 → 관리자 답변	49	23	#73 문의 서비스 · #77 관리자 답변 API · #78 Q&A 실제 API 연결
1차 팀 (인수 이전)	—	361	—	황정민 50 · 안중섭 30 · 여름 8 · 채희주 273 (1차 저장소에서 옮겨 온 기록)

• 같은 사람의 다른 이름을 합쳤어요: b3matego(이메일이 dydtlsrl noreply) → 양성용 · donghyunwoo1222 · 본인 이름(같은 이메일) → 우동현. 다시 세기: git log 38720a6..origin/main --format='%an' | sort | uniq -c

협업 규칙: main 직접 push 금지 → feat/* · docs/* 브랜치 → PR(Closes #이슈) → 머지. 마이그레이션은 기사만 만들어요 (uv run alembic heads가 항상 한 줄).

3. 인수 기준

• 인수 커밋: 38720a6 (1차 저장소 KANT-2/pixel-mart의 main을 그대로 옮겨 온 시점)
• 인수 당시 상태: Next.js 16 화면 전체 + FastAPI 단일 계층(backend/app/: routers · services · models), pip + requirements.txt, 구글 로그인과 개발용 로그인(쿠키 JWT, 로그아웃은 쿠키 삭제만), 관리자 기능은 개발자 API(/api/dev/...)로만
• 인수 상태의 화면·흐름 재현 기록: docs/backend/BASELINE_DAY1.md

4. 개발 방향과 변경 전·후

영역	인수 전 (38720a6)	2차 이후	담당	상태
구조	app/ 한 층에 라우터·서비스·모델	새 기능은 src/<기능>/ 4계층, 도메인은 순수 파이썬	모두	✅
패키지 · 실행	pip · requirements.txt · Python 3.12	uv · pyproject.toml · uv.lock · Python 3.13+	🛡️	✅
서버 기반	앱 생성만	lifespan(DB 확인·정리) · 요청 로깅 미들웨어 · 공통 예외 → HTTP	🛡️	✅
DB	재고·배송비·역할·비밀번호 칸 없음	products.stock · orders.shipping_fee · users.role · users.password_hash · token_blacklist (마이그레이션 ①)	🛡️	✅
가입 · 로그인	구글 · 개발용 로그인만	이메일 가입(bcrypt 해싱) · OAuth2 로그인(/api/auth/token, Swagger Authorize)	🧭	✅
로그아웃	쿠키만 삭제 (복사한 토큰은 7일간 유효)	토큰 jti를 블랙리스트에 → 같은 토큰은 401 (구글·개발용 로그인 포함)	🧭	✅
권한	로그인 확인만	CurrentUser(Bearer · 쿠키) · AdminUser(관리자 아니면 404). 기존 API도 같은 검사	🧭	✅
관리자 회원	없음	회원 목록 (검색 · 역할 필터 · 페이지)	🧭	✅
주문	app/ 서비스가 재고·배송비 없이 주문 저장	src/orders/ 4계층으로 재고 차감(품절·부족 409) · 3만 원 이상 무료 배송 · 생성 전체 트랜잭션 · 상태/검색/페이지 목록	🛡️	✅
관리자 주문	개발자 API(/api/dev/...)	/api/admin/orders · 배송 단계 한 칸씩 · 취소 승인(재고 복구)/거절 + /admin 화면	🏹	✅
상품 문의	화면은 새로고침하면 사라지는 메모리 데이터	DB 저장 · 비밀글은 서버에서 가림 · 관리자 답변 1회 · 답변 알림	🔮	✅
도전 A · 동시성	재고를 읽고 나서 줄임	재고는 stock >= 수량 조건부 UPDATE, 같은 사람 동시 주문 · 같은 취소 요청 동시 승인은 행 잠금() + 동시 요청 테스트

5. 기존 app/ vs 이번 src/

	backend/app/ (인수한 코드)	backend/src/ (2차에서 새로)
무엇	쇼핑 · PIXEL LOCAL · 아바타 등 1차 기능 전부	4개 Use Case + 공통 기반
구조	routers · services · models · schemas	<기능>/presentation · application · domain · infrastructure
앱	app/main.py는 src.main을 다시 내보내기만 해요	src/main.py가 앱을 조립 (기존 라우터 + 새 라우터)
로그인 확인	app/deps.py → src/common/auth.py를 다시 내보냄	src/common/auth.py (CurrentUser · OptionalUser · AdminUser)
DB	app/core/db.py → src/database.py를 다시 내보냄	src/database.py (비동기 엔진 · 세션 · Base)

새 기능은 src/에만 만들고, app/은 연결 한 줄씩만 고쳐요. 그래서 기존 API(장바구니 · 주문 등)도 새 인증(블랙리스트)을 그대로 받아요.

6. 4계층 구조도 · 요청 흐름

backend/src/
├─ main.py            앱 조립: lifespan · CORS · 로깅 · 예외 처리기 · 라우터
├─ database.py        비동기 엔진 · AsyncSession · Base
├─ common/            errors.py(예외 → HTTP) · auth.py(CurrentUser·AdminUser) · pagination.py · logging.py
└─ <기능>/            auth · orders · admin_orders · questions
   ├─ presentation/   라우터 · 요청/응답 스키마 (검증 · 호출 · 변환만)
   ├─ application/    서비스: 조회 → 도메인 → 저장 → commit (실패하면 rollback)
   ├─ domain/         규칙 · 상태 변경 (FastAPI · SQLAlchemy · Pydantic import 0개)
   └─ infrastructure/ Repository(ORM ↔ 도메인) · bcrypt · JWT

flowchart LR
  B["브라우저 :3000"] -->|"/api/* (Next rewrites)"| R["presentation<br/>라우터 · 스키마"]
  R -->|"CurrentUser · AdminUser"| A["common/auth.py<br/>서명 · 만료 · 블랙리스트"]
  R --> S["application<br/>서비스 · 트랜잭션"]
  S --> D["domain<br/>규칙 (순수 파이썬)"]
  S --> I["infrastructure<br/>Repository"]
  I --> DB[("PostgreSQL")]
  D -. "도메인 예외" .-> E["common/errors.py<br/>401 · 404 · 409 · 422"]

실패	상태 코드	예
입력 형식 · 규칙	422	비밀번호 7자, 빈 제목
인증	401	로그인 안 함, 틀린 비밀번호, 로그아웃한 토큰
권한 · 남의 것	404	일반 사용자의 관리자 API, 남의 주문
규칙 충돌	409	이미 가입한 이메일, 재고 부족, 두 번 답변

입력 형식 오류(422)는 공통 처리기가 "비밀번호: 8자 이상 입력해 주세요."처럼 필드 이름 + 한글 안내로 (필드를 모르면 "입력값을 확인해 주세요. …") 바꾸고, 보낸 입력값(비밀번호 등)을 응답에 다시 담지 않아요 (backend/src/common/errors.py).

7. 실행 (uv) · 환경 변수

준비물: Node.js 22+ · Python 3.13+ · uv · PostgreSQL(Docker Desktop 또는 설치형)

실제 사용 버전	로컬 (개발 PC)	CI (GitHub Actions)	기타
Python	3.14.7	3.13 (uv python install 3.13)	pyproject.toml requires-python >=3.13 · Render 3.13.1
Node.js	24.19	22
uv	0.13.5	astral-sh/setup-uv@v6	의존성은 uv.lock 고정 (uv sync --locked)
PostgreSQL	18 (docker-compose.yml)	16 (서비스 컨테이너)

git clone https://github.com/KANT-2/pixel-mart-v2.git
cd pixel-mart-v2

# 1) 백엔드 (backend/)
cd backend
uv sync                                                   # 가상환경 + 의존성 (uv.lock 그대로)
if (!(Test-Path .env)) { Copy-Item .env.example .env }    # 처음 한 번만
# → 8장 DB 준비 후
uv run uvicorn src.main:app --reload --port 8000

# 2) 프론트 (새 터미널, 저장소 루트)
npm ci
npm run dev

• 브라우저 http://localhost:3000 · API 문서(Swagger) http://127.0.0.1:8000/api/docs (오른쪽 위 Authorize로 로그인)
• DB 연결 확인: http://localhost:3000/api/health/db
• 로그인: /signup에서 이메일 가입, 또는 개발 환경의 개발용 로그인(이메일만). 테스트 계정은 *@pixelmart.test

환경 변수 (backend/.env): 실제 값은 저장소에 올리지 않아요 (.env.example에 이름만)

이름	설명
ENV	local이면 개발용 로그인 · 개발자 API 켜짐
DATABASE_URL	postgresql+asyncpg://… (Docker는 5433, 설치형은 5432)
JWT_SECRET	토큰 서명 비밀값 (아무 긴 문자열)
FRONTEND_URL	CORS 허용 주소 (http://localhost:3000)
GOOGLE_CLIENT_ID · GOOGLE_CLIENT_SECRET	구글 로그인 (비우면 구글 버튼만 꺼짐, 팀 채널로만 공유)
CLOUDFLARE_ACCOUNT_ID · CLOUDFLARE_API_TOKEN · CLOUDFLARE_IMAGE_MODEL · AI_AVATAR_PER_HOUR	AI 픽셀 아바타 (비우면 AI 만들기만 꺼짐)
ADMIN_EMAIL	배포 전용. 시작 스크립트(scripts/render_start.sh)가 이 이메일 계정을 make_admin으로 관리자로 지정 (먼저 가입한 계정, 비우면 건너뜀)
SHOWCASE_EMAIL	배포 전용. 이 계정(쉼표로 여러 개)에 발표 시연 데이터(주문 · 리뷰 · 문의 · 선물 · 교환 신청)를 seed_showcase로 채움 (한 번 로그인한 뒤부터, 비우면 건너뜀)

검사 명령	위치
uv run ruff check . · uv run pytest --ignore=tests/test_seed_demo.py · uv run alembic heads	backend/
npm run lint · npx tsc --noEmit · npm test · npm run build	저장소 루트

CI: main으로 가는 PR과 main push마다 GitHub Actions가 위 검사를 자동으로 돌려요 (.github/workflows/ci.yml, PostgreSQL 16 서비스 + alembic upgrade head + seed). tsc가 경로 타입(PageProps) 오류를 내면 npx next typegen을 먼저 실행해요.

빌드 재현성: main의 모든 머지 커밋은 CI에서 lint · tsc · test · build · ruff · alembic · pytest를 통과해야 머지돼요 (저장소 규칙 "main 보호": PR 필수 + frontend · backend 두 검사 필수) → Actions 실행 기록

배포 — #58

구성	서비스 (무료 요금제)	설정
프론트	Vercel	환경 변수 BACKEND_URL = 백엔드 주소 · vercel.json (싱가포르 리전)
백엔드 + DB	Render (Web Service + PostgreSQL)	render.yaml 블루프린트 · 시작 시 backend/scripts/render_start.sh

1. Render → New → Blueprint → 이 저장소 선택 → render.yaml대로 API 서버와 DB가 만들어져요. 시작할 때마다 alembic upgrade head → seed → seed_demo (재실행 안전)
2. Vercel → Add New → Project → 이 저장소 → 환경 변수 BACKEND_URL = https://<Render 서비스 주소> → Deploy
3. Render 환경 변수 FRONTEND_URL = Vercel 주소 → 저장(자동 재시작)
4. 배포 주소에서 이메일로 가입한 계정을 ADMIN_EMAIL에 넣으면 재시작 때 관리자가 돼요

환경 변수	배포 값	지키지 않으면
ENV	production	개발용 로그인 · 개발자 API(/api/dev/...)가 열려요. production이면 둘 다 404
JWT_SECRET	Render가 자동 생성	기본값이거나 32자 미만이면 서버가 시작을 거부해요
DATABASE_URL	Render DB와 자동 연결	postgres:// 주소는 postgresql+asyncpg://로 자동 변환
FRONTEND_URL	Vercel 주소	구글 콜백(<FRONTEND_URL>/api/auth/google/callback) · CORS
(프론트) BACKEND_URL	Render 주소	/api/* 전달이 안 돼요

• production에서는 로그인 쿠키가 secure(https 전용), 로그인 화면의 개발용 로그인 칸도 숨겨져요.
• API 문서(/api/docs · /api/openapi.json)는 production에서 관리자로 로그인한 사람만 열려요. 그 외에는 404
• 실제 키(구글 · Cloudflare)는 배포 서비스의 환경 변수 화면에만 넣어요. 비우면 그 기능만 꺼져요.
• Render 무료 서버는 15분 동안 요청이 없으면 잠들어요. 첫 요청은 30초 정도 걸려요.

8. DB 준비

# Docker를 쓸 때 (저장소 루트). 설치형 PostgreSQL이면 건너뛰기
docker compose up -d db

# backend/에서
uv run alembic upgrade head                      # 테이블 만들기 · 최신 마이그레이션
uv run python -m scripts.seed                    # 상품 · 지역 · 취향 · 키보드 (재실행 안전)
uv run python -m scripts.seed_demo               # 선택: 시연용 데모 이웃
uv run python -m scripts.make_admin 이메일        # 관리자 만들기 (먼저 한 번 가입·로그인한 계정)
uv run python -m scripts.purge_blacklist         # (가끔) 이미 만료된 로그아웃 토큰 줄 정리 — 만료 전 줄은 남겨서 401 그대로

• pytest는 지금 연결된 DB를 그대로 써요. 데모 이웃을 지우는 tests/test_seed_demo.py는 빼고 돌리고, 테스트 뒤 seed_demo를 다시 실행해 주세요.
• 스키마 · ERD (회원·주문·문의 + 추가 퀘스트, 현재 DB 기준): docs/backend/ERD_DAY1.md · docs/backend/SCHEMA.md

9. 개인별 Use Case

칸마다 흐름 · 관련 파일 · API · 정상/실패 결과 · 캡처 · 인수 전후 비교, 그리고 로그인 → 내 API 200 → 로그아웃 → 같은 토큰 401을 담았어요.

🛡️ 주문하기 (재고 · 배송비): 양성용

• UC 한 줄: 로그인 사용자가 장바구니 상품을 주문하면 서버가 재고와 배송비를 검증하고, 주문·상태 기록·알림·재고 차감·장바구니 비우기를 한 트랜잭션으로 확정합니다.

flowchart LR
  screen["화면<br/>/cart → /checkout"] --> api["API<br/>POST /api/orders"]
  api --> service["Application<br/>OrderService.place_order()"]
  service --> domain["Domain<br/>Order · summarize_prices()<br/>StockItem.take() 규칙"]
  service --> repo["Infrastructure<br/>OrderRepository"]
  repo --> db["PostgreSQL<br/>products · orders · order_items<br/>order_status_history · notifications · cart_items"]
  repo -->|"조건부 UPDATE 실패"| rollback["rollback<br/>주문·재고 그대로"]

• 관련 파일: 화면 components/cart/ · components/orders/CheckoutContents.tsx · 클라이언트 lib/cart.ts · lib/orders.ts · API backend/src/orders/presentation/ · 서비스 backend/src/orders/application/ · 도메인 backend/src/orders/domain/ · 저장소 backend/src/orders/infrastructure/

• 핵심 코드: 라우터 create_order → 서비스 OrderService.place_order → 도메인 summarize_prices · 배송비 기준 · StockItem.take → 저장소 조건부 UPDATE

🧭 가입 · 로그인 · 로그아웃: 채희주

• UC 한 줄: 이메일로 가입한 사용자가 로그인해 토큰을 받고, 로그아웃하면 그 토큰의 고유번호(jti)를 블랙리스트에 적어 같은 토큰으로는 다시 들어올 수 없게 합니다. 팀원 모두가 쓰는 로그인 확인 부품(CurrentUser · AdminUser)도 이 UC에서 만들었습니다.

flowchart LR
  screen["화면<br/>/signup · /login"] --> api["API<br/>POST /api/auth/signup · token · logout"]
  api --> service["Application<br/>AuthService"]
  service --> domain["Domain<br/>Account · IssuedToken<br/>check_password() · normalize_email()"]
  service --> infra["Infrastructure<br/>bcrypt hasher · JWT(jti)<br/>UserRepository · TokenBlacklistRepository"]
  infra --> db["PostgreSQL<br/>users · token_blacklist"]
  guard["common/auth.py<br/>CurrentUser · AdminUser"] -->|"서명 · 만료 · 블랙리스트 확인"| infra
  other["다른 팀원 API<br/>주문 · 관리자 · 문의"] --> guard

• 관련 파일: 화면 components/EmailSignupForm.tsx · components/LoginForm.tsx · components/AuthProvider.tsx · components/LoginRequiredNotice.tsx · 클라이언트 lib/api.ts · API backend/src/auth/presentation/ · 서비스 backend/src/auth/application/ · 도메인 backend/src/auth/domain/ · 저장소·도구 backend/src/auth/infrastructure/ (hasher.py · jwt.py · repositories.py) · 공용 의존성 backend/src/common/auth.py

• 핵심 코드: 라우터 · · → 서비스 · · → 도메인 · → 저장소 → 매 요청

🏹 관리자 주문 관리: 우동현

• UC 한 줄: 관리자가 /admin/orders에서 주문을 주문 완료 → 상품 준비중 → 배송중 → 배송 완료로 한 칸씩 넘기고, /admin/cancels에서 취소 요청을 승인(재고·적립금 복구)하거나 거절(신청 직전 단계로 복귀)합니다. 상태가 바뀔 때마다 구매자에게 알림이 갑니다.

flowchart LR
  screen["화면<br/>/admin/orders · /admin/orders/[id] · /admin/cancels"] --> api["API<br/>POST /api/admin/orders/{id}/advance<br/>POST /api/admin/cancel-requests/{id}/approve · reject"]
  api --> service["Application<br/>AdminOrderService"]
  service --> domain["Domain<br/>OrderProgress.advance() 한 칸씩<br/>CancelRequest.approve() · reject() 한 번만"]
  service --> repo["Infrastructure<br/>AdminOrderRepository"]
  repo --> db["PostgreSQL<br/>orders · order_status_history<br/>cancel_requests · products · notifications"]
  repo -->|"취소 처리 중 실패"| rollback["rollback<br/>상태·기록 그대로"]
  api -.->|"응답 뒤 BackgroundTasks"| notice["단계 진행 알림<br/>(새 세션 · 실패는 로그만)"]

• 관련 파일: 화면 app/admin/orders/ · app/admin/cancels/ · components/admin/ (AdminNav · AdminGuard · StatusFilter · ConfirmDialog) · 클라이언트 lib/admin.ts · API backend/src/admin_orders/presentation/ · 서비스 backend/src/admin_orders/application/ · 도메인 backend/src/admin_orders/domain/ · 저장소 backend/src/admin_orders/infrastructure/

• 핵심 코드: 라우터 advance_order · approve_cancel_request · reject_cancel_request → 서비스 AdminOrderService.advance_order · · → 도메인 · → 저장소

🔮 상품 문의 → 관리자 답변: 김예주

• UC 한 줄: 로그인 사용자가 상품 상세 Q&A 탭에서 문의(비밀글 선택 가능)를 남기면, 관리자가 /admin/questions에서 한 번만 답변하고 작성자에게 알림이 갑니다.

flowchart LR
  screen["화면<br/>상품 상세 Q&A 탭 · /admin/questions"] --> api["API<br/>POST /api/products/{id}/questions<br/>POST /api/admin/questions/{id}/answer"]
  api --> service["Application<br/>QuestionService.ask() · answer()"]
  service --> domain["Domain<br/>Question · can_be_read_by()<br/>answer_with() 한 번만"]
  service --> repo["Infrastructure<br/>QuestionRepository"]
  repo --> db["PostgreSQL<br/>product_questions · notifications"]
  repo -->|"알림 저장 실패"| rollback["rollback<br/>답변도 저장 안 됨"]

• 관련 파일: 화면 components/products/QuestionsPanel.tsx · QuestionEntries.tsx · QuestionDeleteButton.tsx · app/admin/questions/ · 클라이언트 lib/questions.ts · API backend/src/questions/presentation/ · 서비스 backend/src/questions/application/ · 도메인 backend/src/questions/domain/ · 저장소 backend/src/questions/infrastructure/

• 핵심 코드: 라우터 create_question · answer_question → 서비스 QuestionService.ask · answer → 도메인 · → 저장소 ·

10. 미완료 · Mock 목록

항목	지금 상태	구분	다음 단계 · 이유
결제	가상 결제 — 결제수단만 고르고 PG 미연동, 주문·재고·적립금은 실제 DB에 저장	실제 API · 결제만 가상	발제 제외 범위
상품 목록 · 상세 · 카테고리	API 실패 시 lib/products.ts가 data/products.ts · data/categories.ts로 폴백 (백엔드가 꺼져도 쇼핑 기본 화면 동작)	실제 API + 장애 폴백	유지
FAQ	API 실패 시 lib/faqs.ts가 lib/faqFallback.ts(시드와 같은 내용)로 폴백	실제 API + 장애 폴백	유지
mocks/ 폴더	mocks/admin.ts만 남음. lib/admin.ts는 USE_MOCK = false라 실제 API만 사용, mock은 백엔드 머지 전 화면 개발용 잔여	미사용 Mock	정리 예정
정적 데이터	키캡 · 키보드 · 데스크 룩북 테마(data/keycaps.ts · data/keyboards.ts · data/deskLookbook.ts)	정적 데이터 (Mock 아님)	유지
비밀번호 찾기	메일 발송 없음 — 로컬에서는 화면에 재설정 링크를 바로 보여 주고, 배포에서는 "메일 발송 미지원" 안내만	메일만 미구현	메일 서버 연동
레거시 backend/app 라우터	src/main.py가 아직 app.routers의 health · auth(구글 · 개발용 로그인) · products · faqs · cart · orders.dev_router · (+) · · · · · · · · · · 를 서비스 (인증은 새 로 검사, 는 로컬 전용 · 배포 404)

---

11. 에러 처리 · 보안 · 테스트

에러 처리 — 사용자에게는 한글 안내만, 자세한 원인은 서버 로그로

상황	서버 응답	화면
입력 형식 오류	422 "비밀번호: 8자 이상 입력해 주세요." — 공통 처리기가 한글로 바꾸고 보낸 값(비밀번호 등)은 다시 담지 않음 (errors.py)	폼 아래 안내 문구
업무 규칙 위반	도메인 예외 → ERROR_STATUS_MAP 한 곳에서 409 · 404 · 400 + 한글 detail	같은 문구 그대로
로그인 필요 · 로그아웃한 토큰	401	"로그인이 필요합니다" + 로그인 안내 (lib/api.ts)
남의 데이터 · 일반 사용자의 관리자 API	404 (있다는 사실도 숨김)	찾을 수 없음 안내
예상 못한 서버 오류	500 — 스택·SQL은 응답에 없음	"요청을 처리하지 못했습니다"
화면이 깨짐 · 없는 주소	—	공통 GAME OVER 화면: error.tsx · global-error.tsx (레이아웃까지 깨질 때) · not-found.tsx + 상품 · 주문 · 공지 상세 404

서버 로그에는 메서드 · 경로 · 상태 · 처리 시간만 남기고, 422는 필드 이름과 오류 종류만 남겨요 (입력값 · 토큰 · 쿼리스트링 X).

보안

• 비밀번호: bcrypt 해시만 저장 (8자 이상 · 72바이트 이하). 로그인 실패는 "없는 이메일"과 "틀린 비밀번호"를 구분하지 않음
• 토큰: JWT(HS256)에 sub · jti · exp(7일)만 — 개인정보는 넣지 않음. 매 요청 CurrentUser가 서명 · 만료 · 블랙리스트 확인
• 로그아웃: jti를 token_blacklist에 저장 → 같은 토큰 401. 만료된 줄은 scripts.purge_blacklist로 정리
• 인가: AdminUser가 관리자 역할 확인, 서비스가 "내 주문 · 내 문의인지" 확인 — 아니면 404
• 쿠키: pm_session은 HttpOnly · SameSite=Lax · 배포에서 Secure
• 배포 안전장치: 기본 JWT 비밀값이거나 32자 미만이면 서버가 시작을 거부 · 개발용 로그인 · /api/dev/*는 배포에서 404 · CORS는 FRONTEND_URL만 허용 · .env는 git 제외
• 비밀번호 재설정: 30분짜리 토큰, 한 번 쓰면 무효(비밀번호 지문). 메일 서버가 없어 배포에서는 "메일을 보내지 않아요"라고 그대로 안내
• 주문 CSV: = + - @로 시작하는 칸은 엑셀 수식으로 실행되지 않게 처리

테스트

종류	무엇을	예
도메인 단위	DB 없이 규칙만 (배송비 · 상태 전이 · 비밀번호 규칙)	test_orders_domain.py · test_admin_orders_domain.py
서비스 · 롤백	중간에 실패하면 주문 · 재고 · 알림이 모두 되돌아가는지	test_orders_service.py · test_admin_orders_service.py · test_questions_service.py
API	정상 · 422 · 404 · 409 · 401(로그아웃 토큰) 응답과 문구	test_auth_api.py · test_orders_api.py · test_error_messages.py
동시성	같은 사람의 동시 주문이 한 건만 되는지	test_orders_duplicate_race.py
프론트	utils/ 순수 함수 (가격 표시 등)	tests/*.test.mjs (268개)

백엔드 pytest 720여 개 · 프론트 268개를 PR마다 CI가 새 PostgreSQL에서 돌리고, 통과해야만 main에 머지돼요. 직접 돌리기: backend/에서 uv run pytest --ignore=tests/test_seed_demo.py, 루트에서 npm test.

---

부록: 1차 결과물

1차 팀 (2026.10.07 ~ 10.13)

이름	역할	담당
채희주 (@kixxuya)	프론트엔드	화면 전체, 디자인 시스템, 메인·상품·PIXEL LOCAL UI
@skshdwkdvkfl55-art	BE-A 플랫폼·커머스	구글 로그인, 장바구니, 찜, 아바타, PIXEL LOCAL(덕력지도·거래)
@totoriri605-oss	BE-B 주문·CS	FAQ, 가상 주문·배송, 취소, 리뷰, 상품 Q&A, 키캡 호환성
@kyrdufmal-summer	BE-C → 기획·정책	PIXEL LOCAL 서비스 정의·운영 정책·개인정보 기준 정리(이슈 #151~), 현재 구현·화면 구조 문서화

기술 스택

구분	사용 기술
프론트	Next.js 16 (App Router, Turbopack, Cache Components) · React 19 · TypeScript 5 · Tailwind CSS 4 (@theme 디자인 토큰)
백엔드	FastAPI · SQLAlchemy 2 (async) · asyncpg · Alembic · Pydantic v2 · PyJWT · bcrypt · Authlib(구글 OAuth) · uv
DB	PostgreSQL (Docker 또는 설치형)
테스트	pytest (백엔드) · node --test (프론트 유틸) · ESLint · ruff
외부	Cloudflare Workers AI (AI 픽셀 아바타, 사용자 동의 시에만)
폰트	Pretendard (본문) · Galmuri (픽셀 타이틀)
협업	Git · GitHub (GitHub Flow + Pull Request · 이슈·라벨) · Notion

페이지 구성

경로	페이지	주요 내용	상태
/	메인	배너 3장(내 캐릭터 · 월드맵 · 데스크 룩북), 추천 아이템	✅
/products	전체 상품	검색·정렬·필터·등급, 무한 스크롤	✅
/products/[id]	상품 상세	이미지·정보·장바구니, 상품정보·리뷰·문의 탭, 같은 카테고리, 최근 본 아이템, 없는 id 안내	✅
/products/[id]/fitting	키캡 피팅룸	내 키보드에 끼워 보기, 조합 장바구니 담기	✅
/lookbook	데스크 테마 룩북	테마별 데스크와 상품	✅
/cart · /checkout	장바구니 · 주문하기	수량·합계, 배송지 입력, 가상 주문	✅
/login · /signup	로그인 · 가입	이메일·비밀번호 로그인/가입(2차), 구글 로그인 + 닉네임 정하기, 개발용 로그인	✅
/mypage	마이페이지	닉네임, 아바타, 뱃지 도감, 바로가기	✅
/mypage/orders · /[id]	주문 내역 · 상세	배송 단계·타임라인, 취소 신청, 리뷰 쓰기	✅
/mypage/wishlist · /gifts · /avatar · /quests	찜 · 선물함 · 픽셀 아바타 · 내 퀘스트	찜 목록, 받은/보낸 선물(받기·거절), AI·캔버스 아바타, 퀘스트 요약	✅
/local	덕력지도	시 › 구 › 생활권 지도, 취향 필터, 지역 패널, 이웃 카드	✅
/local/wish-map	위시맵	동네별 WISH 글, 닉네임·아이템 검색, 선물하기	✅
/local/trades · /new · /mine	거래·교환	게시판, 글쓰기, 내 글·교환 신청함·매칭	✅
/local/gift	이웃에게 선물하기	수량·메시지, 데모 결제	✅
/local/settings	내 동네·취향 설정	동네·취향(최대 20), 공개 설정 5종	✅
/help	고객센터	FAQ 검색·분류	✅
404 · 오류	GAME OVER 화면	없는 페이지·없는 상품·오류	✅

사용자 흐름 (요약)

flowchart LR
  main["메인"] --> list["전체 상품"] --> detail["상품 상세"] --> cart["장바구니"] --> order["주문 · 배송"]
  detail -->|키캡| fit["키캡 피팅룸"] --> cart
  main -->|월드맵| map["덕력지도"] --> card["이웃 카드"]
  map --> trades["거래·교환"] -->|교환 신청 · 수락| trust["하트 · 뱃지 · 알림"]
  card --> wish["위시맵"] -->|선물하기| gift["선물 → 받는 사람 주소 → 주문"] --> trust

화면 구조·컴포넌트 트리·흐름 5개 상세는 docs/UI_STRUCTURE.md 에 있습니다.

화면 캡처 (1차)

메인 (데스크톱)	메인 (모바일)

전체 상품 (무한 스크롤)	상품 상세

키캡 피팅룸	데스크 룩북

PIXEL LOCAL 덕력지도	덕력지도 (모바일)

거래·교환	위시맵 (선물하기)

캡처는 로그인하지 않은 상태, 1280px·390px 화면 기준입니다.

문서

문서	내용
docs/UI_STRUCTURE.md	화면 구조 기획과 분할 · 컴포넌트 조립과 배치 · 사용자 흐름
docs/PIXEL_LOCAL_AS_BUILT.md	PIXEL LOCAL 현재 구현 (화면 문구·규칙·알려진 한계·시연 순서)
docs/archive/TASTE_COMMERCE_PLAN.md	(보관) 10/12 기준 다음 단계 기획 (취향 세분화·하트·개인정보·레퍼런스 분석)
docs/PIXEL_LOCAL_POLICY.md · docs/DUKRYEOK_MAP_POLICY.md · docs/AVATAR_POLICY.md	운영 정책
docs/PRODUCT_STRATEGY.md · docs/UX_CX_STRATEGY.md	상품·UX 전략
docs/backend/	백엔드 실행·구조·스키마·API
AGENTS.md · docs/SETUP.md · docs/archive/	작업 규칙 · 환경 세팅 · 보관 문서

트러블슈팅 (1차)

문제	원인	해결
동적 상세 페이지의 params 처리	params는 Promise이며, Cache Components 환경에서는 동적 값을 읽는 위치도 고려해야 함	페이지는 params를 자식에 전달하고, <Suspense> 내부의 ProductDetail에서 await params로 읽음. generateStaticParams와 notFound()로 정적 경로·없는 상품도 처리
모바일에서 로고 · 메뉴가 두 줄로 꺾임	헤더 가로 공간 부족	whitespace-nowrap, 모바일 여백 축소
ESLint가 <img> 사용을 경고	Next.js는 next/image를 권장	과제 권장에 따라 <img> 유지, 사유를 단 주석으로 처리