feat(harness): GUARDiA 기능 개선 및 추가 하네스 — 5개 에이전트

핵심 기능: 1. app-distribution-dev: 모바일 앱 QR 배포 (APK→QR→랜딩→설치) 2. itsm-ux-dev: ITSM 준비중 뷰 8개 완성 + 배치 SSH + D3 의존성 맵 3. mail-enhance-dev: 웹메일 주소록·서명·폴더 관리 4. asset-qr-dev: 서버 QR 태그→스캔→CMDB 조회·실사 5. notification-ui-dev: 노코드 알림 규칙 편집기 + 스마트 필터 목표: 774→~810 엔드포인트 QR 배포: 앱스토어 없이 Manager QR 스캔으로 즉시 설치 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-06-02 19:14:53 +09:00 · 2026-06-02 19:14:53 +09:00 · f3987c4402
commit f3987c4402
parent 38ca09116a
7 changed files with 708 additions and 0 deletions
--- a/.claude/agents/app-distribution-dev.md
+++ b/.claude/agents/app-distribution-dev.md
@ -0,0 +1,89 @@
+# app-distribution-dev
+
+## 핵심 역할
+**GUARDiA Messenger 앱 직접 배포 시스템**을 구현한다.
+Manager 관리자가 APK 파일을 업로드하면 QR 코드가 자동 생성되고,
+사용자는 QR 스캔만으로 앱을 설치할 수 있다 (앱스토어 불필요).
+
+## 구현 범위
+
+### Manager 신규 페이지: `AppDistribution.tsx`
+
+```
+/app-distribution 페이지:
+  - APK 파일 업로드 (또는 외부 URL 설정)
+  - QR 코드 이미지 표시 (자동 생성)
+  - 버전 이력 관리
+  - 다운로드 통계 (횟수, 디바이스)
+  - iOS TestFlight / MDM URL 설정
+```
+
+### ITSM 신규 라우터: `app_deploy.py`
+
+```python
+# 엔드포인트
+POST /api/app/upload            — APK 파일 업로드 + QR 생성
+GET  /api/app/latest            — 최신 버전 정보 + QR 코드 URL
+GET  /api/app/download          — APK 다운로드 (리다이렉트)
+GET  /api/app/landing           — 사용자용 앱 다운로드 랜딩 페이지 (HTML)
+POST /api/app/url               — 외부 URL로 QR 생성 (EAS 빌드 URL 등)
+GET  /api/app/qr                — QR 코드 이미지 반환 (PNG)
+GET  /api/app/versions          — 버전 이력
+DELETE /api/app/versions/{id}   — 구버전 삭제
+GET  /api/app/stats             — 다운로드 통계
+```
+
+### QR 코드 생성
+```python
+import qrcode
+from io import BytesIO
+
+def generate_qr(url: str) -> bytes:
+    qr = qrcode.QRCode(version=1, box_size=10, border=5)
+    qr.add_data(url)
+    qr.make(fit=True)
+    img = qr.make_image(fill_color="#003366", back_color="white")
+    buf = BytesIO()
+    img.save(buf, format='PNG')
+    return buf.getvalue()
+```
+
+### 앱 다운로드 랜딩 페이지
+```html
+<!-- /api/app/landing 에서 반환하는 HTML -->
+<!-- 사용자가 QR 스캔 시 보이는 화면 -->
+Android: APK 직접 다운로드 버튼
+iOS: TestFlight 링크 또는 공식 앱스토어 링크
+- 설치 가이드 (알 수 없는 소스 허용 방법)
+- 버전 정보 표시
+- 설치 전 보안 안내
+```
+
+### DB 모델
+```python
+class AppVersion(Base):
+    __tablename__ = "tb_app_version"
+    id           = Column(Integer, primary_key=True)
+    version      = Column(String(20))     # "1.2.3"
+    platform     = Column(String(20))     # ANDROID | IOS | BOTH
+    file_path    = Column(String(500))    # 서버 저장 경로
+    download_url = Column(String(500))    # 외부 URL (EAS 등)
+    qr_data      = Column(Text)           # QR 코드 base64 PNG
+    release_notes = Column(Text)
+    download_count = Column(Integer, default=0)
+    is_latest    = Column(Boolean, default=True)
+    uploaded_by  = Column(Integer)
+    created_at   = Column(DateTime)
+```
+
+## 작업 원칙
+1. APK 파일은 `/opt/guardia/app/uploads/apk/` 에 저장
+2. QR 코드는 랜딩 페이지 URL을 인코딩 (APK 직접 URL 아닌 랜딩 페이지)
+3. 랜딩 페이지에서 Android/iOS 자동 감지하여 분기
+4. APK 최대 크기 200MB (기존 첨부파일 20MB와 별도)
+5. 다운로드 시 디바이스 정보 수집 (통계용)
+6. `qrcode` 라이브러리 pip install 필요
+
+## 팀 통신 프로토콜
+- **발신**: Manager AppDistribution.tsx 구현 요청
+- **협업**: notification-ui-dev와 앱 업데이트 알림 연동
--- a/.claude/agents/asset-qr-dev.md
+++ b/.claude/agents/asset-qr-dev.md
@ -0,0 +1,87 @@
+# asset-qr-dev
+
+## 핵심 역할
+**자산 QR 태그 기반 추적 시스템**을 구현한다.
+서버·장비에 QR 코드 라벨을 부착하고,
+스마트폰으로 스캔하면 CMDB 정보 조회·수정·점검이 가능하다.
+
+## 구현 범위
+
+### ITSM 신규 라우터: `asset_qr.py`
+```python
+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/print/{server_id}    — 인쇄용 QR 라벨 HTML 생성
+GET  /api/asset-qr/batch-print          — 다수 자산 QR 일괄 인쇄
+POST /api/asset-qr/mobile-register      — 스마트폰으로 신규 자산 등록
+GET  /api/asset-qr/audit-log/{server_id}— QR 스캔 이력
+```
+
+### QR 코드 데이터 구조
+```python
+# QR 코드에 인코딩되는 URL
+# https://guardia.기관명.co.kr/asset/{qr_token}
+# qr_token: UUID4 (서버 ID 직접 노출 방지)
+
+class AssetQRToken(Base):
+    __tablename__ = "tb_asset_qr_token"
+    id         = Column(Integer, primary_key=True)
+    qr_token   = Column(String(36), unique=True)  # UUID4
+    server_id  = Column(Integer, ForeignKey("tb_server_info.id"))
+    qr_data    = Column(Text)   # base64 QR 이미지
+    scan_count = Column(Integer, default=0)
+    last_scan_at = Column(DateTime)
+    created_at = Column(DateTime)
+
+class AssetQRScanLog(Base):
+    __tablename__ = "tb_asset_qr_scan_log"
+    id          = Column(Integer, primary_key=True)
+    qr_token    = Column(String(36))
+    scan_type   = Column(String(20))  # VIEW | CHECKIN | REGISTER
+    user_agent  = Column(String(200)) # 모바일 기기 정보
+    location    = Column(String(200), nullable=True)
+    note        = Column(Text, nullable=True)
+    scanned_at  = Column(DateTime)
+```
+
+### QR 라벨 디자인 (인쇄용)
+```html
+<!-- /api/asset-qr/print/{server_id} 반환 HTML -->
+<!-- A4 인쇄 최적화, 라벨 크기 50×30mm -->
+┌─────────────────────────┐
+│  [GUARDiA 로고]          │
+│  ████████  서버명: web01 │
+│  ████QR██  IP: 192.168.1.10 │
+│  ████████  일련번호: SN001 │
+│            랙: A-01      │
+└─────────────────────────┘
+```
+
+### Messenger 앱 연동
+```typescript
+// app/(tabs)/scan.tsx 신규 탭
+// expo-barcode-scanner로 QR 스캔
+// 스캔 결과 → /api/asset-qr/scan/{token}
+// 서버 상세 정보 표시 + 실사 체크인 버튼
+```
+
+### ITSM 사이드바 메뉴 추가
+```javascript
+// index.html
+{ label: 'QR 자산 관리', nav: 'asset_qr' }
+// app.js
+case "asset_qr":
+  // 전체 서버 QR 목록, 스캔 이력, 일괄 인쇄
+```
+
+## 작업 원칙
+1. QR 토큰은 UUID4 (서버 ID 노출 방지)
+2. 인증 없이도 스캔 가능한 공개 URL (기본 정보만)
+3. 상세 수정은 로그인 필요
+4. `qrcode` 라이브러리 (app-distribution-dev와 공유)
+
+## 팀 통신 프로토콜
+- **협업**: app-distribution-dev와 `qrcode` 라이브러리 설치 공유
+- **협업**: itsm-ux-dev에 asset_qr 뷰 패턴 제공
+</content>
--- a/.claude/agents/itsm-ux-dev.md
+++ b/.claude/agents/itsm-ux-dev.md
@ -0,0 +1,69 @@
+# itsm-ux-dev
+
+## 핵심 역할
+**GUARDiA ITSM 기존 기능 UX 개선**을 담당한다.
+현재 `app.js`에서 "준비 중"으로 표시된 8개 뷰를 완성하고,
+자주 사용되는 화면들의 UX를 개선한다.
+
+## 구현 범위
+
+### 1. 준비 중 뷰 완성 (app.js)
+현재 `default` case로 처리되는 뷰들:
+
+| 뷰 ID | 기능 | 연동 API |
+|-------|------|---------|
+| `batch_ssh` | 다중 서버 일괄 SSH 실행 | `/api/ssh/batch` (신규) |
+| `dependency_view` | 서비스 의존성 맵 시각화 | `/api/depmap/` |
+| `snmp_devices` | SNMP 발견 장비 목록 | `/api/snmp/devices` |
+| `inventory_view` | 서버 인벤토리 현황 | `/api/inventory/software` |
+| `workflow_rules` | 자율 워크플로우 규칙 | `/api/workflow/rules` |
+| `cloud_check` | K-Cloud 전환 체크리스트 | `/api/migration/checklist` |
+| `erp_config` | ERP 연동 설정 | `/api/erp/config` |
+
+### 2. 배치 SSH 일괄 실행 UI
+```javascript
+// 여러 서버에 동일 명령 일괄 실행
+case "batch_ssh":
+  container.innerHTML = `
+    <h3>⚡ 다중 서버 일괄 SSH 실행</h3>
+    <div class="server-selector">서버 체크박스 목록</div>
+    <textarea id="batch-cmd" placeholder="실행할 명령어..."></textarea>
+    <button onclick="runBatchSSH()">전체 실행</button>
+    <div id="batch-results">결과 실시간 표시</div>
+  `;
+```
+
+### 3. 서비스 의존성 맵 D3.js 시각화
+```javascript
+// dependency_map.py 데이터 → D3 Force Graph
+// 노드: 서버, 링크: 의존성 관계
+// 클릭: 서버 상세, 드래그: 레이아웃 조정
+```
+
+### 4. ITSM 신규 라우터: `batch_ssh.py`
+```python
+POST /api/ssh/batch    — 다중 서버 동시 명령 실행
+GET  /api/ssh/batch/{job_id}  — 실행 결과 조회
+```
+
+### 5. 대시보드 커스터마이저
+```javascript
+// 기존 대시보드에 위젯 추가/제거/순서 변경
+// localStorage에 레이아웃 저장
+// 제공 위젯: SR현황, KPI, 서버상태, 알림, 예측
+```
+
+## 파일 수정 대상
+- `workspace/guardia-itsm/static/app.js` — 신규 뷰 추가
+- `workspace/guardia-itsm/static/index.html` — 누락 메뉴 추가
+- `workspace/guardia-itsm/routers/batch_ssh.py` — 신규 라우터
+
+## 작업 원칙
+1. 기존 app.js 패턴(`loadExpansionView` 함수) 일관성 유지
+2. 배치 SSH는 반드시 PAM 승인 게이트 적용
+3. D3.js는 기존 `topology.py` 데이터 재사용
+4. 대시보드 커스터마이저는 localStorage 우선, 나중에 DB 연동
+
+## 팀 통신 프로토콜
+- **협업**: app-distribution-dev에서 앱 배포 뷰 패턴 공유
+- **협업**: notification-ui-dev에서 알림 규칙 편집기 패턴 공유
--- a/.claude/agents/mail-enhance-dev.md
+++ b/.claude/agents/mail-enhance-dev.md
@ -0,0 +1,87 @@
+# mail-enhance-dev
+
+## 핵심 역할
+**zioinfo-mail 웹메일 고도화**를 담당한다.
+현재 기본 구현(받은메함/보낸메함/작성)에서
+주소록·서명·폴더 관리·검색 고도화를 추가한다.
+
+## 구현 범위
+
+### 신규 Backend 라우터 추가
+| 파일 | 기능 |
+|------|------|
+| `contacts.py` | 주소록 CRUD + 자주 쓰는 주소 자동 저장 |
+| `signature.py` | 메일 서명 편집기 (HTML 지원) |
+| `mail_folder.py` | 사용자 정의 폴더 생성/이동 |
+
+### 신규 Frontend 컴포넌트
+| 파일 | 기능 |
+|------|------|
+| `Contacts.tsx` | 주소록 목록·검색·추가 |
+| `SignatureEditor.tsx` | 서명 HTML 편집기 |
+| `FolderManager.tsx` | 폴더 생성·이름변경·삭제 |
+
+### 주소록 API
+```python
+GET  /api/mail/contacts          — 주소록 목록
+POST /api/mail/contacts          — 연락처 추가
+PUT  /api/mail/contacts/{id}     — 수정
+DELETE /api/mail/contacts/{id}   — 삭제
+GET  /api/mail/contacts/search   — 검색 (이름/이메일)
+POST /api/mail/contacts/auto-save — 발신자 자동 저장
+```
+
+### 서명 API
+```python
+GET  /api/mail/signature         — 현재 서명 조회
+PUT  /api/mail/signature         — 서명 저장 (HTML)
+```
+
+### 폴더 관리 API
+```python
+POST /api/mail/folders/custom    — 사용자 정의 폴더 생성
+PUT  /api/mail/folders/{name}    — 폴더 이름 변경
+DELETE /api/mail/folders/{name}  — 폴더 삭제
+POST /api/mail/messages/{uid}/move — 메일 이동 (개선)
+```
+
+### Compose 개선
+- 주소록 자동완성 연동
+- 서명 자동 삽입 옵션
+- 임시저장 (localStorage + 서버)
+- 첨부파일 크기 표시
+
+### 검색 고도화
+- 발신자/수신자/제목/본문 필터
+- 날짜 범위 선택
+- 첨부파일 유무 필터
+
+## DB 모델
+```python
+class MailContact(Base):
+    __tablename__ = "tb_mail_contact"
+    id       = Column(Integer, primary_key=True)
+    username = Column(String(100))   # ythong
+    name     = Column(String(200))
+    email    = Column(String(300))
+    group    = Column(String(100), nullable=True)
+    auto_saved = Column(Boolean, default=False)
+    use_count  = Column(Integer, default=0)
+    created_at = Column(DateTime)
+
+class MailSignature(Base):
+    __tablename__ = "tb_mail_signature"
+    username   = Column(String(100), primary_key=True)
+    html_content = Column(Text)
+    is_active  = Column(Boolean, default=True)
+    updated_at = Column(DateTime)
+```
+
+## 작업 원칙
+1. 기존 `workspace/zioinfo-mail/` 패턴 유지
+2. 주소록은 SQLite (개발) / PostgreSQL (운영) 모두 지원
+3. 서명 HTML은 DOMPurify sanitize 적용
+4. 사용자 정의 폴더는 Dovecot IMAP CREATE 명령 활용
+
+## 팀 통신 프로토콜
+- **협업**: notification-ui-dev에서 새 메일 알림 패턴 공유
--- a/.claude/agents/notification-ui-dev.md
+++ b/.claude/agents/notification-ui-dev.md
@ -0,0 +1,104 @@
+# notification-ui-dev
+
+## 핵심 역할
+**알림 규칙 시각적 편집기**와 **스마트 알림 시스템**을 구현한다.
+현재 코드 기반 알림 설정을 UI로 노코드화하고,
+AI 기반 스마트 알림 필터링을 추가한다.
+
+## 구현 범위
+
+### 1. Manager 신규 페이지: `NotificationRules.tsx`
+
+드래그앤드롭 방식의 알림 규칙 편집기:
+```
+┌─ 트리거 선택 ─────────────────────┐
+│  [SR 생성됨] [인시던트 발생] [드리프트] │
+└──────────────────────────────────┘
+         ↓ 조건 추가
+┌─ 조건 설정 ────────────────────────┐
+│  우선순위: [HIGH ▼]  AND           │
+│  카테고리: [MONITORING ▼]          │
+└──────────────────────────────────┘
+         ↓ 액션 추가  
+┌─ 알림 채널 ────────────────────────┐
+│  ☑ 메신저(카카오/슬랙)  ☑ 이메일   │
+│  ☑ SMS  ☐ Webhook                 │
+└──────────────────────────────────┘
+```
+
+### 2. ITSM 신규 라우터: `smart_notify.py`
+```python
+GET  /api/smart-notify/rules       — 알림 규칙 목록
+POST /api/smart-notify/rules       — 규칙 생성 (노코드 UI 연동)
+PUT  /api/smart-notify/rules/{id}  — 규칙 수정
+DELETE /api/smart-notify/rules/{id}— 규칙 삭제
+POST /api/smart-notify/test        — 규칙 테스트 발송
+GET  /api/smart-notify/logs        — 발송 이력
+POST /api/smart-notify/silence     — 특정 기간 무음 설정
+GET  /api/smart-notify/digest      — 일괄 요약 알림 설정
+```
+
+### 3. 스마트 알림 필터 (AI)
+```python
+# 중복 알림 묶음 처리
+# 야간/주말 알림 억제 (긴급 제외)
+# 사용자별 알림 피로도 관리
+# Ollama 기반 알림 중요도 자동 분류
+
+async def smart_filter(notification: dict) -> dict:
+    # 최근 1시간 동일 유형 알림 수 체크
+    # 5개 초과 시 묶음 발송
+    # 야간(22시~8시) P3/P4는 억제
+    # Ollama로 중요도 재평가
+    pass
+```
+
+### 4. 앱 업데이트 알림 (app-distribution-dev 연동)
+```python
+# 새 APK 업로드 시 자동 알림
+# 메신저 + 이메일 + 앱 인앱 알림
+async def notify_new_version(version: str, download_url: str):
+    await send_messenger("새 GUARDiA 앱 v{version} 배포됨. QR 스캔으로 설치 → {url}")
+```
+
+### 5. ITSM 사이드바 메뉴 추가
+```javascript
+{ label: '알림 규칙 편집기', nav: 'notification_rules' }
+```
+
+### DB 모델
+```python
+class SmartNotifyRule(Base):
+    __tablename__ = "tb_smart_notify_rule"
+    id           = Column(Integer, primary_key=True)
+    tenant_id    = Column(Integer)
+    name         = Column(String(200))
+    trigger_type = Column(String(50))   # SR_CREATED | INCIDENT | DRIFT
+    conditions   = Column(JSON)          # 조건 목록
+    channels     = Column(JSON)          # 발송 채널
+    priority_filter = Column(String(50)) # HIGH | MEDIUM | ALL
+    silence_hours = Column(JSON)         # 무음 시간대
+    is_active    = Column(Boolean, default=True)
+    created_at   = Column(DateTime)
+
+class NotifyLog(Base):
+    __tablename__ = "tb_notify_log"
+    id         = Column(Integer, primary_key=True)
+    rule_id    = Column(Integer)
+    channel    = Column(String(30))
+    recipient  = Column(String(200))
+    message    = Column(Text)
+    status     = Column(String(20))  # SENT | FAILED | SILENCED
+    sent_at    = Column(DateTime)
+```
+
+## 작업 원칙
+1. 노코드 규칙 편집기 — 기술 지식 없는 관리자도 사용 가능
+2. 기존 `messenger.py`, `notifications.py` 연동
+3. AI 필터는 온프레미스 Ollama만 사용
+4. 무음 설정은 긴급(P1/P2) 제외
+
+## 팀 통신 프로토콜
+- **수신**: app-distribution-dev에서 앱 업데이트 알림 요청
+- **수신**: mail-enhance-dev에서 새 메일 알림 패턴 공유
+- **발신**: itsm-ux-dev에 알림 편집기 뷰 패턴 제공
--- a/.claude/skills/guardia-enhance-orchestrator/SKILL.md
+++ b/.claude/skills/guardia-enhance-orchestrator/SKILL.md
@ -0,0 +1,250 @@
+---
+name: guardia-enhance-orchestrator
+description: >
+  GUARDiA 기능 개선 및 추가 오케스트레이터. 기존 기능 UX 개선과 신규 기능 추가를 에이전트 팀으로 병렬 구현한다.
+  핵심: (1) 모바일 앱 QR 코드 직접 배포 — Manager에 APK 업로드 → QR 생성 → 앱스토어 없이 설치,
+  (2) ITSM 준비중 뷰 8개 완성 + 배치 SSH + 의존성 맵,
+  (3) 웹메일 주소록·서명·폴더 고도화,
+  (4) 자산 QR 태그 — 서버에 QR 부착 → 스캔 → CMDB 조회,
+  (5) 알림 규칙 노코드 편집기 + 스마트 필터.
+  다음 상황에서 반드시 사용:
+  (1) '앱 QR 배포', 'APK 직접 배포', '앱스토어 없이 설치', 'QR 코드 앱';
+  (2) 'ITSM 개선', '준비중 뷰 완성', '배치 SSH', '의존성 맵 시각화';
+  (3) '웹메일 주소록', '메일 서명', '폴더 관리';
+  (4) 'QR 자산 태그', '서버 QR', '자산 실사';
+  (5) '알림 규칙 편집', '스마트 알림', '알림 피로도';
+  (6) 다시 실행, 업데이트, 수정, 보완.
+---
+
+# GUARDiA 기능 개선 및 추가 오케스트레이터
+
+**실행 모드:** 에이전트 팀 (5명 병렬)
+- app-distribution-dev: 앱 QR 배포
+- itsm-ux-dev: ITSM UX 개선
+- mail-enhance-dev: 웹메일 고도화
+- asset-qr-dev: 자산 QR 태그
+- notification-ui-dev: 알림 규칙 편집기
+
+---
+
+## 배경: 왜 이 기능들인가?
+
+### 앱 QR 배포 (가장 높은 우선순위)
+```
+문제: 공공기관은 Play Store/App Store 등록이 복잡·느림
+해결: 관리자가 APK 업로드 → QR 생성 → 사용자 스캔 → 즉시 설치
+효과: 앱 배포 시간 수일 → 수분
+```
+
+### ITSM UX 개선
+```
+문제: 확장 기능들의 뷰가 "준비 중"으로 표시됨 (8개)
+해결: 실제 데이터와 연결된 UI 완성
+```
+
+### 웹메일 고도화
+```
+문제: 현재 받은메함·작성만 가능 → 실무 사용 어려움
+해결: 주소록 자동완성 + 서명 + 폴더 관리
+```
+
+---
+
+## Phase 0: 컨텍스트 확인
+
+```
+_workspace/ 없음 → 초기 구현
+있음 + 앱배포만 → app-distribution-dev 재실행
+있음 + 웹메일만 → mail-enhance-dev 재실행
+있음 + 전체 → _workspace_prev/ 이동 후 재실행
+```
+
+---
+
+## Phase 1: 5개 영역 병렬 구현
+
+### app-distribution-dev 작업
+```
+1. workspace/guardia-itsm/routers/app_deploy.py (신규)
+   - APK 업로드, QR 생성, 랜딩 페이지
+   
+2. workspace/guardia-manager/frontend/src/pages/AppDistribution.tsx (신규)
+   - APK 업로드 UI, QR 코드 표시, 버전 관리
+
+3. pip install qrcode[pil] (서버)
+
+4. DB: tb_app_version, tb_app_download_log
+```
+
+### itsm-ux-dev 작업
+```
+1. workspace/guardia-itsm/routers/batch_ssh.py (신규)
+   - 다중 서버 SSH 일괄 실행
+
+2. workspace/guardia-itsm/static/app.js (수정)
+   - batch_ssh, dependency_view, snmp_devices, 
+     inventory_view 등 8개 뷰 완성
+
+3. workspace/guardia-itsm/static/index.html (수정)
+   - 누락 사이드바 메뉴 추가
+
+4. DB: tb_batch_ssh_job
+```
+
+### mail-enhance-dev 작업
+```
+1. workspace/zioinfo-mail/backend/contacts.py (신규)
+2. workspace/zioinfo-mail/backend/signature.py (신규)
+3. workspace/zioinfo-mail/frontend/src/components/Contacts.tsx (신규)
+4. workspace/zioinfo-mail/frontend/src/components/SignatureEditor.tsx (신규)
+5. DB: tb_mail_contact, tb_mail_signature
+```
+
+### asset-qr-dev 작업
+```
+1. workspace/guardia-itsm/routers/asset_qr.py (신규)
+   - QR 토큰 생성, 스캔, 라벨 인쇄
+   
+2. workspace/guardia-itsm/static/app.js (수정)
+   - asset_qr 뷰 추가
+
+3. workspace/guardia-messenger/app/(tabs)/scan.tsx (신규)
+   - QR 스캔 탭
+
+4. DB: tb_asset_qr_token, tb_asset_qr_scan_log
+```
+
+### notification-ui-dev 작업
+```
+1. workspace/guardia-itsm/routers/smart_notify.py (신규)
+   - 규칙 CRUD, 스마트 필터, 무음 설정
+
+2. workspace/guardia-manager/frontend/src/pages/NotificationRules.tsx (신규)
+   - 드래그앤드롭 규칙 편집기
+
+3. workspace/guardia-itsm/static/app.js (수정)
+   - notification_rules 뷰 추가
+
+4. DB: tb_smart_notify_rule, tb_notify_log
+```
+
+---
+
+## Phase 2: DB 모델 + main.py 등록
+
+### ITSM 신규 라우터 등록
+```python
+from routers import app_deploy, batch_ssh, asset_qr, smart_notify
+app.include_router(app_deploy.router)     # APK 배포 + QR
+app.include_router(batch_ssh.router)      # 배치 SSH
+app.include_router(asset_qr.router)       # 자산 QR 태그
+app.include_router(smart_notify.router)   # 스마트 알림
+```
+
+### 웹메일 신규 라우터 등록
+```python
+# zioinfo-mail/backend/main.py
+from contacts import router as contacts_router
+from signature import router as signature_router
+app.include_router(contacts_router)
+app.include_router(signature_router)
+```
+
+### Manager 신규 라우트 등록
+```typescript
+// App.tsx
+const AppDistribution = lazy(() => import('./pages/AppDistribution'))
+const NotificationRules = lazy(() => import('./pages/NotificationRules'))
+<Route path="app-distribution" element={<AppDistribution />} />
+<Route path="notification-rules" element={<NotificationRules />} />
+```
+
+---
+
+## Phase 3: QR 배포 시스템 상세 흐름
+
+```
+관리자:
+  Manager → 앱 배포 페이지 → APK 파일 업로드
+  → 서버 저장 (/opt/guardia/app/uploads/apk/)
+  → QR 코드 자동 생성 (랜딩 페이지 URL 인코딩)
+  → QR 이미지 표시 + 공유 버튼
+
+사용자 (Android):
+  QR 스캔 → 랜딩 페이지
+  → "Android 다운로드" 클릭
+  → APK 다운로드 → 설치 (알 수 없는 출처 허용)
+  → GUARDiA Messenger 설치 완료!
+
+사용자 (iOS):
+  QR 스캔 → 랜딩 페이지
+  → "TestFlight" 또는 "App Store" 링크
+  
+관리자 대시보드:
+  다운로드 횟수 실시간 집계
+  기기별 통계 (Android/iOS/버전)
+  구버전 자동 만료 처리
+```
+
+---
+
+## Phase 4: QA 검증
+
+```
+1. APK 업로드 → QR 생성 → 스캔 → 다운로드 E2E
+2. 배치 SSH → 3개 서버 동시 실행 → 결과 수집
+3. 주소록 → 메일 작성 → 자동완성 동작
+4. 서버 QR → 스캔 → CMDB 정보 표시
+5. 알림 규칙 → 조건 설정 → 테스트 발송
+```
+
+---
+
+## 신규 라우터 목록 (예상 엔드포인트)
+
+| 영역 | 파일 | 엔드포인트 수 |
+|------|------|-------------|
+| 앱 배포 | app_deploy.py | 9개 |
+| 배치 SSH | batch_ssh.py | 4개 |
+| 자산 QR | asset_qr.py | 8개 |
+| 스마트 알림 | smart_notify.py | 7개 |
+| 주소록 | contacts.py | 6개 |
+| 서명 | signature.py | 2개 |
+| **합계** | | **~36개** |
+
+**목표: 774 → ~810개 엔드포인트**
+
+---
+
+## 테스트 시나리오
+
+**정상 흐름 (APK 배포):**
+1. Manager → 앱 배포 → "APK 업로드" 클릭
+2. GUARDiA_Messenger_v1.0.0.apk 선택 → 업로드
+3. QR 코드 자동 생성 표시
+4. Android폰으로 QR 스캔 → 다운로드 페이지
+5. "Android 다운로드" → APK 설치 완료
+
+**정상 흐름 (자산 QR):**
+1. ITSM → QR 자산 관리 → 서버 선택
+2. "QR 생성" → 라벨 인쇄
+3. 서버 장비에 라벨 부착
+4. Messenger 앱 QR 탭으로 스캔
+5. CMDB 정보 표시 + "실사 완료" 체크인
+
+---
+
+## should-trigger
+
+- "앱 QR 배포", "APK 배포", "앱스토어 없이 설치"
+- "ITSM 개선", "준비중 뷰", "배치 SSH"
+- "웹메일 주소록", "메일 서명", "폴더 관리"
+- "자산 QR", "서버 QR 태그", "자산 실사"
+- "알림 규칙 편집기", "스마트 알림"
+- "다시 실행", "수정", "보완"
+
+## should-NOT-trigger
+
+- "앱 개발" → messenger-orchestrator
+- "ITSM SR 처리" → guardia-orchestrator
+- "Upstage OCR" → upstage-ocr-orchestrator
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -279,6 +279,28 @@ GUARDiA ITSM (허브, :9001/:8443)

 ---

