# GUARDiA ITSM — AI 기반 레거시 인프라 자율 운영 플랫폼
## Claude Code 프로젝트 마스터 컨텍스트

> 이 파일을 읽고 프로젝트 전체 구조와 규칙을 파악한 뒤 작업을 시작하라.

---

## 프로젝트 비전

1,000개 이상 다중 관공서(Multi-tenant) 레거시 인프라를 타겟으로 하는
**AI 기반 통합 ChatOps 오케스트레이션 플랫폼**.

- 메신저 한 줄 명령 → sLLM 파싱 → 에이전트리스(SSH/SFTP) 배포·운영 자동화
- 에이전트 설치 **불필요** — 표준 SSH/FTP 프로토콜만 활용
- 개발(Dev), SM 운영, PM 관리 세 역할의 워크플로우를 단일 메신저로 통합
- **온프레미스 전용**: 외부 클라우드 API 완전 금지 (Ollama 내부 LLM만 허용)

---

## 기술 스택

| 레이어 | 기술 | 비고 |
|--------|------|------|
| Backend API | Python 3.11+ / FastAPI | 비동기 WebSocket 처리 |
| LLM | Ollama localhost:11434 (codellama, llama3) | 외부 API 완전 금지 |
| Infra 연결 | paramiko (SSH/SFTP) | 에이전트리스 |
| Database | SQLite (dev) / PostgreSQL (prod) | SQLAlchemy async |
| 암호화 | AES-256-GCM (서버 자격증명) | |
| 인증 | JWT + 2FA/OTP | |

---

## 디렉토리 구조

```
C:\GUARDiA\
├── itsm/                    # FastAPI 백엔드
│   ├── main.py              # FastAPI 앱 진입점
│   ├── models.py            # SQLAlchemy 모델
│   ├── auth.py              # JWT 인증
│   ├── database.py          # DB 연결
│   ├── core/                # 비즈니스 로직
│   │   ├── code_review.py   # B-3: 코드 리뷰 엔진
│   │   ├── anomaly.py       # B-1: 이상 탐지 엔진
│   │   └── notify.py        # 알림 공통
│   ├── routers/             # API 라우터
│   └── .claude/             # 하네스 에이전트/스킬
├── projects/                # SM/SI 프로젝트 소스
│   ├── testcase-java-api/   # Spring Boot 테스트케이스
│   ├── testcase-py-api/     # FastAPI 테스트케이스
│   ├── testcase-js-frontend/ # HTML/JS 테스트케이스
│   └── testcase-php-legacy/ # PHP 레거시
└── docs/
```

---

## 보안 제약 (절대 불변)

1. **외부 API 완전 금지** — 모든 AI/LLM 호출은 내부 sLLM only (Ollama localhost:11434)
2. **서버 자격증명 노출 금지** — IP, 비밀번호, SSH 계정을 API 응답/메신저에 포함 금지
3. **AES-256-GCM 암호화** — tb_server.os_pw_enc 컬럼 필수 암호화
4. **root SSH 직접 접속 금지** — ssh_user != root 강제
5. **ServerOut 스키마 제외 필드** — ip_addr, ssh_user, os_pw_enc 절대 미포함
6. **스택트레이스 노출 금지** — 에러 응답은 SR ID + 요약 메시지만
7. **명령어 안전성 검증** — SSH 실행 전 위험 패턴 차단 (rm -rf /, mkfs, dd, shutdown 등)
8. **경로 순회 방지** — 첨부파일 경로 resolve().relative_to(UPLOAD_ROOT) 검증

---

## 30개 고도화 항목 진행 현황

