카카오톡의 한 줄은 먼저 게임 요청으로 정리됩니다
사용자가 카카오톡 방에 단어를 보내면 카카오 챗봇이 카맨틀의 API로 요청을 전달합니다. 요청에는 입력한 문장뿐 아니라 어느 방과 사용자의 행동인지 구분하는 정보가 함께 들어옵니다.
API는 필요한 필드가 있는지 확인하고 텍스트를 게임에서 비교할 형태로 정리합니다. 명령어와 일반 추측을 구분하고, 원본 요청에서 내부 게임 이벤트에 필요한 작은 계약만 뽑아냅니다.
이 경계에서 잘못된 요청을 일찍 막으면 뒤의 게임 처리 코드가 카카오 원본 형식의 모든 예외를 반복해서 알 필요가 없습니다.
안정적인 식별 정보가 있는 재전달은 중복을 확인합니다
모바일 네트워크와 외부 플랫폼에서는 같은 요청이 다시 전달될 수 있습니다. 정답 메시지가 중복 처리되면 방이 문제를 두 번 넘기거나 통계가 두 건 쌓일 수 있습니다.
카맨틀은 방, 사용자, 입력 내용과 카카오가 제공한 시각 같은 정보를 조합해 이벤트 키를 만들고 이미 처리 중이거나 끝난 이벤트인지 확인합니다. 같은 키로 다시 도착한 요청은 기존 결과를 재사용하거나 중복으로 표시합니다.
다만 안정적인 시각 정보가 없는 요청은 현재 유입 시각을 대신 사용하므로 같은 메시지 ID만으로 모든 재시도를 같은 이벤트로 보장하지는 않습니다. 중복 확인은 지원되는 식별 정보가 충분할 때 동작하는 보호 장치로 이해해야 합니다.
API는 판정 작업을 큐에 맡깁니다
유사도 판정과 방 상태 변경을 API 요청 안에서 모두 기다리면 순간적으로 입력이 몰릴 때 카카오 응답 시간이 길어질 수 있습니다. 그래서 API는 정리한 게임 명령을 큐에 넣고 워커가 처리하도록 넘깁니다.
콜백을 사용할 수 있는 요청은 API가 접수 응답을 먼저 보내고 워커가 완성된 말풍선을 일회용 콜백 주소로 전달할 수 있습니다. 짧은 대기 안에 결과가 준비되면 바로 응답하고, 그렇지 않으면 비동기 경로가 답장 소유권을 이어받습니다.
API와 워커가 동시에 답장을 보내지 않도록 요청마다 응답 소유 상태를 관리합니다. 실패 안내도 같은 규칙을 따라 중복 말풍선이 생기지 않게 합니다.
방 상태는 독립적이지만 현재 워커는 작업을 차례로 처리합니다
단톡방에서는 여러 사람이 거의 동시에 단어를 보낼 수 있습니다. 뒤에 온 정답이 먼저 처리되거나 같은 최고 기록이 서로 덮어쓰면 사용자가 본 채팅 순서와 게임 상태가 달라집니다.
워커는 방 단위 순서와 잠금을 사용해 같은 방의 상태 변경을 차례대로 처리합니다. 서로 다른 방은 각자의 상태와 정답을 가지므로 한 방의 결과가 다른 방의 상태를 덮어쓰지는 않습니다.
현재 배포 구조에서는 한 워커가 큐에서 꺼낸 작업을 끝낸 뒤 다음 작업을 가져갑니다. 따라서 한 방의 처리가 오래 걸리면 뒤에 기다리는 다른 방의 응답도 늦어질 수 있습니다. 방별 순서 경계는 여러 워커로 확장할 기반이지만 현재 응답 시간까지 방마다 완전히 독립적이라는 뜻은 아닙니다.
정답을 맞힌 방만 다음 문제로 넘어가는 규칙도 이 방 단위 경계 위에서 유지됩니다. 공유하는 것은 미리 만든 정답 데이터이고 현재 진행 위치는 방마다 따로 저장합니다.
유사도 계산은 무거운 일을 미리 끝내 둡니다
입력 하나가 올 때마다 전체 한국어 어휘를 정답과 비교하면 채팅 흐름을 지키기 어렵습니다. 카맨틀은 정답마다 가까운 단어 상위 목록과 점수 분포 기준을 답안지 생성 단계에서 미리 계산합니다.
워커는 먼저 입력 단어가 유효한 어휘인지 확인하고 현재 정답의 상위 목록에서 순위와 점수를 찾습니다. 목록 밖의 단어는 필요한 벡터만 읽어 비교하고 분포 기준을 이용해 표시 점수나 범위를 만듭니다.
이 구조는 계산을 없애는 것이 아니라 사용자가 기다리는 순간에서 미리 준비할 수 있는 계산을 옮기는 방식입니다.
판정 결과와 상태를 함께 저장한 뒤 말풍선을 만듭니다
유효한 추측이면 현재 방의 추측 수, 최고 기록과 최근 기록을 갱신합니다. 정답이면 풀이 결과를 남기고 그 방의 다음 정답을 선택합니다. 힌트와 통계에 필요한 값도 같은 문제와 릴리스 범위를 기준으로 관리합니다.
상태 저장이 끝난 뒤 점수, 순위, 방의 상위 단어와 정답 축하 내용을 카카오 말풍선 형식으로 조립합니다. 사용자가 보는 짧은 답장 뒤에는 다음 요청이 같은 상태를 읽을 수 있도록 저장이 먼저 완료돼야 합니다.
마지막 전달이 실패하면 관측 로그와 재시도 규칙으로 원인을 추적합니다. 이미 정상 답장을 보내기 시작한 요청에는 다른 실패 답장을 겹쳐 보내지 않아 한 입력에 여러 결과가 보이는 일을 피합니다.
빠른 답장보다 중요한 것은 같은 입력의 같은 결과입니다
채팅 게임에서는 속도가 중요하지만 상태가 어긋난 빠른 답장은 더 큰 혼란을 만듭니다. 중복 요청, 동시 입력, 콜백 만료, 저장소 장애를 각각 분리해 다루는 이유입니다.
카맨틀의 한 줄 응답은 API, 큐, 워커, 방 상태, 미리 계산한 답안지와 카카오 콜백이 연결된 결과입니다. 각 단계는 작게 유지하고 단계 사이 계약을 명확히 해 문제가 생긴 위치를 찾을 수 있게 합니다.
앞으로 계산 방식이나 광고·통계 화면이 바뀌더라도 방별 진행과 한 요청 한 결과라는 원칙은 그대로 유지됩니다.