ExperionCrawler/AGENTS.md

ExperionCrawler — Agent Instructions

Build / Run / Test

Action	Command	Working Dir
Build	dotnet build src/Web/ExperionCrawler.csproj	repo root
Run (dev)	dotnet run	src/Web/
Publish	dotnet publish -c Release -o /opt/ExperionCrawler	src/Web/
Tests	dotnet test	repo root

Single project: src/Web/ExperionCrawler.csproj. Core and Infrastructure are included via <Compile Include> globs — there are no separate projects to build. Runtime target is linux-arm64.

Architecture

src/
├── Core/            — Interfaces (IExperionServices.cs), Domain entities, DTOs, Application Services
├── Infrastructure/  — OpcUa/, Database/, Certificates/, Csv/, Mcp/
└── Web/             — Program.cs, Controllers/, wwwroot/ (SPA)

All controllers are in src/Web/Controllers/ExperionControllers.cs (single file). All interfaces are in src/Core/Application/Interfaces/IExperionServices.cs (single file).

Database

PostgreSQL (NOT SQLite — README is stale). Connection strings in src/Web/appsettings.json. TimescaleDB extension may be enabled on history_table via DDL only; no app code changes needed.

⚠️ Critical — duration_seconds semantics

event_history_table.duration_seconds = 직전 상태의 지속 시간(초). 현재 이벤트의 지속 시간이 아니다.

• DigitalEventDetectorService가 이전 상태를 처음 관측한 시점부터 값이 바뀔 때까지의 경과 시간(wall-clock)을 기록
• 예: prev=R-RUN, curr=R-TRIP, duration_seconds=1423 → R-RUN 상태가 1423초간 유지되다가 R-TRIP으로 전환된 것. TRIP이 1423초간 지속된 게 아님
• MCP 툴(query_events, active_alarms) JSON 출력 시 prev_state_duration_s 필드명으로 변환하여 반환하므로 LLM이 필드명만 보고 의미를 알 수 있음
• LLM 프롬프트에 이벤트 데이터를 넘길 때는 (직전상태유지={duration}s) 형식으로 전달

⏰ Timezone — KST

DB는 UTC 저장, LLM에는 KST(UTC+9) 변환해서 전달.

• server.py의 _kst_str() 함수로 UTC ISO 문자열 → KST ISO 문자열 변환
• 모든 시스템 프롬프트에 "모든 시각은 KST"라고 명시
• MCP 서버 재기동 필요 시 uv run server.py --http

Critical Convention — JSON camelCase

PropertyNamingPolicy = null in Program.cs means C# PascalCase becomes JSON keys. Frontend expects camelCase. Every controller Ok(...) response MUST use explicit anonymous objects with camelCase keys:

// ✅ Correct
return Ok(new { id = x.Id, tagName = x.TagName });

// ❌ Broken — JS gets undefined
return Ok(new { x.Id, x.TagName });
return Ok(myDto);  // typed object

See CODING_CONVENTIONS.md for full details and checklist.

Background Services (HostedServices in Program.cs)

• ExperionRealtimeService — OPC UA subscription, 500ms batch flush to DB
• ExperionHistoryService — periodic snapshot (60s) from realtime_table → history_table
• ExperionOpcServerService — exposes realtime data as OPC UA server (port 4841)
• McpServerHostedService — Python MCP server bridge
• ExperionFastService — high-frequency data capture sessions
• ExperionFastCleanupService — expired session cleanup

All registered as Singleton + HostedService. RealtimeService and OpcServerService share autostart flag files (realtime_autostart.json, opcserver_autostart.json) in the working directory.

Frontend

Vanilla JS SPA. wwwroot/index.html + js/app.js + css/style.css. No build step. Tab-based navigation; tabs do NOT auto-fire API calls on entry (performance fix).

OPC UA SDK Gotchas

• SDK v1.5.378.134 — Session.Create() is [Obsolete]; use DefaultSessionFactory.CreateAsync()
• Subscription.Create() / Delete() / ApplyChanges() also deprecated → async variants preferred
• Certificate validation must be attached AFTER OpcUaConfigProvider.GetConfigAsync() returns the config
• TCP connect timeout: wrap SelectEndpointAsync with a 10s CancellationTokenSource (OS default is 127s)

Deploy

sudo bash deploy.sh — publishes to /opt/ExperionCrawler, creates systemd service experioncrawler, sets up PKI dirs. Service runs as www-data.