송금 데모 — 기능 번들 소유권 · 조립 기록 (FB-1)
정본: PRD coco-de/cocode#657 §6 · §8 · §9 · §11 · FB-1FB-5 · L-1L-6,
cocode docs/fullstack-feature-layout.md(v2) · docs/fullstack-bundle-poc/adr-v2.md(AD-1~AD-11).
이 문서는 업무 소유권의 선언이다. 이름이 같다는 이유로 업무를 합치지 않고, 큰 공용 묶음을 두지 않는다.
1. 번들과 역할
번들 feature/<d>/ |
역할(패키지) | 비고 |
|---|---|---|
recipient |
app_common(recipient_common) · app(recipient) · console(console_recipient) · server(recipient_server) · client(recipient_client) |
앱 · 콘솔이 같은 수취인 도메인을 쓰므로 공용 도메인은 app_common 한정 슬롯(AD-1 보강 · D-098) |
remittance_quote |
app(remittance_quote) · server · client |
견적 계산(NFR-013)의 소유자 |
remittance |
app_common(remittance_common) · app(remittance) · console(console_remittance) · server · client |
송금 상태머신 · 심사 큐 · 심사 메모 |
supporting_document |
app · server · client |
추가서류(모의 첨부) |
remit_notice |
app · server · client |
알림함 |
remit_preference |
app · server · client |
송금 설정 |
remit_flag |
console(console_remit_flag) · server · client |
고액 · 반복 플래그(콘솔 전용) |
remit_settlement |
console(console_remit_settlement) · server · client |
정산 라인(콘솔 전용) |
remit_limit |
console(console_remit_limit) · server · client |
데모 한도 정책(콘솔 전용) |
app_router · console_router |
커널 라우터 번들 | 최상위 라우트 목록(커널 제공) |
호스트: backend/demo_exchange_remittance_server(실행 · 조립 · 인증 · 통합 테스트) ·
backend/demo_exchange_remittance_client(합성 SDK) · app/app · app/console · app/app_widgetbook(셸) ·
app/remit_world(호스트 조립 패키지 — localOnly 데모 세계의 시드 순서 · 계약 바인딩 · 데모 세션 · 체험 시계.
업무 규칙을 담지 않는다. 앱 · 콘솔 두 셸이 같은 조립을 쓰도록 app/* 호스트 계층에 둔다).
2. 소유권 표 — 레시피 feature · workflow 컬렉션 → 번들
| PRD 입력 | 소유 번들 | 단일 소유 테이블(서버 table:) · localOnly 컬렉션 |
endpoint/service(서버) | 화면 |
|---|---|---|---|---|
레시피 recipient · workflow remit_recipients |
recipient |
remit_recipient |
RecipientEndpoint(송금인 · 콘솔 대장 — scope 로 가른다) · RecipientService |
A-02 · A-03 · A-04 · C-05 |
레시피 remittance_quote(remittance_quote · quote_line) |
remittance_quote |
remit_quote(발급 기록 — 라인은 금액의 결정적 투영이라 저장하지 않는다) |
RemittanceQuoteEndpoint · RemittanceQuoteService |
A-05 |
레시피 remittance · workflow remit_transfers(approval) · remit_milestones · remit_review_notes |
remittance |
remit_transfer · remit_milestone · remit_review_note (limit_check 는 DTO — 아래 주) |
RemittanceEndpoint(송금인 · 심사역 · 정산 담당 · 운영 관리자 — 전이 주체는 서비스가 scope 로 다시 검사) · RemittanceService |
A-01 · A-06 · A-07 · A-08 · A-09 · A-10 · C-01 · C-03 |
레시피 supporting_document · workflow remit_documents |
supporting_document |
remit_document |
SupportingDocumentEndpoint · SupportingDocumentService |
A-11 |
레시피 remit_notice |
remit_notice |
remit_notice |
RemitNoticeEndpoint · RemitNoticeService(게시는 송금 후처리 트랜잭션) |
A-12 |
레시피 remit_preference |
remit_preference |
remit_preference |
RemitPreferenceEndpoint · RemitPreferenceService |
A-13 |
fast 팩 exchange_reports(재사용 표기) |
remit_flag |
remit_flag |
RemitFlagConsoleEndpoint · RemitFlagService |
C-02 |
fast 팩 exchange_invoices의 정산 라인 쓰임 |
remit_settlement |
remit_settlement_line |
RemitSettlementConsoleEndpoint · RemitSettlementService(도착 반영은 송금 후처리 트랜잭션) |
C-04 |
fast 팩 exchange_invoices의 견적 초안 쓰임 |
remittance_quote |
(위 quote_line) |
— | A-05 |
workflow remit_limit_rules |
remit_limit |
remit_limit_rule |
RemitLimitConsoleEndpoint · RemitLimitService |
C-06 (A-07 판정 입력) |
fast 팩 exchange_offers · exchange_orders |
채택 안 함 | — | — | P2P 매물 · 매칭 전이는 송금 심사와 다른 업무(PRD §9(b)) |
- 이름으로 합치지 않은 것: PRD 는
exchange_invoices하나를 「견적 초안」과 「일별 정산 라인」에 함께 재사용한다고 적었다. 두 쓰임은 다른 업무(송금인 견적 vs 정산 담당 집계)이므로 테이블을 나눠 각 소유자에 둔다(quote_line·settlement_line). limit_check는 레시피 엔티티라 compose 가 테이블로 만들었지만 실제로는 계산 결과(규칙 × 송금 × 서류)다 — 2단계에서 테이블을 두지 않고 DTO(RemitLimitCheck)로 바꿨다.- 레시피 필드
appliedRate: double·receiveAmount: double은 2단계에서 minor-unit int + 유리수 환율 (rateNumerator/rateDenominator)로 바꿨다(NFR-013 — 받는 금액은 내림, 정밀도 상한을 곱하기 전에 검사). - 테이블 · 필드 이름은 localOnly 레코드 codec 과 같다(
id→<entity>Id). 호스트는remit_account(AuthUser ↔ 송금 소유자 id)만 소유한다.
3. 교차 기능 계약 — 호출 쪽이 소유, 호스트가 바인딩, 미바인딩은 실패
| 계약(소유: 호출 쪽) | 공급 | 쓰임 | 클라이언트(localOnly) | 서버(2단계) |
|---|---|---|---|---|
TransferQuotePort (remittance) |
remittance_quote | 견적 → 송금 생성: 견적이 있고 · 내 것이고 · 만료 전이며 수취인이 같을 때만 submitted 생성 |
app/remit_world 어댑터가 견적 저장소에 바인딩 |
RemittanceHostBindings.bind(serverpod, …) · forSession(session) |
TransferRecipientPort (remittance) |
recipient | 송금의 수취인 소유 · 국가 확인 | 같은 방식 | 같은 방식 |
TransferDocumentPort (remittance) |
supporting_document | 서류가 재심사를 연다: on_hold → under_review 는 서류 ≥ 1 |
같은 방식 | 같은 Session/Transaction |
TransferNoticePort (remittance) |
remit_notice | 심사 결정 → 알림: 보류 · 도착 전이가 알림 1건(사유는 심사역 입력) | 같은 방식 | 같은 Transaction |
TransferSettlementPort (remittance) |
remit_settlement | 도착 → 정산 라인 수량 +1(같은 일자 · 파트너 · 국가 · 단가) | 같은 방식 | 같은 Transaction |
TransferLimitPort (remittance) |
remit_limit | 한도 · 증빙 체크(A-07)의 데모 규칙 | 같은 방식 | 같은 방식 |
RecipientTransferStatsPort (recipient) |
remittance | 프로필 Stat(송금 건수 · 누적 금액) | 같은 방식 | 같은 방식 |
QuoteRecipientPort (remittance_quote) |
recipient | 견적의 수취 국가 → 통화 · 환율 | 같은 방식 | 같은 방식 |
*ActorPort (각 기능) |
호스트 인증 | 현재 행위자(소유자 id · scope) | 데모 세션(역할 전환) | <Feature>HostBindings.caller ← session.authenticated + remit_account |
- 기능 패키지끼리는 서로 import 하지 않는다(
requires: []). 계약 타입은 소비 기능의domain/port/에 있고, 구현 어댑터는 호스트(app/remit_world)만 둔다. 등록되지 않은 계약은ServiceLocator조회에서 즉시 실패한다(fail-closed) — 성공 · 빈 값 · 다른 모드로 흉내 내지 않는다. - 서버 쪽은 같은 계약을 서버 모듈이 소유하고 호스트(
RemitHostPorts.bindTo(pod))가 인스턴스별로 바인딩한다(AD-2) —<Feature>HostBindings.bind(serverpod, …)·forSession(session)(Expando), 미바인딩은StateError(fail-closed). 쓰기 쪽 계약(알림 · 정산)과 게이트 입력(서류 수)은 호출자의Transaction을 받는다(아래 §9).
4. 식별자 도메인 · scope
- 식별자 도메인:
AuthenticationInfo.userIdentifier(compose 가host-integration.json.identityDomain에 기록). localOnly 는 데모 세션의 소유자 id(sender·new-sender· 콘솔 대장의customer-<n>)를 같은 자리로 쓴다. - scope:
remit.customer(송금인 — 자기 수취인 · 송금 · 서류 · 알림 · 설정),remit.review(심사역 — 검토 시작 · 승인 · 반려 · 보류 · 플래그 해소),remit.ops(정산 담당 — 송금 · 도착 · 정산 라인),remit.admin(운영 관리자 — 전 scope + 한도 정책). - 전이 주체(FR-021): 송금인은
submitted→canceled·on_hold→under_review(서류 ≥ 1) ·on_hold→canceled만, 심사역은 검토 · 결정, 정산 담당은approved→sent→delivered만. 화면 버튼 숨김과 별개로 저장소가 다시 검사한다.
5. 데이터 종류 (#1065 · L-1 — 상세 표는 3단계 docs/locale-data.md)
- A 업무: id · 참조번호 · 소유자 · 국가 코드 · 통화 · 금액(minor int) · 환율(유리수) · 상태 · 시각 · 수량 · 규칙 수치 → localOnly 컬렉션에 저장, 언어와 무관.
- B 표시: 시드 수취인 이름(영문 이니셜 마스킹) · 가상 은행명 · 파트너 이름 · 이벤트 알림 문장 →
co_demo_world의DisplayProjector(<entity>.<field>· entity id 키). 기능이 생성기(<feature>DisplayFields)를 소유하고 호스트가 하나로 합친다. - C 입력: 송금인이 등록한 수취인 이름 · 은행명 · 메모, 심사역이 쓴 사유 → 저장소 필드로 저장하고 투영보다 우선한다.
- enum/code(상태 · 목적 · 수령 방법 · 서류 종류 · 규칙)는 A 이고 라벨은 기능 소유 번역(slang)이 맡는다.
6. 조립 기록 (2026-10-09)
공급 ref — co-bricks main 1f27867578f8de761a8debdcac35b1f2c32f7aeb(미릴리스, dart run bin/cob.dart) · bricks main
bd8571753da1c82bc75f1ceeb3afff759ad21092 · kernel main f4bfa774d8aae17a8b696c2f4fd8dc4892685fcc(cob kernel package 로 직접 포장,
dirty=false — bricks 의 커널 스냅샷 7e1a9c19 대신) · coui coui_flutter-v0.158.0=coui_core-v0.157.0(6b7f7b80) ·
serverpod 4.0.3(커널 핀 · ADR AD-9 — 조립 때 --serverpod stable 이 pub.dev 최신 4.0.4 로 해석한 것을
python3 tool/serverpod/profile.py apply stable --version 4.0.3 로 되돌렸다. 4.0.3 과 4.0.4 의 serverpod generate 출력은
같다 — 재생성 diff 0, 바뀐 것은 pubspec · lock 뿐) · co-package d23a5c42
(co_demo_world 0.1.0 · co_faker 0.11.1 · co_demo_prefs 1.0.1 · co_bdd 0.2.0 · co_golden 0.3.0 · co_golden_gallery 0.2.2).
| 단계 | 명령 | 결과 | 시간(초) |
|---|---|---|---|
| 스펙만 | cob demo --recipe exchange_remittance --name demo_exchange_remittance --layout bundle --spec-only |
exit 0 | 11.0 (cold) · 10.7 (warm) |
| 드라이런 | 같은 명령 --dry-run |
exit 0 · 포트폴리오 13화면 | 10.1 · 10.5 |
| 실조립 | 같은 명령(--spec-only 없이) | exit 78 BLOCKED — bundle에는 exact-input 공급 profile이 필요합니다 (co-bricks#830) |
10.7 |
| 커널 포장 | cob kernel package --kernel kernel@f4bfa774 --out …/core/kernel |
428 파일 | 18.9 |
| 생성 | cob create-from-config(layout bundle · demo · app_link_domain) |
커널 scaffold · coui 최신 · serverpod stable | 21.3 |
| 매니페스트 | cob generate --spec <demo spec> --print-effective |
레시피 6기능 | 10.0 |
| compose ×9 | cob compose --layout bundle -m <feature>.yaml |
9 번들 · 약 2,000 파일 | 42.5(첫) · 11~17(나머지) |
| pub get | flutter pub get |
성공 | 5.3 |
| 서버 codegen | tool/serverpod/cli.sh generate (모듈 9 → 호스트) |
성공 | 213.8(CLI 준비 포함) |
| Flutter codegen | tool/feature_modules flutter-codegen (slang + build_runner --workspace) |
성공 · 98 산출물 | 41.3 |
| 분석 | dart analyze |
2224건(error 13 · warning 463 · info 1748) — 전부 생성 골격 | 12.8 |
cob create 대신 cob create-from-config 를 쓴 이유: 둘 다 같은 CreateProjectService 로 generate --base kernel --layout bundle 을 부르지만,
create 는 demo(compose 가 데모 저장소 · 시드 슬롯을 쓰는 조건)와 app_link_domain 을 받지 않는다. create-from-config 는 GitHub 저장소를
만드는 경로가 없다(소스 확인). 콘솔 역할 · 콘솔 전용 번들 3종 · 심사 메모 모델은 이 문서의 소유권 표에 맞춰 매니페스트에 더했다.
6.1 이식 뒤 검증 (1단계 끝, 같은 기계 · heavy.sh 경유)
| 검사 | 명령 | 결과 | 시간(초) |
|---|---|---|---|
| Flutter codegen(깨끗한 재생성) | rm -rf .dart_tool/build && tool/feature_modules flutter-codegen |
PASS · 46 산출물(생성물은 포맷하지 않는다) | 59.3 |
| Flutter codegen(증분) | 같은 명령 | PASS · 6 산출물 | 39.7 |
| 분석 | dart analyze |
479건(error 0 · warning 37 · info 442) — 전부 아직 이식 전 생성 골격: recipient/console 165 · remit_flag/console 98 · remit_preference/app 86 · 서버 골격 9개 130(T-3 · T-4). 이식 · 작성 코드 0건 |
8.8 |
| 계약 게이트 | tool/gates/check_*.py 15종 · feature_modules.py check |
PASS(11 번들 · 한 파일 한 공개 타입 649 · 계층 위반 0 · StatefulWidget 0 · git ref 42 단일). 경고: assetlinks.json 서명 자리표시자 |
— |
| 포맷 | CI 와 같은 dart format --set-exit-if-changed(생성물 제외) |
FAIL 1 — tool/feature_codegen.dart(compose 출력, T-15). 작성 코드 0 |
1.6 |
| 테스트(서버 제외) | SKIP_SERVER=1 TZ=UTC tool/dev/test_all.sh |
PASS · 26 패키지 · 263 통과(생성 골격 골든 147 skip) — 뒤이은 수정으로 console_remittance +1 = 264 |
111.0 |
| 모듈 서버 단위 | TZ=UTC python3 tool/feature_modules.py test-unit --modules-only |
PASS · 9 패키지 × 10 | 24.1 |
| 호스트 서버 통합 | ONLY_SERVER=1 tool/dev/test_all.sh · test-host |
DEFERRED — 내장 Postgres · 고정 포트, 서버 업무는 FB-3 | — |
| 웹 빌드(앱) | flutter build web --release --no-wasm-dry-run --dart-define=COB_RUNTIME_MODE=localOnly --dart-define=WEB_URL_STRATEGY=hash |
PASS · main.dart.js 3.8 MB | 28.3 · 27.2 |
| 웹 빌드(콘솔) | 같은 명령(app/console) |
PASS · main.dart.js 3.5 MB | 27.9 · 26.5 |
| 웹 스모크 | 위 빌드를 로컬 정적 서버(25701 · 25703)에 띄우고 격리된 headless Chrome(--user-data-dir 따로 · 공유 브라우저 MCP 아님)으로 콘솔 #/remittance?status=under_review&reference=NR-260114-0019 · #/console · 앱 / 열기 |
PASS — 심사 큐 · 상세 패널 · 송금 홈(32% · 진행중 1 · 보류 1) 렌더, RenderBox was not laid out 0건(수정 전 화면마다 1건 → 7d37650) |
— |
이식 · 작성 코드의 테스트: remittance_quote 22(NFR-013 정수 계산 · 넘침 사전 검사 · 위조 견적 거부) · recipient_common 12 ·
remittance_common 26(상태머신 · 전이 주체 · 서류 게이트 · 알림 · 정산 부수효과) · recipient 5 · remittance 5(4단계 검증 · 이중 제출) ·
console_remittance 6(scope 별 버튼 · 실패 사유 · 모르는 참조번호) · 공급 기능 4종 18 · remit_world 6(시드 결정성 · 체험 시계 · fail-closed 등록) ·
호스트 여정 app/app 11(받는 사람 → 견적 → 4단계 → NR-260115-0042 → 한도 4/4 → 추적 09:12) · app/console 2(심사역 승인 →
정산 담당 송금 · 도착 → 알림 · 정산 라인 +1, 보류 사유 필수) · 커널 라우터 테스트 갱신(앱 25 · 콘솔 3).
6.2 1단계 잔여(A) 뒤 검증 (2026-10-09)
| 검사 | 명령 | 결과 |
|---|---|---|
| 분석 | dart analyze --fatal-infos |
PASS — 0건(이식 전 479건: 생성 골격 화면 3종은 이식 코드로 바꾸고, 서버 골격 9개 모듈은 lint 만 맞춤) |
| 계약 게이트 | tool/gates/check_all.sh |
PASS — 한 파일 한 공개 타입 691 · StatefulWidget 0 · raw 스타일 0(697 파일, 새 게이트) · 계층 위반 0 |
| 포맷 | CI 와 같은 검사(생성물 · T-15 adapter 파일 제외) | PASS — 0 changed |
| 테스트(서버 제외) | SKIP_SERVER=1 TZ=UTC tool/dev/test_all.sh |
PASS — 26 패키지 · 246 통과(커널 골든 24 skip) |
| 모듈 서버 단위 | TZ=UTC python3 tool/feature_modules.py test-unit --modules-only |
PASS — 9 패키지 |
| 웹 빌드 | flutter build web --release --no-wasm-dry-run(localOnly · hash) |
PASS — 앱 24.6초 · 콘솔 24.7초 |
| 깊은 링크 스모크 | 격리 headless Chrome + CDP Runtime.exceptionThrown, 화면 12개(앱 6 · 콘솔 6) |
PASS — 예외 0(T-16 adapter 뒤 · 2026-10-11 adapter 제거 · coui_flutter-v0.159.0 에서 다시 예외 0) |
7. 도구 · 템플릿 결함 (upstream 대상 — 데모마다 우회를 복제하지 않는다)
| # | 결함 | 재현 | 영향 |
|---|---|---|---|
| T-1 | backend 템플릿의 endpoint/endpoint.dart 가 endpoint: false 여도 <d>_endpoint.dart 를 export |
콘솔 전용 매니페스트(backend: {endpoint: false, console_endpoint: true}) compose → analyze |
uri_does_not_exist 3건(remit_flag · remit_limit · remit_settlement) |
| T-2 | checklist shape 페이지가 coui 0.158 에 없는 Checkbox(state:) · CoreCheckboxState 사용 |
limit_checklist bloc 이 있는 매니페스트 compose → analyze |
error 10건(앱 · 콘솔) |
| T-3 | bundle 레이아웃에서 core 가 모듈 모델을 재수출하지 않는데 생성 파일이 hide <Entity> 를 둠 |
아무 번들 compose → analyze | undefined_hidden_name 462건 |
| T-4 | 생성 Dart 의 상대 import · 지시문 순서 · TODO 형식 · 불필요 import 등 lint | compose → analyze | info 1748건 |
| T-5 | compose 가 co-package 의존을 서로 다른 태그로 핀(co_faker-v0.11.0 · co_bdd-v0.2.0 · co_golden-v0.2.0 · co_golden_gallery-v0.2.0) | compose 후 pubspec | S-9(형제 패키지 같은 커밋) 위반 → 손으로 d23a5c42 일원화 |
| T-6 | compose 가 쓰는 tool/feature_codegen.dart 가 전역 serverpod CLI(이 기계 4.1.0-beta.1)를 기본으로 부름 — 커널의 고정 CLI(tool/serverpod/cli.sh, 4.0.4)와 이중 진입점 |
compose 출력의 「다음 단계」 안내 | 버전 불일치 codegen 위험 |
| T-7 | typed 라우트가 :id(int) 를 정적 형제(wizard 등)보다 먼저 둠 + 참조번호(String)를 int 로 받음 |
remittance 라우트 생성물 | /remittance/wizard 가 :id 로 잡혀 int 파싱 실패 |
| T-8 | feature 배럴 라이브러리 주석이 다른 기능 라벨(/// 커뮤니티) |
recipient 배럴 | 문서 오류 |
| T-9 | 커널 콘솔 셸의 localOnly DemoWorld 에 시드 슬롯이 없고 compose 의 시드 등록도 application 만 |
콘솔 역할 compose(--demo) | 콘솔 데모가 빈 세계로 뜸 — 호스트가 조립해야 함 |
| T-10 | cob create 에 --demo · --app-link-domain 이 없음(SavedProjectConfig 는 지원) |
cob create --help |
create-from-config 로 우회 |
| T-11 | cob demo --layout bundle 의 공급 profile 을 만들 수 없음 |
위 실조립 | BLOCKED(co-bricks#830) |
| T-12 | Flutter 3.47 pub get 이 생성 패키지 analysis_options.yaml 에 build/** 제외를 덧붙임(커널 패키지는 이미 가짐) |
첫 pub get | 생성 직후 작업 트리 변경 |
| T-13 | 기능 소유 slang.yaml 에 string_interpolation: braces · param_case: camel 이 없음 — 기능 번역의 {count} 가 매개변수가 아니라 글자 그대로 남는다 |
아무 번들 compose → 번역에 "page": "{current} / {total}" → dart run slang |
접근자가 String 게터로 생성(작성 쪽에서 두 줄 추가로 우회) |
| T-14 | cob generate --base kernel 이 console target 을 거부(generate_service.dart:526 「커널 바닥에는 콘솔 앱이 없습니다」) — 커널 f4bfa774 에는 app/console 이 있다 |
targets: [console] 매니페스트로 cob generate --base kernel |
콘솔 번들은 cob compose --layout bundle -m 로 직접 조립(우회) |
| T-15 | compose 출력 일부가 dart format 결과와 다름 — tool/feature_codegen.dart(compose 가 다시 쓰는 생성기 소유 파일) · remit_flag_table_page.dart |
compose → dart format --output=none --set-exit-if-changed tool/feature_codegen.dart |
CI 포맷 단계 FAIL — 기능 코드는 6a154fe 에서 맞췄고, 생성기 파일은 임시 adapter 로 포맷 검사에서만 뺀다(아래) |
| T-16 | CoUI(coui_flutter-v0.158.0) 웹 텍스트 선택(CoUIApp.enableWebTextSelection 기본 true · SelectionArea)이 라우트 스택의 화면 밖 페이지(중첩 라우트의 부모 · 전환 중 페이지) 글자를 배치 전에 정렬해 RenderBox was not laid out(Uncaught) |
릴리스 웹을 깊은 링크로 열기 — #/remittance/history?status=on_hold · #/recipients/recipient-1 (CDP Runtime.exceptionThrown: MultiSelectableSelectionContainerDelegate._flushAdditions → RenderParagraph.size) |
해소(2026-10-11) — coui_flutter-v0.159.0(coui#5355: #5268 · #5348 · #5361)으로 올리고 enableWebTextSelection: false 4곳(앱 · 콘솔 · 두 서버 모드 관문 앱)을 지웠다. 선택 영역을 켠 기본 설정에서 같은 깊은 링크 · Patrol(chrome) · Pages 스모크 예외 0 |
T-1~T-15 는 co-bricks#860 으로 올렸다 — 이 저장소에서 우회를 늘리지 않는다.
7.1 임시 adapter (제거 조건이 있는 것만)
| adapter | 적용 범위 | 제거 조건 |
|---|---|---|
CI 포맷 검사에서 tool/feature_codegen.dart 제외(.github/workflows/ci.yml 「생성물이 최신인가 · 포맷」 단계의 -e '^tool/feature_codegen\.dart$') |
그 파일 하나. 다른 작성 코드 · 생성물 판정은 그대로 | co-bricks#860 T-15 수정이 들어간 co-bricks 로 재조립(compose)해 그 파일이 dart format 결과와 같아지면 exclude 한 줄을 지운다 |
8. 1단계 이식 범위 · 남은 단계
이식(localOnly · 계약 경유 · 한 파일 한 공개 타입 · HookWidget + signals_hooks · CoUI Text 체인 · raw 색 0) — PRD 의 앱 13화면 · 콘솔 6화면 · 역할 진입 · 초기화를 모두 옮겼다(2026-10-09, 1단계 잔여 A 포함).
| 화면 | 번들 | 검증 |
|---|---|---|
| 로그인 화면(FR-001 — 데모 안내 FR-023 · 계정 · 언어 · 테마 · 초기화 FR-024) · 하단 탭 5개 | app/remit_world 셸 + app/app 호스트 |
여정 테스트(로그인 · 로그아웃 · 초기화) |
| A-01 홈 · A-06 신청 · A-07 한도 · A-08 추적 · A-09 내역(탭 8 + 전체, 720 이상 2열) · A-10 상세(고객 취소 · 재심사 요청) | remittance(app) |
여정 · Cubit 테스트 |
| A-02 · A-03 · A-04 | recipient(app) |
Cubit · 여정 테스트 |
| A-05 견적 | remittance_quote(app) |
단위 22 |
| A-11 추가서류 제출(모의 첨부 · 업로드 0) | supporting_document(app) |
저장소 · 여정 테스트 |
| A-12 알림함(분류 칩 · 날짜 섹션 · 안 읽음 · 읽음 처리) | remit_notice(app) |
저장소 · 여정 테스트 |
| A-13 송금 설정(즉시 저장 · 광고성 안내) | remit_preference(app) — 생성 골격을 이식 코드로 바꿈 |
저장소 · Cubit 테스트 |
| C-01 심사 큐 · C-03 심사 메모(결정 사유 필수) | remittance(console) |
여정 · Cubit 테스트 |
| C-02 고액 · 반복 플래그(5열 · 금액 정렬 · 해소 · 미해소 필터) | remit_flag(console) — 생성 골격을 이식 코드로 바꿈 |
여정(투어 7) · Cubit 테스트 |
C-04 정산(일자 · 수량 편집 · setLines · 「자금 이동 없음」) |
remit_settlement(console) |
저장소 · 여정 테스트 |
| C-05 수취인 · 고객 대장(국가 필터 · 10행 페이지 · 좁은 폭 목록 행 · 상세) | recipient(console) — 생성 골격을 이식 코드로 바꿈 |
Cubit 테스트 |
| C-06 한도 정책(운영 관리자 편집 → A-07 판정에 바로 반영) | remit_limit(console) |
저장소 · 여정 테스트 |
- FR-024 AC2 — 같은 브라우저의 앱 · 콘솔 탭이 한 세계를 나눈다: 각 기능이 자기 레코드 codec 을 소유하고(A 업무 데이터 ·
C 입력만, B 표시 투영은 저장하지 않는다)
app/remit_world가 묶어 쓰기마다 localStorage(키demo_exchange_remittance.world.v1)에 저장한다. 부팅은 저장본이 있으면 그것으로, 다른 탭의storage이벤트는 그 저장본으로 세계를 바꾸고 화면 세대를 올린다. 판이 다른 저장본은 버리고 시드에서 시작한다. 웹이 아닌 플랫폼은 저장하지 않는다(앱 하나가 세계 하나). - 화면 접근 권한은 기능이 소유한 행위자 계약(
*ActorPort)으로 저장소가 다시 검사한다 — 서류 · 알림 · 설정은 송금인만, 플래그 해소는 심사역 · 운영 관리자, 정산 편집은 정산 담당 · 운영 관리자, 한도 정책 편집은 운영 관리자. - 생성 골격의 서버 쪽(9개 모듈의 상수 · 예외 · 헬퍼 · 검증기 TODO)은 1단계에서 lint 만 맞췄고, 2단계(FB-3)에서 실제 모델 · 서비스 · endpoint 로 바꿨다(§9).
남은 것
- 3단계: co_demo_world 실시간 언어 전환 · 11개 언어 ·
docs/locale-data.md(LOCALE_DATA_GUIDE). - FB-3 · FB-4(2단계)는 §9.
- 검증 5종 중 골든 · BDD · Patrol 과 Pages 6면 — Widgetbook 은 새 화면 6종(A-11 · A-12 · A-13 · C-02 · C-04 · C-06)의 유즈케이스를 실제 localOnly 저장소 + 실제 Cubit 으로 더했다(나머지 화면은 다음 단계).
- 정체성
display_name(지금은 생성 기본값) → 송금 데모: 정체성 파일 13개(네이티브 포함)를 함께 바꾸고 Android 빌드 잡으로 확인해야 해서 따로 한다.
호스트 결정(1단계)
- 콘솔 역할 전환은
RemitConsoleHost(app/console)가 라우터를 새로 만든다(웹은overridePlatformDefaultLocation). 내비게이터가 GlobalKey 라 key 를 바꿔도 화면 상태가 남고, 최상위 화면 하나에서pushReplacement는 같은 page key 의go로 줄어든다(go_router 18.0.1parser.dart:271) — 이전 역할의 버튼이 남는 결함을 테스트가 잡았다. - 콘솔 머리 막대(콘솔 이름 · 화면 이동 · 계정 메뉴)는 라우터 밖이라
RemitShellBar가 표면 색을 칠하고, 첫 프레임 전에는 포커스 순회에서 뺀다 — 웹은 창 포커스 때 순회 노드의 위치를 모두 읽는데, 시드로 늦은 첫 프레임 전에 읽으면RenderBox was not laid out이 난다(릴리스 웹에서만 재현, 위젯 테스트는 통과했다). 앱은 머리 막대가 없다. - 데모 크롬은 로그인 화면에만 있다(사용자 결정 2026-10-14 · cocode#1259 — 설계 기록). 로그인
화면 = 커널
DemoLoginPanel(안내 · 데모 계정 · 언어 · 테마 · 초기화). 로그인 전에는 라우터 화면 자리를 대신 차지하므로 초기화 확인 대화상자가 뜰 페이지 하나짜리RemitLoginNavigator를 깐다. 계정 바꾸기는 앱 「설정」 맨 아래 (RemitPreferenceAccountSlot) · 콘솔 계정 메뉴(라우터 Navigator 위 대화상자)의 「로그아웃」이다(세션만 지운다). - 앱 · 콘솔 셸은 화면 세대(초기화 · 다른 탭의 변경)마다 라우터를 새로 만든다(
RemitAppHost·RemitConsoleHost) — 초기화 뒤에는 첫 화면에서, 그 밖에는 지금 주소에서 다시 연다. 셸 프레임의 탭 · 화면 이동 선택은 라우터가 첫 경로를 붙이는 도중에 알리므로 다음 프레임에 반영한다(useRouterLocation). - 기능 계약 바인딩 중 송금 ↔ 서류는 서로를 가리킨다(재심사 게이트 · 서류의 송금 확인) — 서류 쪽 브리지는 저장소를 만들 때가 아니라 부를 때 찾는다(lazy 등록이 서로를 만들다 멈추던 순환을 테스트가 잡았다).
- 체험 시계는 명령(이벤트 루프 한 차례)마다 +2분이다. 데모 세계 변경 신호가 한 건씩 마이크로태스크로 오므로 마이크로태스크로는
묶이지 않는다(쓰기 3건이 +6분이 되던 것을
remit_world테스트가 잡았다) —Timer(Duration.zero)로 한 번만 센다.
9. 2단계 — 실제 백엔드(FB-3) · 데모/서버 계약(FB-4) (2026-10-09)
9.1 기능 server 모듈 (공식 CLI tool/serverpod/cli.sh generate — serverpod_cli 4.0.3, 모듈 → 호스트 DAG 순서)
| 모듈 | 테이블 | endpoint | 불변식 · 규칙(서버가 다시 검사) | 단위 |
|---|---|---|---|---|
recipient_server |
remit_recipient |
RecipientEndpoint list · get · create |
송금인 소유 격리(남의 것 not_found) · 대장은 직원 · 이름 · 계좌 4자리 · 가상 은행 · 국가/수령/관계 코드 · 이름 마스킹 · requestKey 멱등 · id recipient-<최대+1>(트랜잭션 잠금) |
5 |
remittance_quote_server |
remit_quote |
RemittanceQuoteEndpoint quote · find |
1만~10억 원 · 내 수취인 · 송금 경로(co_faker remit — 앱과 같은 출처) · 정수 금액 · 유리수 환율 · 받는 금액 내림 · 정밀도 상한 사전 검사 · 고시 구간(정시) 위조 거부 | 7 |
remittance_server |
remit_transfer · remit_milestone · remit_review_note |
RemittanceEndpoint list · get · create · transition · milestones · limitChecks · addReviewNote · home · transferQuote · documentCount · availableTransitions · recipientStats |
상태머신 1 · 전이 주체(FR-021) · 보류/반려 사유 · 보류 서류 종류 · 재심사 서류 게이트 · 견적 소유/만료/수취인 국가 · 같은 견적 멱등 · 전역 순번 NR-YYMMDD-#### · 행 잠금(FOR UPDATE) + revision(stale_revision) · 한도 4항목 · 보류/도착 알림 · 도착 정산(같은 트랜잭션) |
13 |
supporting_document_server |
remit_document |
SupportingDocumentEndpoint transferFor · create |
송금인 · 내 송금 · 보류 상태 · 서류 종류 · 번들 샘플만(업로드 0) · 미래 발행일 거부 · requestKey 멱등 |
5 |
remit_notice_server |
remit_notice |
RemitNoticeEndpoint mine · markRead |
송금인 본인만 · 읽음 멱등 · 게시는 송금 트랜잭션 · id 잠금 | 3 |
remit_preference_server |
remit_preference |
RemitPreferenceEndpoint mine · update |
저장 위치는 호출자(입력 ownerId 무시) · 알림일 1~28 · 목적 코드 | 4 |
remit_flag_server |
remit_flag |
RemitFlagConsoleEndpoint list(연결 송금 상태 포함 RemitFlagEntry) · resolve |
표는 직원 · 해소는 심사역 · 운영 관리자 · PRD 상태머신 2(연결 송금 approved · rejected 일 때만 — 호스트가 remittance 에 묶은 transferStatuses 계약을 같은 트랜잭션의 공유 잠금으로 읽는다 · 되돌림 없음 already_resolved) · 행 잠금 |
4 |
remit_settlement_server |
remit_settlement_line |
RemitSettlementConsoleEndpoint days · lines · setLines |
직원 조회 · 정산 담당/관리자 편집 · 같은 일자 · 음수 금지 · 도착 반영은 일자 잠금(동시 도착 수량 유실 0) | 5 |
remit_limit_server |
remit_limit_rule |
RemitLimitConsoleEndpoint rules · save |
직원 조회 · 관리자 저장 · 한도 > 0 · 기간 1~365 · 행 잠금 + revision | 4 |
- 실패는 모듈 예외
<Feature>Failure.code— localOnly 실패 코드와 같다(송금 scope 가 없는 로그인 사용자의role_denied· 전송 경계의invalid_purpose만 서버 쪽 추가). 모든 endpoint 는requireLogin. - 호스트(
backend/demo_exchange_remittance_server):RemitHostPorts(호출자 = 인증 +remit_account매핑 · 업무 시계 · 교차 기능 어댑터),remitAccount.me(신원 · 업무 기준 시각), 데모 세계 시더(빈 DB 에만 — localOnly 시드 스냅샷demo/remit_world_seed.v1.json,app/remit_world시험이 같은지 지킨다), 데모 페르소나 계정 5개(개발 모드 · 비밀값demoAccountPassword). - DB 정책: 커널 migration 을 지우고 패키지마다 공식 CLI baseline 하나(
create-migration --tag baseline) — 시간 이력 누적 없음, 격리 시험 DB(demo_exchange_remittance_657이 아니면 시험이 시작하지 않는다), 공유 DB 를 지우지 않는다.
9.2 시험
| 층 | 위치 | 수 | 결과(로컬) |
|---|---|---|---|
| 모듈 단위(DB 없음) | feature/*/server/test/unit |
49 | PASS(9 패키지) |
| 호스트 통합 — 생성 SDK → dispatcher → 모듈 → DB | backend/…/test/integration |
54 + 커널 상태 1 | PASS(임베디드 PostgreSQL · CI 는 서비스 컨테이너) |
| 계약 동등성 — localOnly ≡ 앱의 서버 모드 저장소(생성 SDK) | app/remit_world/test/contract |
12 시나리오(상태머신 2 포함) | PASS |
| 서버 모드 셸(로그인 관문 · 신원 머리 · 명시 실패) | app/app · app/console |
4 · 2 | PASS |
통합 시험이 보는 것: 소유 격리 · scope · 불법 전이 · 사유 · 서류 게이트 · 정수 금액 · 한도 판정 · 동시 이중 제출(1건) · 동시 결정 (1승) · 동시 도착(수량 +2) · revision 거절 · requestKey 멱등 · 정산 실패 시 전이 · 알림 롤백(원자성) · 미바인딩 9개 기능 fail-closed · 서버 인스턴스별 바인딩 · 실제 로그인(이메일 IdP → JWT → 매핑) · DB 정책(baseline 하나 · 빈 DB = 모델 · 시드는 빈 DB 에만). 시험 API 포트는 대역 안(25710 · 25712~25715).
9.3 앱 서버 모드 · 공개 데모
- 기능마다
Serverpod*Repository가 그 번들의 client 역할(모듈 호출자)로 서버를 부른다. 서버에 닿지 못하거나 호출자가 조립되지 않았으면serverNotConnected(「…서버에 연결할 수 없어요」) — 데모 세계로 조용히 폴백하지 않는다(S-13). - 셸: 서버 주소가 없으면 「서버 없음」, 있으면 로그인 관문(페르소나 이메일 채우기 · 비밀번호는 서버 비밀값) → 신원(앱=송금인, 콘솔=직원) → 화면, 닿지 못하면 「서버에 연결할 수 없어요」(다시 시도 · 로그아웃). 앱 시계는 서버 업무 시계에 맞춘다.
- 공개 Pages 는 그대로 localOnly. 공개 스모크(
tool/pages/smoke/public_smoke.mjs)가 외부 아이콘 API 호출을 잡았다 — CoUIIcon이 등록되지 않은 아이콘을api.iconify.design에서 받는다(화면 4개에서 32건). 저장소 · CoUI 가 쓰는 Lucide 52개를 번들해(tool/icons/lucide_bundle.py·OfflineIcons.register(), 검사--check는 CI검증 (generated)) 출처 밖 요청 0 이 됐다. CoUI 쪽 빌드 시 아이콘 번들은 coco-de/coui#5149 에 근거로 연결했다(데모 36개가 같은 결함을 갖는다) — 그 기능이 나오면 이 번들을 지운다.
9.4 CI — 증거 대장 잡(main 커밋에서도 돈다)
커널 #30(coco-de/kernel d36c5ccb)의 증거 잡 계약을 따른다 — main push · workflow_dispatch(입력 evidence)는
변경 범위 판정 없이 전부 돌고, main · dispatch run 은 서로 취소하지 않는다. 게이트 → 잡 이름 정본은
tool/ci/evidence_jobs.json(수집기 --repo-jobs 가 읽는다), check_evidence_jobs.py 가 워크플로 · CLAUDE.md 와의
어긋남을 막는다. 표는 CLAUDE.md 「CI 증거 게이트 ↔ 잡 이름」.
| 게이트 | 워크플로 · 잡 이름 | 트리거 |
|---|---|---|
| unit · widget | CI · 검증 (tests-1) (+ 검증 (tests-2) · 검증 (tests-modules)) |
PR · main push · dispatch |
| bdd | CI · 검증 (bdd) (TEST_SUITE=bdd) |
PR · main push · dispatch |
| widgetbook | CI · 검증 (widgetbook) (TEST_SUITE=widgetbook) |
PR · main push · dispatch |
| backend (runtime_mode: server) | CI · 백엔드 통합 (server · PostgreSQL) (+ 검증 (tests-server)) |
PR · main push · dispatch |
| golden (mode: compare) | Golden · 골든 (compare) |
PR · main push · dispatch(evidence) |
| surfaces | Pages · 사이트 빌드 |
PR · main push · dispatch |
| smoke (runtime_mode: localOnly) | Pages · 공개 스모크 |
main push 배포 뒤 · dispatch(evidence=true) |
| locale · patrol | (잡 없음 — 3단계 · 남은 일) | — |
골든 기준 갱신(골든 (update))은 명시 트리거에서만 — main 밖 브랜치 push 의 [update-goldens] 커밋 메시지 또는
dispatch update_goldens=true(main 밖 브랜치). main 에서는 갱신하지 않는다.
9.5 남은 것
- (3단계에서 해결) PRD 상태머신 2(플래그 해소 조건) — localOnly · 서버가 같은 계약으로 구현했다: 해소는 심사역 · 운영 관리자만, 연결
송금이 approved · rejected 일 때만(
transfer_not_decided), 되돌림 없음(already_resolved, 데모 초기화로만 복원). 플래그 기능이 소유한 송금 상태 계약(FlagTransferPort· 서버transferStatuses)을 호스트가 송금 기능에 바인딩한다. - 3단계(locale) · 골든 · BDD · Patrol 화면 확장 ·
display_name은 §8 그대로.