# GUARDiA ITSM + Messenger — 분석 및 설계서

> **문서번호**: GUARDIA-DS-001  
> **버전**: 1.0  
> **작성일**: 2026-05-25  
> **작성자**: GUARDiA 개발팀  
> **보안등급**: 내부용 (대외비)

---

## 1. 문서 목적

본 문서는 GUARDiA ITSM(IT Service Management) 플랫폼과 GUARDiA Messenger 시스템의 요구사항 분석, 시스템 설계, 데이터 설계, API 설계를 기술한다. 본 문서는 개발자, 운영자, 품질관리자가 시스템을 이해하고 유지보수하는 데 활용한다.

---

## 2. 시스템 개요

### 2-1. GUARDiA ITSM

**GUARDiA ITSM**은 공공기관 IT 운영을 위한 온프레미스 서비스관리 플랫폼이다.

| 항목 | 내용 |
|------|------|
| 목적 | 공공기관 IT 인프라 SR(Service Request) 접수·처리·이력 관리 |
| 운영 방식 | 온프레미스 (인터넷 완전 차단 환경 대응) |
| 주요 사용자 | 운영 엔지니어, PM, 기관 담당자(고객) |
| 기술 스택 | FastAPI, SQLAlchemy (Async), SQLite, Python 3.11+ |
| 인증 방식 | JWT (RS256), 역할 기반 접근 제어 (RBAC) |

### 2-2. GUARDiA Messenger

**GUARDiA Messenger**는 ITSM과 연동되는 사내 메신저로, SR 알림, 봇 명령, 엔지니어 채팅을 지원한다.

| 항목 | 내용 |
|------|------|
| 목적 | 운영팀 실시간 소통 및 ITSM 이벤트 알림 |
| 연동 방식 | GUARDiA ITSM Webhook API |
| 주요 기능 | 채팅, 봇 명령, SR 알림, 공지 |

---

## 3. 요구사항 분석

### 3-1. 기능적 요구사항 (Functional Requirements)

| ID | 분류 | 요구사항 | 우선순위 |
|----|------|----------|---------|
| FR-001 | SR 관리 | SR 접수·파싱·배정·승인·처리·완료 워크플로우 | 필수 |
| FR-002 | SR 관리 | SR 상태 실시간 SSE 이벤트 브로드캐스트 | 필수 |
| FR-003 | 인증 | JWT 기반 역할별 로그인 (ADMIN/PM/ENGINEER/CUSTOMER) | 필수 |
| FR-004 | CMDB | 기관·서버 자산 등록 및 조회 | 필수 |
| FR-005 | SSH | 서버 원격 명령 실행 (asyncssh) | 필수 |
| FR-006 | SSL | SSL 인증서 만료 모니터링 및 갱신 이력 관리 | 필수 |
| FR-007 | PM | 정기 PM 체크리스트 템플릿 및 반복 스케줄 관리 | 필수 |
| FR-008 | 장애 | P1~P4 장애 등록·상태 관리·RCA 기록 | 필수 |
| FR-009 | 당직 | 온콜/당직 일정 관리 | 권장 |
| FR-010 | 배치 | 배치 작업 등록·실행·이력 관리 | 권장 |
| FR-011 | CI/CD | Jenkins 파이프라인 연동 (빌드·배포·콜백) | 선택 |
| FR-012 | 알림 | 이메일(SMTP) + 메신저 Webhook 알림 | 필수 |
| FR-013 | 보고서 | 작업이력·PM결과 Excel 다운로드 | 권장 |
| FR-014 | 감사 | 해시 체인 기반 감사 로그 | 필수 |
| FR-015 | KB | 장애 처리 지식 베이스 문서 관리 | 권장 |
| FR-016 | 상용화 | 라이선스 키 기반 에디션 제어 (COMMUNITY / STANDARD / ENTERPRISE) | 필수 |
| FR-017 | 상용화 | 에디션별 기관·사용자·서버 수량 및 기능(LDAP/PAM/AI/CICD 등) 접근 제한 | 필수 |

### 3-2. 비기능적 요구사항 (Non-Functional Requirements)

