docs(review): 개선 순서 2와 P2·P3 조치 현황, 건너뛴 것과 이유를 적는다
문제: 리뷰 README 13절은 개선 순서 1까지만 적혀 있었다. 밤사이 고친
ID와 커밋, 건너뛴 항목과 이유, 새로 찾은 결함, 예산 여유가 에이전트
보고에만 있었다. CHANGELOG 알려진 제한에는 이미 해결된 두 줄(규모
기준선이 15-01 전 측정, 좁은 화면 골든 미갱신)이 남아 있었고, 규모 근거
문장이 옛 수치를 적고 있었다.
방법: README 13.3~13.8에 개선 순서 2, 영역별 고친 ID와 커밋, 결정이
필요한 건너뛴 항목 20줄, 새 발견(여러 페이지 OPFS purge), 예산 여유,
마지막 게이트를 더했다. 영역 문서는 리뷰 시점 기록이라 고치지 않았다.
CHANGELOG는 해결된 두 줄을 지우고 OPFS purge 제한을 더했다.
feature-shape-ceilings.json의 Initial/Lazy JavaScript 수치를 9333595
측정에 맞췄다.
위험: 13.6의 OPFS purge 결함은 코드로만 확인했다(E2). 실행 재현은 없다.
검증: changelog-review-ids, feature-shape-growth, documentation-readiness,
deletable-history-documents 11/11 통과. verify:documentation PASS_SCOPED.
This commit is contained in:
+3
-4
@@ -68,7 +68,7 @@
|
||||
|
||||
### 그 밖의 수정
|
||||
|
||||
- 화면: 라이트 포커스 링 대비, oklab 색 혼합, 기본 버튼·현재 메뉴가 컴포넌트 토큰을 읽음(서비스가 토큰으로 브랜드를 바꿀 수 있다), `--font-sans`가 실제로 그려지는 시스템 글꼴, 테마·언어 선택 상자 폭, 예제 머리글의 반복 "예제" 라벨 삭제, 표 스크롤 영역 이름, 입력란 테두리가 `--field-border`를 읽음(대비 3:1 이상) (UI-01~UI-06, UI-08, 1101/12-01). `src/presentation/design-system/`, `src/presentation/styles/theme/`, `src/presentation/examples/`. 시각 골든은 `c0c5d9c`에서 다시 찍었다
|
||||
- 화면: 라이트 포커스 링 대비, oklab 색 혼합, 기본 버튼·현재 메뉴가 컴포넌트 토큰을 읽음(서비스가 토큰으로 브랜드를 바꿀 수 있다), `--font-sans`가 실제로 그려지는 시스템 글꼴, 테마·언어 선택 상자 폭, 예제 머리글의 반복 "예제" 라벨 삭제, 표 스크롤 영역 이름, 입력란 테두리가 `--field-border`를 읽음(대비 3:1 이상) (UI-01~UI-06, UI-08, 1101/12-01). `src/presentation/design-system/`, `src/presentation/styles/theme/`, `src/presentation/examples/`. 시각 골든은 `373b27b`에서 고정 글꼴로 다시 찍었다
|
||||
- 화면: 좁은 화면(48rem 미만)에서 머리글이 숨기던 테마 선택과 세션 상태를 메뉴 서랍에 둔다. 셸 문구가 DOM에 두 벌이라 페이지 전체에서 `getByText`로 찾는 테스트는 범위를 좁혀야 한다 (1101/08-01). `src/presentation/layouts/app-shell.tsx`, `src/presentation/styles/theme/`
|
||||
- 저장소: 진단 이벤트 `storage.operation.failed`에 실패 원인(`reason`)이 붙는다 (1101/05-02). lifecycle 리스너 주인 주석을 실제에 맞추고 테스트를 뒀다 (1101/05-03). OPFS purge가 객체를 못 지우면 완료와 chunk sweep을 보고하지 않는다 (0929/05-02). `src/adapters/storage/`, `src/adapters/platform/`
|
||||
- 운영: 배포된 `config.json`의 비상 스위치(`CAPABILITY_OVERRIDES`, `FEATURE_OVERRIDES`)를 바꿀 때 `check:release-admission --config <고친 사본> --original <배포된 원본>`으로 먼저 검사한다. 두 스위치 밖의 필드가 바뀌면 거절한다. 절차는 `docs/runbooks/FE-RB-001.md` (1101/13-05). `scripts/check-release-admission.ts`, `.env.example`
|
||||
@@ -79,14 +79,13 @@
|
||||
- HTTP·조회: 문제 응답 분류기 실패가 진단 reason `CLASSIFIER_FAILED`로 남는다 (1101/03-05). 어느 무효화 topic도 닿지 않는 조회 namespace를 진단으로 한 번 알린다 (1101/03-01)
|
||||
- 화면: 검색값만 바뀌면 포커스·스크롤·`route.changed`를 건드리지 않는다 (1101/08-02). h2·h3·h4 제목 크기·굵기 (1101/08-04), 한국어 단어 단위 줄바꿈 (1101/08-06), 상태 화면·오류 요약의 제목 수준 지정 (1101/08-05), 예제 화면의 `lang="ko-KR"` (1101/08-07), 폼 저장 실패와 결과 불명 화면의 지원 참조 (0929/08-04)
|
||||
- 진단: context·feature 오류 경계와 라우트 모듈 실패가 진단에 남고, 지원 참조가 `build:incident` 형식이다 (1101/09-09). REST 보안 프로필 오류가 operation과 깨진 조건을 말한다 (1101/16-03)
|
||||
- 테스트·운영 도구: guardian이 실패하면 stdin을 기다리지 않고 바로 끝난다 (G-1). SW e2e가 제품이 이미 켠 worker와 빌드가 만든 사전 캐시 목록을 쓴다 (0929/11-03, 0929/06-04). 이벤트 계약 검증이 실제 이벤트 행으로 고정됐다 (1101/10-01)
|
||||
- 테스트·운영 도구: guardian이 실패하면 stdin을 기다리지 않고 바로 끝난다 (G-1). SW e2e가 제품이 이미 켠 worker와 빌드가 만든 사전 캐시 목록을 쓴다 (0929/11-03, 0929/06-04). 이벤트 계약 검증이 실제 이벤트 행으로 고정됐다 (1101/10-01). 규모 측정 기준선을 1101/15-01 뒤 코드로 다시 쟀다. 측정용 기능 복사본은 외부 패키지를 고정하고 선언한다 (`9333595`, 1101/07-04). reference feature를 지워 설치 기능이 0개여도 타입 검사와 `create-application.ts` 커버리지가 통과한다 (`e4ace51`, 1101/15-01)
|
||||
|
||||
### 알려진 제한
|
||||
|
||||
- `config/contracts/registry-baseline.json`의 FE-REG-API·FE-REG-SCHEMA `source`가 1101/15-01 뒤에도 `src/features/installed-feature-contracts.ts`를 가리킨다. 승인 digest가 걸려 있어 소유자가 재승인할 때 고친다. `check:registries`는 통과한다.
|
||||
- 규모 기준선 `config/scale/feature-shape-growth.json`은 1101/15-01 전 측정이다. 그 뒤 수치는 `config/scale/feature-shape-ceilings.json`의 Initial JavaScript 항목에 있다.
|
||||
- 0929/03-01의 백엔드 계약(처리 중 재전송의 status·code, 충돌 409 code 목록)은 이 repo에서 끝나지 않았다.
|
||||
- 좁은 화면 서랍(1101/08-01)의 시각 골든 `app-shell-compact-pseudo-drawer.png`는 이 절을 쓸 때 다시 찍지 않았다.
|
||||
- OPFS의 LOGOUT·ACCOUNT_DELETION purge가 두 페이지 이상이면, 다 지워도 `moreObjectsAvailable: true`를 보고하고 chunk sweep을 하지 않는다. 한 번 더 부르면 끝난다. 이 브랜치 전부터 있던 동작이고 코드로만 확인했다 (1101 README 13.6).
|
||||
- 실제 Gitea runner에서는 돌리지 않았다(SPEC U-1). 시각 테스트의 글꼴 패키지 설치 단계는 workflow에 넣지 않았다. nginx 예시는 실행해 보지 않았다.
|
||||
|
||||
## 0.2.0 — 태그 `v0.2.0` (2026-09-27)
|
||||
|
||||
@@ -21,13 +21,13 @@
|
||||
},
|
||||
{
|
||||
"axis": "Initial JavaScript",
|
||||
"verified": "15-01: only each feature's declaration (route table, messages, invalidation identities) loads at boot; its runtime half loads with its routes. Baseline: 202,509 B with no copy, about 610 B and no extra file per copy (218,010 B at 25, 263,119 B at 100; before 15-01: +3,922 B per copy). tests/unit/feature-shape-growth.test.ts keeps one copy at or under 1 KiB",
|
||||
"verified": "15-01: only each feature's declaration (route table, messages, invalidation identities) loads at boot; its runtime half loads with its routes. Baseline: 203,816 B with no copy, about 610-630 B and no extra file per copy (219,508 B at 25, 264,841 B at 100; before 15-01: +3,922 B per copy). tests/unit/feature-shape-growth.test.ts keeps one copy at or under 1 KiB",
|
||||
"condition": "Same; the feature-declarations and feature-platform chunk groups in vite.config.ts",
|
||||
"notVerified": "The initial budget (204,800 B, config/performance/budgets.json) leaves 2,291 B over the baseline's 202,509 B, so about three more reference-shaped features fit at about 610 B each: the platform itself is 98.9% of it"
|
||||
},
|
||||
{
|
||||
"axis": "Lazy JavaScript",
|
||||
"verified": "About 8.3 KB gzip and eight files per feature, every file far below the 120 KiB lazy-chunk budget",
|
||||
"verified": "About 8.5 KB gzip and eight files per feature, every file far below the 120 KiB lazy-chunk budget",
|
||||
"condition": "Same",
|
||||
"notVerified": "Download cost of many lazy files"
|
||||
},
|
||||
|
||||
@@ -307,7 +307,7 @@
|
||||
| [16-05](16-structure-patterns.md) | Low | P3 | 구조적 위험 | 24, 23, 4, 2, 9, 27 | 같은 개념이 두 폴더에 비슷한 이름으로 있다 — 기능 오류 경계 두 벌이 겹쳐 쌓이고, `TelemetryPort` 타입이 둘이고, 소비자 없는 폐기 사본이 남아 있다 |
|
||||
| [16-06](16-structure-patterns.md) | Low | P3 | 개선 제안 | 2, 4, 22, 9 | 기능 `contracts/` 폴더가 와이어 계약·화면 문구·뷰 모델을 함께 담아 기능 코드의 46%를 차지한다 |
|
||||
|
||||
## 13. 조치 현황 (개선 순서 1)
|
||||
## 13. 조치 현황 (개선 순서 1·2, P2·P3)
|
||||
|
||||
리뷰 뒤 같은 브랜치에서 개선 순서 1을 고쳤다. 각 항목은 고치기 전에 실패하는 테스트를 먼저 넣었다. 리뷰 문서(영역 문서)는 리뷰 시점 기록이라 고치지 않았다.
|
||||
|
||||
@@ -324,6 +324,8 @@
|
||||
|
||||
### 13.1 남은 것 — `test:system` cgroup 테스트의 표본 경쟁 (11-01 후반)
|
||||
|
||||
> 해결: 아래 "방향"대로 다시 설계했다(`0536891`, `a6560be`, 13.3). 이 절은 그 전 기록이다.
|
||||
|
||||
- 증상: `systemd-run --scope`는 scope로 옮긴 뒤 같은 PID에서 wrapper로 exec한다. prlimit도 sh, provider로 같은 PID에서 바뀐다. 5 ms 표본은 이 짧은 단계를 자주 놓친다. 그래서 "systemd-run 1개"(819행), "guardian 1개"(820행) 단언이 간헐적으로 실패한다.
|
||||
- 시도하고 되돌린 것: (1) fork 직후 부모와 같은 argv를 기록하지 않기, (2) systemd-run 단언을 "scope 안에서 wrapper가 된 직접 자식 1개"로 바꾸기, (3) PID별 argv 이력 보존. (3)은 837행 "인프라 argv에 provider 명령이 없다"의 뜻을 바꿔 20회 모두 실패했다. 단언 하나를 고치면 다른 단언의 의미가 바뀐다.
|
||||
- 방향: `/proc` 표본 대신 각 단계(supervisor, guardian, scope wrapper)가 자기 PID와 argv를 실행 증거 파일에 직접 남기게 하고, 테스트는 그 기록을 읽는다. 별도 작업으로 다룬다.
|
||||
@@ -331,3 +333,78 @@
|
||||
### 13.2 이번 조치 뒤 게이트 (`4d27b20`, 오케스트레이터)
|
||||
|
||||
`check:architecture`, `check:types`, `lint`, unit 2,380건, component 211건, integration 155건, contract 15건, runtime-schema 56건, `verify:documentation`, `check:adapter-inventory`, `check:ci`, `check:design-system`, `check:i18n` 통과. `test:system`은 13.1의 간헐 실패 외 111건 통과. 관련 e2e(reference form·save·route, ui-gallery, design-system-interactions, i18n, accessibility) 3엔진 96/96 통과. 시각 회귀 5/5는 기존 골든 그대로 통과(입력란 테두리 변화가 허용치 안이다 — 11 영역이 지적한 시각 검사의 둔감함).
|
||||
|
||||
### 13.3 개선 순서 2 (2026-11-01 밤)
|
||||
|
||||
| ID | 상태 | 커밋 | 막는 테스트·검증 |
|
||||
|---|---|---|---|
|
||||
| 15-01 | 충족 | `298201f`, `f41e3d5`, `e4ace51` | 기능 1개를 더할 때 초기 JS +3,934 B → +741 B. `tests/unit/feature-shape-growth.test.ts`가 1 KiB 이하를 지킨다. 번들 검사를 merge 단계로 옮겼다. 설치 기능 0개(샘플 제거 드릴)에서도 타입 검사와 커버리지가 통과한다. **BREAKING**: 기능은 선언과 실행부(`feature-runtime.ts`)로 나뉜다. 이행 순서는 CHANGELOG 미출시 절 첫 항목 |
|
||||
| 08-01 | 충족 | `d2a882f` | 48rem 미만에서 테마 선택과 세션 상태가 메뉴 서랍에 있다. 좁은 화면 골든은 `373b27b`에서 다시 찍었다 |
|
||||
| 11-02 | 충족 | `08b5ccc` | `fonts.conf`로 세 글꼴 폴더만 보이게 하고 시각 테스트 전에 검사한다 |
|
||||
| 0929/10-01 | 충족 | `c03bf02`, `5826300`, `c862004` | Testing Library 대기 기한을 `tests/setup.ts` 한 곳에서 정한다. 극한 규모 테스트는 CPU와 무관한 비교만 단언한다 |
|
||||
| 11-01 (후반) | 충족 | `0536891`, `a6560be` | 13.1의 표본 경쟁. 실행 단계가 자기 PID·argv를 실행 기록에 남기고 테스트가 그 기록을 읽는다. 20/20 통과 |
|
||||
|
||||
### 13.4 P2·P3 조치 (2026-11-01 밤)
|
||||
|
||||
영역 에이전트 10개가 각자 worktree에서 고치고, 오케스트레이터가 이 브랜치로 cherry-pick했다. 각 커밋 본문에 수정 전 실패(RED)와 수정 뒤 통과(GREEN)를 적었다.
|
||||
|
||||
| 영역 | 고친 ID (커밋) |
|
||||
|---|---|
|
||||
| 01·02 | 01-01 `95e4445`, 01-04 `6b7b53f`, 02-01 `8ad11c0`, 02-03 `3bb1829`, 02-05 `5b96529`, 0929/01-01 `9142390`(부분), 0929/02-01 `aedd328` |
|
||||
| 03 | 03-01 `ffb6782`, 03-02 `4da0466`(0929/03-05 포함), 03-05 `f8a492a` |
|
||||
| 04·06 | 04-01 `3fe28de`, 04-02 `5b3f5b0`(문서만), 06-01 `c67edd2`, 06-02 `b28e290`, 0929/06-02 `85d55e0`, 0929/06-04 `96a4f68` |
|
||||
| 05 | 05-01 `e98a980`, 05-02 `12c23fe`, 05-03 `49f7cde`, 05-05 `cc011bc`, 0929/05-02 `68e88b0` |
|
||||
| 07 | 07-01 `fc303d8`, 07-02 `3c31576`, 07-04 `c063389`, 07-06 `32da8a4`, 0929/07-01 `5e6be9a`·`65ea208`, 0929/07-02 `82c9e59` |
|
||||
| 08 | 08-02 `d0f3993`, 08-04 `6fc77bb`, 08-05 `dda153b`, 08-06 `8ed5beb`, 08-07 `ad73e56`, 08-09 `b9a8a1a`, 0929/08-04 `e54fbf2` |
|
||||
| 09·16 | 09-06 `7139c7c`(부분), 09-07 `48a4074`, 09-09 `de48db2`, 16-03 `abf3ce5`(부분) |
|
||||
| 10·11 | 10-01 `dddf635`, 10-02 `ba98048`, 10-04 `95e7d11`, 11-03 `5ce3db9`, 11-04 `1604ef1`, 0929/11-03 `37e5f9d`, 0929/11-05 `41e7962`·`9333595` |
|
||||
| 12 | 12-02 `c0451f9`, 12-04 `e714c0d`(부분), 12-05 `98b9682`(부분), G-1 `3c175a5` |
|
||||
| 13·14·15 | 13-04 `629c8f0`, 13-05 `b3af26f`, 14-02 `003832b`, 14-06 `f13ed7b`, 15-02 `8c7bcda`, 15-05 `e0c2a91` |
|
||||
|
||||
합친 뒤 시각 골든 5장을 고정 글꼴로 다시 찍었다(`373b27b`). 시각 회귀 허용치는 절대 픽셀 50이다(11-03).
|
||||
|
||||
### 13.5 건너뛴 것 — 결정이 필요하다
|
||||
|
||||
| ID | 건너뛴 이유 | 정할 것 |
|
||||
|---|---|---|
|
||||
| 08-08, 08-03 | 리뷰의 수정안(파일 분리)만으로는 효과가 없다. 배럴이 다시 내보내는 모듈은 side effect가 있다고 보고 모두 초기 청크에 들어간다. design-system을 side effect 없는 모듈로 선언하면 초기 JS가 1,067 B 줄지만 초기 청크가 16개에서 21개로 는다 | 바이트와 요청 수 중 무엇을 줄일지 |
|
||||
| 0929/01-01 ④ | BFF 발급 401/403과 object store PUT 403은 code·단계·recovery가 같아 번역 한 곳에서 나눌 수 없다. 리뷰 예시와 보존 조건이 서로 어긋난다 | 백엔드가 code를 나눌지, 프론트가 단계를 따로 넘길지 |
|
||||
| 0929/03-04 | 결과 불명 쓰기의 문의 식별자. 완료하려면 결과 불명 화면(async-state, async-surface, use-app-form)을 고쳐야 한다 | 08·09 화면 작업과 묶을지 |
|
||||
| 0929/05-01 | 손상 행 하나가 목록 읽기 전체를 실패시킨다. 테스트 주석에 의도로 적혀 있다 | 동작을 바꿀지와 예산 인상 |
|
||||
| 0929/05-03 | 구조 변경이 크고 다운스트림이 깨질 수 있다 | 범위 |
|
||||
| 0929/05-04 | 코드가 아니라 예산 문제다(offline-indexeddb 여유 4 B) | 예산 |
|
||||
| 0929/06-05 | 다른 묶음 파일(`config/hosting`, `verify-hosting-headers.ts`)을 고쳐야 하고 조건부 surface 설계가 필요하다 | 설계 |
|
||||
| 0929/07-01 일부 | 오래된 증거 행 정리 | 행을 지울지 |
|
||||
| 0929/07-03 | 허용 목록을 줄이면 기준선 재승인이나 증거가 필요하고 `loadingSurface` 처리 방식을 골라야 한다 | 처리 방식, 기준선 재승인 |
|
||||
| 0929/08-02, 0929/08-03 | 0929 README가 "확장 지점 결정 뒤"로 묶어 두었다 | 5절 확장 지점 결정 |
|
||||
| 0929/10-02 | 구조 변경이 크다 | 범위 |
|
||||
| 04-02 (a) | "관측에서 구분" 기준을 채우려면 코드 어휘를 바꿔야 한다. 문서만 고쳤다 | (a)를 할지 |
|
||||
| 09-06 (3) | 미등록 route handle 검사. `context-routes.ts`를 늦게 읽어야 해서 헬퍼로 할지 적재 때 검사할지 골라야 한다. 그 실패의 진단 누락은 09-09로 막았다 | 검사 위치 |
|
||||
| 16-03 이름 변경 | 프로필 이름을 `EXTERNAL_BEARER`로 바꾸려면 레지스트리 기준선 재승인(REGISTRY_BASELINE_OWNER/REASON)이 필요하다 | 재승인 |
|
||||
| 12-04 일부 | 제품이 싣는 글꼴 목록을 선언하는 칸. 공개 계약에 새 이름이 생긴다 | 계약에 넣을지 |
|
||||
| 12-05 일부 | `check:feature-index`를 지울지 이유 문구만 고칠지 | 둘 중 하나 |
|
||||
| 10-04 정책 | 새 reporter는 quarantine 주석이 붙은 Vitest skip도 실패시킨다. 지금 그런 테스트는 없다. 전략 문서 16.5절에 적었다 | 이 정책을 유지할지 |
|
||||
| registry-baseline `source` | FE-REG-API·FE-REG-SCHEMA의 `source`가 15-01 뒤에도 옛 파일을 가리킨다. 승인 digest가 걸려 있다 | 재승인 때 고칠지 |
|
||||
| file-transfer 예산 | 55,700 → 56,100 gzip B로 올렸다(측정 56,031). 01-01·01-04·02-01·0929/01-01 수정분 | 인상을 받아들일지 |
|
||||
| 13-01, 13-02 | 배포 job과 운영 검사. 5절 결정 | 로드맵 6과 함께 |
|
||||
|
||||
### 13.6 새로 찾은 것
|
||||
|
||||
| 무엇 | 근거 | 성격·심각도 |
|
||||
|---|---|---|
|
||||
| LOGOUT·ACCOUNT_DELETION purge가 두 페이지 이상이면, 다 지워도 `moreObjectsAvailable: true`를 보고하고 chunk sweep을 하지 않는다. 다시 부르면 끝난다 | `src/adapters/storage/opfs/opfs-byte-store-adapter.ts`의 페이지 넘김 대입(`moreObjectsAvailable = page.value.moreAvailable`)이 true를 넣고, 마지막 페이지의 `||=`가 그 값을 유지한다. `6c52cdb`(2026-07-30)부터 있던 코드다. 코드로만 확인했고 실행하지 않았다(E2) | 확인된 결함, Low, P3. 고치면 offline-indexeddb 번들이 늘어 예산(여유 4 B)과 함께 정해야 한다 |
|
||||
|
||||
### 13.7 예산 여유 (`e4ace51`)
|
||||
|
||||
| 예산 | 측정 / 한도 (gzip B) | 여유 |
|
||||
|---|---|---|
|
||||
| 초기 JS | 203,816 / 204,800 | 984 |
|
||||
| realtime 레시피 | 40,897 / 40,900 | 3 |
|
||||
| offline-indexeddb 레시피 | 36,896 / 36,900 | 4 |
|
||||
| file-transfer 레시피 | 56,031 / 56,100 | 69 |
|
||||
|
||||
레시피 세 개는 다음 수정 때 예산 인상과 묶여야 한다(4절 4번).
|
||||
|
||||
### 13.8 마지막 게이트 (`e4ace51`, 오케스트레이터, 2026-11-02 00:32~)
|
||||
|
||||
`test:sample-removal`(설치 기능 0개에서 타입 검사·커버리지·빌드 포함) 통과, `check:bundle` 통과(초기 JS 203,816 / 204,800 B). `check:architecture`, `check:types`, `lint`, unit 2,497건, component 228건, integration 159건, contract 23건, runtime-schema 56건, `verify:documentation`, `check:adapter-inventory`, `check:ci`, `test:system` 112건, `check:design-system`, `check:i18n` 통과. 그 전 검증(`373b27b` 기준)에서 e2e 3엔진 187건 통과·3건 skip, 규모 측정은 `9333595`에서 다시 쟀다. 실제 Gitea runner에서는 돌리지 않았다(6절).
|
||||
|
||||
Reference in New Issue
Block a user