zioinfo-mail/.claude/skills/guardia-enhance-orchestrator/SKILL.md

---
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