| ID | 분류 | 요구사항 |
|----|------|---------|
| NFR-001 | 보안 | AES-256-GCM 서버 자격증명 암호화 |
| NFR-002 | 보안 | API 응답에 IP·SSH계정·비밀번호 절대 미포함 |
| NFR-003 | 보안 | root SSH 직접 접속 차단 |
| NFR-004 | 보안 | 명령어 안전성 검증 (위험 패턴 차단) |
| NFR-005 | 가용성 | 99% 이상 가용성 목표 |
| NFR-006 | 성능 | API 응답 시간 500ms 이하 (DB 조회 기준) |
| NFR-007 | 호환성 | RHEL 8/9, CentOS 7/8, Ubuntu 20.04/22.04 |
| NFR-008 | 호환성 | Windows Server 2019/2022 |
| NFR-009 | 격리 | 외부 인터넷 완전 차단 환경 동작 가능 |
| NFR-010 | 감사 | 모든 SR 처리 이력 블록체인형 해시 체인 보존 |

---

## 4. 시스템 아키텍처

### 4-1. 전체 구성도

```
┌─────────────────────────────────────────────────────────────────┐
│                        클라이언트 레이어                           │
│  ┌──────────────┐  ┌──────────────┐  ┌────────────────────────┐ │
│  │  웹 브라우저  │  │  모바일 앱    │  │  GUARDiA Messenger     │ │
│  └──────┬───────┘  └──────┬───────┘  └──────────┬─────────────┘ │
└─────────┼─────────────────┼─────────────────────┼───────────────┘
          │  HTTPS          │  HTTPS              │  WebSocket/HTTP
┌─────────▼─────────────────▼─────────────────────▼───────────────┐
│                        API 게이트웨이 레이어                        │
│                 Nginx (Reverse Proxy + TLS Termination)          │
└─────────────────────────────┬───────────────────────────────────┘
                              │ HTTP (내부)
┌─────────────────────────────▼───────────────────────────────────┐
│                        애플리케이션 레이어                          │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │              GUARDiA ITSM (FastAPI)                     │  │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐  │  │
│  │  │ SR 관리   │ │ SSH 실행  │ │ SSL 감시  │ │ PM 관리   │  │  │
│  │  │ tasks    │ │ ssh_exec │ │ssl_mgr   │ │   pm     │  │  │
│  │  └──────────┘ └──────────┘ └──────────┘ └───────────┘  │  │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐  │  │
│  │  │ 장애관리  │ │ 배치작업  │ │ CI/CD    │ │ Scheduler │  │  │
│  │  │incidents │ │  batch   │ │  cicd    │ │(APSchedul)│  │  │
│  │  └──────────┘ └──────────┘ └──────────┘ └───────────┘  │  │
│  └──────────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │              GUARDiA Messenger (FastAPI)                 │  │
│  └──────────────────────────────────────────────────────────┘  │
└──────────────────────────────┬──────────────────────────────────┘
                               │ SQLAlchemy (Async)
┌──────────────────────────────▼──────────────────────────────────┐
│                        데이터 레이어                               │
│  SQLite (개발/소규모)  →  PostgreSQL (운영 권장)                    │
└─────────────────────────────────────────────────────────────────┘
                               │ asyncssh
┌──────────────────────────────▼──────────────────────────────────┐
│                       대상 서버 레이어                              │
│  WEB (Nginx/Apache)  WAS (Tomcat/JBoss)  DB (PostgreSQL/Oracle) │
└─────────────────────────────────────────────────────────────────┘
```

### 4-2. GUARDiA ITSM 컴포넌트 설명

| 컴포넌트 | 파일 | 역할 |
|---------|------|------|
| 진입점 | `main.py` | FastAPI 앱, 라우터 등록, lifespan |
| ORM/스키마 | `models.py` | SQLAlchemy 모델 + Pydantic 스키마 |
| DB 세션 | `database.py` | AsyncSession 팩토리 |
| 인증 | `core/auth.py` | JWT 발급/검증 |
| SSH 실행 | `core/ssh_exec.py` | asyncssh 기반 원격 실행 |
| 알림 | `core/notify.py` | SMTP + Messenger Webhook |
| 스케줄러 | `core/scheduler.py` | SSL/PM/계약 만료 자동 감시 |
| Jenkins 클라이언트 | `core/cicd.py` | Jenkins REST API |
| 시드 데이터 | `core/seed.py` | 초기 데이터 자동 생성 |
| 라이선스 엔진 | `core/license.py` | AES-256-GCM 라이선스 생성·검증·캐싱 |
| 라이선스 가드 | `middleware/license_guard.py` | 에디션별 기관·서버·기능 접근 제한 Dependency |

