클랜원 조회를 API 계약부터 화면까지 한 줄로 이었습니다. 백엔드가 Cloudflare에 올라가 실제로 돌고 있습니다.
담긴 것
구조가 바뀌었습니다
contracts/openapi.yaml 손으로 쓰는 유일한 계약
├─ apps/api/src/schemas.py 서버 모델 (생성물)
└─ apps/web/src/api/schema.d.ts 화면 타입 (생성물)
packages/core/.../member/ 도메인 — SQL 도 HTTP 도 모른다
apps/api/src/adapters/ 바깥과 만나는 자리 — CoC API, D1
apps/api/src/routes/ HTTP 경로
apps/web/src/pages/ 화면 — 서버가 준 것을 보기 좋게 옮긴다
세 가지 원칙을 코드가 실제로 지키도록 만들었습니다.
앱끼리는 남입니다. 계약이 유일한 접점이고, 서버 모델과 화면 타입이 모두 거기서 생성됩니다. 서버는 자기 명세를 따로 발행하지 않습니다. 두 벌이 되면 어느 쪽도 계약이 아니게 되기 때문입니다.
서버는 사실만 말합니다. 응답에 "ADMIN" 은 담되 "장로" 는 담지 않습니다. 그 번역은 화면이 맡으므로, 표시 문구를 바꾸는 데 서버를 다시 배포할 필요가 없습니다.
공유하는 것은 순수한 것뿐입니다. 도메인에는 자료형과 규칙, 그리고 바깥과 만나는 자리의 약속만 둡니다.
새로 생긴 것
GET /api/v1/members— 클랜원 목록. 태그로 좁힐 수 있습니다- 마이그레이션 체계 — 번호를 붙인 파일을 순서대로 적용하고, D1이 어디까지 갔는지 스스로 기록합니다
/members/화면 — React로 새로 썼습니다. 불러오는 중·실패·빈 목록·목록 네 상태를 갈라 보여 줍니다- 기존
scores·draws도/api/v1/아래로 옮겼습니다
배포하며 겪은 것
실제로 올려 봐야만 드러나는 결함이 셋 있었고, 모두 다시 겪지 않도록 테스트로 막았습니다.
- 이미 배포된 데이터베이스에 마이그레이션을 걸면
users표를 못 쓰게 되던 문제. 빈 데이터베이스에만 걸어 보면 드러나지 않아, 배포되어 있던 스키마를 픽스처로 남겨 두 출발점에서 같은 결과가 나오는지 지킵니다 - 공용 코드가 쓰는 꾸러미가 번들에서 빠지던 문제. 소스를 복사해 넣는 방식이라 번들 도구가 그 안의
import를 볼 수 없습니다 - 마이그레이션 경로 설정이 무시되어, 하나도 적용되지 않은 채 배포만 성공한 것처럼 끝나던 문제
확인한 것
- 테스트 197개 통과
GET /api/health→coc_core: ok, 표 여덟 개, 한국 시각 정상GET /api/v1/members→ 동작 (동기화 전이라 빈 목록)
아직 남은 것
클랜원 동기화를 예약 실행으로 붙이는 일이 남았습니다. 그 전에 httpx 를 Workers에서 쓸 수 없다는 문제를 풀어야 합니다. CI에서 테스트와 빌드를 돌리는 것도 아직입니다.