---
name: dz-api-ref
description: >
  This skill should be used when the user asks to "API 정의 참조", "이 API 위키 정의 가져와",
  "sc111A05 정의 정리해", "엔드포인트 API 정합 검증", "API 참조 md 만들어", "정식 개발 전 API 참조",
  또는 Amaranth 10 기존 API(엔드포인트 코드 sc111A05·rs122A31·proxymgw24A72 등)를 정식 개발에
  활용하기 전에 사내 위키 API 정의를 조회하고 소스와 3중 대조하여 신뢰 가능한 참조 md를 만들어야 할 때.
  위키 정의(계약) + 소스(실동작)를 교차 검증해 enum·필드·필수·무가드 컬럼 불일치를 잡아낸다.
  단일 출처(SSoT) = 규칙/프로세스/API참조-체계-표준.md.
version: 0.1.0
---

# dz-api-ref — API 정의 참조·정합 검증 스킬

## 목적

Amaranth 10 기존 API를 **정식 개발**(제품 소스 반영·고객 영향)에 활용하기 전에, 사내 위키 API 정의서를
조회하여 **소스와 3중 대조**한 신뢰 가능한 참조 md를 만든다. 소스만 보고 추정하다 enum·필드명·필수
필드를 틀리는 사고(일정 API sc111A05 사례)를 막는다.

> **표준(SSoT, Single Source of Truth, 단일 출처)** = [`규칙/프로세스/API참조-체계-표준.md`](../../../규칙/프로세스/API참조-체계-표준.md). 본 스킬은 그 §4·§5를 자동 수행한다.
> ⛔ **추정 금지(전면)**: 정식 개발이든 내부 MCP·도구 개선이든 **모든 작업은 확인된 사양**(본 스킬 산출=정합 검증 완료 md)으로만 진행한다. 소스/실측 추정으로 구현·계약 작성 금지. 사양 미확인 시 구현 보류·보고.

## 입력

- **API 엔드포인트 코드**(권장): `sc111A05`·`rs122A31`·`proxymgw24A72` 등, 또는
- **기능명 + 모듈**: "일정 등록", "자원 조회" 등(코드를 모를 때 위키 검색으로 역추적)

## 절차 (1 API 기준 — 순차)

### 1단계: 위키 API 정의 조회 (계약)
- jira MCP 위키 도구 사용(기본 공간 `DBPKLAGO`):
  - `wiki_search`(query=코드·기능명 / 또는 cql `space=DBPKLAGO AND title~"..." AND type=page`)로 후보 페이지 검색
  - **신(新) 정의서 우선** — 부모 "30. Amaranth 10 Backend API 정의" 하위 + 제목에 `API 명 {code}`·`~/모듈/{code}` 포함 + **실 요청 예시(body)** 가 있는 페이지. 구(舊) `proxymgw API 문서(구)`는 보조.
  - `wiki_get_page`(page_id)로 본문 추출(format=text)
- 신/구 둘 다 있으면 둘 다 확보(신=주, 구=참고). 신 정의서 없으면 그 사실을 md에 명시하고 소스 우선.

### 2단계: 소스 확인 (실동작)
- 해당 모듈 레포에서:
  1. **컨트롤러 라우트** — `@RequestMapping(value = "/{code}")` → 호출 서비스 메서드(do*) 확인. 실제 엔드포인트 URL 확정.
  2. **서비스** — 요청에서 읽는 키(`request.get(...)`/`containsKey`), 분기·검증(`validateChecked`), 세션 자동 주입 필드.
  3. **매퍼(XML)** — insert/select의 **컬럼 ↔ #{파라미터}** 매핑, `<if>`/`<choose>` 가드 유무(가드 없는 필드 = 무조건 필요), enum 처리.
- 모듈→레포 매핑: [`조직/협업플랫폼개발본부/SBUnit/_관리레포-매핑.md`](../../../조직/협업플랫폼개발본부/SBUnit/_관리레포-매핑.md). 소스 분석 맥락: `Amaranth10/<모듈>/context/_source-architecture.md`.

### 3단계: 3중 대조 (Truth 판정)
표준 §2 표로 항목별 판정:

| # | 출처 | 역할 |
|---|------|------|
| ① 위키 신 정의서 | 계약(필드·enum·필수·예시) — 1순위 |
| ② 구 proxymgw | 보조 계약 |
| ③ 소스 | 실동작(무가드 컬럼·실 enum 처리) |

- **불일치 시**: 실제 동작은 ③(소스)이 truth, 의도·계약은 ①(위키)이 truth → 양쪽 충족하도록 기록(예: 위키 예시 빈 배열 + 소스 무가드 컬럼).
- 대조 항목: 엔드포인트 URL · 필수 필드 · 각 필드 enum · 무가드(NOT NULL) 컬럼 · 중첩 객체 구조 · 응답.

### 4단계: 참조 md 작성
- 위치: `Amaranth10/_소스분석/wiki/api정의/{모듈}/{API코드}-{기능명}.md` (없으면 폴더 신설)
- 양식: 표준 §4. frontmatter(api_code·page_id·url·module·endpoint·source_repo·source_path·collected·verified·verify_result) + 본문 7절(개요·요청 파라미터·중첩 객체·응답·실 예시·**소스 정합 검증 표**·변경 이력).
- **§6 소스 정합 검증 표가 핵심** — 단순 위키 복사 금지. 불일치는 근거(소스 `파일:라인`·위키 항목) 명시.
- 비밀정보(평문 자격증명 등) 마스킹.

### 5단계: 인덱스 갱신
- `Amaranth10/_소스분석/wiki/api정의/_INDEX.md`에 행 추가/갱신:
  `| 모듈 | API코드 | 기능 | 엔드포인트 | 수집일 | 검증일 | 정합결과 | 링크 |`
- 인덱스 없으면 신설(헤더 + 컬럼).

## 산출 보고

- 작성한 md 경로 + **정합 결과 요약**(일치 / 불일치 N건과 핵심 불일치) + 정식 개발 시 주의점.
- 불일치가 있으면 **반드시 명시**(맹종 금지) — 어느 쪽이 truth인지 근거와 함께.

## 함정 / 주의

- **catch-all 오류 메시지**: 서버가 모든 예외에 같은 메시지를 붙이는 경우 있음(예: insert 실패를 "종료일을 시작일 전"으로 표기). 메시지를 곧이곧대로 믿지 말고 소스 catch 블록 확인.
- **무가드 컬럼**: 매퍼 insert에서 `<if>` 없이 `#{x}`로 항상 참조되는 컬럼은 빈값이라도 키를 보내야 함(누락 시 NOT NULL 위반).
- **신/구 버전 혼재**: 구 proxymgw 정의의 enum이 신 정의와 다를 수 있음 — 신 정의서 우선, 소스로 최종 확인.
- **위키 vs 웹 엔드포인트**: proxymgw(모바일)와 web(예 schres) 엔드포인트는 래퍼({header,body} vs flat)가 다를 수 있음. 실제 사용할 엔드포인트 기준으로 기록.

## 관련

- 표준: [`규칙/프로세스/API참조-체계-표준.md`](../../../규칙/프로세스/API참조-체계-표준.md)
- 진단: [`참고자료/리포트/2026-06-30-위키API참조체계-진단.md`](../../../참고자료/리포트/2026-06-30-위키API참조체계-진단.md)
- 위키 인벤토리(전수): `Amaranth10/_소스분석/wiki/_전체인벤토리/20260602-wiki-전수데이터.json`