Files
clean-architecture-frontend…/docs/architecture/capability-consumer-experience.md
T
DongHyeonka 06ffafa25e docs: 살아 있는 문서의 낡은 문장을 지금 코드와 정본에 맞춘다
2026-11-07~08의 정리(문서 이동, 참조 기능 삭제, CI 재편) 뒤 살아 있는
문서가 지금 코드와 다른 말을 한다.

- 현재 계약 문서 둘과 스타터 문서가 기록(docs/design/)을 정본으로
  가리킨다. 정본을 frontend-application-foundation.md·src/bootstrap/,
  패턴 표·계층 규칙으로 바꾸고 설계서는 배경으로 둔다(1112/02-06).
- 실시간 대응표 둘(짝 백엔드 출구, poll attempt 결과)이 기록에만 있었다.
  optional-adapter-recipes.md로 옮기고 코드 주석·매뉴얼 03·설계서 머리
  블록이 옮긴 곳을 가리킨다(1112/09-02).
- 실행 격리 변수 목록을 설계 기록이 아니라 scripts/lib/run-isolation.ts로
  가리킨다(1112/08-17).
- 계약 소유 절 이름(「판단 규칙」), pin 대조 시험의 게이트(005·007),
  drift 검사 범위(1112/02-07). INVENTORY 머리의 손 숫자와 지킬 수 없는
  꼬리 문장(1112/02-08).
- 검증 안내: 검사기를 바꾸면 FE-GATE-029, 문서면 desktop
  verify:documentation(1112/08-05, 08-04). FE-GATE-012는 merge 단계다
  (08-16). N6이 알리는 파일을 좁혀 적는다(08-10). 한 파일 시험은
  verify.sh exec(08-11). 문서 검사 범위의 손 사본을 정본 한 곳으로(08-07).
- create:feature 참조의 Next: 3과 되돌리기(08-08), 손으로 옮긴 숫자
  (08-19), 라운드 없는 리뷰 ID 17곳에 0925를 붙인다(08-15).
- secret scan 범위 설명(1112/07-03), lab이 기능 라우트를 읽는 문장
  (1103/16-06), README 동기화 기준점·제품 소유 파일·선택 기능 결함 몫
  (0929/14-02, 14-03, 13-10), 커밋을 다시 지은 모든 통합의 해시 대조
  (1106/14-02).

고른 방법: 문장을 코드에 맞춘다. 표는 옮기고 숫자는 정본을 가리킨다.
버린 대안: 기록 문서 본문 고치기(기록은 머리 블록만 고친다).

위험·한계: 문서 검사 범위 목록을 지운 ci-quality-gates.md는 이제
docs/README.md 5절과 gates.md 7절을 읽어야 한다. 매뉴얼 02 7절 업로드
예의 declare module 문제(1112/09-01)는 고치는 방향이 check:architecture
규칙과 부딪쳐 결정 대기로 남긴다.

검증: scripts/verify.sh docs(노트북) 통과. desktop verify:documentation과
FE-GATE-005(문서를 읽는 시험)는 PR 본문에 적는다.

Refs: 1112/02-06, 1112/02-07, 1112/02-08, 1112/07-03, 1112/08-04,
 1112/08-05, 1112/08-07, 1112/08-08, 1112/08-10, 1112/08-11, 1112/08-15,
 1112/08-16, 1112/08-17, 1112/08-19, 1112/09-02, 1103/16-06, 0929/14-02,
 0929/14-03, 0929/13-10, 1106/14-02
2026-11-12 23:36:14 +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

이 문서는 이 파일들의 줄 수를 적어 두지 않는다. 손으로 적은 줄 수가 코드와 어긋난 적이 있다(리뷰 0925/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 프로세스 모델이다.