전체 요약

현재 결정과 남은 일을 한 화면에서 봅니다.

이 포털은 문서가 많아져도 관리자와 개발자가 같은 그림을 보도록 만든 정적 대시보드입니다. 각 사이드 메뉴는 독립 화면으로 구성되어 목적에 맞는 정보만 보여줍니다.

Backend Decision

Hybrid

Supabase + R2 + bounded AWS worker lane

AWS-only MVP

철회

비용 사유로 MVP 기본 계획에서 제외

Phase 5 Local

9/9 slices

로컬 command slice 기준 captured

Production

Blocked

외부 provider/runtime evidence 필요

빠른 판단

현재 문서들의 핵심 결론만 요약한다.

확정 방향 실행 준비 실행 증거 대기

하이브리드 백엔드로 간다

DB/Auth는 Supabase, 이미지/파일은 Cloudflare R2, 무거운 비동기 작업은 비용 제한 AWS worker lane으로 나눕니다. 초기 비용을 낮추면서도 나중에 확장할 수 있는 구조입니다.

일반 표현 돈과 재고는 DB가 책임지고, 이미지는 이미지 전용 창고가 책임지고, 오래 걸리는 일은 별도 작업자가 처리합니다.
개발 표현 권위 write path는 TypeScript API command boundary + PostgreSQL transaction + audit/outbox로 고정합니다.

아직 production 완료가 아니다

문서는 잘 정리됐지만 실제 계정에서 API, DB, RLS/JWT, R2/CDN, queue/worker, 비용 알림, 복구 테스트를 돌린 증거가 필요합니다.

  • Supabase 프로젝트와 RLS/JWT runtime 검증 필요
  • Cloudflare R2 bucket, custom domain, cache rule 검증 필요
  • AWS worker/queue는 budget alert와 sandbox 증거 후 열기
  • 정책 미확정 19개 command는 구현 진행률에서 제외
쉬운 설명

개발자가 아니어도 이해할 수 있게 풀어서 봅니다.

복잡한 기술 문서를 “왜 필요한지”, “누가 준비해야 하는지”, “안 하면 어떤 문제가 생기는지” 중심으로 설명합니다.

관리자 관점

이 프로그램은 장부와 창고를 동시에 다룹니다

단순 쇼핑몰이 아니라 거래처, 주문, 입금, 외상, 재고, 이미지, 전표가 얽혀 있습니다. 그래서 “버튼이 눌린다”보다 “돈과 재고가 틀어지지 않는다”가 더 중요합니다.

비용 관점

이미지 비용은 따로 관리해야 합니다

상품 이미지가 많고 거래처가 많이 내려받으면 트래픽이 커집니다. R2는 인터넷 egress 비용이 없지만 요청 수, 저장량, Worker, WAF, 로그 비용은 여전히 관리해야 합니다.

재고 관점

미송 때문에 재고는 음수가 될 수 있습니다

이 시스템에서 음수 현재고는 무조건 오류가 아닙니다. 주문은 잡혔지만 아직 발송하지 못한 미송이 있으면 현재고가 음수로 보일 수 있습니다. 중요한 것은 음수 재고가 미송 잔량과 재고 원장에 연결되어 추적되는지입니다.

보안 관점

누가 무엇을 했는지 남겨야 합니다

재고나 입금이 잘못되면 분쟁이 생깁니다. “어느 직원이 언제 어떤 거래처/상품을 어떻게 바꿨는지”가 남아야 문제를 추적할 수 있습니다.

운영 흐름을 쉽게 보면

주문 1건이 실제로는 여러 작업으로 나뉩니다.

1. 거래처가 주문

상품, 수량, 가격, 거래처 상태를 확인합니다.

2. 재고를 잠금

동시에 주문해도 중복 차감이 생기지 않게 DB에서 직렬화합니다. 미송으로 인정된 경우 현재고는 음수가 될 수 있고, 그 음수는 미송 잔량과 원장에 연결돼야 합니다.

3. 장부를 기록

주문, 미수금, 재고 원장, 감사 로그를 한 묶음으로 남깁니다.

