2. 域 ID 规则

PlantPulse 的所有主数据均遵循服务端正则校验。域 Validator(SiteValidator、OPCValidator、AssetValidator、TagValidator 等)会强制执行正则匹配,一旦违反,create() / update() 调用将返回 null,且响应 envelope 中会包含 _code=E1002 (VALIDATION_FAILED)。准确的 ID 设计是构建可扩展 IoT 系统的起点。

📖 平台整体约定的摘要请参阅“域 ID 命名约定”页面。

2.1 一览式 ID 规则(以服务端正则为准)

域	Regex	推荐模式	示例
Site	^V?SITE_[A-Z0-9_]+$	SITE_<token>(或 VSITE_… Virtual)	SITE_DJ, VSITE_AGG_01
OPC	^(OPC|EDGE|TEST)_[A-Z0-9_]+$	OPC_<type>_<number> / EDGE_<location>_<number>	OPC_00303, EDGE_GW01, TEST_VIRTUAL
Edge	^(EDGE|OPC)_[A-Z0-9_]+$	EDGE_<location>_<number>	EDGE_LINE1_01
Asset(Area/Line/Equipment)	^ASSET_[A-Z0-9_]+$	ASSET_<site>_<type>_<number>	ASSET_DJ_L_0001
Tag	^V*TAG_[A-Z0-9_]+$	TAG_<OPC>_<number>(或 VTAG_ 虚拟标签)	TAG_EDGE_00303_90007, VTAG_OEE_LINE1
AlarmConfig	^ALARM_CONFIG_[A-Z0-9_]+$	ALARM_CONFIG_<metric>_<number>	ALARM_CONFIG_TEMP_HIGH_01
Employee	^EMP_[A-Z0-9_]+$	EMP_<employee-no>	EMP_E12345
Customer	^CUSTOMER_[A-Z0-9_]+$	CUSTOMER_<number>	CUSTOMER_001
Product	^PRODUCT_[A-Z0-9_]+$	PRODUCT_<SKU>	PRODUCT_A001
Flow	^FLOW_[A-Z0-9_]+$	FLOW_<purpose>_<interval>	FLOW_OEE_DAILY
User (login)	^[A-Z][A-Z0-9_]*$	以大写字母开头,[A-Z0-9_]	ADMIN, OPERATOR_01
Calendar	(自由)	CAL_<YYYYMMDD>_<seq>	CAL_20260514_0001
Order	(自由)	ORD_<YYYYMMDD>_<seq>	ORD_20260514_001

⚠️ 强制校验:上表中标注了正则的所有域均由服务端校验。违反时 V5 返回 null,并在响应中包含 _code=E1002、_message="site_id must match ^V?SITE_[A-Z0-9_]+$" 等。

⚠️ Customer/Product 使用完整单词:CUSTOMER_、PRODUCT_ 才是正确的前缀。较短的 CUST_、PROD_ 会被拒绝。

⚠️ OPC 中不可使用 API_ 前缀:即便是外部 API 通道,opc_id 也必须以 OPC_ / EDGE_ / TEST_ 之一开头。

2.2 Site ID

정규식: ^V?SITE_[A-Z0-9_]+$
허용: SITE_… 또는 VSITE_… (Virtual Site — 물리 사이트 없이 만드는 가상/집계용 사이트)

示例

import plantpulse.api.v5.dto.request.SiteRequestV5;
import plantpulse.api.v5.dto.response.SiteResponseV5;

SiteRequestV5 req = new SiteRequestV5();
req.setSite_id("SITE_DJ");                 // 대전공장
req.setSite_name("대전 1공장");
req.setLat("36.3504");
req.setLng("127.3845");

SiteResponseV5 created = client.site().create(req);
if (created == null) {
    System.err.println("등록 실패 — site_id 정규식 확인 필요");
}

// Virtual Site (테스트·집계용)
SiteRequestV5 vsite = new SiteRequestV5();
vsite.setSite_id("VSITE_AGG_01");
vsite.setSite_name("집계 가상 사이트");
client.site().create(vsite);

❌ 错误示例(在 V5 中均返回 null)

req.setSite_id("DJ_FACTORY");    // ❌ SITE_ 누락 → E1002
req.setSite_id("site_00001");    // ❌ 소문자 → E1002
req.setSite_id("00001");         // ❌ 접두사 없음 → E1002
req.setSite_id("VVSITE_01");     // ❌ V는 0 또는 1개만 (V?)

2.3 OPC ID

