2. ドメインID規則

PlantPulseのすべてのマスタデータはサーバー側正規表現検証に従います。サーバーが正規表現の一致を強制し、違反した場合は E1002 (VALIDATION_FAILED) として拒否されます。正確なID設計は拡張可能なIoTシステム構築の出発点です。

📖 プラットフォーム全般のコンベンションの要約は、ドメインID命名コンベンションページを参照してください。

2.1 ID規則一覧 (サーバー正規表現基準)

新しいIDは «接頭辞フルネーム + 番号» です。 プラットフォームが自動発行する場合、接頭辞の後に6桁の番号を付与します (SITE_000001, TAG_000001)。ドメインごとにシーケンスが分かれており、999999を超えると桁数が増えます(ORDER_1000000)。

ドメイン	正式接頭辞	旧接頭辞 (引き続き有効)	発行例
企業 (Enterprise)	ENTERPRISE_	—	ENTERPRISE_000001
サイト (Site)	SITE_	—	SITE_000001
区域 (Area)	AREA_	ASSET_	AREA_000001
ライン (Line)	LINE_	ASSET_	LINE_000001
設備 (Equipment)	EQUIPMENT_	ASSET_	EQUIPMENT_000001
接続 (OPC)	OPC_	—	OPC_000001
タグ (Tag)	TAG_	—	TAG_000001
Edge (Edge)	EDGE_	—	発行せず — EDGE_LINE1_01 のように直接指定します
アラーム設定 (AlarmConfig)	ALARM_CONFIG_	5桁の番号, ALARM_CONFIG_TAG_…	ALARM_CONFIG_000001
社員 (Employee)	EMPLOYEE_	EMP_	EMPLOYEE_000001
顧客 (Customer)	CUSTOMER_	—	CUSTOMER_000001
製品 (Product)	PRODUCT_	—	PRODUCT_000001
フロー (Flow)	FLOW_	—	FLOW_000001
ワークオーダー (Order)	ORDER_	ORD_	ORDER_000001
カレンダー (Calendar)	CALENDAR_	CAL_	CALENDAR_000001
シフト例外 (Shift override)	SHIFT_OVERRIDE_	OV_	SHIFT_OVERRIDE_000001
工程セグメント (Process segment)	PROCESS_SEGMENT_	SEG_	PROCESS_SEGMENT_000001
設備関係 (Asset relation)	ASSET_RELATION_	REL_	ASSET_RELATION_000001
設備命令 (Asset command)	ASSET_COMMAND_	—	ASSET_COMMAND_000001
PLC命令領域 (Command area)	COMMAND_AREA_	CMDAREA_	COMMAND_AREA_000001
イメージ (Image)	IMAGE_	IMG_	IMAGE_000001
整備オーダー (Maintenance order)	MAINTENANCE_ORDER_	数字のみ	MAINTENANCE_ORDER_000001
ログインアカウント (User)	なし	—	発行せず — ^[A-Z][A-Z0-9_]*$

接頭辞の後には大文字・数字・_ のみが許可されます([A-Z0-9_]+)。整備オーダーおよびアラーム設定の新しいIDは、6桁以上の数字のみが許可されます。

階層はIDではなく asset_type で判断します

旧IDは再採番されないため、今後も引き続き登場します。ASSET_ 一つが区域・ライン・設備に幅広く使用されていたため、 接頭辞を見て階層を推測すると誤ります。 階層は常に asset_type(E · S · A · L · M) を読み取ってください。

接頭辞でドメインを区別する場合、最も長い接頭辞が優先されます — ASSET_RELATION_… と ASSET_COMMAND_… は ASSET_ ではなく、SHIFT_PATTERN_… は SHIFT_ ではありません。

IDを直接指定するとそのまま保存されます

IDを指定して作成した場合、形式チェックを通過すれば指定した値がそのまま保存されます。番号が発行されるのは、IDを空にした場合です。 V5で空にできるのは区域・ライン・設備(asset_id)とカレンダー(calendar_id)であり、POST /api/v5/site は site_id を必ず指定する必要があります。旧接頭辞で新規作成する場合も、区域・ライン・設備は受け入れられます。

番号は連続しません — 拒否された生成処理が番号を消費するため、空き番号が生じるのが正常です。

⚠️ 検証強制: サーバーはこの規則を検査します。違反した場合は HTTP 422, コード E1002 で拒否されます。同一IDが既に存在する場合は HTTP 409 となります。

