chore: sync the frontend template from ebea300 to af3d8e6
Carries 359 template commits, tag v0.2.0 plus one documentation commit: the generator-built feature index with its app, bounded-context and feature declarations, the src/platform kernel and scale tooling, the 2026-09-24 src review fixes, and the 2026-09-25 maturity review round with its CHANGELOG [보안]/[계약] rows. 691 of the 824 template paths are applied, 85 of them merged with product changes; 127 are not carried. Product identity is unchanged: name, version 0.1.0, routes, design and the TechLog domain. Three decisions worth naming. TechLog stays composed directly, as the last two syncs recorded; its directory carries a NOT_INSTALLED marker that says so, and every installed-* composer takes the template's projection with TechLog added on top. The reference sample is no longer installed: the template now installs a feature only through feature-module.ts and context-routes.ts, which load the screens this product deleted, so its three operations, six schemas and one topic leave the registries, recorded as registry change evidence. And AppRouter mounts the platform and TechLog routes only; the template's bounded-context route gateway waits for a generator-installed feature. Required fixes: readSubject on the BFF session owner (without it every HTTP Studio session would close as integration-failed), zod through the facade in nine TechLog files, noUnusedLocals, and public/config.json written out to match the local profile. Derived baselines were recomputed after reproducing both sides' values: CI contract 101 commands / 106 references / 141 artifacts, gate shape c9adcf85; registry approval 2dc6c3a3; the runtime config schema baseline equals the schema at8210d48. Verified here: types, lint, architecture, adapter inventory, CI contract, i18n, design system, diagnostics, browser security, dev release manifest, TechLog contract and build pass; 220 component, 155 integration, 15 contract, 418 TechLog, 43 reference-feature, 18 recipe and 46 release-coherence tests pass, and 2381 of 2383 unit tests. Reproduced at8210d48first and unchanged: check:registries (byte-identical), test:runtime-schema, verify:documentation. Brought by the template and escalated rather than suppressed: check:request-fanout on TechLog's cursor pagination, check:remediation-ledger (fails upstream too), the shared-chunk hash test, and the registry-dependent sample removal and second-feature tests. Playwright suites were not run. Full record, the five open questions and the follow-ups in docs/operations/template-sync-2026-09-29.md. (cherry picked from commit b2170cf265dea45dc9cc05d3c61e627e97f31cdb)
This commit is contained in:
@@ -50,7 +50,10 @@ architecture/security/type negative input으로 전환했다. 이는 7번 결정
|
||||
|
||||
- `check:types`는 app, Node scripts/config, tests project를 모두 검사한다.
|
||||
- TS invalid-call, invalid port, discriminated-union fixture는 실패해야 한다.
|
||||
- ESLint와 dependency-cruiser는 TS/TSX architecture fixture를 검사한다.
|
||||
- ESLint와 `check:architecture`의 import 그래프(`scripts/check-architecture.ts`)가
|
||||
TS/TSX architecture fixture를 검사한다. dependency-cruiser 18은 TypeScript 7을
|
||||
해석하지 못해 0개 모듈을 검사하고 통과했으므로 실행하지 않는다(리뷰 12-05).
|
||||
`.dependency-cruiser.json`은 이름만 남은 규칙 파일이고 그래프가 읽는다.
|
||||
- registry scanner는 TS registry의 required field, uniqueness와 reference를
|
||||
검증한다.
|
||||
- browser security gate는 TSX의 금지된 raw HTML fixture를 거절한다.
|
||||
|
||||
@@ -18,7 +18,8 @@ field orchestration까지 플랫폼 기본값으로 고정하게 된다.
|
||||
2. Zod presentation schema, application command mapper와 domain invariant는 서로
|
||||
다른 소유물로 유지한다.
|
||||
3. page와 feature는 `useAppForm`, `Form`, `FormField`, `ErrorSummary`,
|
||||
`mapValidationFailureToFields`, `useDirtyNavigationGuard`만 사용한다.
|
||||
`FormFailureStatus`, `mapValidationFailureToFields`, `useDirtyNavigationGuard`만
|
||||
사용한다.
|
||||
4. 422 details는 승인된 `path`와 `code`만 HTTP 경계에서 투영한다. backend
|
||||
message와 알 수 없는 field는 field에 전달하지 않고 안전한 form-level
|
||||
error로 이동한다.
|
||||
@@ -27,6 +28,16 @@ field orchestration까지 플랫폼 기본값으로 고정하게 된다.
|
||||
dirty 상태를 해제한다.
|
||||
7. `StandardPage`, `CollectionPage`, `DetailPage`, `FormPage`, `StatusPage`는
|
||||
layout과 state slot만 소유하며 application/query/HTTP를 import하지 않는다.
|
||||
8. (2026-09-25, 08-01) 입력 오류가 아닌 저장 실패는 ErrorSummary에 넣지 않는다.
|
||||
`useAppForm`은 `action: "reauth"`를 `reauth-required`, `FORBIDDEN`을 `forbidden`,
|
||||
`action: "retry"`를 `retry-later`로, 나머지 입력 외 실패를 `unavailable`로 구분하고
|
||||
그 실패를 `failure`로 낸다(F-10). 화면은
|
||||
`FormFailureStatus`로 문구와 행동(로그인·이동·다시 시도)을 보여 준다. 재로그인은
|
||||
입력을 지운다는 안내를 버튼 앞에 둔다(`src/presentation/forms/use-app-form.ts`,
|
||||
`form-components.tsx`).
|
||||
9. (2026-09-25, 03-01) 결과 불명 저장은 사용자가 "변경되지 않음"을 판정하지 않는다.
|
||||
`resendUnknown(mutation.resendUnknownEffect)`로 같은 intent·같은
|
||||
`Idempotency-Key`를 다시 보낸다(`src/presentation/adapters/query/application-query.ts`).
|
||||
|
||||
## React Hook Form 도입 조건
|
||||
|
||||
|
||||
@@ -38,9 +38,18 @@
|
||||
|
||||
## 경계와 검증
|
||||
|
||||
- 제품 코드는 `presentation/design-system/index`만 import한다.
|
||||
- design-system 검사기는 direct icon/headless import, deep import, raw palette,
|
||||
undefined token과 tooltip-only required information fixture를 거절한다.
|
||||
- 제품 코드는 `presentation/design-system/index`만 import한다. 예외는 규칙에
|
||||
이름으로 적는다. `presentation/components/ui/*.ts`는 아래 Rollback의 재수출
|
||||
facade이고, `presentation/templates/page-templates.tsx`는 index가 내보내지
|
||||
않는 `PaginationLandmarkContext`를 읽는다.
|
||||
- deep import와 direct icon import는 `check:architecture` 그래프 규칙
|
||||
`design-system-is-reached-through-its-index`, `icon-vendor-is-facade-only`
|
||||
(`.dependency-cruiser.json`)가 거절한다. 경로 해석이 끝난 간선을 보므로
|
||||
presentation 안의 상대 경로 import도 잡는다(리뷰 12-08). 음성 fixture는
|
||||
`tests/fixtures/architecture/dependency-graph/import-boundaries`다.
|
||||
- design-system 검사기(`scripts/check-design-system.ts`)는 headless vendor
|
||||
import, raw palette, undefined token과 tooltip-only required information
|
||||
fixture를 거절한다.
|
||||
- type negative fixture는 accessible name 없는 `IconButton`을 거절한다.
|
||||
- component test는 decorative icon, form control, Menu, Tabs, Drawer와 Toast를
|
||||
검증한다.
|
||||
|
||||
@@ -66,9 +66,15 @@ route/form/failure 의미 값
|
||||
|
||||
## 검증
|
||||
|
||||
- `check:i18n`은 catalog key와 placeholder parity, common UI의 한국어 literal,
|
||||
backend message JSX 렌더링과 raw HTML 사용을 검사한다.
|
||||
- `check:i18n:fixture`는 세 금지 사례를 실제로 거절해야 성공으로 인정된다.
|
||||
- `check:i18n`은 catalog key와 placeholder parity, 화면 코드의 한국어 literal,
|
||||
backend message JSX 렌더링과 raw HTML 사용을 검사한다. 검사 범위는 공통 UI
|
||||
디렉터리, `src/presentation/pages`, 모든 `src/features/*/presentation`이다.
|
||||
컴포넌트 갤러리 `src/presentation/examples`는 일부러 뺐다
|
||||
(`scripts/check-i18n.ts`의 `commonDirectories`, `featurePresentationDirectories`).
|
||||
- `check:i18n:fixture`는 같은 탐색 규칙을 `tests/fixtures/i18n/forbidden` 트리에
|
||||
돌린다. fixture 파일 하나라도 거절되지 않으면 종료 코드 2로 실패한다.
|
||||
- `tests/unit/i18n-contract.test.ts`는 `ERROR_REGISTRY`의 모든 `userMessageKey`가
|
||||
ko-KR·en-US catalog에 있는지 확인한다.
|
||||
- type negative fixture는 unknown key와 잘못된 parameter shape를 거절한다.
|
||||
- unit test는 fallback, alias, pseudo 확장, direction과 timezone/number/relative/
|
||||
list/plural/select의 결정성을 검증한다.
|
||||
|
||||
@@ -43,13 +43,17 @@ vendor 결정 전에는 안전한 기본값이 아니다.
|
||||
`createHttpObservationProjector`가 유일한 projection authority다. observation은
|
||||
arbitrary context map이 아니며 projector는 `route_id`, `operation_id`,
|
||||
`operation`, `outcome`, `error_kind`, `http_status_group`,
|
||||
`attempt_count_bucket`, `duration_bucket`만 사용한다. raw attempt count,
|
||||
`attempt_count_bucket`, `duration_bucket`만 사용한다. diagnostics에만
|
||||
`correlation_id`(서버가 돌려준 `x-correlation-id`, 없으면 실행이 보낸 요청 ID)를
|
||||
더한다. telemetry에는 넣지 않는다(03-03, `createHttpObservationProjector`). raw attempt count,
|
||||
duration, status, URL, intent, key, input identity와 내부 `terminalReason`은
|
||||
sink로 나가지 않는다. effect certainty가 운영상 필요해지면 `effect_certainty`
|
||||
key와 닫힌 value policy를 contract·fixture·이 ADR에 동시에 추가한 뒤에만
|
||||
전달한다.
|
||||
5-2. caller cancellation과 scope fence는 API failure가 아니다. diagnostics는 한
|
||||
번 남기고 `api.request.failed`는 발행하지 않는다.
|
||||
번 남기고 `api.request.failed`는 발행하지 않는다. 자격증명이 없어 한 번도
|
||||
보내지 않은 `UNAUTHENTICATED`(응답 status 없음)도 같다(03-07,
|
||||
`src/bootstrap/runtime-adapters.ts` `isTerminalNonAbortFailure`).
|
||||
5-3. `routeId`는 installed operation-executor 경계의 필수 입력이다. feature
|
||||
gateway가 소유한 low-cardinality route identity를 URL에서 재구성하지 않는다.
|
||||
6. `app.boot.failed`, `ui.render.failed`, `release.mismatch.detected`,
|
||||
@@ -72,6 +76,11 @@ vendor 결정 전에는 안전한 기본값이 아니다.
|
||||
아니거나 1 미만이거나 문서화된 ceiling(각각 `MAX_TELEMETRY_QUEUE`,
|
||||
`MAX_DIAGNOSTIC_ENTRIES` = 10,000)을 넘으면 `TypeError`로 거절한다. NaN/Infinity가
|
||||
조용히 eviction을 비활성화하는 경로를 남기지 않는다.
|
||||
7-5. (2026-09-25) 두 telemetry port는 collector 하나로 보낸다
|
||||
(`src/adapters/telemetry/telemetry-collector.ts`). collector는 본문을 60KiB 아래로
|
||||
나누고, 진행 중인 keepalive 본문 합이 64KiB를 넘으면 그 부분은 keepalive 없이
|
||||
보낸다(03-05). 조합 루트가 release manifest의 `buildId`·`releaseId`를 넘기면 모든
|
||||
이벤트에 `build_id`·`release_id`를 붙인다(13-11, `src/bootstrap/runtime-adapters.ts`).
|
||||
8. diagnostics와 telemetry failure는 제품 흐름, HTTP 결과, route transition,
|
||||
storage/cache fallback과 React error surface를 바꾸지 않는다.
|
||||
9. mount 전 bootstrap failure는 안전한 build/config/error kind만 별도 evidence로
|
||||
|
||||
@@ -255,15 +255,20 @@ reconnect는 capped full-jitter exponential backoff를 사용한다. base/max de
|
||||
max attempts와 max elapsed는 immutable registry/implementation ceiling으로
|
||||
제한한다.
|
||||
|
||||
- stable-open window 또는 valid heartbeat/event 뒤에만 attempt reset
|
||||
- valid heartbeat/event와 stable-open window를 둘 다 충족한 뒤에만 attempt와
|
||||
elapsed budget reset. session의 모든 종료 경로(server close, offline,
|
||||
`waitClosed` throw)에서 확인한다
|
||||
- valid server hint는 local delay보다 이른 retry를 금지하는 not-before bound
|
||||
- server hint가 implementation max/remaining elapsed budget을 넘으면 낮춰
|
||||
clamp하지 않고 degraded/stale로 종료
|
||||
- offline에서는 timer retry를 멈춤
|
||||
- offline에서는 timer retry를 멈춤. offline 대기 시간은 elapsed budget에 넣지
|
||||
않고 online 복귀 시 elapsed budget을 다시 시작한다. attempt 상한은 유지한다
|
||||
- auth expiry는 session owner single-flight recovery 한 번
|
||||
- forbidden/protocol/schema failure는 terminal
|
||||
- 외부 rate/provider failure는 exact bounded server not-before hint가 있을 때만
|
||||
retry하고, hint가 없으면 terminal
|
||||
- retry 여부는 transport가 보고한 `retryable`이 정한다. retryable 실패는 hint가
|
||||
없어도 bounded retry한다. hint가 꼭 필요한 실패(SSE `429`/`503`, WebSocket
|
||||
`OVERLOADED`)는 hint가 없으면 transport가 terminal로 보고한다. SSE
|
||||
`502`/`504`와 WebSocket `RESTART`·`NETWORK_LOST`는 hint 없이 bounded retry
|
||||
- retry budget 소진 뒤 declared Polling fallback 또는 stale UI
|
||||
- reconnect는 realtime coordinator, auth는 session owner, Poll cadence는 poll
|
||||
coordinator가 소유하고 Poll-bound HTTP/Query retry는 비활성
|
||||
@@ -456,7 +461,7 @@ push hint와 worker deadline을 제한한다. 제품 config는 더 작게만 설
|
||||
|
||||
2026-07-28 reference-runtime amendment로, RT-01~RT-04 source 전체를
|
||||
tree-shaking 없이 합성하는 optional-recipe gzip 예산을 40,000 bytes로
|
||||
고정한다. 이는 production bundle 허용량이 아니며 미선택 production asset의
|
||||
고정한다(2026-09-27 성숙도 리뷰 반영으로 40,900 bytes로 올림. 근거는 `config/recipes/frontend-capability-recipes.json` 변경 커밋). 이는 production bundle 허용량이 아니며 미선택 production asset의
|
||||
realtime module 허용량은 계속 0이다. SSE replay-open과 WebSocket
|
||||
`SUBSCRIBED`가 exact recovery checkpoint를 증명하고 common barrier가 확인될
|
||||
때까지 event admission을 막는 readiness gate는 attempt당 최대 30초다.
|
||||
|
||||
Reference in New Issue
Block a user