어른패치 서버

어른패치 앱의 사용자 학습 상태를 저장하고 제공하기 위한 REST API 서버입니다.

현재 단계에서는 로컬 개발 환경과 데이터베이스 연결, 공통 응답 형식, API 문서, Health API, 사용자 학습 상태와 패치 학습 기록 API까지 구성되어 있습니다.

프론트엔드 저장소: https://github.com/Adult-Patch/adult-patch-app.git

기술 구성

• Node.js 20.19 이상
• TypeScript
• NestJS 11
• Prisma ORM 7
• SQLite
• Joi
• class-validator / class-transformer
• Swagger
• Jest

로컬 개발에 Docker와 PostgreSQL은 사용하지 않습니다.

로컬 실행

1. 패키지를 설치합니다.

   npm install

2. 환경 변수 파일을 준비합니다.

   cp .env.example .env

   Windows PowerShell에서는 다음 명령을 사용할 수 있습니다.

   Copy-Item .env.example .env

3. Prisma Client와 로컬 SQLite 데이터베이스를 준비합니다.

   npm run prisma:generate
   npx prisma migrate dev

4. 개발 서버를 실행합니다.

   npm run start:dev

기본 포트는 3001입니다.

확인 주소

• Health API: http://localhost:3001/api/v1/health
• 사용자 학습 상태 조회: http://localhost:3001/api/v1/users/me/state
• 온보딩 저장: PATCH http://localhost:3001/api/v1/users/me/onboarding
• 패치 학습 기록: http://localhost:3001/api/v1/patches/{patchId}/...
• Swagger: http://localhost:3001/docs

Health API는 서버 응답뿐 아니라 SQLite에 SELECT 1 쿼리를 실행해 실제 연결 상태를 확인합니다. 데이터베이스 확인에 실패하면 HTTP 503을 반환합니다.

환경 변수

NODE_ENV=development
PORT=3001
DATABASE_URL=file:./dev.db
DEV_MEMBER_ID=00000000-0000-4000-8000-000000000001
CORS_ORIGINS=http://localhost:5173,http://localhost,https://localhost,capacitor://localhost

여러 CORS 출처는 쉼표로 구분합니다.

개발용 현재 회원

JWT 인증을 아직 도입하지 않았으므로 로컬 개발 환경에서는 DEV_MEMBER_ID의 UUID를 현재 회원 ID로 사용합니다. API 요청의 body, query, path에서는 memberId를 받지 않습니다. 요청 시 해당 회원이 없으면 Member 레코드를 자동 생성하고, 있으면 기존 레코드를 사용합니다.

이 방식은 개발용 임시 구현이며 운영 인증이 아닙니다. JWT 인증 도입 시 인증된 요청 컨텍스트에서 현재 회원을 가져오는 구현으로 교체해야 합니다.

공통 응답 형식

성공 응답:

{
  "success": true,
  "code": "SUCCESS",
  "message": "요청을 정상적으로 처리했습니다.",
  "data": {},
  "timestamp": "2026-07-29T00:00:00.000Z"
}

오류 응답:

{
  "success": false,
  "code": "ERROR_CODE",
  "message": "오류 설명",
  "data": null,
  "timestamp": "2026-07-29T00:00:00.000Z",
  "path": "/api/v1/..."
}

프론트엔드 상태 계약

프론트엔드가 서버에 저장할 사용자 상태는 아래 필드를 기준으로 합니다.

• onboardingCompleted
• selectedSituation
• selectedInterests
• experienceLevel
• completedPatchIds
• completedMissionIds
• reviewCompletedPatchIds
• patchSelections
• patchReviewSelections
• patchProgress
• patchCompletedAt

현재 프론트엔드는 adult-patch:app-state 키의 localStorage를 사용합니다. 프론트 remote 연동 전까지 서버 상태 API와 별도로 동작합니다.

API 목록

