复杂施工环境大型地下工程装备设计制造运维信息接口要求

复杂施工环境大型地下工程装备设计制造运维信息接口要求1范围本文件规定了复杂施工环境下大型地下工程装备设计制造运维环节一体化建设运用过程中，各环节过程接口协议、内容以及安全的规范。本文件适用于复杂施工环境下大型地下工程装备一体化集成方案设计与实施。2规范性引用文件下列文件中的条款通过本文件的引用而成为本文件的条款。下列文件对于本文件的应用是必不可少的。凡是注日期的引用文件，其随后所有的修改单（不包括勘误的内容）或修订版均不适用于本文件，然而，鼓励根据本文件达成协议的各方研究是否可使用这些文件的最新版本。凡是不注日期的引用文件，其最新版本适用于本文件。3术语与定义T/BIAIMXXXX-2024界定的以及下列术语与定义适用于本文件。4缩略语JSON：JS对象简谱（JavaScriptObjectNotation）REST：表达性状态转移（RepresentationalStateTransfer）5接口要求5.1接口基本要求复杂施工环境大型地下工程装备设计制造运维一体化平台信息接口应满足以下基本要求：a)网络要求：确保集成系统间网络通畅、稳定、安全；b)数据安全要求：确保系统集成过程中具备完善的权限验证机制；c)通信协议要求：满足Rest协议；d)通信频率要求：≤1Hz；e)更新频率：≥5M的数据采用增量方式对接，或系统资源利用不高时间段进行更新。5.2接口定义方式5.2.1接口分类复杂环境大型工程装备设计制造运维一体化平台提供的信息接口类型包括但不限于：a)文件接口：基于超文本传输协议(HTTP)或超文本传输安全协议(HTTPS)网络协议的网络服务，以电子文件形式传输数据；b)API接口：基于HTTP或HTTPS网络协议的网络服务，用于平台与数据提供主体间通过调用API接口获取数据。5.2.2接口格式描述接口说明包括但不限于：接口功能说明主要包括：——从众多的系统中提取数据到通用数据仓库，供报告、分析或商业情报之用——将现有系统的数据转化或合并为新系统和应用的格式和结构——用软件即服务(SaaS)应用集成留在公司内的数据接口地址格式格式：协议://+域名或者地址+路径+参数——目前数据集成协议以Rset协议接口为主，所以地址中“协议”用“https”；——地址中“域名或者地址”一般常见的是IP地址或者IP地址+端口号的方式，如涉及到外网数据集成访问会采用外网域名的方式，目前兆丰机电采用IP地址+端口号的方式；——这里地址的路径指接口对接时数据发布的地址路径；——这里接口地址中的“参数”是用于请求数据时的“暗号”，需要集成方与被集成方进行约定，或被访问方进行标准化规定。示例：HYPERLINKhttps://<域名或地址>/api/hufu-web/restData/lxtest?apiToken=ee116fhttps://<域名或地址>/iuapmdm/cxf/mdmrs/newcenter/queryListMdByMdmCodes请求参数数据接口请求参数报文应包含，如下内容：表1接口请求参数报文格式参数名必填描述备注mdmtokenY远程系统的令牌useridY用户IDj051hqr3数据接口请求参数正文应包含，如下内容：表2接口请求参数正文格式参数名类型是否数组必填备注systemCodestringNY远程系统编码gdCodestringNY项目定义编码codesjsonYY主数据编码(数组格式)响应数据返回类型参数应包含，如下内容：表3接口响应参数格式参数名是否数组必填描述successNY接口访问状态messageNY接口访问状态描述dataYY返回的主数据(JSON)示例：请求示例{"systemCode":"default","gdCode":"person","codes":["mdmCode1","mdmCode2","mdmCode3",""]}注：请求参数正文返回示例{"data":[{"id":"xxx（数据在此集成系统的主键值）","code":"xxx","name":"xxx","pk_mdm":"xxx（数据的主数据唯一主键）","mdm_code":"xxx（数据在模型中的唯一编码）","mdm_version":"1（数据版本。整型）","mdm_duplicate":"0（数据重复性，0为无重复。整型）","creator":"admin（数据创建人）","createtime":"2022-01-2313:17:26","modifier":"lihua（数据修改人）","modifytime":"2022-01-2313:17:26","mdm_datastatus":"3（数据状态，0:未提交，1:审批中，2:驳回，3:已发布（已解封），4:封存，5:已提交。整型）","mdm_cleanstatus":"WAITING（数据清洗状态，WAITING:等待中；RUNNING:清洗中；ERROR:清洗出错；COMPLETE:清洗结束；TRANSFER:已转化。）"}]"success":true,"message":"XXX查询异常……（只有查询失败时响应报文中才会出现此标签）"}5.3接口数据类型复杂环境大型工程装备设计制造运维信息接口应覆盖以下数据类型，包括：——字符串型；——整字型；——对象型。6接口定义6.1需求协同接口6.1.1爬虫数据提交接口爬虫数据提交接口定义见表4：表4爬虫数据提交接口定义接口名称爬虫数据提交接口接口说明提交工程相关爬虫数据接口方法POST参数说明至少包括：系统ID(systemCode)、项目ID（gdCode）、需求ID、爬取到的项目信息(工程名称、工程行业、地理位置等)返回值返回应用是否正常运行的状态信息6.1.2需求列表查询接口需求列表查询接口定义见表5：表5需求列表查询接口定义接口名称需求列表查询接口接口说明根据账号ID获取项目需求信息接口方法GET参数说明至少包括：系统ID(systemCode)、项目ID（gdCode）、需求ID返回值返回应用是否正常运行的状态信息和项目需求相关信息，如需求号、项目工号、工程名称、工程行业、地理位置、地下工程形式、设备类型、提交时间、优化建议等。6.2设计协同接口6.2.1设计列表查询接口设计列表查询接口定义见表6：表6项目详细需求查询接口定义接口名称项目详细需求查询接口接口说明根据账号ID获取设计需求信息接口方法GET参数说明至少包括：系统ID(systemCode)、项目ID（gdCode）返回值返回应用是否正常运行的状态信息和设计列表信息，如项目工号、产品名称、产品型号、最新需求提报时间、最新方案更新时间等。6.2.2项目详细需求查询接口项目详细需求查询接口定义见表7：表7项目详细需求查询接口定义接口名称项目详细需求查询接口接口说明根据需求ID获取项目详细需求信息接口方法GET参数说明至少包括：系统ID(systemCode)、项目ID（gdCode）返回值返回应用是否正常运行的状态信息和项目需求相关信息，如需求号、项目工号、工程名称、工程行业、地理位置、隧道形式、设备类型、提交时间、优化建议等。6.2.3项目详细需求确认提交接口项目详细需求确认提交接口定义见表8：表8项目详细需求确认提交接口定义接口名称项目详细需求确认提交接口接口说明确认提交项目详细需求信息接口方法POST参数说明至少包括：系统ID(systemCode)、项目ID（gdCode）、设计需求返回值返回应用是否正常运行的状态信息6.2.4项目设计结果查询接口项目设计结果查询接口定义见表9：表9项目设计结果查询接口定义接口名称项目设计结果查询接口接口说明根据项目ID提交设计方案信息进行设计结果确认接口方法POST参数说明至少包括：系统ID(systemCode)、项目ID（gdCode）、需求设计方案返回值应用是否正常运行的状态信息6.2.5项目设计结果确认提交接口项目设计结果确认提交接口定义见表10：表10项目设计结果确认提交接口定义接口名称项目设计结果确认提交接口接口说明根据项目ID获取项目设计结果信息接口方法GET参数说明至少包括：系统ID(systemCode)、项目ID（gdCode）返回值返回应用是否正常运行的状态信息和项目设计结果相关信息，如模块化配置结果、定制化设计结果、三维预览页面链接等。6.2.6项目设计变更查询接口项目设计变更查询接口定义见表11：表11项目设计变更查询接口定义接口名称项目设计变更查询接口接口说明根据项目ID获取项目设计变更信息接口方法GET参数说明至少包括：系统ID(systemCode)、项目ID（gdCode）返回值返回应用是否正常运行的状态信息和项目设计变更相关信息，如装备设计变更记录等。6.2.7设计制造协同接口设计制造协同接口定义见表12：表12设计制造协同接口定义接口名称设计制造协同接口接口说明根据一级BOM清单获取项目工艺信息接口方法GET参数说明至少包括：系统ID(systemCode)、项目ID（gdCode）、一级BOM清单返回值返回应用是否正常运行的状态信息和项目制造工艺相关信息，如详细BOM、设计图纸和工艺文件等。6.3制造协同接口6.3.1生产计划列表查询接口生产计划列表查询接口定义见表13：表13生产计划列表查询接口定义接口名称生产计划列表查询接口接口说明根据账号ID获取项目生产计划信息接口方法GET参数说明至少包括：系统ID(systemCode)、项目ID（gdCode）返回值返回应用是否正常运行的状态信息和项目生产计划相关信息，如项目图纸、物料生产计划列表（含自制件生产进度信息）等。6.3.2待排批次查询接口待排批次查询接口定义见表14：表14待排批次查询接口定义接口名称待排批次查询接口接口说明根据选中的模型ID获取待排批次信息接口方法GET参数说明至少包括：系统ID(systemCode)、项目ID（gdCode）、待排模型ID返回值返回应用是否正常运行的状态信息和模型待排批次相关信息。6.3.3待排批次确认提交接口待排批次确认提交接口定义见表15：表15待排批次确认提交接口定义接口名称待排批次确认提交接口接口说明确认提交待排批次信息接口方法POST参数说明至少包括：系统ID(systemCode)、项目ID（gdCode）、待排模型ID、带排批次信息返回值返回应用是否正常运行的状态信息6.3.4排程结果查询接口排程结果查询接口定义见表16：表16排程结果查询接口定义接口名称排程结果查询接口接口说明根据模型ID获取排产结果信息接口方法GET参数说明至少包括：系统ID(systemCode)、项目ID（gdCode）、模型ID返回值返回应用是否正常运行的状态信息和模型生成的排产结果相关信息。6.3.5排程结果确认提交接口排程结果确认提交接口定义见表17：表17排程结果确认提交接口定义接口名称排程结果确认提交接口接口说明确认提交排程结果信息接口方法POST参数说明至少包括：系统ID(systemCode)、项目ID（gdCode）、排程结果返回值返回应用是否正常运行的状态信息6.3.6物流列表查询接口物流列表查询接口定义见表18：表18物流列表查询接口定义接口名称物流列表查询接口接口说明根据登录账号ID获取物流列表信息接口方法GET参数说明至少包括：系统ID(systemCode)、项目ID（gdCode）返回值返回应用是否正常运行的状态信息和外协外购件物流列表6.3.7项目外协外购件数量查询接口项目外协外购件数量查询接口定义见表19：表19项目外协外购件数量查询接口定义接口名称项目外协外购件数量查询接口接口说明根据项目ID获取外协外购件数量信息接口方法GET参数说明至少包括：系统ID(systemCode)、项目ID（gdCode）返回值返回应用是否正常运行的状态信息和项目外协件和外购件数量信息6.3.8项目外协外购件清单内容查询接口项目外协外购件清单内容查询接口定义见表20：表20项目外协外购件清单内容查询接口定义接口名称项目外协外购件清单内容查询接口接口说明根据项目ID获取外协外购件清单信息接口方法GET参数说明至少包括：系统ID(systemCode)、项目ID（gdCode）返回值返回应用是否正常运行的状态信息和项目外协外购件清单6.3.9项目外协外购信息查询接口项目外协外购信息查询接口定义见表21：表21项目外协外购信息查询接口定义接口名称项目外协外购信息查询接口接口说明根据项目ID获取外协外购相关技术信息接口方法GET参数说明至少包括：系统ID(systemCode)、项目ID（gdCode）返回值返回应用是否正常运行的状态信息和项目所有外协外购件的技术信息、供应链资源协同、进度协同信息等6.4运维协同接口6.4.1运维需求提报接口运维需求提报接口定义见表22：表22运维需求提报接口定义接口名称运维需求提报接口接口说明确认运维需求相关信息接口方法POST参数说明至少包括：系统ID(systemCode)、项目ID（gdCode）、服务请求编号、现场联系人、联系电话、服务地点、区域、信息来源返回值返回应用是否正常运行的状态信息6.4.2项目需求内容查询接口项目需求内容查询接口定义见表23：表23项目需求内容查询接口定义接口名称项目需求内容查询接口接口说明根据项目ID获取运维需求内容信息接口方法GET参数说明至少包括：系统ID(systemCode)、项目ID（gdCode）返回值返回应用是否正常运行的状态信息和项目下的所有人员或备件需求内容，含响应情况6.4.3项目及设备信息查询接口项目及设备信息查询接口定义见表24：表24项目及设备信息查询接口定义接口名称项目及设备信息查询接口接口说明根据项目ID获取项目及设备相关信息接口方法GET参数说明至少包括：系统ID(systemCode)、项目ID（gdCode）返回值返回应用是否正常运行的状态信息和项目及设备相关信息，包括项目背景、工程进度、装备实时参数等信息。6.4.4实时数据加载接口实时数据加载接口定义见表25：表25实时数据加载接口定义接口名称实时数据加载接口接口说明根据项目ID获取实时运行信息接口方法GET参数说明至少包括：系统ID(systemCode)、项目ID（gdCode）返回值返回应用是否正常运行的状态信息和项目获取的实时运行参数和监测结果等6.4.5异常工况事件查询接口异常工况事件查询接口定义见表26：表26异常工况事件查询接口定义接口名称异常工况事件查询接口接口说明根据异常工况ID获取该工况详细信息接口方法GET参数说明至少包括：系统ID(systemCode)、项目ID（gdCode）、异常工况ID返回值返回应用是否正常运行的状态信息和项目异常工况的详细信息，包括异常工况名称、关联数据、判断时间等6.4.6异常工况确认接口异常工况确认接口定义见表27：表27异常工况确认接口定义接口名称异常工况确认接口接口说明确认异常工况事件相关信息接口方法POST参数说明至少包括：系统ID(systemCode)、项目ID（gdCode）、异常工况事件ID、判断时间、核查结果、原因分析、优化建议等返回值返回应用是否正常运行的状态信息7接口安全7.1结构安全结构安全要求包括：应根据各用户的工作重要性、权限、职能等因素，开放不同的功能权限。7.2访问控制访问控制要求包括：a)应具备针对未授权访问的识别和阻断能力，实现基于如访问时间、次数、用户IP等要素的API访问控制；b)宜通过ACL、RBAC等技术，