4. 부가 작업 처리

전표, 이미지 ZIP, 알림 같은 오래 걸리는 일은 worker가 처리합니다.

관리자가 알아야 할 용어

문서에서 자주 나오는 표현을 업무 말로 바꾼 표입니다.

용어 쉬운 설명 왜 중요한가
Audit Trail 누가 무엇을 바꿨는지 남기는 기록 분쟁, 실수, 내부 통제에 필요
Concurrency 여러 사람이 동시에 같은 재고를 건드릴 때 꼬이지 않게 하는 장치 중복 차감과 원장 없는 음수 재고 방지. 미송으로 인정된 음수 현재고는 허용
RBAC/ABAC 직원 역할과 상황에 따라 볼 수 있는 메뉴와 기능을 제한 단가, 매출, 설정 같은 민감 기능 보호
Snapshot 주문 당시의 상품명, 단가, 세금 설정을 따로 저장 나중에 상품 가격이 바뀌어도 과거 주문서가 변하지 않음
백엔드 설계

데이터 정합성, 이미지 비용, 확장성을 나눠서 설계합니다.

모든 것을 AWS-only로 만들면 통제력은 높지만 초기 비용과 운영 복잡도가 큽니다. 현재 계획은 비용과 안정성의 균형을 맞춘 하이브리드 구조입니다.

DB/Auth

Supabase

Postgres와 Auth를 담당합니다. Seoul region 선택 가능 여부, RLS/JWT, backup/PITR, connection pool 검증이 필요합니다.

API

TypeScript Backend

업무 command를 검증하고, 권한/중복요청/트랜잭션/감사로그/outbox를 책임집니다.

Media

Cloudflare R2

상품 이미지와 ZIP 파일을 저장합니다. custom domain과 cache rule이 있어야 이미지 요청 비용을 통제하기 쉽습니다.

Worker

AWS 제한 lane

전표, 이미지 ZIP, 썸네일, 정산 같은 오래 걸리는 작업만 SQS/ECS worker로 처리합니다.

핵심 불변조건

이 조건은 화면이 예뻐도 빠지면 안 되는 backend 기준입니다.

영역 설계 기준 금지선
감사 로그 성공/거부/실패 command를 business audit으로 분리 저장 원문 token, presigned URL, raw PII 로그 저장 금지
재고 동시성 PostgreSQL transaction, stable lock order, command별 음수 허용 정책 앱 메모리에서 수량 읽고 차감 후 저장하는 방식, 미송 원장 없는 음수 재고 금지
권한 서버 middleware + RLS defense-in-depth UI 버튼 숨김이나 user role 입력값으로 권한 판단 금지
대량 데이터 cursor/keyset pagination, async streaming export/import 동기 full scan, 전체 Excel 메모리 로드 금지
이력 보존 단가/상호/세금 설정 snapshot, soft-delete/status/reversal 과거 주문 금액이 master row 변경으로 바뀌는 구조 금지
Phase 현황

로컬 구현은 많이 진행됐고, 운영 증거는 아직 남아 있습니다.

Phase 5의 로컬 command slice는 충분히 쌓였지만, 실제 provider 계정과 production 환경에서 증명해야 하는 항목은 별도로 남아 있습니다.

큰 흐름

현재 상태 문서 기준으로 읽기 쉽게 줄인 표입니다.

Phase 현재 상태 일반 설명 다음 조건
Phase 0-2 Ready 기본 원칙, 보안, 권한, 운영 기준은 문서상 준비됨 큰 방향은 유지하고 구현 시 계속 참조
Phase 3 Prepared 이미지/미디어 구조는 준비됐지만 실제 R2/CDN 검증 필요 R2 bucket, custom domain, cache, 비용 로그 캡처
Phase 4 Captured 웹 UI first slice와 로컬 브라우저 검증이 많이 진행됨 앱/native/WebView 검증은 웹 완료 후 별도 진행
Phase 5 Local Captured 9/9 local command slice, 25 local execution-path command 기준 production HTTP, RLS/JWT, provider runtime evidence
Release Blocked 운영 배포 완료로 말하려면 실제 외부 증거가 필요 배포 URL, 로그, metric, trace, billing, restore/canary

