windpacer/ExperionCrawler
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: CLAUDE.md 정리 — 변경 이력 압축 (963→81줄)

Browse Source 
git 히스토리에 이미 있는 Phase 0~6 changelog, OPC UA 서버,
버그 수정 이력, 성능 분석, 구현 계획(Task 1~4) 전부 삭제.
작업 규칙 + 최신 1건(Phase 7)만 유지해 세션 컨텍스트 로드량 축소.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
windpacer
2026-05-16 07:13:39 +09:00
parent d09ef95869
commit 0ccec38c18
1 changed files with 55 additions and 862 deletions
Download Patch File Download Diff File Expand all files Collapse all files

917
CLAUDE.md
View File

@@ -7,882 +7,75 @@
## 완료된 작업
### 기능 추가 — 로컬 LLM 채팅 + 지식 베이스(RAG) Phase 0~5 (2026-05-13)
### Phase 7 + Phase 5 후순위 일괄 구현 (2026-05-14)
#### 배경
운전원이 채팅 UI에서 자연어로 공장 상황·계기 상태·정비 이력 등을 질문하면, (a) PostgreSQL 시계열/이벤트 데이터와 (b) 관리자가 업로드한 KB 문서(Qdrant 벡터 검색)를 합성해 답하도록 통합. 별도 14번 탭 "RAG 관리"에서 관리자 비번 인증 후 문서 업로드/인덱싱/관리.
`plans/빅피클-잔여작업-코딩계획.md`의 1~6번 항목을 일괄 구현. Phase 7 옵션 4종 + Phase 5
후순위 2종으로 채팅 UX·관리 편의·운영자 분석 능력을 강화.
설계서: `plans/LLM채팅+지식증강플랜.md`
#### 구현 내역
#### 아키텍처
```
[채팅 #13] ── /api/ollama/vllm/chat/stream ──► [OllamaController]
│ SSE: message, tool_start, tool_result
│ tool_calls 루프(최대 10라운드)
▼
[McpClient → Python MCP]
│
┌───────────────────────────────┴───────────┐
▼ ▼
PostgreSQL Qdrant 컬렉션 7개
(history/realtime/event/ ├── ws-65f457145aee80b2 (코드)
tag_metadata/kb_*) ├── experion-opc-docs (R530)
└── kb_* 5개 (사용자 KB)
[RAG 관리 #14] ── /api/kb/{auth,upload,documents,jobs,download,...} ──►
[KbAuthController + KbController + KbIngestWorker(BackgroundService)]
│ Argon2id 비번 + 60분 세션 토큰
│ 업로드 → storage/kb/{yyyy-MM}/{uuid}.ext (SHA256)
│ 큐 폴링 2초 → parse(MCP) → embed(Ollama 768-dim) → upsert(Qdrant)
│ attempts ≥3 = failed
```
#### KB 데이터 모델 (PostgreSQL, 자동 마이그레이션)
- `kb_collections` (5종 시드: system_instrument / plant_operation / procedure / report / vendor_doc)
- `kb_documents` (UUID PK + collection_key FK + status: pending/parsing/embedding/indexed/failed/disabled)
- `kb_ingest_jobs` (stage: parse, attempts, finished_at)
- `kb_admin_credential` (단일 행, Argon2id 해시)
- `kb_admin_sessions` (60분 만료)
#### Phase별 구현
**Phase 0 — 사전 정비**
| 파일 | 수정 내용 |
|------|----------|
| `mcp-server/worker/nl2sql_worker.py` | `time_bucket('1 min', ts)` → history_table.recorded_at 직접 SELECT, `_get_tag_metadata`도 server.py 형식과 일치 |
| `mcp-server/llm-model.json` | 실제 서빙 모델(`Qwen3.6-27B-FP8`)과 이미 동기화 — 변경 없음 |
| `prompts/plant_context.md` | 신규 (빈 골격) — 단위/계기 약어/태그 규칙/예시 자유 작성 영역 |
| `src/Web/Controllers/OllamaController.cs` | `ComposeSystemPrompt(userPrompt, toolsEnabled)` 추가 — `BaseSystemPromptKo` + plant_context.md + `ToolGuideKo` + 사용자 입력 순서로 합성 |
| `src/Web/wwwroot/js/app.js` | 영문 하드코딩된 tool description 제거 (서버에서 합성) |
| `src/Web/appsettings.json` | `PromptsDirectory: "../../prompts"` 추가 |
**Phase 1 — 데이터 모델 & 인증**
| 파일 | 수정 내용 |
|------|----------|
| `src/Core/Domain/Entities/ExperionEntities.cs` | `KbCollection / KbDocument / KbIngestJob / KbAdminCredential / KbAdminSession` 5개 엔티티 추가 |
| `src/Infrastructure/Database/ExperionDbContext.cs` | DbSet 5개 + OnModelCreating 인덱스 + InitializeAsync에 DDL/시드 (pgcrypto 활성화 포함) |
| `src/Infrastructure/Kb/KbQdrantClient.cs` | 신규 — `EnsureCollectionAsync`, `DeleteByDocAsync`, `UpsertAsync` |
| `src/Infrastructure/Kb/KbStartupService.cs` | 신규 IHostedService — 부팅 시 활성 컬렉션 5개 Qdrant ensure |
| `src/Infrastructure/Kb/PasswordHasher.cs` | 신규 — Argon2id (4 thread, 64MB, 3 iter) + `NewSessionToken` |
| `src/Infrastructure/Kb/KbAuthService.cs` | 신규 — `EnsureCredentialAsync` (env or 자동생성), Login/Validate/Logout/ChangePassword |
| `src/Web/Controllers/KbAuthController.cs` | 신규 — `/api/kb/auth/{login\|logout\|status\|change-password}`, `X-Kb-Token` 헤더 |
| `src/Web/ExperionCrawler.csproj` | `Konscious.Security.Cryptography.Argon2 v1.3.1` 추가 |
| `src/Web/Program.cs` | KB 서비스 등록 + 부팅 시 `EnsureCredentialAsync` 호출 |
**Phase 2 — 업로드 & 비동기 워커**
| 파일 | 수정 내용 |
|------|----------|
| `src/Infrastructure/Kb/KbStorageService.cs` | 신규 — `storage/kb/{yyyy-MM}/{uuid}.{ext}`, SHA256 스트림 계산 |
| `src/Infrastructure/Kb/KbEmbeddingClient.cs` | 신규 — Ollama nomic-embed-text(`/api/embeddings`) 768-dim |
| `src/Infrastructure/Kb/KbIngestWorker.cs` | 신규 BackgroundService — 2초 폴링, parse→embed→index 단일 패스, attempts ≥3=failed |
| `src/Web/Controllers/KbController.cs` | 신규 — upload(multipart, RequestSizeLimit 500MB), documents 페이지네이션, jobs 조회, download(Content-Disposition), delete(Qdrant+storage 동시정리), reindex, disable, bulk-disable, purge-disabled |
| `mcp-server/parsers/` | 신규 디렉터리 — `xlsx_parser`(시트+행), `pdf_parser`(페이지+표), `docx_parser`(헤딩 path), `text_parser`(md/txt) |
| `mcp-server/server.py` | `@mcp.tool() parse_document(doc_id, title, file_path, mime_type, collection_key, chunking_policy)` 추가 |
| `mcp-server/pyproject.toml` | `openpyxl / python-docx / pdfplumber` 의존성 추가 |
**Phase 3 — 관리 탭 #14**
| 파일 | 수정 내용 |
|------|----------|
| `src/Web/wwwroot/index.html` | 사이드바 14번 탭 + `pane-kbadmin` 섹션 (로그인 카드, 필터, 문서 테이블, 업로드/비번변경 모달) |
| `src/Web/wwwroot/js/app.js` | `kbLogin / kbLogout / kbLoadCollections / kbRefresh / kbRenderDocs / kbUpload* / kbDelete / kbReindex / kbDisable / kbBulkDisable / kbPurgeDisabled / kbChangePw*` + 1.5초 진행률 폴링 + sessionStorage 토큰 |
| `src/Web/wwwroot/css/style.css` | `.kb-login-card / .kb-main / .kb-doc-tbl / .kb-status (pending/parsing/embedding/indexed/failed/disabled 색상) / .kb-modal` |
**Phase 4 — 다운로드 & 검색**
| 파일 | 수정 내용 |
|------|----------|
| `mcp-server/server.py` | `KB_COLLECTIONS` 상수, `_search_kb_collection` (Qdrant 단일 + tags filter), `_recency_factor` (7d+10% / 30d+5% / 90d+2%), `_search_kb_raw` (다중 컬렉션 검색→가중치→since 후필터→dedup→top_k), `@mcp.tool() search_kb`, `rag_query` 확장 (`search_kb`, `kb_collections` 인자) |
**Phase 5 — 채팅 통합**
| 파일 | 수정 내용 |
|------|----------|
| `src/Web/Controllers/OllamaController.cs` | `EmitToolStart(id, name, argsJson)` / `EmitToolResult(id, name, ok, payload)` 헬퍼. `VllmChatStreamWithTools`의 공식 tool_calls 경로 + JSON-텍스트 폴백 경로 모두 SSE 이벤트 발행 |
| `src/Web/wwwroot/js/app.js` | SSE 파서 버그 수정 (`event:` 라인 추적), `llmAppendToolCard / llmUpdateToolCard / llmRenderToolPayload / llmRenderTable / llmRenderKbHits` 추가, `llmKbDocMap` + `llmLinkKbCitations` (제목→다운로드 링크 치환), `LLM_STARTER_CHIPS` 7종 + `llmUseChip` |
| `src/Web/wwwroot/css/style.css` | `.llm-tool-cards / .llm-tool-card (spin 애니, ok/err 색상) / .llm-tool-tbl (sticky header) / .llm-kb-hits / .kb-cite-link / .llm-chip` |
#### 주요 설계 결정
| 항목 | 결정 |
|------|------|
| 관리자 권한 | 비번 인증 (Argon2id), 세션 토큰 60분, `X-Kb-Token` 헤더 |
| 초기 비번 | 환경변수 `KB_ADMIN_INITIAL_PASSWORD` 우선, 없으면 부팅 시 콘솔에 16자 랜덤 출력 |
| 컬렉션 구조 | doc_type별 5개 분리 컬렉션 (마스터 시드) + 자유 태그 |
| 임베딩 모델 | 기존 `nomic-embed-text` (768-dim) — Phase 0~5는 그대로, BGE-M3 마이그레이션은 보류 |
| 청킹 정책 | xlsx 시트+행 둘 다, pdf 페이지+표 별도, docx 헤딩 path, md/txt 단순 |
| 재인덱스/삭제 | Qdrant(`doc_id` filter)와 storage 파일 동시 정리 |
| Worker 큐 처리 | parse→embed→index 단일 패스(한 잡으로 끝까지), attempts ≥3 = failed, 2초 폴링 |
| 시스템 프롬프트 | 서버에서 합성 (한글 base + plant_context.md + tool guide + 사용자 입력) |
| SSE 이벤트 | `message` / `tool_start` / `tool_result` / `done` / `error` — 클라이언트 파서가 event-type 추적 |
| KB 인용 | search_kb 결과 title↔doc_id 매핑 누적, 본문에 등장 시 다운로드 링크로 자동 치환 |
| 자동 표 렌더 | `{success, columns, data}` 또는 `data:[{...}]` 형태 감지 시 최대 50행 HTML 테이블 |
#### API 엔드포인트 (신규)
- `POST /api/kb/auth/login` / `logout` / `change-password`, `GET /api/kb/auth/status`
- `GET /api/kb/collections` — 활성 컬렉션 + 문서/청크 카운트
- `POST /api/kb/upload` (multipart, admin) — 즉시 doc_id 반환, 큐 적재
- `GET /api/kb/documents?collection=&status=&q=&page=&pageSize=`
- `GET /api/kb/documents/{id}` / `DELETE /api/kb/documents/{id}` (admin)
- `POST /api/kb/documents/{id}/reindex` / `/disable` (admin)
- `POST /api/kb/documents/bulk-disable` / `/purge-disabled` (admin)
- `GET /api/kb/jobs?docId=&stage=&pendingOnly=`
- `GET /api/kb/download/{docId}` — Content-Disposition 원본 스트림 (인증 X)
#### MCP 도구 (신규)
- `parse_document(doc_id, title, file_path, mime_type, collection_key, chunking_policy)` — KbIngestWorker 전용
- `search_kb(query, collection_keys?, top_k=8, tags?, since?, boost_recent=True)` — 채팅 노출
- `rag_query` 확장 — `search_kb=False`, `kb_collections=None` 옵션
#### 빌드 결과
- `dotnet build` — 경고 0건, 에러 0건
- `mcp-server` Python 6개 파일 (server.py, nl2sql_worker.py, parsers/*) syntax OK
#### 런타임 셋업 (코드 외)
- `cd mcp-server && uv pip install -e .` — Phase 2에서 추가된 `openpyxl/python-docx/pdfplumber` 설치
- `mcp-server` 재시작 — `parse_document`, `search_kb` 새 도구 인식
- 앱 첫 기동 후 콘솔의 `[Kb] 관리자 초기 비밀번호 자동 생성: XXXX` 로그 → 14번 탭에서 즉시 변경
- Qdrant 5개 컬렉션 생성 확인 — `curl http://localhost:6333/collections`
#### 잔여 작업
- ~~Phase 6 (보강 도구)~~ → 완료 (2026-05-14 두 섹션 아래 참조)
- Phase 7 (옵션): NL2SQL 의도 라우터, 대화 요약, 에이전트 모드, KB 청크 미리보기 UI
- Phase 5 후순위: 시계열 미니 스파클라인, 툴 카드 메시지 영구 보존
- 결정 보류: 현장 재고 데이터 출처, 임베딩 모델 BGE-M3 마이그레이션
---
### Phase 5 후속 — 진단 보고서 핫픽스 + Phase 6 첫 항목 (2026-05-14)
#### 배경
`plans/LLM채팅+지식증강-phase5-사용자체크리스트.md` 진단 보고서에서 도출된 6건의 코드 이슈와 Phase 6 잔여 항목 중 우선순위가 가장 높은 `run_sql` 안전 가드를 함께 처리.
| # | 항목 | 핵심 |
|---|------|------|
| 1 | 툴 카드 영구 보존 | `sess.messages[*].toolCalls[]` 저장 → `llmRenderMessages`에서 재렌더링. F5 새로고침 후에도 툴 카드 유지 |
| 2 | KB 청크 미리보기 UI | Qdrant Scroll API → `/api/kb/documents/{id}/chunks` → 모달에 청크 카드 (접기/펼침) |
| 3 | 시계열 미니 스파클라인 | `llmDetectTimeSeries` (timestamp+value 키 자동 감지) → uPlot 90px 차트가 표 위에 자동 렌더링 |
| 4 | NL2SQL 의도 라우터 | `_classify_intent` 정규식 6규칙 → `query_with_nl` 진입 시 알람/요약/태그검색/이벤트로 위임. `classify_intent` MCP 도구로도 노출 |
| 5 | 대화 요약 | `sess.summary` + `summarizedUpTo` 인덱스, `LLM_MAX_HISTORY=20` 초과 시 `/api/ollama/summarize` 호출 → systemPrompt에 누적 요약 prepend |
| 6 | 에이전트 모드 | `#llm-agent-mode` 토글 → `AgentMode` 요청 필드 → `ComposeSystemPrompt`에 `AgentModeGuideKo` (ReAct 사이클) 주입 |
#### 수정 파일
| 파일 | 수정 내용 |
| 파일 | 변경 요약 |
|------|----------|
| `mcp-server/worker/nl2sql_worker.py` | (HIGH) `_list_drawings` `dict(zip(columns, row[0]))` → `[row[0] for row in rows]` 버그 수정 — 문자열이 문자 단위로 분리되어 잘못된 dict 생성되던 문제 |
| `mcp-server/worker/nl2sql_worker.py` | (MED) `_run_sql`/`_query_pv_history`/`_get_tag_metadata`/`_list_drawings`/`_query_with_nl` 5개 함수가 async 안에서 `psycopg.connect()` blocking 호출 → `_aget_db_connection()` 헬퍼(`asyncio.to_thread`)로 격리 |
| `mcp-server/worker/nl2sql_worker.py` | (Phase 6) `_validate_sql` + `_apply_sql_guards` 추가, `_run_sql`·`_query_with_nl`에 auto-LIMIT/statement_timeout 적용 |
| `mcp-server/server.py` | (Phase 6) `_validate_sql` 강화 (단어 경계 매칭으로 `updated_at` 오탐 제거, `WITH` 허용, 세미콜론 다중문장 차단, `TRUNCATE`/`COPY` 추가). `SQL_MAX_ROWS=1000`, `SQL_STATEMENT_TIMEOUT_MS=30000` 환경변수화. `_apply_sql_guards`로 LIMIT 미지정 시 서브쿼리 wrap. `_execute_sql_internal`에서 매 호출 `SET statement_timeout` 적용. `run_sql` 도구 docstring 갱신 |
| `src/Infrastructure/Kb/KbIngestWorker.cs` | (LOW) 단일 청크 임베딩 실패 시 전체 abort → skip 후 부분 인덱싱, `error_message`에 `"부분 인덱싱: N/M 청크"` 기록. 전 청크 실패 시에만 throw |
| `src/Infrastructure/Kb/KbAuthService.cs` | (LOW) 초기 비번 로그 평문 → 마스킹(앞 4자만)으로 변경, 평문은 `Console.Out`으로 1회 분리 출력 (파일 로거 미포함) |
| `src/Infrastructure/Kb/KbQdrantClient.cs` | (LOW) `new HttpClient` 직접 생성 → `IHttpClientFactory.CreateClient("KbQdrant")` |
| `src/Web/Program.cs` | (LOW) `AddHttpClient("KbQdrant")` 팩토리 등록 (BaseAddress + 30s Timeout) |
| `src/Web/Controllers/OllamaController.cs` | (LOW) `LoadPlantContext()` 매 요청 `File.ReadAllText` → mtime 기반 캐시 (lock 보호) |
| `src/Infrastructure/Database/ExperionDbContext.cs` | (HIGH) KB DDL의 `ExecuteSqlRawAsync` 사용 → `JSONB '{}'` / `TEXT[] '{}'` / 시드 JSON의 중괄호가 `String.Format` placeholder로 오인되어 부팅 실패. 별도 `NpgsqlConnection` + `NpgsqlCommand.ExecuteNonQueryAsync`로 전환 |
| `.gitignore` | KB 업로드 원본 디렉토리 `storage/` 추가 (런타임 데이터는 git 추적 제외) |
| `src/Web/wwwroot/js/app.js` | `llmRenderToolCardsHtml`(영구 렌더), `llmDetectTimeSeries`+`llmBuildSparklineHtml`+`llmMountSparkline`(uPlot), `kbShowChunks`+`kbRenderChunks`(모달), `LLM_MAX_HISTORY`+`llmEnsureSummary`+`sess.summary` 표시, `llmAgentMode`+`llmToggleAgentMode`, 툴 카드 표시 + 요약 prepend 로직 |
| `src/Web/wwwroot/index.html` | `#kb-chunk-modal` 모달, `#llm-agent-row`/`#llm-agent-mode` 토글 |
| `src/Web/wwwroot/css/style.css` | `.kb-chunk-*`(청크 카드/뱃지/locator), `.llm-sparkline-box/-chart`, `.llm-summary-card`(접기/펼침) |
| `src/Web/Controllers/OllamaController.cs` | `AgentMode` request 필드, `ComposeSystemPrompt(agentMode)`, `AgentModeGuideKo` ReAct 가이드, `POST /api/ollama/summarize` 엔드포인트, `OllamaSummarizeRequest` DTO, `ToolGuideKo`에 `classify_intent` 추가 |
| `src/Web/Controllers/KbController.cs` | `GET /api/kb/documents/{id}/chunks` (admin) — KbQdrantClient Scroll 호출 |
| `src/Infrastructure/Kb/KbQdrantClient.cs` | `GetChunksByDocIdAsync(collection, docId, limit)` — payload-only Scroll API |
| `mcp-server/server.py` | `_CLASSIFY_RULES`+`_classify_intent`+`@mcp.tool() classify_intent`, `query_with_nl` 진입부에서 라우팅 후 5개 전용 도구로 위임 (실패 시 SQL fallback) |
#### Phase 6 — `run_sql` 가드 동작
#### 의도 라우터 규칙
| 가드 | 동작 |
| 정규식 | 라우팅 대상 |
|--------|------------|
| `활성.*알람\|현재.*알람\|지금.*알람\|active.*alarm` | `active_alarms` |
| `트립\|trip` | `active_alarms` |
| `상태\s*보고서\|교대.*보고\|status.*report\|운전.*보고` | `generate_status_report` |
| `요약\|보고서\|리포트\|summary\|summarize\|report` | `summarize_events` |
| `태그.*찾\|tag.*찾\|찾아\s*줘\|find.*tag\|어떤.*태그` | `find_tags` |
| `이벤트.*조회\|이벤트.*목록\|event.*list\|event.*query\|로그.*조회` | `query_events` |
| (그 외) | `query_with_nl` (기본 SQL 경로) |
스모크 테스트 10건 모두 통과 — "지금 알람 알려줘"→active_alarms / "FIC-6113.PV 값 보여줘"→query_with_nl / "안녕"→query_with_nl 등.
#### 설계 결정
| 항목 | 결정 |
|------|------|
| 키워드 차단 | `\b{kw}\b` 단어 경계 매칭 — `INSERT/UPDATE/DELETE/DROP/ALTER/CREATE/GRANT/REVOKE/TRUNCATE/COPY/EXEC` |
| 시작 키워드 | `SELECT` 또는 `WITH`만 허용 (선행 `(` 허용) |
| 다중 문장 | 끝의 `;` 제외하고 `;` 포함 시 차단 |
| 자동 LIMIT | 꼬리 `LIMIT N [OFFSET M]` 미지정 시 `SELECT * FROM ({sql}) _capped LIMIT 1000` wrap |
| 타임아웃 | `SET statement_timeout = 30000` (커넥션별) |
| 환경변수 | `SQL_MAX_ROWS`, `SQL_STATEMENT_TIMEOUT_MS`로 조정 가능 |
| 툴 카드 영구화 | `assistantMsg.toolCalls`에 `{id,name,args,ok,preview,length,payload}` 누적 저장. 기존 세션에 `toolCalls` 없으면 렌더링 생략(역호환) |
| AbortError 시 | `content` 또는 `toolCalls`가 비어있지 않으면 메시지 유지 (도구만 호출하고 중단된 경우도 보존) |
| 시계열 감지 | `timestamp/recorded_at/ts/time/datetime` + `value/pv/val/fieldvalue/sp/op` 페어. 3건 이상이어야 차트 생성. uPlot 미로딩 시 렌더 생략 |
| 스파클라인 부착 | innerHTML로 컨테이너만 만든 후 `requestAnimationFrame`에서 uPlot 생성 (DOM 마운트 후 실행 보장) |
| 요약 임계 | `LLM_MAX_HISTORY=20` 초과 시 오래된 절반을 요약. 누적 요약은 이전 요약을 system 메시지로 함께 전송 |
| 요약 송신 | sess.summary가 있으면 systemPrompt 맨 앞에 `[이전 대화 요약]` 블록 prepend. 사용자에게는 접이식 카드로 표시 |
| 의도 라우터 fallback | 라우팅 시도 실패(예외) 시 조용히 SQL 경로로 fallback |
| 에이전트 모드 조건부 표시 | `llmType==='vllm' && llmUseTools` 일 때만 토글 노출. localStorage 영속 |
| 청크 미리보기 권한 | admin 토큰 필요. payload만 조회(vector 제외), 최대 500개/문서 |
응답 JSON에 `row_limit` 필드 추가 — 클라이언트가 잘림 여부 판단 가능.
#### 빌드/검증 결과
#### 빌드/검증
- `dotnet build src/Web/ExperionCrawler.csproj` — 경고 0건, **에러 0건**
- `python3 -m py_compile mcp-server/server.py mcp-server/worker/nl2sql_worker.py` — OK
- `_apply_sql_guards` / `_validate_sql` 스모크 테스트 통과
- `SELECT *` → wrap 적용, `LIMIT 10` / `LIMIT 10 OFFSET 5` → 그대로
- `SELECT 1; DROP TABLE x` → 차단, `WITH t AS ...` → 허용
- `SELECT updated_at` → 허용 (단어 경계 매칭으로 `UPDATE` 키워드 오탐 제거)
#### 잔여 (이 커밋 이후)
- Phase 6 나머지: `query_events`, `summarize_events`, `active_alarms`, `find_tags`, `generate_status_report`
- Phase 7 옵션, Phase 5 후순위는 변동 없음
- `appsettings.json`의 `AdminInitialPassword: "admin"`은 사용자 지시로 유지 (운영 전 제거 권장)
---
### Phase 6 보강 도구 5종 추가 (2026-05-14)
#### 배경
운전원이 채팅으로 "지금 활성 알람 뭐 있어?", "오늘 6-1차 area 이벤트 요약해줘", "교대 시작 보고서 만들어줘" 등을 묻는 경우 단순 SQL 조회만으로는 부족. 이벤트 중심 도구와 LLM 요약/보고서 도구가 필요.
#### 신규 MCP 도구
| 도구 | 입력 | 동작 |
|------|------|------|
| `find_tags(query, area?, top_k=20)` | 자연어 일부 | `v_tag_summary` 뷰에서 `base_tag` 또는 `description` ILIKE 매칭, 옵션 area 필터. PV/SP/OP/설명/area 함께 반환 |
| `query_events(tag_name?, event_type?, area?, since?, until?, limit=100)` | 필터 조건 | `event_history_table`에서 시간/태그/타입/area 필터로 조회. since/until 미지정 시 최근 24시간 |
| `active_alarms(area?, limit=100)` | area 옵션 | `DISTINCT ON (tagname)` + `WHERE event_type IN ('ALARM','TRIP')`로 태그별 최신 이벤트가 알람/트립인 것만 |
| `summarize_events(since?, area?, event_type?, max_events=200, focus?)` | 범위 + 강조점 | `query_events` 결과를 LLM에 넣어 한국어 6~10줄 구조화 요약 (현황/알람/패턴/권고) + 통계 |
| `generate_status_report(area?, hours=24)` | area + 윈도우 | 활성알람 + 최근 이벤트 통계 + 표본을 LLM에 넘겨 교대 보고서 형식(요약/알람/이벤트분석/권고) 마크다운 생성 |
모두 `SET statement_timeout = 30000` 적용, prepared statement(파라미터 바인딩)으로 SQL 인젝션 방지.
#### 수정 파일
| 파일 | 수정 내용 |
|------|----------|
| `mcp-server/server.py` | "Phase 6 보강 도구" 섹션 추가 — 5개 `@mcp.tool()` 함수 + `_VALID_EVENT_TYPES` 상수. `_DB_SCHEMA` 컨텍스트에 `event_history_table` 정의 추가 (NL2SQL이 인지하도록) |
| `src/Web/Controllers/OllamaController.cs` | `ToolGuideKo` 갱신 — `find_tags / query_events / active_alarms / summarize_events / generate_status_report / search_kb` 항목 추가, event_type 5종 명시, `run_sql` 자동 가드 안내 |
#### 설계 결정
| 항목 | 결정 |
|------|------|
| 알람 정의 | "활성 알람 = 태그의 최신 이벤트가 ALARM 또는 TRIP" — NORMAL이 들어오면 자동 해제. 최근 30일 윈도우로 DISTINCT ON 처리 |
| 이벤트 타입 | `DigitalEventDetectorService.DetermineEventType` 그대로 — TRIP/ALARM/NORMAL/RUN/CHANGE 5종 |
| LLM 모델 | `VLLM_MODEL`(현재 Qwen3.6-27B-FP8) 공용. summarize: max_tokens 1200, report: 2048 |
| 보고서 윈도우 | 1~168시간(최대 7일), 기본 24시간 |
| 도구 노출 | 클라이언트가 `McpService.ListToolsAsync`로 동적 수집 → 새 도구는 mcp-server 재시작만으로 자동 등록 |
| 시스템 프롬프트 | `ToolGuideKo`에 도구 + event_type 5종 명시해 LLM이 적절한 도구를 선택하도록 유도 |
#### 빌드/검증 결과
- `dotnet build`: 경고 0건, **에러 0건**
- `python3 -m py_compile mcp-server/server.py mcp-server/worker/nl2sql_worker.py`: OK
- `import server` 후 5개 도구 모두 attribute로 노출 확인
- `python3 -c "import server"` — 9개 도구 모두 attribute로 노출 확인
- `node -c src/Web/wwwroot/js/app.js` — syntax OK
- 의도 분류기 10/10 통과
#### 런타임 셋업
- `mcp-server` 재시작 필요 — 5개 신규 도구 인식
- 클라이언트(채팅 #13)는 도구 토글 ON 상태에서 자동으로 새 도구 함수 시그니처 노출
- `mcp-server` 재시작 — `classify_intent` 신규 도구 인식
- 브라우저 캐시 무효화 (Ctrl+F5) — 신규 JS/CSS 적용
- 사용자 첫 진입 시 에이전트 모드 토글은 OFF (옵트인)
#### 잔여 (이 커밋 이후)
- Phase 7 (옵션): NL2SQL 의도 라우터, 대화 요약, 에이전트 모드, KB 청크 미리보기 UI
- Phase 5 후순위: 시계열 미니 스파클라인, 툴 카드 메시지 영구 보존
- 결정 보류: 현장 재고 데이터 출처, 임베딩 모델 BGE-M3 마이그레이션
→ Phase 6 모두 완료. CLAUDE.md 첫 잔여 작업 항목에서 Phase 6 줄 삭제 가능.
---
### 기능 추가 — OPC UA 서버 기능 (2026-04-15)
#### 배경
ExperionCrawler가 OPC UA 클라이언트 역할만 했으나, 외부 OPC UA 클라이언트(SCADA, MES 등)가 ExperionCrawler에 접속해 실시간 값을 읽을 수 있도록 OPC UA 서버 기능 추가.
#### 아키텍처
```
[Experion HS R530] ──(OPC UA Client)──► ExperionCrawler ◄──(OPC UA Client)── [외부 시스템]
│
(OPC UA Server)
│
[PostgreSQL DB]
```
#### 주소 공간 구조
```
Root/Objects/ExperionCrawler
├── ServerInfo/Status, PointCount, LastUpdateTime
└── Realtime/<tagname_1>, <tagname_2>, … (ns=2;s=tag_{tagname})
```
#### 수정/추가 파일
| 파일 | 수정 내용 |
|------|----------|
| `src/Web/ExperionCrawler.csproj` | `OPCFoundation.NetStandard.Opc.Ua.Server v1.5.378.134` 패키지 추가 |
| `src/Web/appsettings.json` | `OpcUaServer` 섹션 추가 (Port:4841, EnableSecurity:false, AllowAnonymous:true) |
| `src/Core/Application/Interfaces/IExperionServices.cs` | `IExperionOpcServerService` 인터페이스, `OpcServerStatus` record, `GetRealtimeNodeDataTypesAsync()` 추가 |
| `src/Infrastructure/OpcUa/ExperionOpcServerNodeManager.cs` | 신규 — `CustomNodeManager2` 상속, 주소 공간 관리 (`CreateAddressSpace`, `RebuildAddressSpace`, `UpdateNodeValue`) |
| `src/Infrastructure/OpcUa/ExperionOpcServerService.cs` | 신규 — `ExperionStandardServer` + `ExperionOpcServerService` (`IHostedService` + `IExperionOpcServerService`) |
| `src/Infrastructure/OpcUa/ExperionRealtimeService.cs` | `_pointCache` (nodeId→RealtimePoint) 추가; `FlushPendingAsync`에서 OPC 서버 노드 값 lazy 갱신 |
| `src/Infrastructure/Database/ExperionDbContext.cs` | `GetRealtimeNodeDataTypesAsync()` — realtime_table × node_map_master 조인 |
| `src/Web/Controllers/ExperionControllers.cs` | `ExperionOpcServerController` 추가 (start/stop/status/rebuild) |
| `src/Web/Program.cs` | `ExperionOpcServerService` Singleton+HostedService 등록 |
| `src/Web/wwwroot/index.html` | 08 OPC UA 서버 탭 + pane-opcsvr 섹션 추가 |
| `src/Web/wwwroot/js/app.js` | `srvLoad/Start/Stop/Rebuild/_srvRender/_srvStartPoll/_srvStopPoll` 구현 |
| `src/Web/wwwroot/css/style.css` | `.srv-status-card`, `.srv-meta`, `.dot.grn` 스타일 추가 |
#### 주요 설계 결정
| 항목 | 결정 |
|------|------|
| 인증서 | 기존 `pki/own/certs/{hostname}.pfx` 재사용 (`ApplicationType.ClientAndServer`) |
| 포트 | 기본 4841 (4840은 Experion HS R530이 사용 가능) |
| 보안 | 기본 None (appsettings.json에서 변경 가능) |
| 자동 재시작 | `opcserver_autostart.json` 플래그 파일 패턴 (RealtimeService와 동일) |
| 순환 참조 | `IServiceProvider` lazy resolve — `_opcServer ??= _sp.GetService<IExperionOpcServerService>()` |
| FlushLoop 연동 | 500ms 배치 DB 업데이트 후 → OPC 서버 노드 값도 동시 갱신 (DB 폴링 없음) |
#### API 엔드포인트
- `GET /api/opcserver/status` — 상태 조회 (running, clientCount, nodeCount, endpointUrl, startedAt)
- `POST /api/opcserver/start` — 서버 시작
- `POST /api/opcserver/stop` — 서버 중지
- `POST /api/opcserver/rebuild` — 주소 공간 재구성
#### 빌드 결과
- 경고 11건 (기존 8건 + OPC SDK Server Start/Stop deprecated 3건), **에러 0건** — 빌드 성공
#### OPC UA 서버가 노출하는 데이터
**데이터 출처**: `realtime_table`에 등록된 포인트 전체 (포인트빌더에서 빌드/수동 추가한 포인트)
**주소 공간 구조**
```
Root/Objects/ExperionCrawler
├── ServerInfo/
│ ├── Status (String) — "Running" / "Stopped"
│ ├── PointCount (Int32) — 구독 중인 포인트 수
│ └── LastUpdateTime (DateTime) — 마지막 값 갱신 시각
└── Realtime/
├── <tagname_1> ns=2;s=tag_FIC101_PV
├── <tagname_2>
└── …
```
**NodeId 명명 규칙**: `ns=2;s=tag_{tagname}`
**DataType 결정**: `realtime_table` × `node_map_master` 조인
- Double/Float/Int32/Int64/Boolean/DateTime → 해당 OPC UA 타입
- 기타/NULL → String (fallback)
**접근 제한**: 읽기 전용 (`AccessLevel = CurrentRead`), `Historizing = false`
**갱신 주기**: Experion HS R530 → FlushLoop 500ms 배치 → DB + OPC 서버 노드 동시 갱신
---
### 로그 정리 — 스냅샷 로그 2줄 → 1줄 (2026-04-15)
#### 증상
히스토리 스냅샷 1회 저장마다 터미널에 로그 2줄 출력:
```
[ExperionDb] history 스냅샷: 1752건 @ 01:14:18
[HistoryService] 스냅샷 저장: 1752건
```
#### 원인
DB 저장 완료 후 `ExperionDbService`에서 `LogInformation`, 호출자 `ExperionHistoryService`에서도 `LogInformation`. 저장은 1회이나 로그가 2줄.
#### 수정 파일
| 파일 | 수정 내용 |
|------|----------|
| `src/Infrastructure/Database/ExperionDbContext.cs` | `SnapshotToHistoryAsync()` 내부 로그를 `LogInformation` → `LogDebug`로 변경 |
#### 결과
운영 로그(`Information` 레벨)에서 `[HistoryService] 스냅샷 저장: N건` 1줄만 출력.
---
### 버그 수정 — Ctrl+C 종료 시 자동재시작 플래그 삭제 오류 (2026-04-15)
#### 증상
Ctrl+C로 앱 종료 시 `realtime_autostart.json` 플래그 파일이 삭제되어, 재기동 후 자동 구독 시작이 동작하지 않음.
#### 원인
`IHostedService.StopAsync(CancellationToken)` (앱 종료 훅)이 UI 수동 중지 메서드인 `StopAsync()`를 그대로 호출. `StopAsync()`는 플래그 파일을 삭제하므로 앱 종료와 수동 중지를 구분하지 못했음.
#### 수정 파일
| 파일 | 수정 내용 |
|------|----------|
| `src/Infrastructure/OpcUa/ExperionRealtimeService.cs` | `IHostedService.StopAsync(CancellationToken)` 분리 — `_cts.Cancel()` + 태스크 대기만 수행, 플래그 파일 삭제 없음 |
#### 동작 구분
| 종료 방식 | 플래그 파일 |
|----------|------------|
| Ctrl+C (앱 종료) | **유지** → 재기동 시 자동 구독 시작 |
| UI 중지 버튼 | **삭제** → 재기동 후 자동 시작 없음 |
---
### 버그 수정 — 이력 조회 중복 키 예외 (2026-04-15)
#### 증상
이력 조회 시 서버 500 에러:
```
System.ArgumentException: An item with the same key has already been added.
Key: p-6102.hzset.fieldvalue
at ExperionDbService.QueryHistoryAsync ... line 342
```
#### 원인
`history_table`에 동일 `recorded_at` + 동일 `tagname` 조합이 중복 저장된 행 존재. `.ToDictionary(r => r.TagName, r => r.Value)` 호출 시 중복 키로 예외 발생.
#### 수정 파일
| 파일 | 수정 내용 |
|------|----------|
| `src/Infrastructure/Database/ExperionDbContext.cs` | `TagName` 기준 `GroupBy` 추가 → 중복 시 `.Last().Value` 사용 |
---
### 기능 추가 — 이력 조회 날짜/시간 팝업 피커 (2026-04-15)
#### 배경
- `datetime-local` 입력이 Windows 브라우저 로케일에 따라 AM/PM 12시간제로 표시됨
- 서버(Ubuntu UTC) / 브라우저(Windows KST) 시간대 차이로 인한 표시 혼란
#### 설계
- `datetime-local` 입력 제거 → 클릭 시 커스텀 달력+시간 팝업 오픈
- 달력: 월 이동 가능, 오늘 날짜 amber 강조, 선택일 반전 표시
- 시간: 24시간제, `−`/`+` 버튼 또는 직접 입력 (0–23시, 0–59분)
- 확인 시 `YYYY-MM-DD HH:MM` 형식으로 필드 표시
- hidden input에 로컬 시간 문자열 저장 → `new Date(...).toISOString()`으로 KST→UTC 변환 후 서버 전송 (기존 로직 유지)
#### 수정 파일
| 파일 | 수정 내용 |
|------|----------|
| `src/Web/wwwroot/index.html` | `datetime-local` 2개 → `.dt-display` + `hidden input` 교체; 팝업 HTML(`#dt-popup`, `#dt-overlay`) 추가 |
| `src/Web/wwwroot/css/style.css` | `.dt-popup`, `.dt-cal-grid`, `.dt-day`, `.dt-time-row` 등 피커 전용 다크 테마 스타일 추가; 기존 `datetime-local` AM/PM 숨김 CSS 제거 |
| `src/Web/wwwroot/js/app.js` | `dtOpen()`, `dtRenderCal()`, `dtSelectDay()`, `dtPrevMonth()`, `dtNextMonth()`, `dtAdjTime()`, `dtClampTime()`, `dtConfirm()`, `dtClear()`, `dtClose()` 구현; `histReset()`에서 `dtClearField()` 호출로 표시 텍스트 초기화 |
#### 빌드 결과
- 경고 8건 (기존 동일), **에러 0건** — 빌드 성공
---
### 버그 수정 — 단일 태그 읽기 성공/실패 판정 오류 (2026-04-15)
#### 증상
서버접속테스트 페이지에서 단일 태그 읽기 시, OPC UA 서버가 `BadNodeIdUnknown(0x80340000)` 등 에러 상태 코드를 반환해도 "✅ 읽기 성공"으로 표시되는 버그.
#### 원인
`ExperionOpcClient.cs`의 `ReadTagsAsync` 내부에서 `StatusCode` 값과 무관하게 `Success = true`를 하드코딩해서 `ExperionReadResult`를 생성했음.
#### 수정 파일
| 파일 | 수정 내용 |
|------|----------|
| `src/Infrastructure/OpcUa/ExperionOpcClient.cs` | `StatusCode.IsGood()` 결과를 `Success` 플래그로 사용. Bad이면 `Success=false`, `Value=null`, `Error`에 상태 코드 메시지 설정 |
#### 결과
`BadNodeIdUnknown` 등 Bad 상태 코드 수신 시 → ❌ 읽기 실패로 정상 표시
#### 빌드 결과 (경고 상세)
경고 8건, **에러 0건** — 빌드 성공
| # | 파일 | 내용 |
|---|------|------|
| 1 | `ExperionOpcClient.cs:108` | `Session.Create()` → `ISessionFactory.CreateAsync` 사용 권장 |
| 2 | `ExperionRealtimeService.cs:161` | `Subscription.ApplyChanges()` → `ApplyChangesAsync()` 사용 권장 |
| 3 | `ExperionRealtimeService.cs:168` | 동일 |
| 4 | `ExperionRealtimeService.cs:277` | `Subscription.Create()` → `CreateAsync()` 사용 권장 |
| 5 | `ExperionRealtimeService.cs:346` | `Subscription.Delete()` → `DeleteAsync()` 사용 권장 |
| 6 | `ExperionRealtimeService.cs:424` | `Session.Create()` → `ISessionFactory.CreateAsync` 사용 권장 |
| 7–8 | (위 항목 중 중복 카운트) | — |
전부 OPC UA SDK가 동기 메서드를 `[Obsolete]`로 표시하고 비동기 버전을 권장하는 경고. 기능상 문제 없음.
---
### 노드맵 대시보드 구현 (2026-04-14)
node_map_master 테이블을 조회·탐색할 수 있는 웹 대시보드를 풀스택으로 구현했다.
#### 수정된 파일
| 파일 | 내용 |
|------|------|
| `src/Core/Application/Interfaces/IExperionServices.cs` | `IExperionDbService`에 `GetMasterStatsAsync()` / `QueryMasterAsync()` 추가, `NodeMapStats` / `NodeMapQueryResult` record 추가 |
| `src/Infrastructure/Database/ExperionDbContext.cs` | `ExperionDbService`에 두 메서드 구현 (통계·필터 조회, 페이지네이션) |
| `src/Web/Controllers/ExperionControllers.cs` | `ExperionNodeMapController` 추가 (`GET /api/nodemap/stats`, `GET /api/nodemap/query`) |
| `src/Web/wwwroot/index.html` | 사이드바 05번 탭 추가, `#pane-nm-dash` 섹션 추가 (통계 카드·필터폼·페이지네이션·테이블) |
| `src/Web/wwwroot/js/app.js` | `nmLoad()` / `nmQuery()` / `nmPrev()` / `nmNext()` / `nmReset()` 구현, 탭 클릭 핸들러에 `nmLoad()` 호출 추가 |
| `src/Web/wwwroot/css/style.css` | `.nm-stat-row`, `.nm-cls`, `.nm-dtype`, `.pg`, `.btn-sm` 등 대시보드 전용 스타일 추가 |
#### 빌드 결과
- 경고 3건 (기존 경고 동일), **에러 0건** — 빌드 성공
#### 주의 사항
- 인증서 관련 코드(`ExperionCertificateService.cs`, 인증서 컨트롤러)는 일절 수정하지 않음
---
### 이름 필터 드롭다운 OR 조건 검색 (2026-04-14)
노드맵 대시보드의 이름 검색을 텍스트 입력에서 `name` 컬럼 고유값 풀다운 메뉴 4개로 교체, OR 조건 최대 4개 동시 선택 가능하도록 확장했다.
#### 수정된 파일
| 파일 | 내용 |
|------|------|
| `src/Core/Application/Interfaces/IExperionServices.cs` | `GetNameListAsync()` 추가; `QueryMasterAsync` 파라미터 `string? name` → `IEnumerable<string>? names` |
| `src/Infrastructure/Database/ExperionDbContext.cs` | `GetNameListAsync()` 구현 (distinct + 오름차순 정렬); `QueryMasterAsync`에서 `nameList.Contains(x.Name)` → EF가 `WHERE name IN (...)` SQL 생성 |
| `src/Web/Controllers/ExperionControllers.cs` | `GET /api/nodemap/names` 엔드포인트 추가; `Query` 액션 파라미터 `string? name` → `List<string>? names` (ASP.NET Core가 `?names=A&names=B` 자동 바인딩) |
| `src/Web/wwwroot/index.html` | "이름 검색" 텍스트 입력 제거 → `nf-name-1` ~ `nf-name-4` 4개 `<select>` 드롭다운 추가 |
| `src/Web/wwwroot/js/app.js` | `nmLoad()`에서 `/api/nodemap/names` 병렬 호출 후 4개 드롭다운 채우기; `nmQuery()`에서 선택 이름들을 `params.append('names', nm)`로 OR 전송; `nmReset()`에서 4개 드롭다운 초기화 |
| `src/Web/wwwroot/css/style.css` | `.nm-name-selects` (4열 그리드, 900px 이하 2열) 추가 |
#### 빌드 결과
- 경고 3건 (기존 경고 동일), **에러 0건** — 빌드 성공
---
## 구현 완료 (2026-04-14, todo.md 전항목)
### 빌드 결과
- 경고 6건 (기존 3건 + 신규 3건 OPC SDK deprecated API 경고), **에러 0건** — 빌드 성공
---
## 버그 수정 이력 (2026-04-14)
### 버그 1 — OPC UA 연결 시 OS TCP 타임아웃(최대 127초) 문제
#### 증상
- 접속 테스트 버튼을 눌렀을 때 수분간 응답 없는 것처럼 보임
- `ExperionRealtimeService`: "연결 오류, 30초 후 재시도" 로그가 매우 늦게 출력됨
- 오류: `System.Net.Sockets.SocketException (110): Connection timed out`
#### 원인
Linux에서 OPC UA 서버 IP가 응답 없음(firewall/unreachable)이면 OS TCP SYN 재전송 타임아웃이 최대 127초까지 걸림. `TransportQuotas.OperationTimeout`은 OPC UA 프로토콜 레벨 타임아웃이라 TCP connect 단계에는 적용되지 않음.
#### 수정 파일
| 파일 | 수정 내용 |
|------|----------|
| `ExperionOpcClient.cs` | `SelectEndpointAsync`에 `CancellationTokenSource(10초)` 추가 — DiscoveryClient 생성 시 10초 타임아웃 적용 |
| `ExperionRealtimeService.cs` | 동일하게 `SelectEndpointAsync` 10초 타임아웃 적용 |
#### 결과
서버 미응답 시 127초 대기 → **10초 이내 실패** 처리
---
### 버그 2 — PostgreSQL `sorry, too many clients already` (SQLSTATE 53300)
#### 증상
구독 시작 후 실시간 값 수신 시 터미널에 다량의 에러:
```
Npgsql.PostgresException (0x80004005): 53300: sorry, too many clients already
at ExperionDbService.UpdateLiveValueAsync(...)
at ExperionRealtimeService.<<OnNotification>b__0>d.MoveNext()
```
#### 원인
`OnNotification` 콜백이 포인트마다 `Task.Run` → 새 DI 스코프 → 새 `DbContext` → 새 DB 커넥션을 열었음. 2000여개 포인트가 동시에 값 변경 콜백을 받으면 순식간에 PostgreSQL `max_connections`(기본 100) 초과.
```
값 변경 콜백 × 2000개 → Task.Run × 2000개 → DB 커넥션 × 2000개 → 💥
```
#### 수정 파일
| 파일 | 수정 내용 |
|------|----------|
| `IExperionServices.cs` | `BatchUpdateLiveValuesAsync(IEnumerable<LiveValueUpdate>)` 인터페이스 추가, `LiveValueUpdate` record 추가 |
| `ExperionDbContext.cs` | `BatchUpdateLiveValuesAsync` 구현 — 단일 DbContext에서 순차 ExecuteUpdateAsync |
| `ExperionRealtimeService.cs` | `OnNotification`에서 `Task.Run` 제거 → `ConcurrentDictionary`에 최신값만 기록. 별도 `FlushLoopAsync` 태스크가 500ms마다 단일 DbContext로 배치 업데이트 |
#### 수정 후 구조
```
값 변경 콜백 × N개 → ConcurrentDictionary[nodeId] = 최신값
↓ 500ms마다
단일 DbContext → BatchUpdateLiveValuesAsync → DB 커넥션 1개
```
#### 결과
- DB 커넥션 동시 사용 수: 2000개 → **최대 1개**
- 500ms 내 중복 변경은 최신값 1건만 DB에 반영 (deduplication)
- 빌드: 경고 6건(기존 동일), **에러 0건**
---
### 버그 3 — 대시보드 탭 진입 시 자동 API 호출로 인한 CPU/브라우저 버벅임
#### 증상
- **노드맵 대시보드** 탭 진입 시 CPU 과부하, 페이지 버벅임
- **포인트빌더** 탭 진입 시 동일 증상
- **이력 조회** 탭 진입 시 한참 동안 열리지 않음
#### 원인 (항목별)
| 탭 | 자동 호출 API | 무거운 이유 |
|----|--------------|------------|
| 노드맵 대시보드 | `/api/nodemap/stats` + `/api/nodemap/names` + `/api/nodemap/query` | stats: 5가지 집계 쿼리(COUNT×4, MAX, DISTINCT). 결과로 전체 조회까지 자동 실행 |
| 포인트빌더 | `/api/nodemap/names` + `/api/nodemap/stats` | stats 집계 쿼리 (포인트빌더 dataType 드롭다운 채우기 용도) |
| 이력 조회 | `/api/history/tagnames` → 드롭다운 8개에 2000개 옵션 삽입 | 8 × 2000 = 16,000개 DOM `<option>` 생성으로 브라우저 freeze |
#### 수정 내용
**공통 원칙**: 탭 진입 시 API 호출 0건. 사용자가 명시적으로 버튼을 눌렀을 때만 실행.
| 파일 | 수정 내용 |
|------|----------|
| `app.js` | 탭 클릭 핸들러에서 `nmLoad()`, `pbLoad()`, `histLoad()` 자동 호출 제거 |
| `app.js` | `nmReset()` 에서 `nmQuery(0)` 자동 호출 제거 |
| `app.js` | `nmLoad()` → `nmLoadNames()`로 분리 (이름 드롭다운만, 버튼 클릭 시 호출) |
| `app.js` | `nmLoad()` 내부의 통계 카드 렌더링 + `nmQuery(0)` 자동 호출 제거 |
| `app.js` | `pbLoad()` 에서 `/api/nodemap/stats` 호출 제거 |
| `app.js` | `histLoad()` 는 유지하되 탭 자동 호출 제거, "▼ 옵션 불러오기" 버튼 클릭 시에만 실행 |
| `index.html` | 노드맵 대시보드: 통계 카드(`nm-stat-row`) 제거, 데이터타입 select → text input |
| `index.html` | 노드맵 대시보드: 이름 드롭다운에 "▼ 옵션 불러오기" 버튼 추가 |
| `index.html` | 포인트빌더: 데이터타입 select 2개 → text input 2개 (`Double`, `Int32` 등 직접 입력) |
| `index.html` | 이력 조회: 태그 선택 드롭다운에 "▼ 옵션 불러오기" 버튼 추가 |
#### 결과 (탭별 진입 시 API 호출 수)
| 탭 | 이전 | 이후 |
|----|------|------|
| 노드맵 대시보드 | stats + names + query = **3건** | **0건** |
| 포인트빌더 | names + stats = **2건** | names = **1건** |
| 이력 조회 | tagnames = **1건** + DOM 16,000개 생성 | **0건** |
#### 주의 사항
- `/api/nodemap/stats` 엔드포인트는 서버에 남아있으나 프론트엔드에서 호출하지 않음
- 이름/태그 드롭다운은 "▼ 옵션 불러오기" 버튼으로 수동 로드
- 데이터타입 필터는 text input 직접 입력 방식으로 변경 (API 불필요)
---
### 버그 4 — 포인트빌더 탭 진입 시 여전히 버벅임 (2026-04-14)
#### 증상
버그 3 수정 이후에도 포인트빌더 탭 진입 시 버벅임 지속.
#### 원인
버그 3 수정 시 탭 핸들러에서 `pbLoad()` 제거를 누락. `app.js`에 `if (tab === 'pb') pbLoad()` 가 그대로 남아 있었음. `pbLoad()`는 `/api/nodemap/names` 호출 → 8개 드롭다운에 전체 name 목록 삽입 → DOM 부하.
#### 수정 파일
| 파일 | 수정 내용 |
|------|----------|
| `app.js` | 탭 핸들러에서 `if (tab === 'pb') pbLoad()` 제거 |
| `index.html` | 포인트빌더 이름 선택 레이블 옆에 "▼ 옵션 불러오기" 버튼 추가 (`onclick="pbLoad()"`) |
#### 결과
포인트빌더 탭 진입 시 API 호출 **0건**
---
### 기능 추가 — 실시간 구독 자동 재시작 플래그 (2026-04-14)
#### 배경
앱 재기동 시 구독이 자동으로 재시작되지 않아 매번 수동으로 구독 시작 버튼을 눌러야 했음.
히스토리 스냅샷이 구독 여부와 무관하게 무조건 실행되어 `livevalue = NULL` 행이 저장되는 문제도 존재.
#### 설계
- 구독 시작 시 서버 설정을 `realtime_autostart.json` 파일로 저장 (앱 실행 디렉토리)
- 앱 기동 시 (`IHostedService.StartAsync`) 파일 존재 여부 확인 → 있으면 자동 구독 시작
- 구독 중지 시 파일 삭제 → 재기동 후 자동 시작 없음
- `ExperionHistoryService`가 `IExperionRealtimeService.GetStatus().Running` 확인 → OFF이면 스냅샷 건너뜀
#### 수정 파일
| 파일 | 수정 내용 |
|------|----------|
| `ExperionRealtimeService.cs` | `StartAsync(cfg)` 시 `realtime_autostart.json` 저장; `StopAsync()` 시 파일 삭제; `StartAsync(CancellationToken)` (IHostedService)에서 파일 읽어 자동 재시작 |
| `ExperionHistoryService.cs` | `IExperionRealtimeService` 생성자 주입; 스냅샷 전 `GetStatus().Running` 체크 → false이면 `continue` |
#### 동작 흐름
```
구독 시작 버튼 → realtime_autostart.json 저장 → OPC UA 구독 시작
앱 재기동 → 파일 감지 → 자동 구독 시작
구독 중지 버튼 → 파일 삭제 → 재기동 후 자동 시작 안 함
히스토리 서비스 → Running=false이면 스냅샷 건너뜀
```
---
### 기능 추가 — 수동 포인트 추가 시 OPC UA 핫 추가 및 유효성 검증 (2026-04-14)
#### 배경
수동으로 포인트를 추가해도 기존 구독에는 반영되지 않아 구독 재시작이 필요했음.
잘못된 node_id 입력 시 DB에만 저장되고 `livevalue`가 영원히 NULL인 문제도 존재.
#### 설계
- 수동 추가 시 DB 저장 후 구독 중이면 `MonitoredItem` 핫 추가 (`ApplyChanges()`)
- OPC UA 서버 응답 상태 확인 → bad 상태코드이면 subscription 제거 + DB 롤백 + 에러 반환
- 구독 중이 아닌 경우 DB에만 저장 → 다음 구독 시작 시 자동 포함
#### 수정 파일
| 파일 | 수정 내용 |
|------|----------|
| `IExperionServices.cs` | `IExperionRealtimeService`에 `AddMonitoredItemAsync(string nodeId)` 추가 (반환: `(bool Success, string Message)`) |
| `ExperionRealtimeService.cs` | `AddMonitoredItemAsync` 구현 — MonitoredItem 생성, `ApplyChanges()`, 상태 확인, bad이면 롤백 |
| `ExperionControllers.cs` | `ExperionPointBuilderController`에 `IExperionRealtimeService` 주입; `Add` 엔드포인트에서 DB 저장 후 `AddMonitoredItemAsync` 호출 → 실패 시 `DeleteRealtimePointAsync`로 DB 롤백 |
#### 동작 흐름
```
수동 추가 요청
├── DB 저장
├── 구독 중 아님 → 성공 ("다음 구독 시작 시 자동 포함")
└── 구독 중
├── OPC UA ApplyChanges() → Good → 즉시 구독 포함, 성공
└── OPC UA → Bad → subscription 제거 + DB 롤백 + 에러 반환
```
#### 빌드 결과
- 경고 8건 (기존 6건 + OPC SDK deprecated 2건), **에러 0건** — 빌드 성공
---
### 성능 분석 — 1,699포인트 기준 CPU 부하 추정 (2026-04-14)
#### 전제 조건
- 실시간 포인트: 1,699개
- 히스토리 스냅샷 주기: 60초
- 실시간 배치 flush 주기: 500ms
#### 히스토리 스냅샷 (60초마다)
- 작업: `realtime_table` 1,699행 SELECT → `history_table` INSERT 1,699행
- 특성: 1분에 1번 순간 burst, 수십 ms 수준
- 앱 CPU: EF Core 객체 생성 1,699개 → 거의 무시 가능
- **결론: 평균 CPU 기여 < 1%**
#### 실시간 livevalue 갱신 (500ms마다 배치)
- 작업: `ExecuteUpdateAsync` × (변경된 포인트 수)건 / 500ms
- OPC UA는 값이 바뀔 때만 콜백 → 전 포인트가 동시에 변경되는 경우는 드묾
- 실제 변경 수: 수십~수백건/500ms가 일반적
- **결론: 변경 포인트 수에 비례, 대부분의 경우 낮음**
#### 종합
| 작업 | 주기 | 예상 CPU |
|------|------|----------|
| 히스토리 스냅샷 | 60초/회 | 무시 가능 (< 1%) |
| 실시간 배치 업데이트 | 500ms/회 | 변경 포인트 수에 비례 |
| **합계** | - | **단일 코어 기준 5~15% 이내** |
실제 병목은 CPU보다 **PostgreSQL I/O와 커넥션 처리**쪽이 먼저 나타남. 현재 구조(단일 DbContext, 배치 flush)는 이미 최적화된 상태.
---
### 성능 분석 — 멀티모니터 4대 실시간 폴링 부하 (2026-04-14)
#### 시나리오
- 웹페이지에서 `realtime_table` 조회, 페이지당 200개, 2초 간격 갱신
- 멀티모니터 4대에서 4개의 브라우저 탭/창이 동시 동작
#### 부하 추정
| 항목 | 계산 | 평가 |
|------|------|------|
| 서버 요청 수 | 4탭 × 1회/2초 = **2 req/s** | 무시 가능 |
| DB 쿼리 | SELECT 200행 × 2회/s | 경량 |
| 응답 크기 | 200행 × ~150 bytes ≈ **30KB/응답** | 소량 |
| 네트워크 | 4 × 30KB / 2s = **60KB/s** | 거의 없음 |
| 브라우저 RAM | 탭당 60~100MB × 4 = **240~400MB** | 보통 수준 |
**결론: 서버 부하 크지 않음. 일반 개발용 PC(i5급, 8GB RAM)에서 충분히 감당 가능.**
#### 실질적 병목 — 브라우저 DOM 재렌더링
현재 `pbRender()`는 `tbl.innerHTML`로 테이블 전체를 교체하는 방식 (full re-render).
- 200행 × 4탭 × 2초마다 전체 재생성 → 체감 가능한 CPU 사용
#### 결정 사항
**실시간 모니터링 페이지 구현 시 반드시 incremental DOM update 방식 사용**
- 이미 그려진 `<td>` 셀의 `.textContent`만 갱신 (값이 바뀐 셀만)
- `innerHTML` 전체 교체 금지
- 구조 변경(행 추가/삭제) 시에만 DOM 재구성 허용
---
### TimescaleDB 관련 결정 사항 (2026-04-14)
PostgreSQL에 TimescaleDB 확장이 설치되어 있음.
#### 결론: 앱 코드 수정 불필요
TimescaleDB는 PostgreSQL **확장(extension)** 이므로:
- 연결 문자열: 기존 PostgreSQL 그대로 사용
- EF Core / Npgsql 드라이버: 그대로 사용
- `history_table` hypertable 전환은 DB에서 DDL 한 줄만 실행
```sql
SELECT create_hypertable('history_table', 'recorded_at');
```
이 명령을 DB에서 한 번 실행하면 이후 INSERT/SELECT는 코드 변경 없이 TimescaleDB가 자동으로 시계열 최적화를 적용함.
**DbContext, 엔티티, 컨트롤러 등 앱 코드는 전혀 수정 불필요.**
---
## 구현 계획 (참고용)
### Task 1 — RealtimeTable + 포인트빌더 대시보드
#### 개요
- `realtime_table` PostgreSQL 테이블 생성: `id, tagname, node_id, livevalue, timestamp`
- `tagname`: `node_id.Substring(node_id.LastIndexOf(':') + 1)` (마지막 ':' 오른쪽 문자열, 없으면 전체)
- 소스: `node_map_master WHERE name IN (...) AND data_type = 'Double'`
#### 수정 파일
| 파일 | 내용 |
|------|------|
| `ExperionEntities.cs` | `RealtimePoint` 엔티티 추가 (`realtime_table` 매핑) |
| `IExperionServices.cs` | `IExperionDbService`에 `BuildRealtimeTableAsync`, `GetRealtimePointsAsync`, `AddRealtimePointAsync`, `DeleteRealtimePointAsync` 추가 |
| `ExperionDbContext.cs` | `DbSet<RealtimePoint>`, 테이블 DDL, 4개 서비스 메서드 구현 |
| `ExperionControllers.cs` | `ExperionPointBuilderController` 추가 (POST /api/pointbuilder/build, GET /api/pointbuilder/points, POST /api/pointbuilder/add, DELETE /api/pointbuilder/{id}) |
| `index.html` | 06번 탭 '포인트빌더' 추가 — name 드롭다운 8개, dataType 드롭다운, 빌드 버튼, 수동 node_id 입력, 포인트 테이블 |
| `app.js` | `pbLoad()`, `pbBuild()`, `pbAddManual()`, `pbDelete(id)`, `pbRender()` 구현 |
| `style.css` | 포인트빌더 전용 스타일 추가 |
#### 설계 결정
- `BuildRealtimeTableAsync`는 기존 레코드를 모두 지우고 재생성 (TRUNCATE + INSERT)
- 수동 추가(`AddRealtimePointAsync`)는 `tagname`을 자동 추출해서 삽입
- 약 2000건 → 페이지네이션 불필요, 전체 목록을 클라이언트 측 테이블로 렌더링
---
### Task 2 — OPC UA 실시간 구독 (livevalue 업데이트)
#### 개요
- OPC UA Subscription + MonitoredItem API 사용 (값 변경 시에만 콜백)
- `IExperionRealtimeService` 인터페이스 + `ExperionRealtimeService` BackgroundService 신규 파일
- 서버 접속 설정은 `appsettings.json`에서 읽음 (기존 `ExperionServerConfig` 구조 재사용)
- 값 변경 콜백 → `realtime_table.livevalue` 업데이트 + `timestamp` 갱신
#### 수정 파일
| 파일 | 내용 |
|------|------|
| `IExperionServices.cs` | `IExperionRealtimeService` 인터페이스, `IExperionDbService`에 `UpdateLiveValueAsync` 추가 |
| `ExperionDbContext.cs` | `UpdateLiveValueAsync` 구현 |
| `ExperionRealtimeService.cs` (신규) | `BackgroundService` 구현 — Subscription 생성, MonitoredItem 등록, 콜백 처리 |
| `ExperionControllers.cs` | `ExperionRealtimeController` 추가 (POST /api/realtime/start, POST /api/realtime/stop, GET /api/realtime/status) |
| `Program.cs` | `AddHostedService<ExperionRealtimeService>()` 등록 |
| `index.html` + `app.js` | 포인트빌더 탭에 실시간 시작/정지 버튼, 상태 표시, livevalue 폴링(3초) 추가 |
#### 설계 결정
- OPC UA Subscription: `PublishingInterval = 1000ms`
- MonitoredItem: `SamplingInterval = 500ms`, `DeadBandType = None`
- 값 변경 없으면 콜백 없음 → DB 업데이트 없음 (OPC UA 규약 준수)
- 서비스 재시작 시 자동 재연결 로직 포함 (30초 재시도)
---
### Task 3 — HistoryTable (시계열 스냅샷)
#### 개요
- `history_table`: `id, tagname, node_id, value, recorded_at`
- `ExperionHistoryService` BackgroundService → 설정된 주기(기본 60초)마다 `realtime_table` 전체를 스냅샷
- 주기는 `appsettings.json: "HistoryIntervalSeconds": 60` 에서 읽음
#### 수정 파일
| 파일 | 내용 |
|------|------|
| `ExperionEntities.cs` | `HistoryRecord` 엔티티 추가 (`history_table` 매핑) |
| `IExperionServices.cs` | `IExperionDbService`에 `SnapshotToHistoryAsync` 추가 |
| `ExperionDbContext.cs` | `DbSet<HistoryRecord>`, 테이블 DDL, `SnapshotToHistoryAsync` 구현 |
| `ExperionHistoryService.cs` (신규) | `BackgroundService` — 주기적 `SnapshotToHistoryAsync` 호출 |
| `Program.cs` | `AddHostedService<ExperionHistoryService>()` 등록 |
---
### Task 4 — HistoryTable 웹페이지
#### 개요
- 07번 탭 '이력 조회' 추가
- tagname 드롭다운 최대 8개 선택 (다중 선택으로 열 구성)
- 시작 시간 / 종료 시간 범위 필터
- 결과 테이블: tagname이 열 헤더, recorded_at이 행
#### 수정 파일
| 파일 | 내용 |
|------|------|
| `IExperionServices.cs` | `IExperionDbService`에 `GetTagNamesAsync`, `QueryHistoryAsync` 추가; `HistoryQueryResult` record 추가 |
| `ExperionDbContext.cs` | `GetTagNamesAsync`, `QueryHistoryAsync` 구현 |
| `ExperionControllers.cs` | `ExperionHistoryController` 추가 (GET /api/history/tagnames, GET /api/history/query) |
| `index.html` | 07번 탭 '이력 조회' + `#pane-hist` 섹션 추가 |
| `app.js` | `histLoad()`, `histQuery()`, `histRender()` 구현 |
| `style.css` | 이력 조회 전용 스타일 추가 |
#### 잔여
- **결정 보류**: 현장 재고 데이터 출처 (KB 엑셀 업로드로 즉시 가능, 별도 개발 불필요), 임베딩 모델 BGE-M3 마이그레이션 (위험 대비 임계값 평가 필요)
- 모두 코드 작업 아닌 분석/결정 항목