feat: expand vehicle data platform capabilities
This commit is contained in:
lingniu
168
vehicle-data-platform/docs/open-platform-architecture.md
Normal file
168
vehicle-data-platform/docs/open-platform-architecture.md
Normal file
@@ -0,0 +1,168 @@
|
||||
# 车辆数据开放平台独立化规划
|
||||
|
||||
## 产品目标
|
||||
|
||||
开放平台是面向合作方和开发者的独立产品，不与内部车辆运营平台共享入口、会话或发布节奏。首期开放单日用氢量和单日里程，后续通过数据产品目录持续增加实时状态、轨迹、告警、充换能、诊断等能力。
|
||||
|
||||
## 运行边界
|
||||
|
||||
| 服务 | 端口 | 面向对象 | 职责 |
|
||||
|---|---:|---|---|
|
||||
| `platform-api` | `20300` | 内部运营人员 | 开放平台用户、应用、Key 和车辆授权管理 |
|
||||
| `open-platform-api` | `20310` | 合作方及开发者 | 门户、登录、控制台、文档和数据 API |
|
||||
| `open-platform-stat` | 定时任务 | 内部计算 | 预计算开放平台日统计 |
|
||||
|
||||
`20310` 不挂载任何 `/api/v2/*` 内部接口；`20300` 不再承载合作方数据接口和开放门户。两个进程共享平台自有 MySQL 数据表，但使用相互独立的认证域。
|
||||
|
||||
## 门户信息架构
|
||||
|
||||
```text
|
||||
首页
|
||||
├── 数据产品目录
|
||||
├── 接入流程
|
||||
└── 服务状态
|
||||
|
||||
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`
|
||||
|
||||
```http
|
||||
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`
|
||||
|
||||
除现有应用和车辆授权管理外，增加：
|
||||
|
||||
```http
|
||||
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`，移动端以单列和可折叠导航延续。
|
||||
|
||||
## 验收标准
|
||||
|
||||
1. `20310` 可独立启动、停止和发布，`20300` 不受影响；
|
||||
2. 合作方可登录、查看所属应用和授权车辆；
|
||||
3. owner 可轮换 Key，完整 Key 只显示一次；
|
||||
4. 数据 API 仅在 `20310` 提供，并保持既有协议兼容；
|
||||
5. 门户首页、文档和控制台在桌面及移动端可用；
|
||||
6. OpenAPI、Swagger 和门户文档描述一致；
|
||||
7. 迁移、Go/React 测试、竞态测试、Linux 构建和 ECS 冒烟全部通过。
|
||||
Reference in New Issue
Block a user