# HC900 Gateway — 아키텍처 및 구현 계획

## 1. 개요

ExperionCrawler의 OPC UA → Experion HS R530 경로를
**Modbus TCP → HC900** 경로로 대체.

```
Before:
HC900 ──Modbus TCP──▶ Experion R530 ──OPC UA──▶ ExperionCrawler ──▶ PostgreSQL

After:
HC900 ──Modbus TCP──▶ C++ Gateway ──gRPC──▶ HC900Crawler ──▶ PostgreSQL
```

## 2. C++ 게이트웨이 (Modbus TCP → gRPC)

### 설계 원칙
- **단순, 고효율, 경량** (예상 RSS 5~8 MB)
- **Full poll 1초 주기** — 모든 레지스터 읽어서 캐시
- **Scattered read는 안 함** — 어차피 Modbus는 batch가 빠름

### 아키텍처

```
┌─────────────────────────────────────────────┐
│              C++ Gateway                     │
│  ┌──────────┐  ┌──────────┐  ┌────────────┐ │
│  │ Poller    │─▶│ Cache    │◀─│ gRPC Server│ │
│  │ (1s 주기) │  │ (47KB)   │  │            │ │
│  │ 32+3+13   │  │          │  │ ReadTags   │ │
│  │ batch     │  │          │  │ WriteTag   │ │
│  │ reads     │  │          │  │ ListTags   │ │
│  └────┬──────┘  └──────────┘  └─────┬──────┘ │
│       │                             │        │
│       ▼                             ▼        │
│  ┌─────────────────────────────────────────┐ │
│  │     industrial-comm (libcomm_core)      │ │
│  │     ModbusTCP → HC900 @ 192.168.0.240  │ │
│  └─────────────────────────────────────────┘ │
└─────────────────────────────────────────────┘
```

### 폴링 전략
- `read_holding_registers(addr, count=120)` batch
- Loop 1~24: 32 reads (120 regs each)
- Loop 25~32: 32 reads (120 regs each)
- Variable area: 3 reads (0x18C0~, 336 regs)
- Signal area: 13 reads (0x2000~, 1,508 regs)
- **Total: 48 batch reads → ~117 ms full poll**
- 1초 간격 poll, 캐시 갱신

### gRPC Service (`proto/modbus_gateway.proto`)

```protobuf
service ModbusGateway {
  rpc ReadTags(ReadTagsRequest) returns (ReadTagsResponse);     // 캐시 응답
  rpc WriteTag(WriteTagRequest) returns (WriteTagResponse);     // Modbus write
  rpc StreamTags(StreamTagsRequest) returns (stream TagValue);  // 실시간 구독
  rpc ListTags(ListTagsRequest) returns (ListTagsResponse);     // 메타정보
  rpc HealthCheck(HealthCheckRequest) returns (HealthCheckResponse);
}
```

- `ReadTags`: 캐시에서 즉시 응답 (sub-millisecond)
- `WriteTag`: Modbus FC16 직접 write 후 캐시 갱신
- `StreamTags`: 1초 poll 주기에 맞춰 push

### 레지스터 맵 로딩
- 시작 시 `register-map.json` 파일 읽음 (174 KB)
- 또는 `hc900_map_master` DB 테이블에서 읽음

## 3. hc900_map_master (DB 기반 태그 카탈로그)

### 개념
- `node_map_master`와 동일한 패턴
- HC Designer CSV 3종을 DB에 로드
- 태그 prefix 기반 분류 (기존 PidPrefixRule 재활용)

### DDL

```sql
CREATE TABLE hc900_map_master (
    id          SERIAL PRIMARY KEY,
    tag_name    TEXT NOT NULL,       -- 레지스터 맵 태그명 (e.g. 'FICQ3101.PV', 'FIQ6101')
    base_tag    TEXT NOT NULL,       -- 베이스 태그 (e.g. 'FICQ3101', 'FIQ6101')
    attribute   TEXT,                -- 속성 (e.g. 'PV', 'SP', 'QV') — NULL이면 베이스 태그 자체
    addr        INTEGER NOT NULL,    -- Modbus 주소
    count       INTEGER NOT NULL,    -- 레지스터 수 (1 or 2)
    type        TEXT NOT NULL,       -- 'float32' or 'uint16'
    access      TEXT NOT NULL,       -- 'R' or 'RW'
    description TEXT,
    eu          TEXT,
    category    TEXT,                -- PidPrefixRule 기반 분류 ('instrument', 'power_equipment', ...)
    tag_class   TEXT,                -- 'field' or 'system'
    tag_dcs     BOOLEAN,             -- DCS function block 여부
    source      TEXT NOT NULL,       -- 'loop', 'signal', 'variable'
    group_name  TEXT,                -- PointBuilder 그룹 ('Controller1', 'Custom', ...)
    created_at  TIMESTAMPTZ DEFAULT NOW()
);

CREATE INDEX idx_hc900_map_base ON hc900_map_master(base_tag);
CREATE INDEX idx_hc900_map_addr  ON hc900_map_master(addr);
CREATE INDEX idx_hc900_map_group ON hc900_map_master(group_name);
```

