zioinfo-mail/workspace/guardia-itsm/.claude/skills/rpa-orchestrator/SKILL.md

name	description
rpa-orchestrator	GUARDiA ITSM RPA 봇 오케스트레이터. ITSM 반복 업무 자동화, RPA 작업 등록/실행/스케줄링, 입력 Validation 학습, 실행 이력 조회를 총괄한다. 다음 상황에서 반드시 사용: (1) 'RPA', '봇 자동화', '자동 처리', '반복 작업 자동화' 요청; (2) 'validation 학습', '입력 규칙 학습', 'API 스키마 학습' 요청; (3) 'RPA 작업 등록', 'RPA 실행', 'RPA 스케줄' 요청; (4) 'SR 자동 접수', 'SSL 만료 자동 알림', '정기 점검 자동화' 요청; (5) 'RPA 이력', 'RPA 실행 결과', 'RPA 현황' 조회; (6) 다시 실행, 업데이트, 수정, 보완, 재실행 요청.

GUARDiA ITSM RPA 오케스트레이터

RPA 봇(자동화)과 Validation 학습을 조율하는 통합 워크플로우. 실행 모드: 파이프라인 (에이전트 팀) — validation-learner → rpa-bot → 기존 에이전트 연동.

---

에이전트 팀 구성

에이전트	역할
validation-learner	ITSM API 스키마 스캔 → validation 규칙 DB 저장
rpa-bot	학습 규칙 참조 → ITSM API 자동 호출 실행
incident-responder	RPA 실행 실패 → 인시던트 자동 생성

---

Phase 0: 컨텍스트 확인

사용자 요청 분류:

• 학습 요청 ("validation 학습해줘", "API 스키마 학습") → Phase 1만 실행
• 실행 요청 ("RPA 실행", "자동 처리") → Phase 2 실행 (학습 규칙이 없으면 Phase 1 선행)
• 등록 요청 ("RPA 작업 추가", "봇 등록") → Phase 3 실행
• 조회 요청 ("RPA 현황", "실행 이력") → GET /api/rpa/tasks, GET /api/rpa/executions

---

Phase 1: Validation 학습

validation-learner 서브 에이전트 호출.

# 전체 학습 (최초 또는 엔드포인트 추가 후)
POST /api/rpa/validations/learn
{
  "endpoints": "all",     # 또는 특정 endpoint 목록
  "overwrite": true
}

응답: { learned: N, endpoints: [...] }

학습 순서:

1. FastAPI OpenAPI 스펙 수집: GET /api/openapi.json
2. 각 POST/PUT 엔드포인트의 requestBody.schema 파싱
3. 필드별 rules 추출 → tb_rpa_validation upsert
4. 학습 결과 요약 출력

---

Phase 2: RPA 작업 실행

rpa-bot 에이전트 호출. 실행 전 반드시 validation 확인.

# 단발성 즉시 실행
POST /api/rpa/execute
{
  "task_type": "SR_CREATE" | "SR_STATUS_UPDATE" | "SHELL_EXEC" | "SSL_CHECK",
  "payload": { ... },       # 입력 데이터 (validation 학습 규칙 준수 필수)
  "dry_run": false          # true 시 검증만, API 호출 없음
}

# 스케줄 작업 실행 (등록된 태스크)
POST /api/rpa/tasks/{task_id}/run

실행 흐름:

payload 입력
  → validation 검증 (tb_rpa_validation 규칙)
  → 실패: 오류 필드 + 위반 규칙 상세 반환 (실행 중단)
  → 성공: API 호출
    → 성공: tb_rpa_execution 기록 (SUCCESS)
    → 실패: 재시도 3회 → incident-responder 인시던트 생성

---

Phase 3: RPA 작업 등록/관리

# 작업 등록
POST /api/rpa/tasks
{
  "task_name": "SSL 만료 30일 전 SR 자동 생성",
  "task_type": "SR_CREATE",
  "schedule": "0 9 * * *",           # cron: 매일 09:00
  "payload_template": {
    "sr_type": "INQUIRY",
    "priority": "HIGH",
    "title": "SSL 인증서 만료 예정 점검",
    "description": "{{server_name}} SSL 만료일 {{ssl_expire_date}}"
  },
  "is_active": true
}

# 목록 조회
GET /api/rpa/tasks?page=1&size=20&is_active=true

# 실행 이력
GET /api/rpa/executions?task_id={id}&status=FAILED

---

Phase 4: 결과 보고

실행 완료 후 요약:

• 실행된 RPA 작업 목록
• 성공/실패 건수
• 실패 원인 (validation 오류 or API 오류)
• 생성된 SR/인시던트 ID 목록

---

주요 API 엔드포인트

Method	Path	설명
POST	/api/rpa/validations/learn	Validation 학습 트리거
GET	/api/rpa/validations	학습된 규칙 목록
POST	/api/rpa/tasks	RPA 작업 등록
GET	/api/rpa/tasks	작업 목록
PUT	/api/rpa/tasks/{id}	작업 수정
DELETE	/api/rpa/tasks/{id}	작업 삭제
POST	/api/rpa/tasks/{id}/run	즉시 실행
POST	/api/rpa/execute	단발성 즉시 실행
GET	/api/rpa/executions	실행 이력
GET	/api/rpa/executions/{id}	실행 상세

---

테스트 시나리오

정상 흐름:

1. POST /api/rpa/validations/learn → 전체 학습
2. POST /api/rpa/execute with dry_run: true → validation 통과 확인
3. POST /api/rpa/execute with dry_run: false → 실제 SR 생성
4. GET /api/rpa/executions → 실행 이력 확인

에러 흐름:

1. 필수 필드 누락 → validation 오류: title 필드 필수 반환
2. enum 오류 → sr_type 허용값: DEPLOY|RESTART|LOG|INQUIRY|OTHER 반환
3. API 5xx → 3회 재시도 → incident-responder 인시던트 생성