Files
clean-architecture-frontend…/docs/architecture/capability-consumer-experience.md
DongHyeonka 374af98640 docs: 번역하며 찾은 낡은 서술을 코드·설정에 맞춘다
문제: 살아 있는 문서를 옮길 때 뜻을 바꾸지 않는다는 규칙 때문에 남겨
둔 낡은 서술이 있다.
- contract-ownership: 계약 파일 「39개」. 지금 src/contracts의 .ts는 44개다.
- capability-consumer-experience: Local Draft를 「두 번째 구체 소비자」,
  「두 feature」라고 부른다. 지금은 제품 feature가 아니라 테스트 fixture
  (tests/fixtures/indexeddb-consumer)다.
- static-delivery: initialJavascript.files가 「예시 feature 기준」이라고
  한다. feature-shape-ceilings.json은 feature가 없는 지금 템플릿 빌드라고
  적는다.
- .dependency-cruiser.json:254 주석이 번호 없는 layers.md의 「§4」를 가리킨다.
- runbook 문서 제목 셋이 runbooks.json title과 다르다. FE-RB-002는 영어
  원문부터 manifest가 빠져 있었고, 001·003은 번역에서 갈라졌다.
- ci-quality-gates: zod 행의 고친 버전은 4.6.6인데 이유 칸은 4.6.7을 말한다.
  4.6.7은 올렸을 때 잰 버전이다(26ca2fdb 원문 "4.6.7 also adds").
- 같은 문서 FE-GATE-016 문단 끝 두 문장은 원래 runbook record 고정 경로
  문단의 것이다(6c52cdb9 원문). 폐기 문장 뒤로 밀려 뜻이 끊겼다.

고른 방법: 숫자는 옮겨 적지 않고 정본(src/contracts/)을 가리킨다.
Local Draft는 fixture라고 쓰고, 편의 프로필을 들일 조건을 「IndexedDB를
쓰는 제품 feature」로 좁힌다. 절 번호는 절 이름으로, 문서 제목은 등록부
title로 맞춘다. zod는 「고친 버전 이상으로 올리면」으로 쓰고 잰 버전과
날짜를 괄호에 둔다. 두 문장은 원래 문단으로 옮긴다.

위험: zod 7 KB는 다시 재지 않았다(2026-11-04 측정값 그대로).
cruiser 주석은 check:architecture 위반 메시지의 why 줄에 나온다. 이 주석을
비교하는 시험은 없다.

검증: 각 사실을 git ls-files, feature-shape-ceilings.json, runbooks.json,
layers.md 절 제목, 원문 커밋으로 확인했다. 문서 검사와 관련 시험은
desktop에서 돌린다.
2026-11-12 09:40:51 +09:00

7.3 KiB

capability 소비자 경험 기준선

재사용 capability 안이 올바르다는 것만으로는 부족하다. 플랫폼은 그 올바름을 쓰려고 보통의 feature 개발자가 얼마나 많이 알아야 하는지로도 평가받는다.

이 측정값은 기준선이지 점수 목표가 아니다. 줄 수가 적어도 업무 의미를 숨기거나 만능 repository 추상화를 만든다면, 저절로 더 좋은 것이 아니다.

시나리오 A — REST feature

REST 소비자는 corepack pnpm create:feature <id> --with-create가 쓰는 feature다(2026-11-07까지는 템플릿의 참조 샘플이 이 역할을 했다).

목록·상세·생성 동작, 매핑, 타입이 있는 operation 입력, application port를 다룬다.

feature가 소유한 경계 코드와 application 코드는 다음 네 파일이다.

  • application/<base>-feature-api.ts
  • contracts/<base>-mapper.ts
  • adapters/<base>-http-gateway.ts
  • adapters/create-<base>-feature-input.ts

이 문서는 이 파일들의 줄 수를 적어 두지 않는다. 손으로 적은 줄 수가 코드와 어긋난 적이 있다(리뷰 14-07). 생성한 feature에서 이 네 파일에 wc -l을 돌려 잰다.

중요한 경계 지표는 단순 합계가 아니다. 이 파일들이 플랫폼에 대해 무엇을 알아야 하는지다.

지금 결과:

  • feature adapter 계층에서 HTTP 플랫폼을 import하는 파일: 2개
  • 두 파일이 쓰는 정식 import 경로: src/adapters/http/index.ts
  • http-execution-v3.ts, retry scheduler, 응답 reader, 인증 승인(auth admission), effect-certainty 내부 모듈을 직접 import하는 곳: 0
  • 전송 실패를 변환(projection)하는 일을 feature gateway가 맡는 곳: 0
  • feature gateway가 operation ID, route ID, 정확한 입력·값 타입, mapper를 고르는가: 예
  • 중앙 설치 파일이 feature 전용 adapter·runtime 연결을 소유하는가: 아니오. feature가 소유한 contribution을 중앙에서 모을 뿐이다.

실행 결과를 정규화하는 일은 이제 재사용 HTTP capability가 createFeatureHttpBinding으로 맡는다. 재사용 계약이 업무 요구에 맞지 않으면, feature는 여전히 자기 application port 뒤에 직접 만든 outbound adapter를 둘 수 있다.

시나리오 B — IndexedDB 로컬 초안

실행되는 소비자 탐침(probe)은 다음이다.

tests/contract/consumer-experience/indexeddb-local-draft.test.ts