정규식: ^(OPC|EDGE|TEST)_[A-Z0-9_]+$
허용: OPC_…  / EDGE_…  / TEST_…

OPC ID 表示数据采集的物理与逻辑来源。在同一 OPC 类型内需要进一步区分含义时,使用 _ 表达层级。

各 OPC Type 的推荐模式

OPC Type	用途	推荐 ID 前缀
OPC	OPC UA / OPC DA 服务器	OPC_<ua-server-name>_<number>
PLC	Siemens、Mitsubishi、Allen-Bradley 等	OPC_PLC_<line>_<number>
MODBUS	Modbus TCP/RTU 设备	OPC_MB_<equipment>_<number>
DATABASE	外部 RDBMS 轮询	OPC_DB_<system>
FILE	REST API/文件导入	OPC_FILE_<system>_<number>
VIRTUAL	测试与仿真	TEST_VIRTUAL_<number>
Edge Gateway	边缘网关(单独使用 edge_id)	EDGE_<location>_<number>

⚠️ 早期文档曾提到 API_ 前缀,但当前服务端校验仅允许 OPC_/EDGE_/TEST_。即使是外部 API/文件通道,在 OPC 域中也请使用 OPC_FILE_… 形式。

示例

import plantpulse.api.v5.dto.request.OPCRequestV5;

OPCRequestV5 req = new OPCRequestV5();
req.setOpc_id("OPC_EDGE_00303");
req.setOpc_name("Line1 Edge Gateway");
req.setOpc_type("PLC");                    // OPC/PLC/MODBUS/DATABASE/FILE/VIRTUAL
req.setOpc_sub_type("SIEMENS_S7");
req.setSite_id("SITE_DJ");
req.setOpc_server_ip("192.168.10.50");
req.setOpc_agent_ip("192.168.10.5");
req.setOpc_agent_port(60000);
client.opc().create(req);

// ERP 연동 — OPC_FILE_ 접두사 (API_ 아님!)
OPCRequestV5 fileChannel = new OPCRequestV5();
fileChannel.setOpc_id("OPC_FILE_ERP_001");
fileChannel.setOpc_type("FILE");
fileChannel.setSite_id("SITE_DJ");
client.opc().create(fileChannel);

// 테스트·시뮬레이션
OPCRequestV5 testOpc = new OPCRequestV5();
testOpc.setOpc_id("TEST_VIRTUAL_001");
testOpc.setOpc_type("VIRTUAL");
testOpc.setSite_id("SITE_DJ");
client.opc().create(testOpc);

2.4 Edge ID

정규식: ^(EDGE|OPC)_[A-Z0-9_]+$

edge_id 是边缘网关设备的标识符。其正则与 OPC 几乎相同,但不允许使用 TEST_ 前缀。

req.setEdge_id("EDGE_LINE1_01");
req.setEdge_id("OPC_EDGE_00303");   // OPC도 가능
// req.setEdge_id("TEST_EDGE_01");  // ❌ edge_id는 TEST_ 불가

2.5 Asset ID — 层级结构的核心

Asset 构成 Area → Line → Equipment 三层树形结构。建议在 ID 中包含类型代码,以便直观识别层级。

정규식: ^ASSET_[A-Z0-9_]+$
권장 형식: ASSET_<site-token>_<type-code>_<number>

Asset Type 代码

asset_type 值	含义	推荐 ID 模式
A	Area(区域)	ASSET_<site>_A_<number>
L	Line(产线)	ASSET_<site>_L_<number>
M	Equipment(设备,Machine)	ASSET_<site>_M_<number>

💡 EQUIPMENT 代码为 M 的原因:Equipment = Machine。在检索与筛选中使用简短明确的单字母代码。

标准 ID 模式示例

大田工厂(SITE_DJ)的 1 号区域、其中的 2 号产线,以及其上的 3 号设备:

ASSET_DJ_A_0001     ← Area (1구역)
  └ ASSET_DJ_L_0002 ← Line (2번 라인)
      └ ASSET_DJ_M_0003 ← Equipment (3번 설비)

示例 — 创建资产树

import plantpulse.api.v5.dto.request.AssetRequestV5;
import plantpulse.api.v5.dto.response.AssetResponseV5;

// 1) 사이트 직속 Area
AssetRequestV5 area = new AssetRequestV5();
area.setSite_id("SITE_DJ");
area.setParent_asset_id("SITE_DJ");        // 부모는 사이트 ID
area.setAsset_id("ASSET_DJ_A_0001");
area.setAsset_name("조립구역");
area.setAsset_type("A");
client.asset().create(area);

