认证与通信约定
2 通信与认证约定
2.1 服务地址与鉴权
测试页默认服务地址为 https://api.engine.foresim.top/api/simulation，公开接口根路径为该地址加上 /openapi/v1。接口参考中的 /openapi/v1/... 路径会自动追加到服务地址之后，不需要手工重复填写。自建服务填写实际网关前缀。
请求体与响应体采用 UTF-8 编码的 JSON。所有请求通过 X-Foresim-Api-Key 请求头认证。业务系统可在服务端保管 Key；接口测试页支持临时输入 Key 并由浏览器直接调用。仿真实例与创建它的凭证关联，后续控制和查询必须使用同一凭证。
| 请求头 | 使用要求 |
|---|---|
X-Foresim-Api-Key | 所有接口必填 |
Content-Type | 有 JSON 请求体时填 application/json |
Accept | 建议填 application/json |
Idempotency-Key | 创建实例和提交脚本执行时必填，规则见对应接口 |
X-Request-Id | 可选，用于请求关联；响应头与响应 JSON 中返回相同的有效编号 |
2.2 统一响应
HTTP 状态码为 2xx 且 code=OK 表示请求成功，业务结果位于 data。非 2xx 响应通过 code 和 details 说明错误。启动请求成功后，仍需查询实例状态确认仿真是否完成。以下各接口的响应字段说明均指 data 内的字段。
| 响应字段 | 类型 | 含义 |
|---|---|---|
code | 字符串 | OK 或明确的错误码 |
message | 字符串 | 可读说明，不作为程序判断条件 |
requestId | 字符串 | 请求关联编号，与 X-Request-Id 响应头对应 |
data | 对象 | 成功响应中的业务结果，结构由接口定义 |
details | 对象数组 | 错误响应的补充信息；每项含 field 与 reason 字符串，无补充信息时为 []，示例见第 10.2 节 |
2.3 标识 时间与读取一致性
simulationId 标识一次独立仿真运行。对象、统计和对象所属表接口统一使用当前实例中的完整对象名称 entityName；统计属性使用模型定义中的 propertyName；结果表使用 tableName，重名时再用 entityName 限定归属。名称精确匹配区分大小写并保留首尾空白。tableId 只作为结果响应中的稳定标识和审计信息。所有路径参数均为字符串。
以 Micros 结尾的时间字段为 64 位整数，单位是仿真微秒；1 秒等于 1000000 微秒。仿真时间与实际等待时间不同。createdAt 等日期时间字段采用带时区的 ISO 8601 格式，响应使用 UTC。客户端应使用能够准确保存 64 位整数的 JSON 处理方式，避免精度损失。
响应中的 null 表示该字段无可用值，空数组表示没有记录，两者均不等同于数值 0；空字符串也不等同于 null。请求字段省略或传 null 的行为按各接口的参数说明处理。
查询响应中的 observation 描述读取过程：
| 字段 | 类型 | 含义 |
|---|---|---|
simulationTimeStartMicros | 64 位整数 | 开始读取时的仿真时刻 |
simulationTimeEndMicros | 64 位整数 | 结束读取时的仿真时刻 |
timeStable | 布尔值 | 两个仿真时刻是否相等 |
consistent | 布尔值 | 返回 false，不保证多个字段来自同一瞬间 |
timeStable=true 仅表示读取前后的仿真时刻相等，不构成多个字段的一致性保证。
2.4 分页与请求限制
分页参数 page 从 1 开始，省略或为 null 时取 1；pageSize 省略或为 null 时取 100，上限见第 9.1 节。响应中的 page.number 和 page.size 为实际页码和页大小，totalElements 为匹配记录总数，totalPages 为总页数。空集合的 totalPages 为 0，超过末页时返回空记录数组。运行中跨页读取可能遇到数据变化；最终结果应在实例完成后读取。
PAGE_OUT_OF_RANGE 表示页码与页大小计算出的偏移量超出支持范围，应减小页码或页大小。RESULT_TOO_LARGE 表示响应过大，应缩小对象、指标集合或分页大小；仍无法读取时，保留 requestId 并联系服务提供方。
请求建议带 Accept: application/json。可选 X-Request-Id 为 1～128 位字母、数字、点、下划线、冒号或短横线；格式不符时服务生成替代值。反馈问题保留实际响应的 requestId，不附带 API Key。
测试页连接
在页面顶部填写“服务地址”和“API Key”，点击“检查连接”查询 capabilities。浏览器直接调用所填地址，发送 X-Foresim-Api-Key，不携带 Cookie，不依赖本地调试代理。服务端 CORS 必须允许页面来源及相应请求方法，并允许 Content-Type、X-Foresim-Api-Key、X-Request-Id、Idempotency-Key 请求头。
Key 不写入环境变量、localStorage、sessionStorage、URL、cURL 或导出记录。页面实际发送认证头，在“实际输入”视图和导出中用 <api-key> 隐去密钥。刷新、离页或重置会话清除 Key；切换服务地址也清除 Key。修改 Key 会停止等待和轮询，清空旧实例、对象、表、执行记录与两类动画游标。
所有场景和对象标识作为字符串。测试页保留响应原文，JSON 格式化也保留数字的原始十进制文本；下载不会把 64 位整数四舍五入。浏览器取消等待只影响当前等待，不表示服务端操作取消。