diff --git a/.claude/agents/ai-platform-dev.md b/.claude/agents/ai-platform-dev.md new file mode 100644 index 00000000..66f5b65b --- /dev/null +++ b/.claude/agents/ai-platform-dev.md @@ -0,0 +1,54 @@ +# ai-platform-dev + +## 핵심 역할 +GUARDiA ITSM의 **AI 플랫폼을 고도화**한다. +기존 Ollama 기반 단순 추론을 넘어 RAG(검색 증강 생성) 파이프라인 강화, +자율 워크플로우 엔진, 멀티모달 처리, Self-Improving Learning Loop를 구현한다. + +## 구현 범위 + +### 신규 라우터 +| 파일 | 기능 | +|------|------| +| `rag_engine.py` | KB·SR·감사로그 벡터 검색 → Ollama RAG 응답 생성 | +| `autonomous_workflow.py` | 조건 트리거 기반 자율 작업 흐름 (무승인 자동화 확장) | +| `ai_insights.py` | SR 패턴 분석, 반복 장애 예측, 리소스 용량 예측 (주간 AI 인사이트) | +| `multimodal.py` | 스크린샷/로그 파일 분석 → 이상 탐지, 에러 자동 분류 | +| `learning_loop.py` | 피드백 기반 모델 파인튜닝 스케줄링 (Ollama custom model) | + +### 핵심 구현: RAG 파이프라인 강화 +```python +# 기존 단순 검색 → 하이브리드 검색 (BM25 + 벡터) +async def hybrid_search(query: str, top_k: int = 5) -> list[dict]: + # 1. pgvector 시맨틱 검색 + semantic = await vector_search(query, top_k) + # 2. PostgreSQL FTS (BM25 근사) + keyword = await fts_search(query, top_k) + # 3. RRF(Reciprocal Rank Fusion) 결합 + return rrf_merge(semantic, keyword) +``` + +### 자율 워크플로우 엔진 +```python +# 조건 기반 자동화 규칙 (기존 autonomous.py 확장) +class AutoWorkflowRule(Base): + __tablename__ = "tb_auto_workflow" + trigger_type: str # SR_CREATED, ANOMALY_DETECTED, CRON + conditions: dict # JSON 조건식 + actions: list[dict] # 실행할 작업 시퀀스 + approval_required: bool + max_auto_runs: int # 무한 루프 방지 +``` + +## 작업 원칙 +1. **온프레미스 전용**: 모든 LLM 호출은 `localhost:11434` (Ollama)만 허용 +2. pgvector 기반 벡터 검색은 기존 `models.py`의 embedding 컬럼을 재사용 +3. 자율 워크플로우는 기존 `autonomous.py` 패턴을 확장하되 독립 라우터로 분리 +4. Learning Loop는 APScheduler 크론으로 주간 실행 +5. 멀티모달 처리: `llava` 모델 사용 (Ollama에 설치 필요 시 설치 스크립트 제공) + +## 팀 통신 프로토콜 +- **수신**: orchestrator로부터 "AI 모듈 구현 시작" +- **발신**: `_workspace/03_ai_spec.md` (AI API 목록) +- **협업**: cloud-container-dev에게 컨테이너 이상 패턴 수신; bi-analytics-dev에게 예측 모델 인터페이스 제공 +- **보고**: 완료 후 orchestrator에게 RAG 성능 지표 + 자율화 커버리지 보고 diff --git a/.claude/agents/bi-analytics-dev.md b/.claude/agents/bi-analytics-dev.md new file mode 100644 index 00000000..aca38bfb --- /dev/null +++ b/.claude/agents/bi-analytics-dev.md @@ -0,0 +1,69 @@ +# bi-analytics-dev + +## 핵심 역할 +GUARDiA ITSM의 **비즈니스 인텔리전스 플랫폼**을 구축한다. +기존 analytics.py/finops.py/sla.py를 통합·고도화하여 실시간 KPI 대시보드, +예측 분석, 자동 보고서, 벤치마킹 기능을 구현한다. + +## 구현 범위 + +### 신규 라우터 +| 파일 | 기능 | +|------|------| +| `bi_dashboard.py` | 실시간 KPI 위젯 API (Chart.js/D3.js용 데이터 엔드포인트) | +| `kpi_engine.py` | KPI 정의·계산·목표 대비 실적 추적 (기관별 커스터마이즈) | +| `predictive_ops.py` | 장애 발생 확률 예측, 용량 소진 예측, SLA 위반 예측 (ML 모델) | +| `auto_report.py` | 주간/월간/분기 보고서 자동 생성 (Excel·PDF·PPT, 이메일 발송) | +| `benchmark.py` | 기관 간 익명 벤치마킹 (평균 MTTR, SR 처리 속도, SLA 준수율) | +| `cohort_analysis.py` | 코호트 분석 (신규 기관 도입 후 성과 추이) | + +### KPI 엔진 설계 +```python +class KPIDefinition(Base): + __tablename__ = "tb_kpi" + id = Column(Integer, primary_key=True) + tenant_id = Column(Integer, ForeignKey("tb_tenant.id")) + name = Column(String(100)) # "평균 SR 처리 시간" + formula = Column(Text) # SQL/Python 식 + unit = Column(String(20)) # hours, %, count + target = Column(Float) # 목표값 + direction = Column(String(10)) # LOWER_BETTER / HIGHER_BETTER + period = Column(String(10)) # DAILY/WEEKLY/MONTHLY +``` + +### 예측 분석 (Ollama 기반 시계열) +```python +# 기존 predictive.py + 통계 모델 결합 +async def predict_sla_breach(tenant_id: int, horizon_days: int = 7) -> dict: + # 1. 최근 30일 SLA 이행 데이터 수집 + history = await get_sla_history(tenant_id, days=30) + # 2. 트렌드 분석 (이동평균) + trend = calculate_trend(history) + # 3. Ollama로 자연어 인사이트 생성 + insight = await ollama_analyze(trend, "SLA 위반 예측") + return {"probability": trend["breach_prob"], "insight": insight, "actions": trend["recommendations"]} +``` + +### 자동 보고서 템플릿 +```python +# 기존 report.py 확장 — 기관별 커스텀 템플릿 +REPORT_TEMPLATES = { + "weekly_ops": WeeklyOpsTemplate, # 주간 운영 보고서 + "monthly_sla": MonthlySLATemplate, # 월간 SLA 보고서 + "incident_rca": IncidentRCATemplate, # 인시던트 분석 보고서 + "capacity_plan": CapacityPlanTemplate, # 용량 계획 보고서 +} +``` + +## 작업 원칙 +1. 기존 `analytics.py`, `report.py`, `sla.py`, `finops.py`와 중복되지 않도록 확장 +2. KPI 계산은 PostgreSQL 집계 함수를 최대 활용 (Python 루프 금지) +3. 예측 모델은 Ollama 추론 + 통계 알고리즘 결합 (외부 ML 서비스 사용 금지) +4. 보고서 생성은 기존 `report.py`의 Excel/PDF 패턴 재사용 +5. 벤치마킹 데이터는 반드시 익명화 (기관명, IP 등 식별 정보 제거) + +## 팀 통신 프로토콜 +- **수신**: orchestrator로부터 "BI 모듈 구현 시작"; ai-platform-dev에서 예측 모델 인터페이스 수신; enterprise-integrator에서 외부 데이터 API 수신 +- **발신**: `_workspace/06_bi_spec.md` +- **협업**: saas-platform-dev에게 테넌트별 KPI 대시보드 설정 API 제공 +- **보고**: 완료 후 orchestrator에게 KPI 엔진 + 예측 정확도 테스트 결과 diff --git a/.claude/agents/cloud-container-dev.md b/.claude/agents/cloud-container-dev.md new file mode 100644 index 00000000..a0c3a368 --- /dev/null +++ b/.claude/agents/cloud-container-dev.md @@ -0,0 +1,53 @@ +# cloud-container-dev + +## 핵심 역할 +GUARDiA ITSM에 **클라우드·컨테이너 인프라 관리** 기능을 추가한다. +Kubernetes 클러스터, Docker 서비스, NCloud(네이버 클라우드) 리소스를 SSH/API 기반으로 +에이전트리스 방식으로 관리하는 FastAPI 라우터·모델·서비스를 구현한다. + +## 구현 범위 + +### 신규 라우터 (`workspace/guardia-itsm/routers/`) +| 파일 | 기능 | +|------|------| +| `kubernetes.py` | 클러스터 상태·Pod·Deployment·Service 조회, HPA 설정, 롤링 업데이트 트리거 | +| `docker_mgr.py` | 컨테이너 목록/시작/중지/로그 조회, 이미지 관리, docker-compose 배포 | +| `ncloud.py` | NCloud 서버·로드밸런서·DNS·오브젝트스토리지 조회 (NCloud API) | +| `container_alerts.py` | 컨테이너 헬스 이상 감지 → SR 자동 생성 → 메신저 알림 | + +### 기술 패턴 +```python +# kubectl exec via SSH (에이전트리스) +async def kubectl_cmd(server_ssh, cmd: str) -> dict: + result = await ssh_exec(server_ssh, f"kubectl {cmd} -o json") + return json.loads(result) + +# Docker API via SSH tunnel +async def docker_exec(server_ssh, cmd: str) -> str: + return await ssh_exec(server_ssh, f"docker {cmd}") +``` + +### DB 모델 (`workspace/guardia-itsm/models.py` 확장) +```python +class KubernetesCluster(Base): + __tablename__ = "tb_k8s_cluster" + id = Column(Integer, primary_key=True) + tenant_id = Column(Integer, ForeignKey("tb_tenant.id")) + name = Column(String(100)) + api_server = Column(String(200)) # kubeconfig 또는 SSH 경유 + ssh_server_id = Column(Integer, ForeignKey("tb_server.id")) # SSH 경유 서버 + namespace = Column(String(100), default="default") +``` + +## 작업 원칙 +1. **에이전트리스 원칙 준수**: kubectl/docker는 기존 SSH 서버를 경유한다 +2. 기존 `routers/cmdb.py`의 서버 조회 패턴을 재사용한다 +3. `routers/ssh.py`의 SSH 세션 관리를 상속한다 +4. 컨테이너 이상 감지 시 반드시 `tasks.py`의 SR 생성 흐름을 따른다 +5. NCloud API 키는 AES-256-GCM 암호화 저장 (서버 자격증명과 동일 패턴) + +## 팀 통신 프로토콜 +- **수신**: orchestrator로부터 "cloud 모듈 구현 시작" + 우선순위 목록 +- **발신**: `_workspace/02_cloud_spec.md` (API 엔드포인트 목록) +- **협업**: ai-platform-dev에게 컨테이너 이상 감지 패턴 공유 +- **보고**: 완료 후 orchestrator에게 라우터 목록 + 테스트 결과 전달 diff --git a/.claude/agents/enterprise-integrator.md b/.claude/agents/enterprise-integrator.md new file mode 100644 index 00000000..a0c71779 --- /dev/null +++ b/.claude/agents/enterprise-integrator.md @@ -0,0 +1,72 @@ +# enterprise-integrator + +## 핵심 역할 +GUARDiA ITSM을 **외부 엔터프라이즈 시스템과 통합**한다. +Jira, Slack, ServiceNow, ERP(그룹웨어), SMS/카카오 알림, SSO(SAML/OAuth2)와의 +양방향 연동 커넥터를 FastAPI 라우터로 구현한다. + +## 구현 범위 + +### 신규 라우터 +| 파일 | 기능 | +|------|------| +| `jira_sync.py` | SR ↔ Jira Issue 양방향 동기화, 상태 매핑, 첨부파일 연동 | +| `slack_connector.py` | Slack Incoming Webhook, Slash Commands, Block Kit 메시지 | +| `servicenow.py` | ServiceNow CMDB·Incident 연동, REST API 커넥터 | +| `erp_connector.py` | 그룹웨어 결재 연동 (나라장터, 전자결재), ERP HR 데이터 동기화 | +| `sso_provider.py` | SAML 2.0 / OAuth2 / OIDC SSO (행정안전부 공통로그인 포함) | +| `kakao_notify.py` | 카카오 알림톡 (기존 카카오워크와 별도 — 일반 휴대폰 수신) | + +### 핵심 구현: 범용 커넥터 프레임워크 +```python +# 기존 gateway.py 확장 — 플러그인 방식 +class ConnectorBase(ABC): + @abstractmethod + async def push_event(self, event: dict) -> dict: ... + @abstractmethod + async def pull_data(self, query: dict) -> list: ... + @abstractmethod + async def health_check(self) -> bool: ... + +# 등록 방식 +CONNECTORS = { + "jira": JiraConnector, + "slack": SlackConnector, + "servicenow": ServiceNowConnector, +} +``` + +### Jira 동기화 모델 +```python +class JiraSyncMapping(Base): + __tablename__ = "tb_jira_sync" + sr_id = Column(Integer, ForeignKey("tb_task.id")) + jira_issue_key = Column(String(50)) # PROJ-1234 + jira_project_key = Column(String(20)) + status_mapping = Column(JSON) # {"접수": "Open", "처리중": "In Progress"} + last_synced_at = Column(DateTime) + sync_direction = Column(String(10)) # BOTH/TO_JIRA/FROM_JIRA +``` + +### SSO SAML 플로우 +```python +# 행정안전부 공통로그인 (GPKI) 연동 +async def saml_acs(request: Request) -> RedirectResponse: + assertion = parse_saml_response(await request.form()) + user = await upsert_saml_user(assertion) # 계정 자동 생성/동기화 + token = create_jwt(user) + return RedirectResponse(f"/?token={token}") +``` + +## 작업 원칙 +1. 기존 `routers/gateway.py`의 커넥터 패턴을 상속한다 +2. 외부 API 자격증명은 AES-256-GCM 암호화 저장 (기존 서버 자격증명과 동일) +3. 연동 실패 시 DLQ(Dead Letter Queue) 패턴으로 재시도 (APScheduler) +4. Jira/ServiceNow는 테넌트별 독립 설정 (멀티테넌트 격리) +5. SSO는 기존 `routers/ldap.py` + `routers/auth.py` 패턴 확장 + +## 팀 통신 프로토콜 +- **수신**: orchestrator로부터 "통합 모듈 구현 시작"; saas-platform-dev에게 SSO 연동 요청 수신 +- **발신**: `_workspace/05_integration_spec.md` +- **협업**: bi-analytics-dev에게 외부 시스템 데이터 수집 API 제공 +- **보고**: 완료 후 orchestrator에게 커넥터 목록 + Jira E2E 동기화 테스트 결과 diff --git a/.claude/agents/saas-platform-dev.md b/.claude/agents/saas-platform-dev.md new file mode 100644 index 00000000..bff30871 --- /dev/null +++ b/.claude/agents/saas-platform-dev.md @@ -0,0 +1,64 @@ +# saas-platform-dev + +## 핵심 역할 +GUARDiA ITSM을 **멀티테넌트 SaaS 플랫폼**으로 확장한다. +화이트라벨 브랜딩, 셀프서비스 기관 온보딩, 구독 관리, 사용량 과금, +기관별 커스터마이즈 설정을 구현한다. + +## 구현 범위 + +### 신규 라우터 +| 파일 | 기능 | +|------|------| +| `tenant_portal.py` | 기관 관리자 셀프서비스 포털 (사용자·서버·설정 자체 관리) | +| `white_label.py` | 로고·색상·도메인 커스터마이즈, 테넌트별 UI 설정 | +| `subscription.py` | 구독 플랜(COMMUNITY/STANDARD/ENTERPRISE), 갱신·업그레이드·해지 | +| `billing.py` | 사용량 측정 (서버 수·API 호출·SR 건수), 월별 청구서 생성 | +| `onboarding.py` | 신규 기관 온보딩 마법사 (DB 초기화·관리자 계정·서버 등록 자동화) | + +### 핵심 구현: 테넌트 격리 강화 +```python +# Row-Level Security 미들웨어 (기존 middleware/tenant.py 강화) +class TenantIsolationMiddleware: + async def __call__(self, request, call_next): + tenant_id = extract_tenant(request) + # 모든 DB 쿼리에 tenant_id 필터 자동 주입 + set_tenant_context(tenant_id) + response = await call_next(request) + return response +``` + +### 화이트라벨 설정 모델 +```python +class TenantBranding(Base): + __tablename__ = "tb_tenant_branding" + tenant_id = Column(Integer, ForeignKey("tb_tenant.id"), unique=True) + logo_url = Column(String(500)) + primary_color = Column(String(7)) # #003366 + company_name = Column(String(200)) + custom_domain = Column(String(200)) # guardia.기관명.go.kr + favicon_url = Column(String(500)) + email_template = Column(Text) # 발신 메일 커스터마이즈 +``` + +### 구독 플랜 정의 +```python +PLANS = { + "COMMUNITY": {"max_servers": 20, "max_users": 10, "price": 0}, + "STANDARD": {"max_servers": 200, "max_users": 100, "price": 500000}, + "ENTERPRISE": {"max_servers": -1, "max_users": -1, "price": None}, # 협의 +} +``` + +## 작업 원칙 +1. 기존 `routers/tenant_mgmt.py`를 기반으로 확장한다 +2. 온보딩 마법사는 기존 `routers/onboarding.py` 패턴을 고도화한다 +3. 화이트라벨 설정은 React 프론트엔드의 CSS 변수로 동적 적용 +4. 구독·과금 데이터는 별도 `billing_db` 스키마에 격리 (보안) +5. 기관별 커스텀 도메인은 nginx 설정 자동 생성으로 처리 + +## 팀 통신 프로토콜 +- **수신**: orchestrator로부터 "SaaS 모듈 구현 시작" +- **발신**: `_workspace/04_saas_spec.md` +- **협업**: enterprise-integrator에게 SSO/LDAP 온보딩 연계 요청 +- **보고**: 완료 후 orchestrator에게 신규 테넌트 온보딩 E2E 플로우 보고 diff --git a/.claude/skills/guardia-expansion-orchestrator/SKILL.md b/.claude/skills/guardia-expansion-orchestrator/SKILL.md new file mode 100644 index 00000000..c7217c8d --- /dev/null +++ b/.claude/skills/guardia-expansion-orchestrator/SKILL.md @@ -0,0 +1,248 @@ +--- +name: guardia-expansion-orchestrator +description: > + GUARDiA ITSM 플랫폼 확장 오케스트레이터. 현재 81개 라우터에서 다음 5개 영역으로 확장한다: + (1) 클라우드·컨테이너 인프라 관리 (Kubernetes/Docker/NCloud), + (2) AI 플랫폼 고도화 (RAG 강화, 자율 워크플로우, 멀티모달), + (3) 멀티테넌트 SaaS 확장 (화이트라벨, 구독, 기관 온보딩), + (4) 엔터프라이즈 통합 (Jira/Slack/ServiceNow/ERP/SSO), + (5) 비즈니스 인텔리전스 (KPI 엔진, 예측 분석, 자동 보고서). + guardia-itsm 기존 패턴(FastAPI+SQLAlchemy+paramiko) 준수. 외부 API 완전 금지. + 다음 상황에서 반드시 사용: + (1) 'GUARDiA 확장', '신규 기능 추가', '가디아 고도화'; + (2) Kubernetes/Docker/컨테이너/클라우드 관리 기능; + (3) AI RAG/자율화/멀티모달 고도화; + (4) SaaS/화이트라벨/구독/온보딩 구현; + (5) Jira/Slack/ServiceNow/ERP/SSO 연동; + (6) KPI/BI 대시보드/예측 분석/자동 보고서; + (7) 다시 실행, 업데이트, 수정, 보완. +--- + +# GUARDiA 플랫폼 확장 오케스트레이터 + +**실행 모드:** 하이브리드 +- Phase 1 (현황 분석): 서브 에이전트 (itsm-dev — 기존 코드베이스 분석) +- Phase 2~4 (구현): **에이전트 팀** (cloud-container-dev + ai-platform-dev + saas-platform-dev + enterprise-integrator + bi-analytics-dev) +- Phase 5 (QA): 서브 에이전트 (cross-system-qa) + +--- + +## Phase 0: 컨텍스트 확인 + +``` +_workspace/ 존재 여부: +- 없음 → 초기 구현 (Phase 1부터) +- 있음 + 특정 영역 요청 → 해당 에이전트만 재실행 + 예: "Jira 연동만 다시" → enterprise-integrator만 Phase 3 재실행 +- 있음 + 전체 재구성 → _workspace/ → _workspace_prev/ 이동 후 전체 재실행 +``` + +--- + +## Phase 1: 현황 분석 (서브 에이전트) + +**itsm-dev** 서브 에이전트로 실행: + +``` +분석 항목: +1. workspace/guardia-itsm/routers/ 전체 파일 목록 +2. 각 확장 영역과 기존 라우터 중복 분석 + - cloud: ssh.py, infra_ext.py, scouter.py → 재사용 가능 + - ai: anomaly.py, chatbot.py, kb_agent.py, autonomous.py → 확장 기반 + - saas: tenant_mgmt.py, onboarding.py, license.py → 확장 기반 + - integration: gateway.py, ldap.py, groupware.py → 확장 기반 + - bi: analytics.py, finops.py, sla.py, report.py → 확장 기반 +3. 확장 구현 시 사용할 공통 유틸 파악 +4. DB 모델에서 재사용 가능한 테이블 파악 +``` + +산출물: `_workspace/01_analysis_report.md` + +--- + +## Phase 2: 5개 영역 병렬 설계 (에이전트 팀) + +**팀 구성 (TeamCreate):** +- 리더: orchestrator +- 팀원: cloud-container-dev, ai-platform-dev, saas-platform-dev, enterprise-integrator, bi-analytics-dev + +**작업 할당 (TaskCreate):** + +| 에이전트 | 작업 | 산출물 | +|---------|------|--------| +| cloud-container-dev | kubernetes.py, docker_mgr.py, ncloud.py, container_alerts.py 설계 | `_workspace/02_cloud_spec.md` | +| ai-platform-dev | rag_engine.py, autonomous_workflow.py, ai_insights.py, multimodal.py, learning_loop.py 설계 | `_workspace/03_ai_spec.md` | +| saas-platform-dev | tenant_portal.py, white_label.py, subscription.py, billing.py, onboarding.py 설계 | `_workspace/04_saas_spec.md` | +| enterprise-integrator | jira_sync.py, slack_connector.py, servicenow.py, erp_connector.py, sso_provider.py, kakao_notify.py 설계 | `_workspace/05_integration_spec.md` | +| bi-analytics-dev | bi_dashboard.py, kpi_engine.py, predictive_ops.py, auto_report.py, benchmark.py 설계 | `_workspace/06_bi_spec.md` | + +**팀원 간 인터페이스 조율 (SendMessage):** +- cloud → ai: 컨테이너 이상 이벤트 스키마 +- ai → bi: 예측 모델 API 인터페이스 +- saas → integration: SSO 연동 요청 스키마 +- integration → bi: 외부 데이터 수집 API + +--- + +## Phase 3: 구현 (에이전트 팀 계속) + +### 구현 우선순위 + +**P1 (즉시 구현 — 고가치·저복잡도):** +``` +1. ai/rag_engine.py — 기존 pgvector + Ollama, 즉각 효과 +2. integration/jira_sync.py — 고객 요청 최다 +3. bi/kpi_engine.py — 기존 analytics 기반 빠른 구현 +4. saas/tenant_portal.py — 기존 tenant_mgmt 확장 +``` + +**P2 (다음 스프린트 — 중간 복잡도):** +``` +5. cloud/kubernetes.py — SSH 경유 kubectl, 에이전트리스 유지 +6. ai/autonomous_workflow.py — 기존 autonomous.py 고도화 +7. integration/sso_provider.py — SAML/OIDC +8. bi/predictive_ops.py — ML 모델 적용 +``` + +**P3 (장기 — 고복잡도):** +``` +9. saas/billing.py — 과금 시스템 +10. integration/servicenow.py — 외부 ITSM 연동 +11. ai/learning_loop.py — 파인튜닝 파이프라인 +12. bi/benchmark.py — 멀티테넌트 비교 분석 +``` + +### 구현 원칙 (모든 에이전트 공통) + +```python +# 1. 라우터 등록 (workspace/guardia-itsm/main.py) +from routers import kubernetes, rag_engine, tenant_portal, jira_sync, kpi_engine +app.include_router(kubernetes.router, prefix="/api/k8s", tags=["Cloud"]) +app.include_router(rag_engine.router, prefix="/api/rag", tags=["AI"]) + +# 2. 보안 — 모든 엔드포인트 JWT 필수 +from core.auth import get_current_user +@router.get("/clusters") +async def list_clusters(user=Depends(get_current_user)): + ... + +# 3. 테넌트 격리 — 모든 쿼리에 tenant_id 적용 +clusters = await db.execute( + select(K8sCluster).where(K8sCluster.tenant_id == user.tenant_id) +) + +# 4. 에러 응답 — SR ID만 노출 +raise HTTPException(500, detail=f"SR-{sr_id}: 서버 오류") +``` + +--- + +## Phase 4: DB 마이그레이션 + +각 에이전트가 생성한 신규 모델을 DB에 반영: + +```python +# workspace/guardia-itsm/migrations/v3_expansion.py +from alembic import op +import sqlalchemy as sa + +def upgrade(): + # Cloud + op.create_table('tb_k8s_cluster', ...) + op.create_table('tb_docker_service', ...) + # AI + op.create_table('tb_auto_workflow', ...) + op.create_table('tb_rag_feedback', ...) + # SaaS + op.create_table('tb_tenant_branding', ...) + op.create_table('tb_subscription', ...) + # Integration + op.create_table('tb_jira_sync', ...) + op.create_table('tb_connector_config', ...) + # BI + op.create_table('tb_kpi', ...) + op.create_table('tb_kpi_value', ...) +``` + +--- + +## Phase 5: QA (서브 에이전트) + +**cross-system-qa** 서브 에이전트: + +``` +검증 항목: +1. 신규 라우터 임포트 오류 없음 +2. JWT 인증 누락 엔드포인트 없음 +3. 테넌트 격리 누락 쿼리 없음 +4. 외부 API 호출 코드 없음 (온프레미스 원칙) +5. ServerOut 스키마에 민감 정보 노출 없음 +6. 각 라우터의 /docs 표시 확인 +``` + +--- + +## 데이터 흐름 + +``` +_workspace/ +├── 01_analysis_report.md ← itsm-dev (기존 코드 분석) +├── 02_cloud_spec.md ← cloud-container-dev +├── 03_ai_spec.md ← ai-platform-dev +├── 04_saas_spec.md ← saas-platform-dev +├── 05_integration_spec.md ← enterprise-integrator +├── 06_bi_spec.md ← bi-analytics-dev +└── 07_qa_report.md ← cross-system-qa +``` + +--- + +## 에러 핸들링 + +| 에러 | 처리 | +|------|------| +| 기존 라우터와 충돌 | Phase 1 분석 재실행, 접두사 변경 | +| DB 마이그레이션 실패 | 롤백 후 에러 보고 | +| 외부 API 호출 발견 | 즉시 중단, 온프레미스 대안 제시 | +| 테넌트 격리 누락 | QA에서 감지, 해당 에이전트 재호출 | + +--- + +## 확장 로드맵 + +상세 로드맵은 `references/expansion-roadmap.md` 참조. + +--- + +## 테스트 시나리오 + +**정상 흐름:** +1. "K8s 클러스터 관리 기능 추가해줘" +2. Phase 1: itsm-dev가 ssh.py, infra_ext.py 분석 +3. Phase 2: cloud-container-dev가 kubernetes.py 설계 +4. Phase 3: kubernetes.py 구현 + main.py 등록 +5. Phase 5: QA — JWT 확인, 테넌트 격리 확인 +6. "✅ Kubernetes 클러스터 관리 API 추가 완료" + +**에러 흐름:** +- kubernetes.py에서 외부 K8s API 직접 호출 → QA 감지 → SSH 경유로 재구현 + +--- + +## should-trigger + +- "가디아 확장해줘" +- "K8s 관리 기능 추가" +- "Jira 연동 구현" +- "KPI 대시보드 만들어줘" +- "화이트라벨 기능" +- "RAG 강화해줘" +- "구독 관리 시스템" +- "다시 실행", "수정", "보완" + +## should-NOT-trigger + +- "guardia-itsm SR 접수해줘" → guardia-orchestrator +- "ITSM UI 개편" → ui-overhaul-orchestrator +- "CI/CD 파이프라인" → cicd-pipeline-orchestrator +- "5개 시스템 배포 확인" → system-sync-orchestrator diff --git a/.claude/skills/guardia-expansion-orchestrator/references/expansion-roadmap.md b/.claude/skills/guardia-expansion-orchestrator/references/expansion-roadmap.md new file mode 100644 index 00000000..a801772f --- /dev/null +++ b/.claude/skills/guardia-expansion-orchestrator/references/expansion-roadmap.md @@ -0,0 +1,229 @@ +# GUARDiA 플랫폼 확장 로드맵 + +## 현황 (2026-06-01 기준) + +| 카테고리 | 구현 완료 | 미구현 | +|---------|---------|--------| +| ITSM 핵심 | SR, CMDB, CAB, Problem, SLA, SVC Catalog | — | +| AI/자동화 | Anomaly, Chatbot, Code Review, KB Agent, RPA, Scraping | RAG 강화, 자율 워크플로우, 멀티모달 | +| 인프라 | SSH, Scouter APM, infra_ext, shell_scripts | Kubernetes, Docker, NCloud | +| 보안 | LDAP, PAM, OTP, Vuln Scan, CSAP, Audit | SSO(SAML), 위협 헌팅 | +| 리포트 | analytics, sla, report, finops | KPI 엔진, 예측 분석, 벤치마킹 | +| 통합 | gateway, groupware | Jira, Slack, ServiceNow, ERP | +| SaaS | tenant_mgmt, license, onboarding | 화이트라벨, 구독, 과금 | +| SI 관리 | si_projects, si_wbs, si_milestones | — | +| DR/네트워크 | dr.py, network_devices.py | — | + +--- + +## Phase 1 확장 (즉시 — P1) + +### 1-1. AI RAG 강화 (`rag_engine.py`) + +**목표:** 현재 단순 벡터 검색 → 하이브리드 검색(BM25+벡터) + 재순위화 + +``` +현재: 쿼리 → pgvector → Ollama +목표: 쿼리 → BM25+pgvector → Cross-Encoder 재순위 → Ollama +``` + +**구현 포인트:** +- `pgvector` 기존 임베딩 재사용 +- PostgreSQL FTS (Full-Text Search) 추가 +- RRF(Reciprocal Rank Fusion) 결합 알고리즘 +- 피드백 루프: 사용자 평점 → 검색 품질 개선 + +**예상 효과:** SR 자동 분류 정확도 15% 향상, 지식베이스 검색 응답 품질 개선 + +--- + +### 1-2. Jira 양방향 동기화 (`jira_sync.py`) + +**목표:** SR ↔ Jira Issue 실시간 동기화 + +``` +SR 생성 → Jira Issue 자동 생성 +Jira 상태 변경 → SR 상태 자동 업데이트 +코멘트 양방향 동기화 +첨부파일 동기화 +``` + +**구현 포인트:** +- Jira REST API v3 (Cloud) + Jira Server API +- Webhook 수신 (Jira → GUARDiA) +- 상태 매핑 테이블 (기관별 커스터마이즈) +- 멀티테넌트: 기관마다 별도 Jira 설정 + +--- + +### 1-3. KPI 엔진 (`kpi_engine.py`) + +**목표:** 기관별 KPI 정의·계산·목표 추적 대시보드 + +``` +지표 예시: +- MTTR (평균 복구 시간): 목표 < 4시간 +- FCR (첫 번째 해결율): 목표 > 80% +- SLA 준수율: 목표 > 95% +- SR 적체율: 목표 < 10건 +``` + +**구현 포인트:** +- KPI 정의는 SQL/Python 식으로 커스터마이즈 +- 일별/주별/월별 자동 계산 (APScheduler) +- 목표 대비 신호등 상태 (RED/YELLOW/GREEN) +- 기존 `analytics.py` 데이터 재사용 + +--- + +### 1-4. 테넌트 셀프서비스 포털 (`tenant_portal.py`) + +**목표:** 기관 관리자가 직접 설정 관리 (GUARDiA Manager 연동) + +``` +기관 관리자 권한: +- 사용자 등록/삭제/역할 변경 +- 서버 자산 등록 +- 알림 설정 (수신자, 임계값) +- 비밀번호 정책 설정 +``` + +--- + +## Phase 2 확장 (1~2개월 — P2) + +### 2-1. Kubernetes 관리 (`kubernetes.py`) + +**에이전트리스 K8s 관리:** +```bash +# SSH 경유 kubectl 실행 +ssh opsagent@k8s-master "kubectl get pods -n production -o json" +ssh opsagent@k8s-master "kubectl rollout restart deployment/app" +``` + +**기능 목록:** +- 클러스터/네임스페이스/Pod 현황 조회 +- Deployment 롤링 업데이트 트리거 +- HPA(수평 자동 확장) 현황 조회 +- Pod 로그 실시간 스트리밍 (WebSocket) +- 리소스 사용률 수집 (CPU/메모리/디스크) + +--- + +### 2-2. 자율 워크플로우 엔진 (`autonomous_workflow.py`) + +**현재 autonomous.py 확장:** +```python +# 기존: 단순 자동 승인 큐 +# 목표: 조건 기반 자동 실행 워크플로우 +{ + "trigger": "SR_CREATED", + "condition": "sr.category == 'MONITORING' AND sr.priority < 3", + "actions": [ + {"type": "AUTO_ASSIGN", "rule": "ROUND_ROBIN"}, + {"type": "NOTIFY", "channel": "messenger"}, + {"type": "HEALTH_CHECK", "delay_minutes": 5} + ], + "approval_required": false +} +``` + +--- + +### 2-3. SSO 통합 (`sso_provider.py`) + +**행정안전부 공통로그인 + 기업 IdP 지원:** +- SAML 2.0 (행정안전부 GPKI, 국가정보자원관리원) +- OIDC/OAuth2 (Google Workspace, Microsoft Entra) +- LDAP/AD (기존 `ldap.py` 활용) + +--- + +### 2-4. 예측 운영 분석 (`predictive_ops.py`) + +**기존 predictive.py 고도화:** +```python +# 7일 후 장애 발생 확률 예측 +{ + "server_id": 42, + "failure_probability_7d": 0.78, + "main_indicators": ["CPU 트렌드", "디스크 증가율"], + "recommended_action": "긴급 점검 SR 생성", + "confidence": 0.85 +} +``` + +--- + +## Phase 3 확장 (3~6개월 — P3) + +### 3-1. 구독·과금 시스템 (`subscription.py`, `billing.py`) + +``` +플랜: COMMUNITY → STANDARD → ENTERPRISE +서버 수: 20 → 200 → 무제한 +사용자 수: 10 → 100 → 무제한 +가격(월): 무료 → 50만원 → 협의 +청구 주기: 월납 / 연납 (10% 할인) +``` + +### 3-2. 멀티모달 AI (`multimodal.py`) + +``` +입력: 스크린샷, 로그 파일, 에러 이미지 +처리: Ollama llava 모델 +출력: 에러 분류, 해결 방법, SR 자동 생성 +``` + +### 3-3. 기관 간 벤치마킹 (`benchmark.py`) + +``` +익명화된 업계 평균과 비교: +- 우리 기관 MTTR vs 공공기관 평균 MTTR +- SR 처리 속도 순위 (익명 백분위) +- SLA 준수율 업계 평균 대비 +``` + +### 3-4. Self-Improving Learning Loop (`learning_loop.py`) + +``` +1. 사용자 피드백 수집 (AI 응답 평가) +2. 저품질 응답 샘플 수집 +3. Ollama 파인튜닝 데이터셋 생성 +4. 모델 파인튜닝 (주 1회 자동 실행) +5. 성능 비교 후 배포 (A/B 테스트) +``` + +--- + +## 신규 라우터 목록 (전체) + +| 영역 | 파일명 | 우선순위 | +|------|-------|---------| +| Cloud | kubernetes.py | P2 | +| Cloud | docker_mgr.py | P2 | +| Cloud | ncloud.py | P3 | +| Cloud | container_alerts.py | P2 | +| AI | rag_engine.py | **P1** | +| AI | autonomous_workflow.py | P2 | +| AI | ai_insights.py | P2 | +| AI | multimodal.py | P3 | +| AI | learning_loop.py | P3 | +| SaaS | tenant_portal.py | **P1** | +| SaaS | white_label.py | P2 | +| SaaS | subscription.py | P3 | +| SaaS | billing.py | P3 | +| Integration | jira_sync.py | **P1** | +| Integration | slack_connector.py | P2 | +| Integration | servicenow.py | P3 | +| Integration | erp_connector.py | P2 | +| Integration | sso_provider.py | P2 | +| Integration | kakao_notify.py | P2 | +| BI | bi_dashboard.py | **P1** | +| BI | kpi_engine.py | **P1** | +| BI | predictive_ops.py | P2 | +| BI | auto_report.py | P2 | +| BI | benchmark.py | P3 | +| BI | cohort_analysis.py | P3 | + +**총 25개 신규 라우터** (P1: 6개, P2: 11개, P3: 8개) diff --git a/CLAUDE.md b/CLAUDE.md index 8cdd9b9d..1f8e22dd 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -279,6 +279,23 @@ GUARDiA ITSM (허브, :9001/:8443) --- +## 하네스: GUARDiA 플랫폼 확장 + +**목표:** GUARDiA ITSM 81개 라우터에서 25개 신규 라우터 추가. 클라우드/컨테이너·AI 고도화·멀티테넌트 SaaS·엔터프라이즈 통합·BI 5개 영역 확장. + +**트리거:** GUARDiA 확장, 신규 기능 추가, 고도화 요청 시 `guardia-expansion-orchestrator` 스킬을 사용하라. K8s/Docker/Jira/Slack/KPI/RAG/SaaS/화이트라벨/구독 관련 모든 요청 포함. + +**에이전트:** cloud-container-dev · ai-platform-dev · saas-platform-dev · enterprise-integrator · bi-analytics-dev + +**로드맵:** `.claude/skills/guardia-expansion-orchestrator/references/expansion-roadmap.md` + +**변경 이력:** +| 날짜 | 변경 내용 | 대상 | 사유 | +|------|----------|------|------| +| 2026-06-01 | 초기 하네스 구성 | 전체 | GUARDiA 플랫폼 확장 5개 영역 | + +--- + ## 하네스: zioinfo-mail 웹메일 시스템 **목표:** 지오정보기술 Postfix/Dovecot SMTP 서버를 활용한 React+FastAPI 웹메일 클라이언트 구축. `mail.zioinfo.co.kr:8025`, IMAP/SMTP 연동, 3-패널 메일 UI.