From 821b249d507ee69c930dc49d0b3860cc1f0b931c Mon Sep 17 00:00:00 2001
From: jade <jade.kimhs@gmail.com>
Date: Tue, 21 Jul 2026 10:29:30 +0900
Subject: [PATCH] fix: resolve MCI sample tool execution errors and improve
 parameter definitions in UI

---
 .../dap/mcg/service/ExecuteService.java       |  3 +
 .../mci/dto/ShinhanMessageDto.java            | 51 +++++++++++++++
 .../mci/dto/ShinhanTelegramWrapper.java       | 38 +++++++++++
 .../dap/common/util/PodScaffolder.java        |  2 +-
 .../resources/application-local.properties    |  2 +-
 .../mcc/other/DapToolOtherApplication.java    |  4 +-
 .../dap/other/dto/MciSampleRequestDto.java    | 30 +++++++++
 .../dap/other/dto/MyBizDataDto.java           | 40 ++++++++++++
 .../dap/other/tool/MciSampleTool.java         | 65 +++++++++++++++++++
 .../resources/application-local.properties    |  2 +-
 .../resources/application-local.properties    |  2 +-
 .../resources/application-local.properties    |  2 +-
 12 files changed, 234 insertions(+), 7 deletions(-)
 create mode 100644 dap-tool-core/src/main/java/io/shinhanlife/dap/common/integration/mci/dto/ShinhanMessageDto.java
 create mode 100644 dap-tool-core/src/main/java/io/shinhanlife/dap/common/integration/mci/dto/ShinhanTelegramWrapper.java
 create mode 100644 dap-tool-other/src/main/java/io/shinhanlife/dap/other/dto/MciSampleRequestDto.java
 create mode 100644 dap-tool-other/src/main/java/io/shinhanlife/dap/other/dto/MyBizDataDto.java
 create mode 100644 dap-tool-other/src/main/java/io/shinhanlife/dap/other/tool/MciSampleTool.java

