5. Site 服务

通过 client.site() 进行访问。站点（工厂）是紧邻企业下方层级的资产节点（asset_type=S），所有 OPC·Asset·Tag·Order 均隶属于该站点。

每个安装实例仅限一个企业。站点的 enterprise_id 指向该企业，且站点节点的父级即为企业。 若尝试创建第二个企业或删除唯一的企业，将被 409(enterprise.only_one) 拒绝 — 但名称和属性可以修改。

ID 规则: 必须包含 SITE_ 前缀。详细内容请参考 领域 ID 规则。

5.1 方法一览

方法	返回类型	HTTP	端点
create(SiteRequestV5)	SiteResponseV5 或 null	POST	/api/v5/site
update(site_id, SiteRequestV5)	SiteResponseV5 或 null	PUT	/api/v5/site/{id}
delete(site_id)	boolean	DELETE	/api/v5/site/{id}
get(site_id)	SiteResponseV5 或 null	GET	/api/v5/site/{id}
list()	List<SiteResponseV5>	GET	/api/v5/site
exists(site_id)	boolean	GET	/api/v5/site/{id}/exists

5.2 SiteRequestV5 (请求 DTO)

字段	类型	必填	说明
site_id	String	✅	以 SITE_ 开头
site_name	String	✅	站点名称
description	String	-	说明
lat / lng	String	-	经纬度（用于地图）
enterprise_id	String	-	企业 ID (ISA-95 Enterprise, 例如: ENTERPRISE_01)
site_code	String	-	ERP·MES 调用的工厂代码（50字以内）
operational_status_code	String	-	运行状态 — PLANNED · COMMISSIONING · IN_OPERATION · STANDBY · OUT_OF_SERVICE · DECOMMISSIONED
external_system / external_id	String	-	其他系统调用此节点的编号。两者同时填写或同时留空
timezone	String	-	IANA 时区。留空时使用安装时区(PP_TZ)
country	String	-	ISO 3166-1 alpha-2 国家代码
address	String	-	地址（500字以内）

5.3 SiteResponseV5 (响应 DTO)

上述请求字段 + 以下追加字段：

字段	类型	说明
insert_date / update_date	String	注册/修改时间
total_area_count	int	站点的 Area 数量
total_line_count	int	Line 数量
total_equipment_count	int	Equipment 数量
total_tag_count	int	Tag 数量

5.4 使用示例

创建站点

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.setDescription("주력 생산 공장");
req.setLat("36.3504");
req.setLng("127.3845");

SiteResponseV5 created = client.site().create(req);
if (created != null) {
    System.out.println("등록 완료: " + created.getSite_id());
}

单条查询

SiteResponseV5 site = client.site().get("SITE_DJ");
if (site != null) {
    System.out.println(site.getSite_name());
    System.out.println("Area 수: " + site.getTotal_area_count());
    System.out.println("Line 수: " + site.getTotal_line_count());
    System.out.println("Equipment 수: " + site.getTotal_equipment_count());
    System.out.println("Tag 수: " + site.getTotal_tag_count());
}

全部列表

import java.util.List;

List<SiteResponseV5> sites = client.site().list();
for (SiteResponseV5 s : sites) {
    System.out.println(s.getSite_id() + " — " + s.getSite_name());
}

修改站点

SiteRequestV5 update = new SiteRequestV5();
update.setSite_id("SITE_DJ");                // 동일하게 채워서 보내야 합니다
update.setSite_name("대전 1공장 (확장)");
update.setDescription("2026년 라인 증설 완료");

SiteResponseV5 updated = client.site().update("SITE_DJ", update);

确认是否存在

if (client.site().exists("SITE_DJ")) {
    // ...
}

删除站点

⚠️ 在删除站点之前，必须先删除该站点下属的所有 Asset·OPC·Tag·Order。否则将收到 E1200 (CONFLICT) 响应并返回 false。

boolean ok = client.site().delete("SITE_OLD");
if (!ok) {
    System.err.println("삭제 실패 — 하위 리소스 존재 가능");
}

5.5 应用场景

场景 — 分站点 KPI 仪表盘

for (SiteResponseV5 site : client.site().list()) {
    String siteId = site.getSite_id();

    // 사이트별 자산 통계는 SiteResponseV5에 이미 포함됨
    int eqCount  = site.getTotal_equipment_count();
    int tagCount = site.getTotal_tag_count();

    // 사이트별 OPC 수
    long opcCount = client.opc().countBySite(siteId);

    System.out.printf("%s — Equipment %d, Tag %d, OPC %d%n",
        site.getSite_name(), eqCount, tagCount, opcCount);
}

下一步

• Asset 服务 — 构建 Area/Line/Equipment 树
• OPC 服务 — 注册采集通道