# GUARDiA ESN — ESL 통합 관리 플랫폼

> 레거시 ESL(전자 가격표) 8개 Spring Boot 1.5 프로젝트를 단일 현대화 플랫폼으로 통합한 프로젝트

---

## 프로젝트 개요

`C:\GUARDiA\workspace\esn\` 의 레거시 ESN 시스템(ESN_WEB_ZIOINFO·ESN_WEB_LGInnotek·ESN_DAEMON_EMART·ESN_DAEMON_LGIT·esn·ESL_AUTO_UPDATE·restapi_lgit·UCS_LGU)을  
**Spring Boot 3.5 + Java 17 + React 19 + PostgreSQL** 단일 플랫폼으로 재구현.

멀티테넌트 (TENANT_A / TENANT_B / EMART / ZIOINFO), Ollama 온프레미스 AI 알람 분석·POS 자동 분류.

---

## 기술 스택

| 레이어 | 기술 |
|--------|------|
| Backend | Spring Boot 3.5 · Java 17 · MyBatis 3.0.3 |
| Database | PostgreSQL (`guardia_esn_db` / `guardia_esn_user`) |
| Frontend | React 19 · Vite · TypeScript · Tailwind CSS |
| AI | Ollama 온프레미스 (llama3, llava) |
| 인증 | Spring Security · JWT (jjwt 0.12.6) |
| 배포 | 단일 JAR (Vite 번들 → static/) |

---

## 실행 명령어

```bash
# 프론트엔드 빌드 (필수 — 백엔드 static/ 번들)
cd frontend && npm install && npm run build

# 백엔드 빌드 + 실행
cd backend && mvn clean package -DskipTests
java -jar target/zioinfo-esn-1.0.0.jar \
  --spring.datasource.url=jdbc:postgresql://localhost:5432/guardia_esn_db \
  --spring.datasource.username=guardia_esn_user \
  --spring.datasource.password=guardia_esn_pass2026 \
  --server.port=8016
```

---

## 환경변수

| 변수 | 기본값 | 설명 |
|------|--------|------|
| DB_URL | jdbc:postgresql://localhost:5432/esn_db | 운영에서는 guardia_esn_db |
| DB_USER | esn_user | 운영에서는 guardia_esn_user |
| DB_PASS | esn_pass2026 | 운영에서는 guardia_esn_pass2026 |
| OLLAMA_URL | http://localhost:11434 | Ollama 서버 |
| JWT_SECRET | ZioInfoEsnJwtSecret... | JWT 서명 키 |

---

## 디렉터리 구조

```
workspace/guardia-esn/
├── .claude/
│   ├── agents/                   (에이전트 4종)
│   └── skills/guardia-esn-orchestrator/SKILL.md
├── CLAUDE.md                     ← 이 파일
├── Jenkinsfile
├── backend/
│   ├── pom.xml
│   └── src/main/
│       ├── java/com/zioinfo/esn/ (67개 Java 파일)
│       └── resources/
│           ├── application.yml
│           ├── db/schema.sql     (13개 테이블)
│           └── mapper/*.xml      (15개 MyBatis XML)
└── frontend/
    └── src/
        ├── App.tsx
        ├── api/client.ts
        ├── components/           (Layout, Sidebar, Header...)
        └── pages/                (15개 관리자 화면)
```

---

## 도메인 (13개)

| 도메인 | 테이블 | 설명 |
|--------|--------|------|
| Tenant | esn_tenants | 멀티테넌트 (LGINNOTEK·LGIT·EMART·ZIOINFO) |
| StoreGroup | esn_store_groups | 매장 그룹 |
| Store | esn_stores | 매장 (tenantCode 격리) |
| Template | esn_templates | ESL 표시 템플릿 |
| PosCvt | esn_pos_cvt | POS→ESL 가격 변환 |
| Alarm | esn_alarms | 장치 알람 |
| HCore | esn_hcores | 게이트웨이/허브 |
| WorkHistory | esn_work_history | 작업 이력 |
| Firmware | esn_firmware | 펌웨어 버전 |
| User | esn_users | 사용자 (RBAC) |
| Product | esn_products | 상품/가격 |
| TagBinding | esn_tag_bindings | ESL↔상품 바인딩 |
| UpdateQueue | esn_update_queue | 업데이트 큐 |

---

## 보안 제약 (불변)

1. `@MapperScan(annotationClass = Mapper.class)` — basePackages 절대 금지
2. Hikari `maximum-pool-size=3` — 공유 PG 서버 보호
3. 외부 AI API 절대 금지 — Ollama localhost:11434만 허용
4. API 응답에서 `passwordHash`, `ssh_*` 필드 완전 제외
5. SecurityConfig에 static 리소스 `permitAll` 필수 (SPA 403 방지)

---

## 하네스 트리거

`guardia-esn-orchestrator` 스킬을 사용하라:
- ESN 기능 추가·수정
- 배포 작업
- 레거시 소스 분석·통합
- 알람·POS·HCore 관련 작업

## AI 에이전트 (최신 기법 — 중앙 guardia-rag 연계)

`.claude/agents/` 의 도메인 맞춤 AI 에이전트 4종(외부 API 금지·Ollama 전용·테넌트 격리·소형모델 기본·degraded 폴백, 중앙 계약 `/answer`·`/verify`·`/agent`·`/structured`·`/feedback`):
- `esn-ai-alarm-agent` — ESL/HCore 알람 원인분석·우선순위(tool-use + GraphRAG 의존성 추적)
- `esn-ai-poscvt-agent` — POS 데이터 자동 분류·매핑 보조(`/structured` format:json 결정론)
- `esn-ai-applier` — 최신 기법(hybrid/graph/rerank·tool-use·structured·스트리밍) ESN 적용·배선·기법 토글
- `esn-ai-qa` — 근거·결정론·테넌트 격리·외부 API 0 경계면 검증(general-purpose)