GA 질의 이벤트 연결 키 충돌 해소

CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project are documented in this file.
 Before creating a release tag, add a section whose heading matches the tag name.
 For example, tag `v1.2.3` must have a `## [v1.2.3]` section.
 
+## [Unreleased]
+
+### Changed
+- 서버 GA 이벤트 `query_submit`, `query_response_complete`의 질의 연결 키를 `query_id`에서 `app_query_id`로 변경했습니다. GA 웹 태그의 내부 식별자와 충돌하지 않도록 하며, API/WebSocket의 `queryId` 필드와 값은 유지됩니다.
+- 클라이언트의 `query_result_click`, `query_feedback`도 응답의 `queryId`를 `app_query_id`로 전송해야 네 질의 이벤트를 연결할 수 있습니다. 백엔드 배포 시 클라이언트에도 변경된 연결 키가 함께 적용되어야 합니다.
+- 질의별 GA 분석·리포트의 연결 기준도 `app_query_id`로 맞춰야 합니다.
+
 ## [v0.1.1] - 2026-09-01
 
 ### Added

src/main/java/com/sofa/linkiving/domain/chat/dto/response/AnswerRes.java

@@ -21,7 +21,7 @@ public record AnswerRes(
 	@JsonSerialize(using = HashidsSerializer.class)
 	Long messageId,
 	@JsonInclude(JsonInclude.Include.NON_NULL)
-	@Schema(description = "GA query_id")
+	@Schema(description = "질의 추적 ID")
 	String queryId,
 	@Schema(description = "답변 내용")
 	String content,

src/main/java/com/sofa/linkiving/domain/chat/dto/response/MessageRes.java

@@ -24,7 +24,7 @@ public record MessageRes(
 	String content,
 
 	@JsonInclude(JsonInclude.Include.NON_NULL)
-	@Schema(description = "GA query_id")
+	@Schema(description = "질의 추적 ID")
 	String queryId,
 
 	@Schema(description = "발신자 타입 (USER / AI)")

src/main/java/com/sofa/linkiving/domain/chat/service/RagChatService.java

@@ -122,7 +122,7 @@ private List<Long> parseLinkIds(List<String> linkIds) {
 
 	private void publishQuerySubmit(Member member, String clientId, String queryId, long linkCountAtQuery) {
 		publishQueryEvent(member, clientId, "query_submit", Map.of(
-			"query_id", queryId,
+			"app_query_id", queryId,
 			"link_count_at_query", linkCountAtQuery
 		));
 	}
@@ -138,7 +138,7 @@ private void publishQueryResponseComplete(
 		List<LinkDto> selectedLinks
 	) {
 		Map<String, Object> params = new HashMap<>();
-		params.put("query_id", queryId);
+		params.put("app_query_id", queryId);
 		params.put("is_error", isError);
 		params.put("latency_ms", elapsedMillis(startNanos));
 

src/test/java/com/sofa/linkiving/domain/chat/service/RagChatServiceTest.java

@@ -220,11 +220,13 @@ void shouldPublishQueryAnalyticsEvents_WhenClientIdExists()
 		assertThat(complete.params()).containsEntry("selected_count", 2);
 		assertThat(complete.params()).containsEntry("top_similarity", 0.91);
 		assertThat(complete.params()).containsKey("latency_ms");
-		assertThat(complete.params().get("query_id")).isEqualTo(submit.params().get("query_id"));
+		assertThat(submit.params()).containsKey("app_query_id").doesNotContainKey("query_id");
+		assertThat(complete.params()).containsKey("app_query_id").doesNotContainKey("query_id");
+		assertThat(complete.params().get("app_query_id")).isEqualTo(submit.params().get("app_query_id"));
 		verify(messageCommandService).saveUserMessage(eq(chat), eq(userMessage),
-			eq((String)submit.params().get("query_id")));
+			eq((String)submit.params().get("app_query_id")));
 		verify(messageCommandService).saveAiMessage(eq(chat), eq("AI answer"),
-			eq((String)submit.params().get("query_id")), eq(List.of(link1)));
+			eq((String)submit.params().get("app_query_id")), eq(List.of(link1)));
 		assertThat(complete.params()).doesNotContainValue(userMessage);
 		assertThat(complete.params()).doesNotContainValue("AI answer");
 	}
@@ -263,9 +265,11 @@ void shouldPublishErrorQueryAnalyticsEvent_WhenAiClientFails() {
 		assertThat(complete.params()).containsEntry("is_error", true);
 		assertThat(complete.params()).containsEntry("error_type", "UNKNOWN");
 		assertThat(complete.params()).containsKey("latency_ms");
-		assertThat(complete.params().get("query_id")).isEqualTo(submit.params().get("query_id"));
+		assertThat(submit.params()).containsKey("app_query_id").doesNotContainKey("query_id");
+		assertThat(complete.params()).containsKey("app_query_id").doesNotContainKey("query_id");
+		assertThat(complete.params().get("app_query_id")).isEqualTo(submit.params().get("app_query_id"));
 		verify(messageCommandService).saveUserMessage(eq(chat), eq(userMessage),
-			eq((String)submit.params().get("query_id")));
+			eq((String)submit.params().get("app_query_id")));
 		assertThat(complete.params()).doesNotContainValue(userMessage);
 	}
 }