숨결필라테스 — 풀스택 기능 번들 배치 (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 시험을 적는다. 정본 결정은 cocodestage6-decisions.md§3(D-04 · D-05 · D-10)이고, 구조는 POCdemo-ecommerce-grocery의 같은 문서(§5 · §6 · §13)를 따랐다.
1. 원칙
- 한 업무 표(서버 테이블 · localOnly 컬렉션)는 한 기능만 쓴다(
tool/feature_modules.py check의 표 이중 소유 0). - 다른 기능의 데이터가 필요한 업무는 호출자가 포트를 소유하고, 호스트가 실행 인스턴스마다 공급 구현을
바인딩한다(앱:
package/fitness_binding, 서버:bindFitnessHost). 바인딩이 없으면 그 자리에서StateError(서버는 HTTP 500)로 실패한다 — 빈 결과 · 실제 시각 · 인증 정보로 몰래 대신하지 않는다. - 업무 판정은 순수 Dart 공유 패키지
package/fitness_rules한 곳(D-04 「UI · local repository · server 가 같은 표를 검증」). 앱BookingRules(typedef) ·PassRules·ClassSlotRules와 서버 서비스가 같은 함수를 부른다. 큰 공통 core 로 옮긴 것이 아니다(D-10) — 상태머신 · 불변식 · 범위 · 실패 코드만 있다. - 표시 문자열(B — 회원 · 강사 이름, 수업명 라벨, 알림 · 이력 문구)은 저장하지 않는다. 두 런타임 모두 앱이
코드(
fitness_<entity>/<id>/<field>)와 A 값(성별 · 종류 · 수치)으로 투영한다(설계 기록 §3).
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 |
- 포트는 호출자의 같은 트랜잭션으로 돈다. 취소 → 좌석 반환 → 대기 전환 → 차감 → 알림이 한 번에 커밋되거나 모두 버려진다(AC-02). 잠금 순서는 회차 행 → 예약 행 → 수강권 행(교착 회피).
- 모든 쓰기는 트랜잭션 머리에서 시스템 전이 스윕(대기 마감이 지난 회차의 대기 만료 · 만료일이 지난 수강권
만료)을 먼저 돈다 — localOnly
ClassBookingService.sweep와 같은 자리 · 같은 판정. 콘솔studioBooking.sweep은 같은 스윕을 명시적으로 부른다(fitness.promote).
5. 신원 · 역할 · scope
- 서버 신원 도메인은 업무 주체(데모 계정 · 회원 코드 · 강사 코드 —
host-integration.json의identityDomain)다. 기능 모듈은session.authenticated를 직접 읽지 않고 HostBindings 의caller포트 (FitnessCaller = ({account, role, memberId, instructorId, scopes})—fitness_rules)로 묻는다. - 운영 resolver
FitnessCallerResolver는 JWT 의 AuthUser(UUID)를 호스트 신원 매핑fitness_account로 주체로 바꾸고, scope 는 이 데모의 업무 scope(FitnessScope7개)만 남긴다. 매핑이 없으면 모든 업무가forbidden. 통합 시험 서버는 시험 토큰(demo:<계정>)을 시드 계정의 역할 · 회원 코드로 바꾸는 resolver 를 묶는다. - 서버 모드 데모 로그인(실제 인증 아님 — W4-09c): 호스트 endpoint
fitnessDemoSignIn.signIn(역할)이 시드 계정의 AuthUser ·fitness_account매핑을 보장하고 짧은 수명 JWT 접근 토큰을 준다.FITNESS_DEMO_SIGN_IN=true· 비 production 일 때만, 그 밖에는 403(login-flow-decision.md §5 · §6). - 소유 · 격리: 회원은 자기 예약 · 수강권 · 알림 · 설정만. 남의 것은 없는 것과 같다(
notFound— 존재를 알려 주지 않는다). 직원(역할 ≠ member)은 예약 현황 · 대행 · 표, 강사는 자기 수업의 명단 · 출석만.
| 계정 | 역할 | 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
- 모듈 6개 + 호스트의 migration 은 공식
tool/serverpod/cli.sh create-migration으로만 만든다. W4-09 는 기존 생성 CRUD 표(서버 모드 배포 이력 없음 · 행 없음)를 업무 모델로 바꾸며--force(표 재생성 경고 수락)를 썼다. 과거 migration 은 고치지 않고 새 버전을 덧붙였다(migration_registry.txtappend). - 서버 데모 시드
FitnessDemoSeed는 localOnly 와 같은FitnessWorldSeed(seed 436 · 2026-01-15 09:00 서울)의 A 행을 옮긴다 — 투어 수치(리포머 10회권 잔여 4/10 · 스탬프 6/10 · 10:00 매트 기초 잔여 2/8 · 19:30 리포머 마감 · 대기 1)가 두 런타임에서 같다. 실행 서버는 운영 모드가 아니고 표가 비었을 때만 부팅 때 넣는다. - 기준시각: 호스트가
FitnessClock을 모든 기능에 같은 값으로 묶는다 — 시험 · 데모는 시드 시각, 운영은 실제 시각(FITNESS_DEMO_CLOCK=seed|<ISO-8601>로 고정 가능).
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() = 세계 계정). 서버 쪽은 앱과 같은 데모 로그인(역할 버튼)으로 행위자가 된다 — 시험 경계 토큰을 쓰지 않는다 |
- 격리 DB: 시험 파일마다
fitness_it_<스키마 지문>_<pid>_<slot>DB 를 만들고 끝나면 지운다(다른 DB 는 건드리지 않는다). 로컬 ·검증 (tests-server)는 내장 Postgres,백엔드 통합 (server · PostgreSQL)는 잡 안 docker Postgres(FITNESS_IT_DB_*).
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) |
- 쓰기는 소유 기능의 endpoint 하나로만 — 서버가 scope · 소유 · 판을 다시 검사하고, 교차 효과(차감 · 전환 · 알림)는 서버의 한 트랜잭션이다. 앱은 같은 권한 판정을 세션 행위자로 먼저 한다(localOnly 와 같은 실패 코드).
- 세션:
registerFitnessServer()(fitness_binding)가 서버의fitnessAccount.me()(기능 모듈과 같은 호출자 포트)로 행위자를 만든다 — 로그인 · 매핑이 없거나 서버에 닿지 못하면 scope 없는 손님(모든 업무가 실패 상태로 그려진다). 앱 · 콘솔 부트스트랩이 localOnly 가 아니면 부른다. - 기준시각: 각 기능 endpoint 의
now()(호스트가 묶은 같은 시계) — 「오늘」 · 시작 여부 · 만료를 서버와 같은 시각으로 판정한다. - 실패: 서버 업무 실패 → 같은 이름의 실패 코드, 401 · 403 → forbidden, 연결 · 서버 오류 → serverUnavailable, 서버 주소 없음
(
FitnessServerMissing) → serverMissing. 조용히 빈 결과로 꾸미지 않는다. - 서버 모드 로그인 — 결정: A(서버 모드 데모 계정 매핑) — W4-09c 구현(근거 · 조건 · 시험은
login-flow-decision.md §5 · §6). 앱 · 콘솔 서버 모드 진입은 localOnly 와 같은 역할 버튼이
FitnessDemoSignIn(fitness_binding)으로 서버에 데모 로그인하고 세션 행위자를 바꾼다. 계약 동등성의 서버 쪽도 이 경로다. 기능 endpoint 통합 시험(86)은 시험 경계 토큰(demo:<계정>)을 그대로 쓴다(인증 경로는 데모 로그인 시험이 맡는다). Pages 는 localOnly 고정이다.