### 데이터 출처

| CSV 파일 | source | 건수 | 범위 |
|---|---|---|---|
| SummaryFunctionBlockReport.csv | `loop` | 32 loops × 25 params = 800 | 0x0040~0x7FFF |
| SignalTags.csv | `signal` | 530 | 0x2000~0x25E4 |
| Variables.csv | `variable` | 155 | 0x18C0~0x1A10 |

### Prefix Rules (PidPrefixRule 활용)

| Prefix | Category | 예시 |
|---|---|---|
| FIC, FICA, FICQ | instrument, tag_dcs=true | FICQ3101 (PID Loop) |
| FIT, FIQ, FT | instrument, tag_dcs=false | FIT6101, FIQ6101 (Signal Tag) |
| TI, TIC, TICA | instrument, tag_dcs=true | TICA6111A, TICA3202A |
| LI, LIC, LICA | instrument | LICA6213, LICA5113 |
| PI, PIC, PICA | instrument | PICA6111 |
| XV | instrument | XV3208B_REM |
| VP, P- | power_equipment | VP8117_HS, P-3101B_RUN |

### PointBuilder-like Selection

웹 UI에서 `hc900_map_master`를 대상으로:

| Group | 필터 조건 | 용도 |
|---|---|---|
| Controller1 | prefix=FIC/TIC/PIC/LIC, attribute=PV/SP/OP | 주요 PID 값 |
| Custom | user-defined | QV, TRIP, ESD, HS 등 |

DB 조회 예시:
```sql
-- FICQ-6101 계열 모든 태그
SELECT * FROM hc900_map_master
WHERE base_tag IN (
  SELECT base_tag FROM hc900_map_master
  WHERE base_tag ILIKE 'ficq6101'
);
```

## 4. OPC UA 이름 매핑 (핵심 난제)

### 문제
- DB (Experion OPC UA): `ficq-6101.pv`, `ficq-6101.qv` (lowercase, dash, dot attribute)
- HC Designer CSV: `FICQ3101`, `FIQ6101` (uppercase, no dash, no prefix-dot suffix)
- R530이 중간에서 이름 변환 + 서브 속성 구성하며, **이 매핑 정보는 R530 설정에만 존재**

```
OPC UA (DB)              HC Designer (CSV)       Modbus
────────────────────     ──────────────────      ───────
ficq-6101.pv             FICA6101 (Loop #11)     0x0A40  ← prefix 다름 (FICQ vs FICA)
ficq-6101.qv.value       FIQ6101 (Signal Tag)    0x2006  ← 사용자 정의 규칙 (FIQ=QV)
ficq-6101.sp             FICA6101 (Loop #11)     0x0A44
ficq-3101.pv             FICQ3101 (Loop #1)      0x0040
ficq-3101.qv.value       FIQ3101 (Signal Tag)    0x2164
```

prefix 예: `FICQ`/`FICA`/`FIT`/`FIQ` 모두 숫자부 `6101` 공유 → **prefix는 접근 방식(loop, PV, QV)을 나타내고, 숫자부가 실제 연결고리**

### 매핑 전략: 숫자부 조인 + prefix 검증

`realtime_table`의 OPC UA 이름과 `hc900_map_master`의 HC Designer 이름을 **숫자부(6101) 기준으로 매칭**하고, prefix rules로 검증:

```sql
-- Phase A: 후보 추출 (숫자부 기반 매칭)
WITH rt_base AS (
  SELECT DISTINCT
    split_part(tagname, '.', 1) AS opcua_tag,
    tagname,
    substring(tagname FROM '(\d+)') AS tag_number
  FROM realtime_table
),
hc_base AS (
  SELECT
    tag_name,
    base_tag,
    addr,
    substring(tag_name FROM '(\d+)') AS tag_number
  FROM hc900_map_master
)
SELECT
  r.opcua_tag,
  r.tagname      AS opcua_name,
  h.tag_name     AS hc_name,
  h.addr
FROM rt_base r
JOIN hc_base h ON r.tag_number = h.tag_number
  AND r.opcua_tag ~* h.base_tag  -- base_tag regex 매칭
ORDER BY r.opcua_tag, h.addr;
```

