sync: update from workspace (latest ITSM/CICD/DR changes)

04_운영자지침서.md

@@ -932,4 +932,35 @@ curl -X POST http://localhost:8001/api/license/activate \
 
 ---
 
-*본 운영자 지침서는 GUARDiA ITSM v1.0 기준으로 작성되었습니다.*
+## 17. 신규 기능 (v2.0 — 2026-06-02)
+
+| 기능 | 위치 | 상세 가이드 |
+|------|------|------------|
+| 📱 모바일 앱 QR 직접 배포 | Manager → 앱 배포 | `44_신규기능_운영가이드.md` §1 |
+| ⚡ 배치 SSH 일괄 실행 | ITSM → 배치 SSH 실행 | `44_신규기능_운영가이드.md` §2 |
+| 🏷️ 자산 QR 태그 관리 | ITSM → 자산 QR 태그 | `44_신규기능_운영가이드.md` §3 |
+| 🔔 스마트 알림 규칙 편집기 | ITSM/Manager → 알림 규칙 | `44_신규기능_운영가이드.md` §4 |
+| 📧 웹메일 주소록·서명 | Webmail → 주소록/서명 탭 | `44_신규기능_운영가이드.md` §5 |
+
+### 17.1 빠른 시작 — APK QR 배포
+
+```
+1. Manager(https://zioinfo.co.kr:8090) 로그인
+2. 사이드바 → 📱 앱 배포
+3. APK 파일 선택 + 버전 입력 → 🚀 배포 + QR 생성
+4. 생성된 QR 이미지를 사용자에게 공유
+5. 사용자: QR 스캔 → APK 다운로드 → 설치 완료
+```
+
+### 17.2 빠른 시작 — 배치 SSH
+
+```
+1. ITSM(https://zioinfo.co.kr:8443) 로그인
+2. 사이드바 → ⚡ 배치 SSH 실행
+3. 명령어 + 서버 ID 목록 입력 → 실행
+4. 서버별 결과(성공/실패·stdout) 즉시 확인
+```
+
+---
+
+*본 운영자 지침서는 GUARDiA ITSM v2.0 기준으로 작성되었습니다.*

44_신규기능_운영가이드.md

@@ -0,0 +1,403 @@
+# 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, 스마트 알림, 웹메일 주소록·서명) |