zioinfo-mail/docs/ARCHITECTURE.md

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 ✅ (완료)

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

Phase 2 ✅ (완료)

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