진행률에 포함

production/full web transport, production HTTP, Supabase RLS/JWT, provider/worker/CDN/object-storage runtime, 성능/load/복구/canary.

진행률에서 제외

정책/상세규칙 미확정 19개 command. 관리자 결정 전까지 구현 금지 항목으로 분리합니다.

주의

문서 Ready는 “방향 확정”이고, Runtime Evidence는 “실제 계정에서 실행한 증거”입니다. 둘을 섞지 않습니다.

정책/블로커

관리자 결정 전까지 성공 구현을 열면 안 되는 항목입니다.

정책이 애매한 기능을 먼저 구현하면 나중에 DB, UI, 테스트, 운영 문서를 모두 되돌려야 합니다. 그래서 이 항목들은 진행률 분모에서 제외합니다.

Excluded From Progress

19개 policy/detail-rule blocker

삭제/복구/취소, 정산, VAT, today summary rebuild, finance settings 같은 업무 규칙은 세부 정책 없이는 success fixture/API/DB/UI mutation/provider enqueue를 만들지 않습니다.

Admin Answer Needed

남은 질문은 결정 문서에서 닫기

관리자 답변, PRD/spec delta, 상태 전이표, command inventory 전환안, golden cases, evidence acceptance가 준비되면 다시 진행률에 포함합니다.

관리자 결정이 필요한 대표 시나리오

정확한 항목 수와 최신 상태는 원본 blocker 문서를 기준으로 합니다.

시나리오 결정해야 하는 것 결정 전 금지
삭제/복구 계열 삭제를 취소, 보류, 역분개, 숨김 중 무엇으로 볼지 실제 DB row 삭제 또는 임의 reversal 구현
정산 마감/재오픈 누가 언제 마감하고, 마감 후 수정은 어떻게 허용할지 마감 후 금액/재고 수정 success path
부가세/할인 계산 계산 순서, 반올림 단위, 세포함/별도, 음수 처리 세금/정산 golden case 없는 계산 로직
요약 재생성 today/product summary rebuild 권한과 기준 시점 운영 데이터 재계산 API success
개발자 준비

개발을 계속 진행하려면 계정, 권한, 환경값을 먼저 준비해야 합니다.

아래는 개발자가 실제 runtime blocker를 닫기 전에 필요한 준비물입니다. 원문 secret 값을 문서나 채팅에 남기지 말고, 안전한 secret store와 배포 환경 변수에만 넣어야 합니다.

Cloudflare

이미 준비됨

현재 CLI는 jkyang83@gmail.com 계정으로 로그인되어 있고, 이 포털은 Cloudflare Pages에 배포됨.

  • Pages project: magic-wholesale-docs
  • 향후 R2 bucket, custom domain, cache rule 필요
  • R2 API token은 문서에 raw 값 저장 금지
Supabase

계정 생성됨

jkyang83@gmail.com 계정은 준비됨. 아직 project ref, region, DB/Auth 설정, RLS/JWT runtime 검증은 필요.

  • Organization / Project 생성 또는 확인
  • Region은 사용자 위치와 latency 기준 선택
  • anon/service role key 보관 방식 결정
  • RLS enabled table 확인 및 migration flow 결정
AWS

계정 생성됨

jkyang83@gmail.com 계정은 준비됨. AWS는 전체 백엔드가 아니라 queue/worker lane에 제한해서 사용합니다.

  • root access key 금지
  • IAM Identity Center 또는 최소 권한 IAM user
  • Budgets, CloudWatch log retention, SQS/ECS/ECR 준비
  • worker secret은 Secrets Manager 또는 배포 secret 사용

개발자가 받아야 할 준비물

아래 값이 있어야 production/runtime evidence를 안전하게 캡처할 수 있습니다.

