# GUARDiA 통합 플랫폼 아키텍처

> AI 오케스트레이터와 인간 엔지니어 간의 협업(Human-in-the-Loop)을 핵심으로 하는
> 폐쇄망 인프라 자동화 플랫폼

---

## 1. 시스템 철학

GUARDiA는 **"AI가 작업을 수행하고, 엔지니어가 AI의 판단을 검토·명령하며, 대시보드가 이를 가시화"** 하는 구조다.

- **ChatOps 기반**: 메신저 한 곳에서 SR 접수 → 실행 → 결과 확인까지 완결
- **에이전트리스**: SSH/SFTP(paramiko)만 사용 — 대상 서버에 에이전트 설치 없음
- **폐쇄망 우선**: 외부 API 호출 절대 금지 / on-premise sLLM(Ollama) 사용
- **HITL 필수**: 민감 작업은 반드시 인간 승인 거침

---

## 2. 3계층 아키텍처

```
┌─────────────────────────────────────────────────────────┐
│  INTAKE LAYER  (접수)                                    │
│  메신저 Webhook · 고객 포털 (/customer) · 이메일        │
│  → SR 자동 생성 · sLLM 의도 분류                        │
└────────────────────┬────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────────────┐
│  CONTROL LAYER  (제어/거버넌스)                          │
│  sLLM 파서 (자연어 → JSON) · RBAC 승인 엔진             │
│  HITL: PM/팀장/보안책임자 다단계 승인                   │
│  AI 명령 인터페이스 (자연어 Override)                   │
└────────────────────┬────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────────────────┐
│  EXECUTION LAYER  (실행)                                 │
│  SSH/SFTP 에이전트리스 엔진 (paramiko)                  │
│  CMDB 자산 조회 → 명령 실행 → 헬스체크 → 결과 기록     │
│  SHA-256 해시 체인 감사 로그                            │
└─────────────────────────────────────────────────────────┘
```

---

## 3. SR 상태 머신

```
RECEIVED → PARSED → PENDING_APPROVAL → APPROVED → IN_PROGRESS
                                                        ↓
                                          PENDING_PM_VALIDATION
                                           ↙              ↘
                                      COMPLETED     FAILED_ROLLBACK
```

- **PENDING_APPROVAL**: 팀장/PM/보안책임자 승인 대기
- **IN_PROGRESS**: AI 에이전트 SSH 실행 중
- **FAILED_ROLLBACK**: 실행 실패 시 자동 롤백 + Kill-Switch 트리거

---

## 4. 서비스 구성

| 서비스 | 포트 | 역할 |
|--------|------|------|
| GUARDiA Messenger | 8000 | ChatOps 채널 · 실시간 WebSocket |
| GUARDiA ITSM | 8001 | SR 관리 · 워크플로우 · CMDB |
| Ollama (sLLM) | 11434 | 챗봇 AI (llama3:8b-instruct) |

---

## 5. 완료 알림 흐름 (ITSM ↔ 메신저 연동)

```
고객 포털 SR 등록
    ↓
ITSM 엔지니어/AI: CMDB 확인 → SSH 실행 → 결과 기록
    ↓
SR 상태 → COMPLETED
    ↓
ITSM → POST /api/messenger/webhook { event: "itsm_complete" }
    ↓
메신저 ops 채널: GUARDiA-Bot 완료 메시지 + ★★★★★ 별점 위젯
    ↓
고객 별점 클릭 → ITSM /api/rating/{sr_id} 저장
```

---

## 6. 보안 아키텍처

| 항목 | 구현 |
|------|------|
| 서버 자격증명 | AES-256-GCM 암호화 저장 (`os_pw_enc`), API 응답 미노출 |
| SSH 접근 | opsagent 전용 계정, root 직접 접속 금지 |
| 감사 로그 | SHA-256 해시 체인 (위변조 자동 감지) |
| Kill-Switch | 메신저 `정지` 명령 → 전체 작업 즉시 중단 + 롤백 |
| 에러 응답 | 스택트레이스 미노출, SR ID + 요약만 전달 |

---