### 4-3. GUARDiA Messenger 컴포넌트

```
C:\GUARDiA\messenger\
├── core/         실시간 채팅 엔진
├── models/       메시지·사용자·채널 ORM
└── main.py       WebSocket + REST API
```

---

## 5. 데이터 설계

### 5-1. 전체 테이블 목록 (27개)

| 번호 | 테이블명 | 설명 | 관련 기능 |
|-----|---------|------|---------|
| 1 | `tb_user` | 시스템 사용자 | 인증 |
| 2 | `tb_inst_meta` | 기관 메타정보 | CMDB |
| 3 | `tb_inst_contact` | 기관 담당자 연락처 | CMDB |
| 4 | `tb_server_info` | 서버 자산 (암호화) | CMDB/SSH |
| 5 | `tb_sr_request` | SR 마스터 | SR관리 |
| 6 | `tb_sr_approval` | SR 승인 이력 | 승인 |
| 7 | `tb_work_log` | 작업 실행 로그 | 작업 |
| 8 | `tb_audit_log` | 감사 로그 (해시체인) | 감사 |
| 9 | `tb_rating` | 만족도 평가 | 고객 |
| 10 | `tb_shell_script` | SM 스크립트 메타 | 자동화 |
| 11 | `tb_work_timetable` | 작업 일정표 | 타임테이블 |
| 12 | `tb_sr_attachment` | SR 첨부파일 | 첨부 |
| 13 | `tb_notification_log` | 알림 이력 | 알림 |
| 14 | `tb_kb_document` | 지식 베이스 | KB |
| 15 | `tb_engineer_profile` | 엔지니어 스킬 | 자동배정 |
| 16 | `tb_project` | CI/CD 프로젝트 | 배포 |
| 17 | `tb_vibe_session` | 바이브 코딩 세션 | CI/CD |
| 18 | `tb_ssl_history` | SSL 갱신 이력 | SSL |
| 19 | `tb_pm_template` | PM 체크리스트 템플릿 | PM |
| 20 | `tb_pm_schedule` | PM 반복 스케줄 | PM |
| 21 | `tb_pm_result` | PM 점검 결과 | PM |
| 22 | `tb_incident` | 장애 마스터 | 장애관리 |
| 23 | `tb_incident_sr` | 장애↔SR 연결 | 장애관리 |
| 24 | `tb_oncall_schedule` | 온콜/당직 일정 | 당직 |
| 25 | `tb_batch_job` | 배치 작업 | 배치 |
| 26 | `tb_batch_run` | 배치 실행 이력 | 배치 |
| 27 | `tb_license` | 라이선스 등록 이력 | 상용화 라이선스 관리 |

### 5-2. 핵심 테이블 ERD (텍스트 형식)

```
tb_inst_meta (1) ──< (N) tb_server_info
                          │
tb_inst_meta (1) ──< (N) tb_sr_request ──< (N) tb_sr_approval
                                          ──< (N) tb_work_log
                                          ──< (N) tb_audit_log
                                          ──< (N) tb_sr_attachment
                                          ──< (N) tb_ops_task

tb_sr_request (N) >──< (N) tb_incident  (via tb_incident_sr)

tb_server_info (1) ──< (N) tb_ssl_history
tb_server_info (1) ──< (N) tb_batch_job

tb_pm_template (1) ──< (N) tb_pm_result
tb_work_timetable (1) ──< (N) tb_pm_result
```

### 5-3. SR 상태 머신

```
RECEIVED ──→ PARSED ──→ PENDING_APPROVAL ──→ APPROVED ──→ IN_PROGRESS
                                          └──→ REJECTED
                                                  ↓
IN_PROGRESS ──→ PENDING_PM_VALIDATION ──→ COMPLETED
                                      └──→ FAILED_ROLLBACK
```

---

## 6. API 설계

### 6-1. 인증 방식

```
POST /api/auth/login
요청: { "username": "admin", "password": "****" }
응답: { "access_token": "eyJ...", "token_type": "bearer" }

이후 모든 API 요청 헤더:
Authorization: Bearer eyJ...
```

### 6-2. 주요 API 목록

