숨결필라테스 — 풀스택 기능 번들 배치 (FB-1 ~ FB-4)

#637 W1 · #662 4단계 W4-09(설계 기록 docs/design/s3-design-record.md §7 · §12). 기능 번들 feature/<d>/{app,console,server,client} 의 소유 · 교차 기능 계약 · 서버 모듈 · 호스트 바인딩 · 격리 DB 시험을 적는다. 정본 결정은 cocode stage6-decisions.md §3(D-04 · D-05 · D-10)이고, 구조는 POC demo-ecommerce-grocery 의 같은 문서(§5 · §6 · §13)를 따랐다.

1. 원칙

2. 번들 requires 가 비어 있는 이유

requires 는 feature_modules.py 의 생성 순서(위상 정렬)와 존재 검사에만 쓰인다. 기능 사이 의존은 패키지 의존이 아니라 호출자 소유 포트라 모듈은 서로를 import 하지 않는다(서버 모듈 6개의 pubspec 은 fitness_rules · serverpod 만). 포트 방향을 requires 로 적으면 수업 ↔ 예약(좌석 포트 · 회차 포트)이 순환이 되어 Feature dependency cycle 로 막힌다. 그래서 DAG 는 비우고, 포트 표(§4)를 이 문서의 정본으로 둔다. (D-05 ② — 역방향 효과 · 단일 화면 계산은 호스트 포트.)

3. 기능 소유권

기능 화면 서버 표(모델 · 유일 색인) endpoint(SDK client.modules.<기능>.*)
class_session A-01 · A-02 · C-01 · C-02 class_session(code 유일 · startsAt 색인 · revision) classSession(list · get) · classPlan(create · update — fitness.schedule)
class_booking A-03 · A-04 · C-04 · C-05 · C-06 class_booking(code 유일 · activeKey 유일(같은 수업 중복 예약 · 대기) · (memberId, requestKey) 유일(멱등) · sessionCode · memberId 색인 · revision) · booking_rule(studio 유일 · revision) · class_booking_sequence classBooking(create · mine · restriction · occupancy · previewCancel · cancel) · studioBooking(sessionBookings · cancelOnBehalf · offerSeat · closeRoster · sweep — 직원) · bookingRule(get · update — fitness.rules)
membership_pass A-05 ~ A-08 · C-03 membership_pass(code 유일 · (memberId, requestKey) 유일 · memberId 색인 · revision) · pass_product · pass_usage(passCode 색인) · pass_benefit · membership_pass_sequence membershipPass(mine · usages · products · benefits · purchase) · memberPassAdmin(table · hold · release · restoreOne — fitness.pass_admin)
instructor A-09 · A-10 instructor(code 유일 — A 값만) instructor(list · get)
studio_alert A-11 studio_alert(code 유일 · memberId 색인) · studio_alert_sequence studioAlert(mine · markRead · markAllRead)
alert_preference A-12 alert_preference(memberId 유일) alertPreference(mine · update)
호스트 — fitness_account(authUserId 유일 · account 유일) · fitness_member(memberId 유일) —

모듈 안 배치(6개 같음): server/lib/src/{model, bindings, rule, service, endpoint} — 모델은 기능 소유 .spy.yaml, 생성물(generated/ · 클라이언트 protocol/)은 공식 CLI 로만 만든다. 생성 템플릿의 constant/ · exception/ · helper/ · validation/(페이지네이션 · id 검사만, W4-09 TODO 표시 36건)은 서비스가 쓰지 않던 골격이라 실제 서비스 · 공유 규칙 · 오류 enum 으로 대체했다(결함 후보 C-15).

서버 protocol 이름은 기능 접두사를 붙였다(ClassBookingIntent · ClassBookingCancelOutcome · MembershipPassStatus · ClassSessionCategory/Level/Room · ClassSlotInput · MemberPassEntry · ClassSessionOccupancy) — 커널 package:core 가 모든 기능 client 를 다시 내보내 앱 도메인 이름과 겹치기 때문이다(결함 후보 C-14). 값 이름은 공유 규칙 · 앱 enum 과 같다(서버 단위 시험이 이름 집합을 단언).

4. 교차 기능 업무 — 호출자 소유 포트