// 2) Area 산하 Line
AssetRequestV5 line = new AssetRequestV5();
line.setSite_id("SITE_DJ");
line.setParent_asset_id("ASSET_DJ_A_0001");  // 부모는 Area
line.setAsset_id("ASSET_DJ_L_0001");
line.setAsset_name("1라인");
line.setAsset_type("L");
client.asset().create(line);

// 3) Line 산하 Equipment
AssetRequestV5 equip = new AssetRequestV5();
equip.setSite_id("SITE_DJ");
equip.setParent_asset_id("ASSET_DJ_L_0001"); // 부모는 Line
equip.setAsset_id("ASSET_DJ_M_0001");
equip.setAsset_name("CNC #1");
equip.setAsset_type("M");
equip.setTable_type("CNC");
client.asset().create(equip);

parent_asset_id 规则

子级类型	parent_asset_id 值
Area(A)	站点 ID(例:SITE_DJ)
Line(L)	Area 的 asset_id(例:ASSET_DJ_A_0001)
Equipment(M)	Line 的 asset_id(例:ASSET_DJ_L_0001)

Equipment 之下还可以再设置下级 Equipment(子装配)。此时 parent_asset_id 为上级 Equipment 的 asset_id。

2.6 Tag ID

정규식: ^V*TAG_[A-Z0-9_]+$
허용: TAG_…, VTAG_…, VVTAG_… (V 누적 가능 — Virtual Tag 파생 단계)

Tag 是数据点(传感器值、计数器、状态等)的定义。与 OPC 为 1:1 关系,与 Asset 为 0:N(可选连接)关系。

推荐模式

场景	模式	示例
OPC 连接标签	TAG_<part-of-opc-id>_<channel-no>	TAG_EDGE_00303_90007
自定义标签	TAG_<domain>_<number>	TAG_PROD_COUNT_001
Virtual Tag(第 1 级)	VTAG_<purpose>_<number>	VTAG_OEE_LINE1
Virtual Tag(第 2 级派生)	VVTAG_<purpose>_<number>	VVTAG_AGGREGATED_01

💡 Virtual Tag 的 V 叠加:计算公式与聚合标签的派生层级越深,就追加越多 V。通常 VTAG_ 一级即可满足需求。

示例

import plantpulse.api.v5.dto.request.TagRequestV5;

TagRequestV5 req = new TagRequestV5();
req.setTag_id("TAG_EDGE_00303_90007");
req.setTag_name("Spindle RPM");
req.setOpc_id("OPC_EDGE_00303");
req.setSite_id("SITE_DJ");
req.setLinked_asset_id("ASSET_DJ_M_0001");
req.setJava_type("Double");
req.setUnit("RPM");
req.setTag_source("OPC");
req.setDescription("Spindle 회전수 (RPM)");
client.tag().create(req);

// Virtual Tag — 라인별 OEE 집계
TagRequestV5 vtag = new TagRequestV5();
vtag.setTag_id("VTAG_OEE_LINE1");
vtag.setTag_name("Line1 OEE");
vtag.setSite_id("SITE_DJ");
vtag.setTag_source("VIRTUAL");
client.tag().create(vtag);

tag_id vs tag_name vs alias_name

字段	在 V5 中是否可更改	用途
tag_id	不可更改(建议重新创建)	系统内部唯一键。不可变
tag_name	update() 或 patchBasic()	面向用户显示的名称
alias_name	patchMetadata()	与外部系统映射的别名(例:HMI 标签名)

建议尽可能将 tag_id 保持不可变,显示名称使用 tag_name / alias_name。更改 tag_id 可能导致与外部时序数据的一致性问题。

2.7 AlarmConfig / Employee / Customer / Product / Flow

这些域同样强制执行服务端校验。请使用准确的完整前缀。

// Alarm Config
AlarmConfigRequestV5 alarm = new AlarmConfigRequestV5();
alarm.setAlarm_config_id("ALARM_CONFIG_TEMP_HIGH_01");
alarm.setSite_id("SITE_DJ");

// Employee
EmployeeRequestV5 emp = new EmployeeRequestV5();
emp.setEmployee_id("EMP_E12345");
emp.setRole_code("OPERATOR");                // OPERATOR, SUPERVISOR 등

// Customer — CUSTOMER_ (전체 단어, CUST_ 아님!)
CustomerRequestV5 cust = new CustomerRequestV5();
cust.setCustomer_id("CUSTOMER_001");
cust.setExternal_customer_id("ERP_C001");