### 결과물: opcua_aliases

```sql
ALTER TABLE hc900_map_master ADD COLUMN opcua_aliases TEXT[];

-- 예시 (자동 생성 후 사용자 검증 필요):
-- FIQ6101       → {"ficq-6101.qv", "ficq-6101.qv.value"}
-- FICQ3101.PV   → {"ficq-3101.pv"}
-- FICA6101-WSP  → {"ficq-6101.wsp"}
```

### 사용자 검증 플로우

```
CSV → hc900_map_master    realtime_table (OPC UA)
         │                       │
         └──── SQL 숫자부 조인 ───┘
                  │
            alias 후보 목록
                  │
            사용자 검증 (Y/N)
                  │
            opcua_aliases 확정
                  │
            C# 앱이 gRPC 호출 시
            aliases로 주소 조회
```

C# 앱에서 gRPC 요청 시:
```csharp
// C# 앱은 DB 이름(ficq-6101.pv)으로 요청
// 게이트웨이는 aliases 매칭으로 레지스터 주소 조회
var resp = client.ReadTags(new[] { "ficq-6101.pv", "ficq-6101.qv" });
```

## 5. 구현 단계

### Phase 1: C++ 게이트웨이 (완성)
- [ ] `industrial-comm`에 gRPC 서버 추가
- [ ] `register-map.json` 로더
- [ ] Poller (full poll 1초)
- [ ] gRPC 서비스 구현 (ReadTags, WriteTag, ListTags, HealthCheck)
- [ ] CMakeLists.txt에 gRPC/Protobuf 종속성 추가
- [ ] systemd unit file

### Phase 2: DB 및 백엔드
- [ ] `hc900_map_master` 테이블 생성 SQL
- [ ] `build_hc900_map.py` CSV → DB 로더 (Python)
- [ ] `scripts/build_register_map.py` → DB 직접 적재
- [ ] Prefix Rules 추가 (FIQ, FIT, FICA 등)
- [ ] PointBuilder-like 웹 UI (기존 ExperionCrawler UI 확장)

### Phase 3: C# HC900Crawler
- [ ] ExperionCrawler 포크 → gRPC Client 추가
- [ ] 기존 OPC UA 계층 대체 (IExperionOpcClient → IModbusGatewayClient)
- [ ] Hc900RealtimeService (캐시 폴링 기반)
- [ ] Write 서비스
- [ ] 기존 DB 스키마 재활용 (realtime_table, history_table, etc.)

### Phase 4: OPC UA 이름 매핑
- [ ] node_map_master 조회로 실제 OPC UA 이름-레지스터 관계 분석
- [ ] opcua_aliases DB 구축
- [ ] 매핑 검증 툴

## 6. 검증된 사실

| 항목 | 상태 |
|---|---|
| HC900 Modbus TCP 연결 | ✅ C70, port 502, IP=192.168.0.240 |
| Float 포맷 | ✅ FP_B (IEEE 754 big-endian) |
| Loop 주소 체계 | ✅ Loop #N = 0x40+(N-1)*0x100 (1~24), 0x7840+(N-25)*0x100 (25~32) |
| batch read 성능 | ✅ 120 regs = 2.4ms, full poll = 117ms |
| C70 최대 연결 | ✅ 10개 |
| R530 사용 연결 | ✅ 1개 (Modbus TCP 채널) |
| 우리 사용 가능 | ✅ 9개, 실제론 1~2개면 충분 |
| Signal Tag FIQ6101 = QV | ✅ `ficq-6101.qv.value` = `FIQ6101` @ 0x2006 |
| 사용자 정의 네이밍 | ✅ FIT=PV, FIQ=QV 등 prefix 기반 규칙 존재 |

## 7. 오픈 이슈

- [ ] **OPC UA ↔ Modbus 주소 매칭 (최대 난제)** — 숫자부 조인으로 후보 추출 후 사용자 검증 필요
- [ ] HC900 Custom Map/User Defined 영역 태그 확인 (현재는 Fixed Map만 커버)
- [ ] Write 시 Modbus FC16 테스트 필요
- [ ] 캐시 무효화 전략 (C#에서 Write 후 gateway cache 갱신)
- [ ] StreamTags 구현 방식 (1초 poll마다 변경분 push vs 전부 push)
