새벽들녘 — 풀스택 기능 번들 배치 (FB-1)

# 새벽들녘 — 풀스택 기능 번들 배치 (FB-1)

> coco-de/cocode#659 · Project #637. 커널 + 기능 번들(`feature/<d>/{app,console,server,client}`)로
> 새로 조립하고 업무를 이식한 기록이다. **1단계**는 21개 화면 · localOnly 업무 · 상태 4종 · 상태 미리보기 ·
> BDD · 골든 · Pages 다면 배포, **2단계(FB-3 · FB-4)**는 기능 소유 서버 모듈 7개 · 호스트 바인딩 · 생성 SDK
> 통합 테스트 · 앱 서버 모드 저장소 · 계약 동등성 · main 증거 CI 다(§13 · §14). 남은 것은 §10.

## 1. 원칙

- 한 업무 컬렉션(서버 테이블)은 한 기능만 쓴다. 다른 기능의 데이터가 필요한 업무는 **호출자가 포트를
  소유**하고, 호스트가 실행 인스턴스마다 공급 구현을 바인딩한다(§5). 바인딩이 없으면 그 자리에서
  `StateError` 로 실패한다(fail-closed).
- 기능은 다른 기능의 Route · Page · Cubit 을 import 하지 않는다. 화면 사이 이동도 호출 기능이 소유한
  이동 계약을 호스트(`app_router`)가 실제 라우트로 바인딩한다.
- localOnly 공용 세계(`package/grocery_world`)는 **A 업무 데이터 저장소**일 뿐 업무 규칙을 갖지 않는다.
  규칙(최소 주문 · 마감 · 상태 전이 · 대체 정책)은 소유 기능의 localOnly 저장소에 있다.

## 2. 공급 ref (실제 사용)

