feat: 가상화 문서들 추가

2026-09-10 08:54:05 +09:00
parent e9f6a93327
commit 43e1aadef0
695 changed files with 153404 additions and 12754 deletions
@@ -27,9 +27,9 @@ source:

 ## 문제

-결정은 상세 endpoint 가 없다. 공개 주소가 `/projects/{slug}/decisions#{slug}` 로 목록 위의 앵커다.
+결정은 상세 endpoint 가 없다. 공개 주소가 /projects/{slug}/decisions#{slug} 로 목록 위의 앵커다.

-상세가 없으면 화면이 그리는 칸이 전부 목록 항목에 있어야 한다. 목록 항목에는 `title`·`summary`·`consequences`·`evidence` 가 빠져 있었다.
+상세가 없으면 화면이 그리는 칸이 전부 목록 항목에 있어야 한다. 목록 항목에는 title·summary·consequences·evidence 가 빠져 있었다.

 ## 결론

@@ -15,7 +15,7 @@ source:

 # 공개 Reference 가 통째로 비어 있었다 — 이름이 어긋났고 본문은 다른 테이블에 있었다

-Reference 를 게시했더니 Studio 에서는 모든 칸이 보이는데 공개 화면만 통째로 비어 있었다. 원인이 둘 겹쳐 있었다. 게이트웨이가 읽던 칸 이름이 계약에 없는 것들이었고, Reference 의 본문이 `body_markdown` 이 아니라 별도 테이블에 있었다. 타입 검사는 `as` 단언 때문에 아무 말도 하지 않았다.
+Reference 를 게시했더니 Studio 에서는 모든 칸이 보이는데 공개 화면만 통째로 비어 있었다. 원인이 둘 겹쳐 있었다. 게이트웨이가 읽던 칸 이름이 계약에 없는 것들이었고, Reference 의 본문이 body_markdown 이 아니라 별도 테이블에 있었다. 타입 검사는 as 단언 때문에 아무 말도 하지 않았다.

 ## 관계

@@ -24,7 +24,7 @@ Reference 를 게시했더니 Studio 에서는 모든 칸이 보이는데 공개
 - **Studio 에서는 보이는데 공개 쪽만 비면 그 사이에 계약이 있다**
  이 사건에서 굳힌 진단 규칙이다.
 - **TypeScript 가 검사를 놓아 주는 네 곳**
-  `as` 단언이 어긋남을 가린 것을 그 개념이 설명한다.
+  as 단언이 어긋남을 가린 것을 그 개념이 설명한다.

 ## 문제

@@ -40,9 +40,9 @@ DB 에는 작성자가 쓴 값이 그대로 있었다. 두 화면이 같은 데
 계약이 주는 이름 : scopeSummary · appliesTo · excludedScope
 결과 : 전부 undefined 로 떨어졌고, as string 단언 때문에 타입 검사가 통과했다

-Reference 의 본문은 `body_markdown` 이 아니라 `reference_detail` 의 규칙과 예시에 있다. Studio 편집기가 규칙을 제목과 본문으로 나눠 받고 마크다운 본문은 비워 두기 때문이다. 공개 조회는 `body_markdown` 만 보고 빈 문자열을 내보냈다.
+Reference 의 본문은 body_markdown 이 아니라 reference_detail 의 규칙과 예시에 있다. Studio 편집기가 규칙을 제목과 본문으로 나눠 받고 마크다운 본문은 비워 두기 때문이다. 공개 조회는 body_markdown 만 보고 빈 문자열을 내보냈다.

-고친 뒤에는 값이 아니라 이름을 지키는 테스트를 뒀다. 계약에서 그 칸이 사라지면 `satisfies` 가 먼저 깨진다. 값을 검사하는 테스트로는 이 결함이 잡히지 않는다.
+고친 뒤에는 값이 아니라 이름을 지키는 테스트를 뒀다. 계약에서 그 칸이 사라지면 satisfies 가 먼저 깨진다. 값을 검사하는 테스트로는 이 결함이 잡히지 않는다.

 ## 검증 환경

