SYSTEM BLUEPRINT

카페 원가·마진 정산 앱 MVP
운영자 앱 화면과 인계 화면 스토리보드

원가 입력부터 일일정산·푸시 미션까지의 앱 화면과, API 문서·스키마·배포 인계 화면을 실제에 가깝게 그렸습니다.

스토리보드란?

스토리보드는 서비스의 화면을 실제 모습에 가깝게 미리 그려 보는 문서입니다. 카페 운영자가 쓰는 앱 화면과 대표·발주처 개발자가 받는 인계 화면으로 나눠 여정 순서대로 배치했습니다.

  1. 카페 운영자가 레시피 원가를 확인하고 판매량을 입력해 일일정산과 미션을 끝내는 흐름
  2. 대표와 발주처 개발자가 API 문서·스키마·배포·실기기 테스트 결과를 받아 이어가는 흐름

마지막까지 보시면 발표에서 시연할 앱이 서버와 어떻게 이어져 동작하는지 그려지실 것입니다.

P.01
카페 운영자 시나리오

카페 운영자 여정

로그인 상태를 유지한 채 원가를 확인하고, 하루 판매를 정산한 뒤 예약 알림으로 미션을 끝내는 흐름입니다.

1. 로그인 유지

토큰 자동 갱신
다시 로그인 없음

2. 원가 등록

원재료·중간재·레시피
서버 저장

3. 마진 확인

서버 계산 마진율
메뉴별 표시

4. 판매·정산

판매량 입력
끊기면 자동 재시도

5. 푸시·미션

마감 예약 알림
미션 완료 전송

P.02
카페 운영자 | 화면 01

메뉴 원가 · 마진율

메뉴 원가연남 오후세시
바닐라 라떼 (ICE)저장됨
마진율
74.8%
판매가 5,500원
잔당 원가 1,384원
에스프레소 2샷
원재료 · 원두 36g
612원
우유
원재료 · 200ml
540원
바닐라 시럽
중간재 · 30ml (설탕·바닐라빈)
162원
컵·뚜껑·빨대
부재료 · 1세트
70원
서버 계산값 · 오늘 14:32 저장
다른 메뉴 등록 메뉴 24개 · 재료 38개
아메리카노 (HOT)
판매가 4,500원 · 원가 806원
82.1%저장됨
딸기 라떼
판매가 6,000원 · 원가 1,968원
67.2%전송 대기
콜드브루
판매가 5,000원 · 원가 1,120원
77.6%저장됨
원가
정산
알림
마이페이지

[화면 개요 및 목적]

레시피를 원재료·중간재·부재료로 나눠 잔당 원가와 마진율을 보여주는 대표 화면입니다. 기존에 만든 원가·레시피 화면에 서버 저장과 계산 결과를 연결합니다.

[핵심 기능 로직]

원가와 마진율은 서버가 계산해 내려주고 앱은 표시만 합니다. 바닐라 시럽 같은 중간재는 자기 레시피로 단가를 먼저 구해 다시 들어갑니다. 저장 상태를 메뉴마다 표시해 아직 전송되지 않은 값을 구분합니다.

  • 앱·서버 숫자 일치
    NestJS 원가 계산 서비스
  • 원가 데이터 저장
    Prisma + PostgreSQL
P.03
카페 운영자 | 화면 02

일일정산 · 전송 재시도

일일정산
9월 16일 (수) · 영업 09:00~22:00
오늘 순이익
917,613원
매출 합계1,282,500원
아메리카노 142잔639,000원
바닐라 라떼 61잔335,500원
콜드브루 34잔170,000원
딸기 라떼 23잔138,000원
재료 원가− 282,220원
고정비 일할 (월 2,480,000원)− 82,667원
서버 전송 기록 매장 와이파이 끊김
판매량 3건
14:05 서버 저장
저장됨
콜드브루 34잔
자동 재시도 3회차 · 8초 후
재시도 중
어제(9월 15일) 순이익846,190원
전송이 끝나면 정산을 확정할 수 있어요 · 확정 후에도 수정 가능
지금 다시 보내기
전송 완료 후 정산 확정

[화면 개요 및 목적]

하루 판매량으로 매출·재료 원가·고정비 일할을 계산해 순이익을 보여주고, 서버 전송 상태를 함께 표시하는 정산 화면입니다.

[핵심 기능 로직]