업무 호출자(소유) 포트 공급 앱 바인딩(localOnly) 서버 어댑터(호스트)
회차 정보 · 회차 행 잠금(좌석 판정 줄 세우기) class_booking BookingSessionPort class_session WorldBookingSessionPort BookingSessionAdapter → ClassSessionSupply.find(lock:)
수강권 검사 · 차감 · 복원 · 유지 · 스탬프 · 노쇼 · 시스템 만료 class_booking BookingPassPort membership_pass WorldBookingPassPort BookingPassAdapter → MembershipPassSupply
예약 · 대기 · 전환 · 만료 · 취소 알림 class_booking BookingAlertPort studio_alert WorldBookingAlertPort BookingAlertAdapter → StudioAlertSupply.post(대기 계열은 waitlist 섹션)
좌석 점유 수 · 정원 증가 전환 class_session SessionSeatPort(앱 SessionBookingPort) class_booking WorldSessionBookingPort SessionSeatAdapter → ClassBookingSupply
아는 강사 class_session SessionInstructorPort instructor WorldSessionInstructorPort SessionInstructorAdapter → InstructorSupply.exists
구매 · 홀딩 · 해제 · 복원 알림 membership_pass PassAlertPort studio_alert WorldPassAlertPort PassAlertAdapter(pass 섹션)
콘솔 마스킹 연락처 membership_pass PassMemberPort 호스트 회원 명부 WorldMemberPort PassMemberAdapter → FitnessMember
알림 설정이 거르는 종류(FR-012 AC2) studio_alert StudioAlertPreferencePort alert_preference WorldStudioAlerts.enabled AlertPreferenceAdapter → AlertPreferenceSupply.enabled

5. 신원 · 역할 · scope

계정 역할 scope
member-yoon(M-001) 회원 fitness.book · fitness.cancel
manager-bae(강사 겸 IN-04) 매니저 fitness.cancel · attend · promote · pass_admin · schedule · rules
instructor-yoga(IN-06) 강사 fitness.attend

fitness.schedule · fitness.rules 는 PRD §11 표에 없는 scope 다(설계 기록 §2.1 — C-01/C-02 · C-06 용). PRD 정정 요청 후보로 남긴다.

6. DB · migration

7. 시험

층 위치 수 무엇
공유 규칙 package/fitness_rules/test 47 계약 표(신청 10 · 취소 8줄) · 상태머신 ①② · 4시간 · 대기 마감 경계 · 노쇼 · 잔여 하한/상한 · 홀딩 · 수업 입력 범위 · 알림 필터
기능 서버 단위(TZ=UTC) feature/*/server/test/unit 15 행 다음 판 · 진행 키 · 상태/오류 enum ↔ 공유 코드 이름 1:1 · 출석 권한 · 기본값
생성 SDK 통합 backend/demo_booking_fitness_server/test/integration/fitness 95 생성 SDK → 호스트 dispatcher → 기능 모듈 → 격리 DB. 성공 · 타인 거부/격리 · 불법 전이 · 입력 오류 · revision 충돌 · 동시성(마지막 자리 3명 · 같은 판 두 탭) · 멱등 · 차감 정합성 · 대기 자동 전환 · 시스템 만료(시계 주입) · 미바인딩 fail-closed · 인스턴스별 바인딩 · 운영 resolver · 부팅 시드 · 서버 모드 읽기(기준시각 · 회차 묶음 · 예약 현황 · me() · 안 읽음) · 계약 동등성(같은 18줄) · 데모 로그인(정책 표 · 403 두 겹 · TTL · 시드 밖 거부 · 역할 전환 — W4-09c)
앱 SDK 변환 feature/{class_session,class_booking,membership_pass}/app/test/src/*_sdk_test.dart · IN · SA · AP 저장소 시험 12 서버 실패 → localOnly 와 같은 실패 코드(노쇼 마지막 날 · 정원 좌석 수 포함) · 401/403 forbidden · 500 serverUnavailable · 주소 없음 serverMissing · 행 → 도메인
저장소 계약 동등성 package/fitness_binding/contract_test 4 시나리오 · 72 단계 같은 시드 · 같은 시계에서 localOnly 저장소(FitnessDemoKit)와 생성 SDK 저장소(실제 서버 → 격리 DB)가 단계마다 같은 결과(도메인 값 전체 · 실패 코드) — 회원(시간표 · 신청/대기/취소 · 수강권 · 구매 · 알림 · 설정 · 강사) · 매니저(보드 · 명단 · 출석 · 규칙 · 대행 · 자리 제안 · 편성 · 수강권 관리) · 강사(명단 · 권한 경계) · 역할 전환(회원 → 매니저 → 회원 — W4-09c). 행위자도 같다(서버 me() = 세계 계정). 서버 쪽은 앱과 같은 데모 로그인(역할 버튼)으로 행위자가 된다 — 시험 경계 토큰을 쓰지 않는다

8. 앱 서버 모드(FB-4 클라이언트)

기능 서버 모드 저장소 읽기 조립(다른 기능의 공개 읽기 endpoint 를 읽기만)
class_session ServerClassSessionRepository 좌석 · 대기 · 내 예약 상태(classBooking.occupancy/mine) · 무료 취소 시간(bookingRule.get) · 강사 목록(instructor.list)
class_booking ServerClassBookingRepository · ServerBookingRuleRepository 회차(classSession.get/byCodes) · 수강권 · 마스킹 연락처(membershipPass.mine · memberPassAdmin.table)
membership_pass ServerMembershipPassRepository —
instructor · studio_alert · alert_preference 생성 *Repository(SDK mixin — W4-09 TODO 표시 6건 구현) 이번 주 수업 수(classSession) · 알림 사실(classSession.byCodes · membershipPass.mine/products)