공용 데모 세계 — 한달품 데모 (cocode#1276)

앱(/app/ — 데스크 태블릿 키오스크)과 콘솔(/console/)은 서로 다른 Flutter 웹 빌드지만 같은 출처다. 둘은 package/postpartum_world 의 PostpartumWorld 하나를 같은 브라우저 저장소 키로 읽고 쓴다 — 콘솔이 발급한 코드를 키오스크가 받고, 키오스크가 제출하면 콘솔에 새로고침 없이 뜬다. 값은 모두 가상이다.

이 문서는 설계 단계의 world-schema(W-1)를 옮긴 세계 계약이다. 기능 번들은 여기 적힌 컬렉션 · 필드만 읽고 쓰고, 숫자는 §5 의 집계 식으로만 센다.

0. 한눈에

1. 패키지

기능 저장소의 기본 모양 — 기능 번들(L5)은 postpartum_world 만 의존한다. postpartum_binding(L6)의 PostpartumRuntime 은 셸(console_router · app_router) · 호스트 전용이다(계층 래칫 — daycare 기능도 daycare_world 만 의존). 인스턴스는 서비스 로케이터로 받는다:

final locator = ServiceLocator.instance;          // package:core
if (!locator.isRegistered<PostpartumWorld>()) {   // 서버 모드 · 등록 전 — S-05(조용한 폴백 금지)
  return;
}
final world = locator.get<PostpartumWorld>();
final session = locator.get<PostpartumSession>();
final actor = session.actor;                      // 콘솔 로그인 행위자(로그인 전 null)
final scope = session.branchScope;                // 지점 범위(FR-02) — null = 전체(대표의 「전체」)
final rows = world.view.where(                    // 읽기 — 신호 0
  PostpartumCollections.reservations,
  (r) => scope == null || r.text('branchId') == scope,
);
await world.transact((tx) {                       // 쓰기 — 한 트랜잭션이 원자적
  final r = tx.get(PostpartumCollections.reservations, id);
  tx.update(PostpartumCollections.reservations, id, {
    'status': ReservationStatus.booked.name,
    'history': [...r.list('history'), {'at': PostpartumDates.instant(tx.now), 'status': 'booked', 'staffId': actor!.staffId}],
  });
});
// 화면은 mergeSignals([world.changes, session.changes]) 를 듣고 다시 읽는다(읽기는 신호 0 — 루프 없음).

교차 쓰기는 한 트랜잭션 안에서 한다(예: 퇴실 = reservations.status + stays.dischargedAt + rooms.status + aftercareCalls 생성). 다른 번들의 컬렉션을 쓸 때는 그 번들 시드 · 화면이 기대는 필드 이름을 바꾸지 않는다.

2. 신원 · 세션

세션은 탭의 메모리다(탭마다 따로 — 세계는 공유). 콘솔은 로그인 전, 앱은 기기 선택 전 상태로 시작한다.

콘솔 데모 계정(로그인 패널 순서)

행위자 PostpartumActor = accountId · staffId · role(PostpartumRole) · branchId · scope(postpartum.<역할>) · canAccessBranch · canSee(ConsoleMenu) · showsAmounts. 퇴사(staff.status = retired)한 직원의 계정은 패널에서 빠진다.

세션 인터페이스 PostpartumSession (기능 번들이 보는 것)

셸은 같은 동작을 PostpartumRuntime(signIn · signOut · selectDevice · beginPass · endPass · branchScope · selectBranch · reset)로 부른다 — 세션을 바꾸는 메서드는 세션에 위임한다.

키오스크 기기 · 코드 흐름 (BRIEF-contract §7)

1. 로그인 패널에서 기기 — PostpartumRuntime.selectDevice(deviceId).
2. K-01 이 4자리 코드를 받아 KioskPassCheck.byCode(view, code) → KioskPassCheck.verdict(pass, device:, now:) 로 이유를 가린다(없음 · 만료 · 제출됨 · 다른 기기/목적 · 다른 기기에서 작성 중).
3. 통과면 PostpartumRuntime.beginPass(passId)(셸) — 같은 판정을 트랜잭션 안에서 다시 하고 행을 inUse(inUseDeviceId · inUseAt)로 바꾼 뒤 세션에 싣는다.
4. 제출 = 한 트랜잭션(기능 컬렉션 쓰기 + kioskPasses status: submitted · submittedAt) → 세션의 endPass()(기능은 locator.get<PostpartumSession>().endPass() — 셸의 PostpartumRuntime.endPass() 와 같다) → /done. 목적별 화면은 session.passId 가 없으면 /code 로 돌려보낸다(world.pass(passId) 로 행을 읽는다).

만료는 저장 상태가 아니라 시각으로 판정한다(expiresAt 이 지났고 제출 전이면 만료). 데모 시계가 09:00 고정이라 08:5x 에 발급한 코드는 데모 내내 유효하다.

3. 컬렉션

필드 이름은 camelCase, 열거값은 postpartum_rules · postpartum_world 의 enum name 이다. 「더한 필드」는 world-schema 에 없던 것을 A1 이 시드 · 집계를 위해 더한 것이다(모두 선택 — 없으면 null).

customers.nameText · guardianNameText(선택 · C): 상담 등록 · 접수 연결이 새 고객을 만들 때 사람이 친 이름을 그대로 넣는다(시드에는 없다 — 시드 고객의 이름은 B). 화면은 이 필드를 직접 읽지 않고 B 와 같은 projector.text(PostpartumDisplayKeys.customerName(id)) 로 읽는다 — 바인딩이 overlay 로 맞춘다(§6).

코드 값: newborns.tests 키 = congenitalMetabolic · hearing · hepatitisB1 · vitaminK · transcutaneousJaundice(NewbornTest), assessment 키 = skinJaundice · genitals · fontanelle · hip · eyesMouth · primitiveReflex · umbilical · breathingCry (NewbornAssessmentArea). documents.kind = DocumentKind(consultForm · privacyRequired · marketingOptional · reservationConfirmation · admissionForm · infectionSafety · newbornAssessment · dischargeEducation · procedureConsent · refundForm · stayCertificate). 입실 서류의 동의 항목 키(documents.items) = admissionRules · privacy · healthInfo · infectionSafety(필수) · aesthetic · messaging(선택) — K-04 ConsentItem 이름과 같다. 세 enum 의 주인은 WP-STAY. staff.licenseKey = nurse · nurseAide · ibclc · esthetician. reservations.extras[].key 예: pumpFunnelSet. sessionBuckets.menuKey 예: postnatalBody60 · breastCare40 · swellingCare40. 결제 note = partialDuringStay (재실 중 지자체 지원 승인) · balanceAtAdmission(잔금을 입실일에 냈다).

4. 시드 (seed 1274 · 기준 2026-01-15 09:00 서울)

부품 목록 PostpartumWorldSeed._steps: seedOrganization → seedOccupancy → seedConsultations → seedKioskPasses → seedMonthlyLedgers(→ 기능 WP 의 단계: seedStay — 물결점 재실 체류가 입실 때 서명한 입실 서류 행 · 서명 이미지 · 산모 입력은 싣지 않는다). 빈 세계(reset(empty: true))에는 조직 · 기기 · 객실(모두 사용 가능)만 있다. VM 과 웹(dart2js)이 같은 seed 로 같은 바이트를 만든다(확인함). 크기는 약 1.14M 자.

4.1 숫자 (seed_facts_test 가 §5 의 식으로 단언)

괄호 값은 시험이 단언하지 않는 생성 결과다(기능 WP 가 기대지 말 것).

4.2 물결점 이름 있는 행 (Figma 와 같게)

• 강다솜(C-10): 디럭스 13박 · 당일 + 지인 · 보호자 식사 6식 · pumpFunnelSet 40,000 → 총액 4,900,000 · 계약금 500,000 (12/2 카드) · 잔금 결제 pay_dasom_balance = 지자체 1,000,000(승인 1/14) + 지역화폐 500,000(1/2 회 승인 08:55) + 지역화폐 500,000(2/2 대기) + 카드 2,400,000(대기) · 산후 서비스 1/2 사용.
• 민서윤(C-11): res_seoyun 디럭스 13박 · 총액 5,000,000 · 계약금 500,000(12/20 카드) · 입소 3/1 · 예약완료 · terminationRequestedAt = 1/15 08:40 · terminationRequestedBy = staff_counselor → 45일 전 · 31~60일 행 · 150,000. refunds 행은 정산 WP 가 같은 시각으로 만든다.
• 상담(C-03 — Figma 열 그대로): 자가 입력 접수함의 한예나 · 차하람은 상담 카드가 아니다 — intakes 는 상담 WP 가 시드한다(제출된 키오스크 코드 1594 · 8826, §4.3). 차하람은 재방문 고객이라 cust_haram customers 행(재방문 1)만 있고, 한예나는 고객 행도 없다. 진행 중 카드 — 1차 cust_haneul 이하늘(3/18 · VIP 13박 · 맘 커뮤니티 · 다음 연락 1/16) · cust_chaeeun 문채은(3/27 · 디럭스 13박 · 병원 추천 · 1/17) · cust_serin 오세린(4/8 · 디럭스 20박 · 블로그 · 1/19) + 생성 4 / 2차 cust_gaeul 윤가을(3/4 · VIP 20박 · 지인 소개 · 1/16 · 방문 예약) · cust_haedam 장해담(3/11 · 디럭스 9박 · 산모 교실 · 1/18) + 생성 4 / 3차 cust_sia 백시아(2/26 · VIP 13박 · SNS · 다음 연락 오늘 · 견적 발송) · cust_haon 류하온(3/2 · 디럭스 13박 · 지역 카페 · 1/16) + 생성 3. 3차 둘은 아직 계약 전이라 예약 · 회차 버킷이 없다. 예약 열(이번 주) — cust_yunseul 홍윤슬(2/20 · VIP 13박 · 가계약: 예약 hold 1/14 16:00 · 계약금 기한 1/16) · cust_saebyeok 진새벽(2/14 · 디럭스 13박 · 예약완료: 계약금 1/12 14:00 승인 · 예약확인서 발송). 예약 단계가 된 때가 1/12(월) 이후 · 09:00 전인 물결 상담은 이 둘뿐이다. 보류 · 이탈은 생성 카드 2장(12월 시작 — 화면 열 밖). 이하늘의 예약 행은 없다 — 투어 4(C-05)가 1차 카드를 예약으로 옮긴다(희망 입실일 wishAdmissionOn 3/20).
• 사후(C-15) 대상 퇴실: cust_nayun 권나윤(VIP 705 · 1/12) · cust_seojin 안서진(디럭스 307 · 1/8) · cust_haeun 도하은(디럭스 302 · 12/16) · cust_onyu 최온유(VIP 702 · 1/10) — 해피콜 행은 메시지 WP.
• 회차(C-09): 고은비 산후 2회 중 0회 사용(투어 8 이 2 → 1) · 하윤서 산후 1/2 사용 · 조은결 코스 10회 1회 사용(1/6 2,500,000) · 노하나 코스 5회 2회 사용(1/9 1,000,000) · 표다인 오늘 08:45 코스 5회 구매(1,280,000 · 0회 사용) · 진새벽 산전 2회 중 0회 사용(bkt_saebyeok_prenatal · 입실일 2/16 에 소멸 — C-09 14:00 산전 관리의 회차, §8).

id 규칙: 고객 cust_<꼬리> → 예약 res_<꼬리> · 체류 stay_<꼬리> · 신생아 baby_<꼬리>(쌍둥이 _2) · 상담 cons_<꼬리> · 결제 pay_<꼬리>_<deposit|balance|course|support> · 버킷 bkt_<꼬리>_<prenatal|postnatal|course>. 생성 레코드는 cust_<지점>_<nnn>(상담만 있는 고객은 cust_<지점>_c<nn>), 직원 staff_<지점>_<nn>. PostpartumTourIds 가 모든 이름 있는 id 와 파생 함수를 가진다.

4.3 키오스크 코드 (데모 방문자가 앱에서 넣는다)

4.4 생성 규칙 (숫자를 맞추는 방법)

• 객실 타임라인: 입실일 + 박 수 = 퇴실일, 퇴실 다음 날 소독, 그다음 날부터 다음 입실. 오늘 · 내일 입실할 방은 그제까지 비운다. 과거 체류는 객실마다 거꾸로 채운다(물결 12/14 · 솔빛 · 노을 12/24 까지).
• 1월 입실은 표에 적은 것만: 물결 당월입실 15 = 이름 있는 재실 11 + 생성 재실 3(313 · 316 · 322) + 오늘 아침 퇴실한 308. 그래서 나머지 재실은 12월에 입실한 3 · 4주 계약이다.
• 매출 맞추기: 1월 매출이 목표보다 많으면 12월 입실 · 1월 퇴실 고객의 잔금을 입실일 결제로 옮기고(balanceAtAdmission), 모자라면 재실 고객의 지자체 지원 승인 줄(partialDuringStay)을 더한다 — 마지막 줄이 원 단위까지 맞춘다.
• 상담 열: 예약에 딸린 상담은 모두 booked(가계약 포함)이고, 예약 단계 이력 시각은 계약 시각(없으면 가계약 시각)이다. 생성 1월 계약(물결 11)은 1/21/11 에 흩는다 — 이번 주(1/12)에 예약 단계가 된 상담은 C-03 예약 열의 두 장뿐이다.
• 크기: 퇴실한 체류의 신생아 · 체크인 단계는 두지 않는다. 생성 예약의 history 는 비어 있다(계약 · 입실 · 퇴실 시각 필드가 같은 정보). 회차 버킷은 재실 · 2월 말까지 입실 예정 · 이름 있는 예약만.

4.5 마감 월 장부 (monthlyLedgers — 솔빛 / 물결 / 노을)

예약: 8월 24/22/19 · 9월 26/21/20 · 10월 25/23/18 · 11월 27/24/21 · 12월 23/22/19. 해지 · 상담 · 전환 · 입실 · 매출 칸은 가상 값이다(seed_monthly_ledgers.dart). 이번 달(1월)은 장부가 아니라 행에서 센다.

4.6 케어 차트 (seed_care.dart — WP-CARE)

물결점 재실자만 시드한다. 솔빛 · 노을은 행이 없다(그 지점의 차트 계정이 없다 — 그 지점 숫자는 「재실 전원 미기록」이 된다). 기준시각 뒤의 「일어난 일」은 넣지 않는다 — 오늘(1/15)은 오전 바이탈 · 07:00 뒤 첫 칸 · D 근무조 점검(꼬물이 · 하윤서 아기)까지.

합계 ≈ 99,500 자(스냅샷 전체 1,242,127 자 — 척추 + 케어 차트만 올린 때). id 규칙은 CareChartIds: 바이탈 mv_<체류 꼬리>_<YYYYMMDD>_<am|pm>, 칸 nbe_<아기 꼬리>_<YYYYMMDDHHmm>, 점검 nsc_<아기 꼬리>_<YYYYMMDD>_<D|E|N>, 체중 nbw_<아기 꼬리>_<YYYYMMDD>, 직원 일지 note_<일련번호>(시드 일지는 note_<고객 꼬리>_<n>). 한 칸 · 회차 · 근무조 · 하루에 행이 하나라 저장은 같은 id 를 덮어쓴다 — 체크인 ④(WP-STAY)의 첫 바이탈도 같은 id 로 쓴다.

차트 하루 · 근무조(CareChartDay · CareShift): 차트 날짜는 서울 07:00 ~ 다음 날 07:00(칸은 정시 · 반시 48개), 근무조 D 07–15 · E 15–23 · N 23–07(N 은 시작한 차트 날짜에 속한다). 바이탈 회차는 13시 전 오전 · 뒤 오후. 체중은 15:00(목욕) 기준 — 그 전이면 어제가 「마지막 측정일」이다.

숫자(물결 · 09:00 — seed_care_test 가 CareChartFacts 로 단언)

홈(C-01) · 사이드바 배지가 위 숫자를 쓰려면 CareChartFacts 를 부른다(식 정의는 이 표 하나).

5. 집계 식 (PostpartumFacts)

기준 순간 at(없으면 세계의 지금 — 09:00), 「오늘」 = at 의 서울 날짜, 「이번 달」 = [월초 0시, at](끝 포함 — 데모 중 쓰기는 모두 09:00 에 찍힌다). branchId 가 null 이면 전체 지점. 비율은 반올림 정수(87.5 → 88).

환불은 refunds 행으로만 매출에서 뺀다 — 원결제 줄을 refunded 로 바꿔도 그 줄은 승인 당시의 매출로 남는다(이중 차감 금지). 정산 WP 는 지급(모의) 때 paidAt(과 가능하면 branchId)을 refunds 행에 적는다.

6. 표시(B) 데이터

PostpartumDisplayFields.of(() => world.view) 를 두 호스트의 표시 필드 목록(demoDisplayFields · consoleDemoDisplayFields)이 싣는다 — 같은 설정(PostpartumWorldSpec.config)이라 같은 사람이 앱 · 콘솔 어디서나 같은 이름이다. 화면은 DisplayProjector.text(PostpartumDisplayKeys.…) 로만 읽는다.

사람이 친 이름(C): 고객 행에 nameText · guardianNameText 가 있으면 postpartum_binding 이 부팅 때와 world.changes 때(이 탭의 쓰기 · 다른 탭의 갱신) DisplayProjector.overlay 의 customerName(id) · guardianName(id) 로 맞춘다. 그래서 예약 · 재실 · 정산 등 다른 화면은 고칠 것 없이 projector.text(customerName(id)) 로 친 이름을 본다.

• 필드를 지우거나 비우면 overlay 키도 지워져 B(생성 이름)로 돌아간다. 초기화는 시드로 되돌리므로 친 이름도 사라진다.
• 언어를 바꿔도 그대로다 — overlay 는 언어와 무관하다(친 이름은 번역하지 않는다).
• 동기화는 자기가 넣은 키만 지운다. 기능은 이름을 overlay 에 직접 넣지 말고 고객 행에 쓴다 — 그래야 다른 탭 · 새로고침 · 초기화가 따라온다.
• 호스트(앱 · 콘솔)는 DisplayProjector 를 registerPostpartumDemo 보다 먼저 등록한다.

메모 예문 · 병원 틀 · 고정 이름의 글자는 번들 글꼴(Pretendard ∪ LocaleFallback)이 덮는다 — postpartum_display_glyph_test.dart 가 지킨다(글꼴 게이트는 slang 카탈로그 · co_faker 만 본다).

7. 시드 더하기 (기능 WP)

1. 자기 컬렉션 상수는 이미 PostpartumCollections 에 있다(새 컬렉션이면 상수 + all 에 한 줄).
2. package/postpartum_world/lib/src/seed/seed_<도메인>.dart 에 void seed<Domain>(PostpartumSeedBuilder builder) 를 쓴다.
   • 업무 행은 if (builder.empty) return; 뒤에.
   • 난수는 builder.faker('<도메인>/<키>') 로만(단계마다 독립 스트림 — 다른 단계 값을 밀지 않는다).
   • 시각은 builder.at(월, 일, 시, 분)(서울 → UTC 문자열), 날짜는 builder.date(월, 일). 기준시각(09:00) 이후의 「일어난 일」을 넣지 않는다 — 앞으로의 일정(예약된 마사지 10:00 등)은 된다.
   • 척추 행은 builder.rowsOf(collection) · builder.find(collection, id) 로 읽고, id 는 PostpartumTourIds 로 만든다.
   • 한국어 문자열을 넣지 않는다(이름 · 병원 · 메모는 B 키 — 시드 시험이 한글을 막는다). null 필드는 빌더가 뺀다.
3. PostpartumWorldSeed._steps 의 🔧 줄 아래에 한 줄을 더하고 schema 를 올린다(옛 저장본은 버려진다).
4. 시험: 자기 화면 숫자를 단언하는 시험을 더하고, seed_facts_test · postpartum_world_seed_test(참조 무결성 · 객실 겹침 · 기준시각 · 한글 · 크기)가 그대로 통과해야 한다. 척추 행을 더해도 이미 단언된 숫자를 깨지 않는다.
5. 크기: 스냅샷 전체 2,000,000 자 안(척추 ≈ 1.14M 자 — 기능 WP 합계 ≈ 0.85M 자). 같은 출처 localStorage 를 앱 · 콘솔이 함께 쓰고 브라우저 한도가 약 5MB(UTF-16)다. 격자 기록(신생아 24시간 등)은 이름 있는 재실자 · 최근 며칠만.

8. Figma 와 다른 값

9. 같은 출처의 다른 데모와 겹치지 않기

docs.cocode.im/<저장소>/ 의 다른 데모는 자기 접두사를 쓴다. 이 세계의 초기화는 demo-healthcare-postpartum/v1/ 로 시작하는 키만 지운다(시험: 「접두사 밖의 키는 읽지도 쓰지도 지우지도 않는다」). 포털과 공유하는 언어 · 테마 값 (co_demo_prefs)은 이 세계의 저장 키가 아니다.