windpacer/ExperionCrawler

Fork 0

Files

windpacer 15c17522c8 MCP-서버 리팩토링 후 P&ID 추출 테스트전 다른 기능 확인 후 커밋

2026-05-04 10:35:13 +09:00

12 KiB

Raw Blame History

ExperionCrawler 프로젝트 분석 보고서 (Qwen 기반)

작성일: 2026-04-28
분석 도구: Qwen3-Coder-Next
프로젝트 경로: /home/windpacer/projects/ExperionCrawler

1. 개요

1.1 프로젝트 목표

Honeywell Experion OPC UA 서버를 위한 웹 기반 데이터 수집 및 시계열 분석 도구입니다.
OPC UA 프로토콜을 통해 실시간 데이터 수집, CSV 저장, TimescaleDB 이력 관리, 자연어 질의 처리까지 통합적으로 제공합니다.

1.2 기술 스택

계층	기술	용도
Backend	.NET 8 (C#)	웹 API, 백그라운드 서비스
Frontend	Vanilla JS + Bootstrap	UI 구현
Database	PostgreSQL + TimescaleDB	시계열 데이터 저장
OPC UA	opcua-sharp (Opc.Ua)	실시간/히스토리 데이터 수집
MCP	Python + Qwen3-Coder-Next	자연어 → SQL 변환 (LLM 기반)

2. 아키텍처

2.1 소스 구조 (Clean Architecture)

ExperionCrawler/
├── src/
│   ├── Core/                    # 핵심 비즈니스 로직 (Domain, Application)
│   │   ├── Domain/
│   │   │   └── Entities/        # 엔티티 정의 (ExperionTag, ExperionRecord, RealtimePoint...)
│   │   └── Application/
│   │       ├── DTOs/            # 데이터 전송 객체
│   │       ├── Interfaces/      # 서비스 인터페이스 (DI 대상)
│   │       └── Services/        # 구현체 (TextToSqlService, KoreanTimeRangeExtractor...)
│   │
│   ├── Infrastructure/          # 기술적 구현 (OPC UA, DB, Mcp)
│   │   ├── Certificates/        # X.509 인증서 관리 (pki/ 디렉토리)
│   │   ├── Database/            # EF Core + TimescaleDB
│   │   ├── Csv/                 # CSV 읽기/쓰기 (CsvHelper)
│   │   ├── OpcUa/               # OPC UA 클라이언트/서버 구현
│   │   └── Mcp/                 # MCP 클라이언트 (Python 통신)
│   │
│   └── Web/                     # ASP.NET Core 웹 프로젝트
│       ├── Controllers/         # API 컨트롤러
│       ├── Program.cs           # DI, 미들웨어 구성
│       └── wwwroot/             # 정적 파일 (index.html, js/app.js, css/)

2.2 DI 컨테이너 등록 (`Program.cs`)

Service	Lifetime	구현체
`IExperionCertificateService`	Singleton	`ExperionCertificateService`
`IExperionStatusCodeService`	Singleton	`ExperionStatusCodeService`
`IOpcUaConfigProvider`	Singleton	`OpcUaConfigProvider`
`IExperionOpcClient`	Scoped	`ExperionOpcClient`
`IExperionCsvService`	Scoped	`ExperionCsvService`
`IExperionDbService`	Scoped	`ExperionDbService`
`ITextToSqlService`	Scoped	`TextToSqlService`
`IMcpService`	Singleton	`McpService`
`ExperionRealtimeService`	Singleton	실시간 구독 (BackgroundService)
`ExperionHistoryService`	Singleton	히스토리 구독 (BackgroundService)
`ExperionOpcServerService`	Singleton	OPC UA 서버 (BackgroundService)

3. 핵심 기능

3.1 인증서 관리

기능	설명
생성	`POST /api/certificate/create` → X.509 클라이언트 인증서 생성
상태 확인	`GET /api/certificate/status?clientHostName=dbsvr`
PKI 구조	`pki/{own,trusted,issuers,rejected}/certs/`

3.2 OPC UA 클라이언트

기능	설명
서버 접속	`POST /api/connection/test` → 단일 태그 읽기, 노드 탐색
실시간 구독	`ExperionRealtimeService` → Subscription 기반 콜백
히스토리 수집	`ExperionHistoryService` → 주기적 Snapshot
CSV 저장	`ExperionCsvService` → `data/csv/` 디렉토리
DB 임포트	`ExperionDbService` → `history_table` / `realtime_table`

3.3 Text-to-SQL (자연어 → SQL)

기능	설명
자연어 파싱	`POST /api/text-to-sql/parse` → `TextToSqlService.ParseNaturalLanguageAsync()`
MCP 통합	`POST /api/text-to-sql/query-nl` → LLM → SQL → 실행
도구 목록	`GET /api/text-to-sql/tools`
시계열 분석	`POST /api/text-to-sql/analyze` → avg/max/min/추세 계산
간격 쿼리	`POST /api/text-to-sql/query-history-interval`

시간 키워드 예시:

"최근 1시간", "최근 24시간", "최근 7일", "최근 1개월"
"오늘", "어제", "오늘부터 ~ 까지", "어제부터 ~ 까지"
"오전 9시부터 오후 5시까지"

3.4 MCP (Model Context Protocol)

기능	설명
Ping	`GET /api/mcp/ping` → Python 서버 연결 확인
SQL 실행	`POST /api/mcp/run-sql` → TimescaleDB 쿼리
PV 히스토리	`POST /api/mcp/query-pv-history` → 태그명 + 시간 범위
태그 메타데이터	`POST /api/mcp/get-tag-metadata`
도면 목록	`GET /api/mcp/list-drawings?unitNo=...`
자연어 질의	`POST /api/mcp/query-with-nl`

3.5 OPC UA 서버

기능	설명
시작	`POST /api/opcserver/start` → 자동 시작 플래그 저장
중지	`POST /api/opcserver/stop` → 플래그 삭제
NodeManager	`ExperionOpcServerNodeManager` → 커스텀 노드 매니저

4. 데이터베이스 스키마

4.1 테이블 정의

테이블명	용도	주요 컬럼
`raw_node_map`	노드맵 원시 데이터	`id, level, class, name, node_id, data_type`
`node_map_master`	마스터 노드맵	`id, level, class, name, node_id, data_type`
`realtime_table`	실시간 포인트	`id, tagname, node_id, livevalue, timestamp`
`history_table`	시계열 이력	`id, tagname, node_id, value, recorded_at`

** TimescaleDB 확장 활성화: CREATE EXTENSION IF NOT EXISTS timescaledb **

5. API 엔드포인트

5.1 인증서

메서드	엔드포인트	기능
GET	`/api/certificate/status?clientHostName={name}`	인증서 존재 여부 확인
POST	`/api/certificate/create`	X.509 클라이언트 인증서 생성

5.2 연결

메서드	엔드포인트	기능
POST	`/api/connection/test`	서버 접속 테스트, 단일 태그 읽기
POST	`/api/connection/read`	nodeId 기반 읽기
POST	`/api/connection/browse`	노드 탐색

5.3 크롤링

메서드	엔드포인트	기능
POST	`/api/crawl/start`	복수 노드 주기 수집 시작
POST	`/api/crawl/stop`	수집 중지
POST	`/api/crawl/export`	CSV 다운로드

5.4 DB

메서드	엔드포인트	기능
GET	`/api/db/records?limit={n}&offset={m}`	레코드 조회
POST	`/api/db/import`	CSV 임포트
POST	`/api/db/export`	CSV 다운로드

5.5 Text-to-SQL

메서드	엔드포인트	기능
POST	`/api/text-to-sql/parse`	자연어 → SQL 변환
POST	`/api/text-to-sql/execute`	SQL 실행
POST	`/api/text-to-sql/suggest`	쿼리 제안
POST	`/api/text-to-sql/analyze`	시계열 분석
POST	`/api/text-to-sql/query-history-interval`	사용자 지정 간격 조회
POST	`/api/text-to-sql/query-nl`	MCP 통합 자연어 질의
GET	`/api/text-to-sql/tools`	MCP 도구 목록

5.6 OPC UA 서버

메서드	엔드포인트	기능
POST	`/api/opcserver/start`	서버 시작
POST	`/api/opcserver/stop`	서버 중지
GET	`/api/opcserver/status`	서버 상태

6. 주요 서비스 클래스

6.1 TextToSqlService

기능	메서드
자연어 파싱	`ParseNaturalLanguageAsync(string input)`
SQL 생성	`BuildSqlFromNaturalLanguage(string input, out List<string> tagNames)`
태그 매핑	`GetMappingNodesAsync(List<string> tagNames)`
시계열 분석	`AnalyzeAsync(string sql)`
시간 범위 추출	`KoreanTimeRangeExtractor` 협업

6.2 ExperionOpcClient

기능	메서드
단일 읽기	`ReadAsync(string nodeId)`
복수 읽기	`ReadAsync(List<string> nodeIds)`
노드 탐색	`BrowseAsync(string nodeId)`
연결 테스트	`TestConnectionAsync(ExperionServerConfig cfg)`

6.3 ExperionRealtimeService

기능	메서드
시작	`StartAsync(ExperionServerConfig cfg)`
중지	`StopAsync()`
등록	`SubscribeAsync(List<string> nodeIds)`
해제	`UnsubscribeAsync(List<string> nodeIds)`

7. 설정 파일

7.1 appsettings.json

{
  "ConnectionStrings": {
    "DefaultConnection": "Host=localhost;Port=5432;Database=iiot_platform;Username=postgres;Password=postgres",
    "ExperionDbConnection": "Host=localhost;Port=5432;Database=postgres;Username=postgres;Password=postgres;Trust Server Certificate=true"
  },
  "OpcUaServer": {
    "Port": 4841,
    "EnableSecurity": false,
    "AllowAnonymous": true,
    "AllowedUsernames": ["mngr"],
    "AllowedPasswords": ["mngr"]
  }
}

7.2 자동 시작 플래그

파일	용도
`realtime_autostart.json`	실시간 구독 자동 시작
`opcserver_autostart.json`	OPC UA 서버 자동 시작

8. 개발/배포

8.1 로컬 실행

cd src/Web
dotnet run
# → http://localhost:5000

8.2 Ubuntu 배포

git clone <repo> ExperionCrawler
cd ExperionCrawler
sudo bash deploy.sh

8.3 systemctl 관리

sudo systemctl status experioncrawler
sudo systemctl restart experioncrawler
sudo systemctl stop experioncrawler
sudo journalctl -u experioncrawler -f  # 실시간 로그

9. 테스팅

9.1 단위 테스트 프로젝트

테스트 클래스	주요 테스트 항목
`TextToSqlServiceTests.cs`	SQL 생성, 태그 매핑, 시간 범위 추출
`SqlValidatorTests.cs`	SQL 인젝션 방지, 테이블 제한
`KoreanTimeRangeExtractorTests.cs`	한국어 시간 표현 파싱

9.2 테스트 명령어

dotnet test ExperionCrawler.Tests/

10. 주의사항

10.1 JSON 직렬화 정책

Program.cs에서 PascalCase 유지 설정:

opt.JsonSerializerOptions.PropertyNamingPolicy = null;  // camelCase로 변환하지 않음

프론트엔드 대응: app.js의 모든 API 응답은 소문자 키로 접근 (res.id, res.tagName).

10.2 인증서 경로

pki/own/certs/{clientHostName}.pfx         # 클라이언트 인증서
pki/trusted/certs/                         # 신뢰 피어
pki/issuers/certs/                         # 신뢰 발급자 (필수)
pki/rejected/certs/                        # 거부 인증서

10.3 TimescaleDB

history_table은 TimescaleDB의 Hypercube로 자동 관리됨
recorded_at 컬럼은 TIMESTAMPTZ 타입

11. 다음 개선 방향

항목	설명
realtime_table indexing	`node_id` 유니크 인덱스만 있고 `tagname` 인덱스 추가 필요
CSV import 성능	AssetLoader의 binary COPY 대신 EF Core Bulk Insert 고려
MCP error handling	Python 서버 장애 시 fallback 처리 강화
UI/UX	Bootstrap 5 업그레이드, 모바일 반응형 개선
OPC UA Security	현재 `AutoAcceptUntrustedCertificates=true` → 프로덕션 시 변경 필요

12. 관련 문서

문서	경로	설명
CLAUDE.md	`CLAUDE.md`	Claude 작업 규칙
.roo.md	`.roo.md`	Roo 작업 규칙
task_state.md	`task_state.md`	Text-to-SQL 개발 로그
issues.md	`issues.md`	이슈 추적
REVIEW_REQUEST.md	`REVIEW_REQUEST.md`	코드 리뷰 요청

분석 완료일: 2026-04-28 23:11 (KST)
분석 도구: Qwen3-Coder-Next
프로젝트 상태: ✅ 활발한 개발 중 (Text-to-SQL + MCP 통합 완료)

12 KiB Raw Blame History