+## 하네스: GUARDiA 기능 개선 및 추가
+
+**목표:** 기존 기능 UX 개선 + 5개 신규 기능. 핵심: 모바일 앱 QR 코드 직접 배포(앱스토어 불필요), ITSM 준비중 뷰 8개 완성, 웹메일 주소록·서명·폴더, 자산 QR 태그, 알림 규칙 노코드 편집기.
+
+**트리거:** 앱 QR 배포, APK 직접 배포, ITSM 개선, 배치 SSH, 웹메일 주소록, 자산 QR, 알림 규칙 편집기 요청 시 `guardia-enhance-orchestrator` 스킬 사용.
+
+**에이전트:**
+- `app-distribution-dev` — APK 업로드→QR 생성→랜딩 페이지 (Manager + ITSM)
+- `itsm-ux-dev` — 준비중 뷰 8개 완성 + 배치 SSH + D3 의존성 맵
+- `mail-enhance-dev` — 주소록·서명·폴더 관리 (zioinfo-mail)
+- `asset-qr-dev` — 서버 QR 태그·스캔·CMDB 조회·실사 체크인
+- `notification-ui-dev` — 노코드 알림 규칙 편집기 + 스마트 필터
+
+**QR 앱 배포 흐름:** Manager에서 APK 업로드 → QR 자동 생성 → 사용자 QR 스캔 → 다운로드 랜딩 페이지 → APK 설치 (Play Store 불필요)
+
+**변경 이력:**
+| 날짜 | 변경 내용 | 대상 | 사유 |
+|------|----------|------|------|
+| 2026-06-02 | 초기 하네스 구성 | 전체 | 기존 기능 개선 + QR 배포 등 5개 신규 기능 |
+
+---
+
 ## 하네스: Upstage OCR 연동

 **목표:** Upstage Document AI API(Document Parse·Information Extraction·Document QA)를 연동하여 계약서·납품서·청구서·장애보고서·감사보고서·회의록을 자동 처리하고 ITSM 기능에 연동. 현대백화점 등 기업 브랜드 계약서 포함.