#662 S3 설계 기록 — 숨결필라테스 / booking_fitness

작성: 2026-10-10, PC-B(M2 Ultra) W1 선행 설계 worker(task task_d7e126a77059). 설계 · 판정만 했다 — 기능 코드 · 공급 ref · 기존 PR · 브랜치 · salvage 를 바꾸거나 머지 · 삭제하지 않았다. 이 PR 은 이 문서 하나만 더한다. 머지는 코디네이터 승인 뒤다.

조사 대상 소스: main 20d1b5bfb35d4f96033e5bea81213a9263bd175e(README 만 있는 initial), PR #1 story/cocode-662-assembly c4e3d37e9492fe0db5f259a9ba0eb669351953d3(이하 「조립 브랜치」 — 아래 표의 경로는 모두 이 커밋 기준), salvage/cocode-662-oyster-20261009-wip 6c76dc05(조립 브랜치 + 미커밋 214파일 보존 커밋 1개).

정본: PRD #662 전체 본문, 계약 커밋 baeab83538b30ebb945f0190d3387685e0d60c14 의 execution-contract · phases · baseline v1 · prd-dependencies · change-requests · 증거 형식. POC 세 앱(#653 · #657 · #659)의 S3 기록은 구성과 공급 결함 목록만 참고했고 내용은 이 앱의 소스 · 실행으로 채웠다.

이 저장소의 main 에는 다른 docs 가 없다(조립 브랜치에도 docs/ 없음 — docs/fullstack-feature-layout.md · docs/brand.md · docs/locale-data.md · docs/mobbin-references.md 모두 부재). 따라서 이 문서가 첫 설계 문서다.

상태 어휘: 구현+검증 = 그 AC 동작을 단언하는 테스트가 현재 소스에 있다 · 구현만 = 코드는 있으나 단언 없음 · 부분 = 요구 일부 또는 연결이 빠짐 · 없음 = 코드 없음 · TODO · 빈 화면 · 단언 없는 테스트. 조립 브랜치는 현재 앱 · 웹 컴파일이 실패한다(§6 CI) — 「구현만」 코드도 실행 근거는 0 이다.

0. 요약