| 공급 | ref | 비고 |
|---|---|---|
| co-bricks(cob) | main `1f27867578f8de761a8debdcac35b1f2c32f7aeb` · cob 0.6.0 | 읽기 전용 클론에서 `dart run bin/cob.dart` |
| bricks | main `bd8571753da1c82bc75f1ceeb3afff759ad21092` | `--bricks-dir <클론>/bricks` |
| 커널 | `7e1a9c19004430eb4fa19ef94d8d246474ac16a8`(bricks 스냅샷) | kernel main `f4bfa774` 가 **아니다** — `generation-lock.json` |
| coui | `coui_flutter-v0.159.2`(= `1b3838db`) · `coui_core-v0.158.1`(= `e48a3568`) | baseline v2 최종(#5372 아이콘 글꼴 제외 — 시각 변화 0; 후보 1 = `e48a3568`, v1.1 = `c3eac02f`) |
| co-package | `5b479112d5f4c017572b304656239983d9cfae92`(main — 릴리스 태그 없음) | co_faker 0.13.0 · co_demo_world 0.2.0 · co_demo_prefs 1.0.1 · co_golden 0.3.0 · co_bdd 0.2.0 — **S-9 단일 ref**(baseline v2 최종: co_faker #103 · co_bdd #104 HarnessFonts; 후보 1 = `a66629f6`) |
| Serverpod | 초기 배치 당시4.0.4; S4 현재4.0.3(고정 `tool/serverpod/cli`) | 승인 baseline v1 정렬은 `docs/design/s4-w4-02-baseline-v1.md`; 전역 CLI는 쓰지 않는다 |
| Flutter | 3.47.6(fvm) | |

## 3. 조립 명령 · 소요 시간

`cob` 는 저장소를 만들거나 바꾸지 않게 돌렸다(`--no-create-repo`, `--github-*` 미사용, `gh` 는 읽기 전용
`gh api` 만 통과시키는 감시 래퍼 — 기록 4건 모두 coui 태그 조회 GET).

| 단계 | 명령 | 결과 | 시간 |
|---|---|---|---|
| 데모 스펙 | `cob demo --recipe ecommerce_grocery --name demo_ecommerce_grocery --layout bundle --spec-only` | 0 | 9.7s |
| 데모 dry-run | 같은 명령 `--dry-run --bricks-dir <bricks>` | 0 | 9.2s |
| 데모 실조립 | 같은 명령(`--spec-only`/`--dry-run` 없이) | **78 BLOCKED** — "bundle에는 exact-input 공급 profile이 필요합니다. tool/demo_verify.dart prove/compare로 검증하세요" (co-bricks#830) | 9.2s |
| 커널 생성 | `cob create --layout bundle --no-interactive -n demo_ecommerce_grocery --bricks-dir <bricks>/bricks --organization <org> --org-tld <tld> --no-create-repo --no-auto-start --no-save-config` | 0 | 17.0s |
| 기능 7개 | `cob compose --layout bundle -m <feature>.yaml -d <project> -b <bricks>/bricks --no-interactive` × 7 | 0 | 93.4s(11.2 ~ 18.9s) |
| 의존성 | `flutter pub get` | 0 | 4.6s |
| 환경 파일 | `bash tool/dev/write_env.sh` | 0 | 17.9s |
| 번들 검사 | `python3 tool/feature_modules.py check` | 0 | 0.3s |
| 모듈 → 호스트 생성 | `python3 tool/feature_modules.py generate` | 0 | 178.3s |
| Flutter 생성 | `python3 tool/feature_modules.py flutter-codegen` | 0 | 37.2s |
| 게이트 | `bash tool/gates/check_all.sh` | 0 | 4.6s |

조립 합계 약 349s(5.8분). 조립 직후 `dart analyze` 는 1,206건(경고 224 — 전부 `undefined_hidden_name`,
정보 982)이었다(§12).

## 4. 기능 소유권

| 기능 | 역할(패키지) | 화면 | localOnly 컬렉션 | 서버 테이블 / endpoint(SDK `client.modules.<기능>.*`) | 공급 업무(다른 기능의 포트에 바인딩) |
|---|---|---|---|---|---|
| grocery_product | app · console · server · client | A-01 홈 · A-02 카테고리 · A-03 그리드 · A-04 상세 · A-05 옵션 · A-06 장바구니 · C-03 상품 · 재고 | products · categories · options · cart | grocery_product(revision) · produce_category · product_option · cart_line · grocery_product_sequence / `groceryCatalog`(공개) · `groceryCart` · `groceryStock` | `GroceryCatalogLedger` · 서버 `GroceryCatalogSupply` — 장바구니 사본 · 비우기 · 재고 검사 · 차감 · 대체 후보 · 대체 |
| delivery_slot | app · console · server · client | A-07 배송 시간 · C-04 권역 · 슬롯 | slots · holds | delivery_slot · slot_hold(orderCode 유일) / `deliverySlot`(공개) · `deliverySlotAdmin` | `DeliverySlotLedger` · `DeliverySlotSupply` — 슬롯 사본 · 예약 가능 검사 · 정원 점유(주문당 1회, 슬롯 행 잠금) |
| grocery_order | app · console · server · client | A-08 주문서 · A-09 내 주문 · A-10 추적 · C-01 보드 · C-02 피킹 · C-05 출고 현황 · C-06 주문 품목 | orders · order_lines · events · picks · requests | grocery_order · grocery_order_line · grocery_order_event · pick_line · grocery_order_request(owner+requestKey 유일) · grocery_order_sequence / `groceryOrder` · `groceryFulfillment` | 호출자 — 포트 5종 소유(§5). 공급: 주문 수 · 배송완료 품목(`GroceryOrderLedger` · `GroceryOrderSupply`) |
| delivery_subscription | app · server · client | A-11 정기배송 | subscriptions | delivery_subscription(owner 유일) / `deliverySubscription` | — (기준시각만 호스트 바인딩) |
| grocery_review | app · server · client | A-12 후기 목록 · A-13 후기 쓰기 | reviews | grocery_review(lineCode 유일) / `groceryReview` | 호출자 — 배송완료 품목 포트(`ReviewOrderPort`) 소유 |
| shopper | app · server · client | A-14 내 정보 | shoppers | shopper_profile / `shopper` | `ShopperLedger` · `ShopperSupply` — 배송지 코드. 호출자 — 주문 수 포트 소유 |
| grocery_alert | app · server · client | A-15 알림함 | alerts | grocery_alert · grocery_alert_sequence / `groceryAlert` | `GroceryAlertLedger` · `GroceryAlertSupply` — 알림 기록 |

호스트 쪽(기능이 모르는 패키지):

| 패키지 | 계층 | 소유 |
|---|---|---|
| `package/grocery_world` | 4 · shared | 공용 세계 스냅샷 · `WorldTx` · 결정적 시드(A) · `GroceryDisplay`(B) · `GrocerySession` 계약 · accounts 컬렉션 |
| `package/grocery_host` | 6 | 포트 어댑터 5종 · `GroceryHostPorts.app()/console()` · `HostGrocerySession` · `registerGroceryWorld` · `GroceryDemoBanner` |
| `feature/app_router/app` | 6 | `GroceryAppShell`(하단 탭 · 레일 · 배지 · 배너) · 이동 계약 바인딩 |
| `feature/console_router/console` | 6 | `GroceryConsoleShell`(좌측 · 하단 내비 · 역할 전환) |
| `app/app` · `app/console` | 7 | 부트스트랩 순서: 번들 아이콘 → 세계 · 세션 · 포트 → 모듈 → 이동 계약 |

## 5. 교차 기능 업무 — 호출자 소유 계약

| 업무 | 호출자(소유) | 포트 | 공급 | 앱 바인딩 | 콘솔 바인딩 |
|---|---|---|---|---|---|
| 주문 생성 = 장바구니 사본 + 비우기 | grocery_order | `OrderCartPort` | grocery_product | `CatalogCartPort` | 없음(fail-closed) |
| 주문 · 결제 전 재고 검사, 모의 결제 재고 차감 | grocery_order | `OrderCatalogPort` | grocery_product | `CatalogStockPort` | `CatalogStockPort` |
| 슬롯 사본 · 예약 가능 · 결제 시 정원 점유 | grocery_order | `OrderSlotPort` | delivery_slot | `DeliverySlotOrderPort` | `DeliverySlotOrderPort` |
| 배송지 검증 | grocery_order | `OrderShopperPort` | shopper | `ShopperAddressPort` | 없음 |
| 대체 · 출고 알림 | grocery_order | `OrderAlertPort` | grocery_alert | 없음 | `GroceryAlertOrderPort` |
| 장바구니 → 배송 시간 | grocery_product | `GroceryProductNavigation` | delivery_slot 라우트 | `AppGroceryProductNavigation` | — |
| 배송 시간 → 주문서 | delivery_slot | `DeliverySlotNavigation` | grocery_order 라우트 | `AppDeliverySlotNavigation` | — |
| 내 정보 주문 수 | shopper | `ShopperOrderPort` | grocery_order | `OrderCountShopperPort` | — |
| 후기 쓸 수 있는 품목(배송완료 · 환불 제외) | grocery_review | `ReviewOrderPort` | grocery_order | `DeliveredReviewPort` | — |

- 포트는 호출자의 같은 `WorldTx` 로 돈다 — 결제(주문 전이 + 정원 점유 + 재고 차감)는 한 번에 커밋되거나
  모두 버려진다. 공급 거절(`CatalogRejection` · `SlotRejection`)은 어댑터가 `OrderPortRejection`
  (`stock` · `slot` · `substitute` · `missing`)으로 바꾸고, 주문 저장소가 자기 실패 코드로 바꾼다.
- 서버(FB-3)는 같은 계약을 `<Feature>HostBindings.bind(serverpod, …)` 로 서버 인스턴스마다 묶고
  `forSession(session)` 으로 같은 Session/Transaction 을 넘긴다(호스트 `bindGroceryHost` — 어댑터 7종 ·
  기준시각). 바인딩 누락은 `StateError` → HTTP 500(fail-closed), 빈 결과로 꾸미지 않는다(§13).
- 실제 원장에 묶은 투어 통합 테스트: `package/grocery_host/test/src/grocery_tour_test.dart`.

## 6. 신원 · 역할 · scope

- 정체성 값은 `identity.yaml` 의 지정 파일에만 둔다(Identity-Free 게이트).
- 서버 신원 도메인은 **업무 주체**(데모 계정 id — `host-integration.json` 의 `identityDomain`)다. 기능 모듈 7개는
  `session.authenticated` 를 직접 읽지 않고 HostBindings 의 `caller` 포트(`<Feature>Caller =
  ({String? principal, Set<String> scopes})`)로 묻는다. 호스트 운영 resolver(`GroceryCallerResolver`)는 JWT 의
  AuthUser(UUID)를 신원 매핑(`grocery_accounts` — authUserId · principal 유일)으로 주체로 바꾸고, scope 는 인증
  정보 중 이 데모의 업무 scope 만 남긴다. 주체가 없으면(매핑 없음) 모든 업무가 `forbidden`, 바인딩이 없으면
  `StateError`(500). `groceryAccount.me()` 는 같은 포트의 값을 돌려준다 — 앱 · 콘솔 server 모드 게이트의 행위자다.
  통합 · 계약 시험 서버는 시험 토큰(`demo:<계정>`)의 식별자를 그대로 주체로 쓰는 resolver 를 묶는다.
- localOnly 의 행위자는 세계의 `accounts`(호스트 소유)에서 읽고, 셸이 `HostGrocerySession` 으로 고른다.
  앱은 구매자 고정, 콘솔은 배너에서 역할을 바꾼다. 저장소는 **모든 쓰기에서** scope · 소유자를 다시 검사한다
  (화면의 버튼 숨김은 편의일 뿐이다).

| 데모 계정 | 역할 | scope |
|---|---|---|
| `shopper-ohaneul` 오하늘(데모) | 구매자 | `grocery.checkout` · `grocery.cancel` · `grocery.review` · `grocery.subscription` |
| `manager-muntaeo` 문태오(데모) | 운영 매니저 | `grocery.orders` · `grocery.pick` · `grocery.pack` · `grocery.dispatch` · `grocery.slots` |
| `picker-hangyeol` 한결(데모) | 피커 | `grocery.orders` · `grocery.pick` |
| `md-seoyun` 서윤(데모) | 상품 MD | `grocery.catalog` |

| 전이 | 필요 scope | 앱 / 콘솔 |
|---|---|---|
| 결제대기 → 결제완료(모의 결제) | `grocery.checkout` | 앱 |
| 결제대기 · 결제완료 → 취소(모의 환불) | `grocery.cancel` | 앱(본인 주문만) |
| 결제완료 → 피킹중 | `grocery.pick` | 콘솔 |
| 피킹중 → 포장완료(모든 줄 종결) | `grocery.pack` | 콘솔 |
| 포장완료 → 배송중 → 배송완료 | `grocery.dispatch` | 콘솔 |

## 7. 공용 데모 세계(A 데이터)

- 스냅샷 하나를 브라우저 `localStorage` 의 `demo-ecommerce-grocery/world-v1` 에 둔다. 앱(`/app/`)과
  콘솔(`/console/`)은 서로 다른 웹 빌드지만 같은 출처라 같은 키를 쓴다(FR-023). 쓰기는 Web Locks
  (`navigator.locks`) 배타 구간에서 최신 스냅샷의 초안으로 하고, 던지면 아무것도 쓰지 않는다.
- 포커스 복귀 · `storage` · `visibilitychange` 때 다시 읽고, 실제로 바뀐 때만 신호를 낸다(읽기 신호 루프 없음).
- 「초기화」는 `demo-ecommerce-grocery/` 접두 키만 지우고 시드로 되돌린다 — 같은 출처의 다른 데모 저장소는
  건드리지 않는다.
- 시드: seed 436 · 기준시각 2026-01-15(UTC) · 상품 48 · 분류 21 · 옵션 54 · 장바구니 3줄(22,280원) ·
  슬롯 24 · 주문 18(`SB-20260113-0024` ~ `SB-20260115-0041`, 다음 번호 0042) · 이벤트 72 · 피킹 31 ·
  후기 30 · 알림 12.

## 8. B 표시 투영 · co_demo_world 이관 대상

`GroceryDisplay` 는 (seed, 기준시각, locale, 엔티티 키)의 결정적 함수로 이름 · 원산지 · 주소 · 메모를
투영한다(A 데이터에는 표시 문자열이 없다). 지금은 co_faker 0.11.1 의 ko · en 만 투영한다.

- 이관 대상: 분류 2차 이름 · 페르소나 이름(파일 안 하드코딩) → co-package `co_demo_world` 0.1.0 의
  `DisplayProjector` · `DisplayFieldSet` · 사용자 입력 overlay(C 데이터)로 옮기고 11개 언어(S-18)로 넓힌다.
- 알려진 품질 문제: co_faker 의 grocery 카탈로그가 분류 안에서 같은 이름을 반복해 상품 이름이 겹치고
  (예: 「시금치 200g」 7개), 보관 온도대와 이름이 어긋나는 상품이 있다(「냉동 고등어」 · 냉장). 투어 고정 상품
  10종은 파일 안 고정 이름이라 영향이 없다.
- co_faker 0.11.0 은 웹(dart2js)에서 `deriveSeed` 가 VM 과 다른 값을 내 웹 데모의 표시 값이 골든 · 테스트와
  달랐다(co-package #69). d23a5c42(0.11.1)로 올린 뒤 웹 빌드도 VM 과 같은 주소를 보인다.

## 9. 21개 화면

| ID | 화면 | 기능 · 역할 | localOnly | 서버 모드(SDK) |
|---|---|---|---|---|
| A-01 | 홈 피드 | grocery_product · app | ✅ | ✅ |
| A-02 | 2단 카테고리 | grocery_product · app | ✅ | ✅ |
| A-03 | 상품 그리드 | grocery_product · app | ✅ | ✅ |
| A-04 | 상품 상세 | grocery_product · app | ✅ | ✅ |
| A-05 | 옵션 · 수량 시트 | grocery_product · app | ✅ | ✅ |
| A-06 | 장바구니 | grocery_product · app | ✅ | ✅ |
| A-07 | 배송 시간 선택 | delivery_slot · app | ✅ | ✅ |
| A-08 | 주문서 | grocery_order · app | ✅ | ✅ |
| A-09 | 내 주문 | grocery_order · app | ✅ | ✅ |
| A-10 | 주문 추적 | grocery_order · app | ✅ | ✅ |
| A-11 | 정기배송 | delivery_subscription · app | ✅ | ✅ |
| A-12 | 후기 목록 | grocery_review · app | ✅ | ✅ |
| A-13 | 후기 쓰기 | grocery_review · app | ✅ | ✅ |
| A-14 | 내 정보 | shopper · app | ✅ | ✅ |
| A-15 | 알림함 | grocery_alert · app | ✅ | ✅ |
| C-01 | 주문 처리 보드 | grocery_order · console | ✅ | ✅ |
| C-02 | 피킹 리스트 | grocery_order · console | ✅ | ✅ |
| C-03 | 상품 · 재고 | grocery_product · console | ✅ | ✅ |
| C-04 | 권역 · 배송 슬롯 | delivery_slot · console | ✅ | ✅ |
| C-05 | 오늘 출고 현황 | grocery_order · console | ✅ | ✅ |
| C-06 | 주문 품목 | grocery_order · console | ✅ | ✅ |

## 10. 남은 단계

| 항목 | 상태 | 사유 · 다음 |
|---|---|---|
| S-18 — 11개 언어 UI · `co_demo_prefs`(첫 값 `?lang=&theme=` · 포털 iframe 실시간 전환 · pre-boot) · `co_demo_world` 11개 언어 투영(§8) | BLOCKED | 지금 ko · en 2개. co_demo_world(#70) 투영 · 커널 F-7(co_demo_prefs · 공개 스모크 live 판정)을 들인 뒤 증거 대장 `locale` 게이트를 `공개 스모크` 에 묶는다 |
| Patrol 실기기 여정 | BLOCKED | 기기 러너 없음 — 증거 대장 `patrol` |
| 서버 모드 로그인 흐름(데모 토큰 → 실제 인증 IdP) | DEFERRED | 서버 통합은 테스트 경계 토큰(`demo:<계정>`)으로 검증. Pages 는 localOnly 고정 |
| 시드 이벤트 진행 · 권역 선택 · compose 템플릿 출력 정리 | DEFERRED | 1단계 기록 그대로 |

## 11. 검증(1단계 — 조립 직후 기록)

| 항목 | 결과 |
|---|---|
| 게이트 `tool/gates/check_all.sh` | 통과(정체성 · 슬롯 · 번들 9 · 계층 래칫 0/0/0 · 한 파일 한 공개 타입 724 · git ref 26/0 · StatefulWidget 0) — 경고는 앱 링크 서명 자리표시자 2건 |
| 테스트 `TZ=UTC SKIP_SERVER=1 tool/dev/test_all.sh` | 21개 패키지 · 248 통과 · 골든 변형 388 skip(기본 skip 모드) |
| 서버 단위 `tool/feature_modules.py test-unit --modules-only` | 7개 기능 × 10 = 70 통과(템플릿 서버 코드) |
| 골든 캡처 `tool/golden/capture.sh` | 8개 패키지 · 384 변형 렌더 성공(macOS — 기준 이미지는 CI Linux 가 정본) |
| `dart analyze`(루트) | 오류 0 · 경고 43 · 정보 433 — 전부 compose 템플릿 출력(미이식 앱 역할 4 · 서버 역할 7 · 호스트 DI import 순서 3). 이식한 패키지는 0 |
| 웹 빌드(release · localOnly · 해시 URL · `--no-web-resources-cdn` · `--no-wasm-dry-run`) | 앱 30s · 콘솔 28s |
| 브라우저 투어(같은 출처로 앱 · 콘솔 동시 서빙) | 담기 → 장바구니 → 슬롯 → 주문 0042 → 모의 결제 → 콘솔 피킹 · 시금치 300g 대체 · 포장 · 출고 → 앱 추적에 대체 이벤트, 외부 요청 0 |

## 12. 도구 결함(upstream)

| # | 대상 | 재현 | 우회 |
|---|---|---|---|
| D1 | cob demo | `cob demo --recipe ecommerce_grocery --layout bundle --output-dir <d> --bricks-dir <b>` → exit 78 "exact-input 공급 profile 필요"(co-bricks#830) | create + compose 수동 조립 |
| D2 | cob demo | `--spec-only` 출력 스펙에 `project.demo` 가 없어 그대로 되먹일 수 없다 | 매니페스트 7개 손 작성 |
| D3 | cob create | `--organization <project_name>` 을 받아들이지만 serverpod 프로토콜이 project_name 을 품어 `check_identity.py` 가 실패 | 다른 organization 으로 재생성 |
| D4 | cob create/compose | create 는 bricks 저장소 루트를 받지만 compose 는 `<repo>/bricks` 만 받는다("필요한 브릭이 없습니다") | 둘 다 `<repo>/bricks` |
| D5 | cob create | 내부 `tool/dev/write_env.sh` 가 "Attempting to send request on closed client" 로 실패 | pub get 뒤 다시 실행 |
| D6 | compose 출력 | `undefined_hidden_name` 224 + 정보 982(상대 import · directives_ordering · flutter_style_todos …) — 커널 CI 는 `dart analyze --fatal-infos` | 이식한 기능만 0, 나머지는 기록 |
| D7 | compose 출력 | Flutter 3.47 `pub get` 이 기능 7개의 `analysis_options.yaml` 을 고쳐 쓴다(`build/**` exclude) | 바뀐 채 커밋 |
| D8 | compose | 7회 compose 뒤에도 `generation-lock.json` `features: []` | — |
| D9 | compose · 커널 | 기존 번들에 console 역할을 더할 수 없고 커널 `feature_modules.py generate` 도 console 대상을 거부 | console_grocery_order 손 작성 + bundle.json 갱신 |
| D10 | cob | `tool/feature_codegen.dart` 가 전역 `serverpod`(4.1.0-beta.1)를 불러 커널 고정 4.0.4 와 갈린다 | 커널 `tool/feature_modules.py` |
| D11 | 커널 | `DemoWorld` 는 메모리 전용이라 앱 ↔ 콘솔 공유(FR-023) 불가 | `package/grocery_world` |
| D12 | coui | 등록 안 된 `Icon` 을 그릴 때 Iconify API 를 런타임에 부른다(외부 요청) | Lucide 부분집합 번들 + 부트스트랩 · 골든 하네스 등록 |
| D13 | coui · Flutter | `CoUIApp` 웹 앱 전체 `SelectionArea` + 중첩 라우트 딥링크(예: `/app/#/grocery_order/checkout?slot=DS-0116-DAWN-A` 새로 열기) → 한 번도 배치되지 않은 아래 페이지 문단으로 `_compareScreenOrder` 가 "RenderBox was not laid out" 2건 | 미해결 — 화면은 정상 |
| D14 | coui | `NavigationBar` 항목 의미 레이블이 두 번("홈 홈") · 버튼 노드 2겹, Scaffold 헤더의 Button 이 스캐폴드 노드에 합쳐짐 | 배너를 `Semantics(container, explicitChildNodes)` 로 감쌈 |
| D15 | bricks | 커널 · compose 가 co_golden/co_bdd `v0.2.0`(0af1421)와 co_faker `v0.11.0`(e1492864)을 따로 고정(S-9 위반) | d23a5c42 로 수동 통일 |
| D16 | compose 출력 | 주석 오류(「소유: order_event_server」 · 배럴 「/// 커뮤니티」), 콘솔 부트스트랩에 ConfigurationErrorApp 처리 없음, DiRegistrar 가 import 를 정렬하지 않음(정보 3) | 기록 |
| D17 | 커널 | 콘솔 웹 `index.html` 에 favicon 링크가 없어 `/favicon.ico` 404 | 기록 |
| D18 | cob | 조립이 쓴 `tool/feature_codegen.dart` 가 `dart format` 형식이 아니라 커널 CI `검증 (generated)` 의 포맷 검사가 실패한다(생성기 출력이 아닌 도구 스크립트) | 포맷해 커밋 |
| D19 | 커널(조립 시점) | `app/app_widgetbook` 이 TranslationProvider · coui 테마 없이 `Widgetbook.material` 만 띄워 use-case 23개가 「Please wrap your app with TranslationProvider」로 그려지지 않았고, 기본 홈 이모지가 fonts.gstatic.com 에서 Noto Color Emoji 를 받았다 | `AppWidgetbook` · `WidgetbookHome`(커널 #30 과 같은 대처) + 모든 use-case 렌더 시험 |

## 13. 서버 (FB-3 · FB-4)

기능마다 `feature/<d>/server/lib/src/{model(+dto · enum · exception),rule,service,endpoint,bindings}` —
모델은 기능 소유 `.spy.yaml`, 생성물은 공식 CLI 로만 만든다(손대지 않는다).

| 기능 | 표 | endpoint(메서드) | 서비스 · 불변식 |
|---|---|---|---|
| grocery_product | 5 | 9 — `groceryCatalog`(공개 4) · `groceryCart` 3 · `groceryStock` 2 | 필수 옵션 · 같은 상품+옵션 합산 · 정수 금액 · 재고 revision 낙관적 동시성(같은 값은 no-op) · `grocery.catalog` |
| delivery_slot | 2 | 3 — `deliverySlot`(공개) · `deliverySlotAdmin` 2 | 마감 · 정원 · 주문당 점유 1회(orderCode 유일, 슬롯 행 FOR UPDATE) · `grocery.slots` |
| grocery_order | 6 | 12 — `groceryOrder` 7 · `groceryFulfillment` 5 | 상태 전이표(불법 전이 거절) · 멱등 키(owner+requestKey) · 결제 = 정원 점유 + 재고 차감 한 트랜잭션 · 대체 정책 · 이벤트 E-n · KST 주문번호 |
| delivery_subscription | 1 | 2 — `deliverySubscription` | 구매자당 1행 · 주기 1·2·4주 · 쉬는 중 건너뛰기 거절 · 쉬면 건너뛰기 해제 · 요일 변경은 KST 다음 날부터 첫 그 요일 · FOR UPDATE |
| grocery_review | 1 | 2 — `groceryReview` | 본인 후기 · 별점 1~5 · 메모 300자 · 번들 사진 키만 · 배송완료(환불 제외) 줄당 1개(lineCode 유일 + ON CONFLICT) |
| shopper | 1 | 2 — `shopper` | 본인 프로필 · 내 배송지 코드만 기본값 · 주문 수는 포트 |
| grocery_alert | 2 | 3 — `groceryAlert` | 본인 알림 · 읽음 멱등 · 시퀀스 AL-n |

- **바인딩(호출자 소유 포트)**: `GroceryOrderHostBindings`(장바구니 · 카탈로그 · 슬롯 · 배송지 · 알림 · 시계) ·
  `ShopperHostBindings`(주문 수) · `GroceryReviewHostBindings`(배송완료 품목 · 시계) ·
  `DeliverySlotHostBindings` · `GroceryAlertHostBindings` · `DeliverySubscriptionHostBindings`(시계).
  `Expando` 로 서버 인스턴스마다 따로 — 같은 프로세스의 세 인스턴스(바인딩 · 미바인딩 · 하루 뒤 시계)가 서로를 보지 않는다.
- **DB 정책**: 원래 baseline을 보존하고 변경은 공식 새 migration으로 append한다.
  통합 테스트는 실행마다 스키마 지문(FNV-1a) 이름의 격리 DB 를 만들고 지운다(다른 DB 는 만들거나 지우지 않는다).
  빈 DB에 전체 이력을 적용한 결과 = 모델 스냅샷(`grocery_schema_snapshot_test`). 기존 fixture DB의
  upgrade·원래 컬럼값 보존도 검증한다. S4 이력/실행 근거는 `docs/design/s4-w4-03-revision.md`와
  `docs/design/s4-w4-04-login.md`를 따른다.
- **생성**: `tool/serverpod/cli.sh generate` + `python3 tool/feature_modules.py flutter-codegen` → 작업 트리 변화 0
  (CI `검증 (generated)` · `번들 모듈 → 호스트 코드 생성`).

아래는 초기 backend 결합 당시 집계다. 현재 S4의 revision/login 및 재검증 집계는 위 설계 보고서를 따른다.

| 시험 | 수 | 무엇 |
|---|---|---|
| 기능 서버 단위(순수 규칙, TZ=UTC) | 30 | 옵션 · 슬롯 · 주문 규칙 · 정기배송 일정 · 후기 규칙 |
| 호스트 SDK 통합(생성 SDK → dispatcher → 모듈 → 격리 Postgres) | 54 | 권한 · 격리 · 불법 전이 · 불변식 · 동시성(정원 · 재고 · 후기 한 줄 · 정기배송 잃어버린 변경 없음) · 멱등 · 교차 기능 원자성 · 미바인딩 fail-closed · 인스턴스별 바인딩 · 스키마 스냅샷 |
| 계약 동등성(같은 시나리오 표 · 같은 시드) | 64단계 × 2 런타임 | localOnly 저장소 = SDK 저장소(엔티티 전체 · 실패 코드). localOnly 공급 원장의 불안정 정렬(32줄 초과 시 줄 순서 뒤집힘)을 이 시험이 잡아 고쳤다 |

앱 서버 모드 저장소는 생성 SDK 를 부르고 실패를 명시 코드로 바꾼다 — 서버 주소 없음 `serverMissing`, 연결 실패 ·
서버 오류 `serverUnavailable`, 401 · 403 `forbidden`, 모듈 업무 실패는 같은 이름의 코드. 이름 · 주소 · 시드 본문(B)은
`GroceryDisplaySource` 로 투영한다. Pages 는 localOnly 고정이다.

## 14. CI 증거 (main HEAD SHA)

증거 대장은 main HEAD 와 같은 SHA 의 run · 잡만 인정한다. main push 는 변경 범위 판정 없이 전부 돈다 —
게이트 ↔ 잡 이름 표는 `CLAUDE.md` 「CI 증거 게이트 ↔ 잡 이름」, 정본 `tool/ci/evidence_jobs.json`.
골든 기준은 명시 트리거(main 밖 브랜치의 `[update-goldens]` 커밋 · dispatch `update_goldens=true`)에서만 갱신한다.