• GET /api/v1/health
• GET /api/v1/users/me/state
• PATCH /api/v1/users/me/onboarding
• DELETE /api/v1/users/me/state
• POST /api/v1/patches/:patchId/selection
• POST /api/v1/patches/:patchId/review-selection
• PATCH /api/v1/patches/:patchId/progress
• POST /api/v1/patches/:patchId/review-complete
• POST /api/v1/patches/:patchId/complete

온보딩 저장 요청 예시:

{
  "selectedSituation": "independence",
  "selectedInterests": ["daily-life", "finance"],
  "experienceLevel": "beginner"
}

온보딩 저장 후 응답의 data에는 일부 필드가 아닌 전체 사용자 학습 상태가 반환됩니다.

패치 선택, 진행, 최종 확인, 완료 및 상태 초기화 API도 처리 후 동일한 전체 학습 상태를 반환합니다. 모든 변경 API의 성공 상태는 HTTP 200입니다.

지원하는 패치 ID

• laundry-basics
• microwave-container
• move-in-report
• rental-contract-check
• payslip-basics
• card-payment-date
• work-question
• mistake-report
• suspicious-message
• lost-card

패치 학습 기록 정책

• 상황 판단 및 최종 확인 선택은 upsert하며, 답변을 변경하면 answeredAt도 마지막 답변 시각으로 갱신합니다.
• 진행 단계는 1~3이며 이전 단계로 돌아갈 수 있습니다.
• 최종 확인 완료 전에는 REVIEW 선택 기록이 필요합니다.
• 패치 완료 전에는 최종 확인 완료 기록이 필요합니다.
• reviewCompletedAt과 completedAt은 최초 완료 시각을 유지합니다.
• 완료 처리와 상태 초기화처럼 여러 레코드를 함께 변경하는 작업은 Prisma transaction으로 처리합니다.
• DELETE /users/me/state는 개발·테스트 전용이며 회원은 삭제하지 않습니다. 운영 환경에서는 HTTP 403을 반환합니다.

현재 패치 콘텐츠와 정답 판정은 프론트 정적 데이터에 있습니다. 따라서 서버는 최종 문제의 정답 여부를 직접 검증하지 못하며, 악의적인 클라이언트가 REVIEW 선택을 저장한 뒤 review-complete를 직접 호출할 수 있습니다. 서버 콘텐츠와 정답 검증이 도입되기 전까지의 임시 제약입니다.

현재 구현 범위

• 전역 API prefix /api/v1
• 환경 변수 검증
• 환경 변수 기반 CORS
• 전역 ValidationPipe
• 전역 예외 필터와 공통 오류 응답
• Prisma Client 연결과 종료 처리
• SQLite 초기 Member 모델과 migration
• 개발용 현재 회원 자동 생성
• 사용자 학습 상태 조회
• 온보딩 저장
• 온보딩, 패치 진행, 선택, 완료 기록 테이블 구조
• 패치 상황 판단 선택 저장
• 최종 확인 선택 저장
• 패치 진행 단계 저장
• 최종 확인 완료
• 미션 및 패치 완료
• 개발용 학습 상태 초기화
• 최초 완료 시각 보존과 중복 요청 안전성
• 모든 변경 API에서 전체 학습 상태 반환
• Health API
• Swagger 문서
• Health, Users, Patches Controller/Service 테스트

다음 구현 범위

아래 기능은 아직 구현하지 않았습니다.

• JWT 인증
• 소셜 로그인
• 서버에서 최종 문제 정답 검증
• 프론트 remote 연동
• localStorage 데이터 서버 병합
• PostgreSQL 배포 전환
• 운영용 상태 초기화 정책
• 사용자 계정 삭제

인증 도입 전 임의의 사용자 ID를 body에서 받는 API는 만들지 않습니다.

검증 명령

npm run format
npm run prisma:generate
npx prisma migrate status
npm run lint
npm test -- --runInBand
npm run build