50 lines
5.5 KiB
Markdown
50 lines
5.5 KiB
Markdown
# 车辆实况接口补充：发布与验收记录
|
||
|
||
需求依据：2026-09-08《OneOS 氢能车辆实况接口补充需求》。交付范围是本仓库 OneOS 开放平台，Seeker 客户端代码不在本仓库，未将接口上线等同于客户端页面已完成适配。
|
||
|
||
## 交付范围
|
||
|
||
- 实时查询：储氢 kg、百分比接口字段、字段级状态、真实采集时间、来源和陈旧阈值；GPS 定位位、位置采集时间和可确认的坐标系。
|
||
- 日用氢量：VIN、来自同一统计记录的可空证据起止时间、更新时间。
|
||
- 日里程：所选来源真实证据起止时间，历史累计结转不伪造当日区间。
|
||
- 认证、原请求体、响应外壳和旧数值口径兼容；加强请求车牌与授权映射成员校验。
|
||
- 内嵌 OpenAPI 1.8.0、HTML 文档以及 `oneos-vehicle-live-api-contract.md`。
|
||
|
||
## 验收方法
|
||
|
||
1. 执行 API 模块 `go test ./...`、开放平台 `go test -race ./internal/openplatform`、`go vet ./internal/openplatform`，以及发布脚本自测与 diff-check。
|
||
2. 在生产机器仅监听 127.0.0.1:20311 的候选进程读取真实数据；以已有授权车辆为样本，创建临时测试凭证，调用三个正式 HTTP 接口，测试完删除临时凭证与授权，保留接口审计记录。凭证没有写入交付文件。
|
||
3. 每轮批量 100 台，检查结果数量、车牌白名单、VIN 一致性、必备新增字段、真实零、百分比空值、NO_FIX 坐标为空、401 未认证、403 未授权名单。覆盖当日及前一日统计。
|
||
4. 对实时快照与原始帧进行脱敏核对，确认合并快照会保留旧字段、最新帧可能没有储氢单元；回补须使用真正含储氢字段的原始帧及原采集时间。
|
||
5. 原始回查以每 VIN 五分钟接收时间窗、四并发、共享三秒预算限制成本；测试缺数据、显式异常、未来时间、陈旧、历史离线定位、故障降级、错 VIN、跨日结转及证据重算变化。
|
||
|
||
候选联调中发现并修复了两个仅靠 SQL mock 无法充分覆盖的问题：DATE_FORMAT 秒标记与 IN 参数模板冲突；TDengine 的排序分区查询 LIMIT 实际限制全局行数，回补最终改为每 VIN 单独查询。上线前进一步通过真实 SQL 核对。
|
||
|
||
## 交付限制
|
||
|
||
- 百分比目前 `null / UNSUPPORTED`：没有可信全车容量分母，不能使用电池 SOC、单瓶值或猜测容量替代。
|
||
- `REPORTED` 仅确认终端上报质量；无法确认终端内部采用测量还是估算。全车口径依赖已识别的 GB32960 广东扩展，不代表全部车型和协议均支持。
|
||
- 坐标系没有明确原始编码时为 UNKNOWN，不能宣称统一 GCJ02；真实定位状态与在线、新旧独立。
|
||
- 两个日统计接口没有共同快照保证；PRELIMINARY 氢耗开始时间通常未知，不能仅凭同日就作为严格同步百公里氢耗依据。
|
||
- 回补有明确时间窗；原始记录不可用、没有相关字段或查询超时仍可能 MISSING，不伪造数值或采集时间。
|
||
- Seeker 须自行增加字段映射、状态展示和 VIN/统计区间核验，接口添加不会自动改变其页面。
|
||
|
||
## 发布证据
|
||
|
||
发布结果、二进制 SHA-256、正式接口烟测和脱敏样本保存在工作区 `outputs/live-api-release-20260908/`。最终发布与验收结果如下：
|
||
|
||
|
||
- 正式版本：`open-platform-live-fields-202609082146`，北京时间 2026-09-08 21:46:08 切换，21:46:09 健康检查就绪。
|
||
- 服务：`lingniu-vehicle-open-platform`，端口 20310。无数据库迁移；沿用原门户静态资源，更新开放平台 API 及其内嵌接口文档。
|
||
- 正式二进制 SHA-256：`724491000e1010dc20960e0abb7db9aceac0dd99dc9867cd993f339da00ac97c`，与验收候选一致。
|
||
- 原版本 `open-platform-suspect-20260904162007` 和本次首版 `open-platform-live-fields-202609082130` 均保留。安装器保留失败时恢复旧版本的逻辑；本次正式切换成功，未执行生产回滚演练。
|
||
- 最终全量 Go 测试、race、vet、文档测试、YAML 校验、发布脚本测试和 diff-check 均通过。
|
||
- 最终候选四轮：实时接口 244–275 ms，100 台样本中 74–77 台有 kg，0 台 MISSING；其余为不支持协议。包括当日及前一日统计。各轮重新选择活跃授权样本，不是固定车辆群组，不应把不同轮覆盖率当作同一群组趋势。
|
||
- 正式接口三轮（每轮 100 台）：实时 446/335/295 ms；里程 15/15/18 ms；用氢 6/6/6 ms。三接口均 SUCCESS，结果数量及车牌/VIN 核验通过，401/403 负向用例通过。
|
||
- 正式样本 kg 非空 59/69/71 台，包含 3/4/4 个真实零；MISSING 33/22/19 台；UNSUPPORTED 8/9/10 台。未把缺失样本认定为已有有效储氢量，也不承诺全量车辆覆盖。无 enrichment 错误日志，仍应按真实来源和回查窗口判断可用性。
|
||
- 正式 GPS 样本识别 NO_FIX 4/5/5 台，经纬度及 locationAvailable 验证一致；所有样本坐标系为 UNKNOWN，未伪报统一坐标系。
|
||
- `http://115.29.187.205:20310/healthz`、`/open-api/openapi.yaml`、`/open-api/docs/` 公网检查 200 且版本/字段匹配；门户 catalog 正常，systemd active，无异常退出。
|
||
- 本轮所有临时测试应用与授权均删除，测试用凭证未输出。没有修改既有合作方密钥和授权。
|
||
|
||
结论：开放平台本次增量接口及其兼容、权限、真实来源、空值和发布行为验收通过；储氢百分比数据接入、未知坐标系的供应方确认、统一统计快照和 Seeker 页面适配仍属于上述明确限制，不宣称这些数据/客户端工作已经完成。
|