Files
DongHyeonka 63ba523519 fix(form): 저장 뒤 이동과 마운트 판정을 폼이 맡고 다시 로그인 안내를 먼저 그린다
앞 커밋(1112/01-01) 뒤 확인 리뷰가 완료 기준의 남은 셋과 결함 둘을 찾았다.

- 생성 작성 페이지에 마운트 표시(useRef)와 저장 뒤 이동이 남았다. 저장이
  끝나면 페이지가 폼보다 먼저, 폼이 pending인 동안 상세로 옮겼다. 다시
  마운트한 폼에서 재전송이 성공하면 사용자가 돌아와 입력한, 보낸 적 없는
  값을 이탈 확인 없이 버렸다(1112/01-02 영향).
- 폼이 재전송 결과로 결과 불명을 다시 판정했다(resendLeftUnknown).
  코디네이터와 401에서 갈린다. 코디네이터는 결과 불명을 쥐고 폼은 다시
  로그인으로 가는데, FormSaveFeedback이 결과 불명을 먼저 그려 다시 로그인
  안내를 가렸다(D-2 위반).
- 지난 세 결함(1105/08-02·08-04, 1106/08-02)의 시험이 생성 페이지 시험에만
  있었다.

고른 방법: useAppForm에 onSaved를 더한다(추가만). 폼이 결과를 보이고
pending을 끈 뒤, 마운트된 동안만 부른다. confirmUnknownEffect(then)도
마운트된 동안만 then을 부른다. resendUnknownEffect의 then 인자와
FormSaveFeedback의 onResent는 지운다(앞 커밋에서 생겨 아직 내보낸 적이
없다). 재전송 뒤 결과 불명인지는 코디네이터의 새 holdsUnknownEffect로
묻는다. mutation 없이 쓰는 폼(이미 생성한 페이지)은 물을 곳이 없어 같은
거절 표(isRefusedOnEveryAttempt)로 본다. FormSaveFeedback은 다시 로그인
실패를 결과 불명보다 먼저 그린다. 생성 페이지는 mutation.submit을 그대로
넘기고 onSaved와 onConfirmed에서 옮기기만 한다. VD-04 머리 칸에 넣었던
문장은 보완 절로 옮긴다(머리 칸의 백틱 낱말을 문서 검사가 경로로 본다).
페이지가 FormSaveFeedback을 늘 넘기므로, 할 말이 없는 피드백 칸은 자리를
차지하지 않는다(templates.css, 빈 칸이 그리드 간격을 한 줄 더했다).

위험·한계: 저장 뒤 이동이 폼이 결과를 그린 뒤로 한 번 늦어진다. 다시
마운트한 폼에 보내지 않은 값이 있으면 이동이 이탈 확인을 띄운다(의도).

검증: form-foundation 새 시험 일곱과 create-feature 생성 페이지 시험
(RED·GREEN, 막기·다른 저장·충돌 안내 변이 셋), 생성 기능 e2e의 피드백 칸 간격 시험은 desktop에서 돌려 PR
본문에 적는다.

Refs: 1112/01-01, 1112/01-02, 1105/08-02, 1105/08-04, 1106/08-02, 1112/04-02
2026-11-13 00:03:42 +09:00

13 KiB

기능 개발 패턴

기능을 만들 때 쓰는 패턴과, 그 패턴의 정의와 예제가 어디 있는지 적는다.

  • 정의: 플랫폼(기능 밖)에서 패턴을 제공하는 파일.
  • 예제: 복사해 볼 수 있는 기능 코드. 생성 뼈대는 create:feature가 만드는 코드다. 쓰기 slice는 create:feature <id> --with-create가 더 만드는 코드다(짝 백엔드 Envelope 모양). 코드 조각은 매뉴얼 안의 코드 블록이다. 생성 뼈대에 없는 모양을 보이고, tests/unit/manual-code-blocks.test.ts가 생성 기능 위에서 타입 검사와 동작 시험을 돌린다.
  • 예제가 없는 패턴은 없음이라고 적었다. 그 패턴은 정의를 읽고 직접 쓴다.

템플릿에는 복사해 볼 기능 샘플이 없다. 모양을 보고 생성 뼈대에 옮긴다.

