mcp-server warning clear

2026-05-09 04:28:10 +09:00
parent 9b87ad13a0
commit 05e2156843
55 changed files with 1555 additions and 13280 deletions
--- a/plans/enum-metadata-optimize-coding-plan.md
+++ b/plans/enum-metadata-optimize-coding-plan.md
@@ -13,10 +13,13 @@

 - [ ] STEP 1 — 백업: 수정 대상 파일들을 `.rooBackup/`에 백업
 - [ ] STEP 2 — `MetadataLoaderService.cs`: `MetaAttributes` 배열에서 state0~7descriptor 제거
- [ ] STEP 3 — `MetadataLoaderService.cs`: 빌드 검증
+- [ ] STEP 2.5 — `MetadataLoaderService.cs`: 클래스 주석 업데이트
+- [ ] STEP 3 — `MetadataLoaderService.cs` + `ExperionDbContext.cs`: 빌드 검증
 - [ ] STEP 4 — `ExperionDbContext.cs`: `v_tag_summary` 뷰에서 state descriptor JOIN 제거
- [ ] STEP 5 — `ExperionDbContext.cs`: 빌드 검증
+- [ ] STEP 4.5 — `tag_metadata` 고아 데이터 삭제 (선택적)
+- [ ] STEP 5 — `ExperionDbContext.cs` 변경 후 빌드 검증
 - [ ] STEP 6 — `app.js`: pv 값 파싱 헬퍼 함수 `parseEnumPv()` 추가
+- [ ] STEP 6.5 — NL2SQL DB_SCHEMA 동기화 (`server.py` + `nl2sql_worker.py`)
 - [ ] STEP 7 — `app.js`: pv 값 표시 관련 코드 모두 `parseEnumPv()` 적용
 - [ ] STEP 8 — End-to-End 검증: 전체 빌드 + UI 테스트
 - [ ] STEP 9 — git 커밋 및 정리
@@ -27,9 +30,11 @@

 | # | 파일 | 변경 내용 | 영향 범위 |
 |---|------|-----------|-----------|
-| 1 | `src/Infrastructure/OpcUa/MetadataLoaderService.cs` | `MetaAttributes` 배열 수정 | 메타데이터 로딩 |
-| 2 | `src/Infrastructure/Database/ExperionDbContext.cs` | `v_tag_summary` 뷰 단순화 | DB 뷰 |
+| 1 | `src/Infrastructure/OpcUa/MetadataLoaderService.cs` | `MetaAttributes` 배열 수정 + 주석 업데이트 | 메타데이터 로딩 |
+| 2 | `src/Infrastructure/Database/ExperionDbContext.cs` | `v_tag_summary` 뷰 단순화 + 고아 데이터 삭제 | DB 뷰 |
 | 3 | `src/Web/wwwroot/js/app.js` | pv 파싱 헬퍼 + 표시 로직 변경 | 프론트엔드 UI |
+| 4 | `mcp-server/server.py` | DB_SCHEMA에서 state0~2_descriptor 제거 | NL2SQL |
+| 5 | `mcp-server/worker/nl2sql_worker.py` | DB_SCHEMA에서 state0~2_descriptor 제거 | NL2SQL |

 ---

@@ -47,14 +52,17 @@ TIMESTAMP=$(date +%Y%m%d%H%M)
 mkdir -p .rooBackup/enum-opt-$TIMESTAMP/src/Infrastructure/OpcUa
 mkdir -p .rooBackup/enum-opt-$TIMESTAMP/src/Infrastructure/Database
 mkdir -p .rooBackup/enum-opt-$TIMESTAMP/src/Web/wwwroot/js
+mkdir -p .rooBackup/enum-opt-$TIMESTAMP/mcp-server/worker

 cp src/Infrastructure/OpcUa/MetadataLoaderService.cs .rooBackup/enum-opt-$TIMESTAMP/src/Infrastructure/OpcUa/
 cp src/Infrastructure/Database/ExperionDbContext.cs .rooBackup/enum-opt-$TIMESTAMP/src/Infrastructure/Database/
 cp src/Web/wwwroot/js/app.js .rooBackup/enum-opt-$TIMESTAMP/src/Web/wwwroot/js/