이 테스트는 Local Draft 구현 하나를 실행하고 읽는다. 그 구현은 테스트 fixture tests/fixtures/indexeddb-consumer다. 예전에 src/features/ 아래 있던 템플릿의 local-draft 샘플인데, 제품 feature가 아니라서 이리로 옮겼다. 예전에 따로 떼어 둔 복사본은 이 구현과 어긋나서 지웠다(09-12).

소비자는 Local Draft의 domain·application API를 소유한다. 그리고 repository에서 자기가 부르는 부분(slice)을 선언한다 (tests/fixtures/indexeddb-consumer/adapters/local-draft-indexeddb-store.ts의 LocalDraftRepository). host는 indexedDb capability로 IndexedDbRepositoryPort<LocalDraft, never>를 넘겨준다. 이 port는 구조적 타입으로 그 slice를 만족한다. capability를 가로지르는 조립 계약은 다음에 있다.

tests/contract/reusable-capability/feature-adapter-composition.test.ts

이 테스트는 HTTP만 쓰는 contribution 하나와 IndexedDB만 쓰는 Local Draft contribution을 같은 범용 카탈로그 경로로 조립한다.

브라우저 수준의 조립 증명은 다음에 있다.

tests/browser-capabilities/local-draft-composition.spec.ts

이 테스트는 브라우저의 실제 IndexedDB에서 돈다. 먼저 플랫폼의 createIndexedDbRuntime을 만들고, 타입이 있는 createIndexedDbRepositoryProvider로 그 runtime을 내놓는다. 그다음 LOCAL_DRAFT_FEATURE_ADAPTER_CONTRIBUTION을 조립하고, feature API로 Local Draft의 저장·조회·삭제를 실행한다. 그래도 Local Draft feature는 IndexedDB runtime이나 브라우저 기본 API를 import하지 않는다.

Local Draft 소비자가 아직 src/features/ 아래 있을 때 잰 값(09-12):

지표 결과
feature LOC (모든 .ts 파일) 295
feature 밖으로 나가는 import 문(contracts/errors, contracts/result, application-api, feature-adapter-contribution) 7
브라우저 기본 IndexedDB API 참조 0
src/adapters/storage/indexeddb/** import 0
src/application/ports/browser-file-storage/** import 0

이 feature는 storage runtime도 그 port도 import하지 않는다. 그래서 브라우저 file/storage runtime을 지워도(test:browser-file-storage-removal) 계속 컴파일된다.

계약 테스트는 다음에 손대는 feature 코드를 거부한다. globalThis.indexedDB, IDBFactory, IDBDatabase, IDBTransaction, IDBObjectStore, 구체 IndexedDB adapter 디렉터리, browser-file-storage port다.

이것이 증명하는 것과 증명하지 않는 것

계약 탐침은 IndexedDbRepositoryPort가 조립되고 나면 feature 업무 코드에 브라우저 기본 IndexedDB 지식이 필요 없다는 것을 확인한다. 브라우저 capability 증명은 하나를 더 확인한다. 그 port 뒤에 이 repo의 실제 createIndexedDbRuntime과 브라우저 기본 IndexedDB 구현이 있어도, 같은 feature contribution이 동작한다는 것이다.

createIndexedDbRuntime을 조립하는 비용이 싸다는 것은 증명하지 않는다. 이 생성 함수는 여전히 상당한 인프라 정책을 갖고 있다.

  • dataset 범위와 저장 정책
  • 물리 store 관리
  • 보존·멱등성(idempotency) store
  • schema 마이그레이션
  • codec과 조회 정책
  • 수명 주기 권한(lifecycle authority)
  • 내구성, 스케줄링, 관측

이 복잡함은 feature가 아니라 조립·플랫폼 경계에 둔다. Local Draft 세로 slice는 이 repository port를 feature 모양으로 쓰는 구체 소비자다. 다만 제품 feature가 아니라 테스트 fixture(tests/fixtures/indexeddb-consumer)다. 이 소비자는 안정된 연결 지점(seam)이 타입이 있는 repository provider와, feature가 소유한 repository 식별자라는 것을 확인한다. dataset 범위, 보존, 마이그레이션, codec, 수명 주기 권한 설정을 만능 create...Repository<T> factory 하나로 안전하게 합칠 수 있다는 것은 보여 주지 않는다.

그래서 편의 프로필은 IndexedDB를 쓰는 제품 feature가 생기고, 그 feature들이 같은 인프라 정책을 되풀이한 뒤에만 들인다. 여러 소비자가 같은 repository port를 쓴다는 이유만으로 들이지 않는다.

소비자 품질 검토 체크리스트

새 제품 feature마다 다음을 기록한다.

  • feature가 소유한 adapter LOC
  • 플랫폼 연결 코드(glue) LOC
  • 바뀐 파일
  • 중앙 카탈로그 수정
  • capability 내부 모듈 직접 import
  • 브라우저·네트워크 기본 API 참조
  • 중복된 실패·retry·수명 주기 정책

건강한 feature 경로는 다음 모양이다.

  1. domain 타입과 불변식
  2. use case
  3. 업무 port
  4. feature가 소유한 mapper·codec과 정책
  5. capability 전용 binding
  6. presentation controller·페이지

feature는 다음을 알 필요가 없어야 한다. retry scheduler, abort 소유, effect-certainty 장치, IndexedDB transaction 수명 주기, OPFS journal, 재연결 coordinator, provider 프로세스 모델이다.