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

## 产品目标

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

## 运行边界

| 服务 | 端口 | 面向对象 | 职责 |
|---|---:|---|---|
| `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 冒烟全部通过。