---
name: rpa-orchestrator
description: "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 인시던트 생성