모바일 앱, 웹 관리자, 서버를 서로 다른 업체에 맡기면 각 분야의 전문성을 활용하고 일정을 병렬화할 수 있습니다. 하지만 사용자는 세 결과물을 따로 사용하지 않습니다. 로그인부터 업무 완료까지 하나의 흐름으로 사용하기 때문에 업체 사이 경계가 관리되지 않으면 통합 단계에서 비용이 집중됩니다.
API 명세 밖의 통합 책임
엔드포인트와 필드 이름이 같아도 동작 의미가 다르면 연동할 수 없습니다. 다음 내용까지 공통 계약으로 정의해야 합니다.
- 필수값, 빈 값, 기본값의 구분
- 날짜, 시간대, 금액과 소수점 표현
- 인증 토큰의 발급, 갱신, 만료와 강제 로그아웃
- 오류 코드와 사용자에게 보여줄 수 있는 메시지
- 목록의 정렬, 검색, 페이지 이동 기준
- 중복 요청 처리와 요청 식별자
- 파일 업로드 크기, 형식, 중단 후 처리
- API 버전 변경과 폐기 절차
문서만 최신이고 구현이 다르면 의미가 없습니다. 명세에서 테스트용 클라이언트나 타입을 생성하거나, 계약 테스트를 자동 실행해 변경을 빠르게 발견해야 합니다.
전체 상태 흐름의 책임자
앱 업체는 서버 응답 문제라고 하고 서버 업체는 앱 호출 방식 문제라고 하면 발주사가 기술적 판정을 떠맡게 됩니다. 분리 발주에서도 한 명 또는 한 조직이 전체 구조와 최종 동작에 대한 결정권을 가져야 합니다.
통합 책임자는 특정 업체의 일정 관리만 하는 PM과 다릅니다. 인증, 상태 모델, API 계약, 데이터 소유권, 배포 순서를 판단하고 변경의 영향을 모든 업체에 전달할 수 있어야 합니다. 중요한 결정은 회의 기억이 아니라 결정 기록으로 남깁니다.
의존성 중심의 일정 관리
앱 화면이 90퍼센트 완료됐어도 핵심 API의 상태 규칙이 바뀌면 다시 작업해야 합니다. 각 업체의 완료율을 더하는 대신 사용자 흐름별 선행 조건을 관리해야 합니다.
예를 들어 회원가입 완료에는 화면, 인증 API, 약관 버전, 본인확인 연동, 오류 처리, 테스트 계정이 모두 필요합니다. 이 중 가장 늦은 항목이 전체 완료 시점입니다. 주간 보고도 업체별 작업량보다 어떤 흐름이 실제 검수 환경에서 끝까지 동작하는지를 기준으로 받는 편이 정확합니다.
공통 검수 환경과 테스트 데이터
각 업체의 로컬 환경에서는 동작하지만 통합 환경에서는 인증서, CORS, 네트워크 허용 목록, 데이터 버전 차이로 실패할 수 있습니다. 초기에 공통 개발·검수 환경을 만들고 모든 업체가 같은 기준으로 접속해야 합니다.
테스트 계정과 데이터도 역할별로 준비합니다. 정상 계정만 있으면 만료된 토큰, 권한 부족, 승인 대기, 한도 초과, 삭제된 데이터 같은 예외를 검증할 수 없습니다. 외부 서비스가 준비되지 않았다면 응답 지연과 오류까지 재현할 수 있는 모의 서버가 필요합니다.
버전 조합과 배포 순서
웹은 즉시 배포할 수 있지만 모바일 앱은 심사와 사용자 업데이트 시간이 필요합니다. 서버가 새 API만 지원하도록 바뀌면 구버전 앱 사용자가 갑자기 실패합니다.
서버는 일정 기간 이전 계약과 새 계약을 함께 지원하고, 앱 버전별 최소 지원 범위를 관리해야 합니다. 데이터베이스 변경도 기존 서버와 새 서버가 동시에 실행되는 구간을 고려합니다. 한 번에 모두 바꾸는 배포보다 추가, 전환, 제거의 세 단계로 나누는 편이 안전합니다.
업체 경계에서 증폭되는 변경 요청
필드 하나를 추가하는 요청이 데이터베이스, API, 웹, Android, iOS, 분석 이벤트와 문서까지 영향을 줄 수 있습니다. 한 업체에만 변경을 전달하면 나머지 결과물과 불일치가 생깁니다.
변경 요청에는 목적, 영향 받는 사용자 흐름, 계약 변경, 담당자, 적용 버전, 배포 순서, 검수 항목을 포함합니다. 통합 책임자가 영향 범위를 확인한 뒤 각 업체 일정에 반영하고 하나의 완료 조건으로 묶어야 합니다.
사용자 흐름 중심의 검수
화면 목록과 API 목록을 각각 검수하면 경계의 오류가 빠집니다. 최종 검수 시나리오는 실제 사용자의 시작부터 결과 확인까지 이어져야 합니다.
- 신규 사용자가 가입하고 인증한다
- 권한에 맞는 데이터를 조회하고 업무를 등록한다
- 담당자가 승인 또는 반려한다
- 알림을 받은 사용자가 결과를 확인한다
- 관리자가 이력과 통계를 조회한다
각 단계에서 네트워크 중단, 중복 요청, 세션 만료, 권한 부족과 외부 연동 실패도 시험합니다. 어느 업체가 수정할지는 내부 책임이고, 발주사의 완료 기준은 전체 흐름입니다.
계약서에 명시할 역할과 책임
- API 계약의 작성·승인·변경 책임자
- 인증과 사용자 식별의 최종 소유자
- 테스트 환경, 데이터와 계정 제공자
- 통합 테스트 작성 및 실행 주체
- 장애 원인 판정과 업체 간 조정 책임자
- 앱·웹·서버의 배포 승인자
- 로그와 모니터링 접근 권한
- 소스, 디자인, 계정, 문서의 인수 조건
분리 발주가 적합한 경우
분리 발주 자체가 잘못된 것은 아닙니다. 내부에 강한 기술 책임자가 있고, 도메인과 API 경계가 비교적 안정적이며, 각 결과물을 독립적으로 검수할 수 있을 때 효과적입니다. 반대로 요구사항이 계속 발견되는 초기 제품이거나 내부에서 기술 결정을 내릴 사람이 없다면 통합 비용이 절감액보다 커질 수 있습니다.
핵심은 업체 수가 아니라 전체 제품을 하나로 보는 책임 구조입니다. 업체별 계약, 일정, 검수를 유지하더라도 공통 상태 모델과 통합 환경, 사용자 흐름 기준의 완료 조건은 하나여야 합니다.