> For the complete documentation index, see [llms.txt](https://kopens.gitbook.io/plantpulse-platform/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kopens.gitbook.io/plantpulse-platform/developer/id-naming-convention.md).

# 도메인 ID 네이밍 컨벤션

PlantPulse 플랫폼은 모든 마스터 데이터 ID에 **서버측 정규식 검증**을 강제합니다. 위반 시 `create()` / `update()` 호출이 거부되며, 응답 envelope에 `_code=E1002` (VALIDATION\_FAILED) 가 반환됩니다.

## 핵심 규칙

1. **도메인 프리픽스로 시작** — 각 도메인은 고유 접두사로 시작해야 합니다 (`SITE_`, `OPC_`, `ASSET_`, `TAG_`, …).
2. **허용 문자: `[A-Z0-9_]`** — 영문 **대문자**(A–Z), 숫자(0–9), 언더스코어(`_`)만 사용 가능합니다.
3. **소문자·한글·공백·특수문자 금지** — 모두 검증 실패 사유입니다.

```
✅ 허용 문자 집합: [A-Z0-9_]
❌ 금지: 소문자, 한글, 공백, 하이픈(-), 점(.), 콜론(:), 슬래시(/), 기타 특수문자
```

## 도메인별 정규식 (서버 검증 기준)

서버 Validator가 적용하는 **정확한 정규식**입니다. 이 패턴에 맞지 않으면 모두 `E1002`로 거부됩니다.

| 도메인                  | Regex                            | 설명                                          | 예시                                       |
| -------------------- | -------------------------------- | ------------------------------------------- | ---------------------------------------- |
| `site_id`            | `^V?SITE_[A-Z0-9_]+$`            | `SITE_` 또는 `VSITE_` (Virtual Site) 시작       | `SITE_DJ`, `VSITE_TEST01`                |
| `opc_id`             | `^(OPC\|EDGE\|TEST)_[A-Z0-9_]+$` | `OPC_`, `EDGE_`, `TEST_` 중 하나               | `OPC_00303`, `EDGE_GW01`, `TEST_VIRTUAL` |
| `asset_id`           | `^ASSET_[A-Z0-9_]+$`             | `ASSET_` 시작                                 | `ASSET_DJ_L_0001`                        |
| `tag_id`             | `^V*TAG_[A-Z0-9_]+$`             | `TAG_`, `VTAG_`, `VVTAG_` … (Virtual 레벨 다중) | `TAG_EDGE_00303_90007`, `VTAG_CALC_01`   |
| `alarm_config_id`    | `^ALARM_CONFIG_[A-Z0-9_]+$`      | `ALARM_CONFIG_` 시작                          | `ALARM_CONFIG_HIGH_TEMP_01`              |
| `edge_id`            | `^(EDGE\|OPC)_[A-Z0-9_]+$`       | `EDGE_` 또는 `OPC_` 시작                        | `EDGE_GW01`, `OPC_00303`                 |
| `emp_id`             | `^EMP_[A-Z0-9_]+$`               | `EMP_` 시작                                   | `EMP_E12345`                             |
| `customer_id`        | `^CUSTOMER_[A-Z0-9_]+$`          | `CUSTOMER_` 시작                              | `CUSTOMER_001`                           |
| `product_id`         | `^PRODUCT_[A-Z0-9_]+$`           | `PRODUCT_` 시작                               | `PRODUCT_A001`                           |
| `flow_id`            | `^FLOW_[A-Z0-9_]+$`              | `FLOW_` 시작                                  | `FLOW_OEE_DAILY`                         |
| `user_login.user_id` | `^[A-Z][A-Z0-9_]*$`              | 대문자로 시작, 이후 `[A-Z0-9_]`                     | `ADMIN`, `OPERATOR_01`                   |

> ⚠️ **주의**: `customer_id`는 `CUSTOMER_` (전체 단어), `product_id`는 `PRODUCT_` (전체 단어)입니다. 짧은 `CUST_`, `PROD_`는 거부됩니다.
>
> ⚠️ **OPC vs Edge**: `opc_id`는 `OPC|EDGE|TEST` 셋 다 허용, `edge_id`는 `EDGE|OPC` 둘만 허용합니다. `TEST_` 접두사는 OPC에서만 사용 가능합니다.

## 가상(Virtual) ID 접두사

| 패턴         | 의미                                             | 예시                          |
| ---------- | ---------------------------------------------- | --------------------------- |
| `V` (Site) | Virtual Site — 물리 사이트 없이 생성하는 가상 사이트 (테스트·집계용) | `VSITE_AGG_01`              |
| `V*` (Tag) | Virtual Tag — 계산식·집계 태그. `V`가 누적될수록 파생 단계가 깊음  | `VTAG_SUM`, `VVTAG_DERIVED` |

## 권장 형식 (운영 모범 사례)

서버 정규식은 패턴만 강제하지만, 운영 일관성을 위해 다음 형식을 권장합니다.

| 도메인               | 권장 형식                    | 예시                          |
| ----------------- | ------------------------ | --------------------------- |
| Site              | `SITE_<사이트토큰>`           | `SITE_DJ` (대전공장)            |
| OPC               | `OPC_<유형>_<번호5자리>`       | `OPC_EDGE_00303`            |
| Edge              | `EDGE_<위치>_<번호>`         | `EDGE_LINE1_01`             |
| Asset (Area)      | `ASSET_<사이트>_A_<번호4자리>`  | `ASSET_DJ_A_0001`           |
| Asset (Line)      | `ASSET_<사이트>_L_<번호4자리>`  | `ASSET_DJ_L_0001`           |
| Asset (Equipment) | `ASSET_<사이트>_M_<번호4자리>`  | `ASSET_DJ_M_0001`           |
| Tag               | `TAG_<OPC식별>_<채널>`       | `TAG_EDGE_00303_90007`      |
| Virtual Tag       | `VTAG_<용도>_<번호>`         | `VTAG_OEE_LINE1`            |
| Alarm Config      | `ALARM_CONFIG_<지표>_<번호>` | `ALARM_CONFIG_TEMP_HIGH_01` |
| Employee          | `EMP_<사번>`               | `EMP_E12345`                |
| Customer          | `CUSTOMER_<번호>`          | `CUSTOMER_001`              |
| Product           | `PRODUCT_<SKU>`          | `PRODUCT_A001`              |
| Flow              | `FLOW_<용도>_<주기>`         | `FLOW_OEE_DAILY`            |

> 💡 **Asset 타입 코드**: Area=`A`, Line=`L`, Equipment(Machine)=`M`. Equipment 코드 `M`은 Machine 약어로, 검색·필터링에서 짧은 한 글자 코드를 사용합니다.

## 잘못된 예시 (모두 `E1002` 거부)

```
❌ site_00001            → 소문자 사용
❌ DJ_FACTORY            → SITE_ 접두사 누락
❌ API_ERP_001           → OPC는 OPC|EDGE|TEST만 허용 (API_ 불가)
❌ CUST_001              → customer_id 는 CUSTOMER_ 가 전체 접두사
❌ PROD_A001             → product_id 는 PRODUCT_ 가 전체 접두사
❌ ASSET-DJ-L-0001       → 하이픈 사용
❌ ASSET_라인1           → 한글 사용
❌ OPC 001               → 공백 사용
❌ TAG.EDGE.001          → 점(.) 사용
❌ Tag_Edge_001          → 소문자 혼용
❌ TEST_EDGE_001 (edge)  → edge_id 는 EDGE|OPC 만 허용 (TEST_ 불가)
```

## 검증이 강제되지 않는 도메인

다음 도메인은 위 표에 없으므로 서버측 강제 검증이 없습니다. 단, 운영 일관성을 위해 권장 접두사를 따르시는 것을 권장합니다.

| 도메인           | 권장 접두사 | 예시                  |
| ------------- | ------ | ------------------- |
| Calendar (일정) | `CAL_` | `CAL_20260514_0001` |
| Order (작업지시)  | `ORD_` | `ORD_20260514_001`  |

## 설계 모범 사례

1. **불변성 유지** — 한번 부여한 ID는 변경하지 마세요. 시계열 데이터·외부 시스템 정합성과 직결됩니다. 변경이 필요하면 새 ID로 마이그레이션하는 것을 권장합니다.
2. **고정 자릿수 사용** — 번호 부분은 `0001`, `00001` 처럼 0 패딩으로 자릿수를 통일해야 사전순 정렬이 보장됩니다.
3. **계층을 ID에 표현** — `ASSET_<사이트>_<타입>_<번호>` 형태로 트리 구조를 ID 자체에서 읽을 수 있게 설계합니다.
4. **의미를 ID에 박지 마세요** — `ASSET_DJ_L_OLD_BROKEN_LINE` 처럼 상태·이력 정보를 ID에 넣으면 변경 불가능한 흔적이 남습니다. 그런 정보는 `*_name`, `description`, 메타데이터로 분리합니다.
5. **외부 시스템 ID는 별도 필드** — ERP/MES 원본 ID는 `external_*_id` 필드에 보관하고, PlantPulse 내부 ID 체계는 자체적으로 유지합니다.
6. **표시 이름과 분리** — 사용자에게 보이는 이름은 `*_name` 또는 `alias_name`을 사용하고, `*_id`는 시스템 내부 키로만 취급합니다.

## 검증 실패 응답 예시

```json
{
  "_status": "ERROR",
  "_code": "E1002",
  "_message": "validation failed: site_id must match ^V?SITE_[A-Z0-9_]+$",
  "_http_status": 400
}
```

V5 클라이언트에서 `debug=true`로 생성하면 응답 envelope가 로그에 출력됩니다.

```java
client = new APIClient_V5(proto, host, port, user, token, true);  // debug=true
```

## 더 자세한 정보

* 도메인별 코드 예시: [API 사용 매뉴얼 - 도메인 ID 규칙](/plantpulse-platform/developer/api-manual/id-rules.md)
* 에러 코드 매핑: [응답 형식 및 에러 처리](/plantpulse-platform/developer/api-manual/error-handling.md)
* 자산 트리 구축: [Asset 서비스](/plantpulse-platform/developer/api-manual/asset-service.md)