루트 항목 하나를 옮기려면 코드 7곳의 루트 경로 목록을 같이 고쳐야 했다(복사 대상, 비밀값 검사 범위, 공급망 시험의 필수 입력, 이력 문서 검사, 규모 입력, vite 입력, TS 전용 규칙). 서로 다른 부분집합이고 한 곳에서 선언하지 않았다. 목록이 갈라져 공급망 생성이 깨진 적도 있다 (removal-fixture.ts 주석). 루트에는 JSON Schema 5개만 담은 `schemas/`가 `config/` 옆에 따로 있었다. `artifacts/`(출력 폴더)에는 사람이 쓴 수동 a11y 기록이, `config/hosting/`(호스트 계약)에는 시험 fixture가 섞였다. 고른 방법(design-docs repo-structure/04-frontend-layout.md 9.2절 3단계, 11절 R1·R2, 소유자 승인 2026-11-07): - `config/repository-layout.json`이 루트 항목마다 종류·역할·읽는 곳과 들어가는 목록(`sets`, 항목 안 경로는 `setPaths`)을 적는다. `scripts/lib/repository-layout.ts`가 읽고 검증한다. 6곳은 이름 붙은 집합을 고른다. JSON인 비밀값 검사 정책은 집합의 사본을 두고 시험이 같은지 본다(정책 파일은 릴리스 후보에 실려 형식을 바꾸지 않았다). 공급망 시험의 필수 입력 목록은 그 시험으로 대신한다. - `tests/unit/repository-layout.test.ts`: 등록부에 없는 루트 항목이 추적되면 실패(R1). 7곳이 등록부 모듈을 쓰고 루트 이름 둘 이상의 문자열 배열을 갖지 않는지(R2). - `schemas/artifacts/` → `config/schemas/artifacts/`, recipe 카탈로그 스키마 → `config/schemas/recipes/`. 정책 입력 순서(ASCII)에 맞춰 `config/schemas/`가 `config/security/` 앞에 온다. - 수동 a11y 기록 3개 → `docs/accessibility/route-reviews/`. `artifacts/`는 `.gitkeep`만 추적한다. 기록은 단위 시험이 읽어서 drill 사본에도 복사한다(`fixture-copy` 집합의 `docs/accessibility/route-reviews`). - `config/hosting/response-headers.fixture.json` → `tests/fixtures/hosting/response-headers.json`. 버린 것: 비밀값 검사 정책이 집합 이름을 참조하게 바꾸는 방법. 정책 파일은 릴리스 후보와 로컬 증거 평가가 읽는 형식이라 바꾸면 릴리스 증거 계약이 바뀐다. 루트 항목이 지워졌는데 등록부에 남는 경우는 시험하지 않았다. drill 사본은 일부만 복사해 그 방향을 볼 수 없다. 그런 항목은 그 집합을 쓰는 곳(복사, 비밀값 검사)에서 실패한다. 위험: 하네스 작업(fe-c)이 더할 `AGENTS.md`·`.claude/`를 미리 등록했다 (optional). 등록부가 이력 문서(`SPEC.md`)와 `CLAUDE.md` 이름을 적어서 이력 문서 검사에서 등록부 파일은 뺐다. 다운스트림은 자기 루트 항목을 등록부에 더해야 한다(CHANGELOG). CI 계약 기준선을 다시 받았다(a11y 기록 산출물 id·경로). 검증(desktop): 아래 4단계 커밋까지 쌓은 트리에서 test:unit, check:types, check:ci, lint, verify:documentation을 돌렸다(그 커밋에 적음). 이 커밋 단독으로 test:unit·check:ci·check:types를 돌렸다. Refs: design-docs repo-structure/04-frontend-layout.md 2.4·9.2·11절, README.md 3.4절
65 lines
4.7 KiB
Markdown
65 lines
4.7 KiB
Markdown
# 전역 ID
|
|
|
|
전역 ID는 기능 하나가 아니라 설치된 기능 전체가 함께 쓰는 공간의 이름이다.
|
|
두 기능이 같은 값을 쓰면 조립·레지스트리 검사에서 충돌하거나, 아무 검사 없이 조용히 섞인다.
|
|
|
|
규칙은 하나다(원칙 5).
|
|
|
|
- 모든 전역 ID에 기능 접두어를 붙인다.
|
|
- 무작위 값(무효화 topic)은 복사하지 않고 새로 만든다.
|
|
|
|
`create:feature`는 이 규칙대로 값을 만든다. 아래 표의 "생성 값" 열은 `invoice-feature`로 만들었을 때다.
|
|
접두어 꼴: `<base>` = `invoice`, `<BASE>` = `INVOICE`, `<Base>` = `Invoice`.
|
|
|
|
## 표
|
|
|
|
"검사 없음"은 이 커밋에서 유일성 검사를 찾지 못했다는 뜻이다. 접두어만이 충돌을 막는다.
|
|
|
|
| ID | 어디에 있나 | 생성 값 | 겹치면 |
|
|
|---|---|---|---|
|
|
| 기능 ID | `feature-module.ts`, 계약 `featureId`, `ApplicationFeatureInputs` 키, `FEATURE_OVERRIDES` 키 | `invoice-feature` | 생성 명령·생성기가 거부 (`Duplicate generated feature ids`) |
|
|
| context ID | `context-module.ts`, `FEATURE_CONTEXT_ID` | `invoice-context` | 생성 명령·생성기가 거부 (`Duplicate context id`) |
|
|
| route ID | 계약 `routes`, `routeRuntimeContracts`, 문구 키 | `INVOICE_LIST` | 조립 (`Duplicate route registry key`) |
|
|
| 라우트 경로 | 계약 `routes.*.path` | `/invoice` (새 context), `/<루트>/invoice` (기존 context) | `check:registries` (`duplicates path=`) |
|
|
| `chunkId` | 계약 `routes` | `route-invoice-list` | `check:registries` (`duplicates chunkId=`) |
|
|
| `moduleId` | `routeRuntimeContracts`, 지연 페이지 표 | `invoice-list-page` | `check:registries` (FE-REG-ROUTE-RUNTIME) |
|
|
| `loadingSurface` | 계약 `routes` | `invoice-list` | 검사 없음 (형식만 본다) |
|
|
| operation ID | descriptor, gateway | `INVOICE_LIST_ITEMS` | 계약 조립 (`duplicate operation`) |
|
|
| API 경로 | descriptor `pathTemplate` | `/invoices` | 검사 없음. 백엔드 계약을 따른다 |
|
|
| 스키마 ID | 스키마 메타데이터, zod 검증기 | `InvoiceNoRequest`, `InvoiceItemListPayload`, `InvoiceProblem` | 모듈 로드 (`Invalid or duplicate schema definition`) |
|
|
| `contributionId` | 계약 기여 | `invoice-feature-http-v1` | 계약 조립 (`duplicate contributionId`) |
|
|
| `policyId` | descriptor `frontend` | `INVOICE_LIST_V1` | 검사 없음 |
|
|
| `diagnosticsOperation` | descriptor `frontend` | `invoice.list` | 검사 없음 |
|
|
| 쿼리 namespace | 계약 `invalidation.namespaces`, 쿼리 바인딩 | `invoice-item` (버전 1) | 조립 (`Duplicate invalidation namespace`) |
|
|
| 무효화 topic | 계약 `invalidation.topics`, 뮤테이션 `invalidate` | `qinv.` + 무작위 26자 | 생성 명령이 설치된 topic과 비교, 조립 (`Duplicate invalidation topic`) |
|
|
| 쿼리·뮤테이션 `definitionId` | 쿼리 바인딩 | `invoice-item-list-v1` | 검사 없음 |
|
|
| 문구 키 | 기능 문구 catalog | `route.INVOICE_LIST.title`, `invoice.list.title` 등 | 생성 명령, 조립 (`Duplicate ko-KR message key`) |
|
|
| telemetry `kind` | application input | `invoice.list.failed` | 검사 없음 |
|
|
| `owner` | 스키마 메타데이터 | `feature-frontend-invoice-feature` | 검사 없음 |
|
|
| 인증 프로필 ID | descriptor `frontend.authProfileId` | `EXTERNAL_BEARER` (템플릿 것을 씀) | 제품 프로필이 템플릿 ID를 쓰면 모듈 로드 (`reuses a template profile id`) |
|
|
| `navigationOrder` | 계약 `routes` | 설치된 최댓값 + 10 | 검사 없음. 같은 숫자가 둘이어도 통과 |
|
|
|
|
메시지 전체와 고칠 파일은 [errors.md](errors.md)에 있다.
|
|
|
|
## 손으로 ID를 더할 때
|
|
|
|
뼈대에 operation·라우트·topic을 더하면 생성 명령이 다시 돌지 않는다. 아래를 직접 지킨다.
|
|
|
|
- 접두어를 붙인다. `NoRequest`, `ItemList` 같은 일반 이름을 쓰지 않는다.
|
|
- 무효화 topic은 새로 만든다.
|
|
- 형식: `qinv.` + 소문자·숫자 26자.
|
|
- `scripts/create-feature.ts`의 `randomTopicSuffix`가 같은 형식으로 만든다.
|
|
- 다른 기능의 값을 복사하지 않는다.
|
|
- route ID는 `<BASE>_<화면>` 꼴로 짓는다(`INVOICE_DETAIL`). 라우트를 더하면 a11y 기록 파일도 더한다(`docs/accessibility/route-reviews/<ROUTE_ID>.md`).
|
|
- 문구 키는 ko-KR과 en-US에 같은 키를 넣는다. `check:i18n`이 비교한다.
|
|
|
|
## 정본 위치
|
|
|
|
설치된 값의 목록은 이 문서에 두지 않는다. 코드에서 본다.
|
|
|
|
- 라우트: `src/features/installed-feature-contracts.ts`의 `ROUTE_REGISTRY`
|
|
- 무효화 topic·namespace: 같은 파일의 `INVALIDATION_REGISTRY`
|
|
- 문구 키: `src/presentation/i18n/catalog.ts`의 `KO_MESSAGES`
|
|
- 템플릿 인증 프로필: `src/contracts/rest-profiles.ts`의 `REST_AUTH_PROFILES`
|
|
- 레지스트리 스냅샷: `config/contracts/registry-baseline.json`
|