shishengliang/lingniu-vehicle-ingest

Fork 0

Files

lingniu 3c4bece72c feat: expand vehicle data platform capabilities

2026-07-27 16:46:15 +08:00

5.3 KiB

Raw Blame History

车辆数据开放平台独立化规划

产品目标

开放平台是面向合作方和开发者的独立产品，不与内部车辆运营平台共享入口、会话或发布节奏。首期开放单日用氢量和单日里程，后续通过数据产品目录持续增加实时状态、轨迹、告警、充换能、诊断等能力。

运行边界

服务	端口	面向对象	职责
`platform-api`	`20300`	内部运营人员	开放平台用户、应用、Key 和车辆授权管理
`open-platform-api`	`20310`	合作方及开发者	门户、登录、控制台、文档和数据 API
`open-platform-stat`	定时任务	内部计算	预计算开放平台日统计

20310 不挂载任何 /api/v2/* 内部接口；20300 不再承载合作方数据接口和开放门户。两个进程共享平台自有 MySQL 数据表，但使用相互独立的认证域。

门户信息架构

首页
├── 数据产品目录
├── 接入流程
└── 服务状态

API 文档
├── 开始使用
│   ├── 接入指南
│   ├── 认证与安全
│   └── 错误码
├── 数据 API
│   ├── 单日用氢量
│   └── 单日里程
└── OpenAPI / Swagger

控制台
├── 应用与凭证
├── 授权车辆
├── 调用记录
└── 账号设置

身份和授权模型

合作方用户

开放平台使用独立的 vehicle_open_user 和 vehicle_open_user_session：

用户名和 bcrypt 密码；
启用/停用状态；
用户起止有效期；
连续登录失败锁定；
随机会话 Token，数据库仅存 SHA-256；
登录、退出和失败事件写审计。

应用成员

vehicle_open_user_app 将用户与应用关联，角色为：

owner：查看应用、授权车辆、调用记录并轮换 Key；
developer：查看应用、授权车辆和调用记录；
viewer：只读查看。

管理员在 20300 创建用户并配置应用成员关系。合作方不能自行扩大车辆范围；车辆授权仍由管理员管理。

appKey

appKey 继续用于数据 API，不等同于门户会话：

32 位无连字符 UUID v4；
明文仅在创建或轮换时返回一次；
数据库只存 SHA-256 和前 8 位展示前缀；
Key 有效期和逐车有效期都必须完整覆盖查询自然日；
任一车辆越权时整批失败。

可扩展的数据产品模型

数据能力在代码中注册为产品目录项，每个产品具有稳定的：

productCode；
名称、说明、版本和状态；
HTTP 方法和路径；
认证方式；
请求/响应 Schema；
所属权限和统计依赖。

一期产品：

productCode	名称	路径
`daily_hydrogen`	单日用氢量	`/api/v1/vehicles/hydrogen-consumption/query`
`daily_mileage`	单日里程	`/api/v1/vehicles/mileage/query`

新增数据类型时，优先增加产品注册、查询服务和统计投影，不修改用户、应用和会话核心模型。

API 边界

合作方端口 `20310`

POST /portal-api/auth/login
POST /portal-api/auth/logout
GET  /portal-api/session
GET  /portal-api/catalog
GET  /portal-api/apps
GET  /portal-api/apps/{id}/vehicles
GET  /portal-api/apps/{id}/audit
POST /portal-api/apps/{id}/rotate-key

POST /api/v1/vehicles/hydrogen-consumption/query
POST /api/v1/vehicles/mileage/query

GET  /open-api/openapi.yaml
GET  /open-api/swagger/

内部端口 `20300`

除现有应用和车辆授权管理外，增加：

GET  /api/v2/open-platform/users
POST /api/v2/open-platform/users
PUT  /api/v2/open-platform/users/{id}
GET  /api/v2/open-platform/users/{id}/apps
PUT  /api/v2/open-platform/users/{id}/apps

所有内部开放平台管理接口继续仅允许 admin。

发布和网络

ECS 独立 systemd：lingniu-vehicle-open-platform.service；
默认监听 :20310；
独立静态目录：/opt/lingniu-vehicle-platform/current/open-web；
与 platform-api 独立重启和扩容；
对公网暴露时应使用 HTTPS、独立域名、限流和 WAF；
安全组只开放明确需要的端口或由反向代理统一承接；
20300 继续作为内部平台端口，不作为合作方入口。

视觉系统

设计规格来自三张协调概念稿：

首页：call_RL4zPXsqt5Iuo05fMQx2ne4k.png
控制台：call_mMBokoRHqq5JTuw4o9DhmG82.png
文档中心：call_mnCP5ARl7NnWRSllKHJ64lo0.png

核心 Token：

背景：纯白 #ffffff；
主文字：深海军蓝 #071b4a；
主色：钴蓝 #155eef；
数据状态：青绿 #10a7a0；
分割线：#dce5f2；
代码背景：#071a3b；
容器：开放式分区、列表、表格和窄侧栏，避免默认卡片网格；
字体：系统中文无衬线，代码使用等宽字体；
桌面最大内容宽度：1440px，移动端以单列和可折叠导航延续。

验收标准

20310 可独立启动、停止和发布，20300 不受影响；
合作方可登录、查看所属应用和授权车辆；
owner 可轮换 Key，完整 Key 只显示一次；
数据 API 仅在 20310 提供，并保持既有协议兼容；
门户首页、文档和控制台在桌面及移动端可用；
OpenAPI、Swagger 和门户文档描述一致；
迁移、Go/React 测试、竞态测试、Linux 构建和 ECS 冒烟全部通过。

5.3 KiB Raw Blame History Unescape Escape