document-haness/docs/TechLog/tech-log-studio/values-lost-between-boundaries/reference/reference-a-missing-contract-field-has-a-signature.md

kind, slug, title, topic, topicName, project, status, verifiedOn, sourceRevision, source

kind	slug	title	topic	topicName	project	status	verifiedOn	sourceRevision	source
REFERENCE	a-missing-contract-field-has-a-signature	Studio 에서는 보이는데 공개 쪽만 비면 그 사이에 계약이 있다	values-lost-between-boundaries	값이 경계에서 사라진다	TechLog	게시 전	2026-09-04	tech-log@2026-09-02	final/document.md#§5.6 final/document.md#§5.5

Studio 에서는 보이는데 공개 쪽만 비면 그 사이에 계약이 있다

Studio 편집기에서는 값이 다 보이는데 공개 화면만 비어 있다면, 작성과 공개 사이의 계약 경계를 먼저 확인할 만한 강한 신호다. 이 저장소에서는 같은 신호가 여덟 번 계약 누락을 가리켰지만, 저장 구조가 종류별로 다른 경우에는 조회 로직이 원인일 수 있다.

관계

• 공개 Reference 가 통째로 비어 있었다 — 이름이 어긋났고 본문은 다른 테이블에 있었다 이 신호가 처음 잡힌 사건이다.
• 결정에는 상세 화면이 없어 목록 항목이 문서 전체를 실어야 했다 화면 쪽에서 역으로 확인해야 했던 사건이다.
• 한 경계를 고쳤으면 값의 여정 끝에서 확인한다 칸을 더한 뒤 무엇을 확인할지가 그 기준에 있다.

목적

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

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

규칙

1. Studio 에서는 보이고 공개 쪽만 비면 그 사이의 계약을 먼저 본다

두 화면이 같은 데이터베이스를 보는데 한쪽만 비면, 먼저 두 화면 사이의 계약 차이를 확인한다. 작성 쪽은 작성 계약을 지나고 조회 쪽은 조회 계약을 지난다. 이 저장소에서는 같은 신호가 여덟 번 계약 누락을 가리켰다. 이름과 계약이 맞는데도 값이 비면 종류별 저장 구조와 조회 로직으로 범위를 옮긴다.

2. 화면이 그리는 칸을 먼저 적고 응답에 있는지 하나씩 맞춘다

응답에서 출발하면 없는 칸은 보이지 않는다. 상세 endpoint 가 없는 종류에서 특히 그렇다 — 부를 상세가 없으므로 목록 항목이 문서 전체를 실어야 하고, 그 목록에 없는 칸은 화면이 각자 메운다.

3. 한 종류의 저장 구조가 다른 종류와 다르면 조회 쪽이 그것을 알아야 한다

Reference 의 본문은 문서 본문 칸이 아니라 규칙과 예시를 담는 별도 테이블에 있다. 이름이 맞아도 읽는 곳이 틀리면 빈 문자열이 나온다.

4. 칸을 더할 때 required 로 올릴지는 따로 판단한다

이미 나가 있는 응답에는 그 칸이 없다. required 로 올리면 계약을 반입한 쪽이 배포되기 전까지 그 응답이 검증에 걸린다. 배포 순서에 따라 깨지는 것과 값이 안 오는 것 중에서 고른다.

5. 값이 아니라 이름을 지키는 검사를 둔다

게이트웨이가 읽는 이름이 계약의 타입에 있는지를 묻는다. 값을 비교하는 검사는 픽스처를 게이트웨이가 읽는 이름으로 만들면 그대로 통과한다 — 테스트 작성자와 게이트웨이 작성자가 이름에 대해 합의한 것을 확인할 뿐이다.

적용 조건

• 같은 데이터를 두 표면이 각자의 계약으로 읽고, 한쪽만 비어 보이는 화면. 작성 계약과 조회 계약이 나뉜 구조에서 걸린다.

• 계약에 칸을 더하거나 화면에 칸을 더하는 변경에서도 건다. 화면이 먼저 늘면 그 칸이 응답에 있는지 확인할 곳이 없다.

예외

• 두 표면이 같은 계약을 쓰면 이 신호는 성립하지 않는다. 그때는 매퍼나 질의를 먼저 본다.

• 저장 구조가 종류마다 다르면 계약이 아니라 조회가 원인일 수 있다. 이름이 계약과 맞는데도 값이 비면 그쪽을 본다.

• 값이 있는데 겹쳐 보이는 경우는 이 신호가 아니다. 빈 칸을 다른 값으로 메우면 같은 글이 두 번 나온다.

예시

• 공개 Reference 가 통째로 비었을 때 게이트웨이가 읽던 네 이름이 전부 계약에 없었다.

• 프로젝트의 「주요 주제」는 테이블도 조인도 가능했는데 응답에 실을 칸이 없었다.

• 질문 목록만 주제가 빠져 있어서 질문 줄의 맥락이 「· 프로젝트」로 시작했다. 지식 목록은 처음부터 그 칸을 싣고 있었다.

• 프로젝트 목록 행에 slug 가 없었다. 다른 목록이 프로젝트를 가리킬 때 쓰는 것은 id 가 아니라 slug 다.

• 문서 요약 자리에 유형별 요약을 대신 넣었더니 머리말이 바로 아래와 같은 글을 두 번 말했다.