기능 조립

패턴 정의 예제 검사
기능 모듈 등록 src/features/feature-module.ts (defineFeatureModule, defineFeatureRuntime), 생성기 생성 뼈대 feature-module.ts, feature-runtime.ts 생성기, 기능 ID와 계약 featureId 일치
context 소속 선언 src/contexts/bounded-context-module.ts 생성 뼈대 src/contexts/<base>-context/context-module.ts(새 context를 만들 때) 생성기(없는 context, 예산), 앱 모듈(루트 밖 라우트)
context 전용 레이아웃 docs/architecture/starter-experience.md "제품 홈과 레이아웃" tests/helpers/fixture-layout-product.tsx (테스트 fixture) tests/component/context-layouts.test.tsx
앱 홈 대신하기 src/contracts/routes.ts의 FEATURE_REPLACEABLE_PLATFORM_ROUTE_IDS 없음 (기능 예제) 조립 (두 기능이 APP_HOME을 선언하면 실패)
조립 기여(needs) src/features/feature-adapter-contribution.ts 생성 뼈대 adapters/create-<base>-feature-input.ts 조립 (없는 capability, 다른 기능의 input)
제품 capability src/features/product-capabilities.ts(타입), src/bootstrap/product-composition.ts(값), src/bootstrap/product-composition-contract.ts recipes/frontend-capabilities/indexeddb-feature-capability.ts check:types
기능 끄기 config/runtime/<profile>.json의 FEATURE_OVERRIDES config/runtime/local.json tests/component/product-feature-switch.test.tsx(시험 전용 기능으로 메뉴·홈 링크·직접 주소를 본다)

라우트

패턴 정의 예제 검사
라우트 선언 src/contracts/routes.ts, src/contracts/route-runtime-contract.ts 생성 뼈대 계약 routes, routeRuntimeContracts 조립(중복 route ID), check:registries(경로·chunk 중복)
context 라우트 적재 src/platform/routing/context-route-module.ts 생성 뼈대 context-routes.ts context 적재(계약에 없는 handle)
route ID로 URL 만들기 src/presentation/routes/route-codecs.ts의 buildRouteUrl 생성 뼈대 presentation/<base>-routes.ts 타입(기능의 route ID만 받음)
파라미터·검색값 codec src/presentation/routes/route-codecs.ts 쓰기 slice presentation/<base>-route-codecs.ts(상세 params). 검색값 codec은 01 문서 6단계의 코드 조각 해석 실패 시 잘못된 경로 화면
URL 검색값 읽기 src/presentation/routes/route-input.tsx의 useRouteInput + 검색값 codec 코드 조각: 01 문서 6단계의 contracts/<base>-list-search.ts, presentation/use-<base>-list-filters.ts 해석 실패 시 잘못된 경로 화면
URL 검색값을 바꾸는 폼 buildRouteUrl의 search, 디자인 시스템 SearchField, CollectionPage의 toolbar 기능 예제 없음. 아래 짧은 예 라우터를 거치는 페이지 테스트

URL 검색값을 바꾸는 폼 (짧은 예)

검색값의 정본은 URL이다. 입력 중인 글자만 state에 둔다.

사용자가 검색어를 입력한다 (state의 draft만 바뀐다)
  → 제출하면 navigate(목록 URL + ?q=...)
  → 라우터가 검색값 codec으로 q를 읽는다
  → 목록 쿼리 입력이 바뀌어 GET을 다시 보낸다

준비:

  • 목록 라우트의 searchSchema와 routeRuntimeContracts의 searchCodec.
  • 그 codec을 context-routes.ts handle의 codecs와 URL 함수(buildRouteUrl의 세 번째 인자)에 함께 넘긴다.
  • 검색값을 읽는 hook. 01 문서 6단계의 코드 조각 use-<base>-list-filters.ts가 예제다.
// 공지 기능의 목록 페이지. noticeRouteUrl은 생성된 <base>-routes.ts의 URL 함수다.
const navigate = useNavigate();
const listQuery = useNoticeListQuery(); // URL 검색값 읽기
const [draft, setDraft] = useState(listQuery.q ?? "");
const search = (q: string) =>
  void navigate(noticeRouteUrl("NOTICE_LIST", q.trim() ? { search: { q: q.trim() } } : {}));