diff --git a/dap-gateway/src/main/java/io/shinhanlife/dap/mcg/service/ExecuteService.java b/dap-gateway/src/main/java/io/shinhanlife/dap/mcg/service/ExecuteService.java
index f003541..1f05976 100644
--- a/dap-gateway/src/main/java/io/shinhanlife/dap/mcg/service/ExecuteService.java
+++ b/dap-gateway/src/main/java/io/shinhanlife/dap/mcg/service/ExecuteService.java
@@ -252,6 +252,9 @@ public class ExecuteService {
                         JsonNode data = null;
                         try {
                             data = toolInvoker.invoke(pagePayload, executeApiUrl);
+                        } catch (org.springframework.web.client.RestClientResponseException e) {
+                            // HTTP 4xx, 5xx 에러는 연결 오류가 아니라 비즈니스 로직 오류이거나 검증 실패이므로 원본 에러를 그대로 반환
+                            throw new ToolExecutionException(FailureType.SERVER_ERROR, "Tool Pod HTTP 에러 (" + e.getStatusCode() + "): " + e.getResponseBodyAsString());
                         } catch (Exception e) {
                             if (executeApiUrl.contains("http://tool-")) {
                                 String fallbackUrl = executeApiUrl.replaceAll("http://tool-[a-zA-Z0-9-]+", "http://localhost");
diff --git a/dap-tool-core/src/main/java/io/shinhanlife/dap/common/integration/mci/dto/ShinhanMessageDto.java b/dap-tool-core/src/main/java/io/shinhanlife/dap/common/integration/mci/dto/ShinhanMessageDto.java
new file mode 100644
index 0000000..f7d540b
--- /dev/null
+++ b/dap-tool-core/src/main/java/io/shinhanlife/dap/common/integration/mci/dto/ShinhanMessageDto.java
@@ -0,0 +1,51 @@
+package io.shinhanlife.dap.common.integration.mci.dto;
+
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+/**
+ * @package io.shinhanlife.dap.common.integration.mci.dto
+ * @className ShinhanMessageDto
+ * @description AX HUB 시스템 처리 클래스 - MCI 전문 메시지부
+ * @author 김형식
+ * @create 2026.09.01
+ * <pre>
+ * ---------- 개정이력 ----------
+ * 수정일      수정자    수정내용
+ * ---------- -------- ---------------------------
+ * 2026.09.01  김형식    최초생성
+ * 
+ * </pre>
+ */
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public class ShinhanMessageDto {
+
+    private MsgHddvValu msgHddvValu; // 메시지헤더부값
+    private MsgDtdvValu msgDtdvValu; // 메시지데이터부값
+
+    @Data
+    @Builder
+    @NoArgsConstructor
+    @AllArgsConstructor
+    public static class MsgHddvValu {
+        private String msgTnsmTypeCd; // 메시지전송유형코드
+        private Integer msdvLencn;    // 메시지부길이
+        private Integer msgRpttCc;    // 메시지반복건수
+    }
+
+    @Data
+    @Builder
+    @NoArgsConstructor
+    @AllArgsConstructor
+    public static class MsgDtdvValu {
+        private String msgCd;         // 메시지코드
+        private String msgPrnAttrCd;  // 메시지출력속성코드
+        private String msgCt;         // 메시지내용
+        private String anxMsgCt;      // 부가메시지내용
+    }
+}
diff --git a/dap-tool-core/src/main/java/io/shinhanlife/dap/common/integration/mci/dto/ShinhanTelegramWrapper.java b/dap-tool-core/src/main/java/io/shinhanlife/dap/common/integration/mci/dto/ShinhanTelegramWrapper.java
new file mode 100644
index 0000000..b324391
--- /dev/null
+++ b/dap-tool-core/src/main/java/io/shinhanlife/dap/common/integration/mci/dto/ShinhanTelegramWrapper.java
@@ -0,0 +1,38 @@
+package io.shinhanlife.dap.common.integration.mci.dto;
+
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import com.fasterxml.jackson.annotation.JsonUnwrapped;
+
+/**
+ * @package io.shinhanlife.dap.common.integration.mci.dto
+ * @className ShinhanTelegramWrapper
+ * @description AX HUB 시스템 처리 클래스 - MCI 전문 전체 래퍼 (공통헤더부 + 메시지부 + 데이터부)
+ * @author 김형식
+ * @create 2026.09.01
+ * <pre>
+ * ---------- 개정이력 ----------
+ * 수정일      수정자    수정내용
+ * ---------- -------- ---------------------------
+ * 2026.09.01  김형식    최초생성
+ * 
+ * </pre>
+ */
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public class ShinhanTelegramWrapper<T> {
+
+    // 1. 공통 헤더부
+    private ShinhanCommonHeaderDto tgrmCmnnhddValu;
+
+    // 2. 메시지부
+    private ShinhanMessageDto tgrmMsdvValu;
+
+    // 3. 데이터부 (비즈니스마다 다름, JsonUnwrapped로 평탄화하거나 객체 자체로 유지 가능. 여기서는 객체 유지)
+    private T tgrmDtdvValu;
+}
diff --git a/dap-tool-core/src/main/java/io/shinhanlife/dap/common/util/PodScaffolder.java b/dap-tool-core/src/main/java/io/shinhanlife/dap/common/util/PodScaffolder.java
index 5f4987d..18abddf 100644
--- a/dap-tool-core/src/main/java/io/shinhanlife/dap/common/util/PodScaffolder.java
+++ b/dap-tool-core/src/main/java/io/shinhanlife/dap/common/util/PodScaffolder.java
@@ -163,7 +163,7 @@ public class PodScaffolder {
             
             # Gateway/Tool URLs
             axhub.gateway.url=http://localhost:8081
-            axhub.tool.url=http://localhost:${server.port}
+            axhub.tool.url=${AXHUB_TOOL_URL:http://localhost:${server.port}}
             
             # Disable Kafka
             spring.autoconfigure.exclude=org.springframework.boot.autoconfigure.kafka.KafkaAutoConfiguration
diff --git a/dap-tool-email/src/main/resources/application-local.properties b/dap-tool-email/src/main/resources/application-local.properties
index 96467d3..a7134b9 100644
--- a/dap-tool-email/src/main/resources/application-local.properties
+++ b/dap-tool-email/src/main/resources/application-local.properties
@@ -17,7 +17,7 @@ eims.mcistring.url=http://localhost:${server.port}/api/mock/esb/string
 
 # Gateway/Tool URLs
 axhub.gateway.url=http://localhost:8081
-axhub.tool.url=http://localhost:${server.port}
+axhub.tool.url=${AXHUB_TOOL_URL:http://localhost:${server.port}}
 
 # Disable Kafka
 spring.autoconfigure.exclude=org.springframework.boot.autoconfigure.kafka.KafkaAutoConfiguration
diff --git a/dap-tool-other/src/main/java/io/shinhanlife/dap/mcc/other/DapToolOtherApplication.java b/dap-tool-other/src/main/java/io/shinhanlife/dap/mcc/other/DapToolOtherApplication.java
index 96dee7f..c06b4d7 100644
--- a/dap-tool-other/src/main/java/io/shinhanlife/dap/mcc/other/DapToolOtherApplication.java
+++ b/dap-tool-other/src/main/java/io/shinhanlife/dap/mcc/other/DapToolOtherApplication.java
@@ -20,8 +20,8 @@ import org.springframework.boot.autoconfigure.SpringBootApplication;
 import org.springframework.boot.context.properties.ConfigurationPropertiesScan;
 import org.springframework.cache.annotation.EnableCaching;
 
-@SpringBootApplication(scanBasePackages = {"io.shinhanlife.dap.mcc", "io.shinhanlife.dap.common.adapter", "io.shinhanlife.dap.common.mcp", "io.shinhanlife.dap.common.config"})
-@ConfigurationPropertiesScan(basePackages = {"io.shinhanlife.dap.mcc", "io.shinhanlife.dap.common.adapter", "io.shinhanlife.dap.common.mcp", "io.shinhanlife.dap.common.config"})
+@SpringBootApplication(scanBasePackages = {"io.shinhanlife.dap.mcc", "io.shinhanlife.dap.common.adapter", "io.shinhanlife.dap.common.mcp", "io.shinhanlife.dap.common.config", "io.shinhanlife.dap.other"})
+@ConfigurationPropertiesScan(basePackages = {"io.shinhanlife.dap.mcc", "io.shinhanlife.dap.common.adapter", "io.shinhanlife.dap.common.mcp", "io.shinhanlife.dap.common.config", "io.shinhanlife.dap.other"})
 @EnableCaching
 public class DapToolOtherApplication {
     public static void main(String[] args) {
diff --git a/dap-tool-other/src/main/java/io/shinhanlife/dap/other/dto/MciSampleRequestDto.java b/dap-tool-other/src/main/java/io/shinhanlife/dap/other/dto/MciSampleRequestDto.java
new file mode 100644
index 0000000..107f333
--- /dev/null
+++ b/dap-tool-other/src/main/java/io/shinhanlife/dap/other/dto/MciSampleRequestDto.java
@@ -0,0 +1,30 @@
+package io.shinhanlife.dap.other.dto;
+
+import io.shinhanlife.dap.mcc.annotation.McpParameter;
+import lombok.Data;
+
+/**
+ * @package io.shinhanlife.dap.other.dto
+ * @className MciSampleRequestDto
+ * @description AX HUB 시스템 처리 클래스
+ * @author 김형식
+ * @create 2026.09.01
+ * <pre>
+ * ---------- 개정이력 ----------
+ * 수정일      수정자    수정내용
+ * ---------- -------- ---------------------------
+ * 2026.09.01  김형식    최초생성
+ * 
+ * </pre>
+ */
+@Data
+public class MciSampleRequestDto {
+    @McpParameter(description = "인터페이스 ID (입력 예시: S001)")
+    private String interfaceId;
+
+    @McpParameter(description = "메시지 전송 유형 (입력 예시: T001)")
+    private String messageType;
+
+    @McpParameter(description = "조회 대상 고객명 (입력 예시: 홍길동)")
+    private String customerName;
+}
diff --git a/dap-tool-other/src/main/java/io/shinhanlife/dap/other/dto/MyBizDataDto.java b/dap-tool-other/src/main/java/io/shinhanlife/dap/other/dto/MyBizDataDto.java
new file mode 100644
index 0000000..afecf61
--- /dev/null
+++ b/dap-tool-other/src/main/java/io/shinhanlife/dap/other/dto/MyBizDataDto.java
@@ -0,0 +1,40 @@
+package io.shinhanlife.dap.other.dto;
+
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fasterxml.jackson.annotation.JsonPropertyDescription;
+import io.shinhanlife.dap.mcc.annotation.McpParameter;
+
+/**
+ * @package io.shinhanlife.dap.other.dto
+ * @className MyBizDataDto
+ * @description AX HUB 시스템 처리 클래스 - 샘플 비즈니스 데이터 DTO
+ * @author 김형식
+ * @create 2026.09.01
+ * <pre>
+ * ---------- 개정이력 ----------
+ * 수정일      수정자    수정내용
+ * ---------- -------- ---------------------------
+ * 2026.09.01  김형식    최초생성
+ * 
+ * </pre>
+ */
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public class MyBizDataDto {
+
+    @McpParameter(description = "고객 이름", required = true)
+    private String customerName;
+
+    @McpParameter(description = "조회 대상 일자 (YYYYMMDD)", required = true)
+    private String targetDate;
+
+    @McpParameter(description = "비고 내용")
+    private String remarks;
+}
diff --git a/dap-tool-other/src/main/java/io/shinhanlife/dap/other/tool/MciSampleTool.java b/dap-tool-other/src/main/java/io/shinhanlife/dap/other/tool/MciSampleTool.java
new file mode 100644
index 0000000..93db27a
--- /dev/null
+++ b/dap-tool-other/src/main/java/io/shinhanlife/dap/other/tool/MciSampleTool.java
@@ -0,0 +1,65 @@
+package io.shinhanlife.dap.other.tool;
+
+import io.shinhanlife.dap.mcc.annotation.McpFunction;
+import io.shinhanlife.dap.mcc.annotation.McpTool;
+import io.shinhanlife.dap.common.integration.mci.dto.ShinhanTelegramWrapper;
+import io.shinhanlife.dap.common.integration.mci.dto.ShinhanCommonHeaderDto;
+import io.shinhanlife.dap.common.integration.mci.dto.ShinhanMessageDto;
+import io.shinhanlife.dap.common.integration.mci.dto.ShinhanMessageDto.MsgHddvValu;
+import io.shinhanlife.dap.other.dto.MyBizDataDto;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Service;
+
+import java.util.Map;
+import java.util.UUID;
+
+import io.shinhanlife.dap.other.dto.MciSampleRequestDto;
+
+/**
+ * @package io.shinhanlife.dap.other.tool
+ * @className MciSampleTool
+ * @description AX HUB 시스템 처리 클래스 - MCI 연동 샘플 툴
+ * @author 김형식
+ * @create 2026.09.01
+ * <pre>
+ * ---------- 개정이력 ----------
+ * 수정일      수정자    수정내용
+ * ---------- -------- ---------------------------
+ * 2026.09.01  김형식    최초생성
+ * 
+ * </pre>
+ */
+@Slf4j
+@Service
+@McpTool(routingType = "MCI", categoryKey = "common")
+public class MciSampleTool {
+
+    @McpFunction(displayName = "MCI 샘플 전송", name = "send_mci_sample", description = "MCI 표준 헤더, 메시지부, 데이터부 구조를 갖는 샘플 연동")
+    public ShinhanTelegramWrapper<MyBizDataDto> sendMciSample(MciSampleRequestDto params) {
+        log.info("▶ [MCI Sample Tool] 요청을 수신했습니다. 전달된 파라미터: {}", params);
+        
+        ShinhanTelegramWrapper<MyBizDataDto> request = new ShinhanTelegramWrapper<>();
+        
+        // 1. 공통 헤더부 생성
+        ShinhanCommonHeaderDto header = new ShinhanCommonHeaderDto();
+        header.setItrIfId(params.getInterfaceId() != null && !params.getInterfaceId().isBlank() ? params.getInterfaceId() : "dummy_header");
+        header.setReqRspnScCd("R");
+        header.setGlbId(UUID.randomUUID().toString());
+        request.setTgrmCmnnhddValu(header);
+
+        // 2. 메시지부 생성
+        ShinhanMessageDto msg = new ShinhanMessageDto();
+        MsgHddvValu msgHeader = new MsgHddvValu();
+        msgHeader.setMsgTnsmTypeCd(params.getMessageType() != null && !params.getMessageType().isBlank() ? params.getMessageType() : "dummy_msg_type");
+        msg.setMsgHddvValu(msgHeader);
+        request.setTgrmMsdvValu(msg);
+
+        // 3. 데이터부 생성
+        MyBizDataDto bizData = new MyBizDataDto();
+        bizData.setCustomerName(params.getCustomerName() != null && !params.getCustomerName().isBlank() ? params.getCustomerName() : "홍길동");
+        bizData.setRemarks("정상적으로 처리되었습니다. (응답 테스트)");
+        request.setTgrmDtdvValu(bizData);
+
+        return request;
+    }
+}
diff --git a/dap-tool-other/src/main/resources/application-local.properties b/dap-tool-other/src/main/resources/application-local.properties
index 96467d3..a7134b9 100644
--- a/dap-tool-other/src/main/resources/application-local.properties
+++ b/dap-tool-other/src/main/resources/application-local.properties
@@ -17,7 +17,7 @@ eims.mcistring.url=http://localhost:${server.port}/api/mock/esb/string
 
 # Gateway/Tool URLs
 axhub.gateway.url=http://localhost:8081
-axhub.tool.url=http://localhost:${server.port}
+axhub.tool.url=${AXHUB_TOOL_URL:http://localhost:${server.port}}
 
 # Disable Kafka
 spring.autoconfigure.exclude=org.springframework.boot.autoconfigure.kafka.KafkaAutoConfiguration
diff --git a/dap-tool-payment/src/main/resources/application-local.properties b/dap-tool-payment/src/main/resources/application-local.properties
index 96467d3..a7134b9 100644
--- a/dap-tool-payment/src/main/resources/application-local.properties
+++ b/dap-tool-payment/src/main/resources/application-local.properties
@@ -17,7 +17,7 @@ eims.mcistring.url=http://localhost:${server.port}/api/mock/esb/string
 
 # Gateway/Tool URLs
 axhub.gateway.url=http://localhost:8081
-axhub.tool.url=http://localhost:${server.port}
+axhub.tool.url=${AXHUB_TOOL_URL:http://localhost:${server.port}}
 
 # Disable Kafka
 spring.autoconfigure.exclude=org.springframework.boot.autoconfigure.kafka.KafkaAutoConfiguration
diff --git a/dap-tool-sms/src/main/resources/application-local.properties b/dap-tool-sms/src/main/resources/application-local.properties
index 4372677..7f7a288 100644
--- a/dap-tool-sms/src/main/resources/application-local.properties
+++ b/dap-tool-sms/src/main/resources/application-local.properties
@@ -21,4 +21,4 @@ mcp.security.tenant-domains.mcp-client-2=ALL
 
 # Gateway/Tool URLs
 axhub.gateway.url=http://localhost:8081
-axhub.tool.url=http://localhost:${server.port}
+axhub.tool.url=${AXHUB_TOOL_URL:http://localhost:${server.port}}