판정 항목 결과
FR 22개 / 구현+검증 0 / 구현만 14 / 부분 7 / 없음 1(FR-011). 부분: FR-001 · 007 · 012 · 018 · 019 · 020 · 021
FR 수준 AC 44개 / 구현+검증 2(FR-019 AC2 · FR-021 AC1) / 구현만 31 / 부분 7 / 없음 4
화면 §6 18개 ID 모두 Page 존재(직접 작성 13 + 생성 골격 5). 셸(하단 5탭 · 역할 · 배너 · 초기화 · 상태 미리보기) 없음. 유효 Widgetbook use-case 5/31, 유효 use-case 없는 Page 13
도메인 · FSM 규칙은 앱 localOnly 층에만 있다(feature/*/app/lib/src/{domain/rule,data/local} + package/fitness_world). 서버는 8개 모두 생성 CRUD — 전이 · 불변식 · 소유 · scope 0
5종 검증 핵심 3 feature(class_session · class_booking · membership_pass) app/console 테스트 0. PRD §20 BDD 7편 0. 골든 기준 PNG 는 app_router 24장뿐. Patrol 0. testScaleInvariant 0
backend(FB-3) 통합 테스트 7개는 list 빈 목록 · 미인증 거부 · getById(999) null 뿐. 호스트 migration 에 feature 테이블 없음. SDK Repository 없음
cob plan exit 0 · FR 22 매핑 · 결정론 covered 10 · semantic review-pending 12 · orphan 0 · NFR 12 · hand-author 14 · emit TODO(review) 8 (cob v1 55ce5e14 + W1 레시피 5c030ed9)
cleanbase quick BLOCKED — demo-spec exit 65(레시피가 없습니다: booking_fitness), 36.7 s, 다이제스트 없음. W1 cob 5c030ed9 도 검증되지 않은 레시피 exit 65 → coco-de/cocode#1148
재사용 PR #1 부분 채택(출발점) · salvage 부분 채택(방향만) · main 채택(빈 기준) — §8
새 upstream 이슈 coco-de/co-package#99(co_faker 역할 추론) · coco-de/cocode#1148(cleanbase 스크립트)
전체 완료 선언하지 않는다. 13게이트 모두 미충족(사이드카 없음)

1. FR/AC 전수 대조

경로 약어: CS=feature/class_session · CB=feature/class_booking · MP=feature/membership_pass · IN=feature/instructor · SA=feature/studio_alert · AP=feature/alert_preference · BR=feature/booking_rule · FW=package/fitness_world · P(d,r)=<d>/<r>/lib/src/presentation/page · R(d,r)=<d>/<r>/lib/src/domain/rule · L(d,r)=<d>/<r>/lib/src/data/local. 소유 bundle 은 feature/<d>/bundle.json.

전역 차단(모든 「구현만」에 걸린다):

FR · 소유 코드 AC1 AC2 테스트(단언) FR
001 진입 · 역할 · 초기화 / 셸 + FW FW/lib/src/world/fitness_world.dart(reset) · FW/lib/src/seed/fitness_demo_accounts.dart 없음 — 역할 버튼 · 배너 UI 없음, 첫 화면은 커널 AppStatusPage 부분 — 세계 reset 과 시드(잔여 4 · 대기 1)는 단언, 「초기화」 UI 없음 FW/test/src/fitness_world_test.dart(접두사 초기화) · FW/test/src/fitness_world_seed_test.dart 부분
002 주간 시간표 / CS P(CS,app)/class_timetable_page.dart · R(CS,app)/timetable_builder.dart 구현만 구현만(day_empty_title) 없음(seed 테스트는 일요일 0건만) 구현만
003 수업 상세 / CS P(CS,app)/class_session_detail_page.dart(cta_waitlist · cta_my_booking) 구현만 구현만 없음 구현만
004 예약 · 대기 확인 / CB R(CB,app)/booking_rules.dart(decide) · L(CB,app)/class_booking_service.dart · P(CB,app)/booking_confirm_page.dart 구현만 구현만 없음 구현만
005 수강권 유효성 / CB + MP R(MP,app)/pass_rules.dart(usability) · booking_confirm_page.dart(no_pass) 구현만 구현만 없음 구현만
006 내 예약 · 취소 / CB BookingRules.cancelOutcome(>= freeCancelHours) · P(CB,app)/my_bookings_page.dart 구현만 구현만 없음 구현만
007 대기 자동 전환 / CB(FW) ClassBookingService.promoteFreedSeats · _fill · _renumber · P(CB,console)/studio_booking_board_page.dart(offer_seat) 구현만 부분 — autoPromote 를 BookingRulePort 에서 읽지만 C-06 은 다른 세계(X3)에 저장 없음 부분
008 내 수강권 카드 / MP P(MP,app)/my_passes_page.dart · widget/pass_reward_card.dart · widget/stamp_grid.dart 구현만 구현만(hold_badge) 없음 구현만
009 이용 이력 / MP P(MP,app)/pass_usage_page.dart · L(MP,app)/membership_pass_ledger.dart 구현만 구현만 없음 구현만
010 상품 · 구매 요약 / MP P(MP,app)/pass_products_page.dart · pass_purchase_page.dart · PassRules.expiresOn 구현만 구현만(mock_notice) 없음 구현만
011 강사 / IN(생성) P(IN,app)/instructor_gallery_page.dart · instructor_profile_page.dart — 생성 골격 + 목데이터 목록 없음 — 칩 필터 없음 없음 — ClassTimetablePage.highlightInstructorId 호출처 없음 4종 상태 렌더 테스트만(AC 단언 없음) 없음
012 알림함 · 설정 / SA · AP(생성) P(SA,app)/studio_alert_inbox_page.dart(섹션 · 안 읽음) · P(AP,app)/studio_alert_settings_page.dart 부분 — 예약 쪽 알림 생성과 연결 없음(X3) 없음 — 설정 끄기가 생성을 막지 않음 4종 상태 테스트만, usecase/bloc 테스트는 TODO 부분
013 콘솔 주간 편성 / CS console P(CS,console)/class_plan_page.dart · widget/class_plan_row.dart 구현만 구현만(ClassSlotEditRoute) 없음 구현만
014 수업 등록 · 수정 / CS console P(CS,console)/class_slot_form_page.dart · CS/app/lib/src/data/local/local_class_session_repository.dart(capacityBelowBooked · promoteFreedSeats) 구현만 구현만 없음 구현만
015 회원 · 수강권 / MP console P(MP,console)/member_pass_table_page.dart · widget/pass_manage_dialog.dart 구현만 구현만(reasonRequired) 없음 구현만
016 출석 체크 / CB console P(CB,console)/class_roster_page.dart · ClassBookingService.closeRoster 구현만 구현만(roster_locked) 없음 구현만
017 예약 현황 · 취소 대행 / CB console CB/console/lib/src/presentation/widget/proxy_cancel_dialog.dart · cancelOutcome(waive:) 구현만 구현만 없음 구현만
018 예약 규칙 / BR(생성) + CB P(BR,console)/booking_rule_settings_page.dart(커널 DemoWorld) · BookingRules.restrictedUntil 부분 — 콘솔 값이 앱 판정에 전달되지 않음(X3) 구현만(restricted 문구) 4종 상태 테스트만 부분
019 앱 ↔ 콘솔 연동 / FW FitnessWorld.transact · refresh · changes · 각 *Reader 구독 부분 — 세계 단위 탭 간 반영만 단언, 콘솔에는 FitnessWorld 미등록 구현+검증 FW/test/src/fitness_world_test.dart(「쓰기는 다른 탭…」 · 「초기화는 이 데모의 접두사 키만…」) 부분
020 상태 4종 · 미리보기 / 전 화면 각 *_state_view.dart(Skeleton · Empty · Error) · FW/lib/src/world/fitness_preview_source.dart 구현만(A-01 테스트 없음) 부분 — retry 는 있으나 미리보기 소스 · 배너 미등록, 생성 테스트는 버튼 존재만 생성 화면 5개의 4종 렌더 테스트만 부분
021 서버 없음 / 커널 package/core/lib/src/runtime/demo_only_guard.dart · configuration_error_app.dart 구현+검증(COB_DEMO_ONLY 빌드) 부분 — 커널 상태 화면 배너, PRD 배너 아님 package/core/test/src/runtime/demo_only_guard_test.dart · app/app/test/app_test.dart 부분
022 운동 안전 면책 / CS + CB class_session_detail_page.dart(safety) · booking_confirm_page.dart(건강 입력 없음) 구현만 구현만 없음 구현만

salvage 를 얹으면: FR-011 AC1 칩 필터(instructor_gallery_page.dart)가 생겨 없음 → 구현만, AC2 InstructorNavigation.openTimetable 이 생기나 미등록이라 부분, FR-012 알림함이 FitnessWorld.studio_alerts 를 읽고 StudioAlertLedger 가 AlertPreferencePort 로 생성을 거른다(미등록이라 부분). 집계는 구현+검증 0 / 구현만 14 / 부분 8 / 없음 0 으로 바뀌지만, 두 feature 의 테스트 38개(instructor 22 · studio_alert 16)가 삭제되고 대체가 없으며 컴파일 오류가 5건으로 는다(§8).

2. 도메인 · 역할 · FSM · 불변식

2.1 엔티티 대조(§8 11개)

서버 모델은 §8 필드와 일치하지만 소유자(memberId) · 외래 키(sessionId · passId) · revision · requestKey 가 없다. 앱 도메인 엔티티는 업무 규칙에 필요한 필드를 더 갖고 있어 서버와 어긋난다. 테이블 이중 소유는 없다(tool/feature_modules.py check 가 검사).

§8 엔티티 서버 *.spy.yaml(테이블) 서버 ↔ §8 앱 도메인 엔티티와의 차이 FW 컬렉션
class_session CS/server/.../class_session.spy.yaml(class_session) 일치, category · level 은 String(enum 아님) 앱: +id · instructorId · revision, −instructorName · remainingSeats · waitlistCount · imageUrl(파생) class_sessions
class_booking CB/server/.../class_booking.spy.yaml + status enum 7값 일치 + status, 기본값 waitlisted(PRD initial booked) 앱: +sessionId · memberId · passId · appliedAt · closedAt · deducted · penaltyWaived · cancelledBy · requestKey · revision — 서버에 없음 class_bookings
membership_pass MP/server/.../membership_pass.spy.yaml + status 4값 일치 + status 앱: +memberId · productId · category · unlimited · purchasedAt · expiresOn(String, 서버 expiresAt DateTime) · pausedFrom · validDays · requestKey · revision membership_passes
pass_benefit · pass_usage · pass_product · pass_line MP/server/.../*.spy.yaml 일치 앱이 표시 필드(title · description · name · summary · productName · discountNote)를 버리고 kind/code 로 바꿈 — B 투영 전제(§3) pass_benefits · pass_usages · pass_products
instructor IN/server/.../instructor.spy.yaml 일치 일치 + id instructors
studio_alert · alert_preference SA · AP server 일치 소유자 필드 없음(회원별 격리 불가) studio_alerts · alert_preferences
booking_rule BR/server/.../booking_rule.spy.yaml 일치 앱 사본 2개(BR/console/.../booking_rule.dart · CB/app/.../booking_rule.dart) booking_rules

2.2 상태 머신

전이 서버 앱 localOnly
① 허용 전이 표 없음 — ClassBookingService.update 가 request.status 를 그대로 복사(종료 상태에서도 임의 전이) R(CB,app)/booking_rules.dart BookingRules.transitions. allowed() 는 선언만 있고 호출처 없음 — 서비스가 경우마다 인라인 검사
① waitlisted → booked(시스템) 없음 _fill / promoteFreedSeats(취소 시 autoPromote) · 콘솔 offerSeat(fitness.promote), 차감 + 순번 재부여
① waitlisted → expired(시스템) 없음 _expireAll — 자리가 마감 후 생길 때만 지연 실행. 시각 경과 스윕 없음
① booked → cancelled / late_cancelled 없음 cancel() — cancel scope · 본인 또는 직원 · revision 검사 · 직원만 면제(사유 필수)
① booked → attended / absent 없음 closeRoster + canAttend(강사는 자기 수업만)
② active ↔ paused 없음 L(MP,app)/local_membership_pass_repository.dart hold/release — pass_admin · revision · illegalTransition · 만료일 연장/환원
② active ↔ exhausted 없음 PassRules.afterDeduct / afterRestore(membership_pass_ledger.dart)
② active/paused → expired(시스템) 없음 빈칸 — 읽을 때 PassRules.usability 로 파생만, expired 를 쓰지 않음. 홀딩 종료 자동 복귀 없음

2.3 불변식 위치

불변식 서버 앱 localOnly 4단계
정원 ≥ 예약 수 없음 BookingRules.decide(seats < capacity && queue.isEmpty) · capacityBelowBooked(FR-014) 규칙을 순수 Dart 공유 패키지로 옮겨 서버 · 앱이 같은 판정을 쓰고 계약 동등성 테스트(현재 booking_rules.dart 머리 주석의 「계약 동등성 시험」은 존재하지 않는다)
잔여 ≥ 0 없음 afterDeduct 0 하한 · afterRestore 총량 상한 규칙 표 단위 테스트(NFR-003)
대기 순번 연속 없음 _renumber 동일
같은 수업 중복 예약 · 대기 없음 create → duplicate 실패 서버 유니크 인덱스(sessionId, memberId, 활성 상태)
4시간 경계(≥ 무료) 없음 left >= Duration(hours: freeCancelHours) — 정확 경계 테스트(정확히 4h)
시작 1시간 전 대기 닫힘 없음 waitlistOpen 시계 주입 스윕 + 테스트
노쇼 제한 없음 restrictedUntil 테스트
홀딩 → 만료 연장 없음 hold +일수, release 미사용 일수 환원 테스트
멱등 없음 booking create 의 requestKey 서버 requestKey 유니크
revision(낙관적 동시성) 없음(update/delete 만 forUpdate 행 잠금, create 는 트랜잭션 없음) staleRevision(cancel · pass admin) 서버 revision 열 + 충돌 테스트
소유 · 격리 없음 — list 가 모든 행 반환. AuthenticatedMixin.requireLogin 만, scope 없음 _owned(회원 본인 · 직원 전체) · PassRules.usability memberId 서버 owner 열 + scope 검사 + 타인 거부 테스트
금액 · 재고(PRD 해당: 수강권 잔여 = 초기 − 차감 + 복원) 없음 ledger 이벤트 합 규칙 표 테스트로 「차감 정합성 100%」(§3 지표)

3. 데이터 A/B/C — L-1 초안

원칙: UI 언어는 업무 관할(ko · KRW · Asia/Seoul · 전화 형식)을 바꾸지 않는다(FW/lib/src/seed/fitness_world_spec.dart — seed 436 · 기준시각 2026-01-15T09:00+09:00 · KRW). B 필드는 co_demo_world DisplayProjector 로 entity/id/field 키(id = 업무 코드)에서 만들고, 생성 메시지(알림 · 이력 문구)는 i18n 템플릿 + A 파라미터로 만든다. 데모에 번역 사전을 두지 않는다.

엔티티 · 필드 분류 투영 키(entity/id/field) 또는 출처 비고
class_session: id(CS-0115-1930) · startsAt · durationMinutes · capacity · remainingSeats · waitlistCount · imageUrl · category · level(코드) A FW 업무 행 category/level 라벨은 B(i18n enum 라벨)
class_session.title B fitness_class_session/<CS-id>/title — co_faker fitness.className(category · level 일관) 투어 고정 수업명(「리포머 중급」 등)은 ko 에서 PRD 문구와 일치해야 함 → 4단계 확인
class_session.room B fitness_class_session/<CS-id>/room — fitness.studioRoom
class_session.instructorName · class_booking.instructorName B(참조) fitness_instructor/<I-id>/name 을 읽는다(복제 저장 금지)
class_booking: id · sessionId · memberId · passId · status · waitlistPosition · bookedAt · startsAt · deducted · penaltyWaived · revision · requestKey A FW
class_booking.classTitle · passName B(참조) 수업 · 수강권 상품 키를 읽는다
class_booking.cancelReason 시드 = B(fitness.cancelReason, fitness_class_booking/<id>/cancelReason) / 콘솔 입력(페널티 면제 사유) = C UserEditOverlay 로 C 우선
membership_pass: remainingSessions · totalSessions · attendedCount · stampTarget · expiresAt · pausedUntil · noShowCount · status · productId · memberId A FW
membership_pass.passName · pass_product.name · pass_line.productName B fitness_pass_product/<P-id>/name — fitness.passName + passTerm 일관(60 · 180 · 30일) 수강권은 상품 키를 참조
pass_product.summary · pass_line.discountNote B fitness_pass_product/<P-id>/summary · i18n 템플릿(할인율 A)
pass_product.price · sessions · validDays · pass_line.unitPrice · quantity A(quantity 는 사용자 선택 = C 입력 → A 결과) 금액 정수 원, DemoFormat.money ASCII 숫자
pass_benefit.title · description B fitness_pass_benefit/<B-id>/{title,description} requiredStamps · unlocked 는 A
pass_usage.title · description B(생성 메시지) i18n 템플릿(usage.deduct 등) + A(kind · delta · 수업 키) 콘솔 수동 복원 사유는 C
instructor.name · specialty · career · bio B fitness_instructor/<I-id>/{name,specialty,career,bio} — co_faker person.fullName · fitness.instructorSpecialty · fitness.instructorCareer(c003ca2c 에서 지원) photoUrl · rating · weeklyClassCount · totalClassCount 는 A
studio_alert.title · body B(생성 메시지) i18n 템플릿 + A(category · 수업 키 · 시각) isRead 는 A(사용자 행동 결과), createdAt A
alert_preference 전 필드 · booking_rule 전 필드 C 입력 → A 저장 언어 무관
회원 이름(fitness_member/<M-id>/name) B FW/lib/src/display/fitness_member_display_fields.dart — 성별(A) 일관 person.fullName 투어 고정 pin(아래 예외)
회원 연락처 A(언어 고정) korea.mobilePhone 마스킹 업무 국가 형식 고정

언어 고정 예외 · 주의

L-2 지원 표(계획): baseline v1 c003ca2c 에서 co_fitness_domain.dart 의 className · classCategoryLabel · classLevelLabel · studioRoom · instructorSpecialty · passName · cancelReason · noShowNote · instructorCareer 가 11개 언어 native(co-package#57 · #71 · #78). 조립 브랜치의 d23a5c42 는 도메인 팩 ko/en 만(나머지 영어, ar 조용히 영어)이고 cob plan --entities 가 instructor.specialty · career 를 unsupported 로 보고했다(§9). 실제 11개 언어 × 필드 표(DemoLocaleSupport)는 상향 후 실제 출력으로 측정해 docs/locale-data.md 에 싣는다(4단계 W4-10). 78911c1a(co_demo_world 언어 중립 폴백 native 분류 수정, co-package#96)는 「v2 반영 예정」.

4. 화면 · shape · Page ↔ Widgetbook

ID 실제 Page(파일) PRD bloc 이름 shape 4종 상태 유효 use-case
A-01 ClassTimetablePage(P(CS,app)/class_timetable_page.dart) class_timetable ○(Cubit) timetable hand-author — LayoutBuilder 3단(목록 · 2열 · 7일 그리드) ○ ✗(use-case 가 bloc: 을 넘김, Page 는 cubit:)
A-02 ClassSessionDetailPage class_session_detail ○ hero_detail hand-author ○ ✗(같은 이유)
A-03 BookingConfirmPage ✗(class_booking_create) form hand-author ○ ✗(없는 ClassBookingCreatePage 참조)
A-04 MyBookingsPage ✗(class_booking_board) status_board(탭 7) ○ ✗(없는 ClassBookingBoardPage)
A-05 MyPassesPage + PassRewardCard ✗(pass_membership) 🆕 reward_card hand-author(진행 · 스탬프 그리드 · 혜택) — F-3 전 ○ ✗(없는 PassMembershipPage)
A-06 PassUsagePage ✗(pass_usage_timeline) timeline hand-author ○ ✗
A-07 PassProductsPage ✗(pass_product_list) list ○ ✗
A-08 PassPurchasePage ✗(pass_purchase_lines) line_items ○ ✗
A-09 InstructorGalleryPage(생성) ○ gallery 생성 골격(칩 필터 없음) ○ ○
A-10 InstructorProfilePage(생성) ○ profile 생성 골격 ○ ○
A-11 StudioAlertInboxPage(생성) ○ inbox 생성 골격 ○ ○
A-12 StudioAlertSettingsPage(AP, 생성) ○ settings ○(empty 정의 없음) ○
C-01 ClassPlanPage ✗(class_plan_timetable) console timetable hand-author(verified 게이트 밖) — 요일 탭 + 행, 와이드 주간 그리드 아님 ○ ✗
C-02 ClassSlotFormPage ○ form ○ ✗(bloc:/cubit:)
C-03 MemberPassTablePage ○ data_table → 실제는 ListView 행(표 아님) ○ ✗
C-04 ClassRosterPage ✗(class_roster_checklist) console checklist hand-author(Checkbox · Progress · 잠금) ○ ✗
C-05 StudioBookingBoardPage ○ status_board ○ ✗
C-06 BookingRuleSettingsPage(BR, 생성) ○ settings ○ ○

5. 브랜드 — F-9

항목 현재(조립 브랜치) 4단계
docs/brand.md 없음 「숨결필라테스」 브랜드 문서(톤 · 팔레트 · 서체 · 예시)
테마 package/resources/lib/src/theme/app_theme.dart 가 CoreThemePresets.light / .dark 그대로 — PrimitiveColors.generate 브랜드 팔레트 없음(주석: 커널에 브랜드색 없음) 브랜드 seed 색으로 팔레트 생성, 라이트/다크
토큰 7축 색: coui semantic CoreColors.* 만 · 서체: Pretendard 400/500/600/700 번들, 텍스트 체인 49회, TextStyle( 0 · fontSize: 0 · 간격: 토큰 없음, 숫자 EdgeInsets 38회(all(16) 25) · 반경: coui 기본 · 그림자: 정의 없음 · 모션: 정의 없음(Duration(milliseconds 0) · 아이콘: LucideIcons 12, Material Icons. 0 간격 · 반경 토큰 사용으로 교체, 모션 · 그림자 축은 coui 기본을 명시
raw 색 grep(feature/**/lib · app/**/lib · package/**/lib, *.g.dart 제외) Color(0x 0 · Color.fromARGB 0 · hex 리터럴 0 · Colors. 25건은 모두 CoreColors. 토큰 → raw Material 색 0 CI 게이트로 유지
의미 색(NFR-008) 마감 error · 대기 warning · 잔여 적음 tertiary · 출석 success 를 사용 골든 라이트/다크로 확인
대비(WCAG AA) 표 없음 브랜드 팔레트 확정 후 라이트/다크 텍스트 · 배지 쌍의 대비 표를 docs/brand.md 에
글꼴 외부 요청 google_fonts 없음 · LocaleFallback(Noto 부분집합을 "Roboto" 로 등록, ar/ja/zh/ko) — tool/gates/check_locale_fallback_font.py 가 강제 POC(#659)에서 fonts.gstatic.com 1건 관찰 후 고정 → 공개 스모크에서 외부 요청 0 재확인
Widgetbook 브랜드 토큰 없음 테마 addon 에 브랜드 테마

6. 5종 검증 인벤토리

패키지 unit widget golden(파일 / 기준 PNG) Widgetbook use-case(유효) BDD .feature
class_session app · console 0 0 0 / 0 8(0) 0
class_booking app · console 0 0 0 / 0 8(0) 0
membership_pass app · console 0 0 0 / 0 10(0) 0
instructor(생성) 9 파일 2 2 / 0 2(2) 2(각 1 시나리오, 자리 표시)
studio_alert(생성) 8 1 1 / 0 1(1) 1
alert_preference(생성) 8 1 1 / 0 1(1) 1
booking_rule console(생성) 8 1 1 / 0 1(1) 1
app_router 2 2 1 / 24(ko 만) – 1(2 시나리오)
package/fitness_world 2 파일(19 test) – – – –
서버 feature 7 validator 7 파일(페이지네이션 · id 만, // TODO: 추가 단위 테스트 작성) – – – –
잡 결과 · 근본 원인 분류
계약 게이트 번역 패리티 위반 98건 — 도메인 feature 10개가 ko/en .i18n.json 만(9개 언어 파일 없음 90건) + studio_alert 형식 데모 결함
번들 모듈 → 호스트 코드 생성 widgetbook_generator … FormatException: Not an instance of Type(없는 Page 를 가리키는 use-case 21개) 데모 결함
Android 빌드 Undefined name 'seedClassSessionDemoWorld' 외 2(X1) 데모 결함
사이트 빌드 같은 X1 데모 결함
골든 (compare) 새 suite 기준 PNG 없음 + app_router kernel_status · kernel_error 0.22~4.25% 차이 데모 결함(Linux update 필요)

main 에는 워크플로가 없다(README 만) — 이 문서 PR 에는 CI 가 돌지 않는다.

7. backend — FB-3 · FB 전체

FB 현재 판정
FB-1 구조 · 소유권 bundle.json 9개(전부 requires: []) · host-integration.json 7개(identityDomain: AuthenticationInfo.userIdentifier, 사용처 없음). docs/fullstack-feature-layout.md 없음 부분 — class_booking 은 포트로 class_session · membership_pass · booking_rule 에 의존하는데 requires 에 없음
FB-2 조립 · 의존 호스트 server → feature server path 7 · generated/endpoints.dart 등록 · SDK(backend/demo_booking_fitness_client) → feature client 7 · UI → server import 0 · 모듈 → 호스트 역참조 0 · 테이블 이중 소유 0(feature_modules.py check). UI → feature client 0(package/serverpod_service 경유) 부분 — DAG 가 비어 있음
FB-3 실제 백엔드 서버 서비스 8개 = 생성 CRUD(/// CRUD for the declared entity schema, TODO). 통합 테스트 backend/demo_booking_fitness_server/test/integration/<feature>/*_endpoint_test.dart 7개 — withServerpod(기본 rollback) + 내장 Postgres(config/test.yaml dataPath), 단언은 list 빈 목록 · 미인증 거부 · getById(999) null. create · 타인 거부 · 불법 전이 · 입력 오류 · 동시성 0. migration 에 feature 테이블 없음 → DB 를 쓰는 list 도 실패할 가능성(미실행) 없음
FB-4 데모/서버 계약 CS · CB · MP · BR 은 Local 저장소만 — 비-localOnly 에서 registerClassBookingModule 이 일찍 return 하고 아무도 부르지 않는 registerClassBookingServerModule 을 기대. IN · SA · AP 의 *_serverpod_mixin.dart 는 모든 메서드가 UnexpectedFailure('… 아직 구현되지 않았습니다')(fail-closed 지만 같은 계약 아님) 없음
FB-5 재현 · 증거 cleanbase BLOCKED(§9) · 조립 ref 가 baseline v1 과 다름(bricks 8f6a0440c / kernel d36c5ccb, §10) 없음

CI 에서 백엔드 통합 테스트는 verify / tests-server(ONLY_SERVER=1 test_all.sh → feature_modules.py test-host, 내장 Postgres — 서비스 컨테이너 없음). golden.yml(compare · update) · pages.yml(build · deploy · smoke, 자격 증명 스캔 포함). tool/gates/check_all.sh 는 identity · slots · feature_modules.py check · package_layers · 파일당 클래스 · git dep ref · i18n 패리티 · locale 글꼴 · serverpod 버전 · coui pin(|| true 비차단) 등.

8. 재사용 판정 — 판정만(머지 · cherry-pick · 삭제하지 않음)

대상 · SHA main 대비 판정 근거 · 중복/충돌 · 4단계 채택 범위
main 20d1b5bf — 채택(빈 기준) README 1개. 워크플로 없음
PR #1 draft story/cocode-662-assembly c4e3d37e +17 커밋, 1,807 파일 부분 채택(출발점) 채택: 커널 bundle 골격 · 9 feature 번들 배치 · package/fitness_world(결정적 시드 · 업무 시계 · 접두사 저장소 · 트랜잭션, 테스트 19) · 직접 작성 CS/CB/MP app · console 의 규칙 · 페이지 · tool/assembly/(레시피 · plan · compose 매니페스트 7). 폐기/재작성: 깨진 Widgetbook use-case 26개 · 생성 서버 CRUD 서비스 · 자리 표시 BDD/빈 테스트. 공급 ref 정렬 필요(bricks 8f6a0440c → v1 fd4edb1e, 2커밋 26파일 차이 / kernel d36c5ccb → be421e0b, 1커밋 14파일) — 재생성보다 델타 적용이 작다. CI 5잡 실패(§6)
salvage/cocode-662-oyster-20261009-wip 6c76dc05 조립 브랜치 + 1 커밋, 214 파일(+2,492/−4,942) 부분 채택(방향만) IN · SA 를 FitnessWorld 기반 Local 저장소 · InstructorDisplayFields · StudioAlertLedger · AlertPreferencePort 로 옮기는 방향은 X3(세계 둘) 해소에 맞다. 그러나 테스트 38개 삭제 · 대체 없음, 삭제한 seedInstructorDemoWorld · seedStudioAlertDemoWorld 를 register_demo_world.dart 가 계속 참조(컴파일 오류 3 → 5), use-case 3개가 삭제된 타입 참조, DisplayFields 미등록, server/client 미변경. 통째 머지 금지 — 4단계 W4-04 에서 파일 단위로 다시 작성하며 참고

9. 레시피 · cob plan · cleanbase

9.1 레시피

9.2 cob plan (v1 cob + W1 브랜치 입력)

PUB_CACHE=$HOME/orca/toolchains/637/pub-cache cob plan --prd booking_fitness_prd.md \
  --proposals <co-bricks@5c030ed9>/docs/cocode-637/w1-proposals/booking_fitness.yaml \
  --recipes-dir <co-bricks@5c030ed9>/recipes --no-reuse [--emit emit.project.yaml --name demo_booking_fitness]
항목 결과
exit 0 (W1 cob 5c030ed9 로도 같은 출력)
FR 22개 전부 매핑 · orphan 0
결정론 covered(exact) 10 — FR-002 · 003 · 004 · 005 · 006 · 009 · 010 · 011 · 012 · 022
semantic review-pending 12 — FR-001 · 007 · 008 · 013 · 014 · 015 · 016 · 017 · 018 · 019 · 020 · 021
NFR 12(리포트 전용)
capability 합성 0 / hand-author 14(demo_shell · class_session · class_booking · membership_pass · console_fitness_bookings · pass_membership(🆕 reward_card) · instructor · studio_alert · alert_preference · console_booking_time_slots · console_fitness_passes · console_fitness_rules · demo_world · screen_state_preview) — 레시피 feature 까지 hand-author 로 표시되는 것은 co-bricks#858
--emit TODO(review) 8개(semantic 8 capability)

cob plan --entities(레시피 엔티티 11개, co_faker d23a5c42) — exit 65: instructor.specialty · instructor.career unsupported(c003ca2c 에서 fitness.instructorSpecialty · instructorCareer 로 해소 — 소스 확인). 역할 오추론: class_session.capacity → city, membership_pass.totalSessions · instructor.totalClassCount → price, pass_line.unitPrice → clinic.procedurePrice → co-package#99(schema.dart 부분 문자열 순서, c003ca2c 에도 존재).

9.3 cleanbase quick

python3 ~/orca/toolchains/637/xhost/scripts/pr1142-f97734cb/demo_cleanbase_repro.py \
  --recipe booking_fitness --checks quick --out booking_fitness-quick.json
항목 값
입력 cob 55ce5e14 · bricks fd4edb1e · coui coui_flutter-v0.158.0 · Serverpod 4.0.3 · Flutter 3.47.6 · project S2-A1 embedded
단계 flutter-version 0 · cob-version 0 · clone-bricks 0 · resolve-bricks 0 · archive-bricks 0 · demo-spec 65(❌ 레시피가 없습니다: booking_fitness)
결과 status: failed · 36.7 s · 다이제스트 없음 · 파일 수 없음 · 작업 디렉터리 정리됨
W1 cob 교차 확인 공용 ~/orca/toolchains/637/pub-cache 를 바꾸지 않으려고 격리 PUB_CACHE 에 5c030ed9 cob 을 따로 설치 → cob demo --recipe booking_fitness --layout bundle --spec-only = ❌ 검증되지 않은 레시피는 초고속 데모로 조립하지 않습니다 exit 65
판정 BLOCKED — blocker: W1 레시피 미스탬프(스탬프는 cleanbase 뒤에 붙고, 스크립트는 스탬프된 레시피만 받는 닭-달걀) · issue: coco-de/cocode#1148 · co-bricks#830 · #831 · next: PC-A 가 W1 레시피 PR + bundle cleanbase CI 스탬프, 또는 스크립트에 --recipes-dir/--demo-spec 입력 추가 후 재실행

10. baseline v1 upgrade 계획 — 실행하지 않음(계획만)

공급 조립 브랜치 현재 v1 목표 범위 · 영향
co-package d23a5c42(co_faker 0.11.1 · co_demo_world 0.1.0 · co_demo_prefs 1.0.1 · co_bdd 0.2.0 · co_golden 0.3.0 · co_golden_gallery 0.2.2) — pubspec 15개 + pubspec.lock, 22 파일 28곳 c003ca2c(co_faker 0.13.0 · co_demo_world 0.2.0) S-9 한 PR 일괄. 번역: fitness 팩 11개 언어 native → 데이터 언어 전환 가능, specialty · career 지원. 투영: 이름 목록이 바뀌면 투어 pin(find_pins.dart)을 다시 찾아야 한다(§3 B-12). 골든: 표시 데이터가 바뀌므로 Linux capture 재생성
coui 루트 coui_flutter-v0.158.0 / coui_core-v0.157.0(6b7f7b80) = v1 그대로 tool/golden/gallery/pubspec.yaml override 만 86930350(0.147/0.148) → 6b7f7b80 로 정렬(S-9)
bricks / kernel 8f6a0440c / d36c5ccb fd4edb1e / be421e0b 커널 재포장(testScaleInvariant 하네스 · BDD 경로 인자 · surfaces 공개 스모크 게이트) + 템플릿 컴파일 · 번역 수정(bricks#508). 델타 적용 후 generation-lock.json 갱신
Serverpod · Flutter 4.0.3 · 3.47.6 같음 POC #659 는 4.0.4 로 어긋났음 — 이 앱은 tool/serverpod/serverpod.yaml 4.0.3 유지, 상향은 baseline 결정
cob 조립 당시 0.6.0(55ce5e14 이전 해석) 55ce5e14 전용 PUB_CACHE 레시피는 W1 브랜치

v2 반영 예정(판정은 v1 기준): coui 새 릴리스 — 컴포넌트 chrome 11개 언어(coui PR #5354), 앱 전역 선택 영역 수정(PR #5355 — coui#5268 · #5348 · #5361), 차트(coui#5360 · #5362 — 이 앱 화면에는 차트 없음). co-package 78911c1a(co_demo_world 언어 중립 폴백 native 분류 수정 · grocery 5 SKU, co-package#96) — L-2 지원 표 분류에 영향.

상향 순서(4단계, 6단계 승인 뒤): ① bricks/kernel 델타 → ② co-package 일괄 + lock → ③ gallery coui 정렬 → ④ pin 재탐색 · 투영 등록 → ⑤ 골든 Linux update → ⑥ CI 녹색.

11. blocker · issue · next

13게이트 전체 PASS 로 판정하지 않는다. 사이드카(docs/demo-evidence/662.json)는 없다.

# blocker / 게이트 issue / 소유 next
B-1 레시피 v1 미포함 · verified 스탬프 없음 / recipe · generation co-bricks W1 브랜치 5c030ed9(PR 없음) · co-bricks#830 · #831 · #764 → #766 → #773 사슬 / PC-A W1 레시피 PR · bundle cleanbase CI 스탬프
B-2 cleanbase 스크립트가 미스탬프 레시피를 못 받음 / generation coco-de/cocode#1148(이번에 생성) / PC-A --recipes-dir · --demo-spec · 캐시 경로 인자 → 재실행해 다이제스트 기록
B-3 콘솔 workflow_runtime 컬렉션 · reservation release 확장 미생성 / fr(C-01~C-06) co-bricks#859 · PRD R1 · Q1(#638) / PC-A 그 전까지 콘솔 6화면 hand-author 유지, 표시
B-4 🆕 reward_card v3 shape 미지원 · 다건 카드(Q2) / fr #638 F-3 / PC-A(브릭) · PC-C(UI) A-05 hand-author 유지, F-3 머지 시 승격
B-5 생성기 결함 — transition_* 전이 미저장 · get_my_<여러 단어> · 교차 엔티티 usecase · plan hand-author 표시 co-bricks#855 · #856(get_my_membership_pass · get_my_alert_preference) · #857 · #858 · #860 T-10(--demo 없음) / PC-A 재생성 시 손 보정 범위를 docs/fullstack-feature-layout.md 에 기록
B-6 co_faker 역할 오추론(capacity → city · total* → price) / recipe 계획 정확도 · L-2 co-package#99(이번에 생성) / PC-B(co_faker writer) schema.dart 토큰 매칭 수정 · 태그 → baseline
B-7 목데이터 11개 언어 · instructor 필드 / locale co-package#57 · #71 · #78(CLOSED, c003ca2c 에 포함) / PC-A baseline 반영 완료, 앱 상향 미실행 §10 ② 상향(6단계 승인 뒤)
B-8 선택 영역 크래시(접근성 · 테마 · 딥링크) / patrol · smoke coui#5268 · #5348 · #5361 · 수정 PR coui#5355(미머지) / PC-C v2 반영 전 enableWebTextSelection:false 우회 여부 결정(POC #657 선례)
B-9 coui 컴포넌트 chrome 비-ko 영어 / locale coui PR #5354(미머지) · coui#5084 / PC-C 고정 예외로 기록, v2 반영
B-10 coui Icon Iconify 런타임 요청 / smoke(외부 요청 0) coui#5149 · #5190 / PC-C 이 앱은 LucideIcons 만 — 공개 스모크로 0 재확인
B-11 실행 앱 Patrol 러너 / patrol 러너 없음(인프라) / PC-A BLOCKED 기록, 러너 확보 시 실행
B-12 투어 페르소나 이름 불일치(PRD 윤하린 · 문가람 · 한채운 vs co_faker pin 윤하은 · 문가은 · 한채은) / fr(FR-001 AC1 · 투어) 결정 필요 — co_faker ko 이름 추가(co-package, PC-B) 또는 PRD 정정(cocode#662, PC-A) 코디네이터 결정 후 4단계 W4-10
B-13 Mobbin MCP 미인증 / Mobbin 부속 증거 · AC-15 접근 불가 / — BLOCKED — PRD §13 의 기존 링크(11 + shape 근거)만 인용, 새 링크 · 캡처를 지어내지 않음
B-14 조립 브랜치 컴파일 · CI 실패(X1 · X2 · 패리티 98 · use-case 21 · 골든 기준 없음) / unit~golden 이 저장소 결함 / PC-B 4단계 W4-02

공통 결함 처리는 change-requests §2 를 따른다: 증상 · 재현 · 실제 출력 · 기대 · 영향 PRD · 막힌 게이트를 소유자 이슈에 남기고(B-2 · B-6 은 이번에 생성), 소유자 PR → 릴리스 → PC-A baseline 승인 → 데모 일괄 상향. Actions 예산 소진은 이번 조사에서 관찰되지 않았다(PR #1 실패는 모두 코드 원인).

12. 4단계 작업 분해(6단계 승인 뒤 · 순서 · 크기)

크기: S ≤ 2 SP · M 3~5 SP · L ≥ 8 SP. 공급 ref 상향 · 저장소 설정 변경은 6단계 승인 뒤에만 한다.

# 작업 크기 종료 조건(증거) 의존 · 위험
W4-00 출발점: main 에서 새 story 브랜치, PR #1 의 채택 범위(§8)를 가져옴. salvage 는 참고만 S 브랜치 · 출처 커밋 기록 PR #1 처분은 PC-A
W4-01 공급 정렬(§10 ①~③): bricks/kernel 델타 · co-package c003ca2c · gallery coui · generation-lock.json M check_git_dep_refs.py · check_coui_pin.py 녹색, 재생성 diff 0 6단계 승인 · Serverpod 4.0.3 유지(4.0.4 표류 금지)
W4-02 컴파일 · CI 복구: seed 함수, FitnessWorld · FitnessSession · 포트 앱/콘솔 DI 등록, Widgetbook use-case 를 실제 Page/Cubit 으로 재작성(18 Page × 4상태), 11개 언어 i18n 패리티 M CI 계약 게이트 · 모듈 codegen · Android · 사이트 빌드 녹색 i18n 은 slang 자동 번역 초안
W4-03 앱 셸(FR-001 · 020 · 021): 하단 5탭 · 역할 전환 · localOnly 배너 · 초기화(빈 데이터 포함) · 상태 미리보기 · 서버 없음 M widget 테스트 + screen_states.feature
W4-04 세계 통합(X3): IN · SA · AP · BR 를 FitnessWorld 로(salvage 방향, 테스트 유지), FR-007 AC2 · FR-011 · FR-012 · FR-018 M 해당 AC widget/unit 단언 생성 테스트 38개를 지우지 않고 이관
W4-05 규칙 표 단위 테스트(NFR-003 · L-4): BookingRules · PassRules · ClassBookingService · ledger — 정원 · 잔여 · 순번 · 4h 경계 · 1h 마감 · 노쇼 · 홀딩 · 멱등 · revision · 차감 정합성, 언어 전환 전후 A 불변 M unit 녹색, 투어 9단계 수치(4→3→2 · 7/8 · 2/10) 단언 대기 만료 · 수강권 만료 시스템 전이(시계 스윕) 추가
W4-06 widget 테스트: 18 화면 × AC + 4상태, R-2/R-3 폭, 접근성 시맨틱(NFR-005) L widget 녹색 입력 값 덧붙음(POC 하네스 함정 — enterText 전 기존 값 지우기) · 선택 영역 크래시(B-8)
W4-07 BDD 7편(co_bdd widget-only) + Patrol 시나리오 작성 M co_bdd 잡 녹색 · Patrol 은 러너 없으면 BLOCKED(B-11)
W4-08 골든: 폰 · 태블릿 가로 · 데스크톱 주간 그리드 × 라이트/다크 × ko · en · zh-Hans · ja · ar + 긴 문구, testScaleInvariant(A-01 · A-02 · A-05 · C-04) M Linux 골든 (update) → 골든 (compare) 같은 SHA 녹색 macOS 기준 PNG 금지 · 글꼴 외부 요청 0
W4-09 backend FB-1~FB-4: 서버 모델(owner · FK · revision · requestKey · enum) · feature migration · 서비스(FSM · 불변식 · scope · 소유 격리 · 트랜잭션) · 규칙 공유 패키지 · SDK Repository · requires DAG · docs/fullstack-feature-layout.md · 통합 테스트(성공 · 타인 거부 · 불법 전이 · 입력 오류 · 동시성/revision · 차감 정합성) L verify / tests-server 격리 DB 녹색, runtime_mode: server 생성기 B-5 손 보정 · migration history 수동 편집 금지
W4-09c 서버 모드 데모 계정 매핑(2026-10-13 추가 — 「실제 로그인 흐름 DEFERRED」 해소, 코디네이터 결정 A): 호스트 소유 demoSignIn(명시 플래그 · production 거부 · 시드 계정만 · 짧은 TTL) · 서버 모드 앱/콘솔 역할 버튼 · 계약 동등성 역할 전환 단계 M 생성 SDK 통합(플래그 없음/production 403 · 시드 밖 거부 · TTL) · 서버 모드 widget · 계약 동등성 녹색 W4-09b · login-flow-decision.md §5
W4-10 언어(L-1~L-6): docs/locale-data.md(§3 확정) · DisplayFields 등록(회원 · 강사 · 수업 · 상품 · 혜택) · 메시지 템플릿 · DemoLocaleSupport 실측 표 · 실시간 전환 · ?lang=ar&theme=dark 첫 프레임 · 페르소나 이름(B-12) M unit/widget/golden/BDD 언어 항목 + 브라우저 실측 W4-01 · coui chrome(B-9) 예외
W4-11 브랜드(F-9): docs/brand.md · 브랜드 팔레트 · 간격/반경 토큰 · WCAG AA 표 · Widgetbook 테마 S raw 색 0 grep CI · 대비 표 · 골든 라이트/다크
W4-12 Pages 6표면 + 공개 스모크 + 자격 증명 스캔 2겹 M / /app/ /console/ /widgetbook/ /golden/ /docs/ 응답 · 업무 요청 0 · 콘솔 오류 0 Actions 예산 소진 시 인프라 BLOCKED(재실행 · 워크플로 수정 금지) · 선택 영역 크래시(B-8)
W4-13 Mobbin docs/mobbin-references.md — 화면당 2링크 S — BLOCKED(B-13), PRD §13 기존 링크만
W4-14 cleanbase full · verified · 사이드카 M 다이제스트 · 재생성 diff 0 · 스탬프 BLOCKED(B-1 · B-2)

권장 순서: W4-00 → 01 → 02 → (03 · 04 병행) → 05 → 09 → 06 → 07 → 08 → 10 → 11 → 12 → (13 · 14 는 blocker 해소 시). 합계 대략 55~65 SP — PRD §18 의 34 SP 는 FB · L 범위를 포함하지 않는다(§18 번들 블록).

부록 A. 이 문서의 근거 명령