// Product — PRODUCT_ (전체 단어, PROD_ 아님!)
ProductRequestV5 prod = new ProductRequestV5();
prod.setProduct_id("PRODUCT_A001");
prod.setProduct_code("SKU-A001");

// Flow
FlowRequestV5 flow = new FlowRequestV5();
flow.setFlow_id("FLOW_OEE_DAILY");
flow.setSite_id("SITE_DJ");

❌ 常见的拒绝案例

cust.setCustomer_id("CUST_001");      // ❌ CUST_ 아님 → E1002
prod.setProduct_id("PROD_A001");      // ❌ PROD_ 아님 → E1002
emp.setEmployee_id("E12345");          // ❌ EMP_ 누락 → E1002
flow.setFlow_id("flow_oee_daily");    // ❌ 소문자 → E1002

2.8 User ID(登录账号)

정규식: ^[A-Z][A-Z0-9_]*$
규칙: 대문자로 시작, 이후 [A-Z0-9_]만 허용

与其他域不同,没有固定前缀,但首字母必须为大写。

✅ ADMIN
✅ OPERATOR_01
✅ KOPENS_USER
❌ admin              → 소문자 시작
❌ 1USER              → 숫자 시작
❌ _ADMIN             → _ 시작

2.9 Calendar / Order — 无校验

这两个域没有服务端校验,ID 格式自由。不过为了运维一致性和检索便利,建议遵循推荐模式。

Calendar

import plantpulse.api.v5.dto.request.CalendarRequestV5;

CalendarRequestV5 cal = new CalendarRequestV5();
cal.setCalendar_id("CAL_20260514_0001");   // CAL_<YYYYMMDD>_<seq>
cal.setSite_id("SITE_DJ");
cal.setAsset_id("ASSET_DJ_M_0001");
cal.setTarget_type("MTN");                  // 점검 일정

target_type	含义
MTN	定期巡检(Maintenance)
HOLIDAY	假日/非生产
INSPECTION	检验
MEETING	会议

Order

import plantpulse.api.v5.dto.request.OrderRequestV5;

OrderRequestV5 order = new OrderRequestV5();
order.setOrder_id("ORD_20260514_001");      // ORD_<YYYYMMDD>_<seq>
order.setSite_id("SITE_DJ");
order.setAsset_id("ASSET_DJ_M_0001");
order.setCustomer_id("CUSTOMER_001");        // CUSTOMER_ 주의!
order.setProduct_id("PRODUCT_A001");         // PRODUCT_ 주의!
order.setEmployee_id("EMP_E12345");
order.setTarget_units(500);

工单状态(ISA-88):WAIT → START → END / ABORTED(详细内容参见 Order 服务)

2.10 ID 设计最佳实践

推荐做法

1. 保持不可变性 — 一旦分配的 ID 请勿更改。如需变更,建议迁移到新的 ID。
2. 在 ID 中体现层级 — 如 ASSET_<site>_<type>_<number> 那样将层级信息包含在 ID 中,可提升运维可视性。
3. 使用固定位数 — 编号部分请如 0001、00001 那样补零,以保持排序。
4. 固定使用大写与下划线 — 在整个系统中避免大小写混用,保持 [A-Z0-9_] 模式。
5. 外部系统 ID 单独存放字段 — ERP/MES 的原始 ID 保存在 external_*_id 字段中,PlantPulse ID 保持自有体系。

应避免的模式

• ❌ 使用韩文、空格、特殊字符 — ASSET_라인1、OPC 001
• ❌ 过短或无意义的 ID — S1、A、T01
• ❌ 缺少前缀或错误缩写 — CUST_001(正确:CUSTOMER_001)、PROD_A001(正确:PRODUCT_A001)
• ❌ 将含义写死在 ID 中导致无法变更 — ASSET_DJ_L_OLD_BROKEN_LINE

2.11 确认校验失败响应

V5 在校验失败时,方法会返回 null(或 false)。详细错误可在 envelope 中查看。

import plantpulse.api.v5.service.BaseServiceV5;
import plantpulse.json.JSONObject;

// V5 서비스 내부는 envelope를 외부에 노출하지 않으나,
// 디버그 모드를 켜면 로그에 출력됩니다.
client = new APIClient_V5(proto, host, port, user, token, true);  // debug=true

响应 envelope 示例:

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

详细错误代码请参阅响应格式与错误处理。

后续步骤

• 响应格式与错误处理 — 错误代码映射
• Site 服务 — 从创建站点开始
• Asset 服务 — 构建资产树
• Tag 服务 — 定义数据点