Files

windpacer 302183c97e feat: P&ID 연결 분석, LLM 에이전트 모드, KB 확장, MCP 서버 리팩토링

- P&ID: 연결 분석 API, Prefix 규칙 관리, 카테고리 분류, DXF 그래프 빌드
- LLM: 대화 요약, tool card 영구 보존, 시계열 차트(uPlot), 에이전트 모드
- KB: 청크 미리보기, Field Instrument Inference, 인증/Qdrant 클라이언트
- MCP: 서버 기능 확장, 파이프라인 수정, timeout 개선
- Frontend: P&ID UI, LLM UI, KB UI, OPC UA Write 탭 추가
- 설정: AGENTS.md, plant_context, README, opencode.json 업데이트
- 정리: 진단 체크리스트 문서 삭제

2026-05-21 23:36:57 +09:00

4.3 KiB

Raw Blame History

PROJECT_CONTEXT.md

🎯 Project Overview

ExperionCrawler는 신암정유 전공장의 제어 시스템인 Honeywell Experion HS R530으로부터 실시간 데이터를 수집, 저장, 분석하여 지능형 운영 환경을 제공하는 시스템입니다. OPC UA를 통해 데이터를 획득하며, RAG(Retrieval-Augmented Generation)와 MCP(Model Context Protocol)를 결합하여 LLM이 공정 데이터를 이해하고 운영 가이드를 제공할 수 있도록 설계되었습니다.

🏗️ System Architecture

프로젝트는 Clean Architecture 패턴을 따르며, src/ 디렉토리 내의 세 계층으로 구성됩니다. (Core와 Infrastructure는 Web 프로젝트에 포함되어 빌드됩니다.)

1. Core Layer (`src/Core/`)

Domain/Entities: 데이터베이스 엔티티 및 도메인 모델.
Application/Interfaces: 모든 서비스의 계약(IExperionServices.cs).
Application/Services: 비즈니스 로직 구현 (예: TextToSqlService, PidGraphService).
Application/DTOs: API 및 서비스 간 데이터 전송 객체.

2. Infrastructure Layer (`src/Infrastructure/`)

OpcUa/: OPC UA 클라이언트/서버 로직 및 실시간 데이터 처리.
Database/: Entity Framework Core 및 PostgreSQL/TimescaleDB 연동.
Mcp/: Python 기반 MCP 서버와의 통신을 위한 브릿지 (JSON-RPC over HTTP).
Kb/: Qdrant 기반 지식 베이스(Knowledge Base) 관리.

3. Web Layer (`src/Web/`)

Program.cs: 의존성 주입(DI) 및 백그라운드 서비스(HostedServices) 오케스트레이션.
Controllers/: 단일 파일(ExperionControllers.cs)로 구성된 API 엔드포인트.
wwwroot/: 빌드 단계가 없는 Vanilla JS SPA.

⚙️ Critical Operational Semantics

⏰ Timezone & Time Handling

Storage: 모든 데이터베이스 타임스탬프는 UTC로 저장됩니다.
Presentation: LLM 및 사용자에게 전달될 때는 반드시 **KST (UTC+9)**로 변환되어야 합니다.

⏳ Event Duration Semantics

event_history_table.duration_seconds: 이 필드는 **"직전 상태가 유지된 시간(초)"**을 의미합니다. 현재 이벤트의 지속 시간이 아님에 주의하십시오.

🔡 JSON Naming Convention (CRITICAL)

Backend: PropertyNamingPolicy = null 설정으로 인해 C#의 PascalCase가 JSON 키로 그대로 전달됩니다.
Frontend: 프론트엔드는 camelCase를 기대합니다.
Rule: 모든 Controller의 Ok(...) 응답 시, 반드시 익명 객체를 사용하여 명시적으로 camelCase 키를 지정해야 합니다.
- ✅ return Ok(new { id = x.Id, tagName = x.TagName });
- ❌ return Ok(new { x.Id, x.TagName });

🔄 Background Services (HostedServices)

Service	Responsibility
`ExperionRealtimeService`	OPC UA 구독 및 500ms 단위 데이터 DB 플러시
`ExperionHistoryService`	60초 주기 `realtime_table` → `history_table` 스냅샷
`ExperionOpcServerService`	로컬 데이터를 OPC UA 서버(Port 4841)로 노출
`McpServerHostedService`	Python MCP 서버 프로세스 생명주기 관리
`ExperionFastService`	고주파 데이터 캡처 세션 관리
`ExperionFastCleanupService`	만료된 Fast 세션 정리

🛠️ Development & Deployment

Build & Test

Build: dotnet build src/Web/ExperionCrawler.csproj
Run (Dev): dotnet run (Working Dir: src/Web/)
Test: dotnet test
Lint/Typecheck: (사용자 제공 시 실행 필수)

Deployment

Command: sudo bash deploy.sh
Target: /opt/ExperionCrawler
Service: systemd 서비스 experioncrawler로 실행 (User: www-data)

🤖 Agent Operational Guidelines

Verification: 코드 수정 후에는 반드시 프로젝트의 Lint 및 Typecheck 명령어를 실행하여 무결성을 검증하십시오.
Search First: 새로운 기능을 구현하거나 버그를 수정하기 전, 반드시 Grep과 Glob을 사용하여 기존 패턴과 컨벤션을 확인하십시오.
Data Integrity: DB 쿼리 시 duration_seconds의 의미와 시간대 변환 규칙을 항상 염두에 두십시오.
Commit Policy: 사용자의 명시적 요청이 없는 한 절대 git commit을 수행하지 마십시오.

4.3 KiB Raw Blame History