13단계 — 부분 실패와 복구를 교차 서비스 계약으로 닫기

여러 서비스가 하나의 제품을 이루면 “API가 200을 반환했다”는 완료 증거가 아닙니다. 배치가 일부만 처리했는지, migration이 실제로 적용됐는지, 정적 클라이언트가 서버 기능을 호출할 수 있는지, 사용자가 다음 행동을 알 수 있는지를 함께 닫아야 합니다.

이번 변경의 상태표

세 가지 경계

1. 생성 결과는 묶음 완전성을 먼저 검사한다

LLM이 기대 멤버 중 일부만 반환하면 일부를 저장하고 성공으로 세지 않습니다. 기대 멤버 집합을 비교한 뒤 정확히 맞을 때만 한 transaction으로 upsert합니다. DB 오류는 rollback하고 다음 scheduler 라운드가 부분 상태를 복구할 수 있게 합니다.

관련 읽기: 기대 멤버 집합의 완전성과 원자 upsert

2. 테스트 migration은 실패를 삼키지 않는다

통합 테스트가 migration 디렉터리 누락이나 SQL 오류를 경고만 남기고 통과하면 모든 entity 테스트가 false-green이 됩니다. 디렉터리·파일이 없거나 한 SQL이라도 실패하면 즉시 중단하고, SQL은 명시적 UTF-8로 읽습니다.

관련 읽기: 마이그레이션 replay를 fail-closed로 만들기

3. 정적 플랫폼은 없는 서버 기능을 호출하지 않는다

Tauri export에는 Next.js BFF route가 없습니다. 상대 경로 /api/batch/init를 호출해 404를 만들기보다 unsupported 상태를 반환하고, 화면은 서버 소유 기능이라는 사실을 설명해야 합니다.

관련 읽기: Tauri capability boundary

다섯 관점의 인수 증거

1. 기획자는 정상·부분 실패·재시도·지원하지 않는 플랫폼의 상태와 소유자를 적습니다.
2. 디자이너는 성공분과 실패 범위를 숨기지 않는 표, 키보드 포커스, 오류·재시도 문구를 확인합니다.
3. 개발자는 집합 검증, transaction, unique index, 안전한 오류 코드, 계약 테스트를 남깁니다.
4. 사용자는 현재 결과가 완전한지, 다시 시도하면 무엇이 바뀌는지 이해할 수 있어야 합니다.
5. 운영자는 scheduler 결과, readiness, migration 로그, release SHA와 rollback 경로를 조회할 수 있어야 합니다.

완료 체크리스트

• 부분 묶음이 완전한 결과처럼 skip되지 않는다.
• 한 행의 DB 실패가 묶음 전체를 rollback한다.
• migration 누락·SQL 오류가 테스트 성공으로 남지 않는다.
• NULL을 포함한 캐시 키의 논리적 유일성이 DB와 upsert에서 일치한다.
• 정적 클라이언트의 서버 전용 기능이 명시적 unsupported 상태를 사용한다.
• 공개 UI와 운영 로그가 같은 상태명을 사용한다.

이 체크리스트와 실행 결과가 release 기록에 함께 있을 때 교차 서비스 변경을 완료로 판정합니다.

강좌 연결

• 다음 단계
• 앞 단계
• 강좌 처음으로