문제: docs/architecture의 현재 계약 문서 가운데 scale-architecture.md, starter-experience.md, capability-consumer-experience.md, contract-ownership.md, static-delivery.md, review-evidence.md는 본문이 영어이고, backend-api-and-server-state-contract.md와 optional-adapter-recipes.md에는 영어 문단이 남아 있다. 고른 방법: 뜻을 바꾸지 않고 옮긴다. 백틱 안, 링크 대상, 절 번호(코드 주석이 `scale-architecture.md §N`으로 인용한다), 표 구조, 코드 블록은 그대로 둔다. 문서를 읽는 테스트와 절 이름을 인용한 곳을 같은 변경에서 고친다. - tests/unit/feature-tracked-files.test.ts: starter-experience.md 표를 자르는 시작·끝 문장과 표 행마다 찾는 낱말(`병합 충돌`) - 「Ownership declarations」「Adding a feature」를 인용한 주석 (create-feature.ts, generate-product-feature-index.ts, app-module.ts)과 docs/manual의 절 이름 인용 - optional-adapter-recipes.md의 recipe 개수 복사를 카탈로그를 가리키게 바꾼다(number 검사) 위험: create-feature.ts 417줄은 생성하는 context-module.ts의 JSDoc이라 새로 만드는 기능의 주석 글자가 바뀐다. 그 글자를 비교하는 테스트는 없다. review-evidence.md는 산문만 옮겼고 해시·점수 칸은 그대로다. 검증: 백틱 span·링크 대상·코드 블록·번호 제목을 옮기기 전과 python으로 비교해 같다. 문서 검사의 language 줄이 이 문서들에서 0이 되어 예외 목록에서 지웠다.
147 lines
7.2 KiB
Markdown
147 lines
7.2 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`
|
|
|
|
이 문서는 이 파일들의 줄 수를 적어 두지 않는다. 손으로 적은 줄 수가 코드와 어긋난 적이 있다(리뷰 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는 이제 두 번째 구체 소비자다.
|
|
이 소비자는 안정된 연결 지점(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 프로세스 모델이다.
|