전송에 실패한 입력은 앱에 보관하고 간격을 늘려가며 자동 재시도합니다. 요청마다 고유 번호를 붙여 두 번 도착해도 서버에는 한 건만 저장됩니다. 전송이 끝나야 정산 확정 버튼이 열립니다. 데모 Step 1~2에서 확인합니다.

  • 끊겨도 입력 보존
    로컬 전송 대기 큐 + 재시도
  • 중복 저장 방지
    Idempotency-Key · unique 제약
P.04
카페 운영자 | 화면 03

예약 푸시 · 오늘의 미션

카페 정산 · 예약 알림21:30
마감 30분 전이에요
남은 판매량을 입력하고 오늘 미션을 끝내세요
알림을 누르면 미션 화면으로 이동
9월 16일 (수)
오늘의 미션
1 / 3
오픈 전 원두 재고 기록
09:12 완료 · 원두 4.2kg
완료
오늘 판매량 입력 마감
메뉴 24개 중 21개 입력
진행중
일일정산 확정하기
판매량 입력 후 가능
대기
예약 알림 · 오픈 08:50 · 마감 21:30 (영업시간 기준 자동)
이번 주 미션 달성 5일 중 4일 · 연속 12일
판매량 입력하고 완료 전송
완료를 누르면 수행 결과가 서버에 기록되고, 다음 날 같은 미션이 다시 생성됩니다.
원가
정산
알림
마이페이지

[화면 개요 및 목적]

매장 영업시간에 맞춰 도착한 마감 알림을 누르면 오늘의 고정 미션 화면으로 이동하고, 수행 결과를 서버로 보냅니다.

[핵심 기능 로직]

로그인 후 FCM 기기 토큰을 서버에 등록합니다. 서버 스케줄러가 매장별 오픈·마감 시각을 한국 시간 기준으로 계산해 발송하고 발송 이력을 남깁니다. 알림 데이터에 이동할 화면을 담아 탭하면 미션 화면이 열립니다. 데모 Step 3~4에서 확인합니다.

  • 영업시간 맞춤 알림
    @nestjs/schedule + FCM
  • 알림에서 바로 이동
    firebase_messaging 딥링크
P.05
대표 · 발주처 개발자 시나리오

인계·검수 여정

결과물을 받아 직접 확인하고, 이후 개발을 혼자서도 이어갈 수 있게 전달되는 흐름입니다.

1. 코드 인수

기존 구조 확인
실행 재현

2. 스키마 검토

추가형 마이그레이션
롤백 스크립트

3. API 확인

Swagger 문서
요청·응답 예시

4. 베타 배포

Docker 서버
상태 확인

5. 실기기 검수

Android·iOS 테스트
베타 빌드 전달

P.06
대표 · 발주처 개발자 | 화면 01

Swagger API 문서

beta-api.cafe-app.kr/docs
인계 문서
API 문서
DB 스키마
배포·테스트
변경 내역
beta 서버 · v0.9.3
Swagger · OpenAPI 3.0 · 엔드포인트 38개
카페 정산 API 문서
Authorizeopenapi.json
전체auth 3stores 4cost 14sales 6settlements 4push 4missions 3
GET/v1/ingredients원재료·부재료·중간재 목록신규
POST/v1/recipes/{menuId}레시피 저장신규
GET/v1/menus/{id}/margin메뉴 원가·마진율신규
PATCH/v1/fixed-costs/{id}고정비 수정신규
POST/v1/auth/refresh토큰 재발급기존
POST/v1/devices/fcm-token기기 토큰 등록신규
PATCH/v1/missions/{id}/complete미션 완료 처리신규
POST/v1/settlements/daily신규
일일정산 저장 · 같은 Idempotency-Key 재요청은 기존 결과 반환
Request body
storeIdst_7Qm2
businessDate2026-09-16
sales[0].qty61잔
clientRequestIda3f1-0916-2130
Response 201 · 저장된 정산 결과
revenue1,282,500원
ingredientCost282,220원
fixedCostDaily82,667원
netProfit917,613원
201 Created · 142ms· 401 · 409 · 422 예시 포함

[화면 개요 및 목적]

원가·판매·정산·푸시·미션 전체 API를 기존 인증 API와 한 문서로 정리한 화면입니다. 기존 API와 이번에 추가한 API를 표시로 구분합니다.

[핵심 기능 로직]

