DongHyeonkaandClaude Opus 5
a8ce0dda07
건너뛴 참조 다섯을 읽고 나서 다시 썼다 — from-ssot-to-records.md 의 「그림과 증거는 배정 대상이다」, code-tables-diagrams.md 의 표·코드 규칙, explaining.md 의 「이름을 댔으면 왜 있는지도 댄다」. **SSOT 를 먼저 고쳤다.** §3.3 의 코드블록이 저장소와 달랐다 — PATH_PREFIX_KINDS 는 Record 표가 아니라 튜플 배열이고, 진짜 경로 표는 EXPLORE_KIND_PATHS 다. 저장소에서 확인해 실물로 바꾸고, javadoc 이 적어 둔 이유를 함께 옮겼다. §16.7 에 BRANCH_FIELDS 와 pathOf 실물을, §4.3 에 ContractRouteCoverageTest 의 javadoc 과 면제 상수 둘을 더했다. 62,643 → 65,737 자. **계약에 ssot-assets·ssot-evidence 를 배정했다.** 그 절차를 건너뛰어서 SSOT 가 이미 가진 그림과 측정이 글감에 배정되지 않은 채였다. TechLog 12 글감, keycloak-session-store 는 그림 21장·증거 19건을 배정하고 붙일 글감이 없는 그림 4장은 이유를 계약에 적었다. 배정하자 검사기가 「배정한 증거를 기록이 쓰지 않는다」 4건을 드러냈다. **주제 셋을 다시 썼다.** hand-listed-kinds 중앙값 1,925 → 3,760 자 declared-but-not-implemented → 2,608 자 values-lost-between-boundaries → 2,602 자 게시된 기록은 keycloak 4,546 · n+1liner 3,190 이다. 표와 코드를 SSOT 에서 옮기고, Reference 에 담을 수 없던 표(§5.5 의 여덟 자리)를 짝이 되는 Case 로 내렸다. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
108 lines
5.4 KiB
Markdown
108 lines
5.4 KiB
Markdown
---
|
|
kind: CASE
|
|
slug: a-summary-vanished-at-three-boundaries
|
|
title: 관계의 요약이 경계 세 곳을 지나며 사라졌다
|
|
topic: values-lost-between-boundaries
|
|
topicName: 값이 경계에서 사라진다
|
|
project: TechLog
|
|
status: 게시 전
|
|
lastVerifiedOn: 2026-09-04
|
|
sourceRevision: tech-log@2026-09-02
|
|
source:
|
|
- final/document.md#§5.2
|
|
- final/document.md#§5.3
|
|
---
|
|
|
|
# 관계의 요약이 경계 세 곳을 지나며 사라졌다
|
|
|
|
관계 목록의 라벨을 고쳤는데 요약은 여전히 비어 있었다. 한 경계를 고치고 확인했더니 다음 경계가 버리고 있었고, 그것을 고치니 그다음이 버렸다. 세 번째는 계약에 담을 칸 자체가 없었다.
|
|
|
|
## 관계
|
|
|
|
- **공개 화면 한 줄이 그려지기까지 값이 지나는 경계 열한 개**
|
|
세 경계가 그중 어디인지가 그 개념에 있다.
|
|
- **한 경계를 고쳤으면 값의 여정 끝에서 확인한다**
|
|
이 사건에서 굳힌 규칙이다.
|
|
- **결정에는 상세 화면이 없어 목록 항목이 문서 전체를 실어야 했다**
|
|
같은 시기에 계약의 빈칸으로 난 다른 사건이다.
|
|
|
|
## 문제
|
|
|
|
관계 목록은 한 줄에 대상의 종류와 작성자가 쓴 이유와 대상의 요약을 보인다. 라벨은 고쳤는데 요약 칸이 계속 비어 있었다.
|
|
|
|
계약에는 요약이 있었다. DB 에도 값이 있었다. 화면까지 오지 못했다.
|
|
|
|
## 결론
|
|
|
|
값이 세 경계를 지나며 사라지고 있었다.
|
|
|
|
flattenRelations : 담지 않음 — 1차로 고침
|
|
렌더 모델로 변환 : 담을 칸 자체가 없었음
|
|
화면 목록으로 전달 : 또 버림
|
|
|
|
렌더 모델 계약(`ResolvedRelation`)에 요약 칸이 없었고 `additionalProperties: false` 라 실을 수도 없었다. 계약에 `summary` 를 더하고 — 이미 나가 있는 응답을 깨지 않으려고 required 에는 넣지 않고 — 세 경계를 모두 이었다.
|
|
|
|
그 과정에서 한 칸에 뭉쳐 있던 셋을 갈랐다. 대상의 종류는 `label`, 작성자가 쓴 이유는 `note`, 대상의 요약은 `summary` 다.
|
|
|
|
## 검증 환경
|
|
|
|
tech-log-frontend : a3ed23e 이후
|
|
tech-log-design-package : fa67a64 이후
|
|
tech-log-backend : 92679f5 이후
|
|
확인 방식 : 공개 화면의 관계 목록에서 세 값이 각각 나오는지 확인
|
|
|
|
## 재현 조건
|
|
|
|
1. 기록 둘을 관계로 잇고 이유를 적는다
|
|
2. 게시한 뒤 공개 화면에서 관계 목록을 본다
|
|
3. 라벨·이유·요약 세 값이 각각 나오는지 본다 — 하나라도 비면 그 값이 어느 경계에서 사라졌는지 역순으로 따라간다
|
|
|
|
## 본문
|
|
|
|
<!-- body:start -->
|
|
|
|
## 세 번 버려졌다
|
|
|
|
관계 목록의 라벨을 고치고 화면을 봤을 때 요약은 여전히 비어 있었다. 값이 지나는 경계를 하나씩 따라가니 세 곳에서 버려지고 있었다.
|
|
|
|
```text
|
|
계약(요약 있음)
|
|
└─ flattenRelations 가 담지 않음 ← 1차로 고침
|
|
└─ 렌더 모델로 바꿀 때 버림 ← 담을 자리 자체가 없었다
|
|
└─ 화면 목록으로 넘길 때 또 버림
|
|
```
|
|
|
|
첫 번째는 코드가 그 칸을 안 읽은 것이라 한 줄로 고쳤다. 두 번째에서 막혔다 — 렌더 모델 계약에 담을 칸이 없었고, 그 스키마가 `additionalProperties: false` 라 계약을 고치지 않고는 실을 수도 없었다.
|
|
|
|
## 계약에 칸을 더할 때 required 를 따로 판단한다
|
|
|
|
렌더 모델에 `summary` 를 더했다. required 에는 넣지 않았다.
|
|
|
|
이미 나가 있는 응답에는 그 칸이 없다. required 로 올리면 계약을 반입한 쪽이 배포되기 전까지 그 응답이 검증에 걸린다. 배포 순서에 따라 깨지는 것과 값이 안 오는 것 중에서 뒤쪽을 골랐다.
|
|
|
|
## 한 칸에 셋이 뭉쳐 있었다
|
|
|
|
값을 잇고 나서 다른 문제가 보였다. 관계 한 줄이 답해야 하는 것이 셋인데 `reason` 한 칸을 지나고 있었다.
|
|
|
|
| 무엇 | 뜻 | 경로별로 어떻게 나왔나 |
|
|
|---|---|---|
|
|
| 대상의 종류 | 「근거」「관련 기준」 같은 분류 | 렌더 모델 경로: 작성자의 문장이 이 자리에 눌려 나옴 |
|
|
| 작성자가 쓴 이유 | 「다음에 무엇을 읽을지」의 답 | 공개 조회 경로: **아예 버려짐** |
|
|
| 대상의 요약 | 대상이 무엇인지 | — |
|
|
|
|
한 칸에 셋이 들어가니 경로마다 다른 것이 나왔다. 렌더 모델을 지나는 화면에서는 작성자가 쓴 문장이 분류 자리에 눌려 나왔고, 공개 조회를 지나는 화면에서는 그 문장이 아예 사라졌다.
|
|
|
|
셋을 `label`·`note`·`summary` 로 갈랐다. 설명 자리에는 문장이 있으면 문장을, 없으면 요약을 보인다. 요약은 대상이 무엇인지 말하고 문장은 왜 지금 그것을 읽어야 하는지 말하므로, 문장이 없을 때 요약으로 대신하는 것은 되지만 반대는 되지 않는다.
|
|
|
|
## 한 경계를 고치고 판단하면 안 된다
|
|
|
|
이 건에서 「고쳤다」고 두 번 판단했고 두 번 다 틀렸다. 값이 지나는 경계가 열한 개인데 그중 하나만 보고 판단했기 때문이다.
|
|
|
|
확인은 배포본에서, 그 값이 실제로 그려지는 곳에서 한다. 타입 검사와 단위 테스트와 「코드를 읽어 보니 맞다」는 전부 중간 지점이다.
|
|
|
|
## 확인하지 못한 것
|
|
|
|
세 경로에서 무엇이 나오는지는 화면으로 확인했다. 세 경로 전부를 자동 검사로 고정하지는 않았다.
|
|
|
|
<!-- body:end -->
|