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
148 lines
7.3 KiB
Markdown
148 lines
7.3 KiB
Markdown
# 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 프로세스 모델이다.
|