## 7. CMDB 마스터 테이블

| 테이블 | 역할 |
|--------|------|
| TB_INST_META | 기관 정보 (기관코드, PM 담당자) |
| TB_SERVER_INFO | 서버 정보 (역할, OS, 암호화된 자격증명) |
| TB_SR_REQUEST | SR 요청 및 상태 |
| TB_APPROVAL_FLOW | 승인 워크플로우 이력 |
| TB_WORK_LOG | 작업 실행 단계별 로그 |
| TB_AUDIT_LOG | SHA-256 해시 체인 감사 기록 |
| TB_RATING | 고객 만족도 평가 |

---

## 8. 구현 로드맵

### Phase 1 ✅ (완료)
- [x] ChatOps 메신저 (WebSocket 실시간)
- [x] AI 챗봇 (Ollama + 지식베이스 폴백)
- [x] ITSM SR 상태 머신 + 칸반 보드
- [x] CMDB 기관/서버 관리
- [x] SHA-256 해시 체인 감사 로그
- [x] PM 승인 워크플로우
- [x] 고객 포털 SR 등록 + 처리 현황 조회
- [x] AI 작업 실행 시뮬레이션 (CMDB→SSH→결과)
- [x] ITSM→메신저 완료 알림 연동
- [x] 메신저 별점 위젯 → ITSM 평가 저장

### Phase 2 ✅ (완료)
- [x] JWT 로그인 시스템 (ADMIN / PM / ENGINEER / CUSTOMER 역할 분리)
- [x] 역할별 맞춤 대시보드 (KPI, 액션 아이템, 워크로드)
- [x] 엔지니어 자동 배정 (Round-Robin, 워크로드 균형)
- [x] RAG 기술 문서 KB 검색
- [x] AI 자연어 명령 인터페이스
- [x] SSE 실시간 대시보드 (브로드캐스트 이벤트 버스)
- [x] 7일 SR 추이 차트 (순수 SVG, 외부 라이브러리 불필요)
- [x] Nifty 다크 테마 + 라이트/미드나잇 테마 전환
- [x] FOUC 방지 테마 즉시 적용

### Phase 3 🔜 (현재 진행)
- [ ] **기관(사이트) + 담당자 등록관리** (이메일, 전화번호 포함)
  - `TB_INST_META` 확장 (계약기간, SLA, 지역)
  - `TB_INST_CONTACT` 신규 (담당자 이메일/전화)
  - ITSM 사용자 확장 (이메일, 부서, 직책)
  - `/api/institutions` CRUD 라우터
  - 프론트엔드 기관 관리 화면

- [ ] **서버 자산 관리 확장** (SSH 방법, OS, WEB/WAS/DB 유지보수 정보)
  - `TB_SERVER_INFO` 확장 (ssh_method, web/was/db 버전·경로, ssl_expire, eol_date 등)
  - 서버 자산 상세 뷰 + 수정 모달
  - SSL/EOL 만료 임박 경고 뱃지

- [ ] **쉘 스크립트 라이브러리 관리**
  - `TB_SHELL_SCRIPT` 신규 테이블
  - CRUD 라우터 `/api/shell-scripts`
  - 스크립트 에디터 (코드 하이라이트 적용)
  - 카테고리별 필터링 (SM/정기/수시/배포/보안/모니터링)

- [ ] **작업 타임테이블 + Excel 다운로드**
  - `TB_WORK_TIMETABLE` 신규 테이블
  - CRUD 라우터 `/api/timetable`
  - 달력형 + 목록형 뷰 전환
  - Excel 다운로드 (`openpyxl`, on-premise)
  - 기간/기관/유형별 필터

### Phase 4 🔜 (자율 운영)
- [ ] 실제 SSH/SFTP 실행 엔진 (paramiko)
- [ ] Self-Healing 크론탭 (헬스체크, SSL 만료 감시)
- [ ] Multi-step 승인 (팀장→PM→보안책임자 체인)
- [ ] 계약 만료 / SSL 만료 사전 알림 자동화
- [ ] 월간 보고서 자동 생성 (타임테이블 → Excel → 이메일)