guardia-docs/44_신규기능_운영가이드.md

# GUARDiA 신규 기능 운영 가이드

**문서 버전**: 1.0  
**작성일**: 2026-06-02  
**대상**: 시스템 운영자, IT 관리자  
**관련 시스템**: GUARDiA ITSM · Manager · Messenger · Webmail

---

## 목차

1. [모바일 앱 QR 직접 배포](#1-모바일-앱-qr-직접-배포)
2. [배치 SSH 일괄 실행](#2-배치-ssh-일괄-실행)
3. [자산 QR 태그 관리](#3-자산-qr-태그-관리)
4. [스마트 알림 규칙 편집기](#4-스마트-알림-규칙-편집기)
5. [웹메일 주소록 · 서명 관리](#5-웹메일-주소록--서명-관리)
6. [신규 API 엔드포인트 목록](#6-신규-api-엔드포인트-목록)

---

## 1. 모바일 앱 QR 직접 배포

### 1.1 개요

공공기관은 Google Play Store · Apple App Store 등록 절차가 복잡하고 시간이 오래 걸립니다.  
GUARDiA Manager에서 APK를 직접 업로드하면 **QR 코드가 즉시 생성**되고,  
사용자는 QR 스캔만으로 GUARDiA Messenger를 설치할 수 있습니다.

```
관리자 (Manager)
    ↓ APK 파일 업로드
ITSM 서버 저장 (/opt/guardia/app/uploads/apk/)
    ↓ QR 코드 자동 생성 (랜딩 페이지 URL 인코딩)
QR 이미지 표시 (PNG, #003366 색상)
    ↓
사용자: QR 스캔 → 랜딩 페이지 → Android 다운로드 버튼 클릭
    ↓ APK 다운로드 · 설치 (Play Store 불필요)
GUARDiA Messenger 설치 완료
```

### 1.2 관리자 화면에서 APK 배포

1. `https://zioinfo.co.kr:8090` (GUARDiA Manager) 접속 → 로그인
2. 좌측 사이드바 하단 **📱 앱 배포** 클릭
3. "새 버전 배포" 영역:
   - **버전**: 예) `1.2.3`
   - **APK 파일**: `.apk` 파일 선택 (최대 200MB)
   - **iOS URL** (선택): TestFlight 링크
   - **업데이트 내용**: 변경사항 입력
4. **🚀 배포 + QR 생성** 클릭
5. 상단에 QR 코드 이미지와 랜딩 페이지 링크가 표시됩니다.

> **외부 URL 방식**: EAS 빌드 APK URL 등 외부 링크가 있으면  
> "외부 URL 연결" 탭에서 URL 입력 → QR 생성 가능합니다.

### 1.3 사용자 앱 설치 방법 (Android)

1. GUARDiA Manager에서 QR 이미지 출력 또는 화면 공유
2. Android 기기로 QR 스캔 (카메라 앱 또는 GUARDiA Messenger 앱)
3. 랜딩 페이지 열림 → **"Android 다운로드 (APK)"** 버튼 클릭
4. APK 파일 다운로드 완료 후:
   - 설정 → 보안 → **"알 수 없는 출처"** 허용 (최초 1회)
   - 다운로드된 APK 파일 실행 → 설치
5. GUARDiA Messenger 실행 → 서버 주소 입력 후 로그인

### 1.4 버전 관리

| 작업 | 방법 |
|------|------|
| 최신 버전 확인 | Manager → 앱 배포 → 상단 "현재 최신 버전" 카드 |
| 이전 버전 삭제 | 버전 이력 테이블 → "삭제" 버튼 (최신 버전은 삭제 불가) |
| 다운로드 통계 | 상단 통계 카드: 총 다운로드·Android·iOS 횟수 |

### 1.5 관련 API

| 엔드포인트 | 설명 |
|-----------|------|
| `POST /api/app/upload` | APK 업로드 (multipart/form-data) |
| `GET  /api/app/latest` | 최신 버전 정보 + QR URL |
| `GET  /api/app/qr?token=xxx` | QR 코드 PNG 이미지 (인증 불필요) |
| `GET  /api/app/landing?token=xxx` | 다운로드 랜딩 페이지 (인증 불필요) |
| `GET  /api/app/versions` | 버전 이력 목록 |
| `GET  /api/app/stats` | 다운로드 통계 |

---

## 2. 배치 SSH 일괄 실행

### 2.1 개요

여러 서버에 **동시에 동일한 SSH 명령을 실행**하고 결과를 한눈에 확인합니다.  
점검, 패치, 모니터링 명령을 수동으로 서버마다 반복 실행할 필요가 없습니다.

**주요 사용 사례:**
- 전체 서버 디스크 사용량 일괄 점검: `df -h /`
- 모든 Tomcat 서버 스레드 수 확인: `ps aux | grep tomcat | wc -l`
- 동시 패치 적용 상태 확인: `rpm -q <패키지명>`
- 로그 파일 존재 여부 확인: `ls -lh /app/logs/error.log`

### 2.2 사용 방법

#### ITSM 화면에서 실행
1. GUARDiA ITSM (`https://zioinfo.co.kr:8443`) → 로그인
2. 좌측 사이드바 → **⚡ 배치 SSH 실행** 클릭
3. 폼 입력:
   - **명령어**: 실행할 셸 명령 (단일 명령 또는 세미콜론 구분)
   - **서버 목록**: 서버 ID 또는 태그 (콤마 구분, 예: `1,2,3` 또는 `web,db`)
   - **타임아웃(초)**: 기본 30초
4. **⚡ 실행** 클릭
5. 결과 카드 확인: 서버별 성공/실패·stdout·stderr 표시

#### API 직접 호출
```bash
curl -X POST https://zioinfo.co.kr:8443/api/batch-ssh/run \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "df -h /",
    "server_ids": ["1", "2", "3"],
    "timeout_sec": 30
  }'
```

### 2.3 보안 제약

다음 명령어는 **위험 패턴**으로 차단됩니다:

```
rm -rf /      mkfs       dd if=/dev/zero    shutdown
halt          reboot     > /etc/passwd      chmod 777 /
```

> 위험 패턴이 포함된 명령은 실행 전 거부되며 감사 로그에 기록됩니다.

### 2.4 실행 이력

- ITSM → 배치 SSH 실행 → 하단 "실행 이력" 테이블에서 확인
- API: `GET /api/batch-ssh/jobs?limit=20`

---

## 3. 자산 QR 태그 관리

### 3.1 개요

서버·네트워크 장비 등 물리 자산에 **QR 라벨을 부착**하여  
Messenger 앱으로 스캔하면 CMDB 정보를 즉시 확인하고 **실사 체크인**을 자동화합니다.

```
운영자
    ↓ ITSM에서 서버별 QR 토큰 생성
QR 라벨 인쇄 (50×30mm)
    ↓ 장비에 라벨 부착
현장 점검 시:
    GUARDiA Messenger → QR 탭 → QR 스캔
    ↓
서버 CMDB 정보 즉시 표시 (이름·OS·위치·상태)
    ↓ "실사 체크인" 버튼 클릭
실사 완료 기록 자동 저장
```

### 3.2 QR 토큰 생성 (관리자)

1. ITSM → 좌측 사이드바 → **🏷️ 자산 QR 태그**
2. "서버 ID" 입력 → **🏷️ QR 생성** 클릭
3. QR 이미지와 토큰 UUID가 표시됩니다.
4. **🖨️ 라벨 인쇄** 링크 클릭 → 50×30mm HTML 라벨 인쇄

```bash
# API로 생성
POST /api/asset-qr/generate/{server_id}
Authorization: Bearer <JWT>

# 라벨 HTML 조회 (인쇄용)
GET /api/asset-qr/label/{qr_token}   # 인증 불필요
```

### 3.3 Messenger 앱에서 스캔

1. GUARDiA Messenger 실행
2. 하단 탭바 → **📷 QR** 탭 선택
3. 장비 라벨의 QR 코드 스캔
4. 서버 정보 확인 (이름·IP·OS·위치·상태)
5. **📋 실사 체크인** 버튼 → 체크인 완료

> **토큰 직접 입력**: QR 스캔 대신 "⌨️ 토큰 입력" 탭에서 UUID를 직접 입력해도 됩니다.

### 3.4 스캔 이력 조회

```bash
GET /api/asset-qr/audit-log/{server_id}
Authorization: Bearer <JWT>
```

응답 예시:
```json
[
  {"scanned_at": "2026-06-02T10:30:00", "scanned_by": "홍길동", "checkin": true, "note": "모바일 실사"},
  {"scanned_at": "2026-06-01T14:20:00", "scanned_by": "김엔지니어", "checkin": false}
]
```

---

## 4. 스마트 알림 규칙 편집기

### 4.1 개요

**노코드 방식**으로 알림 규칙을 정의합니다.  
조건이 AND 모두 충족될 때 지정된 채널로 알림을 발송합니다.  
Ollama AI가 알림 중요도를 재평가하여 **알림 피로도를 자동 관리**합니다.

### 4.2 규칙 생성 (Manager)

1. Manager → 좌측 사이드바 → **🔔 알림 규칙**
2. **+ 규칙 추가** 클릭
3. 설정:

| 항목 | 설명 | 예시 |
|------|------|------|
| 규칙 이름 | 식별 이름 | `CRITICAL SR 즉시 알림` |
| 조건 | field + 연산자 + 값 | `sr_priority == CRITICAL` |
| 알림 채널 | 메신저·이메일·SMS | `messenger, email` |
| 우선순위 필터 | HIGH 이상만 등 | `CRITICAL` |
| 무음 시작/종료 | 야간 알림 차단 | `22:00 ~ 08:00` |
| 다이제스트 모드 | 묶음 발송 | ON/OFF |

4. **저장** → 즉시 활성화

#### 사용 가능한 조건 필드

| 필드 | 설명 | 예시 값 |
|------|------|---------|
| `sr_priority` | SR 우선순위 | `CRITICAL`, `HIGH`, `MEDIUM`, `LOW` |
| `sr_category` | SR 카테고리 | `INCIDENT`, `CHANGE`, `PROBLEM` |
| `sr_status` | SR 상태 | `RECEIVED`, `IN_PROGRESS` |
| `server_cpu` | CPU 사용률 (%) | `90` |
| `server_memory` | 메모리 사용률 (%) | `85` |
| `server_disk` | 디스크 사용률 (%) | `80` |
| `tenant_id` | 특정 기관 알림 | `1` |

#### 지원 연산자

`==` `!=` `>` `>=` `<` `<=` `contains`

### 4.3 규칙 관리 (ITSM)

1. ITSM → 좌측 사이드바 → **🔔 스마트 알림 규칙**
2. 등록된 규칙 목록 확인 (활성/비활성 배지)
3. **테스트** 버튼 → 실제 발송 없이 동작 검증
4. **활성화/비활성화** 토글로 즉시 제어

### 4.4 다이제스트 모드

같은 규칙이 단시간에 여러 번 트리거될 때 알림을 묶어서 발송합니다.

```
규칙: CRITICAL SR 알림 (다이제스트 ON, 60분 간격)

09:00 CRITICAL SR-001 발생
09:15 CRITICAL SR-002 발생
09:45 CRITICAL SR-003 발생
    ↓
10:00 [다이제스트] "지난 1시간 CRITICAL SR 3건: SR-001, SR-002, SR-003"
```

---

## 5. 웹메일 주소록 · 서명 관리

### 5.1 주소록

#### 자동 저장
메일 발송 시 수신자가 자동으로 주소록에 저장됩니다.  
자주 연락하는 사람일수록 자동완성 목록 상단에 표시됩니다.

#### 수동 추가
1. 웹메일 (`https://mail.zioinfo.co.kr:8025`) 접속
2. 사이드바 → **주소록** 탭
3. **+ 추가** 버튼 → 이름·이메일·전화번호·회사 입력

#### 메일 작성 시 자동완성
- 수신자 필드에 이름 또는 이메일 앞 글자 입력
- 주소록 자동완성 목록 표시 → 클릭으로 선택

#### API

```bash
GET  /api/contacts?q=홍&limit=8      # 검색
POST /api/contacts                    # 추가
PUT  /api/contacts/{id}               # 수정
DELETE /api/contacts/{id}             # 삭제
POST /api/contacts/auto-save          # 자동 저장 (메일 발송 후 호출)
```

### 5.2 HTML 서명

#### 서명 만들기
1. 웹메일 → 사이드바 → **서명** 탭
2. **+ 새 서명** 클릭
3. 프리셋 선택 또는 HTML 직접 입력:

```html
<div style="font-family:sans-serif;font-size:13px;color:#374151;
            border-top:2px solid #003366;padding-top:10px;margin-top:10px">
  <strong style="font-size:14px">홍길동</strong> | 지오정보기술(주)<br>
  📧 hong@zioinfo.co.kr &nbsp;|&nbsp; 📞 02-0000-0000<br>
  🌐 www.zioinfo.co.kr
</div>
```

4. **미리보기** 탭에서 렌더링 확인
5. **기본 서명으로 설정** → 메일 작성 시 자동 삽입

#### 보안 처리
- `<script>`, `<iframe>`, `on*` 이벤트 핸들러 자동 제거
- XSS 필터링 후 저장 (DOMPurify 적용)

#### API

```bash
GET    /api/signature                # 서명 목록
POST   /api/signature                # 생성
PUT    /api/signature/{id}           # 수정
PATCH  /api/signature/{id}/default   # 기본 서명 설정
DELETE /api/signature/{id}           # 삭제
```

---

## 6. 신규 API 엔드포인트 목록

> 전체 엔드포인트: `https://zioinfo.co.kr:8443/docs`

### 6.1 모바일 앱 배포 (`/api/app/`)

| 메서드 | 경로 | 인증 | 설명 |
|--------|------|------|------|
| POST | `/api/app/upload` | Admin | APK 업로드 + QR 생성 |
| POST | `/api/app/url` | Admin | 외부 URL로 QR 생성 |
| GET  | `/api/app/latest` | 필요 | 최신 버전 정보 |
| GET  | `/api/app/qr` | 불필요 | QR 이미지 PNG |
| GET  | `/api/app/landing` | 불필요 | 다운로드 랜딩 페이지 |
| GET  | `/api/app/download` | 불필요 | APK 파일 다운로드 |
| GET  | `/api/app/versions` | 필요 | 버전 이력 |
| DELETE | `/api/app/versions/{id}` | Admin | 버전 삭제 |
| GET  | `/api/app/stats` | 필요 | 다운로드 통계 |

### 6.2 배치 SSH (`/api/batch-ssh/`)

| 메서드 | 경로 | 설명 |
|--------|------|------|
| POST | `/api/batch-ssh/run` | 다중 서버 동시 실행 |
| GET  | `/api/batch-ssh/jobs` | 실행 이력 목록 |
| GET  | `/api/batch-ssh/jobs/{id}` | 특정 작업 결과 |
| POST | `/api/batch-ssh/stop/{id}` | 실행 중단 |

### 6.3 자산 QR (`/api/asset-qr/`)

| 메서드 | 경로 | 인증 | 설명 |
|--------|------|------|------|
| POST | `/api/asset-qr/generate/{server_id}` | 필요 | QR 토큰 생성 |
| GET  | `/api/asset-qr/scan/{qr_token}` | 필요 | QR 스캔 (서버 정보) |
| POST | `/api/asset-qr/checkin/{qr_token}` | 필요 | 실사 체크인 |
| GET  | `/api/asset-qr/label/{qr_token}` | 불필요 | 라벨 HTML (인쇄용) |
| GET  | `/api/asset-qr/batch-print` | 필요 | 일괄 라벨 인쇄 |
| GET  | `/api/asset-qr/list` | 필요 | QR 토큰 목록 |
| GET  | `/api/asset-qr/audit-log/{server_id}` | 필요 | 스캔 이력 |

### 6.4 스마트 알림 (`/api/smart-notify/`)

| 메서드 | 경로 | 설명 |
|--------|------|------|
| GET    | `/api/smart-notify/rules` | 규칙 목록 |
| POST   | `/api/smart-notify/rules` | 규칙 생성 |
| PUT    | `/api/smart-notify/rules/{id}` | 규칙 수정 |
| DELETE | `/api/smart-notify/rules/{id}` | 규칙 삭제 |
| POST   | `/api/smart-notify/rules/{id}/test` | 테스트 발송 |
| PATCH  | `/api/smart-notify/rules/{id}/toggle` | 활성화 토글 |
| GET    | `/api/smart-notify/logs` | 발송 이력 |

### 6.5 웹메일 주소록/서명 (`/api/contacts/`, `/api/signature/`)

| 메서드 | 경로 | 설명 |
|--------|------|------|
| GET    | `/api/contacts` | 주소록 목록·검색 |
| POST   | `/api/contacts` | 연락처 추가 |
| PUT    | `/api/contacts/{id}` | 연락처 수정 |
| DELETE | `/api/contacts/{id}` | 연락처 삭제 |
| POST   | `/api/contacts/auto-save` | 발송 후 자동 저장 |
| GET    | `/api/signature` | 서명 목록 |
| POST   | `/api/signature` | 서명 생성 |
| PUT    | `/api/signature/{id}` | 서명 수정 |
| PATCH  | `/api/signature/{id}/default` | 기본 서명 설정 |
| DELETE | `/api/signature/{id}` | 서명 삭제 |

---

## 변경 이력

| 날짜 | 버전 | 변경 내용 |
|------|------|-----------|
| 2026-06-02 | 1.0 | 최초 작성 — 신규 기능 5종 (APK QR 배포, 배치 SSH, 자산 QR, 스마트 알림, 웹메일 주소록·서명) |