| 분류 | 메서드 | 경로 | 역할 |
|------|--------|------|------|
| 인증 | POST | `/api/auth/login` | 로그인 |
| SR | GET/POST | `/api/tasks` | SR 목록/생성 |
| SR | PATCH | `/api/tasks/{id}/status` | 상태 변경 |
| SSL | GET | `/api/ssl/expiring` | 만료 임박 목록 |
| SSL | POST | `/api/ssl/check/{id}` | SSH 점검 |
| SSL | POST | `/api/ssl/renew/{id}` | 갱신 기록 |
| PM | GET/POST | `/api/pm/templates` | 체크리스트 템플릿 |
| PM | POST | `/api/pm/schedules/{id}/trigger` | PM 실행 |
| 장애 | GET/POST | `/api/incidents` | 장애 관리 |
| 당직 | GET | `/api/oncall/today` | 오늘 당직자 |
| 배치 | POST | `/api/batch/jobs/{id}/run` | 배치 실행 |

### 6-3. 오류 응답 형식

```json
{
  "detail": "오류 요약 메시지 (IP, 스택트레이스 미포함)"
}
```

---

## 7. 보안 설계

### 7-1. 자격증명 암호화

```
평문 비밀번호
    │
    ▼ AES-256-GCM (12바이트 nonce + 암호문)
    │
    ▼ Base64 인코딩
    │
tb_server_info.os_pw_enc 컬럼 저장
```

암호화 키: `GUARDIA_ENC_KEY` 환경변수 (32바이트)

### 7-2. JWT 보안

- 알고리즘: HS256
- 만료: 8시간 (기본값, 환경변수로 조정 가능)
- 저장: 클라이언트 메모리 (localStorage 사용 금지 권고)

### 7-3. SSH 보안

- root 계정 직접 접속 금지 (`ssh_user ≠ root` 검증)
- known_hosts 검증 (운영 환경 필수)
- 위험 명령어 패턴 차단:
  - `rm -rf /`, `mkfs`, `dd if=`, `shutdown`, `reboot` 등

### 7-4. API 응답 보안

`ServerOut` 스키마에서 민감정보 제외:
- `ip_addr` — 미포함
- `ssh_user` — 미포함
- `os_pw_enc` — 미포함

### 7-5. 감사 로그 무결성

각 감사 로그 항목은 이전 항목의 해시값을 포함하는 체인 구조:
```
log_hash = SHA256(prev_hash + actor + action + detail + timestamp)
```

---

## 8. 배포 구성

### 8-1. 운영 환경 권장 구성

```
인터넷
    │ (차단)
    ▼
[Nginx] :443 ──TLS──→ [GUARDiA ITSM] :8000
                  ──TLS──→ [GUARDiA Messenger] :8001

[GUARDiA ITSM] ──asyncssh──→ [관리 대상 서버들]
[GUARDiA ITSM] ──SMTP──→ [내부 메일 서버]
```

### 8-2. 최소 서버 사양

| 항목 | 최소 | 권장 |
|------|------|------|
| CPU | 2 코어 | 4 코어 |
| 메모리 | 4 GB | 8 GB |
| 디스크 | 50 GB | 100 GB |
| OS | RHEL 8 이상 / Ubuntu 20.04 이상 | RHEL 9 / Ubuntu 22.04 |
| Python | 3.10 이상 | 3.11 |

---

## 9. GUARDiA Messenger 설계

### 9-1. 주요 기능

| 기능 | 설명 |
|------|------|
| 채팅 | 1:1 및 그룹 채팅 |
| 봇 명령 | `!vibe`, `!build`, `!deploy`, `!sr`, `!health` 등 |
| SR 알림 | ITSM SR 상태 변경 시 자동 알림 |
| 파일 전송 | 이미지·문서 공유 |

### 9-2. 봇 명령어 목록

| 명령어 | 설명 | 예시 |
|--------|------|------|
| `!sr <내용>` | SR 빠른 접수 | `!sr WAS 응답 없음` |
| `!status <SR번호>` | SR 상태 조회 | `!status SR-20260525-AA1234` |
| `!health <서버명>` | 서버 헬스체크 | `!health MOF-WAS-01` |
| `!oncall` | 오늘 당직자 조회 | `!oncall` |
| `!pm <스케줄명>` | PM 즉시 실행 | `!pm 기재부 월간점검` |
| `!ssl <도메인>` | SSL 만료 확인 | `!ssl csv.culture.go.kr` |

---

## 10. 변경 이력

| 버전 | 날짜 | 내용 | 작성자 |
|------|------|------|--------|
| 1.0 | 2026-05-25 | 최초 작성 | 개발팀 |