> For the complete documentation index, see [llms.txt](https://kopens.gitbook.io/plantpulse-platform/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kopens.gitbook.io/plantpulse-platform/developer/modules.md). # 주요 모듈 설명 ## 플랫폼 모듈 구성 이 문서에서는 플랜트펄스 플랫폼을 구성하는 주요 모듈들을 개발자 관점에서 안내합니다. 운영자 관점의 상세 매뉴얼은 [모듈별 상세 매뉴얼](/plantpulse-platform/admin/modules.md) 페이지를 참고해 주세요. 플랫폼은 다수의 독립적인 서비스 모듈로 구성되며, 환경에 따라 다음 경로에 설치됩니다. | 환경 | 설치 경로 | | -------------- | ---------------------------------------------- | | 바이너리 (dev 표준) | `/opt/kopens/plantpulse-platform/plantpulse-*` | | Docker 컨테이너 내부 | `/home/kopens/plantpulse-*` | 각 모듈은 `plantpulse-startup` 스크립트에 의해 통합 관리됩니다. 처음 플랫폼을 접하시는 분이라면, 먼저 핵심 애플리케이션 모듈(특히 plantpulse-server)의 역할을 이해하신 뒤, 인프라 모듈과 유틸리티 모듈을 순서대로 살펴보시는 것을 권장합니다. ### 핵심 애플리케이션 모듈 | 모듈 | 포트 | 기술 스택 | 설명 | | ------------------------------ | --------------- | -------------------------------- | -------------------------------------- | | **plantpulse-server** | 80 / 443 / 7443 | Java 21 / Tomcat 10 / Spring MVC | 웹 관리 콘솔, REST API V5, IIoT 엔진 (36 스레드) | | **plantpulse-plugin (OPC-UA)** | 11004 / 11005 | Java | 산업 표준 OPC-UA 서버 + 데이터 수집 어댑터 | | **plantpulse-cep** | 7400 / 7401 | Java / Esper / Tomcat | 복합 이벤트 처리 엔진, EQL 쿼리 실행 | | **plantpulse-batch** | 9500 | Java/Tomcat | 배치 처리 서버, 이벤트 로직 실행 | | **plantpulse-data-gateway** | 5500 | Java/Tomcat | HTTP REST 데이터 게이트웨이, 외부 시스템 연동 | | **plantpulse-sql** | 4000 | Java/Tomcat | SQL 쿼리 도구, PostgreSQL 메타스토어 직접 조회 | | **plantpulse-monitor** | 4949 | Java | 시스템 모니터링 에이전트, 메트릭 수집 | | **plantpulse-warehouse** | 9600 | Java | 데이터 웨어하우스, S3 연동 | | **plantpulse-plugin** | 11004 | Java | 플러그인 시스템 (OPC-UA 등) | ### 인프라 모듈 | 모듈 | 구성 요소 | 설명 | | ------------------------- | -------------------------------------------------------------------------------------------------- | ------------- | | **plantpulse-messaging** | Kafka (9092), MQTT (1883), STOMP (61000) | 산업용 메시지 버스 | | **plantpulse-storage** | Cassandra (9042), PostgreSQL (5432), Valkey/Redis (6379), MinIO (9000), JanusGraph, RustFS, WeedFS | 멀티 스토리지 계층 | | **plantpulse-analytics** | Spark (7077), Kyuubi (10000), Gravitino (19001), Hadoop, Hive | 분산 분석 엔진 | | **plantpulse-timeseries** | 엔진 (7800), UI (3000) | 시계열 데이터 처리 엔진 | | **plantpulse-workflow** | Kestra (8233), Temporal (8380) | 워크플로우 오케스트레이션 | ### 유틸리티 모듈 | 모듈 | 설명 | | --------------------------- | ----------------------------------------------------------------- | | **plantpulse-startup** | 플랫폼 시작/중지/재시작/상태 확인 스크립트 | | **plantpulse-setup** | 초기 모델 셋업 도구 (CSV 기반 모델 구성) | | **plantpulse-backup** | 자동 백업 서비스 | | **plantpulse-recovery** | 데이터 복구 도구 | | **plantpulse-exporter** | 에셋 데이터 내보내기 (`./export.sh [에셋ID] [시작일] [종료일] [출력디렉토리]`) | | **plantpulse-migrator** | Spark 기반 데이터 마이그레이션 (`./run.sh SOURCE_IP TARGET_IP SCHEME.TABLE`) | | **plantpulse-mirror-maker** | 클러스터 간 데이터 복제 | | **plantpulse-simulator** | 테스트용 데이터 시뮬레이터 | | **plantpulse-api** | REST API 클라이언트 라이브러리 (JAR) | ### 모듈 디렉토리 구조 대부분의 서비스 모듈은 아래와 같은 동일한 디렉토리 구조를 따릅니다. ``` plantpulse-{module}/ ├── app/ # 애플리케이션 설정 ├── bin/ # 시작/중지 스크립트 ├── logs/ # 로그 파일 └── server/ # 서버 런타임 (Tomcat 등) ``` 유틸리티 모듈의 디렉토리 구조는 다음과 같습니다. ``` plantpulse-{utility}/ ├── bin/ # 실행 스크립트 ├── config/ # 설정 파일 ├── lib/ # 라이브러리 (JAR) └── logs/ # 로그 파일 ``` *** ## Server 모듈 패키지 구조 `plantpulse-server`는 플랫폼의 핵심 모듈로, 웹 관리 콘솔과 IIoT 엔진을 포함하고 있습니다. 아래에서 전체 패키지 구조를 확인하실 수 있습니다. ``` src/plantpulse/ ├── core/ # 핵심 엔진 및 서비스 │ ├── api/ # API 인증·토큰 관리 │ ├── bean/ # 도메인 모델 (VO/DTO) │ ├── client/ # 외부 서비스 클라이언트 │ ├── context/ # 앱 라이프사이클·컨텍스트 │ ├── dao/ # PostgreSQL DAO (32+) │ ├── db/ # DB 연결 관리 │ ├── diagnostic/ # 진단·헬스체크 │ ├── engine/ # 코어 엔진 │ ├── infra/ # 인프라 모니터링 │ ├── listener/ # 실시간 데이터 리스너 │ ├── service/ # 비즈니스 서비스 (20+) │ └── token/ # API 토큰 관리 ├── server/ │ ├── filter/ # HTTP 필터 (13개) │ ├── mvc/ # MVC 컨트롤러 (103개) │ ├── interceptor/ # Spring 인터셉터 │ └── listener/ # HTTP 리스너 └── utils/ # 유틸리티 (25+ 패키지) ``` ## Core Engine (`plantpulse.core.engine`) 엔진은 플랫폼의 심장부로, 데이터 수집/처리/저장/분배를 담당합니다. 아래에서 각 서브시스템의 역할을 안내합니다. ### EngineManager 엔진 전체 라이프사이클을 관리하는 싱글턴 클래스입니다. * 30+ Deployer를 순서대로 실행하여 각 서브시스템을 초기화합니다. * Graceful Shutdown을 지원합니다. * 상태 모니터링 및 JMX 노출 기능을 제공합니다. ### Pipeline (`engine/pipeline/`) 실시간 데이터 인제스트 파이프라인입니다. * **Sharding**: 태그 ID 해시 기반으로 워커를 분배합니다. * **MPMC Queue**: 다중 생산자/다중 소비자 큐를 사용합니다. * **O3 Buffer**: Out-of-Order 데이터를 정렬합니다. * **6단계 처리**: Prepare → Validate → Cache → Stream → Store → DDS 순서로 처리됩니다. * **백업**: 큐 오버플로 시 RocksDB 기반 오프로딩이 수행됩니다. ### CEP Engine (`engine/cep/`) Esper 기반 복합 이벤트 처리 엔진입니다. * EPL (Event Processing Language) 쿼리를 실행합니다. * 10개의 내장 EPL 스테이트먼트가 제공됩니다. * 알람 규칙, 이상 감지, 성능 모니터링 등에 활용됩니다. * 동적 스테이트먼트 배포/해제가 가능합니다. ### DDS (`engine/dds/`) Kafka 기반 데이터 분배 서비스입니다. * 태그 포인트, 알람, 에셋 데이터를 Kafka 토픽으로 발행합니다. * 멀티 구독자를 지원합니다. * 도메인 변경 이벤트를 전파합니다. ### Monitoring (`engine/monitoring/`) 시스템 모니터링 프레임워크입니다. * 18개 모니터링 타이머 (OPC 상태, 에셋 헬스, 시스템 메트릭 등)가 동작합니다. * JMX MBean 등록 (150+ 속성)을 통해 모니터링 데이터를 노출합니다. * Codahale Metrics (70+ 메트릭)를 수집합니다. * WebSocket을 통한 실시간 푸시를 지원합니다. ### Production Engine (`engine/production/`) OEE/RAM/EMS 생산 분석 엔진입니다. * **EquipmentStateMachine**: 7단계 설비 상태(RUN/IDLE/STOP/FAULT/SETUP/PLANNED\_STOP/PLANNED\_START) 전이 검증 * **OrderStateMachine**: 5단계 워크 오더 상태(WAIT/START/PAUSED/END/ABORTED) 전이 검증 * **ProductionChangeEventBus**: 13종 생산 이벤트를 Kafka(3토픽) + Cassandra(3테이블)로 발행 * **디바운싱**: 100ms 디바운싱으로 OEE 재계산 최적화 (이벤트당 1회) * **에셋 잠금**: 에셋 단위 동시성 제어로 데이터 정합성 보장 ### Scheduling (`engine/scheduling/`) Quartz 기반 잡 스케줄링 시스템입니다. * 27개 잡 클래스, 34개 등록 잡이 포함되어 있습니다. * 10스레드 전용 스레드 풀에서 실행됩니다. * 도메인별 분류: OPC, Asset, Tag, Site, System, Edge, Plugin * **플러그인 잡**: OEECalculationJob(10스레드), RAMCalculationJob(5스레드), EMSCalculationJob(5스레드) ### Storage (`engine/storage/`) 멀티 데이터베이스 스토리지 드라이버입니다. * Cassandra/ScyllaDB: 시계열 데이터 (Select, Insert, Create DAO) * PostgreSQL: 메타데이터 (32+ DAO) * Redis: 쓰기 버퍼링 * TTL 기반 데이터 보관 정책을 적용합니다. ### Cache (`engine/cache/`) 멀티 레벨 인메모리 캐시입니다. * 8개의 특화된 캐시 매니저 (Site, Asset, Tag, Point, OPC, Alarm, MetaModel, Streaming)가 구성되어 있습니다. * 외부 캐시: Redis (일시 데이터) * 압축 캐시: GZIP 정적 리소스 캐싱 ## Service Layer (`plantpulse.core.service`) 서비스 레이어는 비즈니스 로직을 처리하는 계층입니다. 아래 표에서 각 서비스의 역할을 확인하실 수 있습니다. | 서비스 | 역할 | | ------------------------ | --------------------------------------------------- | | AlarmService | 알람 생성, 라우팅, 확인, 이메일/SMS 발송 | | AssetService | 설비 CRUD, 상태 추적, 헬스 스코어 | | DataService | 시계열 데이터 조회, 집계, 내보내기 | | DashboardService | 대시보드 설정, 그래프 관리 | | OPCService | OPC 서버 연결 관리, 모니터링 | | TagService | 태그(데이터 포인트) CRUD, 검증 | | UserService | 사용자 인증, 프로필 관리 | | SecurityService | 역할/권한 기반 접근 제어 | | OrderService | 생산 워크 오더 관리 (5단계 상태: WAIT/START/PAUSED/END/ABORTED) | | CalendarService | 생산 캘린더/시프트 관리 (SITE/ASSET 단위, 중복 검증) | | BaseDataService | 기준정보 마스터 데이터 관리 (13탭) | | ProductionChangeEventBus | 생산 이벤트 발행 (Kafka 3토픽 + Cassandra 3테이블) | | SiteService | 사이트(공장) 관리 | | ServerService | 서버 상태/메트릭 | | AdminService | 관리 유틸리티 (캐시 클리어, 메트릭 조회) | ## Data Access Layer (`plantpulse.core.dao`) 데이터 접근 계층에서는 PostgreSQL과 Cassandra에 대한 CRUD 연산을 처리합니다. ### PostgreSQL DAO (32+) | DAO | 테이블 | 역할 | | -------------- | --------------------- | ------------------------------------------ | | UserDAO | USER\_LOGIN | 사용자 인증/관리 | | SiteDAO | mm\_site | 사이트 CRUD | | AssetDAO | MM\_ASSET\_TREE | 에셋 계층 관리 | | TagDAO | mm\_tag | 태그 CRUD | | OPCDao | mm\_opc | OPC 서버 관리 | | AlarmConfigDAO | mm\_alarm\_config | 알람 설정 관리 | | PointDAO | mm\_point | 포인트 데이터 (TimescaleDB) | | OrderDAO | mm\_order | 워크 오더 관리 (abort\_code, abort\_notes 컬럼 포함) | | CalendarDAO | mm\_calendar | 캘린더 관리 (SITE/ASSET 타입 구분) | | BaseDataDAO | mm\_asset\_class 외 8개 | 기준정보 통합 관리 | | CustomerDAO | mm\_customer | 고객 정보 관리 | | ProductDAO | mm\_product | 제품 정보 관리 | | EmployeeDAO | mm\_employee | 직원 정보 관리 | | DefectCauseDAO | mm\_defect\_cause | 불량 원인 코드 (OEE 품질 연계) | | StopCauseDAO | mm\_stop\_cause | 정지 원인 코드 (OEE 가동률 연계) | | FaultCauseDAO | mm\_fault\_cause | 고장 원인 코드 (RAM 연계) | | CompanyDAO | MM\_COMPANY | 회사 정보 관리 | | SecurityDAO | - | 보안 정책 관리 | | TokenDAO | - | API 토큰 관리 | | DashboardDAO | mm\_dashboard | 대시보드 설정 | ### Cassandra DAO | DAO | 역할 | | ------------------ | --------------------- | | CassandraCreateDAO | 테이블/키스페이스 자동 생성 (DDL) | | CassandraSelectDAO | 시계열 데이터 조회 | | CassandraInsertDAO | 시계열 데이터 삽입 | | ScyllaDBSelectDAO | ScyllaDB 전용 조회 | | ScyllaDBInsertDAO | ScyllaDB 전용 삽입 | | ScyllaDBCreateDAO | ScyllaDB 전용 DDL | ## Presentation Layer (`plantpulse.server`) 사용자 요청을 처리하는 프레젠테이션 계층입니다. ### 컨트롤러 분류 (103개) | 분류 | 컨트롤러 수 | 주요 컨트롤러 | | ------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | REST API (V4) | 12 | V4\_SystemAPI, V4\_SiteAPI, V4\_TagAPI, V4\_AssetAPI, V4\_AlarmAPI, V4\_OPCAPI, V4\_OrderAPI, V4\_CalendarAPI, V4\_PathAPI, V4\_CustomerAPI, V4\_ProductAPI, V4\_EmployeeAPI | | REST API (V3) | 1 | APIController\_V3 | | 알람 | 3 | AlarmController, AlarmConfigController, AlarmAnalysisController | | 에셋/설비 | 3 | AssetController, AssetTreeController, EquipmentDashboardController | | 대시보드 | 3 | DashboardController, SiteDashboardController, AreaDashboardController | | 데이터 | 3 | DataController, GraphController, QueryController | | 시스템 | 3 | ServerStatusController, SystemController, EnvController | | 보안 | 3 | UserController, SecurityController, TokenController | | 생산 | 5 | OrderController, CalendarController, StatementController, BaseDataController, ProductionController | | 기타 | 72 | OPC, Modbus, PLC, SCADA, Map, Timeline, Monitoring 등 | ### HTTP 필터 (13개) | 필터 | 역할 | | -------------------- | ------------------------------ | | XSSFilter | XSS 공격 방어 (10개 패턴 + 유니코드 정규화) | | SecurityFilter | URL 패턴 기반 인증 (43개 규칙) | | SecurityHeaderFilter | 보안 헤더 (CSP, X-Frame-Options 등) | | APIFilter\_V3 | V3 API 토큰 인증 | | V4\_Filter | V4 API Bearer 토큰 인증 | | EncodingFilter | UTF-8 인코딩 | | MDCFilter | 로깅 컨텍스트 (요청별 추적) | | MobileFilter | 모바일 전용 라우팅 (/m/\*) | | ResourcesFilter | 정적 리소스 캐싱/압축 | ## 플러그인 분석 모듈 설비에 대한 고급 분석 기능을 제공하는 3개의 플러그인 패키지입니다. 상세 아키텍처는 [플러그인 아키텍처](/plantpulse-platform/developer/plugins.md) 페이지를 참조해 주세요. ### OEE (설비종합효율) 설비 종합 효율(Overall Equipment Effectiveness)을 실시간으로 계산합니다. * **계산식**: OEE = 가용률(Availability) × 성능(Performance) × 품질(Quality) * **표준**: ISO 22400-2:2014, SEMI E10 * **저장**: PostgreSQL (`mm_oee`) + Cassandra (`tm_asset_oee`, `tm_asset_oee_history`) * **이벤트 핸들러**: * OEEEquipmentStatusHandler: 설비 상태 변경 추적 * OEEOrderHandler: 워크 오더 타이밍 * OEECountHandler: 양품/불량 카운트 집계 ### RAM (신뢰성·가용성·정비성) 설비 고장 패턴을 분석하고 정비 지표를 산출합니다. * **표준**: ISO 14224 * **주요 지표**: MTBF, MTTR, 정비 가용도(MA), 고장률(λ), 신뢰도 R(t), 정비성 M(t) * **저장**: Cassandra (`tm_asset_ram`, `tm_asset_ram_history`, `tm_asset_ram_failure_event`) * **이벤트 핸들러**: RAMFailureHandler (FAILURE\_START/END 처리) * **API**: `GET /as-plugin/ram/{asset_id}?from_ts=...&to_ts=...` ### EMS (에너지 관리) 설비의 에너지 소비, 효율, 탄소 배출 지표를 산출합니다. * **표준**: ISO 50001 * **주요 지표**: 총 에너지 소비(kWh), 단위 에너지, 에너지 효율, CO2 배출량 * **저장**: Cassandra (`tm_asset_ems`, `tm_asset_ems_history`, `tm_asset_ems_power_event`) * **이벤트 핸들러**: EMSPowerUsageHandler (적산 전력 kWh 처리) * **API**: `GET /as-plugin/ems/{asset_id}?from_ts=...&to_ts=...` * **CO2 배출계수**: 0.4594 kg CO2/kWh (2023년 한국 전력 기준) ## 유틸리티 (`plantpulse.utils`) 25+ 유틸리티 패키지가 포함되어 있습니다. 주요 항목은 아래와 같습니다. | 패키지 | 용도 | | ----------- | -------------------- | | DateUtil | 날짜/시간 변환 | | JSONUtil | JSON 직렬화/역직렬화 | | HttpUtil | HTTP 클라이언트 | | CryptoUtil | 암호화/해싱 | | ExcelUtil | Excel 내보내기 (100만+ 행) | | CSVUtil | CSV 처리 | | NetworkUtil | 네트워크/IP 유틸리티 |