132 lines
4.9 KiB
Markdown
132 lines
4.9 KiB
Markdown
# 网关 MC4 模块检查报告 2026-06-03
|
||
|
||
> **基准文档**: `doc/对接文档/MC4.0对外API.md` (31 API)
|
||
> **检查范围**: `gateway/src/IntegrationGateway.Adapters.MC4/` (Mc4Adapter.cs, Mc4AuthHelper.cs)
|
||
> **日期**: 2026-06-03
|
||
|
||
---
|
||
|
||
## 1. 覆盖率概览
|
||
|
||
MC4.0 接口文档共 **31 个 REST 端点**，当前 Mc4Adapter 覆盖了 **6 个**（19%）。
|
||
|
||
| 模块 | 文档端点数 | 已实现 | 缺失 |
|
||
|------|:---:|:---:|:---:|
|
||
| 认证 | 3 | 0 | 3 |
|
||
| 对象树 | 1 | 1 | 0 |
|
||
| 点位 | 3 | 2 | 1 |
|
||
| 告警 | 14 | 3 | 11 |
|
||
| 系统管理 | 10 | 0 | 10 |
|
||
| **合计** | **31** | **6** | **25** |
|
||
|
||
---
|
||
|
||
## 2. 已实现接口对照
|
||
|
||
| MC4.0 端点 | Mc4Adapter 方法 | 能力接口 | 状态 |
|
||
|------|------|------|:--:|
|
||
| /api/central/object/tree | GetObjectTreeAsync | IHasOwnDeviceTree | ✅ |
|
||
| /api/central/device/point/value/get | GetRealtimeValuesAsync | IHasPoints | ✅ |
|
||
| /api/central/point/value/set | SetPointValueAsync | IHasPoints | ✅ |
|
||
| /api/central/alarm/query | GetAlarmsAsync | IHasAlarms | ✅ |
|
||
| /api/central/alarm/confirm | ConfirmAlarmAsync | IHasAlarms | ✅ |
|
||
| /api/central/alarm/end | EndAlarmAsync | IHasAlarms | ✅ |
|
||
|
||
---
|
||
|
||
## 3. 🔴 关键问题
|
||
|
||
### 3.1 Mc4AuthHelper 认证逻辑错误（🔥 致命）
|
||
|
||
**现状**: `GetTokenAsync` 调用 `/api/central/auth/conf/get`：
|
||
|
||
```csharp
|
||
var resp = await _http.PostAsync($"{_baseUrl}/api/central/auth/conf/get", null);
|
||
var result = JsonSerializer.Deserialize<Mc4AuthResponse>(json);
|
||
_token = result?.Token ?? "";
|
||
```
|
||
|
||
**错误**: `/api/central/auth/conf/get` 是**密码加密配置查询接口**，返回 `{ "encrypt": true/false }`，**不是 Token 接口**，不包含 `token` 字段。`result?.Token` 始终为 null，`_token` 被设为空字符串。
|
||
|
||
**实际登录接口**: `/api/central/auth/login`：
|
||
```json
|
||
POST /api/central/auth/login
|
||
{ "account": "admin", "password": "xxx" }
|
||
→ { "token": "string", "id": 0, "account": "string", "name": "string" }
|
||
```
|
||
|
||
> **注意**: MC4.0 可能对大部分 API 不强制 Token 认证（curl 示例中只有 logout 接口显式传了 header）。但当前代码逻辑错误，即便需要 Token 也无法获取。
|
||
|
||
**修复**: Mc4AuthHelper 改为先调 `conf/get` 确认加密方式，再用 `account/password` 调 `login` 获取真正的 token。
|
||
|
||
### 3.2 缺少批量点位查询（🟠 规则引擎依赖）
|
||
|
||
**缺失**: `/api/central/point/multi/value/get`
|
||
|
||
请求体 `{ "ids": [1, 2, 3] }` → 一次返回多个设备的实时值。
|
||
|
||
**影响**: 当前 B4-batch 接口逐设备调 `GetRealtimeValuesAsync`（单设备接口）。MC4.0 提供原生批量接口，应直接使用以提升规则引擎性能。
|
||
|
||
**修复**: 增加 `GetMultiRealtimeValuesAsync(List<int> deviceIds)` 方法，B4-batch 路由优先调此方法。
|
||
|
||
---
|
||
|
||
## 4. 缺失项清单
|
||
|
||
### 4.1 认证接口（3个）
|
||
|
||
| 端点 | 用途 |
|
||
|------|------|
|
||
| `/api/central/auth/conf/get` | 获取密码加密配置（已调但未正确使用） |
|
||
| `/api/central/auth/login` | 登录获取 Token |
|
||
| `/api/central/auth/logout` | 注销 |
|
||
|
||
### 4.2 设备点位（1个）
|
||
|
||
| 端点 | 用途 |
|
||
|------|------|
|
||
| `/api/central/device/point/get` | 查询设备的点位列表（用于发现设备有哪些测点） |
|
||
|
||
### 4.3 告警扩展（11个）
|
||
|
||
| 端点 | 用途 |
|
||
|------|------|
|
||
| `/api/central/alarm/custom_query_count` | 告警自定义统计数量 |
|
||
| `/api/central/alarm/custom_query` | 告警自定义查询 |
|
||
| `/api/central/alarm/get_by_point` | 按点位查询告警 |
|
||
| `/api/central/alarm/get` | 获取单个告警详情 |
|
||
| `/api/central/his_alarm/query` | 历史告警查询 |
|
||
| `/api/central/report/alarm/convergence/query` | 告警聚合报告查询 |
|
||
| `/api/central/alarm/type/add` | 添加告警类型 |
|
||
| `/api/central/alarm/type/set` | 修改告警类型 |
|
||
| `/api/central/alarm/type/del` | 删除告警类型 |
|
||
| `/api/central/alarm/type/list` | 告警类型列表 |
|
||
|
||
### 4.4 系统管理（10个）
|
||
|
||
| 端点 | 用途 |
|
||
|------|------|
|
||
| `/api/central/manager/config/set` | 设置系统配置 |
|
||
| `/api/central/manager/config/get` | 获取系统配置 |
|
||
| `/api/central/manager/db/backup` | 数据库备份 |
|
||
| `/api/central/manager/db/restore` | 数据库恢复 |
|
||
| `/api/central/manager/db/log` | 数据库日志 |
|
||
| `/api/central/manager/hisdb/backup` | 历史库备份 |
|
||
| `/api/central/manager/hisdb/restore` | 历史库恢复 |
|
||
| `/api/central/manager/hisdb/clear` | 清除历史数据 |
|
||
| `/api/central/manager/picture/clear` | 清除图片 |
|
||
| `/api/central/manager/video/clear` | 清除视频 |
|
||
|
||
---
|
||
|
||
## 5. 优先级建议
|
||
|
||
| 优先级 | 项目 | 说明 |
|
||
|:---:|------|------|
|
||
| 🔴 P0 | Mc4AuthHelper 认证修复 | 当前 Token 获取逻辑根本错误 |
|
||
| 🟠 P1 | 批量点位查询 (multi/value/get) | 规则引擎 B4-batch 缺少原生高效接口 |
|
||
| 🟡 P2 | 历史告警查询 | 管理端需要查看已结束的告警 |
|
||
| 🟡 P2 | 设备点位发现 (device/point/get) | IoT 设备入网时自动发现测点 |
|
||
| ⚪ P3 | 告警类型 CRUD | 运维操作 |
|
||
| ⚪ P3 | 系统管理接口 | 运维操作 |
|