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>
5.0 KiB
kind, slug, title, topic, topicName, project, status, sourceRevision, source
| kind | slug | title | topic | topicName | project | status | sourceRevision | source | |
|---|---|---|---|---|---|---|---|---|---|
| CASE | an-operation-you-can-see-but-cannot-call | 타입에는 보이는데 부를 수 없는 연산이 네 번 나왔다 | declared-but-not-implemented | 계약에 선언만 있고 구현이 없다 | TechLog | 게시 전 | tech-log@2026-09-02 |
|
타입에는 보이는데 부를 수 없는 연산이 네 번 나왔다
계약에서 타입이 생성되므로 에디터에서는 그 연산이 멀쩡히 보인다. 기여 목록에 등록하지 않으면 실행할 때 부를 수가 없고, 게이트웨이는 다른 연산으로 떨어진다. 개념 화면이 질문 조회를 부르고 개념 삭제가 질문 삭제를 불렀다. 같은 누락을 네 번 만났다.
관계
- 계약에 선언만 있고 구현이 없어 화면 다섯 곳이 비어 있었다 이쪽은 서버에 구현이 없었고, 여기서는 프론트가 등록을 빠뜨렸다.
- 계약과 구현은 서버와 화면 양쪽에서 전수 대조한다 이 누락을 잡는 가드가 그 기준에 있다.
- 구현이 종류를 좁게 적어도 넓은 포트를 만족했다 같은 개념 삭제 경로에서 타입 검사가 통과시킨 다른 결함이다.
문제
관리 계약의 연산은 tech-log-management-contract-contribution.ts 에 등록해야 실행 시 부를 수 있다. 계약에서 타입은 생성되므로 등록을 빠뜨려도 컴파일은 통과한다.
등록되지 않은 연산을 부르면 게이트웨이가 그 연산을 찾지 못하고 옆의 분기로 떨어진다. 그래서 증상이 「없는 연산」이 아니라 「다른 연산이 실행됨」으로 나온다.
결론
네 번 났고 전부 같은 원인이었다.
getPublicConcept : 개념 화면이 질문 조회를 불렀다
deleteConceptDraft : 개념 삭제가 질문 삭제를 불렀다
listStudioQuestions · listStudioProjectDecisions : 홈 편집기가 빈 목록을 그렸다
축(variant) CRUD 네 연산 : 축 화면이 데이터를 받지 못했다
공개 계약은 전수 대조하고, 관리 계약은 「한 종류만 빠진 항목」을 보는 가드를 뒀다. 깨진 것이 늘 그 모양이었다.
검증 환경
tech-log-frontend : 15e6ea8 이후 계약 : studio-management-v1 86 operation · public-v1 20 operation 확인 방식 : 계약이 선언한 연산과 기여 목록을 대조하는 테스트
재현 조건
- 계약에 연산을 더하고 타입을 생성한다
- 기여 목록에 등록하지 않은 채 그 연산을 부르는 화면을 연다
- 개발자도구 네트워크에서 실제로 나가는 경로를 본다 — 등록된 다른 연산의 경로가 나간다
본문
등록하지 않으면 옆으로 떨어진다
관리 계약의 연산은 기여 목록에 등록해야 실행할 때 부를 수 있다. 계약에서 타입은 생성되므로 등록을 빠뜨려도 에디터에서는 그 연산이 멀쩡히 보이고 컴파일도 통과한다.
증상이 「연산을 찾을 수 없습니다」였다면 바로 보였을 것이다. 게이트웨이는 등록된 것 중에서 고르므로 옆 분기로 떨어지고, 서버는 그 요청에 정상적으로 응답한다. 다만 다른 기록을 다룬다.
개념 삭제가 계속 질문 삭제 경로로 나갔고, 배포된 번들에서 서버 로그에 DELETE /api/v1/studio/questions/{id} 404 가 찍혔다. 개념 상세 주소도 마찬가지로 질문 조회를 불러 404 를 받았다.
네 번의 누락
| 연산 | 화면에서 무엇으로 보였나 |
|---|---|
getPublicConcept |
개념 화면이 질문 조회를 불러 404 |
deleteConceptDraft |
개념 삭제가 질문 삭제로 나가 404 |
listStudioQuestions · listStudioProjectDecisions |
홈 편집기가 빈 목록을 그림 |
| 축 CRUD 네 연산 | 축 화면이 데이터를 받지 못함 |
앞의 둘은 옆 분기로 떨어져 다른 기록을 다뤘고, 뒤의 둘은 아예 값이 오지 않아 빈 화면이 됐다. 등록되지 않은 연산이 무엇으로 보이는지는 게이트웨이가 그 종류를 어떻게 고르느냐에 달려 있다.
기여 목록이 무엇을 들고 있나
기여 목록은 연산 이름만 나열하는 것이 아니라 그 연산이 쓰는 오류 코드 집합까지 들고 있다. 관리 계약의 오류 코드 상수는 계약의 enum 과 1:1 이라고 주석이 못 박아 둔다. 등록이 빠지면 그 연산에 딸린 이 배선이 전부 없는 것이 된다.
가드 둘
축 CRUD 를 더한 커밋에서 가드를 둘 넣었다. 공개 계약은 전수 대조한다 — 계약이 선언한 연산이 기여 목록에 전부 있는지 본다.
관리 계약은 86 operation 이라 전수 대조가 무겁다. 대신 「한 종류만 빠진 항목」을 본다. 깨진 것이 늘 그 모양이었기 때문이다.
확인하지 못한 것
관리 계약 쪽 가드는 종류가 빠진 것만 본다. 연산 전체를 빠뜨리는 경우는 이 가드가 잡지 않고, 그 상태를 만들어 확인하지도 않았다.