feat: apply tool schema v17 metadata

2026-08-12 15:46:57 +09:00
parent 97a56efddf
commit 017812cd29
45 changed files with 1554 additions and 50 deletions
--- a/docs/superpowers/plans/2026-08-12-scaffold-ai-v17-metadata.md
+++ b/docs/superpowers/plans/2026-08-12-scaffold-ai-v17-metadata.md
@@ -0,0 +1,58 @@
+# Scaffold AI V17 Metadata Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** AI Tool 초안 생성 시 Tool Schema V17 Metadata 전체를 생성하고 Scaffold 폼에 자동 입력한다.
+
+**Architecture:** 기존 `/tool-draft` 응답 DTO를 확장하고 서버에서 값을 정규화한다. 화면은 서버 응답의 필드를 기존 V17 폼 요소에 직접 매핑하며, 실제 Scaffold 생성은 기존 `ToolDefinitionOptions` 경로를 그대로 사용한다.
+
+**Tech Stack:** Java 21, Spring Boot MVC, Jackson, JUnit 5, MockMvc, HTML/JavaScript
+
+## Global Constraints
+
+- 기존 Tool 생성 경로와 Legacy 연동 정보 입력 정책을 유지한다.
+- Tool Schema V17 필드명은 기존 `ToolDefinitionOptions`와 동일하게 유지한다.
+- 기존 작업 트리 변경사항을 되돌리거나 포함 범위 밖에서 수정하지 않는다.
+
+---
+
+### Task 1: AI Tool Draft 서버 계약 확장
+
+**Files:**
+- Modify: `dap-gateway/src/test/java/io/shinhanlife/dap/mcg/presentation/ScaffoldingControllerToolDraftTest.java`
+- Modify: `dap-gateway/src/main/java/io/shinhanlife/dap/mcg/presentation/ScaffoldingController.java`
+
+**Interfaces:**
+- Consumes: AI가 반환한 JSON Tool 초안
+- Produces: V17 Metadata가 포함된 `/api/v1/scaffold/tool-draft` JSON 응답
+
+- [ ] Mock AI 응답과 API assertion에 V17 필드를 추가한다.
+- [ ] 테스트를 실행해 현재 응답에서 V17 필드가 누락되어 실패하는지 확인한다.
+- [ ] `ToolDraft`와 프롬프트 및 정규화 로직을 확장한다.
+- [ ] 테스트가 통과하는지 확인한다.
+
+### Task 2: Scaffold 화면 자동 매핑
+
+**Files:**
+- Modify: `dap-gateway/src/main/resources/static/admin/scaffold.html`
+
+**Interfaces:**
+- Consumes: Task 1의 V17 Metadata JSON 필드
+- Produces: 같은 이름을 가진 V17 폼 입력값
+
+- [ ] `createAiToolDraft()`에 문자열 필드 매핑을 추가한다.
+- [ ] `exampleQueries`는 줄바꿈, `tags`는 쉼표 구분 문자열로 변환한다.
+- [ ] 누락된 값은 빈 값 또는 `MCP_TOOL` 기본값으로 처리한다.
+
+### Task 3: 통합 검증
+
+**Files:**
+- Verify: Gateway와 V17 관련 전체 변경
+
+**Interfaces:**
+- Consumes: Task 1~2 결과
+- Produces: 컴파일 및 표준 검증 증거
+
+- [ ] Gateway 대상 테스트를 실행한다.
+- [ ] `validateToolSchemaV17`을 실행한다.
+- [ ] `git diff --check`로 문법적 공백 오류를 확인한다.
--- a/docs/superpowers/plans/2026-08-12-tool-schema-v17-migration.md
+++ b/docs/superpowers/plans/2026-08-12-tool-schema-v17-migration.md
@@ -0,0 +1,162 @@
+# Tool Schema V17 Migration Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** BC-DAB-STD-003 V17의 Tool 스키마 필수 항목을 Tool Pod의 등록, Manifest, MCP 노출, Scaffold 및 빌드 검증 전 구간에 일관되게 적용한다.
+
+**Architecture:** 각 Tool의 업무 명세는 `tool-definitions/{category}/{tool-name}.yml`에서 관리하고, 기동 시 공통 로더가 이를 읽어 기존 어노테이션 정보와 결합한다. 결합된 `ToolMetadata`를 단일 원천으로 Manifest와 MCP Tool을 생성해 Portal/Gateway/직접 MCP 연결 간 메타데이터 차이를 제거한다.
+
+**Tech Stack:** Java 21, Spring Boot 3.5.11, Spring AI MCP 1.1.8, Jackson YAML/JSON, Gradle, JUnit 5, AssertJ
+
+## Global Constraints
+
+- Tool `name`은 `^[a-z][a-z0-9_]{2,63}$`를 만족한다.
+- V17 필수 14개 항목을 누락 없이 제공한다.
+- `example_queries`는 3~10개이며 Tool 이름을 직접 포함하지 않는다.
+- `parameters_schema`는 루트 `type: object`, `additionalProperties: false`이고 모든 property에 description을 둔다.
+- `outputSchema`를 명시한 Tool만 출력 검증하며 기존 우선순위를 유지한다.
+- 기존 SSE/Streamable HTTP 전송, trace-id/request-id/employee-id, MCI/HTTP 호출 흐름은 변경하지 않는다.
+- 기존 미추적 WCM/HMCI 파일을 삭제하거나 덮어쓰지 않는다.
+- `register=false`인 Tool을 임의로 운영 등록 상태로 변경하지 않는다.
+
+---
+
+### Task 1: V17 Tool Definition 모델과 로더
+
+**Files:**
+- Create: `dap-was-lib/src/main/java/io/shinhanlife/dap/lib/metadata/ToolDescription.java`
+- Create: `dap-was-lib/src/main/java/io/shinhanlife/dap/lib/metadata/ToolDefinition.java`
+- Create: `dap-was-lib/src/main/java/io/shinhanlife/dap/lib/metadata/ToolDefinitionRepository.java`
+- Create: `dap-was-lib/src/test/java/io/shinhanlife/dap/lib/metadata/ToolDefinitionRepositoryTest.java`
+- Modify: `dap-was-lib/src/main/java/io/shinhanlife/dap/mcc/dto/ToolMetadata.java`
+
+**Interfaces:**
+- Produces: `Optional<ToolDefinition> findByName(String name)` 및 `ToolMetadata`의 V17 필드 접근자.
+- Consumes: classpath `tool-definitions/**/*.yml`과 Jackson YAML.
+
+- [ ] **Step 1: Write failing loader and validation tests**
+
+  빈 필수 설명, 2개 이하 예시 질의, 잘못된 name, object가 아닌 schema를 거부하고 정상 YAML을 로드하는 테스트를 작성한다.
+
+- [ ] **Step 2: Run tests and verify RED**
+
+  Run: `./gradlew.bat :dap-was-lib:test --tests "*ToolDefinitionRepositoryTest"`
+  Expected: FAIL because V17 model/repository does not exist.
+
+- [ ] **Step 3: Implement minimal immutable models and classpath loader**
+
+  `ToolDescription(function, whenToUse, whenNotToUse, ioLimits)`와 V17 전체 필드를 가진 `ToolDefinition`을 만들고 기동 시 한 번 로드·검증해 name 기준 불변 Map으로 캐시한다.
+
+- [ ] **Step 4: Run tests and verify GREEN**
+
+  Run: `./gradlew.bat :dap-was-lib:test --tests "*ToolDefinitionRepositoryTest"`
+  Expected: PASS.
+
+### Task 2: Registry 수집과 Manifest 표준 매핑
+
+**Files:**
+- Modify: `dap-was-lib/src/main/java/io/shinhanlife/dap/lib/mcp/ToolRegistryHeartbeatSender.java`
+- Modify: `dap-was-lib/src/main/java/io/shinhanlife/dap/lib/manifest/ToolManifestItem.java`
+- Modify: `dap-was-lib/src/main/java/io/shinhanlife/dap/lib/manifest/ToolManifestMeta.java`
+- Modify: `dap-was-lib/src/main/java/io/shinhanlife/dap/lib/manifest/ToolManifestService.java`
+- Modify: `dap-was-lib/src/test/java/io/shinhanlife/dap/lib/mcp/ToolRegistryHeartbeatSenderTest.java`
+- Modify: `dap-was-lib/src/test/java/io/shinhanlife/dap/mcc/manifest/ToolManifestServiceTest.java`
+
+**Interfaces:**
+- Consumes: `ToolDefinitionRepository.findByName`.
+- Produces: V17 description, display description, examples, owner/version/interface/environment metadata가 포함된 `ToolMetadata`와 `/manifest` 응답.
+
+- [ ] **Step 1: Add failing enrichment and manifest mapping tests**
+- [ ] **Step 2: Run targeted tests and verify RED**
+
+  Run: `./gradlew.bat :dap-was-lib:test --tests "*ToolRegistryHeartbeatSenderTest" --tests "*ToolManifestServiceTest"`
+
+- [ ] **Step 3: Merge annotation runtime data with definition YAML**
+
+  호출 주소·상태는 런타임 값, 업무 설명·예시·소유조직은 YAML 값을 사용하며 필수 정의가 없는 등록 대상 Tool은 기동 검증에서 실패시킨다.
+
+- [ ] **Step 4: Map Manifest title/description/inputSchema/outputSchema/annotations/_meta**
+- [ ] **Step 5: Run targeted tests and verify GREEN**
+
+### Task 3: MCP Tool 직접 노출과 Gateway 동기화
+
+**Files:**
+- Modify: `dap-was-lib/src/main/java/io/shinhanlife/dap/lib/mcp/ToolPodMcpToolSynchronizer.java`
+- Create or Modify: `dap-was-lib/src/test/java/io/shinhanlife/dap/lib/mcp/ToolPodMcpToolSynchronizerTest.java`
+- Modify: `dap-gateway/src/main/java/io/shinhanlife/dap/mcg/sync/RegistryMcpToolSpecificationFactory.java`
+- Modify: `dap-gateway/src/test/java/io/shinhanlife/dap/biz/mcp/gateway/sync/RegistryMcpToolSpecificationFactoryTest.java`
+
+**Interfaces:**
+- Consumes: enriched `ToolMetadata`.
+- Produces: 동일한 MCP `name`, `title`, 합성 description, input/output schema, readOnly/destructive/idempotent annotations, `_meta`.
+
+- [ ] **Step 1: Add failing parity tests for Pod and Gateway MCP specs**
+- [ ] **Step 2: Run both module tests and verify RED**
+- [ ] **Step 3: Implement shared metadata-to-MCP mapping without changing transport**
+- [ ] **Step 4: Run both module tests and verify GREEN**
+
+### Task 4: 기존 Tool 전체 정의와 이름 정규화
+
+**Files:**
+- Create: `dap-was-sms/src/main/resources/tool-definitions/**/*.yml`
+- Create: `dap-was-oth/src/main/resources/tool-definitions/**/*.yml`
+- Modify: all `dap-was-sms/src/main/java/**/*UseCase*.java` containing `@McpTool`
+- Modify: all `dap-was-oth/src/main/java/**/*UseCase*.java` containing `@McpTool`
+- Modify: matching tests and mock fixture keys
+
+**Interfaces:**
+- Consumes: Task 1 YAML format.
+- Produces: every discovered Tool has one unique V17 definition.
+
+- [ ] **Step 1: Add failing repository-wide compliance test**
+
+  모든 `@McpTool` name에 정확히 하나의 정의가 있고 필수 필드/예시 수/name 규칙을 만족하는지 검사한다.
+
+- [ ] **Step 2: Run compliance test and verify RED**
+- [ ] **Step 3: Rename invalid names and add complete definitions**
+
+  `smp_exchangeRate_inquiry`는 `smp_exchange_inquiry`, `cmm_commonCode_lookup`는 `cmm_comcode_lookup`로 바꾸고 나머지 호출명은 호왘성을 위해 유지한다.
+
+- [ ] **Step 4: Update tests/fixtures and verify GREEN**
+
+### Task 5: Scaffold V17 생성 지원
+
+**Files:**
+- Modify: `dap-gateway/src/main/resources/static/admin/scaffold.html`
+- Modify: Scaffold request DTO/controller files discovered under `dap-gateway/src/main/java`
+- Modify: `dap-was-lib/src/main/java/io/shinhanlife/dap/lib/util/ToolScaffolder.java`
+- Modify: `dap-was-lib/src/test/java/io/shinhanlife/dap/lib/util/ToolScaffolderTest.java`
+
+**Interfaces:**
+- Consumes: 입력한 function/when-to-use/when-not-to-use/io-limits/display-description/examples/owner/tags/hints.
+- Produces: Java 소스, schemas, V17 tool-definition YAML.
+
+- [ ] **Step 1: Add failing scaffold generation tests**
+- [ ] **Step 2: Verify RED**
+- [ ] **Step 3: Add form fields, validation, preview and YAML generation**
+- [ ] **Step 4: Verify GREEN including duplicate DTO-field regression tests**
+
+### Task 6: Gradle 품질 게이트와 문서
+
+**Files:**
+- Create: `dap-was-lib/src/main/java/io/shinhanlife/dap/lib/validation/ToolSchemaV17ValidationRunner.java`
+- Create: `dap-was-lib/src/test/java/io/shinhanlife/dap/lib/validation/ToolSchemaV17ValidationRunnerTest.java`
+- Modify: `build.gradle`
+- Modify: `README.md`
+
+**Interfaces:**
+- Produces: `validateToolSchemaV17` Gradle task; `bootJar` before validation; file/Tool/field가 표시되는 실패 메시지.
+
+- [ ] **Step 1: Add failing validation runner tests**
+- [ ] **Step 2: Verify RED**
+- [ ] **Step 3: Implement runner and wire `bootJar.dependsOn(validateToolSchemaV17)`**
+- [ ] **Step 4: Document V17 fields, examples, Scaffold, compatibility and commands**
+- [ ] **Step 5: Run targeted and full verification**
+
+  Run:
+  - `./gradlew.bat :dap-was-lib:test`
+  - `./gradlew.bat :dap-was-sms:test :dap-was-oth:test :dap-gateway:test`
+  - `./gradlew.bat validateMcpToolNames validateToolSchemaV17`
+  - `./gradlew.bat clean build`
+
+  Expected: all tasks succeed with zero test failures.
--- a/docs/superpowers/specs/2026-08-12-scaffold-ai-v17-metadata-design.md
+++ b/docs/superpowers/specs/2026-08-12-scaffold-ai-v17-metadata-design.md
@@ -0,0 +1,22 @@
+# Scaffold AI V17 Metadata Design
+
+## Goal
+
+`AI로 Tool 채우기` 실행 시 Tool 기본 정보와 입출력 필드뿐 아니라 Tool Schema V17 Metadata도 함께 생성하고 화면에 반영한다.
+
+## Design
+
+- `/api/v1/scaffold/tool-draft`의 AI JSON 계약에 `functionDescription`, `displayDescription`, `whenToUse`, `whenNotToUse`, `ioLimits`, `exampleQueries`, `tags`, `ownerOrg`를 추가한다.
+- 서버는 문자열을 trim하고 목록 필드는 비어 있는 항목을 제거하여 반환한다.
+- `scaffold.html`은 응답받은 V17 값을 같은 이름의 폼 필드에 채운다. 목록은 화면의 기존 입력 규칙에 맞게 줄바꿈 또는 쉼표 문자열로 변환한다.
+- Legacy Interface ID와 Client System Code는 기존 방침대로 AI가 생성하지 않는다.
+
+## Error Handling
+
+- V17 필드가 누락된 과거 형식의 AI 응답도 역직렬화할 수 있게 하되, 서버에서 업무 설명을 기반으로 안전한 기본값을 생성한다.
+- AI가 빈 배열 또는 공백 항목을 반환하면 기본 예시 질의, 카테고리 태그, 기본 담당 조직을 적용한다.
+
+## Verification
+
+- Mock AI 응답을 사용하는 MVC 테스트로 모든 V17 필드가 API 응답에 포함되는지 검증한다.
+- Gateway 테스트와 Tool Schema V17 검증을 실행한다.
--- a/docs/superpowers/specs/2026-08-12-tool-schema-v17-migration-design.md
+++ b/docs/superpowers/specs/2026-08-12-tool-schema-v17-migration-design.md
@@ -88,8 +88,8 @@ Manifest Tool 항목에는 `outputSchema`를 추가한다. `_meta`에는 `versio

 모든 이름을 영문 소문자 snake_case 3~64자로 통일한다. 현재 확인된 변경 대상은 다음과 같다.

- `smp_exchangeRate_inquiry` -> `smp_exchange_rate_inquiry`
- `cmm_commonCode_lookup` -> `cmm_common_code_lookup`
+- `smp_exchangeRate_inquiry` -> `smp_exchange_inquiry`
+- `cmm_commonCode_lookup` -> `cmm_comcode_lookup`

 나머지 Tool도 같은 정규식과 `category_service_action` 의미 구조로 검증한다. MCI/EIMS 인터페이스 ID는 Tool명으로 사용하지 않고 `legacy_interface_id`에 저장한다.