계약 enum ↔ web 유니온이 `ApiError.code` 하나만 대조된다 — `OpsComponent.id` 는 0 벌이다 (#594·#596 리뷰)

[gitIt-sehyeon]

#596 리뷰에서 실측했습니다. #594 와 #596 이 같은 enum 의 두 사본을 각자 들고 있고, 그 둘을 맞추는 것이 지금 사람입니다.

실물

$ grep -c "enum" server/src/test/java/com/sphinxfin/sphinx/api/contract/WebTypesMirrorContractTest.java
0

WebTypesMirrorContractTest 는 필드 이름만 대조합니다. 그래서 contracts/openapi.yaml 의 enum 값과 web/src/api/types.ts 의 유니온 값이 갈려도 아무것도 안 웁니다.

❗그런데 이 레포에 그 대조를 하는 자리가 이미 있습니다

ErrorCodeContractTest.webUnion() 이 ApiError.code enum 과 types.ts 의 ErrorCode 유니온을 값 단위로 맞춥니다. 즉 enum 하나는 여섯 벌이 대조되고, 다른 하나는 0 벌입니다.

ApiError.code       핸들러 · openapi · CLAUDE.md · 유니온 · 문면 표 · 명세서 §9   여섯 벌
OpsComponent.id     openapi · types.ts 유니온                                   0 벌

왜 지금 걸리나

#594(web 콘솔)가 유니온 넷을 들고 오고, #596(추출 카드)이 enum 에 다섯째(extraction)를 더합니다.

openapi.yaml   enum: [server, database, ai-service, data-volumes, extraction]
types.ts       "server" | "database" | "ai-service" | "data-volumes"

두 PR 이 서로를 알고 있어서 이번엔 사람이 맞춥니다(먼저 머지되는 쪽이 나머지를 고치기로 #594·#596 에서 정리됐습니다). 문제는 다음 카드가 생기는 날입니다 — 그때는 두 PR 이 겹치지 않을 수도 있고, 그러면 조용히 갈립니다.

갈리면 무엇이 나쁜가

#316 과 같은 모양입니다.

프론트가 이 목록을 유니온 타입으로 들고 있어, 어긋나면 타입 검사에서 걸리거나 조용히 default 로 떨어진다.

여기서는 카드 하나가 유니온에 없으면 그 카드만 화면에서 이름 없이 그려집니다. 화면은 components 를 그대로 map 하므로(오준서 확인) 렌더는 되고, id 로 분기하는 자리만 조용히 빠집니다. 그리고 그 화면이 «지금 무엇이 안 되는가» 를 답하는 자리라, 빠진 카드가 하필 문제 있는 카드일 수 있습니다.

무엇을 하면 되나

ErrorCodeContractTest.webUnion() 이 이미 하는 것을 일반화하면 됩니다.

openapi 의 어느 enum 이 types.ts 의 어느 유니온과 짝인지 목록을 두고,
그 목록의 각 쌍을 값 단위로 대조한다

❗목록 자체가 새 사본이 되지 않게 해야 합니다 — #586 이 ErrorCodeContractTest.SOURCES 에서 밟은 자리입니다. 거기서 쓴 방법(읽은 경로를 기록해 목록과 맞춘다)이 그대로 참고가 됩니다.

선행

#594 가 머지돼서 types.ts 의 OpsComponent 가 main 에 있어야 합니다. 그 전에는 대조할 짝이 한쪽밖에 없습니다.

소유

server/…/api/contract/ 와 contracts/ 가 강희진 님 것이라 배정합니다. 제가 내도 되면 그렇게 하겠습니다 — #596 리뷰에서 제가 떼겠다고 한 이슈입니다.

관련: #594 · #596 · #316(같은 계열) · #586(목록이 새 사본이 되는 함정)