+cp mcp-server/server.py .rooBackup/enum-opt-$TIMESTAMP/mcp-server/
+cp mcp-server/worker/nl2sql_worker.py .rooBackup/enum-opt-$TIMESTAMP/mcp-server/worker/
 ```

 **검증 기준**:
- [ ] `.rooBackup/enum-opt-YYYYMMDDHHMM/` 폴더가 생성되고 3개 파일이 복사됨
+- [ ] `.rooBackup/enum-opt-YYYYMMDDHHMM/` 폴더가 생성되고 5개 파일이 복사됨
 - [ ] 원본 파일과 백업 파일의 체크섬이 일치함 (`md5sum` 비교)

 **enum-metadata-optimization.md 규칙 매핑**:
@@ -111,6 +119,7 @@ private static readonly string[] MetaAttributes =
 - `LoadMetadataAsync()` 메서드: `MetaAttributes.Contains(n.Name)`으로 `node_map_master`에서 필터링하므로 state descriptor 노드는 더 이상 조회되지 않음
 - `ReadTagsAsync()`: 8개 menos의 nodeId로 배치 읽기 → 네트워크 트래픽 감소
 - UPSERT 쿼리: 8개 menos의 행 삽입 → DB 부하 감소
+- 클래스 주석 (11줄): `state0~7descriptor` 언급도 함께 제거 필요

 **검증 기준**:
 - [ ] `MetaAttributes` 배열이 `["desc", "area"]` 두 개만 포함
@@ -124,6 +133,37 @@ private static readonly string[] MetaAttributes =

 ---

+### STEP 2.5 — `MetadataLoaderService.cs`: 클래스 주석 업데이트
+
+**파일**: [`MetadataLoaderService.cs`](src/Infrastructure/OpcUa/MetadataLoaderService.cs:11)
+**변경 위치**: 11줄 (클래스 XML 주석)
+
+**변경 전 코드** (11줄):
+```csharp
+/// 메타데이터(desc, area, state0~7descriptor)를 OPC UA에서 읽어서 tag_metadata 테이블에 저장/갱신
+```
+
+**변경 후 코드**:
+```csharp
+/// 메타데이터(desc, area)를 OPC UA에서 읽어서 tag_metadata 테이블에 저장/갱신
+```
+
+**diff**:
+```diff
+-/// 메타데이터(desc, area, state0~7descriptor)를 OPC UA에서 읽어서 tag_metadata 테이블에 저장/갱신
+/// 메타데이터(desc, area)를 OPC UA에서 읽어서 tag_metadata 테이블에 저장/갱신
+```
+
+**변경 이유**:
+- STEP 2에서 `state0~7descriptor`를 제거했는데 주석에는 여전히 남아 있음
+- 주석과 코드 불일치로 인한 혼란 방지
+
+**검증 기준**:
+- [ ] 주석이 `desc, area`만 언급함
+- [ ] 컴파일 오류 없음 (주석 변경이므로 영향 없음)
+
+---
+
 ### STEP 3 — `MetadataLoaderService.cs` 변경 후 빌드 검증

 **목적**: STEP 2 변경이 컴파일 오류 없이 통과하는지 확인
@@ -226,6 +266,40 @@ dotnet build src/Web/ExperionCrawler.csproj --no-restore -v q

 ---

+### STEP 4.5 — `tag_metadata` 고아 데이터 삭제 (선택적)
+
+**파일**: [`ExperionDbContext.cs`](src/Infrastructure/Database/ExperionDbContext.cs:185)
+**변경 위치**: `InitializeAsync()` 메서드 내 `v_tag_summary` 뷰 생성 직후 (330줄 이후)
+
+**추가할 코드**:
+```csharp
+// state descriptor 고아 데이터 정리 (state0~7descriptor는 더 이상 로딩하지 않음)
+await _ctx.Database.ExecuteSqlRawAsync("""
+    DELETE FROM tag_metadata WHERE attribute IN (
+        'state0descriptor', 'state1descriptor', 'state2descriptor',
+        'state3descriptor', 'state4descriptor', 'state5descriptor',
+        'state6descriptor', 'state7descriptor'
+    )
+    """);
+```
+
+**삽입 위치 상세**:
+- 330줄 (`""");` — v_tag_summary 뷰 생성 종료) 바로 다음에 삽입
+- `CREATE EXTENSION IF NOT EXISTS timescaledb` 이전
+
+**변경 이유**:
+- `MetaAttributes`에서 state descriptor가 제거되면 더 이상 갱신되지 않으나, 기존 데이터는 영구히 남음
+- 테이블 크기와 불필요한 JOIN 결과 방지
+
+**검증 기준**:
+- [ ] 실행 시 기존 state descriptor 행이 삭제됨
+- [ ] `SELECT COUNT(*) FROM tag_metadata WHERE attribute LIKE 'state%descriptor'` → 0 반환
+- [ ] desc/area 행은 영향 없음
+
+**참고**: 기존 데이터를 보존해야 한다면 이 스텝을 스킵 가능. 하지만 `v_tag_summary` 뷰에서 해당 컬럼이 제거되었으므로 조회 자체가 불가능해짐.
+
+---
+
 ### STEP 5 — `ExperionDbContext.cs` 변경 후 빌드 검증

 **목적**: STEP 4 변경이 컴파일 오류 없이 통과하는지 확인
@@ -297,6 +371,84 @@ function parseEnumPv(v) {

 ---

+### STEP 6.5 — NL2SQL DB_SCHEMA 동기화 (`server.py` + `nl2sql_worker.py`)
+
+**파일**: [`mcp-server/server.py`](mcp-server/server.py:447) / [`mcp-server/worker/nl2sql_worker.py`](mcp-server/worker/nl2sql_worker.py:78)
+**변경 위치**: 두 파일의 `DB_SCHEMA` 문자열 내 `tag_metadata` / `v_tag_summary` 설명 부분
+
+**변경 전 코드** (`server.py:447` + `462-464` + `470` + `474-475`):
+```
+  attribute   TEXT         - 속성명 ('desc', 'area', 'state0descriptor', ...)
+  ...
+  state0_descriptor TEXT   - 비트 0 의미 (예: "Run/Stop")
+  state1_descriptor TEXT   - 비트 1 의미 (예: "Remote/Local")
+  state2_descriptor TEXT   - 비트 2 의미 (예: "Trip/Normal")
+  ...
+  - 메타데이터: desc (String), area (Enum), state0descriptor~7 (String)
+  ...
+  - state0descriptor~7은 해당 비트의 의미 설명
+  - instate0=true이고 state0descriptor="Run/Stop"이면 → "Run" 상태
+```
+
+**변경 후 코드**:
+```
+  attribute   TEXT         - 속성명 ('desc', 'area')
+  ...
+  description       TEXT   - 장비 설명 (tag_metadata.desc)
+  area              TEXT   - 소속 플랜트 (tag_metadata.area)
+  ...
+  - 메타데이터: desc (String), area (Enum)
+  ...
+  - pv 값이 EnumValueType 형식인 경우 `{코드 | DisplayName | }`에서 DisplayName으로 상태 확인 가능
+  - v_tag_summary 뷰를 사용하면 실시간값+메타데이터 한 번에 조회 가능
+```
+
+**diff** (`server.py` 기준, `nl2sql_worker.py`는 동일):
+```diff
+-  attribute   TEXT         - 속성명 ('desc', 'area', 'state0descriptor', ...)
+  attribute   TEXT         - 속성명 ('desc', 'area')
+   value       TEXT         - 메타데이터 값
+   node_id     TEXT         - OPC UA 노드 ID
+   loaded_at   TIMESTAMPTZ  - 마지막 로드 시각
+
+   뷰: v_tag_summary  (실시간값 + 메타데이터 통합 뷰)
+   ...
+   description       TEXT   - 장비 설명 (tag_metadata.desc)
+   area              TEXT   - 소속 플랜트 (tag_metadata.area)
+-  state0_descriptor TEXT   - 비트 0 의미 (예: "Run/Stop")
+-  state1_descriptor TEXT   - 비트 1 의미 (예: "Remote/Local")
+-  state2_descriptor TEXT   - 비트 2 의미 (예: "Trip/Normal")
+
+   새로운 태그 타입:
+   - 아날로그: ficq-6101.pv/sp/op (Double)
+   - 디지털 XV: xv-6124.pv/op (Int32), xv-6124.instate0~7 (Boolean)
+   - Pump: p-6102.pv/op (Int32), p-6102.instate0~7 (Boolean)
+-  - 메타데이터: desc (String), area (Enum), state0descriptor~7 (String)
+  - 메타데이터: desc (String), area (Enum)
+
+   BCD 상태 조회 팁:
+   - instate0~7은 Boolean (true/false)
+-  - state0descriptor~7은 해당 비트의 의미 설명
+-  - instate0=true이고 state0descriptor="Run/Stop"이면 → "Run" 상태
+  - pv 값이 EnumValueType 형식인 경우 `{코드 | DisplayName | }`에서 DisplayName으로 상태 확인 가능
+   - v_tag_summary 뷰를 사용하면 실시간값+메타데이터 한 번에 조회 가능
+```
+
+**변경 이유**:
+- `v_tag_summary` 뷰에서 `state0~2_descriptor` 컬럼이 제거되면 LLM이 해당 컬럼을 SELECT하는 SQL을 생성하면 실패함
+- DB_SCHEMA는 LLM의 시스템 프롬프트로 사용되므로 실제 DB 스키마와 반드시 일치해야 함
+
+**검증 기준**:
+- [ ] `server.py` DB_SCHEMA에서 `state0_descriptor` / `state1_descriptor` / `state2_descriptor` 언급 없음
+- [ ] `nl2sql_worker.py` DB_SCHEMA에서 동일하게 제거됨
+- [ ] `attribute` 설명이 `'desc', 'area'`만 포함
+- [ ] MCP 서버 재시작 후 NL2SQL 쿼리가 정상 동작 (state descriptor 없이)
+
+**enum-metadata-optimization.md 규칙 매핑**:
+- 섹션 3.1: pv 값이 EnumValueType 형식인 경우 DisplayName 파싱으로 상태 확인
+
+---
+
 ### STEP 7 — `app.js`: pv 값 표시 관련 코드 모두 `parseEnumPv()` 적용

 **파일**: [`app.js`](src/Web/wwwroot/js/app.js:633)
@@ -361,9 +513,15 @@ dotnet run --project src/Web/ExperionCrawler.csproj
 #### 백엔드 검증
 - [ ] 애플리케이션 시작 시 DB 초기화 성공
 - [ ] `v_tag_summary` 뷰 생성 성공 (state descriptor JOIN 없음)
+- [ ] `tag_metadata` 고아 데이터 삭제 성공 (STEP 4.5)
 - [ ] 메타데이터 로드 시 `desc`, `area`만 조회됨 (로그 확인)
 - [ ] `tag_metadata` 테이블에 state0~7descriptor 행 없음

+#### NL2SQL 검증
+- [ ] MCP 서버 재시작 성공
+- [ ] "xv-6124 상태 알려줘" 쿼리가 state descriptor 없이 정상 동작
+- [ ] 생성된 SQL에서 `state0_descriptor` 컬럼 없음
+
 #### 프론트엔드 검증
 - [ ] 브라우저 콘솔 JS 오류 없음
 - [ ] 포인트빌더 테이블에서 digital 태그 pv 값이 DisplayName만 표시됨
@@ -391,17 +549,21 @@ dotnet run --project src/Web/ExperionCrawler.csproj
 ```bash
 # 1. MetadataLoaderService.cs 커밋
 git add src/Infrastructure/OpcUa/MetadataLoaderService.cs
-git commit -m "feat: MetaAttributes에서 state0~7descriptor 제거 (pv 값 파싱으로 대체)"
+git commit -m "feat: MetaAttributes에서 state0~7descriptor 제거, 주석 동시 업데이트"

 # 2. ExperionDbContext.cs 커밋
 git add src/Infrastructure/Database/ExperionDbContext.cs
-git commit -m "feat: v_tag_summary 뷰에서 state descriptor JOIN 제거"
+git commit -m "feat: v_tag_summary 뷰에서 state descriptor JOIN 제거, 고아 데이터 DELETE 추가"

 # 3. app.js 커밋
 git add src/Web/wwwroot/js/app.js
 git commit -m "feat: pv 값 파싱 헬퍼 parseEnumPv() 추가, 포인트빌더 테이블 적용"

-# 4. 계획 문서 커밋
+# 4. NL2SQL DB_SCHEMA 커밋
+git add mcp-server/server.py mcp-server/worker/nl2sql_worker.py
+git commit -m "feat: NL2SQL DB_SCHEMA에서 state0~2_descriptor 제거 (v_tag_summary 변경 반영)"
+
+# 5. 계획 문서 커밋
 git add plans/enum-metadata-optimize-coding-plan.md
 git commit -m "docs: enum metadata 최적화 코딩 계획 작성"
 ```
@@ -422,6 +584,8 @@ TIMESTAMP=$(ls -d .rooBackup/enum-opt-* | tail -1 | xargs basename)
 cp .rooBackup/$TIMESTAMP/src/Infrastructure/OpcUa/MetadataLoaderService.cs src/Infrastructure/OpcUa/
 cp .rooBackup/$TIMESTAMP/src/Infrastructure/Database/ExperionDbContext.cs src/Infrastructure/Database/
 cp .rooBackup/$TIMESTAMP/src/Web/wwwroot/js/app.js src/Web/wwwroot/js/
+cp .rooBackup/$TIMESTAMP/mcp-server/server.py mcp-server/
+cp .rooBackup/$TIMESTAMP/mcp-server/worker/nl2sql_worker.py mcp-server/worker/
 ```

 ---
@@ -432,12 +596,15 @@ cp .rooBackup/$TIMESTAMP/src/Web/wwwroot/js/app.js src/Web/wwwroot/js/

 | STEP | 파일 | 핵심 검증 항목 |
 |------|------|----------------|
-| 1 | — | 백업 파일 3개 생성됨 |
+| 1 | — | 백업 파일 5개 생성됨 |
 | 2 | MetadataLoaderService.cs | `MetaAttributes` = `["desc", "area"]` |
+| 2.5 | MetadataLoaderService.cs | 클래스 주석 업데이트 |
 | 3 | — | 빌드 성공 |
 | 4 | ExperionDbContext.cs | state descriptor JOIN 3개 제거됨 |
+| 4.5 | ExperionDbContext.cs | 고아 데이터 DELETE 쿼리 추가 |
 | 5 | — | 빌드 성공 |
 | 6 | app.js | `parseEnumPv()` 함수 추가됨 |
+| 6.5 | server.py + nl2sql_worker.py | DB_SCHEMA에서 state descriptor 제거 |
 | 7 | app.js | `pbRender()`에서 `parseEnumPv()` 적용됨 |
-| 8 | 전체 | End-to-End 테스트 통과 |
+| 8 | 전체 | End-to-End + NL2SQL 테스트 통과 |
 | 9 | — | git 커밋 완료 |