API 使用手册

这是 PlantPulse Java API 客户端库 (plantpulse-api) 的完整使用手册。您可以通过 13 个域服务访问 Platform 的所有主数据和运行数据，包括站点、资产、标签、报警、工单等。

库特点

标准 REST — 根据语义使用 GET/POST/PUT/PATCH/DELETE 方法
类型 DTO — 所有请求和响应自动映射为 *RequestV5 / *ResponseV5 类 (无需手动解析 JSONObject)
分项 PATCH — 支持 10 种标签部分修改，涵盖报警、元数据、计算、聚合等
13 个域服务 — system, site, customer, employee, product, asset, opc, tag, alarm, order, calendar, path, flow
安全默认值 — 失败时返回 null 或空列表 (不抛出异常)

本手册面向对象：本手册是为开发与 PlantPulse Platform 进行 Java 联接的外部系统（如 MES, ERP, 自定义仪表板等）的开发人员提供的正式参考指南。

领域	指南
初次使用	请按 1. 开始使用 → 2. 域 ID 规则 → 3. 响应格式与错误处理的顺序阅读。
需要特定域	请在下方目录中直接跳转至相应服务（例如：Tag, Order）。
直接调用 REST	端点完整列表中整理了 URL 和方法的映射关系。
需要工作流示例	请在综合示例集中确认端到端场景。
接入 AI 助手	MCP 服务器 — 使类似 Claude 的客户端可以用自然语言查询标签、报警、资产并确认报警。

入口点：new APIClient_V5(proto, host, port, user, token, debug) → connect()
13 个服务：client.system(), client.site(), client.customer(), client.employee(), client.product(), client.asset(), client.opc(), client.tag(), client.alarm(), client.order(), client.calendar(), client.path(), client.flow()
类型 DTO 返回：所有方法返回类型类 (SiteResponseV5, TagResponseV5 等) 而非 JSONObject
失败时的安全默认值：create/update/get → null, list → 空列表, delete/exists → false, count → 0
错误响应提取：BaseServiceV5.getErrorCode(env), getErrorMessage(env), getHttpStatus(env) 静态方法
域 ID 验证：服务器会检查每个域定义的固定前缀。楼层不通过前缀判断，而是通过 asset_type 判断 — 域 ID 规则
基础路径：所有调用均在 /api/v5 下位端点