hepu/docs/contract/6_J-00_OpenAPI使用说明_V1.8.md

J-00 OpenAPI 机器可读版 · 使用说明

文件：6_J-00_接入接口规格_V1.8_OpenAPI.yaml（OpenAPI 3.0.3，v1.8.0）—— 与本说明放在同一目录，可直接用编辑器或 Swagger Editor 打开 对应：6_J-00_接入接口规格_V1.8.md（同一个契约的人读版） 编制：周工 ｜ 2026-11-02

为什么文件名这么长：这是故意的。同一份契约有两个形态——.md 讲"为什么"，.yaml 讲"长什么样"。两个文件共用 6_J-00_接入接口规格_V1.8 前缀，在文件夹里永远相邻，谁也漏不掉；仅仅一个叫 internal-iot.yaml 的文件，脱离上下文就没人知道它是 J-00 的机读版。

---

一、这是什么

一份机器可读的接口契约。内容和 J-00 V1.8 一一对应，只是换了一种能被工具直接消费的写法。

两份文件的分工，不要理解成两份契约：

	管什么	举例
本文件（YAML）	长什么样	路径、方法、字段类型、必填、枚举、长度上限、错误结构
J-00 V1.8	为什么这样	告警状态机、四条硬边界、幂等三档算法、断档与 0x04、tsSource 为什么不能伪造

有些东西写不进 YAML，比如「deviceTime 没有就传 null，禁止用 receivedAt 顶替——填了等于伪造时源」。所以：字段定义以本文件为准，业务语义的解释权仍在 J-00。

两者不一致时，以本文件为准，同时回改 J-00，两边同版本号。

---

二、里面有什么

项	数量	说明
接口	6	在役 5 个（I-01/02/05/12/18）+ 二期预留 1 个（I-17）
schema	20	Event／DeviceStatus／RawFrame／Command／CommandResult 及其批次包装
公共参数	8	鉴权头 4 个 + 幂等键 4 个（每接口一个）
公共响应	4	400／401／429／500

五个在役接口：

编号	方法	路径	operationId
I-01	POST	/events/batch	ingestEvents
I-02	POST	/device-status/batch	ingestDeviceStatus
I-12	POST	/raw-frames	ingestRawFrames
I-18	GET	/commands/pending	pullPendingCommands
I-05	POST	/commands/result	reportCommandResults
I-17	POST	/commands/{commandId}/dump	二期预留，本期固定 404，不要实现

枚举已全部写死，且与 J-00 逐值一致：

枚举	值数	内容
eventType	29	10 对发生/解除 + 9 个单值
sourceChannel	4	OWN_GW／HORN_HOST／HORN_CELL／MIR_CELL
result	5	ACKED／SENT／TIMEOUT／DEVICE_OFFLINE／FAILED
rejectReason	4	RATE_LIMITED／SCHEMA_INVALID／UNKNOWN_CHANNEL／SENSOR_ID_INVALID
cmdType	8	set_mode／set_ack_policy／time_sync／set_report_cfg／del_sensor／reboot／diag_dump／set_ota

---

三、能拿它做什么（五件事）

下表里的 $Y 指本文件名。因为它带中文和版本号，直接敲命令很累，下面给了变量写法，复制即用。

用途	怎么用	省了什么
接口校验	用 swagger-cli validate 或编辑器插件跑一遍	字段漏写、枚举越界当场暴露，不用等联调
生成服务端骨架	openapi-generator-cli generate -i "$Y" -g spring	五个 Controller 的入参出参自动生成，外包只填业务
生成前端类型	-g typescript-fetch 或 typescript-axios	陈工不用照表格手敲 TS 类型
起 Mock 服务	prism mock "$Y"	前端不用等后端就能联调
生成测试用例	-g jmeter 或 schemathesis run	必填、枚举、边界自动出用例，比手写清单全

推荐的命令（外包侧）：

# 文件名太长，先存成变量，后面照抄即可
Y="6_J-00_接入接口规格_V1.8_OpenAPI.yaml"

# 1. 语法与规范校验
npx @redocly/cli lint "$Y"

# 2. 生成 Spring Boot 服务端接口骨架
npx @openapitools/openapi-generator-cli generate \
  -i "$Y" -g spring \
  -o ./generated --additional-properties=interfaceOnly=true

# 3. 起 Mock 服务（前端联调用）
npx @stoplight/prism-cli mock "$Y" -p 4010

---

四、与 J-00 V1.8 的逐项核对

已用脚本比对，以下全部一致：

项	J-00 位置	YAML 位置
五个接口的编号与路径	§1.1	paths
eventType 29 值	§1.5.1	schemas.EventType.enum
事件对象 12 个字段与必填性	§1.3	schemas.Event
I-02 十个字段	§1.8	schemas.DeviceStatus
I-12 八个字段（含 rawFrame 定死 Base64）	§1.9.2	schemas.RawFrame
result 5 值	§3.3	schemas.CommandResult.result
I-18 四个查询参数与上限	§3.2	paths./commands/pending.parameters
鉴权四层 + 幂等键算法	§1.2	components.parameters（每个接口的幂等键分别写，因为取法不同）
响应结构与 unregistered 非错误语义	§1.7	schemas.IngestResponse

幂等键按接口分开写，这是 V1.6 的重点修正：

接口	幂等键	为什么不能统一
I-01	{sourceChannel}-{首条 eventId}-{条数}	有 eventId
I-02	{sourceChannel}-{首条 sensorId}-{reportedAt}-{条数}	I-02 报文里没有 eventId
I-12	{sourceChannel}-{首条 rawRef}-{条数}	I-12 报文里没有 eventId，rawRef 就是 MD5(原始帧字节)
I-05	{nodeId}-{首条 commandId}-{条数}	有 commandId
I-18	不带	GET 拉取，重复拉天然幂等，靠租约去重

---

五、已知未定项（不藏着）

项	现状	何时定
错误响应里的 code 具体码值	只写了 {code, message} 结构，没固定码值	待与业务层错误码表统一后回填。当前按 HTTP 段理解：400xx 请求非法／401xx 鉴权失败／429xx 限流
I-17 的请求体	只写了「本期 404」	二期启用诊断包时再补
params 的结构	additionalProperties: true，随 cmdType 变	八种命令字的参数结构不在本文件里，由业务层命令模块保证；外包按 cmdType 做编码即可

---

六、对陈工和外包各说一句

给陈工：这份 YAML 可以生成 TS 类型，openapi-generator -g typescript-fetch。你前端不用照 J-00 的表格手敲字段，也不用维护第二份接口定义——生成一次即可，接口变了重生成。

给外包（谢工）：五个接口全在这里。各字段的 description 是给你的实现提示，重点是三处最容易做错的：

1. I-02 / I-12 的幂等键不是 eventId（报文里没这个字段），按对应 components.parameters 的说明算。
2. I-18 是 GET，签名时 sha256(body) 取空串的 hash，path 含 query 一并算。
3. rejectedDetail 里出现的条目一律不重试，只有整批 5xx 才重试。