From 374af98640cf55c7b15e6ba2fcb32ace98b40ddc Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 12 Nov 2026 07:04:36 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=EB=B2=88=EC=97=AD=ED=95=98=EB=A9=B0=20?= =?UTF-8?q?=EC=B0=BE=EC=9D=80=20=EB=82=A1=EC=9D=80=20=EC=84=9C=EC=88=A0?= =?UTF-8?q?=EC=9D=84=20=EC=BD=94=EB=93=9C=C2=B7=EC=84=A4=EC=A0=95=EC=97=90?= =?UTF-8?q?=20=EB=A7=9E=EC=B6=98=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 살아 있는 문서를 옮길 때 뜻을 바꾸지 않는다는 규칙 때문에 남겨 둔 낡은 서술이 있다. - contract-ownership: 계약 파일 「39개」. 지금 src/contracts의 .ts는 44개다. - capability-consumer-experience: Local Draft를 「두 번째 구체 소비자」, 「두 feature」라고 부른다. 지금은 제품 feature가 아니라 테스트 fixture (tests/fixtures/indexeddb-consumer)다. - static-delivery: initialJavascript.files가 「예시 feature 기준」이라고 한다. feature-shape-ceilings.json은 feature가 없는 지금 템플릿 빌드라고 적는다. - .dependency-cruiser.json:254 주석이 번호 없는 layers.md의 「§4」를 가리킨다. - runbook 문서 제목 셋이 runbooks.json title과 다르다. FE-RB-002는 영어 원문부터 manifest가 빠져 있었고, 001·003은 번역에서 갈라졌다. - ci-quality-gates: zod 행의 고친 버전은 4.6.6인데 이유 칸은 4.6.7을 말한다. 4.6.7은 올렸을 때 잰 버전이다(26ca2fdb 원문 "4.6.7 also adds"). - 같은 문서 FE-GATE-016 문단 끝 두 문장은 원래 runbook record 고정 경로 문단의 것이다(6c52cdb9 원문). 폐기 문장 뒤로 밀려 뜻이 끊겼다. 고른 방법: 숫자는 옮겨 적지 않고 정본(src/contracts/)을 가리킨다. Local Draft는 fixture라고 쓰고, 편의 프로필을 들일 조건을 「IndexedDB를 쓰는 제품 feature」로 좁힌다. 절 번호는 절 이름으로, 문서 제목은 등록부 title로 맞춘다. zod는 「고친 버전 이상으로 올리면」으로 쓰고 잰 버전과 날짜를 괄호에 둔다. 두 문장은 원래 문단으로 옮긴다. 위험: zod 7 KB는 다시 재지 않았다(2026-11-04 측정값 그대로). cruiser 주석은 check:architecture 위반 메시지의 why 줄에 나온다. 이 주석을 비교하는 시험은 없다. 검증: 각 사실을 git ls-files, feature-shape-ceilings.json, runbooks.json, layers.md 절 제목, 원문 커밋으로 확인했다. 문서 검사와 관련 시험은 desktop에서 돌린다. --- .dependency-cruiser.json | 2 +- docs/architecture/capability-consumer-experience.md | 7 ++++--- docs/architecture/contract-ownership.md | 4 ++-- docs/architecture/static-delivery.md | 2 +- docs/operations/ci-quality-gates.md | 10 +++++----- docs/runbooks/FE-RB-001.md | 2 +- docs/runbooks/FE-RB-002.md | 2 +- docs/runbooks/FE-RB-003.md | 2 +- 8 files changed, 16 insertions(+), 15 deletions(-) diff --git a/.dependency-cruiser.json b/.dependency-cruiser.json index 81abe1f7..7621ddf7 100644 --- a/.dependency-cruiser.json +++ b/.dependency-cruiser.json @@ -251,7 +251,7 @@ }, { "name": "adapters-do-not-know-other-concrete-adapters", - "comment": "docs/architecture/layers.md §4: a concrete adapter never depends on another concrete adapter. The adapter kernel is shared on purpose and any adapter may import it: src/adapters/platform/** (shared mechanisms only: clock, abort primitive, capacity guard, IndexedDB connection and transaction, Retry-After, JSON member scanner; plus two bootstrap-only services, see layers.md), src/adapters/browser-file-storage/result.ts (browser-data result helpers) and src/adapters/cross-context-invalidation/index.ts (the cross-context invalidation transport and its types). Owner: frontend-platform. No new file-level exception is added here; a new shared primitive goes into src/adapters/platform/.", + "comment": "docs/architecture/layers.md, section \"adapter kernel\": a concrete adapter never depends on another concrete adapter. The adapter kernel is shared on purpose and any adapter may import it: src/adapters/platform/** (shared mechanisms only: clock, abort primitive, capacity guard, IndexedDB connection and transaction, Retry-After, JSON member scanner; plus two bootstrap-only services, see layers.md), src/adapters/browser-file-storage/result.ts (browser-data result helpers) and src/adapters/cross-context-invalidation/index.ts (the cross-context invalidation transport and its types). Owner: frontend-platform. No new file-level exception is added here; a new shared primitive goes into src/adapters/platform/.", "severity": "error", "from": { "path": "^src/adapters/([^/]+)/" diff --git a/docs/architecture/capability-consumer-experience.md b/docs/architecture/capability-consumer-experience.md index 8711e45e..1d5f65ff 100644 --- a/docs/architecture/capability-consumer-experience.md +++ b/docs/architecture/capability-consumer-experience.md @@ -111,14 +111,15 @@ Local Draft 소비자가 아직 `src/features/` 아래 있을 때 잰 값(09-12) - 내구성, 스케줄링, 관측 이 복잡함은 feature가 아니라 조립·플랫폼 경계에 둔다. -Local Draft 세로 slice는 이제 두 번째 구체 소비자다. +Local Draft 세로 slice는 이 repository port를 feature 모양으로 쓰는 구체 소비자다. +다만 제품 feature가 아니라 테스트 fixture(`tests/fixtures/indexeddb-consumer`)다. 이 소비자는 안정된 연결 지점(seam)이 타입이 있는 repository provider와, feature가 소유한 repository 식별자라는 것을 확인한다. dataset 범위, 보존, 마이그레이션, codec, 수명 주기 권한 설정을 만능 `create...Repository` factory 하나로 안전하게 합칠 수 있다는 것은 보여 주지 **않는다**. -그래서 편의 프로필은 IndexedDB를 쓰는 다른 제품 feature가 같은 인프라 정책을 되풀이한 뒤에만 들인다. -두 feature가 같은 repository port를 쓴다는 이유만으로 들이지 않는다. +그래서 편의 프로필은 IndexedDB를 쓰는 제품 feature가 생기고, 그 feature들이 같은 인프라 정책을 되풀이한 뒤에만 들인다. +여러 소비자가 같은 repository port를 쓴다는 이유만으로 들이지 않는다. ## 소비자 품질 검토 체크리스트 diff --git a/docs/architecture/contract-ownership.md b/docs/architecture/contract-ownership.md index c36b2a09..5c508585 100644 --- a/docs/architecture/contract-ownership.md +++ b/docs/architecture/contract-ownership.md @@ -39,7 +39,7 @@ bootstrap, presentation, application 모듈을 import하지 못하게 막는다. ## 감사 결과 -2026년 9월 아키텍처 리뷰를 계기로 계약 파일 39개 전체의 import 그래프를 감사했다. +2026년 9월 아키텍처 리뷰를 계기로 그때 `src/contracts`에 있던 계약 파일 전체의 import 그래프를 감사했다. 지금 파일 목록은 `src/contracts/`가 정본이다. ### capability 소유 계약을 옮김 @@ -112,4 +112,4 @@ runtime에 설치됐다는 사실을 message 소유로 보지 않는다. - 같은 정의가 필요한 빌드·release·runtime wire 기준이 없다. - 정의를 그 owner로 옮겨도 안쪽 방향 의존성 규칙을 어기지 않는다. -39라는 숫자를 줄이려고 계약을 옮기지 않는다. 목표는 디렉터리를 작게 하는 것이 아니라 소유를 분명히 하는 것이다. +계약 파일 수를 줄이려고 계약을 옮기지 않는다. 목표는 디렉터리를 작게 하는 것이 아니라 소유를 분명히 하는 것이다. diff --git a/docs/architecture/static-delivery.md b/docs/architecture/static-delivery.md index 289c0b82..74ed06e8 100644 --- a/docs/architecture/static-delivery.md +++ b/docs/architecture/static-delivery.md @@ -44,7 +44,7 @@ rollback은 이전 불변 release의 HTML·asset·config·API·manifest 묶음 미리 불러온다(preload). 몇 개까지 허용할지는 `config/performance/budgets.json`의 `initialJsFiles`가 정한다. 지금 개수는 `config/scale/feature-shape-ceilings.json`의 `initialJavascript.files`이고, 이 -값은 예시 feature를 기준으로 한다. HTTP/1.1에서는 host마다 연결이 여섯 개라 +값은 feature가 없는 지금 템플릿 빌드에서 잰 것이다. HTTP/1.1에서는 host마다 연결이 여섯 개라 파일이 줄을 선다. 그래서 Fast 3G에서 첫 화면이 초기 chunk를 묶었을 때보다 약 1초 늦게 떴다(2026-11-03). HTTP/2에서는 차이가 100 ms 미만이었다. 그래서 템플릿은 chunk를 나눈 채로 둔다. HTTP/1.1로만 서빙할 수 있는 제품은 diff --git a/docs/operations/ci-quality-gates.md b/docs/operations/ci-quality-gates.md index 2dcc4a8a..d90f052b 100644 --- a/docs/operations/ci-quality-gates.md +++ b/docs/operations/ci-quality-gates.md @@ -333,7 +333,9 @@ release 증거는 다음 release 승격까지, drill 증거는 다음 production 증거는 집계까지 보관한다. runbook job은 고정 경로 `artifacts/runbooks//record.json`에 쓴다. 바뀌는 -release identity는 record 안에 저장한다. +release identity는 record 안에 저장한다. 그래서 게이트 증거를 찾는 일이 `RELEASE_ID`의 +slash나 그 밖의 provider별 문자에 영향을 받지 않는다. 그러면서도 workflow 산출물은 각자 +자기 run 범위에 남는다. runbook drill(`drill:runbook`, FE-GATE-021..025)은 판정마다 `PASS`, `FAIL`, `UNVERIFIED` 중 하나로 기록한다(`scripts/drill-runbook.ts`, record schema는 @@ -411,9 +413,7 @@ drill은 `FAIL`(exit 1)이다. 그렇지 않고 `UNVERIFIED`가 하나라도 있 production 단계는 닫히지 않는다. 의도한 결과다. 로컬 drill은 승격한 release를 rollback할 수 있다는 것을 보여 줄 수 없다. FE-GATE-016(`rollback-drill`)은 FE-GATE-025와 같은 FE-RB-005 drill을 돌렸으므로 폐기했다(`scripts/contracts/ci-gates.ts`의 -`RETIRED_GATE_IDS`). 이렇게 하면 게이트 증거를 찾는 일이 `RELEASE_ID`의 slash나 그 밖의 -provider별 문자에 영향을 받지 않는다. 그러면서도 workflow 산출물은 각자 자기 run 범위에 -남는다. +`RETIRED_GATE_IDS`). 브라우저를 쓰는 merge 게이트는 버전을 고정한 Chromium, Firefox, WebKit 엔진을 설치해 실행한다. 그래서 route 동작, reflow, 기본 dialog 동작, theme 유지, 자동 접근성 검사는 @@ -522,7 +522,7 @@ nanoid, source-map-js)은 선언한 범위 안에서 업데이트해서 없어 | Advisory | 패키지 | 고친 버전 | 아직 업데이트하지 않은 이유 | |---|---|---|---| -| GHSA-mrhx-c7xc-m3w5 (high) | `zod`(production. 지금 버전은 `package.json`) | 4.6.6 | production 직접 의존성을 올리려면 `config/security/dependency-change-evidence.json` 항목이 필요하고, 그 항목의 reviewer는 owner가 아니어야 한다. 4.6.7은 초기 JavaScript를 gzip으로 약 7 KB 늘려 번들 예산을 넘는다. 그래서 업데이트에는 예산 결정도 필요하다. 앱은 HTTP 본문을 바이트 상한을 두고 읽는다. 그래서 이 advisory가 필요로 하는 큰 collection 입력이 좁아진다(리뷰 추정) | +| GHSA-mrhx-c7xc-m3w5 (high) | `zod`(production. 지금 버전은 `package.json`) | 4.6.6 | production 직접 의존성을 올리려면 `config/security/dependency-change-evidence.json` 항목이 필요하고, 그 항목의 reviewer는 owner가 아니어야 한다. 고친 버전 이상으로 올리면 초기 JavaScript가 gzip으로 약 7 KB 늘어 번들 예산을 넘는다(2026-11-04에 4.6.7로 잰 값). 그래서 업데이트에는 예산 결정도 필요하다. 앱은 HTTP 본문을 바이트 상한을 두고 읽는다. 그래서 이 advisory가 필요로 하는 큰 collection 입력이 좁아진다(리뷰 추정) | | GHSA-qwww-vcr4-c8h2 (high) | `react-router`, `react-router-dom`을 거쳐 들어옴(production. 지금 버전은 `pnpm-lock.yaml`) | 7.18.2 | 같은 evidence 규칙을 따른다. 이 advisory는 RSC 모드에 관한 것이다. browser router를 쓰는 이 SPA는 RSC 모드를 쓰지 않는다(리뷰 추정, 확인하지 않음). 7.18.5는 초기 JavaScript를 약 470 B 늘린다 | 두 provider role은 서로 다른 key ID뿐 아니라 canonical DER-SPKI public-key bytes도 diff --git a/docs/runbooks/FE-RB-001.md b/docs/runbooks/FE-RB-001.md index 16f7387e..d152de69 100644 --- a/docs/runbooks/FE-RB-001.md +++ b/docs/runbooks/FE-RB-001.md @@ -1,4 +1,4 @@ -# FE-RB-001 — 부트 설정 실패 +# FE-RB-001 — boot 설정 실패 `BOOT_CONFIG_FAILURE`가 나고, 한 번만 허용된 재요청(refetch)도 실패하면 이 runbook을 시작한다. 제품 route를 mount하지 않고 안전한 지원 화면(support diff --git a/docs/runbooks/FE-RB-002.md b/docs/runbooks/FE-RB-002.md index a0342e5b..3c8310e0 100644 --- a/docs/runbooks/FE-RB-002.md +++ b/docs/runbooks/FE-RB-002.md @@ -1,4 +1,4 @@ -# FE-RB-002 — chunk 또는 배포 불일치 +# FE-RB-002 — chunk·manifest·배포 불일치 `CHUNK_LOAD_FAILURE`, `RELEASE_MANIFEST_FAILURE`, `DEPLOY_MISMATCH` 중 하나가 나면 시작한다. 저장하지 않은 상태(dirty state)를 잃을 수 있으면 경고한다. diff --git a/docs/runbooks/FE-RB-003.md b/docs/runbooks/FE-RB-003.md index 27634fcc..870c7e85 100644 --- a/docs/runbooks/FE-RB-003.md +++ b/docs/runbooks/FE-RB-003.md @@ -1,4 +1,4 @@ -# FE-RB-003 — 백엔드 API 품질 저하 +# FE-RB-003 — 백엔드 API 저하 다음 중 하나면 시작한다. 더 재시도하지 않는(terminal) 네트워크·시간 초과·5xx 실패가 최근 5분 이동 구간(rolling)의 기준치를 넘는다. 또는 `SCHEMA_MISMATCH`가