| 코드 | 항목 | 상태 | 주요 파일 |
|------|------|------|-----------|
| A-1 | 알림 고도화 (WebSocket + 이메일) | ✅ DONE | routers/notify.py, core/notify.py |
| A-2 | 첨부 파일 관리 | ✅ DONE | routers/attachments.py |
| A-3 | 배포 승인 알림 (VibeSession 연동) | ✅ DONE | routers/vibe.py |
| A-4 | 운영 이벤트 타임라인 | ✅ DONE | routers/timeline.py |
| A-5 | 역할 기반 접근 제어 (RBAC) | ✅ DONE | auth.py, models.py |
| B-1 | AI 이상 탐지 (Anomaly Detection) | ✅ DONE | core/anomaly.py, routers/anomaly.py |
| B-2 | 자연어 SR 접수 챗봇 | ✅ DONE | core/chatbot.py, routers/chatbot.py |
| B-3 | 코드 리뷰 에이전트 (Ollama) | ✅ DONE | core/code_review.py, routers/code_review.py |
| B-4 | KB 자동 업데이트 에이전트 | ✅ DONE | core/kb_agent.py, routers/kb_agent.py |
| B-5 | 멀티 에이전트 협업 오케스트레이션 | ✅ DONE | core/orchestrator.py, routers/orchestrator.py |
| B-6 | 예측 유지보수 | ✅ DONE | core/predictive.py, routers/predictive.py |
| C-1 | CMDB (형상 관리 DB) | ✅ DONE | routers/cmdb.py (CI+관계+변경이력) |
| C-2 | 변경 관리 CAB | ✅ DONE | routers/change.py (RFC/CAB투표/동결기간) |
| C-3 | Problem Management | ✅ DONE | routers/problem.py (RCA/Known Error/PRB ID) |
| C-4 | 용량 관리 대시보드 | ✅ DONE | routers/capacity.py (예측/경보/확장시점) |
| C-5 | 서비스 카탈로그 | ✅ DONE | routers/catalog.py (SLA/SR자동생성/SVC ID) |
| D-1 | LDAP/AD 연동 | ✅ DONE | core/ldap_auth.py, routers/ldap.py (그룹→역할/env설정/동기화) |
| D-2 | 2FA / OTP | ✅ DONE | routers/otp.py |
| D-3 | 특권 접근 관리 (PAM) | ✅ DONE | routers/pam.py (세션발급/체크아웃/명령로깅/강제종료) |
| D-4 | 보안 취약점 자동 스캔 | ✅ DONE | core/vuln_scan.py, routers/vuln_scan.py (포트스캔/CVE/CVSS) |
| D-5 | 불변 감사 로그 (Hash Chain) | ✅ DONE | routers/audit.py (SHA-256체인/entity/IP해시/export) |
| E-1 | 월별 리포트 자동 생성 | ✅ DONE | routers/report.py |
| E-2 | 대시보드 분석 | ✅ DONE | routers/analytics.py |
| E-3 | SLA 대시보드 (실시간) | ✅ DONE | routers/sla.py |
| E-4 | Grafana 연동 (Prometheus) | ✅ DONE | routers/metrics.py |
| E-5 | FinOps 비용 분석 | ✅ DONE | routers/finops.py |
| F-1 | 멀티테넌트 데이터 격리 | ✅ DONE | middleware/tenant.py |
| F-2 | 모바일 반응형 UI | ✅ DONE | static/ |
| F-3 | 다국어 지원 (i18n) | ✅ DONE | core/i18n.py |
| F-4 | Mobile PWA | ✅ DONE | static/manifest.json |
| F-5 | OpenAPI 외부 연동 게이트웨이 | ✅ DONE | routers/gateway.py |

**완료: 30개 | 남은 항목: 0개 🎉**

---

## GUARDiA 하네스 구조 (.claude/)

### 에이전트 (agents/)
- **sr-manager.md**: SR 생성/조회/상태변경/담당자배정
- **code-reviewer.md**: B-3 코드 리뷰, quick-scan, findings 분석
- **deploy-engineer.md**: VibeSession 배포 파이프라인, Jenkins 연동
- **sla-guardian.md**: SLA 모니터링, 에스컬레이션
- **incident-responder.md**: 인시던트 생성, 온콜 호출, RCA

### 스킬 (skills/)
- **guardia-orchestrator/SKILL.md**: E2E SR→코드리뷰→배포 워크플로우
- **code-review/SKILL.md**: B-3 코드 리뷰 실행 가이드
- **sr-lifecycle/SKILL.md**: SR 상태 흐름, SLA 기준
- **deploy-pipeline/SKILL.md**: VibeSession 배포 단계 관리

---

## 핵심 구현 원칙

1. **에이전트리스**: 대상 서버에 어떤 소프트웨어도 설치하지 않는다.
2. **결정론적 파싱**: sLLM은 JSON만 출력한다. 자연어 부연 설명 금지.
3. **Fail-Safe**: 모든 배포는 백업→배포→헬스체크→롤백 시퀀스를 따른다.
4. **감사 추적**: 모든 명령과 결과는 TB_AUDIT_LOG에 기록한다.
5. **최소 권한**: 관제 전용 일반 계정(opsagent) 사용. root SSH 직접 접속 금지.
6. **보안 우선**: 서버 자격증명은 암호화 DB에만 저장. 메신저 응답에 노출 금지.

---

## 파일 작성 규칙

- **CLAUDE.md 수정 시**: 반드시 Python `open(encoding='utf-8')` 또는 Write 도구 사용
  - PowerShell `Set-Content` / `Out-File` 절대 금지 (UTF-16 LE 오염 발생)
- **.xfdl.js 파일**: Nexacro 빌드 결과물 — 절대 수정/커밋 금지