⚠️ フルネームが正解です: CUST_, PROD_ はどの時期においても有効な接頭辞ではないため拒否されます。EMP_, ORD_, CAL_ は既存のIDのための旧接頭辞であり、新規作成時はフルネームを使用してください。

⚠️ opc_id は OPC_ のみです: Edgeソースであっても外部APIチャネルであっても OPC_ で開始しなければなりません。EDGE_·TEST_·API_ は拒否されます — Edgeソースは OPC_EDGE_00303 のように OPC_ の後に付与します。edge_id は別ドメインであり EDGE_ のみを受け入れます。

2.2 Site ID

정규식: ^SITE_[A-Z0-9_]+$
허용: SITE_… 만

仮想・集計用サイトも接頭辞は同じです — SITE_V_… のように接頭辞の中で名前を付けます。特別なパターンではなく命名規則です。

例

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 정규식 확인 필요");
}

// 가상 사이트 (테스트·집계용) — 접두는 SITE_ 그대로
SiteRequestV5 vsite = new SiteRequestV5();
vsite.setSite_id("SITE_V_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("VSITE_01");      // ❌ V 변형 접두는 없다 → E1002

2.3 OPC ID

정규식: ^OPC_[A-Z0-9_]+$
허용: OPC_… 만

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	テスト・シミュレーション	OPC_TEST_VIRTUAL_<number>
Edge Gateway	Edgeゲートウェイ (別 edge_id ドメイン — ^EDGE_[A-Z0-9_]+$)	EDGE_<location>_<number>

⚠️ 外部API/ファイルチャネルまたはテスト用であっても、OPCドメインでは OPC_FILE_… · OPC_TEST_… 形式を使用してください。

例

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

OPCRequestV5 req = new OPCRequestV5();
req.setOpc_id("OPC_PLC_L1_001");
req.setOpc_name("Line1 메인 PLC");
req.setOpc_protocol("S7");                 // 프로토콜 코드 — 소스 유형(PLC)은 여기서 파생
req.setSite_id("SITE_DJ");
req.setOpc_source_ip("192.168.10.50");
req.setOpc_source_port(102);
client.opc().create(req);

// ERP 연동 — REST API 로 들어오는 연결
OPCRequestV5 erp = new OPCRequestV5();
erp.setOpc_id("OPC_API_ERP_001");
erp.setOpc_protocol("API");
erp.setSite_id("SITE_DJ");
client.opc().create(erp);

// 테스트·시뮬레이션
OPCRequestV5 testOpc = new OPCRequestV5();
testOpc.setOpc_id("OPC_TEST_001");          // TEST_ 로 시작하면 E1002
testOpc.setOpc_protocol("API");
testOpc.setSite_id("SITE_DJ");
client.opc().create(testOpc);

// 엣지 자기감시 연결 OPC_SYSTEM_<edge_id> 는 엣지가 sync 로 선언한다 — 직접 만들지 않는다.

2.4 Edge ID

정규식: ^EDGE_[A-Z0-9_]+$

edge_id はEdgeゲートウェイデバイス識別子であり、opc_id とは異なるドメインです。

req.setEdge_id("EDGE_LINE1_01");
// req.setEdge_id("OPC_EDGE_00303");  // ❌ OPC_ 는 edge_id 의 접두사가 아니다
// req.setEdge_id("TEST_EDGE_01");    // ❌ TEST_ 는 어느 도메인에서도 접두사가 아니다

2.5 Asset ID — 階層構造の核心

設備階層は企業 → サイト → 区域 → ライン → 設備 の5層です(ISA-95)。これら5層すべてがアセットツリーのノードであり、 ノードの階層は asset_type が決定します。

asset_type	階層	正規表現
E	企業 (Enterprise)	^ENTERPRISE_[A-Z0-9_]+$
S	サイト (Site)	^SITE_[A-Z0-9_]+$
A	区域 (Area)	^(AREA_[A-Z0-9_]+|ASSET_[A-Z0-9_]+)$
L	ライン (Line)	^(LINE_[A-Z0-9_]+|ASSET_[A-Z0-9_]+)$
M	設備 (Equipment, Machine)	^(EQUIPMENT_[A-Z0-9_]+|ASSET_[A-Z0-9_]+)$

💡 EQUIPMENTコードが M である理由: Equipment = Machine。検索・フィルタリングにおいて、短く明確な1文字コードを使用します。

企業はインストールごとに一つのみです。2つ目を作成しようとしたり、唯一の企業を削除しようとすると 409(enterprise.only_one) で拒否されます — Siteサービス を参照してください。

ノードの階層は変更できません。区域をラインに変更しようとする修正は拒否されるため、階層が誤っている場合は移動させるのではなく、新しく作成してください。

標準IDパターン例

大田工場(SITE_DJ)の区域一つ、その中のライン一つ、その上の設備一つ — IDを空にして作成すると以下のようになります。

AREA_000001                ← 구역
  └ LINE_000001            ← 라인
      └ EQUIPMENT_000001   ← 설비

例 — アセットツリー生成

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_name("조립구역");
area.setAsset_type("A");
client.asset().create(area);

// asset_id 를 비워 두면 플랫폼이 발급합니다 — 응답에서 AREA_000001 을 받습니다

// 2) Area 산하 Line
AssetRequestV5 line = new AssetRequestV5();
line.setSite_id("SITE_DJ");
line.setParent_asset_id("AREA_000001");      // 부모는 Area
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("LINE_000001");     // 부모는 Line
equip.setAsset_name("CNC #1");
equip.setAsset_type("M");
equip.setAsset_class_code("CNC");            // 설비 분류 — 기준정보에 있는 코드
client.asset().create(equip);

parent_asset_id 規則

子タイプ	parent_asset_id 値
区域 (A)	サイトID (例: SITE_DJ)
ライン (L)	区域の asset_id (例: AREA_000001)
設備 (M)	ラインの asset_id (例: LINE_000001)

親は直上の階層である必要があります。階層を飛び越えたり、別のサイトのノードを親に指定した場合は拒否されます。

2.6 Tag ID

정규식: ^TAG_[A-Z0-9_]+$
허용: TAG_… 만 (가상 태그도 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	TAG_V_<purpose>_<number>	TAG_V_OEE_LINE1

💡 Virtual Tag: 計算式・集計タグの接頭辞も TAG_ 一つです。区別が必要な場合は慣例として TAG_V_ を使用します(別パターンではなく命名規則)。タグが«計算値であるか»は、タグの計算設定(use_calculation)が決定します。作成方法は 仮想タグ に記載されています。

例

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("EQUIPMENT_000001");
req.setJava_type("Double");
req.setUnit("RPM");
req.setDescription("Spindle 회전수 (RPM)");
client.tag().create(req);

// Virtual Tag — 라인별 OEE 집계
TagRequestV5 vtag = new TagRequestV5();
vtag.setTag_id("TAG_V_OEE_LINE1");
vtag.setTag_name("Line1 OEE");
vtag.setSite_id("SITE_DJ");
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

これらのドメインもすべてサーバー検証が強制されます。正確なフル接頭辞を使用してください。アラーム設定IDは番号形式のみ受け入れられます(ALARM_CONFIG_000001)。

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

// Employee
EmployeeRequestV5 emp = new EmployeeRequestV5();
emp.setEmployee_id("EMPLOYEE_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");          // ❌ EMPLOYEE_ 누락 → E1002
flow.setFlow_id("flow_oee_daily");    // ❌ 소문자 → E1002

外部システム名 (external_system)

顧客・製品・社員の external_system は、1〜50文字の大文字・数字・_・: のみが許可されます(^[A-Z0-9_:]{1,50}$)。 : は、そのシステム内で番号を一意にする範囲を付与する際に使用します — 例: SAP PM のクライアント別 SAP_PM:100。 プラットフォームはこの範囲を解釈せず、external_system + external_id のペアをそのままキーとして使用します。 SAP-PM のようにハイフンが含まれていると拒否され、拒否メッセージで許容文字が通知されます。

2.8 User ID (ログインアカウント)

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

他のドメインとは異なり固定接頭辞はなく、最初の文字は大文字である必要があります。

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

2.9 Calendar / Order

これら2つのドメインもサーバーが接頭辞を検査します。 カレンダーは ^(CALENDAR_[A-Z0-9_]+|CAL_[A-Z0-9_]+)$、ワークオーダーは ^(ORDER_[A-Z0-9_]+|ORD_[A-Z0-9_]+)$ です。

Calendar

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

CalendarRequestV5 cal = new CalendarRequestV5();
// calendar_id 를 비워 두면 플랫폼이 CALENDAR_000001 꼴로 발급합니다
cal.setSite_id("SITE_DJ");
cal.setAsset_id("EQUIPMENT_000001");
cal.setTarget_type("MTN");                  // 점검 일정

target_type	意味
MTN	定期点検 (Maintenance)
HOLIDAY	休日/非操業
INSPECTION	検査
MEETING	会議

Order

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

OrderRequestV5 order = new OrderRequestV5();
order.setOrder_id("ORDER_000001");
order.setSite_id("SITE_DJ");
order.setAsset_id("EQUIPMENT_000001");
order.setCustomer_id("CUSTOMER_001");        // CUSTOMER_ 주의!
order.setProduct_id("PRODUCT_A001");         // PRODUCT_ 주의!
order.setEmployee_id("EMPLOYEE_E12345");
order.setPlanned_quantity(Quantity.of("500", "EA"));   // ISA-95 Quantity — 값 + UN/ECE Rec 20 단위

作業指示状態(ISA-88): WAIT → START → END / ABORTED (詳細は Orderサービス)

2.10 ID設計のベストプラクティス

推奨事項

1. 不変性の維持 — 一度付与したIDは変更しないでください。変更が必要な場合は、新しいIDへの移行を推奨します。
2. IDに意味を込めてはいけない — 階層は asset_type、位置は親またはパスで判断します。直接指定する場合は、接頭辞フルネームを遵守してください。
3. 自動IDを使用する — IDを空にすると、プラットフォームが «接頭辞 + 6桁» で発行します。
4. 大文字・アンダースコア固定 — システム全体で大文字小文字の混用を避け、[A-Z0-9_] パターンを維持してください。
5. 外部システムIDは別フィールドへ — ERP/MESの元IDは external_*_id フィールドに保存し、PlantPulse IDは独自体系を維持してください。

回避すべきパターン

• ❌ 日本語、空白、特殊文字の使用 — LINE_라인1, OPC 001
• ❌ 短すぎる、または無意味なID — S1, A, T01
• ❌ 接頭辞の欠落または誤った略称 — CUST_001 (正解: CUSTOMER_001), PROD_A001 (正解: PRODUCT_A001)
• ❌ 意味がIDに組み込まれていて変更不能 — LINE_DJ_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 ^SITE_[A-Z0-9_]+$",
  "_http_status": 422
}

詳細なエラーコードは レスポンス形式およびエラー処理 を参照。

2.12 IDの事前取得 — POST /api/v5/domain-ids

オブジェクトを作成する前にIDを知る必要があるシミュレーターや外部システムで使用します。

要求 {"domain": "EQUIPMENT", "count": 3} → 応答 {"domain": "EQUIPMENT", "ids": ["EQUIPMENT_000123", ...]}

項目	値
domain	ドメイン名(大文字小文字不問)。シーケンスがあるもののみ — ASSET · EDGE · SHIFT · SHIFT_PATTERN · HOLIDAY · BLOB は不可
count	1~1000, デフォルト 1

ADMINまたはAPIトークンが必要です。行を作成せず番号のみを取得するため、使用しなかった番号に空きが生じるのが正常です。再度呼び出すと新しい番号が発行されます(同じ Idempotency-Key を送信した場合を除きます)。

応答	意味
400 domain_id.domain_required	domain なし
404 domain_id.unknown	存在しないドメインまたはシーケンスなし
422 domain_id.count_invalid	count が 1~1000 の範囲外

コンソール登録画面のID欄

登録画面のID欄の右側に生成アイコン(マウスオーバーで «生成»)があります。クリックすると新しい番号が入力されます。直接入力した場合は大文字に変換され、フォーカスを外れる際に形式と重複が検査され、問題がある場合は欄の下に表示されます。修正画面ではID欄はロックされ、アイコンは表示されません。発行シーケンスのないドメイン(Edge・勤務シフト・勤務パターン・休日・オブジェクト)にもアイコンは表示されません。

コンソールではID欄が必須です。生成をクリックするか、直接入力します。空にした場合に自動発行されるのは工程区間のみです。生成および重複検査はADMIN・API権限を持つユーザーのみ利用可能です。

次のステップ

• レスポンス形式およびエラー処理 — エラーコードマッピング
• Siteサービス — サイト生成から開始
• Assetサービス — アセットツリー構築
• Tagサービス — データポイント定義