Files
clean-architecture-frontend…/docs/runbooks/FE-RB-001.md
T
DongHyeonka 374af98640 docs: 번역하며 찾은 낡은 서술을 코드·설정에 맞춘다
문제: 살아 있는 문서를 옮길 때 뜻을 바꾸지 않는다는 규칙 때문에 남겨
둔 낡은 서술이 있다.
- 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에서 돌린다.
2026-11-12 09:40:51 +09:00

2.2 KiB

FE-RB-001 — boot 설정 실패

BOOT_CONFIG_FAILURE가 나고, 한 번만 허용된 재요청(refetch)도 실패하면 이 runbook을 시작한다. 제품 route를 mount하지 않고 안전한 지원 화면(support shell)을 보여 준다. owner가 원인을 가르는(triage) 계획 목표 시간은 5분이다. 환경·설정 owner에서 release owner로 올린다(escalate).

깨끗한 세션에서 부트했을 때 제품 root가 mount되고, 설정 검증 증거가 통과하고, 부트 오류 telemetry가 다시 나오지 않을 때만 닫는다.

다시 빌드하지 않고 긴급 스위치 바꾸기

배포된 config.json에서 바꿔도 되는 것은 CAPABILITY_OVERRIDES와 FEATURE_OVERRIDES뿐이다. 모든 브라우저가 부트할 때 이 문서를 검증한다. 그래서 여기에 오타가 있으면 모든 사용자에게 이 runbook의 실패가 난다. 네 단계로 바꾼다.

  1. 배포된 config.json을 두 번 내려받는다. 하나는 deployed.json(손대지 않고 둔다), 다른 하나는 edited.json이다. edited.json에서 스위치만 바꾼다.
  2. 배포된 commit을 checkout한 곳에서 다음을 실행한다. RELEASE_TARGET=<environment> corepack pnpm check:release-admission --config /abs/edited.json --original /abs/deployed.json 절대 경로를 쓴다. pnpm이 이 명령을 repository root에서 실행하기 때문이다. 출력은 ADMITTED여야 한다. 이 명령은 schema 오류, target 규칙 위반, 두 스위치 말고 바뀐 필드를 모두 거부한다. 바뀐 필드에는 BUILD_ID와 RELEASE_ID도 들어간다.
  3. edited.json을 live 파일 옆에 올린다. 그다음 같은 파일 시스템 안에서 이름을 바꿔 config.json을 덮어쓴다. live 파일을 그 자리에서 고치지 않는다. 되돌릴 때는 같은 방법으로 deployed.json의 이름을 다시 바꾼다.
  4. 깨끗한 세션(새 브라우저 프로필)에서 부트하고 제품 root가 mount되는지 본다. 스위치는 다음 부트부터만 적용된다.

그러면 서빙되는 문서가 release 기록(checksums.txt, promotion된 archive)과 달라진다. release 로그에 이 변경을 적는다. 다음 빌드를 위해 프로필(config/runtime/<environment>.json)에도 넣는다.