<CollectionPage
  toolbar={
    <form role="search" onSubmit={(event) => { event.preventDefault(); search(draft); }}>
      <SearchField
        label={message("notice.list.search")}
        clearLabel={message("notice.list.searchClear")}
        value={draft}
        onChange={(event) => setDraft(event.currentTarget.value)}
        onClear={() => { setDraft(""); search(""); }}
      />
      <Button type="submit">{message("notice.list.searchSubmit")}</Button>
    </form>
  }
  /* heading, resultCount, children은 생성된 목록 페이지와 같다 */
/>

API와 검증

패턴 정의 예제 검사
HTTP 계약 src/contracts/external-contract-runtime.ts 생성 뼈대 contracts/<base>-contract-contribution.ts 계약 조립, check:registries (FE-REG-API 행은 src/contracts/api-operations.ts의 projectApiOperationRows가 뽑는다)
스키마 메타데이터 src/contracts/schema-registry.ts의 SchemaDefinition 생성 뼈대 contracts/<base>-schema-metadata.ts check:registries (FE-REG-SCHEMA)
배포된 계약 패키지 출처 같은 파일의 EXTERNAL_PACKAGE 생성 뼈대(자리표시자 또는 --package 신원). 실제 @org-contracts/* 패키지를 import하는 예제는 없음 계약 조립(신원 형식), 릴리스 승인(자리표시자)
런타임 검증기 src/contracts/zod-validator.ts의 zodValidator 생성 뼈대 contracts/<base>-schemas.ts 스키마 ID 중복
검증 생략 src/contracts/unvalidated-payload.ts의 unvalidatedPayload 없음 (기능 예제) 이유가 비면 throw, listUnvalidatedPayloads가 목록을 보임
DTO → 화면 값 mapper src/contracts/boundary-mapper.ts의 BoundaryMappingResult 생성 뼈대 contracts/<base>-mapper.ts 타입 검사
gateway port + HTTP 어댑터 src/adapters/http/index.ts의 createFeatureHttpBinding, defineFeatureHttpOperationForRoutes 생성 뼈대 adapters/<base>-http-gateway.ts 음성 타입 fixture (operation ID, route ID, 입력)
문제 응답 → 업무 실패 mapProblem (HTTP 바인딩) 쓰기 slice adapters/<base>-http-gateway.ts(400 <BASE>_INVALID → 이름 칸). problem details 백엔드(409, 422)는 02 결정표 4절의 코드 조각 기능 테스트
결과와 실패 src/contracts/result.ts, src/contracts/errors.ts 생성 뼈대 application/<base>-feature-api.ts FailureKind 닫힌 어휘(타입)
실패 → 화면 행동 src/contracts/errors.ts의 action 코드 조각: 01 문서 8단계의 presentation/use-<base>-failure-action.ts 페이지 테스트
파일 업로드 (짝 백엔드 Fileserver) src/adapters/http/index.ts의 createFileserverUploadClient (POST /v1/files) 없음 (기능 예제). 조립은 02 결정표 7절 tests/integration/fileserver-upload.test.ts

서버 상태

패턴 정의 예제 검사
쿼리 바인딩 src/contracts/server-state.ts의 bindQuery, src/presentation/adapters/query/application-query.ts 생성 뼈대 presentation/use-<base>-items.ts profile ID (실행 때). owner·operationId는 읽는 곳이 없는 @deprecated 칸이라 적지 않는다
무효화 topic src/contracts/query-invalidation.ts 생성 뼈대 계약 invalidation 조립(중복, 고아 topic)
멱등 키 쓰기 V3 retrySemantics: "KEYED", commandRecovery, 뮤테이션 정책(src/contracts/server-state.ts의 commandMutationIdentity로 operation ID와 키 여부를 descriptor에서 받는다) 쓰기 slice --keyed(contracts/<base>-contract-contribution.ts, presentation/use-<base>-create.ts) 계약 조립(복구 descriptor 필수), 타입(descriptor 상수 이름, 손으로 적은 operation ID는 MutationOperationId가 아니다), 기능 테스트
결과 불명 화면 src/presentation/components/async-surface.tsx의 onReconcileUnknownEffect, onResendUnknownEffect. 폼으로 저장하면 아래 「폼」 행의 FormSaveFeedback이 이 둘을 잇는다 쓰기 slice presentation/<base>-create-page.tsx 기능 테스트(쓰기 slice는 <base>-create-page.test.tsx), tests/component/form-foundation.test.tsx
수정·삭제 명령 같은 V3 계약 (PUT, PATCH, DELETE) 없음 (쓰기 slice는 작성 명령만 만든다) —
낙관적 갱신 useApplicationMutation의 optimistic 옵션 (application-query.ts) 없음 런타임 테스트만
페이지 넘김 src/adapters/query-cache/index.ts의 createCursorPaginationRuntime 없음 (생성 뼈대 목록은 첫 페이지와 meta.page.total만 읽는다) 런타임 테스트만
로컬 저장(IndexedDB) recipes/frontend-capabilities/indexeddb-feature-capability.ts + product-composition.ts tests/fixtures/indexeddb-consumer/ (시험이 조립하는 소비자 fixture, 기능 폴더 모양) 계약 테스트

화면

패턴 정의 예제 검사
페이지 템플릿 src/presentation/templates/page-templates.tsx 생성 뼈대 CollectionPage, 쓰기 slice DetailPage·FormPage page-templates-own-layout-only
비동기 상태 화면 src/presentation/components/async-surface.tsx의 AsyncSurface 생성 뼈대 목록 페이지 페이지 테스트
폼 src/presentation/forms/use-app-form.ts의 useAppForm. mutation으로 저장하는 폼은 mutation 옵션을 주고 피드백 자리에 FormSaveFeedback(src/presentation/forms/form-components.tsx)을 둔다. 결과 불명 동안 새 저장 막기, 「변경됨으로 확인」, 같은 키 재전송, 다른 저장이 도는 동안의 표시, 마운트된 동안만 저장 뒤 이동(onSaved, FormSaveFeedback의 onConfirmed)을 폼이 맡는다 쓰기 slice presentation/<base>-form.ts와 <base>-create-page.tsx 페이지 테스트(서버 필드 오류, 이탈 확인), tests/component/form-foundation.test.tsx
화면 문구 src/presentation/i18n/index.ts, 기능 문구 catalog 생성 뼈대 contracts/<base>-message-catalog.ts lint(문구 literal), check:i18n(ko-KR·en-US 키)
권한 분기 라우트 access, 서버 403 → 실패 코드 조각: 01 문서 10단계의 403 페이지 테스트 tests/features/<id>/<base>-forbidden.test.tsx 가드 테스트. 역할·권한 힌트 예제는 없음

테스트

패턴 정의 예제 검사
응답 시나리오 tests/mocks/handlers/http-scenarios.ts의 createHttpScenarioHandler 생성 뼈대 페이지 테스트 test:coverage
보낸 요청(헤더·본문) 확인 MSW setupServer().events.on("request:start") 01 문서 10단계의 짧은 예. 핸들러에서 모으는 방법은 쓰기 slice --keyed의 tests/features/<id>/<base>-create-page.test.tsx test:coverage
같은 멱등 키 재전송 시나리오 in-flight-409 + 위 요청 모으기 01 문서 10단계 test:coverage

관측

패턴 정의 예제 검사
기능 telemetry src/platform/telemetry/telemetry-port.ts의 TelemetryPort, failOpenTelemetryPort 생성 뼈대 application/<base>-feature-api.ts 기능 테스트

같은 이름의 다른 타입 src/application/ports/telemetry-port.ts의 TelemetryPort는 기능에서 쓰지 않는다.

기능 사이

패턴 정의 예제 검사
기능 간 협력 금지 규칙만 있다 없음 check:architecture (features-do-not-import-other-features)

두 기능이 같은 것을 써야 하면 기능끼리 import하지 않는다. 공유할 것은 src/contracts나 src/application처럼 기능 밖 공유 폴더에 둘 수 있는지 먼저 본다. 공유 경로를 안내하는 예제는 없다.