@@ -69,7 +69,7 @@ tech-log-backend : a5f93b9 이후
 const summary = body.purposeSummary as string;   // 계약에 그런 칸이 없다
 ```

-`as` 는 「이 값을 이 타입으로 다루겠다」는 선언이므로, 컴파일러는 그 이름이 응답 타입에 있는지 묻지 않는다. 실행하면 `undefined` 가 나오고 화면은 빈 문자열을 그린다.
+as 는 「이 값을 이 타입으로 다루겠다」는 선언이므로, 컴파일러는 그 이름이 응답 타입에 있는지 묻지 않는다. 실행하면 `undefined` 가 나오고 화면은 빈 문자열을 그린다.

 | 게이트웨이가 읽던 이름 | 계약이 주는 이름 |
 |---|---|
@@ -111,6 +111,6 @@ Reference 의 본문은 문서 본문 칸이 아니라 규칙과 예시를 담

 ## 확인하지 못한 것

-`as` 단언을 걷어낸 것은 이 매퍼 하나다. 같은 모양이 다른 매퍼에 남아 있는지 전수로 세지 않았다.
+as 단언을 걷어낸 것은 이 매퍼 하나다. 같은 모양이 다른 매퍼에 남아 있는지 전수로 세지 않았다.

 <!-- body:end -->
@@ -40,9 +40,9 @@ flattenRelations : 담지 않음 — 1차로 고침
 렌더 모델로 변환 : 담을 칸 자체가 없었음
 화면 목록으로 전달 : 또 버림

-렌더 모델 계약(`ResolvedRelation`)에 요약 칸이 없었고 `additionalProperties: false` 라 실을 수도 없었다. 계약에 `summary` 를 더하고 — 이미 나가 있는 응답을 깨지 않으려고 required 에는 넣지 않고 — 세 경계를 모두 이었다.
+렌더 모델 계약(ResolvedRelation)에 요약 칸이 없었고 additionalProperties: false 라 실을 수도 없었다. 계약에 summary 를 더하고 — 이미 나가 있는 응답을 깨지 않으려고 required 에는 넣지 않고 — 세 경계를 모두 이었다.

-그 과정에서 한 칸에 뭉쳐 있던 셋을 갈랐다. 대상의 종류는 `label`, 작성자가 쓴 이유는 `note`, 대상의 요약은 `summary` 다.
+그 과정에서 한 칸에 뭉쳐 있던 셋을 갈랐다. 대상의 종류는 label, 작성자가 쓴 이유는 note, 대상의 요약은 summary 다.

 ## 검증 환경

@@ -18,7 +18,7 @@ source:

 # 공개 화면 한 줄이 그려지기까지 값이 지나는 경계 열한 개

-공개 화면의 한 줄은 PostgreSQL 의 투영 테이블에서 출발해 열한 번 모양을 바꾼 뒤에 그려진다. 그 사이 어느 한 곳이 값을 담지 않아도 오류가 나지 않는다. `undefined` 는 빈 문자열로 그려지고 빈 배열은 「항목이 없습니다」로 그려진다.
+공개 화면의 한 줄은 PostgreSQL 의 투영 테이블에서 출발해 열한 번 모양을 바꾼 뒤에 그려진다. 그 사이 어느 한 곳이 값을 담지 않아도 오류가 나지 않는다. undefined 는 빈 문자열로 그려지고 빈 배열은 「항목이 없습니다」로 그려진다.

 ## 관계

@@ -51,8 +51,7 @@ PostgreSQL 테이블
                                               └─ 화면 컴포넌트
 ```

-:::evidence key="value-boundaries" alt="저장·백엔드 조립·HTTP envelope·프론트엔드 조립·화면 다섯 묶음을 세 저장소 구역으로 나눠 이은 흐름도" caption=" " zoom="true"
-:::
+![저장·백엔드 조립·HTTP envelope·프론트엔드 조립·화면 다섯 묶음을 세 저장소 구역으로 나눠 이은 흐름도](../../../final/assets/diagrams/value-boundaries/value-boundaries.svg)

 저장 쪽에 둘, 백엔드 조립에 넷, 전선에 하나, 프론트엔드 조립에 셋, 화면에 하나다. 저장소 경계로 보면 백엔드가 여섯, 전선이 하나, 프론트엔드가 넷이다.

@@ -64,7 +63,7 @@ PostgreSQL 테이블
 |---|---|---|
 | 어댑터 SQL | 실행할 때 컬럼이 있는지 | 컴파일 시점에는 컬럼 이름을 아무도 안 본다 |
 | 생성된 DTO | 계약의 스키마 모양 | 그 칸에 값이 담겼는지 |
-| 게이트웨이 매퍼 | 계약이 준 타입의 이름 | `as` 단언을 쓰면 그 확인이 사라진다 |
+| 게이트웨이 매퍼 | 계약이 준 타입의 이름 | as 단언을 쓰면 그 확인이 사라진다 |
 | 포트와 화면 | 두 타입이 맞는지 | 포트와 어댑터가 타입을 따로 들면 한쪽만 늘어난다 |

 어댑터 SQL 은 컬럼 이름을 문자열로 적는다. 이름이 틀리면 실행할 때 알게 되고, 그 SQL 을 실제로 돌리는 검사가 없으면 배포 뒤에 알게 된다.
@@ -30,7 +30,7 @@ Studio 편집기에서는 값이 다 보이는데 공개 화면만 비어 있으

 데이터베이스에 값이 있는데 화면이 비어 있을 때 어디를 먼저 볼지 정한다.

-이 부류는 오류를 내지 않으므로 로그에서 출발하면 아무것도 나오지 않는다. `undefined` 는 빈 문자열로 그려지고 빈 배열은 「항목이 없습니다」로 그려진다.
+이 부류는 오류를 내지 않으므로 로그에서 출발하면 아무것도 나오지 않는다. undefined 는 빈 문자열로 그려지고 빈 배열은 「항목이 없습니다」로 그려진다.

 ## 규칙

@@ -41,7 +41,7 @@ source:

 ### 2. 타입 검사 통과를 반영의 증거로 쓰지 않는다

-메서드 매개변수의 bivariance, `as` 단언, 검사 대상이 없는 tsconfig 가 각각 통과시킨 사례가 있다. 통과는 「코드가 맞다」가 아니라 「검사가 그 질문을 하지 않았다」를 뜻할 수 있다.
+메서드 매개변수의 bivariance, as 단언, 검사 대상이 없는 tsconfig 가 각각 통과시킨 사례가 있다. 통과는 「코드가 맞다」가 아니라 「검사가 그 질문을 하지 않았다」를 뜻할 수 있다.

 ### 3. 게이트웨이를 실제로 불러 어떤 연산이 나가는지 확인한다