베타 RC 에픽 계약
읽기 안내
에이전트별 에픽과 인수 조건을 정의한 내부 구현 계약입니다.
책임자·인수 조건을 확인할 때 사용하고 일반 연동 방법은 개발자 가이드를 참고하세요.
각 에픽은 하나의 책임 오너를 가집니다. 공유 파일은 wave당 단일 지정 작성자를 가지고; 협업자는 계약을 리뷰하고 테스트를 공급합니다.
공유 API 계약
Principal 타입
| Principal | 출처 | 백엔드 의미 |
|---|---|---|
anonymous | 자격 증명 없음 | 공개 엔드포인트만 |
buyer | 사용자 JWT role=buyer | 자기 buyer 대면 리소스만 |
seller | 사용자 JWT role=seller + seller 멤버십 | 소유한 셀러 리소스만 |
admin | 사용자 JWT role=admin | 플랫폼 운영자 엔드포인트만 |
service | 내부 서비스 자격 증명 | 명시적으로 허용 목록된 내부 라우트만 |
dev | 로컬 전용 dev 아이덴티티 | 로컬 개발만; 절대 프로덕션 아님 |
오류 계약
401 UNAUTHENTICATED: 누락/무효/만료/폐기된 자격 증명.403 FORBIDDEN: 인증된 principal이 role이나 테넌트 소유권 부족.404 NOT_FOUND: 리소스 부재 또는 의도적으로 숨김/비공개.409 CONFLICT: 유일성/멱등성/상태 충돌.402 NOT_LIVE_PAYMENT: 프로덕션 유료 결제 경로가 의도적으로 비활성.429 RATE_LIMITED: 남용/레이트 리밋 정책 초과.400 INVALID_REQUEST: 잘못된 DTO 또는 비즈니스 규칙 위반.
읽기 후 쓰기 계약
변경 성공은 서버 쓰기가 성공하고 FE가 정확한 서버 반환 상태를 새로고침하거나 보존할 것을 요구합니다. UI는 로컬 mock이나 낙관적 상태만 변경됐을 때 성공을 표시하면 안 됩니다.
EP-01 — 통합 아이덴티티 및 인가 경계
- 우선순위: P0
- 부모: ④
BACKEND_INFRA— 레인 ④-A - 책임 오너: 백엔드 아이덴티티 작성자
- 협업자: ② Platform FE, ③ Seller FE, ⑤ QA
- 주요 경로:
be-cloudflare/src/lib.rs,auth_impl.rs,refund_impl.rs,events_impl.rs,settle_impl.rs,endpoints_impl.rs,contracts/** - 공유 작성자: ④가 이 wave의 나열된 모든 백엔드 파일을 소유.
계약
anonymous, buyer, seller, admin, service, dev principal을 구분하는 단일 Identity/인가 리졸버 생성. 어떤 핸들러도 무인증 요청을 admin이나 seller로 재해석하면 안 됨. Seller 스코프는 seller 멤버십 필요. Admin 스코프는 DB role admin 필요. Service 자격 증명은 별개의 service principal이며 명시적으로 내부 라우트에서만 허용됩니다.
수용 기준
- Given 익명 요청, when 보호된 엔드포인트 호출, then
401수신 및 테넌트 데이터 없음. - Given buyer JWT, when seller/admin 엔드포인트 호출 또는 구독 목록, then
403수신 및 다른 테넌트 데이터 추론 불가. - Given Seller A와 Seller B, when 각각 리소스 목록 또는 변경, then 각각 소유 리소스만 보고 크로스 테넌트 변경 실패.
- Given admin JWT, when 운영자 전용 API 호출, then 운영자 데이터 수신; seller 소유 변경 API 호출 시 정책이 명시적이고 감사되어야 함.
- Given 프로덕션의
X-Dev-User또는DEV_AUTH, when 보호된 엔드포인트 호출, then 요청이 fail closed. - Given 인가 중 DB 조회 실패, when 요청 평가, then fail closed.
검증
Worker/D1 라우트 수준 테스트 + 스테이징 curl/Playwright 부정 인가 매트릭스: 익명, buyer, seller A, seller B, admin, service/dev 헤더.
EP-02 — 공개/비공개 가시성 Fail-Closed
- 우선순위: P0
- 부모: ④
BACKEND_INFRA— 레인 ④-A - 책임 오너: 백엔드 공개 API 작성자
- 협업자: ② Platform FE, ⑤ QA
- 주요 경로:
be-cloudflare/src/public_impl.rs,events_impl.rs,endpoints_impl.rs, slug 유일성 마이그레이션
계약
공개 스토어, 상품, 위젯, 피드백, 공개 체크아웃 표면은 전용 공개 DTO를 사용해야 합니다. 누락된 seller_settings, DB 오류, 미발행 스토어/상품/위젯, 비공개 위젯은 공개가 아닌 404/403으로 fail closed해야 합니다.
수용 기준
- Given
seller_settings없는 seller, when 공개 스토어 요청, then404반환. - Given 비공개/미발행 스토어 또는 상품, when 직접 URL로 접근, then 민감 필드 없이
404반환. - Given 비공개 피드백 위젯, when 피드백 또는 피드백 결제 제출, then 요청 거부.
- Given 중복 seller/product slug 후보, when 공개 조회, then 스키마 유일성 또는 결정론적 충돌 처리로 잘못된 리소스 선택 방지.
- Given 공개 DTO, when 직렬화, then seller 시크릿, webhook 시크릿, 승인된 공개 필드 너머의 PII, 계약에 필요하지 않은 내부 ID를 포함하지 않음.
검증
신규 및 업그레이드 D1 스키마 검사, Worker 공개 API 테스트, 스테이징 익명 브라우저 테스트.
EP-03 — FE 라우트 및 역할 경계
- 우선순위: P0
- 부모: ②
PLATFORM_FE - 책임 오너: 공유 FE 파운데이션 스튜어드
- 협업자: ③ Seller FE, ④ Backend, ⑤ QA
- 주요 경로:
fe/middleware/**,fe/lib/api/client.ts,fe/pages/login.vue,fe/layouts/**,fe/pages/admin/**,fe/pages/dashboard.vue,fe/pages/onboarding.vue
계약
브라우저 라우트는 실제 auth 상태와 /api/v1/me role로 가드됩니다. admin → /admin, seller → 셀러 콘솔, buyer → buyer/공개 표면 또는 안전한 랜딩. API 401은 무효 auth를 지우고 로그인으로 리다이렉트; API 403은 로그인이 고칠 것을 암시하지 않고 인가 오류 표시. 프로덕션 빌드는 절대 X-Dev-User를 자동 전송하지 않습니다.
수용 기준
- Given 익명 방문자, when
/admin,/dashboard,/onboarding열기, then 반환 의도와 함께/login으로 리다이렉트. - Given buyer 로그인, when seller/admin 라우트 열기, then
403UI 수신 및 seller 데이터 없음. - Given admin 로그인, when 로그인 성공, then
/dashboard가 아닌/admin에 랜딩. - Given 만료된 토큰, when API가
401반환, then FE가 auth를 지우고 로그인으로 리다이렉트. - Given 프로덕션 정적 빌드, when 토큰 없음, then 요청에
X-Dev-User를 포함하지 않음.
검증
FE 타입검사, 로컬 Playwright 역할 네비게이션, 스테이징 배포 아티팩트 Playwright.
EP-04 — 셀러 설정 및 상품 지속성
- 우선순위: P0/P1
- 부모: ③
SELLER_FE - 책임 오너: 셀러 설정/상품 작성자
- 협업자: ④ 백엔드 DTO 작성자, ⑤ QA
- 주요 경로:
fe/pages/settings/**,fe/pages/products/**,fe/stores/db.ts,fe/lib/api/client.ts,be-cloudflare/src/endpoints_impl.rs,verify_impl.rs
계약
FE는 camelCase 도메인 모델 사용; API는 snake_case DTO 사용. 명시적 매핑은 API 클라이언트/스토어 경계에서 발생해야 합니다. 셀러 프로필, 설정, 스토어 발행, webhook 메타데이터, 디바이스 기본값, 상품 상태, 상품 삭제, 상품 생성/업데이트 필드, 플랜, 라이선스, entitlement, slug 충돌은 서버를 통해 왕복해야 합니다.
수용 기준
- Given seller가 프로필/설정 업데이트, when 저장 성공, then 응답이 지속되고 리로드가 동일 값 표시.
- Given 설정 저장 실패, when UI가 처리, then 성공 토스트 없음, 이전 서버 상태 가시 유지.
- Given 시크릿 필드, when 재독, then 마스킹됨; 업데이트는 별개의 시크릿 업데이트 액션으로만.
- Given 상품 상태 토글 또는 삭제, when API 실패, then UI가 작업을 성공으로 표시 안 함.
- Given plans/license/entitlements가 있는 상품 생성/업데이트, when 저장 및 리로드, then 계약 필드 손실 없음.
- Given 중복 상품 slug, when 생성/업데이트 시도, then 서버가 명확한
409반환, FE가 표시.
검증
셀러 설정/상품 Playwright 읽기 후 쓰기, Worker API 테스트, 새 로그인/리로드 검증.
EP-05 — 공개 사용자 여정 및 구매 범위
- 우선순위: P1
- 부모: ②
PLATFORM_FE - 책임 오너: 공개 웹 작성자
- 협업자: ① Product & Design, ④ Backend, ⑤ QA
- 주요 경로:
fe/pages/index.vue,signup.vue,login.vue,store/**,checkout/**,donate/**,license/**,legal/**
계약
익명 사용자는 발행된 스토어/상품을 보고 지원되는 무료/공개 상호작용을 제출할 수 있습니다. 프로덕션 유료 구매 CTA는 실제 PG 승인까지 비활성 또는 명확히 사용 불가 표시. Legal 페이지는 링크되고 죽은 링크 없음. 공개 표면은 seller 인증 스토어 상태가 아닌 공개 API를 사용합니다.
수용 기준
- Given 익명 방문자, when 랜딩 페이지 방문, then legal 링크와 지원되는 CTA가 동작하고 미출시 기능이 live로 표시되지 않음.
- Given 익명 방문자, when 공개 스토어/상품 열기, then 로그인이나 seller 상태 없이 공개 API 데이터 렌더.
- Given 프로덕션, when 유료 구매 CTA 도달, then 비활성 또는 명시적
NOT_LIVE_PAYMENT반환, 유료 상태 생성 없음. - Given 스테이징, when 샌드박스 트랜잭션 허용, then 명확히 sandbox 라벨, 프로덕션 유료 entitlement 생산 안 함.
- Given 라이선스 검증 페이지, when 공개 사용, then 공개 레이아웃과 공개 API 계약 사용.
검증
공개 스토어, 상품, 무료 피드백, 비활성 프로덕션 구매 CTA, legal 네비게이션의 익명 스테이징 브라우저 E2E.
EP-06 — 플랫폼 운영자 콘솔
- 우선순위: P1
- 부모: ②
PLATFORM_FE - 책임 오너: 운영자 콘솔 작성자
- 협업자: ④ 백엔드 admin API, ⑤ QA
- 주요 경로:
fe/pages/admin/**,fe/layouts/**,be-cloudflare/src/auth_impl.rs,endpoints_impl.rs
계약
/admin/**은 admin JWT API로 지원되는 플랫폼 운영자 콘솔입니다. 크로스 테넌트 관리의 프록시로 setDevUser, seller fallback, seller 전용 데이터를 사용하면 안 됩니다. MVP는 운영자 대시보드, 사용자, seller 검증 리뷰, API가 존재하는 곳의 읽기 전용 감사/트랜잭션 상태를 표시합니다.
수용 기준
- Given 비admin, when
/admin열기, then 데이터 로드 전 접근 거부. - Given admin JWT, when
/admin열기, then 운영자 네비게이션과 인가된 데이터 로드. - Given admin이 seller 검증 리뷰, when 승인/거부 성공, then 서버 상태 변경 및 감사/결과 가시.
- Given admin API 실패, when 렌더, then FE가
401,403, 서버 오류 구분. - Given 페이지 소스, when 검사, then
setDevUser나 mock admin 아이덴티티 없음.
검증
역할 게이트 Playwright와 Worker admin 인가 매트릭스.
EP-07 — 커머스 신뢰성 및 결제 안전
- 우선순위: P1
- 부모: ④
BACKEND_INFRA— 레인 ④-B - 책임 오너: 커머스 무결성 작성자
- 협업자: ⑤ QA
- 주요 경로:
checkout_impl.rs,purchase_impl.rs,refund_impl.rs,events_impl.rs,settle_impl.rs,contracts/**, outbox/감사 코드
계약
커머스 연산은 멱등하고, 테넌트 스코프이며, 감사 가능합니다. 실제 PG가 비활성인 동안 프로덕션에서 실제 유료 entitlement를 생성하는 코드 경로는 없습니다. 소비자 없는 outbox 목적지는 명시적으로 비활성되거나 큐에 남고; 전달된 것처럼 위장하면 안 됩니다.
수용 기준
- Given 동일 멱등성 키의 중복 체크아웃 요청, when 동시, then 하나가 성공하고 다른 하나는 동일 결과 또는
409안전 반환. - Given 환불/재시도/구독 이벤트 요청, when principal이 소유권/admin 권한 부족, then fail closed.
- Given 프로덕션 결제 모드, when 유료 체크아웃/구매/피드백 결제 시도, then fail closed, 유료 entitlement 기록 없음.
- Given 소비자 없는 outbox 이벤트, when 디스패치, then 외부 전송된 것처럼 delivered/consumed로 표시 안 함.
- Given 동시성에서의 감사 쓰기, when 검증, then 체인 무결성 유지 또는 안전하지 않은 쓰기 직렬화.
검증
Worker/D1 동시성 테스트, 멱등성 테스트, 감사 체인 검증, 스테이징 샌드박스 트랜잭션 테스트만.
EP-08 — D1 스키마, 마이그레이션, 백업, 런타임 안전
- 우선순위: P1
- 부모: ④
BACKEND_INFRA— 레인 ④-C - 책임 오너: 데이터베이스/런타임 작성자
- 협업자: ⑤ QA
- 주요 경로:
be-cloudflare/migrations/**,be/migrations/**,wrangler.toml,scripts/**, 런타임 로깅/CORS 코드
계약
마이그레이션은 순방향 전용이고 재현 가능합니다. 로컬, 스테이징, 프로덕션 데이터는 격리 유지됩니다. 스키마 제약은 테넌트와 공개 조회 정확성을 지원합니다. 백업/복원과 롤백 절차는 프로덕션 사용 전 비프로덕션 스크래치 리소스에서 실행 가능하고 검증됩니다.
수용 기준
- Given 새 D1, when 마이그레이션 001–최신 실행, then 스키마 버전과 제약이 올바름.
- Given 기존 D1, when 마이그레이션 두 번 실행, then 중복/파괴적 동작 없음.
- Given seller/product slug, when 중복 시도, then DB 제약이 거부하거나 API가
409반환. - Given 프로덕션 백업 필요, when export/restore 리허설, then 스크래치 복원 행/해시 수 일치.
- Given 구조화된 Worker 오류, when 로그, then 시크릿/PII 미출력.
검증
신규/업그레이드 마이그레이션 테스트, D1 export/스크래치 복원, 스테이징 배포 검증, 롤백 리허설.
EP-09 — 스테이징 브라우저 E2E 및 릴리스 게이트
- 우선순위: P1 / 릴리스 전 필수
- 부모: ⑤
INDEPENDENT_QA - 책임 오너: QA 증거 작성자
- 협업자: 모든 구현 부모
- 주요 경로:
fe/e2e/**,fe/playwright.config.ts,scripts/verify-deployment.ps1,docs/agent/**,.devpay-control/**
계약
스테이징 Playwright는 로컬 Nuxt 서버가 아닌 공식 스테이징 배포를 타겟합니다. 테스트는 격리된 계정/데이터와 실제 Worker/D1 API를 사용합니다. 증거는 SHA, 환경, 액터 role, 명령, 결과를 기록합니다.
수용 기준
- Given 공식 스테이징 FE/API, when Playwright 실행, then 배포된 아티팩트 대상 실제 브라우저 흐름 수행.
- Given Seller A/B 계정, when 크로스 테넌트 접근 시도, then UI/API가 접근 거부.
- Given 설정/상품 변경, when 브라우저 리로드 또는 재인증, then 서버 상태 지속.
- Given 비공개 스토어/위젯, when 익명 직접 접근, then 차단.
- Given 릴리스 증거, when 테스트 미실행, then 상태는
NOT_VERIFIED유지.
검증
QA 소유 테스트 계획 승인, 재현 가능 아티팩트, 릴리스 게이트 권고.
EP-10 — 제품, 법률, 출시 표면
- 우선순위: P1 / 외부 발표 시 출시 차단 항목은 P0 표시
- 부모: ①
PRODUCT_DESIGN - 책임 오너: 제품 요구사항 작성자
- 협업자: PM, ② Platform FE, ⑤ QA
- 주요 경로:
docs/agent/**,fe/pages/legal/**,fe/pages/index.vue, 온보딩/가입 카피
계약
지원되는 기능만 공개적으로 표시됩니다. 법률과 지원 표면은 죽은 끝이 아니어야 합니다. 제품 수용 기준은 구현과 테스트 증거에 추적 가능으로 유지됩니다.
수용 기준
- Given 랜딩/가입 페이지, when 리뷰, then legal 링크 동작, 사용 불가 기능이 live로 광고되지 않음.
- Given seller 온보딩, when 리뷰, then 미사용 자격 증명 수집 안 함, API 모드에서 mock 동작 암시 안 함.
- Given 공개 베타 범위, when 릴리스 노트/UX 카피 리뷰, then 결제/이메일 한계가 명시적.
- Given 고객 지원 요구, when 지원 채널 없음, then 외부 공개 출시는 차단되거나 명시적으로 제한.
- Given 제품/설계 산출물, when AI 생성, then 계약적으로 필요하면 인간/벤더 수락까지 초안 표시.
검증
외부 발표 전 제품 카피/링크 감사와 PM 승인.