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