[Template+Project] 템플릿 카탈로그 API + templateType 실재 검증 [ #318 ]

[dldnsgkr]

왜

템플릿을 골라도 조용히 무시된다. startMode/templateType 은 검증·저장되기만 하고 읽는 코드가 없었다. 검증도 슬러그 형식만 봐서 존재하지 않는 템플릿이 200 으로 통과했고, 고른 템플릿은 무시된 채 백지 생성됐다. 사용자가 선택한 것이 아무 데도 반영되지 않는데 성공으로 보이는 형태다.

#318 PR-3. 설계는 docs/template-architecture-design.md(#319), 템플릿 저장소는 Dvely/qeploy-templates.

무엇

GET /api/v1/templates, /{id}	카탈로그 서빙. 인증 불필요 — 내용이 이미 공개 Pages 에 있는 정적 목록이고 사용자 데이터가 없다
프로젝트 생성	정규화된 templateType 을 카탈로그와 대조. 없으면 400
카탈로그 취득	10분 주기. 실패 시 직전 목록 유지(stale-while-error)

카탈로그 정본은 이 서버가 아니다. 템플릿 저장소가 발행하는 catalog.json 을 읽어 나를 뿐 소스를 들지 않는다 — jar 가 이미 158MB 고, 템플릿 하나 고치자고 백엔드를 재배포하는 구조를 만들지 않기 위해서다.

sourceUrl(씨앗 tarball)은 응답에 담지 않는다. 서버가 컨테이너에 풀 때만 쓰는 내부 경로다.

판단이 갈릴 만한 곳

검증이 도메인이 아니라 애플리케이션 계층에 있다. 정규화 이후에 물어야 하기 때문이다 — "E Commerce" 는 e-commerce 로 정규화된 뒤 조회돼야 카탈로그와 맞는다. 형식 정규화는 도메인이 끝내고, 네트워크가 필요한 실재 확인만 위로 올렸다. 테스트가 이 순서를 붙잡는다(정규화 전 값으로 물으면 스텁이 비어 실패한다).

갱신 실패 시 낡은 목록으로 계속 응답한다. 카탈로그는 정적 문서라 잠깐 낡은 목록이 프로젝트 생성을 막는 것보다 낫다. 다만 WARN 을 남긴다 — 조용히 넘기면 며칠째 갱신이 안 되는 것을 아무도 모른다. 503 은 한 번도 읽지 못한 경우에만 나간다. 그때 통과시키면 없는 템플릿이 저장되고 씨딩 시점에 가서야 깨진다.

아직 안 되는 것

씨딩이 없다. 카탈로그에 있는 ID 만 통과할 뿐, 통과한 뒤의 동작은 여전히 백지 생성이다. tarball 을 /workspace/app 에 푸는 경로는 PR-4 다. state.md §4.22 에 이 상태 그대로 적어뒀다.

검증

• 전체 테스트 1342건 통과
• 신규: 카탈로그 파싱·캐시·stale-while-error·최초 실패·빈 카탈로그 거절 / guard 3종 / 생성 시 미등록 템플릿 거절
• 마이그레이션 없음

문서(api.md · connection.md · state.md)에 실제와 어긋나 있던 서술도 고쳤다 — "생성 직후 CODE task 제출"은 그 경로가 제거된 뒤로 사실이 아니었다.

🤖 Generated with Claude Code

https://claude.ai/code/session_013y8USoCXTsRTATAhy88M93