구분 관리자가 준비 개발자가 할 일 주의
Supabase 계정 생성됨: jkyang83@gmail.com. 다음은 조직/프로젝트, region, billing, DB password, Auth 정책 migration, RLS/JWT rehearsal, connection pool, backup/PITR 확인 service_role은 사용자 요청 경로에 노출 금지
Cloudflare R2 R2 bucket, custom domain, API token, DNS 권한 upload/download POC, cache hit, CORS, signed access, 비용 로그 캡처 R2 egress free가 전체 무료라는 뜻은 아님
AWS worker 계정 생성됨: jkyang83@gmail.com. 다음은 IAM, budget alert 수신자, SQS/ECS 권한 bounded worker lane, retry/DLQ, log retention, 비용 alarm 검증 NAT/CloudWatch/worker 상시 비용 주의
도메인/DNS 미디어 도메인, 앱 도메인, Cloudflare DNS 관리 권한 custom domain, TLS, cache rule, security headers 확인 R2 cache는 custom domain 연결이 중요
GitHub/CI repo 권한, branch protection, deploy secret 승인 환경변수 주입, 검증 script, release artifact manifest 연결 dirty/local-only evidence를 release evidence로 승격 금지
정책 결정 남은 질문 답변, 업무 규칙, golden case 승인 PRD/spec delta, command inventory, fixture/test 업데이트 정책 미확정 command success path 구현 금지
Implementation Follow-up

음수 재고 처리 코드는 command별로 재검토해야 합니다

현재 설계 기준은 “재고가 절대 음수가 되면 안 된다”가 아닙니다. 미송/백오더로 승인된 흐름은 음수 현재고를 허용하되, 미송 잔량, 발송/해제 이력, 재고 원장과 같은 transaction 안에서 추적해야 합니다. 따라서 기존 local guard/test의 inventory_negative_not_allowed 계열은 주문, 미송, 샘플, 입고, 수동 재고조정별로 허용/거부 정책을 다시 나눠야 합니다.

공식 확인 경로

계정/비용/보안 관련 정보는 공식 문서를 기준으로 다시 확인해야 합니다.

Supabase Regions Supabase RLS Cloudflare Pages Direct Upload Cloudflare R2 Pricing R2 Cache + Custom Domain AWS Access Key Security
문서 보드

원본 문서를 카드처럼 찾습니다.

이 화면은 실제 Markdown 문서의 역할과 읽는 순서를 정리합니다. 검색어는 모든 화면과 문서 카드에 적용됩니다.

검색 결과가 없습니다.
배포/운영

이 포털은 Cloudflare Pages에 직접 업로드합니다.

제품 웹이나 앱과 분리된 정적 문서 포털입니다. 문서 요약이 바뀌면 HTML을 갱신하고 Cloudflare Pages에 다시 배포하면 됩니다.

현재 배포

공개 URL은 magic-wholesale-docs.pages.dev 입니다.

  • Cloudflare account: jkyang83@gmail.com
  • Pages project: magic-wholesale-docs
  • 배포 폴더: cloudflare/docs-portal/src

재배포 명령

정적 파일이므로 빌드 없이 폴더를 직접 업로드합니다.

  • npx wrangler pages deploy cloudflare/docs-portal/src --project-name magic-wholesale-docs --branch main --commit-dirty=true
  • Cloudflare 공식 Direct Upload는 prebuilt assets를 Pages에 올리는 방식입니다.

운영 규칙

문서 포털을 계속 신뢰할 수 있게 유지하기 위한 기준입니다.

상황 할 일 하지 말 것
백엔드 결정 변경 원본 Markdown 먼저 수정 후 포털 요약 갱신 HTML만 바꿔서 정본처럼 보이게 만들기
계정/secret 준비 secret store 또는 배포 환경변수에 저장 HTML, README, 채팅, artifact에 raw secret 기록
runtime evidence 캡처 로그/metric/trace/billing/restore 결과를 evidence index에 연결 local smoke를 production evidence로 승격
정책 결정 완료 PRD/spec, command inventory, tests, blocker status를 함께 갱신 정책 문서 없이 API success path부터 열기