코드의 요청·응답 형식에서 문서를 자동 생성해 문서와 실제가 어긋나지 않습니다. 오류 응답 예시와 재요청 규칙까지 적어 발주처 개발자가 바로 호출해 볼 수 있습니다.

  • 문서와 코드 항상 일치
    @nestjs/swagger · OpenAPI 3.0
  • 로그인 상태로 바로 호출
    Bearer 인증 연동
P.07
대표 · 발주처 개발자 | 화면 02

DB 스키마 보완

beta-api.cafe-app.kr/handover/schema
인계 문서
API 문서
DB 스키마
배포·테스트
변경 내역
beta 서버 · v0.9.3
Prisma schema · PostgreSQL 16 · 기존 User·Store 유지
스키마 보완 내역
기존 4개보완 2개신규 9개
Ingredient신규
id · kind RAW | SUB | INTERMEDIATEunit g · ml · eapurchasePrice · purchaseQty
RecipeItem신규
menuId → MenuingredientId → Ingredientamount · unit
Menu보완
price+ costCached · marginRate+ updatedAt
DailySales신규
storeId · businessDatemenuId · qtyclientRequestId unique
PushSchedule신규
storeId · type OPEN | CLOSEoffsetMin · timezone Asia/SeoullastSentAt
Mission · MissionLog신규
title · repeat DAILYstoreId · missionId · datecompletedAt
마이그레이션
2026_09_21_add_cost_tables적용됨
2026_09_23_add_sales_settlement적용됨
2026_09_26_add_push_mission대기
원가 계산 규칙
중간재는 자기 레시피로 원가를 먼저 구해 1단위 단가로 저장합니다.
예) 바닐라 시럽 1L 5,400원 → 30ml 162원
기존 데이터 삭제 없는 추가형 변경만 적용 · 롤백 스크립트 동봉

[화면 개요 및 목적]

기존 사용자·매장 테이블은 그대로 두고, 원가·판매·정산·푸시·미션에 필요한 테이블을 어떻게 더했는지 보여주는 화면입니다.

[핵심 기능 로직]

원재료·부재료·중간재를 한 테이블의 종류 값으로 구분하고 단위를 함께 저장합니다. 변경은 기존 데이터를 지우지 않는 추가형 마이그레이션으로만 적용하고, 되돌리는 스크립트를 함께 전달합니다.

  • 변경 이력 추적
    Prisma Migrate
  • 기존 데이터 보호
    추가형 변경 + 롤백 스크립트
P.08
대표 · 발주처 개발자 | 화면 03

배포 · 실기기 테스트

beta-api.cafe-app.kr/handover/qa
인계 문서
API 문서
DB 스키마
배포·테스트
변경 내역
beta 서버 · v0.9.3
베타테스트 준비 현황 · 9월 30일 (수) 18:20
배포와 실기기 테스트
테스트 기록 내려받기
테스트 항목
86개
통과
71개
남은 이슈
3건
기기OS확인 범위결과
Galaxy S23Android 14로그인 유지 · 원가 저장 · 푸시 탭 이동통과
Galaxy A24Android 13오프라인 입력 후 재전송통과
iPhone 13iOS 17.6원가·정산 연동 · 토큰 갱신진행중
iPhone SE 3iOS 18.0화면 연동 전 항목대기
iOS 푸시는 이번 범위 제외 · 수신 권한 요청 화면만 확인
docker compose · beta
api (nestjs)healthy · 2일 3시간
postgres:16healthy
scheduler다음 발송 08:50
베타 빌드
Android 0.9.3 (31)완료
iOS 0.9.3 (31)진행중

[화면 개요 및 목적]

베타 서버 상태와 Android·iOS 실기기 테스트 결과, 베타 빌드 전달 상황을 한눈에 확인하는 검수 화면입니다.

[핵심 기능 로직]

서버·DB·스케줄러를 Docker로 묶어 같은 설정으로 다시 띄울 수 있습니다. 기기별 확인 범위와 결과를 기록해 검수 근거로 남기고, iOS 푸시는 범위 밖임을 명시합니다.

  • 어디서나 같은 서버
    Docker Compose
  • 검수 근거 기록
    실기기 테스트 체크리스트
P.09
시나리오

P.10
| 화면 01

[화면 개요 및 목적]

[핵심 기능 로직]

    P.11
    | 화면 02

    [화면 개요 및 목적]

    [핵심 기능 로직]

      P.12
      | 화면 03

      [화면 개요 및 목적]

      [핵심 기능 로직]

        P.13