영차 BE에서 게이트웨이와 모듈 사이의 데이터를 동기화하는 방법

소속 변경은 하나의 통합 이벤트로 보낸다

소속 생성, 등급 변경, 재직 상태 변경은 각각 별도 이벤트로 쪼개지 않고 하나의 소속 변경 이벤트로 통합한다. 복제본이 필요한 값을 한 이벤트에 담으면 소비자는 같은 행을 upsert할 수 있다.

{
  "schemaVersion": 1,
  "occurredAt": "2026-09-07T01:00:00Z",
  "traceId": "trace-id",
  "membership": {
    "user": "user-id",
    "company": "company-id",
    "branch": "branch-id",
    "grade": "OWNER",
    "employmentStatus": "ACTIVE"
  }
}

각 서비스의 읽기 사본은 원본의 대체 테이블이 아니다. 해당 서비스가 조회와 권한 범위 확인에 필요한 읽기 전용 사본이다. 활성 사업장도 로컬 사본으로 확인한다. 그러면 근태 조회가 계정·조직 모듈의 응답을 기다리지 않는다.

값의 소유자 단위로 이벤트를 만든다

복제 대상이 늘어날 때 직원 이벤트에 모든 값을 얹지는 않았다. 값이 어느 대상의 것인지에 따라 이벤트를 나눈다.

사업장 설정을 바꿀 때 직원마다 소속 이벤트를 다시 보내면 한 번의 변경이 직원 수만큼 퍼진다. 값의 소유자가 사업장이므로 사업장 단위 이벤트 하나를 보내고, 근태 모듈이 사업장 기준으로 받는다. 근무 형태 이름도 소속 이벤트에 넣지 않고 근무 형태 자체의 이벤트로 보낸다. 변경 단위와 이벤트 단위를 맞추면 불필요한 재발행을 막을 수 있다.

복제본은 최신 값으로 덮어쓴다

Kafka 소비는 중복될 수 있다. 그렇다고 모든 이벤트에 별도의 처리 이력 테이블을 만들지는 않는다.

현재 상태를 보관하는 읽기 사본은 같은 키를 upsert한다. 같은 이벤트를 두 번 받아도 결과가 같아야 한다. 순서가 뒤집힐 수 있는 경우에는 발생 시각 또는 파티션 순번을 비교해 최신 값만 반영한다. 같은 대상을 같은 파티션 키로 보내면 한 대상의 변경 순서도 유지할 수 있다.

반대로 감사 기록처럼 사건을 누적하는 저장소는 다르다. 같은 사건을 두 번 받으면 기록이 두 줄 남는다. 이런 이벤트에는 고유 이벤트 ID를 넣고 소비자가 처리한 식별자를 기준으로 중복을 제거한다. 알림 발송 이벤트도 같은 이유로 고유 이벤트 ID가 필요하다.

게이트웨이는 조립하지 않는다

화면에 여러 영역의 값이 필요하더라도 게이트웨이에 조립 로직을 넣지 않는다.

• 단일 영역 조회는 해당 영역의 API가 반환한다.
• 다른 영역의 값이 필요하지만 실시간성이 중요하지 않으면 읽기 복제본을 사용한다.
• 서로 다른 원본의 최신 응답을 동시에 합쳐야 하는 화면은 앱에서 여러 API를 호출한다.
• 인증 토큰과 활성 사업장 정보는 게이트웨이를 거쳐 전달하지만, 업무 데이터의 의미는 각 영역이 해석한다.

이 규칙 덕분에 게이트웨이는 모듈이 늘어도 도메인 조립 서비스로 커지지 않는다.

모든 이벤트에 고유 ID와 처리 이력을 강제할 뻔했다

처음에는 중복 수신이 걱정돼 모든 이벤트에 고유 ID와 처리 이력 테이블이 필요하다고 보기 쉬웠다. 하지만 현재 상태를 덮어쓰는 복제 이벤트는 같은 값을 다시 저장해도 결과가 바뀌지 않는다.

누적형 이벤트만 고유 ID를 통한 중복 제거 대상으로 분리했다. 중복을 막는 비용도 이벤트가 실제로 만들어 내는 부작용에 따라 정해야 한다.

퇴사 이벤트를 일반적인 소속 변경으로만 처리했다

퇴사도 소속 상태 중 하나이므로 처음에는 일반 덮어쓰기로 충분해 보였다. 그러나 퇴사는 뒤에 자동으로 새로운 변경이 오지 않을 수 있는 종착 상태다. 더 중요한 점은 각 서비스의 사본 처리 목적이 다르다는 것이다.

• 알림과 감사: 해당 회차의 읽기 사본을 삭제한다.
• 근태와 휴가: 법정 보존이 필요한 기록을 보관 영역으로 옮긴다.
• 근태·휴가 영역: 열린 근태를 마감하고 대기 중인 휴가를 취소한다.

따라서 소비자는 모든 상태 변경을 단순 덮어쓰지 않는다. 퇴사라는 상태에 대한 별도 분기가 필요하다.

유실돼도 다음 이벤트가 오면 된다고 생각했다

일반적인 프로필 속성은 다음 변경 때 다시 복제될 수 있다. 하지만 퇴사 이벤트가 유실되면 사본이 계속 재직 상태로 남고, 이후 이벤트가 오지 않을 수 있다. 사본 파기와 근태 마감도 실행되지 않는다.

그래서 소속 변경 이벤트는 전체 발행 경로를 Outbox로 승격했다. 원본 변경과 발행할 이벤트를 같은 로컬 트랜잭션에 기록하고, 릴레이가 Kafka로 보낸다. 소비자는 여전히 멱등하게 처리한다. Outbox는 중복을 없애는 장치가 아니라 발행 유실을 줄이는 장치다.