g82tt/SecMPS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: g82tt:gateway-dev
Branches Tags
g82tt:master g82tt:gateway-dev g82tt:phase/0-infrastructure
..
compare: g82tt:master
Branches Tags
g82tt:gateway-dev g82tt:phase/0-infrastructure g82tt:master

26 Commits
gateway-de ... master

Author SHA1 Message Date
g82tt
fea3a35b95 Merge pull request 'phase/0-infrastructure' (#1) from phase/0-infrastructure into master 
Reviewed-on: #1
 2026-05-16 15:17:18 +08:00
g82tt
07dd459705 Phase0_delete_old_gateway 2026-05-16 15:12:43 +08:00
g82tt
fcd1d39641 v3.0_manual_with_gateway_assessment 2026-05-16 15:09:12 +08:00
g82tt
65f4b793d3 Gateway_VolPro_API_manual 2026-05-16 14:47:33 +08:00
g82tt
1c2d33b341 v3.0_final_tech_assessment 2026-05-16 14:41:18 +08:00
g82tt
fe90fbea3a v3.0_manual_and_db 2026-05-16 14:20:21 +08:00
g82tt
30e4187e34 v3.0_final_14_fixes_applied 2026-05-16 13:52:19 +08:00
g82tt
eda8572005 Final_assessment_report 2026-05-16 13:34:03 +08:00
g82tt
69a18d38d3 Phase0_gateway_api_specs 2026-05-16 12:56:12 +08:00
g82tt
b5195aa4d4 Phase0_sync_plan_with_db_changes 2026-05-16 12:10:18 +08:00
g82tt
7801cf5730 Phase0_PointId_replace_RegionId 2026-05-16 12:06:54 +08:00
g82tt
bf3cbc71ae Phase0_6tables_ExtraData_DGroup 2026-05-16 11:42:23 +08:00
g82tt
d669b56569 Phase0_dict_comment_details 2026-05-16 11:16:14 +08:00
g82tt
8a9a9a7338 Phase0_lowercase_varchar_dict 2026-05-16 11:10:50 +08:00
g82tt
d2071a610b Phase0_DeviceCategory_dict_val 2026-05-16 11:03:31 +08:00
g82tt
a8507aaa12 Phase0_DeviceCategory_varchar 2026-05-16 10:48:44 +08:00
g82tt
906700e0fe v2.0_final_synced_with_db_and_gateway 2026-05-16 10:45:20 +08:00
g82tt
7c69d9c55f Phase0_gateway_nodes_table 2026-05-16 05:38:32 +08:00
g82tt
839d05f75c Phase0_gateway_config 2026-05-16 04:48:29 +08:00
g82tt
65cfa40e1f Phase0_remove_DeviceType 2026-05-16 04:42:27 +08:00
g82tt
4cbe12ee5d Phase0_comment_fix 2026-05-16 04:26:29 +08:00
g82tt
d204727a07 Phase0_7tables_drop_point_table 2026-05-16 03:24:29 +08:00
g82tt
d92c3da89a Phase0_no_constraints_index_only 2026-05-16 02:30:39 +08:00
g82tt
8d6cc6fd23 Phase0_alarm_generic 2026-05-16 02:18:02 +08:00
g82tt
8dde75f7ec Phase0_pk_int_auto_incr 2026-05-15 23:45:53 +08:00
g82tt
29fedc8701 Phase0_db_init_comments 2026-05-15 23:36:03 +08:00
213 changed files with 4106 additions and 29807 deletions
Expand all files Collapse all files

4
.gitignore vendored
View File

@@ -13,7 +13,3 @@ temp.json
*.bak
tmp.bat
report_form_rollup-plugin-visualizer.html
**/bin/
**/obj/
appsettings.Production.json

102
api_sqlsugar/VolPro.Core/Utilities/VierificationCodeServices.cs
View File

@@ -27,46 +27,44 @@ namespace VolPro.Core.Utilities
canvas.Clear(SKColors.White);
// 从 fonts 文件夹加载字体文件（相对于运行目录）
string fontPath = Path.Combine(AppContext.BaseDirectory, "fonts", "DejaVuSans.ttf");
if (!File.Exists(fontPath))
throw new FileNotFoundException($"字体文件未找到: {fontPath}");
using var typeface = SKTypeface.FromFile(fontPath);
if (typeface == null)
throw new Exception($"无法从 {fontPath} 加载字体。");
using var pen = new SKPaint();
pen.FakeBoldText = true;
pen.Style = SKPaintStyle.Fill;
pen.TextSize = 20;
pen.Typeface = typeface; // 使用加载的本地字体
pen.TextSize = 20;// 0.6f * info.Width * pen.TextSize / pen.MeasureText(code);
// 绘制随机字符
//绘制随机字符
for (int i = 0; i < code.Length; i++)
{
pen.Color = random.GetRandom(colors); // 假设 colors 是外部定义的静态颜色数组
var point = new SKPoint
pen.Color = random.GetRandom(colors);//随机颜色索引值
pen.Typeface = SKTypeface.FromFamilyName("DejaVu Sans", 700, 20, SKFontStyleSlant.Italic);//配置字体
var point = new SKPoint()
{
X = i * 16,
Y = 22
Y = 22// info.Height - ((i + 1) % 2 == 0 ? 2 : 4),
};
canvas.DrawText(code.Substring(i, 1), point, pen);
canvas.DrawText(code.Substring(i, 1), point, pen);//绘制一个验证字符
}
// 绘制噪点
var points = Enumerable.Range(0, 100).Select(
_ => new SKPoint(random.Next(bitmap.Width), random.Next(bitmap.Height))
).ToArray();
canvas.DrawPoints(SKPointMode.Points, points, pen);
canvas.DrawPoints(
SKPointMode.Points,
points,
pen);
// 绘制贝塞尔线条（原有逻辑存在 p1~p4 全为零的问题，此处保留原样）
//绘制贝塞尔线条
for (int i = 0; i < 2; i++)
{
var p1 = new SKPoint(0, 0);
var p2 = new SKPoint(0, 0);
var p3 = new SKPoint(0, 0);
var p4 = new SKPoint(0, 0);
var touchPoints = new SKPoint[] { p1, p2, p3, p4 };
using var bPen = new SKPaint();
@@ -78,76 +76,8 @@ namespace VolPro.Core.Utilities
path.CubicTo(touchPoints[1], touchPoints[2], touchPoints[3]);
canvas.DrawPath(path, bPen);
}
return bitmap.ToBase64String(SKEncodedImageFormat.Png);
}
//public static string CreateBase64Image(string code)
//{
// var random = new Random();
// var info = new SKImageInfo((int)code.Length * 18, 32);
// using var bitmap = new SKBitmap(info);
// using var canvas = new SKCanvas(bitmap);
// canvas.Clear(SKColors.White);
// using var pen = new SKPaint();
// pen.FakeBoldText = true;
// pen.Style = SKPaintStyle.Fill;
// pen.TextSize = 20;// 0.6f * info.Width * pen.TextSize / pen.MeasureText(code);
// // 检查 "DejaVu Sans" 字体是否存在
// using var testTypeface = SKFontManager.Default.MatchFamily("DejaVu Sans");
// if (testTypeface == null || string.IsNullOrEmpty(testTypeface.FamilyName))
// {
// throw new Exception("系统中未找到 'DejaVu Sans' 字体。");
// }
// //绘制随机字符
// for (int i = 0; i < code.Length; i++)
// {
// pen.Color = random.GetRandom(colors);//随机颜色索引值
// pen.Typeface = SKTypeface.FromFamilyName("DejaVu Sans", 700, 20, SKFontStyleSlant.Italic);//配置字体
// var point = new SKPoint()
// {
// X = i * 16,
// Y = 22// info.Height - ((i + 1) % 2 == 0 ? 2 : 4),
// };
// canvas.DrawText(code.Substring(i, 1), point, pen);//绘制一个验证字符
// }
// // 绘制噪点
// var points = Enumerable.Range(0, 100).Select(
// _ => new SKPoint(random.Next(bitmap.Width), random.Next(bitmap.Height))
// ).ToArray();
// canvas.DrawPoints(
// SKPointMode.Points,
// points,
// pen);
// //绘制贝塞尔线条
// for (int i = 0; i < 2; i++)
// {
// var p1 = new SKPoint(0, 0);
// var p2 = new SKPoint(0, 0);
// var p3 = new SKPoint(0, 0);
// var p4 = new SKPoint(0, 0);
// var touchPoints = new SKPoint[] { p1, p2, p3, p4 };
// using var bPen = new SKPaint();
// bPen.Color = random.GetRandom(colors);
// bPen.Style = SKPaintStyle.Stroke;
// using var path = new SKPath();
// path.MoveTo(touchPoints[0]);
// path.CubicTo(touchPoints[1], touchPoints[2], touchPoints[3]);
// canvas.DrawPath(path, bPen);
// }
// return bitmap.ToBase64String(SKEncodedImageFormat.Png);
//}
public static T GetRandom<T>(this Random random, T[] tArray)
{

293
api_sqlsugar/VolPro.Entity/DomainModels/device_manager/base_device.cs
View File

@@ -1,293 +0,0 @@
/*
*代码由框架生成,任何更改都可能导致被代码生成器覆盖
*如果数据库字段发生变化，请在代码生器重新生成此Model
*/
using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using SqlSugar;
using VolPro.Entity.SystemModels;
namespace VolPro.Entity.DomainModels
{
[Entity(TableCnName = "设备管理",TableName = "base_device",DetailTable = new Type[] { typeof(video_channel),typeof(iot_devicedata),typeof(iot_alarm)},DetailTableCnName = "视频通道,数据归档,告警记录",DBServer = "ServiceDbContext")]
public partial class base_device:ServiceEntity
{
/// <summary>
///设备ID
/// </summary>
[SugarColumn(IsPrimaryKey = true, IsIdentity = true)]
[Key]
[Display(Name ="设备ID")]
[Column(TypeName="int")]
[Editable(true)]
[Required(AllowEmptyStrings=false)]
public int DeviceId { get; set; }
/// <summary>
///设备名称
/// </summary>
[Display(Name ="设备名称")]
[MaxLength(100)]
[Column(TypeName="nvarchar(100)")]
[Editable(true)]
[Required(AllowEmptyStrings=false)]
public string DeviceName { get; set; }
/// <summary>
///来源适配器(类型:实例)
/// </summary>
[Display(Name ="来源适配器(类型:实例)")]
[MaxLength(50)]
[Column(TypeName="nvarchar(50)")]
[Editable(true)]
public string AdapterCode { get; set; }
/// <summary>
///源系统设备ID
/// </summary>
[Display(Name ="源系统设备ID")]
[MaxLength(100)]
[Column(TypeName="nvarchar(100)")]
[Editable(true)]
public string SourceId { get; set; }
/// <summary>
///设备种类(数据字典)
/// </summary>
[Display(Name ="设备种类(数据字典)")]
[MaxLength(50)]
[Column(TypeName="nvarchar(50)")]
[Editable(true)]
[Required(AllowEmptyStrings=false)]
public string DeviceCategory { get; set; }
/// <summary>
///设备分组(数据字典)
/// </summary>
[Display(Name ="设备分组(数据字典)")]
[MaxLength(20)]
[Column(TypeName="nvarchar(20)")]
[Editable(true)]
[Required(AllowEmptyStrings=false)]
public string DeviceGroup { get; set; }
/// <summary>
///所属点位ID
/// </summary>
[Display(Name ="所属点位ID")]
[Column(TypeName="int")]
[Editable(true)]
public int? PointId { get; set; }
/// <summary>
///是否父设备(数据字典)
/// </summary>
[Display(Name ="是否父设备(数据字典)")]
[MaxLength(20)]
[Column(TypeName="nvarchar(20)")]
[Editable(true)]
[Required(AllowEmptyStrings=false)]
public string IsParent { get; set; }
/// <summary>
///父设备ID(自引用,子设备挂父设备下)
/// </summary>
[Display(Name ="父设备ID(自引用,子设备挂父设备下)")]
[Column(TypeName="int")]
[Editable(true)]
public int? ParentDeviceId { get; set; }
/// <summary>
///在线状态(数据字典)
/// </summary>
[Display(Name ="在线状态(数据字典)")]
[MaxLength(20)]
[Column(TypeName="nvarchar(20)")]
[Editable(true)]
public string IsOnline { get; set; }
/// <summary>
///IP地址
/// </summary>
[Display(Name ="IP地址")]
[MaxLength(50)]
[Column(TypeName="nvarchar(50)")]
[Editable(true)]
public string IpAddress { get; set; }
/// <summary>
///端口
/// </summary>
[Display(Name ="端口")]
[Column(TypeName="int")]
[Editable(true)]
public int? Port { get; set; }
/// <summary>
///安装位置
/// </summary>
[Display(Name ="安装位置")]
[MaxLength(200)]
[Column(TypeName="nvarchar(200)")]
[Editable(true)]
public string Location { get; set; }
/// <summary>
///纬度
/// </summary>
[Display(Name ="纬度")]
[Column(TypeName="double")]
[Editable(true)]
public decimal? Lat { get; set; }
/// <summary>
///经度
/// </summary>
[Display(Name ="经度")]
[Column(TypeName="double")]
[Editable(true)]
public decimal? Lng { get; set; }
/// <summary>
///三维地图模型ID
/// </summary>
[Display(Name ="三维地图模型ID")]
[MaxLength(100)]
[Column(TypeName="nvarchar(100)")]
[Editable(true)]
public string MapModelId { get; set; }
/// <summary>
///模型缩放比例
/// </summary>
[Display(Name ="模型缩放比例")]
[Column(TypeName="decimal")]
[Editable(true)]
public decimal? MapModelScale { get; set; }
/// <summary>
///模型旋转角度(JSON)
/// </summary>
[Display(Name ="模型旋转角度(JSON)")]
[MaxLength(100)]
[Column(TypeName="nvarchar(100)")]
[Editable(true)]
public string MapModelRotation { get; set; }
/// <summary>
///适配器扩展数据JSON(Owl/MC4/门禁字段均存于此)
/// </summary>
[Display(Name ="适配器扩展数据JSON(Owl/MC4/门禁字段均存于此)")]
[Column(TypeName="nvarchar(max)")]
[Editable(true)]
public string ExtraData { get; set; }
/// <summary>
///上次同步时间
/// </summary>
[Display(Name ="上次同步时间")]
[Column(TypeName="datetime")]
[Editable(true)]
public DateTime? LastSyncTime { get; set; }
/// <summary>
///启用状态(数据字典)
/// </summary>
[Display(Name ="启用状态(数据字典)")]
[MaxLength(20)]
[Column(TypeName="nvarchar(20)")]
[Editable(true)]
public string Enable { get; set; }
/// <summary>
///备注
/// </summary>
[Display(Name ="备注")]
[MaxLength(500)]
[Column(TypeName="nvarchar(500)")]
[Editable(true)]
public string Remark { get; set; }
/// <summary>
///创建人ID
/// </summary>
[Display(Name ="创建人ID")]
[Column(TypeName="int")]
[Editable(true)]
public int? CreateID { get; set; }
/// <summary>
///创建人
/// </summary>
[Display(Name ="创建人")]
[MaxLength(50)]
[Column(TypeName="nvarchar(50)")]
[Editable(true)]
public string Creator { get; set; }
/// <summary>
///创建时间
/// </summary>
[Display(Name ="创建时间")]
[Column(TypeName="datetime")]
[Editable(true)]
public DateTime? CreateDate { get; set; }
/// <summary>
///修改人ID
/// </summary>
[Display(Name ="修改人ID")]
[Column(TypeName="int")]
[Editable(true)]
public int? ModifyID { get; set; }
/// <summary>
///修改人
/// </summary>
[Display(Name ="修改人")]
[MaxLength(50)]
[Column(TypeName="nvarchar(50)")]
[Editable(true)]
public string Modifier { get; set; }
/// <summary>
///修改时间
/// </summary>
[Display(Name ="修改时间")]
[Column(TypeName="datetime")]
[Editable(true)]
public DateTime? ModifyDate { get; set; }
/// <summary>
///所属网关节点ID
/// </summary>
[SugarColumn(IsPrimaryKey = true, IsIdentity = true)]
[Key]
[Display(Name ="所属网关节点ID")]
[Column(TypeName="int")]
[Editable(true)]
public int? NodeId { get; set; }
[Display(Name ="视频通道")]
[ForeignKey("DeviceId")][Navigate(NavigateType.OneToMany,nameof(DeviceId),nameof(DeviceId))]
public List<video_channel> video_channel { get; set; }
[Display(Name ="数据归档")]
[ForeignKey("DeviceId")][Navigate(NavigateType.OneToMany,nameof(DeviceId),nameof(DeviceId))]
public List<iot_devicedata> iot_devicedata { get; set; }
[Display(Name ="告警记录")]
[ForeignKey("DeviceId")][Navigate(NavigateType.OneToMany,nameof(DeviceId),nameof(DeviceId))]
public List<iot_alarm> iot_alarm { get; set; }
}
}

175
api_sqlsugar/VolPro.Entity/DomainModels/device_manager/gateway_nodes.cs
View File

@@ -1,175 +0,0 @@
/*
*代码由框架生成,任何更改都可能导致被代码生成器覆盖
*如果数据库字段发生变化，请在代码生器重新生成此Model
*/
using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using SqlSugar;
using VolPro.Entity.SystemModels;
namespace VolPro.Entity.DomainModels
{
[Entity(TableCnName = "设备管理_网关节点",TableName = "gateway_nodes",DetailTable = new Type[] { typeof(base_device)},DetailTableCnName = "设备管理",DBServer = "ServiceDbContext")]
public partial class gateway_nodes:ServiceEntity
{
/// <summary>
///网关节点ID
/// </summary>
[SugarColumn(IsPrimaryKey = true, IsIdentity = true)]
[Key]
[Display(Name ="网关节点ID")]
[Column(TypeName="int")]
[Editable(true)]
[Required(AllowEmptyStrings=false)]
public int NodeId { get; set; }
/// <summary>
///网关唯一编码
/// </summary>
[SugarColumn(IsPrimaryKey = true)]
[Key]
[Display(Name ="网关唯一编码")]
[MaxLength(50)]
[Column(TypeName="nvarchar(50)")]
[Editable(true)]
[Required(AllowEmptyStrings=false)]
public string NodeCode { get; set; }
/// <summary>
///网关名称
/// </summary>
[Display(Name ="网关名称")]
[MaxLength(100)]
[Column(TypeName="nvarchar(100)")]
[Editable(true)]
[Required(AllowEmptyStrings=false)]
public string NodeName { get; set; }
/// <summary>
///认证令牌
/// </summary>
[Display(Name ="认证令牌")]
[MaxLength(100)]
[Column(TypeName="nvarchar(100)")]
[Editable(true)]
[Required(AllowEmptyStrings=false)]
public string NodeToken { get; set; }
/// <summary>
///支持的适配器类型(网关上报)
/// </summary>
[Display(Name ="支持的适配器类型(网关上报)")]
[MaxLength(200)]
[Column(TypeName="nvarchar(200)")]
[Editable(true)]
public string AdapterTypes { get; set; }
/// <summary>
///网关自身地址(网关上报)
/// </summary>
[Display(Name ="网关自身地址(网关上报)")]
[MaxLength(200)]
[Column(TypeName="nvarchar(200)")]
[Editable(true)]
public string BaseUrl { get; set; }
/// <summary>
///上次心跳时间
/// </summary>
[Display(Name ="上次心跳时间")]
[Column(TypeName="datetime")]
[Editable(true)]
public DateTime? LastHeartbeat { get; set; }
/// <summary>
///在线状态(数据字典：在线/离线)
/// </summary>
[SugarColumn(IsPrimaryKey = true)]
[Key]
[Display(Name ="在线状态(数据字典：在线/离线)")]
[MaxLength(20)]
[Column(TypeName="nvarchar(20)")]
[Editable(true)]
public string IsOnline { get; set; }
/// <summary>
///启用状态(数据字典：启用/禁用)
/// </summary>
[Display(Name ="启用状态(数据字典：启用/禁用)")]
[MaxLength(20)]
[Column(TypeName="nvarchar(20)")]
[Editable(true)]
public string Enable { get; set; }
/// <summary>
///备注
/// </summary>
[Display(Name ="备注")]
[MaxLength(500)]
[Column(TypeName="nvarchar(500)")]
[Editable(true)]
public string Remark { get; set; }
/// <summary>
///创建人ID
/// </summary>
[Display(Name ="创建人ID")]
[Column(TypeName="int")]
[Editable(true)]
public int? CreateID { get; set; }
/// <summary>
///创建人
/// </summary>
[Display(Name ="创建人")]
[MaxLength(50)]
[Column(TypeName="nvarchar(50)")]
[Editable(true)]
public string Creator { get; set; }
/// <summary>
///创建时间
/// </summary>
[Display(Name ="创建时间")]
[Column(TypeName="datetime")]
[Editable(true)]
public DateTime? CreateDate { get; set; }
/// <summary>
///修改人ID
/// </summary>
[Display(Name ="修改人ID")]
[Column(TypeName="int")]
[Editable(true)]
public int? ModifyID { get; set; }
/// <summary>
///修改人
/// </summary>
[Display(Name ="修改人")]
[MaxLength(50)]
[Column(TypeName="nvarchar(50)")]
[Editable(true)]
public string Modifier { get; set; }
/// <summary>
///修改时间
/// </summary>
[Display(Name ="修改时间")]
[Column(TypeName="datetime")]
[Editable(true)]
public DateTime? ModifyDate { get; set; }
[Display(Name ="设备管理")]
[ForeignKey("NodeId")][Navigate(NavigateType.OneToMany,nameof(NodeId),nameof(NodeId))]
public List<base_device> base_device { get; set; }
}
}

154
api_sqlsugar/VolPro.Entity/DomainModels/device_manager/iot_alarm.cs
View File

@@ -1,154 +0,0 @@
/*
*代码由框架生成,任何更改都可能导致被代码生成器覆盖
*如果数据库字段发生变化，请在代码生器重新生成此Model
*/
using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using SqlSugar;
using VolPro.Entity.SystemModels;
namespace VolPro.Entity.DomainModels
{
[Entity(TableCnName = "设备管理_告警记录",TableName = "iot_alarm",DBServer = "ServiceDbContext")]
public partial class iot_alarm:ServiceEntity
{
/// <summary>
///告警ID
/// </summary>
[SugarColumn(IsPrimaryKey = true, IsIdentity = true)]
[Key]
[Display(Name ="告警ID")]
[Column(TypeName="int")]
[Editable(true)]
[Required(AllowEmptyStrings=false)]
public int AlarmId { get; set; }
/// <summary>
///源系统告警ID
/// </summary>
[SugarColumn(IsPrimaryKey = true)]
[Key]
[Display(Name ="源系统告警ID")]
[MaxLength(100)]
[Column(TypeName="nvarchar(100)")]
[Editable(true)]
[Required(AllowEmptyStrings=false)]
public string SourceAlarmId { get; set; }
/// <summary>
///关联设备ID
/// </summary>
[SugarColumn(IsPrimaryKey = true, IsIdentity = true)]
[Key]
[Display(Name ="关联设备ID")]
[Column(TypeName="int")]
[Editable(true)]
[Required(AllowEmptyStrings=false)]
public int DeviceId { get; set; }
/// <summary>
///告警类型
/// </summary>
[Display(Name ="告警类型")]
[Column(TypeName="int")]
[Editable(true)]
public int? AlarmType { get; set; }
/// <summary>
///告警等级(数据字典：提示/普通/重要/紧急)
/// </summary>
[SugarColumn(IsPrimaryKey = true)]
[Key]
[Display(Name ="告警等级(数据字典：提示/普通/重要/紧急)")]
[MaxLength(20)]
[Column(TypeName="nvarchar(20)")]
[Editable(true)]
public string AlarmLevel { get; set; }
/// <summary>
///告警描述
/// </summary>
[Display(Name ="告警描述")]
[MaxLength(500)]
[Column(TypeName="nvarchar(500)")]
[Editable(true)]
public string AlarmDesc { get; set; }
/// <summary>
///触发值
/// </summary>
[Display(Name ="触发值")]
[Column(TypeName="double")]
[Editable(true)]
public decimal? AlarmValue { get; set; }
/// <summary>
///告警开始时间
/// </summary>
[SugarColumn(IsPrimaryKey = true)]
[Key]
[Display(Name ="告警开始时间")]
[Column(TypeName="datetime")]
[Editable(true)]
[Required(AllowEmptyStrings=false)]
public DateTime StartTime { get; set; }
/// <summary>
///告警结束时间
/// </summary>
[Display(Name ="告警结束时间")]
[Column(TypeName="datetime")]
[Editable(true)]
public DateTime? EndTime { get; set; }
/// <summary>
///确认时间
/// </summary>
[Display(Name ="确认时间")]
[Column(TypeName="datetime")]
[Editable(true)]
public DateTime? ConfirmTime { get; set; }
/// <summary>
///确认人
/// </summary>
[Display(Name ="确认人")]
[MaxLength(50)]
[Column(TypeName="nvarchar(50)")]
[Editable(true)]
public string ConfirmUser { get; set; }
/// <summary>
///状态(数据字典：未确认/已确认/已结束)
/// </summary>
[Display(Name ="状态(数据字典：未确认/已确认/已结束)")]
[MaxLength(20)]
[Column(TypeName="nvarchar(20)")]
[Editable(true)]
public string State { get; set; }
/// <summary>
///来源适配器
/// </summary>
[Display(Name ="来源适配器")]
[MaxLength(50)]
[Column(TypeName="nvarchar(50)")]
[Editable(true)]
public string AdapterCode { get; set; }
/// <summary>
///创建时间
/// </summary>
[Display(Name ="创建时间")]
[Column(TypeName="datetime")]
[Editable(true)]
public DateTime? CreateDate { get; set; }
}
}

87
api_sqlsugar/VolPro.Entity/DomainModels/device_manager/iot_devicedata.cs
View File

@@ -1,87 +0,0 @@
/*
*代码由框架生成,任何更改都可能导致被代码生成器覆盖
*如果数据库字段发生变化，请在代码生器重新生成此Model
*/
using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using SqlSugar;
using VolPro.Entity.SystemModels;
namespace VolPro.Entity.DomainModels
{
[Entity(TableCnName = "设备管理_数据归档",TableName = "iot_devicedata",DBServer = "ServiceDbContext")]
public partial class iot_devicedata:ServiceEntity
{
/// <summary>
///数据记录ID
/// </summary>
[SugarColumn(IsPrimaryKey = true, IsIdentity = true)]
[Key]
[Display(Name ="数据记录ID")]
[Column(TypeName="int")]
[Editable(true)]
[Required(AllowEmptyStrings=false)]
public int DataId { get; set; }
/// <summary>
///关联设备ID(子设备/点位)
/// </summary>
[SugarColumn(IsPrimaryKey = true, IsIdentity = true)]
[Key]
[Display(Name ="关联设备ID(子设备/点位)")]
[Column(TypeName="int")]
[Editable(true)]
[Required(AllowEmptyStrings=false)]
public int DeviceId { get; set; }
/// <summary>
///点位数值
/// </summary>
[Display(Name ="点位数值")]
[Column(TypeName="double")]
[Editable(true)]
public decimal? PointValue { get; set; }
/// <summary>
///数据更新时间
/// </summary>
[Display(Name ="数据更新时间")]
[Column(TypeName="datetime")]
[Editable(true)]
[Required(AllowEmptyStrings=false)]
public DateTime UpdateTime { get; set; }
/// <summary>
///采集间隔(毫秒)
/// </summary>
[Display(Name ="采集间隔(毫秒)")]
[Column(TypeName="int")]
[Editable(true)]
public int? Interval { get; set; }
/// <summary>
///归档类型(1小时/2日)
/// </summary>
[Display(Name ="归档类型(1小时/2日)")]
[Column(TypeName="int")]
[Editable(true)]
public int? ArchiveType { get; set; }
/// <summary>
///创建时间
/// </summary>
[SugarColumn(IsPrimaryKey = true)]
[Key]
[Display(Name ="创建时间")]
[Column(TypeName="datetime")]
[Editable(true)]
public DateTime? CreateDate { get; set; }
}
}

42
api_sqlsugar/VolPro.Entity/DomainModels/device_manager/partial/base_device.cs
View File

@@ -1,42 +0,0 @@
/*
*代码由框架生成,任何更改都可能导致被代码生成器覆盖
*如果数据库字段发生变化，请在代码生器重新生成此Model
*/
using System;
using System.Collections.Generic;
using SqlSugar;
using VolPro.Entity.SystemModels;
namespace VolPro.Entity.DomainModels
{
public partial class base_device
{
/////// <summary>导航属性：关联视频通道扩展记录（一对一）</summary>
////[Navigate(NavigateType.OneToOne, nameof(DeviceId), nameof(video_channel.DeviceId))]
////public video_channel? VideoChannel { get; set; }
/////// <summary>导航属性：关联告警记录（一对多）</summary>
////[Navigate(NavigateType.OneToMany, nameof(DeviceId), nameof(iot_alarm.DeviceId))]
////public List<iot_alarm>? Alarms { get; set; }
/////// <summary>导航属性：关联数据归档（一对多）</summary>
////[Navigate(NavigateType.OneToMany, nameof(DeviceId), nameof(iot_devicedata.DeviceId))]
////public List<iot_devicedata>? DeviceData { get; set; }
/// <summary>
/// 网关字段白名单。网关同步时，只有此集合中的字段会被覆盖，
/// 其他字段（DeviceName/DeviceCategory/DeviceGroup/Location/MapModelId等）
/// 由管理员在管理端维护，同步不覆盖。
/// </summary>
public static readonly HashSet<string> GatewayFields = new()
{
nameof(IsOnline),
nameof(IsParent),
nameof(ParentDeviceId),
nameof(ExtraData),
nameof(IpAddress),
nameof(Port),
nameof(LastSyncTime)
};
}
}

28
api_sqlsugar/VolPro.Entity/DomainModels/device_manager/partial/gateway_nodes.cs
View File

@@ -1,28 +0,0 @@
/*
*代码由框架生成,任何更改都可能导致被代码生成器覆盖
*如果数据库字段发生变化，请在代码生器重新生成此Model
*/
using System;
using System.Collections.Generic;
using System.Linq;
using SqlSugar;
using VolPro.Entity.SystemModels;
namespace VolPro.Entity.DomainModels
{
public partial class gateway_nodes
{
/// <summary>
/// 适配器类型列表。从 AdapterTypes（逗号分隔字符串）解析。
/// 示例："Owl:main,MC4:31ku" → ["Owl:main","MC4:31ku"]
/// </summary>
[SugarColumn(IsIgnore = true)]
public List<string> AdapterList
{
get => string.IsNullOrEmpty(AdapterTypes)
? new List<string>()
: AdapterTypes.Split(',').Select(x => x.Trim()).Where(x => !string.IsNullOrEmpty(x)).ToList();
set => AdapterTypes = value != null ? string.Join(",", value) : "";
}
}
}

22
api_sqlsugar/VolPro.Entity/DomainModels/device_manager/partial/iot_alarm.cs
View File

@@ -1,22 +0,0 @@
/*
*代码由框架生成,任何更改都可能导致被代码生成器覆盖
*如果数据库字段发生变化，请在代码生器重新生成此Model
*/
using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using SqlSugar;
using VolPro.Entity.SystemModels;
namespace VolPro.Entity.DomainModels
{
public partial class iot_alarm
{
//此处配置字段(字段配置见此model的另一个partial),如果表中没有此字段请加上[SugarColumn(IsIgnore = true)]属性，否则会异常
}
}

22
api_sqlsugar/VolPro.Entity/DomainModels/device_manager/partial/iot_devicedata.cs
View File

@@ -1,22 +0,0 @@
/*
*代码由框架生成,任何更改都可能导致被代码生成器覆盖
*如果数据库字段发生变化，请在代码生器重新生成此Model
*/
using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using SqlSugar;
using VolPro.Entity.SystemModels;
namespace VolPro.Entity.DomainModels
{
public partial class iot_devicedata
{
//此处配置字段(字段配置见此model的另一个partial),如果表中没有此字段请加上[SugarColumn(IsIgnore = true)]属性，否则会异常
}
}

22
api_sqlsugar/VolPro.Entity/DomainModels/device_manager/partial/video_channel.cs
View File

@@ -1,22 +0,0 @@
/*
*代码由框架生成,任何更改都可能导致被代码生成器覆盖
*如果数据库字段发生变化，请在代码生器重新生成此Model
*/
using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using SqlSugar;
using VolPro.Entity.SystemModels;
namespace VolPro.Entity.DomainModels
{
public partial class video_channel
{
//此处配置字段(字段配置见此model的另一个partial),如果表中没有此字段请加上[SugarColumn(IsIgnore = true)]属性，否则会异常
}
}

22
api_sqlsugar/VolPro.Entity/DomainModels/device_manager/partial/video_record.cs
View File

@@ -1,22 +0,0 @@
/*
*代码由框架生成,任何更改都可能导致被代码生成器覆盖
*如果数据库字段发生变化，请在代码生器重新生成此Model
*/
using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using SqlSugar;
using VolPro.Entity.SystemModels;
namespace VolPro.Entity.DomainModels
{
public partial class video_record
{
//此处配置字段(字段配置见此model的另一个partial),如果表中没有此字段请加上[SugarColumn(IsIgnore = true)]属性，否则会异常
}
}

120
api_sqlsugar/VolPro.Entity/DomainModels/device_manager/video_channel.cs
View File

@@ -1,120 +0,0 @@
/*
*代码由框架生成,任何更改都可能导致被代码生成器覆盖
*如果数据库字段发生变化，请在代码生器重新生成此Model
*/
using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using SqlSugar;
using VolPro.Entity.SystemModels;
namespace VolPro.Entity.DomainModels
{
[Entity(TableCnName = "设备管理_视频通道",TableName = "video_channel",DetailTable = new Type[] { typeof(video_record)},DetailTableCnName = "录像记录",DBServer = "ServiceDbContext")]
public partial class video_channel:ServiceEntity
{
/// <summary>
///通道记录ID
/// </summary>
[SugarColumn(IsPrimaryKey = true, IsIdentity = true)]
[Key]
[Display(Name ="通道记录ID")]
[Column(TypeName="int")]
[Editable(true)]
[Required(AllowEmptyStrings=false)]
public int ChannelId { get; set; }
/// <summary>
///Owl系统通道ID
/// </summary>
[SugarColumn(IsPrimaryKey = true)]
[Key]
[Display(Name ="Owl系统通道ID")]
[MaxLength(64)]
[Column(TypeName="nvarchar(64)")]
[Editable(true)]
[Required(AllowEmptyStrings=false)]
public string OwlChannelId { get; set; }
/// <summary>
///关联Base_Device设备ID
/// </summary>
[SugarColumn(IsPrimaryKey = true, IsIdentity = true)]
[Key]
[Display(Name ="关联Base_Device设备ID")]
[Column(TypeName="int")]
[Editable(true)]
[Required(AllowEmptyStrings=false)]
public int DeviceId { get; set; }
/// <summary>
///Owl流应用名
/// </summary>
[Display(Name ="Owl流应用名")]
[MaxLength(50)]
[Column(TypeName="nvarchar(50)")]
[Editable(true)]
public string OwlStreamApp { get; set; }
/// <summary>
///Owl流名称
/// </summary>
[Display(Name ="Owl流名称")]
[MaxLength(100)]
[Column(TypeName="nvarchar(100)")]
[Editable(true)]
public string OwlStreamName { get; set; }
/// <summary>
///是否支持云台
/// </summary>
[Display(Name ="是否支持云台")]
[Column(TypeName="tinyint")]
[Editable(true)]
public byte? HasPtz { get; set; }
/// <summary>
///是否支持录像
/// </summary>
[Display(Name ="是否支持录像")]
[Column(TypeName="tinyint")]
[Editable(true)]
public byte? HasRecording { get; set; }
/// <summary>
///录像模式
/// </summary>
[Display(Name ="录像模式")]
[Column(TypeName="int")]
[Editable(true)]
public int? RecordMode { get; set; }
/// <summary>
///快照地址
/// </summary>
[Display(Name ="快照地址")]
[MaxLength(500)]
[Column(TypeName="nvarchar(500)")]
[Editable(true)]
public string SnapshotUrl { get; set; }
/// <summary>
///创建时间
/// </summary>
[Display(Name ="创建时间")]
[Column(TypeName="datetime")]
[Editable(true)]
public DateTime? CreateDate { get; set; }
[Display(Name ="录像记录")]
[ForeignKey("ChannelId")][Navigate(NavigateType.OneToMany,nameof(ChannelId),nameof(ChannelId))]
public List<video_record> video_record { get; set; }
}
}

123
api_sqlsugar/VolPro.Entity/DomainModels/device_manager/video_record.cs
View File

@@ -1,123 +0,0 @@
/*
*代码由框架生成,任何更改都可能导致被代码生成器覆盖
*如果数据库字段发生变化，请在代码生器重新生成此Model
*/
using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using SqlSugar;
using VolPro.Entity.SystemModels;
namespace VolPro.Entity.DomainModels
{
[Entity(TableCnName = "设备管理_录像记录",TableName = "video_record",DBServer = "ServiceDbContext")]
public partial class video_record:ServiceEntity
{
/// <summary>
///录像记录ID
/// </summary>
[SugarColumn(IsPrimaryKey = true, IsIdentity = true)]
[Key]
[Display(Name ="录像记录ID")]
[Column(TypeName="int")]
[Editable(true)]
[Required(AllowEmptyStrings=false)]
public int RecordId { get; set; }
/// <summary>
///关联通道ID
/// </summary>
[SugarColumn(IsPrimaryKey = true, IsIdentity = true)]
[Key]
[Display(Name ="关联通道ID")]
[Column(TypeName="int")]
[Editable(true)]
[Required(AllowEmptyStrings=false)]
public int ChannelId { get; set; }
/// <summary>
///Owl录像记录ID
/// </summary>
[Display(Name ="Owl录像记录ID")]
[Column(TypeName="int")]
[Editable(true)]
[Required(AllowEmptyStrings=false)]
public int OwlRecordId { get; set; }
/// <summary>
///应用名
/// </summary>
[Display(Name ="应用名")]
[MaxLength(50)]
[Column(TypeName="nvarchar(50)")]
[Editable(true)]
public string App { get; set; }
/// <summary>
///流ID
/// </summary>
[Display(Name ="流ID")]
[MaxLength(100)]
[Column(TypeName="nvarchar(100)")]
[Editable(true)]
public string Stream { get; set; }
/// <summary>
///录像开始时间
/// </summary>
[SugarColumn(IsPrimaryKey = true)]
[Key]
[Display(Name ="录像开始时间")]
[Column(TypeName="datetime")]
[Editable(true)]
[Required(AllowEmptyStrings=false)]
public DateTime StartedAt { get; set; }
/// <summary>
///录像结束时间
/// </summary>
[Display(Name ="录像结束时间")]
[Column(TypeName="datetime")]
[Editable(true)]
public DateTime? EndedAt { get; set; }
/// <summary>
///录像时长(秒)
/// </summary>
[Display(Name ="录像时长(秒)")]
[Column(TypeName="double")]
[Editable(true)]
public decimal? Duration { get; set; }
/// <summary>
///文件路径
/// </summary>
[Display(Name ="文件路径")]
[MaxLength(500)]
[Column(TypeName="nvarchar(500)")]
[Editable(true)]
public string FilePath { get; set; }
/// <summary>
///文件大小(字节)
/// </summary>
[Display(Name ="文件大小(字节)")]
[Column(TypeName="bigint")]
[Editable(true)]
public long? FileSize { get; set; }
/// <summary>
///创建时间
/// </summary>
[Display(Name ="创建时间")]
[Column(TypeName="datetime")]
[Editable(true)]
public DateTime? CreateDate { get; set; }
}
}

127
api_sqlsugar/VolPro.WebApi/Controllers/Warehouse/Partial/base_deviceController.cs
View File

@@ -1,127 +0,0 @@
/*
*设备管理扩展 — 区域树 + 点位设备列表
*所有改动在 Partial 目录，不破坏框架可升级性
*/
using Microsoft.AspNetCore.Mvc;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.AspNetCore.Http;
using VolPro.Entity.DomainModels;
using Warehouse.IServices;
using System.Linq;
using Microsoft.EntityFrameworkCore;
namespace Warehouse.Controllers
{
public partial class base_deviceController
{
private readonly Ibase_deviceService _service;//访问业务代码
private readonly Iwarehouse_regionsService _regionsService;
private readonly Iwarehouse_devicepointService _pointService;
private readonly IHttpContextAccessor _httpContextAccessor;
[ActivatorUtilitiesConstructor]
public base_deviceController(
Ibase_deviceService service,
Iwarehouse_regionsService regionsService,
Iwarehouse_devicepointService pointService,
IHttpContextAccessor httpContextAccessor
)
: base(service)
{
_service = service;
_regionsService = regionsService;
_pointService = pointService;
_httpContextAccessor = httpContextAccessor;
}
/// <summary>
/// 获取区域→点位→设备树。
/// 用于管理端左侧树形控件展示层级结构。
/// 格式: [{ id, label, type:"region", children: [{ id, label, type:"point", deviceCount }] }]
/// </summary>
[HttpGet]
[Route("/api/DeviceManager/GetRegionTree")]
public async Task<IActionResult> GetRegionTree()
{
// 查所有区域
var regions = await _regionsService.FindAsIQueryable(x => true).ToListAsync();
// 查所有点位
var points = await _pointService.FindAsIQueryable(x => true).ToListAsync();
// 统计每个点位下的设备数量
//var deviceCounts = new Dictionary<int, int>();
//var allDevices = await _service.FindAsIQueryable(x => true)
// .Where(x => x.PointId != null)
// .GroupBy(x => x.PointId!.Value)
// .Select(g => new { PointId = g.Key, Count = g.Count() })
// .ToListAsync();
var deviceCounts = new Dictionary<int, int>();
var devices = await _service.FindAsIQueryable(x => x.PointId != null)
.Select(x => new { x.PointId })
.ToListAsync();
deviceCounts = devices
.Where(x => x.PointId.HasValue)
.GroupBy(x => x.PointId!.Value)
.ToDictionary(g => g.Key, g => g.Count());
// 构建树形结构
var tree = new List<object>();
foreach (var region in regions)
{
var regionChildren = points
.Where(p => p.RegionId == region.Id)
.Select(p => new
{
id = $"p_{p.PointID}",
label = p.PointName ?? $"点位{p.PointID}",
type = "point",
deviceCount = deviceCounts.TryGetValue(p.PointID, out var c) ? c : 0
})
.ToList<object>();
tree.Add(new
{
id = $"r_{region.Id}",
label = region.RegionName ?? $"区域{region.Id}",
type = "region",
deviceCount = regionChildren.Count,
children = regionChildren
});
}
return Ok(tree);
}
/// <summary>
/// 获取指定点位下的设备列表（含子设备）。
/// 支持分页参数 page 和 size。
/// </summary>
[HttpGet]
[Route("/api/DeviceManager/GetDevicesByPoint")]
public async Task<IActionResult> GetDevicesByPoint(int pointId, int page = 1, int size = 20)
{
var query = _service.FindAsIQueryable(x => x.PointId == pointId);
var total = await query.CountAsync();
var items = await query
.Skip((page - 1) * size)
.Take(size)
.OrderBy(x => x.DeviceId)
.Select(x => new
{
x.DeviceId, x.DeviceName, x.AdapterCode, x.SourceId,
x.DeviceCategory, x.DeviceGroup, x.IsParent,
x.ParentDeviceId, x.IsOnline, x.IpAddress, x.Port,
x.Location, x.ExtraData, x.LastSyncTime,
x.MapModelId, x.MapModelScale, x.MapModelRotation, x.Enable
})
.ToListAsync();
return Ok(new { items, total });
}
}
}

246
api_sqlsugar/VolPro.WebApi/Controllers/Warehouse/Partial/gateway_nodesController.cs
View File

@@ -1,246 +0,0 @@
/*
*网关节点管理 — A1注册/A2心跳/A3设备同步/A4告警同步
*A组接口使用 [AllowAnonymous] + NodeToken 二次认证
*所有改动在 Partial 目录，不破坏框架可升级性
*/
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.DependencyInjection;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using VolPro.Core.DBManager;
using VolPro.Core.DbSqlSugar;
using VolPro.Entity.DomainModels;
using Warehouse.IRepositories;
using Warehouse.IServices;
using Warehouse.Services;
namespace Warehouse.Controllers
{
public partial class gateway_nodesController
{
private readonly Igateway_nodesService _service;//访问业务代码
private readonly Ibase_deviceService _deviceService;
private readonly Iiot_alarmService _iot_alarmService;
private readonly IHttpContextAccessor _httpContextAccessor;
[ActivatorUtilitiesConstructor]
public gateway_nodesController(
Igateway_nodesService service,
Ibase_deviceService deviceService,
Iiot_alarmService iot_alarmService,
IHttpContextAccessor httpContextAccessor
)
: base(service)
{
_service = service;
_deviceService = deviceService;
_iot_alarmService = iot_alarmService;
_httpContextAccessor = httpContextAccessor;
}
/// <summary>A1: 网关注册（Upsert）。认证方式: NodeToken</summary>
[HttpPost]
[Route("/api/gateway/register")]
[AllowAnonymous]
public async Task<IActionResult> RegisterGateway([FromBody] GatewayRegisterRequest req)
{
if (string.IsNullOrEmpty(req.NodeCode) || string.IsNullOrEmpty(req.Token))
return BadRequest(new { message = "NodeCode 和 Token 为必填项" });
try
{
var node = await _service.RegisterNodeAsync(req.NodeCode, req.Token, req.AdapterTypes, req.BaseUrl);
// 返回当前网关的顶层设备列表
var devices = await _deviceService.GetDevicesByGatewayNodeAsync(node.NodeId);
return Ok(new { nodeId = node.NodeId, devices = devices.Select(d => new {
d.DeviceId, d.DeviceName, d.AdapterCode, d.SourceId,
d.DeviceCategory, d.DeviceGroup, d.IsParent, d.IsOnline, d.ExtraData
}) });
}
catch (UnauthorizedAccessException)
{
return StatusCode(401, new { message = "认证失败：Token 无效" });
}
}
/// <summary>A2: 心跳。认证方式: NodeToken。每15秒调用一次。</summary>
[HttpPost]
[Route("/api/gateway/heartbeat")]
[AllowAnonymous]
public async Task<IActionResult> GatewayHeartbeat([FromBody] GatewayHeartbeatRequest req)
{
if (string.IsNullOrEmpty(req.NodeCode) || string.IsNullOrEmpty(req.Token))
return BadRequest(new { message = "NodeCode 和 Token 为必填项" });
try
{
await _service.UpdateHeartbeatAsync(req.NodeCode, req.Token);
return Ok(new { status = "ok", serverTime = DateTime.Now.ToString("yyyy-MM-dd HH:mm:ss") });
}
catch (UnauthorizedAccessException)
{
return StatusCode(401, new { message = "认证失败" });
}
}
/// <summary>A3: 设备数据同步（字段分治 + parentSourceId 映射）。认证方式: NodeToken</summary>
[HttpPost]
[Route("/api/gateway/sync/devices")]
[AllowAnonymous]
public async Task<IActionResult> SyncDevices([FromBody] SyncDevicesRequest req)
{
if (string.IsNullOrEmpty(req.NodeCode) || string.IsNullOrEmpty(req.Token))
return BadRequest(new { message = "NodeCode 和 Token 为必填项" });
try
{
// 认证
var node = await _service.FindAsIQueryable(x => x.NodeCode == req.NodeCode && x.NodeToken == req.Token)
.FirstOrDefaultAsync();
if (node == null) return StatusCode(401, new { message = "认证失败" });
var items = req.Devices.Select(d => new SyncDeviceItem
{
AdapterCode = d.AdapterCode,
SourceId = d.SourceId,
Name = d.Name,
Category = d.Category,
Group = d.Group,
IsParent = d.IsParent,
ParentSourceId = d.ParentSourceId,
IsOnline = d.IsOnline,
IpAddress = d.IpAddress,
Port = d.Port,
ExtraDataJson = d.ExtraDataJson
}).ToList();
var (added, updated) = await _service.SyncDevicesAsync(node.NodeId, items);
return Ok(new { added, updated, removed = 0 });
}
catch (UnauthorizedAccessException)
{
return StatusCode(401, new { message = "认证失败" });
}
}
/// <summary>A4: 告警同步（DeviceSourceId→DeviceId 映射 + SourceAlarmId 去重）。认证方式: NodeToken</summary>
[HttpPost]
[Route("/api/gateway/sync/alarms")]
[AllowAnonymous]
public async Task<IActionResult> SyncAlarms([FromBody] SyncAlarmsRequest req)
{
if (string.IsNullOrEmpty(req.NodeCode) || string.IsNullOrEmpty(req.Token))
return BadRequest(new { message = "NodeCode 和 Token 为必填项" });
try
{
var node = await _service.FindAsIQueryable(x => x.NodeCode == req.NodeCode && x.NodeToken == req.Token)
.FirstOrDefaultAsync();
if (node == null) return StatusCode(401, new { message = "认证失败" });
// 获取告警服务
var alarmSvc = _iot_alarmService;
// 批量查询 DeviceSourceId → DeviceId 映射
var deviceSvc = _deviceService;
int added = 0;
foreach (var a in req.Alarms)
{
int? deviceId = null;
if (deviceSvc != null)
{
var dev = await deviceSvc.FindAsIQueryable(
x => x.AdapterCode == a.AdapterCode && x.SourceId == a.DeviceSourceId)
.Select(x => new { x.DeviceId })
.FirstOrDefaultAsync();
deviceId = dev?.DeviceId;
}
if (alarmSvc != null)
{
var alarmItem = new SyncAlarmItem
{
SourceAlarmId = a.SourceAlarmId,
DeviceSourceId = a.DeviceSourceId,
AdapterCode = a.AdapterCode,
Level = a.Level,
Desc = a.Desc,
Value = a.Value,
StartTime = a.StartTime
};
await alarmSvc.UpsertAlarmAsync(alarmItem, deviceId);
added++;
}
}
return Ok(new { added });
}
catch (UnauthorizedAccessException)
{
return StatusCode(401, new { message = "认证失败" });
}
}
}
// ── A 组请求 DTO ──
public class GatewayRegisterRequest
{
public string NodeCode { get; set; } = "";
public string Token { get; set; } = "";
public string AdapterTypes { get; set; } = "";
public string BaseUrl { get; set; } = "";
}
public class GatewayHeartbeatRequest
{
public string NodeCode { get; set; } = "";
public string Token { get; set; } = "";
}
public class SyncDevicesRequest
{
public string NodeCode { get; set; } = "";
public string Token { get; set; } = "";
public List<SyncDeviceItemDto> Devices { get; set; } = new();
}
public class SyncDeviceItemDto
{
public string AdapterCode { get; set; } = "";
public string SourceId { get; set; } = "";
public string? Name { get; set; }
public string? Category { get; set; }
public string? Group { get; set; }
public bool IsParent { get; set; }
public string? ParentSourceId { get; set; }
public bool IsOnline { get; set; }
public string? IpAddress { get; set; }
public int? Port { get; set; }
public string? ExtraDataJson { get; set; }
}
public class SyncAlarmsRequest
{
public string NodeCode { get; set; } = "";
public string Token { get; set; } = "";
public List<SyncAlarmItemDto> Alarms { get; set; } = new();
}
public class SyncAlarmItemDto
{
public string SourceAlarmId { get; set; } = "";
public string DeviceSourceId { get; set; } = "";
public string AdapterCode { get; set; } = "";
public string Level { get; set; } = "";
public string Desc { get; set; } = "";
public double? Value { get; set; }
public string StartTime { get; set; } = "";
}
}

33
api_sqlsugar/VolPro.WebApi/Controllers/Warehouse/Partial/iot_alarmController.cs
View File

@@ -1,33 +0,0 @@
/*
*接口编写处...
*如果接口需要做Action的权限验证，请在Action上使用属性
*如: [ApiActionPermission("iot_alarm",Enums.ActionPermissionOptions.Search)]
*/
using Microsoft.AspNetCore.Mvc;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.AspNetCore.Http;
using VolPro.Entity.DomainModels;
using Warehouse.IServices;
namespace Warehouse.Controllers
{
public partial class iot_alarmController
{
private readonly Iiot_alarmService _service;//访问业务代码
private readonly IHttpContextAccessor _httpContextAccessor;
[ActivatorUtilitiesConstructor]
public iot_alarmController(
Iiot_alarmService service,
IHttpContextAccessor httpContextAccessor
)
: base(service)
{
_service = service;
_httpContextAccessor = httpContextAccessor;
}
}
}

33
api_sqlsugar/VolPro.WebApi/Controllers/Warehouse/Partial/iot_devicedataController.cs
View File

@@ -1,33 +0,0 @@
/*
*接口编写处...
*如果接口需要做Action的权限验证，请在Action上使用属性
*如: [ApiActionPermission("iot_devicedata",Enums.ActionPermissionOptions.Search)]
*/
using Microsoft.AspNetCore.Mvc;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.AspNetCore.Http;
using VolPro.Entity.DomainModels;
using Warehouse.IServices;
namespace Warehouse.Controllers
{
public partial class iot_devicedataController
{
private readonly Iiot_devicedataService _service;//访问业务代码
private readonly IHttpContextAccessor _httpContextAccessor;
[ActivatorUtilitiesConstructor]
public iot_devicedataController(
Iiot_devicedataService service,
IHttpContextAccessor httpContextAccessor
)
: base(service)
{
_service = service;
_httpContextAccessor = httpContextAccessor;
}
}
}

33
api_sqlsugar/VolPro.WebApi/Controllers/Warehouse/Partial/video_channelController.cs
View File

@@ -1,33 +0,0 @@
/*
*接口编写处...
*如果接口需要做Action的权限验证，请在Action上使用属性
*如: [ApiActionPermission("video_channel",Enums.ActionPermissionOptions.Search)]
*/
using Microsoft.AspNetCore.Mvc;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.AspNetCore.Http;
using VolPro.Entity.DomainModels;
using Warehouse.IServices;
namespace Warehouse.Controllers
{
public partial class video_channelController
{
private readonly Ivideo_channelService _service;//访问业务代码
private readonly IHttpContextAccessor _httpContextAccessor;
[ActivatorUtilitiesConstructor]
public video_channelController(
Ivideo_channelService service,
IHttpContextAccessor httpContextAccessor
)
: base(service)
{
_service = service;
_httpContextAccessor = httpContextAccessor;
}
}
}

33
api_sqlsugar/VolPro.WebApi/Controllers/Warehouse/Partial/video_recordController.cs
View File

@@ -1,33 +0,0 @@
/*
*接口编写处...
*如果接口需要做Action的权限验证，请在Action上使用属性
*如: [ApiActionPermission("video_record",Enums.ActionPermissionOptions.Search)]
*/
using Microsoft.AspNetCore.Mvc;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.AspNetCore.Http;
using VolPro.Entity.DomainModels;
using Warehouse.IServices;
namespace Warehouse.Controllers
{
public partial class video_recordController
{
private readonly Ivideo_recordService _service;//访问业务代码
private readonly IHttpContextAccessor _httpContextAccessor;
[ActivatorUtilitiesConstructor]
public video_recordController(
Ivideo_recordService service,
IHttpContextAccessor httpContextAccessor
)
: base(service)
{
_service = service;
_httpContextAccessor = httpContextAccessor;
}
}
}

80
api_sqlsugar/VolPro.WebApi/Controllers/Warehouse/TaskController.cs
View File

@@ -1,80 +0,0 @@
using System;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.DependencyInjection;
using VolPro.Core.Filters;
using Warehouse.IServices;
namespace Warehouse.Controllers;
/// <summary>
/// 定时任务 API 端点。
/// Vol.Pro 框架通过 Sys_QuartzOptions 表配置 URL+Cron 定时调用。
/// 每个方法加 [ApiTask] 属性以允许框架匿名调用。
///
/// 不在 Controller 层注入具体业务类——通过 HttpContext.RequestServices 按需解析，
/// 避免 Controller 构造函数的 DI 依赖链过长。
/// </summary>
[Route("api/task")]
public class TaskController : Controller
{
/// <summary>T1: 设备同步 — 遍历在线网关触发全量设备同步（每5分钟）</summary>
[ApiTask]
[HttpGet, HttpPost, Route("syncDevices")]
public async Task<IActionResult> SyncDevices()
{
var sp = HttpContext.RequestServices;
if (sp.GetService<Igateway_nodesService>() == null)
return StatusCode(500, new { error = "服务未注册: gateway_nodesService" });
// 复用 SyncDevicesJob 的核心流程（Job 内部自行创建 GatewayClient）
var job = new VolPro.Warehouse.Services.SyncDevicesJob(sp);
await job.Execute(null!);
return Ok(new { time = DateTime.Now, status = "ok" });
}
/// <summary>T2: 心跳监控 — 扫描超时网关标记离线（每15秒）</summary>
[ApiTask]
[HttpGet, HttpPost, Route("heartbeatMonitor")]
public async Task<IActionResult> HeartbeatMonitor()
{
var sp = HttpContext.RequestServices;
var gwSvc = sp.GetService<Igateway_nodesService>();
if (gwSvc == null)
return StatusCode(500, new { error = "服务未注册: gateway_nodesService" });
var job = new VolPro.Warehouse.Services.HeartbeatMonitorJob(sp);
await job.Execute(null!);
return Ok(new { time = DateTime.Now, status = "ok" });
}
/// <summary>T3: 实时轮询 — 拉取 MC4 IoT 实时值（每10秒）</summary>
[ApiTask]
[HttpGet, HttpPost, Route("realtimePoll")]
public async Task<IActionResult> RealtimePoll()
{
var sp = HttpContext.RequestServices;
var gwSvc = sp.GetService<Igateway_nodesService>();
if (gwSvc == null)
return StatusCode(500, new { error = "服务未注册: gateway_nodesService" });
var job = new VolPro.Warehouse.Services.RealtimePollJob(sp);
await job.Execute(null!);
return Ok(new { time = DateTime.Now, status = "ok" });
}
/// <summary>T4: 规则引擎 — 评估规则+执行动作（每10秒）</summary>
[ApiTask]
[HttpGet, HttpPost, Route("ruleEngine")]
public async Task<IActionResult> RuleEngine()
{
var sp = HttpContext.RequestServices;
var ruleRepo = sp.GetService<Warehouse.IRepositories.Iwarehouse_ruleRepository>();
if (ruleRepo == null)
return StatusCode(500, new { error = "服务未注册: Iwarehouse_ruleRepository" });
var engine = new Warehouse.Services.RuleEngineService(ruleRepo);
await engine.EvaluateAllAsync();
return Ok(new { time = DateTime.Now, status = "ok" });
}
}

21
api_sqlsugar/VolPro.WebApi/Controllers/Warehouse/base_deviceController.cs
View File

@@ -1,21 +0,0 @@
/*
*代码由框架生成,任何更改都可能导致被代码生成器覆盖
*如果要增加方法请在当前目录下Partial文件夹base_deviceController编写
*/
using Microsoft.AspNetCore.Mvc;
using VolPro.Core.Controllers.Basic;
using VolPro.Entity.AttributeManager;
using Warehouse.IServices;
namespace Warehouse.Controllers
{
[Route("api/base_device")]
[PermissionTable(Name = "base_device")]
public partial class base_deviceController : ApiBaseController<Ibase_deviceService>
{
public base_deviceController(Ibase_deviceService service)
: base(service)
{
}
}
}

21
api_sqlsugar/VolPro.WebApi/Controllers/Warehouse/gateway_nodesController.cs
View File

@@ -1,21 +0,0 @@
/*
*代码由框架生成,任何更改都可能导致被代码生成器覆盖
*如果要增加方法请在当前目录下Partial文件夹gateway_nodesController编写
*/
using Microsoft.AspNetCore.Mvc;
using VolPro.Core.Controllers.Basic;
using VolPro.Entity.AttributeManager;
using Warehouse.IServices;
namespace Warehouse.Controllers
{
[Route("api/gateway_nodes")]
[PermissionTable(Name = "gateway_nodes")]
public partial class gateway_nodesController : ApiBaseController<Igateway_nodesService>
{
public gateway_nodesController(Igateway_nodesService service)
: base(service)
{
}
}
}

21
api_sqlsugar/VolPro.WebApi/Controllers/Warehouse/iot_alarmController.cs
View File

@@ -1,21 +0,0 @@
/*
*代码由框架生成,任何更改都可能导致被代码生成器覆盖
*如果要增加方法请在当前目录下Partial文件夹iot_alarmController编写
*/
using Microsoft.AspNetCore.Mvc;
using VolPro.Core.Controllers.Basic;
using VolPro.Entity.AttributeManager;
using Warehouse.IServices;
namespace Warehouse.Controllers
{
[Route("api/iot_alarm")]
[PermissionTable(Name = "iot_alarm")]
public partial class iot_alarmController : ApiBaseController<Iiot_alarmService>
{
public iot_alarmController(Iiot_alarmService service)
: base(service)
{
}
}
}

21
api_sqlsugar/VolPro.WebApi/Controllers/Warehouse/iot_devicedataController.cs
View File

@@ -1,21 +0,0 @@
/*
*代码由框架生成,任何更改都可能导致被代码生成器覆盖
*如果要增加方法请在当前目录下Partial文件夹iot_devicedataController编写
*/
using Microsoft.AspNetCore.Mvc;
using VolPro.Core.Controllers.Basic;
using VolPro.Entity.AttributeManager;
using Warehouse.IServices;
namespace Warehouse.Controllers
{
[Route("api/iot_devicedata")]
[PermissionTable(Name = "iot_devicedata")]
public partial class iot_devicedataController : ApiBaseController<Iiot_devicedataService>
{
public iot_devicedataController(Iiot_devicedataService service)
: base(service)
{
}
}
}

21
api_sqlsugar/VolPro.WebApi/Controllers/Warehouse/video_channelController.cs
View File

@@ -1,21 +0,0 @@
/*
*代码由框架生成,任何更改都可能导致被代码生成器覆盖
*如果要增加方法请在当前目录下Partial文件夹video_channelController编写
*/
using Microsoft.AspNetCore.Mvc;
using VolPro.Core.Controllers.Basic;
using VolPro.Entity.AttributeManager;
using Warehouse.IServices;
namespace Warehouse.Controllers
{
[Route("api/video_channel")]
[PermissionTable(Name = "video_channel")]
public partial class video_channelController : ApiBaseController<Ivideo_channelService>
{
public video_channelController(Ivideo_channelService service)
: base(service)
{
}
}
}

21
api_sqlsugar/VolPro.WebApi/Controllers/Warehouse/video_recordController.cs
View File

@@ -1,21 +0,0 @@
/*
*代码由框架生成,任何更改都可能导致被代码生成器覆盖
*如果要增加方法请在当前目录下Partial文件夹video_recordController编写
*/
using Microsoft.AspNetCore.Mvc;
using VolPro.Core.Controllers.Basic;
using VolPro.Entity.AttributeManager;
using Warehouse.IServices;
namespace Warehouse.Controllers
{
[Route("api/video_record")]
[PermissionTable(Name = "video_record")]
public partial class video_recordController : ApiBaseController<Ivideo_recordService>
{
public video_recordController(Ivideo_recordService service)
: base(service)
{
}
}
}

BIN
api_sqlsugar/VolPro.WebApi/Download/ExcelExport/20260516/字典明细20260516100837.xlsx Normal file
View File

Binary file not shown.

7
api_sqlsugar/VolPro.WebApi/Download/Logger/Queue/WriteError/20260521.txt
View File

@@ -1,7 +0,0 @@
中文提示 : 检测到你没有开启文件，AllowLoadLocalInfile=true加到自符串上，已自动执行 SET GLOBAL local_infile=1 在试一次
English Message : Loading local data is disabled; this must be enabled on both the client and server sides at SqlSugar.Check.ExceptionEasy(String enMessage, String cnMessage)
at SqlSugar.MySqlFastBuilder.ExecuteBulkCopyAsync(DataTable dt)
at SqlSugar.FastestProvider`1._BulkCopy(List`1 datas)
at SqlSugar.FastestProvider`1.BulkCopyAsync(List`1 datas)
at SqlSugar.FastestProvider`1.BulkCopy(List`1 datas)
at VolPro.Core.Services.Logger.Start() in D:\Code\SecMPS\api_sqlsugar\VolPro.Core\Services\Logger.cs:line 194SqlSugar

11
api_sqlsugar/VolPro.WebApi/Properties/PublishProfiles/FolderProfile1.pubxml
View File

@@ -4,18 +4,13 @@ https://go.microsoft.com/fwlink/?LinkID=208121.
-->
<Project>
<PropertyGroup>
<DeleteExistingFiles>true</DeleteExistingFiles>
<ExcludeApp_Data>false</ExcludeApp_Data>
<LaunchSiteAfterPublish>true</LaunchSiteAfterPublish>
<DeleteExistingFiles>False</DeleteExistingFiles>
<ExcludeApp_Data>False</ExcludeApp_Data>
<LaunchSiteAfterPublish>True</LaunchSiteAfterPublish>
<LastUsedBuildConfiguration>Release</LastUsedBuildConfiguration>
<LastUsedPlatform>Any CPU</LastUsedPlatform>
<PublishProvider>FileSystem</PublishProvider>
<PublishUrl>bin\Release\netcoreapp3.1\net6.0\publish\</PublishUrl>
<WebPublishMethod>FileSystem</WebPublishMethod>
<SiteUrlToLaunchAfterPublish />
<TargetFramework>net8.0</TargetFramework>
<RuntimeIdentifier>linux-arm64</RuntimeIdentifier>
<ProjectGuid>4db3c91b-93fe-4937-8b58-ddd3f57d4607</ProjectGuid>
<SelfContained>true</SelfContained>
</PropertyGroup>
</Project>

8
api_sqlsugar/VolPro.WebApi/Startup copy.cs
View File

@@ -69,14 +69,6 @@ namespace VolPro.WebApi
services.AddSession();
services.AddMemoryCache();
services.AddHttpContextAccessor();
// ── 网关集成: HttpClient + GatewayClient 注册 ──
services.AddHttpClient("VolPro", c =>
{
c.Timeout = TimeSpan.FromSeconds(30);
c.DefaultRequestHeaders.Add("Accept", "application/json");
});
services.AddSingleton<VolPro.Warehouse.Services.GatewayClient>();
services.AddMvc(options =>
{
options.Filters.Add(typeof(ApiAuthorizeFilter));

6
api_sqlsugar/VolPro.WebApi/VolPro.WebApi.csproj
View File

@@ -59,11 +59,5 @@
<None Include="Startup copy.cs" />
</ItemGroup>
<ItemGroup>
<None Update="fonts\DejaVuSans.ttf">
<CopyToOutputDirectory>Always</CopyToOutputDirectory>
</None>
</ItemGroup>
</Project>

BIN
api_sqlsugar/VolPro.WebApi/fonts/DejaVuSans.ttf
View File

Binary file not shown.

18
api_sqlsugar/Warehouse/IRepositories/device_manager/Ibase_deviceRepository.cs
View File

@@ -1,18 +0,0 @@
/*
*代码由框架生成,任何更改都可能导致被代码生成器覆盖
*Repository提供数据库操作，如果要增加数据库操作请在当前目录下Partial文件夹Ibase_deviceRepository编写接口
*/
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using VolPro.Core.BaseProvider;
using VolPro.Entity.DomainModels;
using VolPro.Core.Extensions.AutofacManager;
namespace Warehouse.IRepositories
{
public partial interface Ibase_deviceRepository : IDependency,IRepository<base_device>
{
}
}

18
api_sqlsugar/Warehouse/IRepositories/device_manager/Igateway_nodesRepository.cs
View File

@@ -1,18 +0,0 @@
/*
*代码由框架生成,任何更改都可能导致被代码生成器覆盖
*Repository提供数据库操作，如果要增加数据库操作请在当前目录下Partial文件夹Igateway_nodesRepository编写接口
*/
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using VolPro.Core.BaseProvider;
using VolPro.Entity.DomainModels;
using VolPro.Core.Extensions.AutofacManager;
namespace Warehouse.IRepositories
{
public partial interface Igateway_nodesRepository : IDependency,IRepository<gateway_nodes>
{
}
}

18
api_sqlsugar/Warehouse/IRepositories/device_manager/Iiot_alarmRepository.cs
View File

@@ -1,18 +0,0 @@
/*
*代码由框架生成,任何更改都可能导致被代码生成器覆盖
*Repository提供数据库操作，如果要增加数据库操作请在当前目录下Partial文件夹Iiot_alarmRepository编写接口
*/
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using VolPro.Core.BaseProvider;
using VolPro.Entity.DomainModels;
using VolPro.Core.Extensions.AutofacManager;
namespace Warehouse.IRepositories
{
public partial interface Iiot_alarmRepository : IDependency,IRepository<iot_alarm>
{
}
}

18
api_sqlsugar/Warehouse/IRepositories/device_manager/Iiot_devicedataRepository.cs
View File

@@ -1,18 +0,0 @@
/*
*代码由框架生成,任何更改都可能导致被代码生成器覆盖
*Repository提供数据库操作，如果要增加数据库操作请在当前目录下Partial文件夹Iiot_devicedataRepository编写接口
*/
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using VolPro.Core.BaseProvider;
using VolPro.Entity.DomainModels;
using VolPro.Core.Extensions.AutofacManager;
namespace Warehouse.IRepositories
{
public partial interface Iiot_devicedataRepository : IDependency,IRepository<iot_devicedata>
{
}
}

18
api_sqlsugar/Warehouse/IRepositories/device_manager/Ivideo_channelRepository.cs
View File

@@ -1,18 +0,0 @@
/*
*代码由框架生成,任何更改都可能导致被代码生成器覆盖
*Repository提供数据库操作，如果要增加数据库操作请在当前目录下Partial文件夹Ivideo_channelRepository编写接口
*/
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using VolPro.Core.BaseProvider;
using VolPro.Entity.DomainModels;
using VolPro.Core.Extensions.AutofacManager;
namespace Warehouse.IRepositories
{
public partial interface Ivideo_channelRepository : IDependency,IRepository<video_channel>
{
}
}

18
api_sqlsugar/Warehouse/IRepositories/device_manager/Ivideo_recordRepository.cs
View File

@@ -1,18 +0,0 @@
/*
*代码由框架生成,任何更改都可能导致被代码生成器覆盖
*Repository提供数据库操作，如果要增加数据库操作请在当前目录下Partial文件夹Ivideo_recordRepository编写接口
*/
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using VolPro.Core.BaseProvider;
using VolPro.Entity.DomainModels;
using VolPro.Core.Extensions.AutofacManager;
namespace Warehouse.IRepositories
{
public partial interface Ivideo_recordRepository : IDependency,IRepository<video_record>
{
}
}

12
api_sqlsugar/Warehouse/IServices/device_manager/Ibase_deviceService.cs
View File

@@ -1,12 +0,0 @@
/*
*代码由框架生成,任何更改都可能导致被代码生成器覆盖
*/
using VolPro.Core.BaseProvider;
using VolPro.Entity.DomainModels;
namespace Warehouse.IServices
{
public partial interface Ibase_deviceService : IService<base_device>
{
}
}

12
api_sqlsugar/Warehouse/IServices/device_manager/Igateway_nodesService.cs
View File

@@ -1,12 +0,0 @@
/*
*代码由框架生成,任何更改都可能导致被代码生成器覆盖
*/
using VolPro.Core.BaseProvider;
using VolPro.Entity.DomainModels;
namespace Warehouse.IServices
{
public partial interface Igateway_nodesService : IService<gateway_nodes>
{
}
}

12
api_sqlsugar/Warehouse/IServices/device_manager/Iiot_alarmService.cs
View File

@@ -1,12 +0,0 @@
/*
*代码由框架生成,任何更改都可能导致被代码生成器覆盖
*/
using VolPro.Core.BaseProvider;
using VolPro.Entity.DomainModels;
namespace Warehouse.IServices
{
public partial interface Iiot_alarmService : IService<iot_alarm>
{
}
}

12
api_sqlsugar/Warehouse/IServices/device_manager/Iiot_devicedataService.cs
View File

@@ -1,12 +0,0 @@
/*
*代码由框架生成,任何更改都可能导致被代码生成器覆盖
*/
using VolPro.Core.BaseProvider;
using VolPro.Entity.DomainModels;
namespace Warehouse.IServices
{
public partial interface Iiot_devicedataService : IService<iot_devicedata>
{
}
}

12
api_sqlsugar/Warehouse/IServices/device_manager/Ivideo_channelService.cs
View File

@@ -1,12 +0,0 @@
/*
*代码由框架生成,任何更改都可能导致被代码生成器覆盖
*/
using VolPro.Core.BaseProvider;
using VolPro.Entity.DomainModels;
namespace Warehouse.IServices
{
public partial interface Ivideo_channelService : IService<video_channel>
{
}
}

12
api_sqlsugar/Warehouse/IServices/device_manager/Ivideo_recordService.cs
View File

@@ -1,12 +0,0 @@
/*
*代码由框架生成,任何更改都可能导致被代码生成器覆盖
*/
using VolPro.Core.BaseProvider;
using VolPro.Entity.DomainModels;
namespace Warehouse.IServices
{
public partial interface Ivideo_recordService : IService<video_record>
{
}
}

19
api_sqlsugar/Warehouse/IServices/device_manager/Partial/Ibase_deviceService.cs
View File

@@ -1,19 +0,0 @@
/*
*所有关于base_device类的业务代码接口应在此处编写
*/
using System.Linq.Expressions;
using VolPro.Core.BaseProvider;
using VolPro.Core.Utilities;
using VolPro.Entity.DomainModels;
using Warehouse.Services;
namespace Warehouse.IServices
{
public partial interface Ibase_deviceService
{
Task<List<base_device>> GetDevicesByGatewayNodeAsync(int gatewayNodeId);
Task UpsertDeviceAsync(SyncDeviceItem d, int gatewayNodeId, Dictionary<(string, string), int> existingIds);
}
}

19
api_sqlsugar/Warehouse/IServices/device_manager/Partial/Igateway_nodesService.cs
View File

@@ -1,19 +0,0 @@
/*
*所有关于gateway_nodes类的业务代码接口应在此处编写
*/
using System.Linq.Expressions;
using VolPro.Core.BaseProvider;
using VolPro.Core.Utilities;
using VolPro.Entity.DomainModels;
using Warehouse.Services;
namespace Warehouse.IServices
{
public partial interface Igateway_nodesService
{
Task<gateway_nodes> RegisterNodeAsync(string nodeCode, string token, string adapterTypes, string baseUrl);
Task UpdateHeartbeatAsync(string nodeCode, string token);
Task<(int added, int updated)> SyncDevicesAsync(int gatewayNodeId, List<SyncDeviceItem> devices);
}
}

17
api_sqlsugar/Warehouse/IServices/device_manager/Partial/Iiot_alarmService.cs
View File

@@ -1,17 +0,0 @@
/*
*所有关于iot_alarm类的业务代码接口应在此处编写
*/
using System.Linq.Expressions;
using VolPro.Core.BaseProvider;
using VolPro.Core.Utilities;
using VolPro.Entity.DomainModels;
using Warehouse.Services;
namespace Warehouse.IServices
{
public partial interface Iiot_alarmService
{
Task UpsertAlarmAsync(SyncAlarmItem a, int? deviceId);
}
}

13
api_sqlsugar/Warehouse/IServices/device_manager/Partial/Iiot_devicedataService.cs
View File

@@ -1,13 +0,0 @@
/*
*所有关于iot_devicedata类的业务代码接口应在此处编写
*/
using VolPro.Core.BaseProvider;
using VolPro.Entity.DomainModels;
using VolPro.Core.Utilities;
using System.Linq.Expressions;
namespace Warehouse.IServices
{
public partial interface Iiot_devicedataService
{
}
}

13
api_sqlsugar/Warehouse/IServices/device_manager/Partial/Ivideo_channelService.cs
View File

@@ -1,13 +0,0 @@
/*
*所有关于video_channel类的业务代码接口应在此处编写
*/
using VolPro.Core.BaseProvider;
using VolPro.Entity.DomainModels;
using VolPro.Core.Utilities;
using System.Linq.Expressions;
namespace Warehouse.IServices
{
public partial interface Ivideo_channelService
{
}
}

13
api_sqlsugar/Warehouse/IServices/device_manager/Partial/Ivideo_recordService.cs
View File

@@ -1,13 +0,0 @@
/*
*所有关于video_record类的业务代码接口应在此处编写
*/
using VolPro.Core.BaseProvider;
using VolPro.Entity.DomainModels;
using VolPro.Core.Utilities;
using System.Linq.Expressions;
namespace Warehouse.IServices
{
public partial interface Ivideo_recordService
{
}
}

24
api_sqlsugar/Warehouse/Repositories/device_manager/base_deviceRepository.cs
View File

@@ -1,24 +0,0 @@
/*
*代码由框架生成,任何更改都可能导致被代码生成器覆盖
*Repository提供数据库操作，如果要增加数据库操作请在当前目录下Partial文件夹base_deviceRepository编写代码
*/
using Warehouse.IRepositories;
using VolPro.Core.BaseProvider;
using VolPro.Core.EFDbContext;
using VolPro.Core.Extensions.AutofacManager;
using VolPro.Entity.DomainModels;
namespace Warehouse.Repositories
{
public partial class base_deviceRepository : RepositoryBase<base_device> , Ibase_deviceRepository
{
public base_deviceRepository(ServiceDbContext dbContext)
: base(dbContext)
{
}
public static Ibase_deviceRepository Instance
{
get { return AutofacContainerModule.GetService<Ibase_deviceRepository>(); } }
}
}

24
api_sqlsugar/Warehouse/Repositories/device_manager/gateway_nodesRepository.cs
View File

@@ -1,24 +0,0 @@
/*
*代码由框架生成,任何更改都可能导致被代码生成器覆盖
*Repository提供数据库操作，如果要增加数据库操作请在当前目录下Partial文件夹gateway_nodesRepository编写代码
*/
using Warehouse.IRepositories;
using VolPro.Core.BaseProvider;
using VolPro.Core.EFDbContext;
using VolPro.Core.Extensions.AutofacManager;
using VolPro.Entity.DomainModels;
namespace Warehouse.Repositories
{
public partial class gateway_nodesRepository : RepositoryBase<gateway_nodes> , Igateway_nodesRepository
{
public gateway_nodesRepository(ServiceDbContext dbContext)
: base(dbContext)
{
}
public static Igateway_nodesRepository Instance
{
get { return AutofacContainerModule.GetService<Igateway_nodesRepository>(); } }
}
}

24
api_sqlsugar/Warehouse/Repositories/device_manager/iot_alarmRepository.cs
View File

@@ -1,24 +0,0 @@
/*
*代码由框架生成,任何更改都可能导致被代码生成器覆盖
*Repository提供数据库操作，如果要增加数据库操作请在当前目录下Partial文件夹iot_alarmRepository编写代码
*/
using Warehouse.IRepositories;
using VolPro.Core.BaseProvider;
using VolPro.Core.EFDbContext;
using VolPro.Core.Extensions.AutofacManager;
using VolPro.Entity.DomainModels;
namespace Warehouse.Repositories
{
public partial class iot_alarmRepository : RepositoryBase<iot_alarm> , Iiot_alarmRepository
{
public iot_alarmRepository(ServiceDbContext dbContext)
: base(dbContext)
{
}
public static Iiot_alarmRepository Instance
{
get { return AutofacContainerModule.GetService<Iiot_alarmRepository>(); } }
}
}

24
api_sqlsugar/Warehouse/Repositories/device_manager/iot_devicedataRepository.cs
View File

@@ -1,24 +0,0 @@
/*
*代码由框架生成,任何更改都可能导致被代码生成器覆盖
*Repository提供数据库操作，如果要增加数据库操作请在当前目录下Partial文件夹iot_devicedataRepository编写代码
*/
using Warehouse.IRepositories;
using VolPro.Core.BaseProvider;
using VolPro.Core.EFDbContext;
using VolPro.Core.Extensions.AutofacManager;
using VolPro.Entity.DomainModels;
namespace Warehouse.Repositories
{
public partial class iot_devicedataRepository : RepositoryBase<iot_devicedata> , Iiot_devicedataRepository
{
public iot_devicedataRepository(ServiceDbContext dbContext)
: base(dbContext)
{
}
public static Iiot_devicedataRepository Instance
{
get { return AutofacContainerModule.GetService<Iiot_devicedataRepository>(); } }
}
}

24
api_sqlsugar/Warehouse/Repositories/device_manager/video_channelRepository.cs
View File

@@ -1,24 +0,0 @@
/*
*代码由框架生成,任何更改都可能导致被代码生成器覆盖
*Repository提供数据库操作，如果要增加数据库操作请在当前目录下Partial文件夹video_channelRepository编写代码
*/
using Warehouse.IRepositories;
using VolPro.Core.BaseProvider;
using VolPro.Core.EFDbContext;
using VolPro.Core.Extensions.AutofacManager;
using VolPro.Entity.DomainModels;
namespace Warehouse.Repositories
{
public partial class video_channelRepository : RepositoryBase<video_channel> , Ivideo_channelRepository
{
public video_channelRepository(ServiceDbContext dbContext)
: base(dbContext)
{
}
public static Ivideo_channelRepository Instance
{
get { return AutofacContainerModule.GetService<Ivideo_channelRepository>(); } }
}
}

24
api_sqlsugar/Warehouse/Repositories/device_manager/video_recordRepository.cs
View File

@@ -1,24 +0,0 @@
/*
*代码由框架生成,任何更改都可能导致被代码生成器覆盖
*Repository提供数据库操作，如果要增加数据库操作请在当前目录下Partial文件夹video_recordRepository编写代码
*/
using Warehouse.IRepositories;
using VolPro.Core.BaseProvider;
using VolPro.Core.EFDbContext;
using VolPro.Core.Extensions.AutofacManager;
using VolPro.Entity.DomainModels;
namespace Warehouse.Repositories
{
public partial class video_recordRepository : RepositoryBase<video_record> , Ivideo_recordRepository
{
public video_recordRepository(ServiceDbContext dbContext)
: base(dbContext)
{
}
public static Ivideo_recordRepository Instance
{
get { return AutofacContainerModule.GetService<Ivideo_recordRepository>(); } }
}
}

73
api_sqlsugar/Warehouse/Services/GatewayClient.cs
View File

@@ -1,73 +0,0 @@
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using System.Net.Http;
using System.Net.Http.Json;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;
namespace VolPro.Warehouse.Services;
/// <summary>
/// 网关 HTTP 客户端。封装 Vol.Pro 调用 IntegrationGateway B 组接口的逻辑。
/// 所有对网关的请求统一经此类发出，便于连接池管理和错误处理。
/// </summary>
public class GatewayClient
{
private readonly IHttpClientFactory _httpFactory;
private readonly IConfiguration _config;
public GatewayClient(IHttpClientFactory httpFactory, IConfiguration config)
{
_httpFactory = httpFactory;
_config = config;
}
/// <summary>创建带超时和默认头的 HttpClient</summary>
private HttpClient CreateClient()
{
var client = _httpFactory.CreateClient("VolPro");
client.Timeout = TimeSpan.FromSeconds(30);
return client;
}
/// <summary>
/// B3: 手动触发网关全量设备同步。
/// POST {baseUrl}/api/gateway/devices/sync?adapter={adapterTypes}
/// </summary>
public async Task<JsonDocument?> TriggerFullSyncAsync(string baseUrl, string adapterTypes)
{
var http = CreateClient();
var resp = await http.PostAsync(
$"{baseUrl.TrimEnd('/')}/api/gateway/devices/sync?adapter={Uri.EscapeDataString(adapterTypes)}",
null);
if (!resp.IsSuccessStatusCode) return null;
return await resp.Content.ReadFromJsonAsync<JsonDocument>();
}
/// <summary>
/// B4: 获取设备实时点位值。
/// GET {baseUrl}/api/gateway/realtime/{adapter}/{deviceId}
/// </summary>
public async Task<JsonDocument?> GetRealtimeAsync(string baseUrl, string adapter, string deviceId)
{
var http = CreateClient();
var resp = await http.GetAsync(
$"{baseUrl.TrimEnd('/')}/api/gateway/realtime/{Uri.EscapeDataString(adapter)}/{Uri.EscapeDataString(deviceId)}");
if (!resp.IsSuccessStatusCode) return null;
return await resp.Content.ReadFromJsonAsync<JsonDocument>();
}
/// <summary>
/// B5: 设备反向控制。
/// POST {baseUrl}/api/gateway/realtime/{adapter}/control
/// </summary>
public async Task<bool> ControlDeviceAsync(string baseUrl, string adapter, string deviceId, int pointIndex, double value)
{
var http = CreateClient();
var resp = await http.PostAsJsonAsync(
$"{baseUrl.TrimEnd('/')}/api/gateway/realtime/{adapter}/control",
new { deviceId, pointIndex, value });
return resp.IsSuccessStatusCode;
}
}

77
api_sqlsugar/Warehouse/Services/HeartbeatMonitorJob.cs
View File

@@ -1,77 +0,0 @@
using Quartz;
using Microsoft.Extensions.DependencyInjection;
using Warehouse.IServices;
using VolPro.Entity.DomainModels;
using System;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.EntityFrameworkCore;
using Warehouse.IRepositories;
namespace VolPro.Warehouse.Services;
/// <summary>
/// 心跳超时检测任务。扫描心跳超时 30 秒的网关节点，标记为离线，
/// 并级联标记该节点下所有设备为离线。
/// Cron 建议: 每 15 秒 ("0/15 * * * * ?")
///
/// 设备与网关的关联通过 AdapterCode 前缀匹配（如设备 AdapterCode="MC4:31ku" 匹配网关 AdapterTypes="MC4:31ku"）。
/// </summary>
public class HeartbeatMonitorJob : IJob
{
private readonly IServiceProvider _sp;
public HeartbeatMonitorJob(IServiceProvider sp) { _sp = sp; }
public async Task Execute(IJobExecutionContext? context)
{
var sp = _sp;
if (sp == null) return;
var gwSvc = sp.GetService<Igateway_nodesService>();
var gwRepo = sp.GetService<Igateway_nodesRepository>();
var devRepo = sp.GetService<Ibase_deviceRepository>();
if (gwSvc == null || gwRepo == null || devRepo == null) return;
var timeout = DateTime.Now.AddSeconds(-30);
// 扫描心跳超时的网关（当前在线但心跳超时）
var offlineNodes = await gwSvc.FindAsIQueryable(
x => x.IsOnline == "在线" && x.LastHeartbeat < timeout).ToListAsync();
foreach (var node in offlineNodes)
{
// 标记网关离线
node.IsOnline = "离线";
try { gwRepo.Update(node); } catch { }
Console.WriteLine($"[HeartbeatMonitorJob] 网关 {node.NodeCode} 心跳超时，标记离线");
// 级联标记该网关下所有设备离线（批量 SQL）
try
{
var adapterPrefixes = (node.AdapterTypes ?? "")
.Split(',', StringSplitOptions.RemoveEmptyEntries)
.Select(t => t.Trim()).ToList();
if (adapterPrefixes.Any())
{
var allDevices = await devRepo.FindAsIQueryable(
d => d.IsOnline == "在线").ToListAsync();
var matched = allDevices
.Where(d => adapterPrefixes.Any(p => (d.AdapterCode ?? "").StartsWith(p)))
.ToList();
if (matched.Any())
{
foreach (var dev in matched) dev.IsOnline = "离线";
devRepo.UpdateRange(matched);
Console.WriteLine($"[HeartbeatMonitorJob] 级联 {matched.Count} 台设备离线");
}
}
}
catch (Exception ex)
{
Console.Error.WriteLine($"[HeartbeatMonitorJob] 级联离线失败: {ex.Message}");
}
}
}
}

94
api_sqlsugar/Warehouse/Services/RealtimePollJob.cs
View File

@@ -1,94 +0,0 @@
using Quartz;
using Microsoft.Extensions.DependencyInjection;
using System;
using System.Linq;
using System.Threading.Tasks;
using VolPro.Entity.DomainModels;
using Warehouse.IRepositories;
using Microsoft.Extensions.Configuration;
using System.Net.Http;
using Warehouse.IServices;
namespace VolPro.Warehouse.Services;
/// <summary>
/// 实时数据轮询任务。
/// 定时轮询在线 MC4 IoT 设备的实时值 → 写入 iot_devicedata 表。
/// Cron 建议: 每 10 秒 ("0/10 * * * * ?")
///
/// 设备与网关的关联通过 AdapterCode 前缀匹配（如设备 AdapterCode="MC4:31ku" 匹配网关 AdapterTypes="MC4:31ku"）。
/// </summary>
public class RealtimePollJob : IJob
{
private readonly IServiceProvider _sp;
public RealtimePollJob(IServiceProvider sp) { _sp = sp; }
public async Task Execute(IJobExecutionContext? context)
{
var sp = _sp;
if (sp == null) return;
var gwSvc = sp.GetService<Igateway_nodesService>();
var devRepo = sp.GetService<Ibase_deviceRepository>();
var dataRepo = sp.GetService<Iiot_devicedataRepository>();
var httpFactory = sp.GetService<IHttpClientFactory>();
var config = sp.GetService<IConfiguration>();
var gatewayClient = httpFactory != null ? new GatewayClient(httpFactory, config!) : null;
if (gwSvc == null || devRepo == null || dataRepo == null || gatewayClient == null) return;
// 1. 查在线 MC4 网关
var onlineNodes = await gwSvc.FindAsIQueryable(x =>
x.IsOnline == "在线" && x.AdapterTypes != null && x.AdapterTypes.Contains("MC4")).ToArrayAsync();
foreach (var node in onlineNodes)
{
try
{
var baseUrl = node.BaseUrl;
if (string.IsNullOrEmpty(baseUrl)) continue;
// 2. 解析网关管理的适配器前缀列表
var adapterPrefixes = (node.AdapterTypes ?? "")
.Split(',', StringSplitOptions.RemoveEmptyEntries)
.Select(t => t.Trim());
// 3. 查该网关下在线的 IoT 设备（AdapterCode 前缀匹配）
var devices = await devRepo.FindAsIQueryable(d =>
d.DeviceGroup == "IoT设备" && d.IsOnline == "在线").ToListAsync();
var matchedDevices = devices.Where(d =>
adapterPrefixes.Any(p => (d.AdapterCode ?? "").StartsWith(p))).ToList();
if (!matchedDevices.Any()) continue;
// 4. 逐设备调网关 B4 获取实时值
foreach (var dev in matchedDevices)
{
try
{
var result = await gatewayClient.GetRealtimeAsync(baseUrl, dev.AdapterCode, dev.SourceId);
if (result == null) continue;
var root = result.RootElement;
var points = root.TryGetProperty("pointValues", out var pv) ? pv
: root.TryGetProperty("rows", out var r) ? r
: root;
// 结果可能是 PointValue[] 数组，取第一个点位写入
if (points.ValueKind == System.Text.Json.JsonValueKind.Array && points.GetArrayLength() > 0)
{
var first = points[0];
var entry = new iot_devicedata
{
DeviceId = dev.DeviceId,
PointValue = first.TryGetProperty("value", out var v) ? v.GetDecimal() : (decimal?)null,
UpdateTime = DateTime.Now,
Interval = first.TryGetProperty("interval", out var iv) ? iv.GetInt32() : 10
};
dataRepo.Add(entry);
}
}
catch { /* 单设备失败不阻塞其他设备 */ }
}
}
catch { /* 单网关失败不阻塞其他网关 */ }
}
}
}

29
api_sqlsugar/Warehouse/Services/RuleEngineService.cs
View File

@@ -1,29 +0,0 @@
// ═══════════════════════════════════════════
// RuleEngineService — 待实体字段就绪后启用。
// 阻塞原因: warehouse_rule.Enable/LastTriggered/CooldownSec
// warehouse_rulecondition.LastTriggered/RecoveryThreshold_Numeric
// warehouse_ruleaction.ActionType 等字段在实体类中不存在
// 修复顺序: SQL ALTER TABLE → VolPro 代码生成器 → 移除本桩恢复完整实现
// 完整实现见 git history: 提交 "RuleEngine-R2-R4: RuleEngineService+RuleEngineJob"
// ═══════════════════════════════════════════
using System;
using System.Threading.Tasks;
using Warehouse.IRepositories;
namespace Warehouse.Services;
public class RuleEngineService
{
private readonly Iwarehouse_ruleRepository _ruleRepo;
public RuleEngineService(Iwarehouse_ruleRepository ruleRepo)
{
_ruleRepo = ruleRepo;
}
public Task EvaluateAllAsync()
{
throw new NotImplementedException(
"RuleEngineService 待实体字段就绪。步骤: SQL ALTER TABLE → 代码生成器 → git revert 本桩。");
}
}

50
api_sqlsugar/Warehouse/Services/SyncDevicesJob.cs
View File

@@ -1,50 +0,0 @@
using Quartz;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Configuration;
using System.Net.Http;
using Warehouse.IServices;
using VolPro.Entity.DomainModels;
using System;
using System.Threading.Tasks;
using Microsoft.EntityFrameworkCore;
namespace VolPro.Warehouse.Services;
/// <summary>
/// 定时设备同步任务。遍历所有在线且启用的网关节点，触发全量设备同步。
/// Cron 建议: 每 5 分钟 ("0 */5 * * * ?")
/// </summary>
public class SyncDevicesJob : IJob
{
private readonly IServiceProvider _sp;
public SyncDevicesJob(IServiceProvider sp) { _sp = sp; }
public async Task Execute(IJobExecutionContext? context)
{
var sp = _sp;
var gwSvc = sp.GetService<Igateway_nodesService>();
var httpFactory = sp.GetService<IHttpClientFactory>();
var config = sp.GetService<IConfiguration>();
var client = httpFactory != null ? new GatewayClient(httpFactory, config!) : null;
if (gwSvc == null || client == null) return;
// 遍历所有在线且启用的网关
var onlineNodes = await gwSvc.FindAsIQueryable(
x => x.IsOnline == "在线" && x.Enable == "启用" && x.BaseUrl != null)
.ToListAsync();
foreach (var node in onlineNodes)
{
try
{
// 触发网关全量同步
await client.TriggerFullSyncAsync(node.BaseUrl!, node.AdapterTypes ?? "");
Console.WriteLine($"[SyncDevicesJob] 网关 {node.NodeCode} 同步触发成功");
}
catch (Exception ex)
{
Console.Error.WriteLine($"[SyncDevicesJob] 网关 {node.NodeCode} 同步失败: {ex.Message}");
}
}
}
}

117
api_sqlsugar/Warehouse/Services/device_manager/Partial/base_deviceService.cs
View File

@@ -1,117 +0,0 @@
/*
*所有关于base_device类的业务代码应在此处编写
*可使用repository.调用常用方法，获取EF/Dapper等信息
*如果需要事务请使用repository.DbContextBeginTransaction
*也可使用DBServerProvider.手动获取数据库相关信息
*用户信息、权限、角色等使用UserContext.Current操作
*base_deviceService对增、删、改查、导入、导出、审核业务代码扩展参照ServiceFunFilter
*/
using VolPro.Core.BaseProvider;
using VolPro.Core.Extensions.AutofacManager;
using VolPro.Entity.DomainModels;
using System.Linq;
using VolPro.Core.Utilities;
using System.Linq.Expressions;
using VolPro.Core.Extensions;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.AspNetCore.Http;
using Warehouse.IRepositories;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
namespace Warehouse.Services
{
public partial class base_deviceService
{
private readonly IHttpContextAccessor _httpContextAccessor;
private readonly Ibase_deviceRepository _repository;//访问数据库
[ActivatorUtilitiesConstructor]
public base_deviceService(
Ibase_deviceRepository dbRepository,
IHttpContextAccessor httpContextAccessor
)
: base(dbRepository)
{
_httpContextAccessor = httpContextAccessor;
_repository = dbRepository;
//多租户会用到这init代码，其他情况可以不用
//base.Init(dbRepository);
}
/// <summary>
/// 获取指定网关节点下的顶层设备列表（用于网关注册时返回所管设备）。
/// 返回 ParentDeviceId 为 null 的设备。
/// </summary>
public async Task<List<base_device>> GetDevicesByGatewayNodeAsync(int gatewayNodeId)
{
return await _repository.DbContext.Queryable<base_device>()
.Where(x => x.NodeId == gatewayNodeId && x.ParentDeviceId == null)
.ToListAsync();
}
/// <summary>
/// 按字段分治原则 Upsert 单个设备。
/// 首次入库时写全量（管理员字段），已有记录时仅更新网关字段（IsOnline/ExtraData等）。
/// </summary>
/// <param name="d">同步设备条目</param>
/// <param name="gatewayNodeId">网关节点ID</param>
/// <param name="existingIds">已有设备映射表 (AdapterCode, SourceId) → DeviceId</param>
[Obsolete("已迁移至 gateway_nodesService.SyncDevicesAsync")]
public async Task UpsertDeviceAsync(SyncDeviceItem d, int gatewayNodeId, Dictionary<(string, string), int> existingIds)
{
var db = _repository.DbContext;
var key = (d.AdapterCode, d.SourceId);
existingIds.TryGetValue(key, out var existingId);
bool isNew = existingId == 0;
// 解析父设备
int? parentDeviceId = null;
if (!string.IsNullOrEmpty(d.ParentSourceId))
{
existingIds.TryGetValue((d.AdapterCode, d.ParentSourceId), out var pid);
if (pid > 0) parentDeviceId = pid;
}
if (isNew)
{
var entity = new base_device
{
DeviceName = d.Name ?? $"DEV_{d.SourceId}",
AdapterCode = d.AdapterCode,
SourceId = d.SourceId,
DeviceCategory = d.Category,
DeviceGroup = d.Group,
NodeId = gatewayNodeId,
IsParent = d.IsParent ? "是" : "否",
ParentDeviceId = parentDeviceId,
IsOnline = d.IsOnline ? "在线" : "离线",
IpAddress = d.IpAddress,
Port = d.Port,
ExtraData = d.ExtraDataJson,
Enable = "启用",
LastSyncTime = DateTime.Now,
CreateDate = DateTime.Now
};
db.Insertable(entity).ExecuteCommand();
}
else
{
var entity = db.Queryable<base_device>().InSingle(existingId);
if (entity != null)
{
entity.IsOnline = d.IsOnline ? "在线" : "离线";
entity.IsParent = d.IsParent ? "是" : "否";
entity.ParentDeviceId = parentDeviceId ?? entity.ParentDeviceId;
entity.IpAddress = d.IpAddress;
entity.Port = d.Port;
entity.ExtraData = d.ExtraDataJson ?? entity.ExtraData;
entity.LastSyncTime = DateTime.Now;
db.Updateable(entity).ExecuteCommand();
}
}
}
}
}

194
api_sqlsugar/Warehouse/Services/device_manager/Partial/gateway_nodesService.cs
View File

@@ -1,194 +0,0 @@
/*
*所有关于gateway_nodes类的业务代码应在此处编写
*可使用repository.调用常用方法，获取EF/Dapper等信息
*如果需要事务请使用repository.DbContextBeginTransaction
*也可使用DBServerProvider.手动获取数据库相关信息
*用户信息、权限、角色等使用UserContext.Current操作
*gateway_nodesService对增、删、改查、导入、导出、审核业务代码扩展参照ServiceFunFilter
*/
using VolPro.Core.BaseProvider;
using VolPro.Core.Extensions.AutofacManager;
using VolPro.Entity.DomainModels;
using System.Linq;
using VolPro.Core.Utilities;
using System.Linq.Expressions;
using VolPro.Core.Extensions;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.AspNetCore.Http;
using Warehouse.IRepositories;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using System.Text.Json;
namespace Warehouse.Services
{
/// <summary>
/// gateway_nodes 业务逻辑（partial）。注册/心跳/设备同步。
/// </summary>
public partial class gateway_nodesService
{
private readonly IHttpContextAccessor _httpContextAccessor;
private readonly Igateway_nodesRepository _repository;
[ActivatorUtilitiesConstructor]
public gateway_nodesService(
Igateway_nodesRepository dbRepository,
IHttpContextAccessor httpContextAccessor
)
: base(dbRepository)
{
_httpContextAccessor = httpContextAccessor;
_repository = dbRepository;
}
/// <summary>
/// 网关注册（Upsert）。
/// NodeCode 匹配则更新适配器类型/地址/在线状态；
/// NodeCode 不匹配且 Token 验证通过则插入新记录。
/// </summary>
[Obsolete("由 A1 API Controller 自动调用，不建议手动调用")]
public async Task<gateway_nodes> RegisterNodeAsync(string nodeCode, string token, string adapterTypes, string baseUrl)
{
var existingList = await _repository.FindAsIQueryable(x => x.NodeCode == nodeCode).ToListAsync();
var existing = existingList.FirstOrDefault();
gateway_nodes entity;
if (existing != null)
{
if (existing.NodeToken != token)
throw new UnauthorizedAccessException("NodeToken 不匹配");
existing.AdapterTypes = adapterTypes;
existing.BaseUrl = baseUrl;
existing.IsOnline = "在线";
existing.LastHeartbeat = DateTime.Now;
_repository.DbContext.Updateable(existing).ExecuteCommand();
entity = existing;
}
else
{
entity = new gateway_nodes
{
NodeCode = nodeCode,
NodeName = nodeCode,
NodeToken = token,
AdapterTypes = adapterTypes,
BaseUrl = baseUrl,
IsOnline = "在线",
Enable = "启用",
LastHeartbeat = DateTime.Now,
CreateDate = DateTime.Now
};
_repository.DbContext.Insertable(entity).ExecuteCommand();
}
return entity;
}
/// <summary>
/// 心跳更新。更新 LastHeartbeat 并标记在线。
/// </summary>
[Obsolete("由 A2 API Controller 自动调用，不建议手动调用")]
public async Task UpdateHeartbeatAsync(string nodeCode, string token)
{
var entityList = await _repository.FindAsIQueryable(x => x.NodeCode == nodeCode && x.NodeToken == token).ToListAsync();
var entity = entityList.FirstOrDefault();
if (entity == null)
throw new UnauthorizedAccessException("认证失败：NodeCode 或 Token 无效");
entity.IsOnline = "在线";
entity.LastHeartbeat = DateTime.Now;
_repository.DbContext.Updateable(entity).ExecuteCommand();
}
/// <summary>
/// 设备数据同步。按字段分治原则写入 base_device：
/// 首次入库写全量，后续仅更新网关字段。
/// parentSourceId 解析为 ParentDeviceId。
/// </summary>
[Obsolete("由 A3 API Controller 自动调用，不建议手动调用")]
public async Task<(int added, int updated)> SyncDevicesAsync(int gatewayNodeId, List<SyncDeviceItem> devices)
{
var db = _repository.DbContext;
var adapterCodes = devices.Select(d => d.AdapterCode).Distinct().ToList();
var existingIds = db.Queryable<base_device>()
.Where(x => x.NodeId == gatewayNodeId && adapterCodes.Contains(x.AdapterCode))
.ToList()
.ToDictionary(x => (x.AdapterCode, x.SourceId), x => x.DeviceId);
int added = 0, updated = 0;
foreach (var d in devices)
{
var key = (d.AdapterCode, d.SourceId);
existingIds.TryGetValue(key, out var existingId);
bool isNew = existingId == 0;
int? parentDeviceId = null;
if (!string.IsNullOrEmpty(d.ParentSourceId))
{
existingIds.TryGetValue((d.AdapterCode, d.ParentSourceId), out var pid);
if (pid > 0) parentDeviceId = pid;
}
if (isNew)
{
var entity = new base_device
{
DeviceName = d.Name ?? $"DEV_{d.SourceId}",
AdapterCode = d.AdapterCode,
SourceId = d.SourceId,
DeviceCategory = d.Category,
DeviceGroup = d.Group,
NodeId = gatewayNodeId,
IsParent = d.IsParent ? "是" : "否",
ParentDeviceId = parentDeviceId,
IsOnline = d.IsOnline ? "在线" : "离线",
IpAddress = d.IpAddress,
Port = d.Port,
ExtraData = d.ExtraDataJson,
Enable = "启用",
LastSyncTime = DateTime.Now,
CreateDate = DateTime.Now
};
db.Insertable(entity).ExecuteCommand();
added++;
}
else
{
var entity = db.Queryable<base_device>().InSingle(existingId);
if (entity != null)
{
entity.IsOnline = d.IsOnline ? "在线" : "离线";
entity.IsParent = d.IsParent ? "是" : "否";
entity.ParentDeviceId = parentDeviceId ?? entity.ParentDeviceId;
entity.IpAddress = d.IpAddress;
entity.Port = d.Port;
entity.ExtraData = d.ExtraDataJson ?? entity.ExtraData;
entity.LastSyncTime = DateTime.Now;
db.Updateable(entity).ExecuteCommand();
updated++;
}
}
}
return (added, updated);
}
}
/// <summary>网关同步设备条目</summary>
public class SyncDeviceItem
{
public string AdapterCode { get; set; } = "";
public string SourceId { get; set; } = "";
public string? Name { get; set; }
public string? Category { get; set; }
public string? Group { get; set; }
public bool IsParent { get; set; }
public string? ParentSourceId { get; set; }
public bool IsOnline { get; set; }
public string? IpAddress { get; set; }
public int? Port { get; set; }
public string? ExtraDataJson { get; set; }
}
}

82
api_sqlsugar/Warehouse/Services/device_manager/Partial/iot_alarmService.cs
View File

@@ -1,82 +0,0 @@
/*
*所有关于iot_alarm类的业务代码应在此处编写
*可使用repository.调用常用方法，获取EF/Dapper等信息
*如果需要事务请使用repository.DbContextBeginTransaction
*也可使用DBServerProvider.手动获取数据库相关信息
*用户信息、权限、角色等使用UserContext.Current操作
*iot_alarmService对增、删、改查、导入、导出、审核业务代码扩展参照ServiceFunFilter
*/
using VolPro.Core.BaseProvider;
using VolPro.Core.Extensions.AutofacManager;
using VolPro.Entity.DomainModels;
using System.Linq;
using VolPro.Core.Utilities;
using System.Linq.Expressions;
using VolPro.Core.Extensions;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.AspNetCore.Http;
using Warehouse.IRepositories;
using System;
using System.Threading.Tasks;
namespace Warehouse.Services
{
public partial class iot_alarmService
{
private readonly IHttpContextAccessor _httpContextAccessor;
private readonly Iiot_alarmRepository _repository;//访问数据库
[ActivatorUtilitiesConstructor]
public iot_alarmService(
Iiot_alarmRepository dbRepository,
IHttpContextAccessor httpContextAccessor
)
: base(dbRepository)
{
_httpContextAccessor = httpContextAccessor;
_repository = dbRepository;
//多租户会用到这init代码，其他情况可以不用
//base.Init(dbRepository);
}
/// <summary>
/// Upsert 单条告警。按 SourceAlarmId 去重，已存在则跳过。
/// </summary>
public async Task UpsertAlarmAsync(SyncAlarmItem a, int? deviceId)
{
var db = _repository.DbContext;
// SourceAlarmId 去重
var exists = db.Queryable<iot_alarm>()
.Any(x => x.SourceAlarmId == a.SourceAlarmId);
if (exists) return;
var alarm = new iot_alarm
{
SourceAlarmId = a.SourceAlarmId,
DeviceId = (int)deviceId,
AdapterCode = a.AdapterCode,
AlarmLevel = a.Level,
AlarmDesc = a.Desc,
AlarmValue = (decimal?)a.Value,
StartTime = DateTime.TryParse(a.StartTime, out var st) ? st : DateTime.Now,
State = "未确认",
CreateDate = DateTime.Now
};
db.Insertable(alarm).ExecuteCommand();
}
}
/// <summary>告警同步条目（A4 接口接收的数据模型）</summary>
public class SyncAlarmItem
{
public string SourceAlarmId { get; set; } = "";
public string DeviceSourceId { get; set; } = "";
public string AdapterCode { get; set; } = "";
public string Level { get; set; } = "";
public string Desc { get; set; } = "";
public double? Value { get; set; }
public string StartTime { get; set; } = "";
}
}

41
api_sqlsugar/Warehouse/Services/device_manager/Partial/iot_devicedataService.cs
View File

@@ -1,41 +0,0 @@
/*
*所有关于iot_devicedata类的业务代码应在此处编写
*可使用repository.调用常用方法，获取EF/Dapper等信息
*如果需要事务请使用repository.DbContextBeginTransaction
*也可使用DBServerProvider.手动获取数据库相关信息
*用户信息、权限、角色等使用UserContext.Current操作
*iot_devicedataService对增、删、改查、导入、导出、审核业务代码扩展参照ServiceFunFilter
*/
using VolPro.Core.BaseProvider;
using VolPro.Core.Extensions.AutofacManager;
using VolPro.Entity.DomainModels;
using System.Linq;
using VolPro.Core.Utilities;
using System.Linq.Expressions;
using VolPro.Core.Extensions;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.AspNetCore.Http;
using Warehouse.IRepositories;
namespace Warehouse.Services
{
public partial class iot_devicedataService
{
private readonly IHttpContextAccessor _httpContextAccessor;
private readonly Iiot_devicedataRepository _repository;//访问数据库
[ActivatorUtilitiesConstructor]
public iot_devicedataService(
Iiot_devicedataRepository dbRepository,
IHttpContextAccessor httpContextAccessor
)
: base(dbRepository)
{
_httpContextAccessor = httpContextAccessor;
_repository = dbRepository;
//多租户会用到这init代码，其他情况可以不用
//base.Init(dbRepository);
}
}
}

41
api_sqlsugar/Warehouse/Services/device_manager/Partial/video_channelService.cs
View File

@@ -1,41 +0,0 @@
/*
*所有关于video_channel类的业务代码应在此处编写
*可使用repository.调用常用方法，获取EF/Dapper等信息
*如果需要事务请使用repository.DbContextBeginTransaction
*也可使用DBServerProvider.手动获取数据库相关信息
*用户信息、权限、角色等使用UserContext.Current操作
*video_channelService对增、删、改查、导入、导出、审核业务代码扩展参照ServiceFunFilter
*/
using VolPro.Core.BaseProvider;
using VolPro.Core.Extensions.AutofacManager;
using VolPro.Entity.DomainModels;
using System.Linq;
using VolPro.Core.Utilities;
using System.Linq.Expressions;
using VolPro.Core.Extensions;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.AspNetCore.Http;
using Warehouse.IRepositories;
namespace Warehouse.Services
{
public partial class video_channelService
{
private readonly IHttpContextAccessor _httpContextAccessor;
private readonly Ivideo_channelRepository _repository;//访问数据库
[ActivatorUtilitiesConstructor]
public video_channelService(
Ivideo_channelRepository dbRepository,
IHttpContextAccessor httpContextAccessor
)
: base(dbRepository)
{
_httpContextAccessor = httpContextAccessor;
_repository = dbRepository;
//多租户会用到这init代码，其他情况可以不用
//base.Init(dbRepository);
}
}
}

41
api_sqlsugar/Warehouse/Services/device_manager/Partial/video_recordService.cs
View File

@@ -1,41 +0,0 @@
/*
*所有关于video_record类的业务代码应在此处编写
*可使用repository.调用常用方法，获取EF/Dapper等信息
*如果需要事务请使用repository.DbContextBeginTransaction
*也可使用DBServerProvider.手动获取数据库相关信息
*用户信息、权限、角色等使用UserContext.Current操作
*video_recordService对增、删、改查、导入、导出、审核业务代码扩展参照ServiceFunFilter
*/
using VolPro.Core.BaseProvider;
using VolPro.Core.Extensions.AutofacManager;
using VolPro.Entity.DomainModels;
using System.Linq;
using VolPro.Core.Utilities;
using System.Linq.Expressions;
using VolPro.Core.Extensions;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.AspNetCore.Http;
using Warehouse.IRepositories;
namespace Warehouse.Services
{
public partial class video_recordService
{
private readonly IHttpContextAccessor _httpContextAccessor;
private readonly Ivideo_recordRepository _repository;//访问数据库
[ActivatorUtilitiesConstructor]
public video_recordService(
Ivideo_recordRepository dbRepository,
IHttpContextAccessor httpContextAccessor
)
: base(dbRepository)
{
_httpContextAccessor = httpContextAccessor;
_repository = dbRepository;
//多租户会用到这init代码，其他情况可以不用
//base.Init(dbRepository);
}
}
}

22
api_sqlsugar/Warehouse/Services/device_manager/base_deviceService.cs
View File

@@ -1,22 +0,0 @@
/*
*Author：jxx
*Contact：283591387@qq.com
*代码由框架生成,此处任何更改都可能导致被代码生成器覆盖
*所有业务编写全部应在Partial文件夹下base_deviceService与Ibase_deviceService中编写
*/
using Warehouse.IRepositories;
using Warehouse.IServices;
using VolPro.Core.BaseProvider;
using VolPro.Core.Extensions.AutofacManager;
using VolPro.Entity.DomainModels;
namespace Warehouse.Services
{
public partial class base_deviceService : ServiceBase<base_device, Ibase_deviceRepository>
, Ibase_deviceService, IDependency
{
public static Ibase_deviceService Instance
{
get { return AutofacContainerModule.GetService<Ibase_deviceService>(); } }
}
}

22
api_sqlsugar/Warehouse/Services/device_manager/gateway_nodesService.cs
View File

@@ -1,22 +0,0 @@
/*
*Author：jxx
*Contact：283591387@qq.com
*代码由框架生成,此处任何更改都可能导致被代码生成器覆盖
*所有业务编写全部应在Partial文件夹下gateway_nodesService与Igateway_nodesService中编写
*/
using Warehouse.IRepositories;
using Warehouse.IServices;
using VolPro.Core.BaseProvider;
using VolPro.Core.Extensions.AutofacManager;
using VolPro.Entity.DomainModels;
namespace Warehouse.Services
{
public partial class gateway_nodesService : ServiceBase<gateway_nodes, Igateway_nodesRepository>
, Igateway_nodesService, IDependency
{
public static Igateway_nodesService Instance
{
get { return AutofacContainerModule.GetService<Igateway_nodesService>(); } }
}
}

22
api_sqlsugar/Warehouse/Services/device_manager/iot_alarmService.cs
View File

@@ -1,22 +0,0 @@
/*
*Author：jxx
*Contact：283591387@qq.com
*代码由框架生成,此处任何更改都可能导致被代码生成器覆盖
*所有业务编写全部应在Partial文件夹下iot_alarmService与Iiot_alarmService中编写
*/
using Warehouse.IRepositories;
using Warehouse.IServices;
using VolPro.Core.BaseProvider;
using VolPro.Core.Extensions.AutofacManager;
using VolPro.Entity.DomainModels;
namespace Warehouse.Services
{
public partial class iot_alarmService : ServiceBase<iot_alarm, Iiot_alarmRepository>
, Iiot_alarmService, IDependency
{
public static Iiot_alarmService Instance
{
get { return AutofacContainerModule.GetService<Iiot_alarmService>(); } }
}
}

22
api_sqlsugar/Warehouse/Services/device_manager/iot_devicedataService.cs
View File

@@ -1,22 +0,0 @@
/*
*Author：jxx
*Contact：283591387@qq.com
*代码由框架生成,此处任何更改都可能导致被代码生成器覆盖
*所有业务编写全部应在Partial文件夹下iot_devicedataService与Iiot_devicedataService中编写
*/
using Warehouse.IRepositories;
using Warehouse.IServices;
using VolPro.Core.BaseProvider;
using VolPro.Core.Extensions.AutofacManager;
using VolPro.Entity.DomainModels;
namespace Warehouse.Services
{
public partial class iot_devicedataService : ServiceBase<iot_devicedata, Iiot_devicedataRepository>
, Iiot_devicedataService, IDependency
{
public static Iiot_devicedataService Instance
{
get { return AutofacContainerModule.GetService<Iiot_devicedataService>(); } }
}
}

22
api_sqlsugar/Warehouse/Services/device_manager/video_channelService.cs
View File

@@ -1,22 +0,0 @@
/*
*Author：jxx
*Contact：283591387@qq.com
*代码由框架生成,此处任何更改都可能导致被代码生成器覆盖
*所有业务编写全部应在Partial文件夹下video_channelService与Ivideo_channelService中编写
*/
using Warehouse.IRepositories;
using Warehouse.IServices;
using VolPro.Core.BaseProvider;
using VolPro.Core.Extensions.AutofacManager;
using VolPro.Entity.DomainModels;
namespace Warehouse.Services
{
public partial class video_channelService : ServiceBase<video_channel, Ivideo_channelRepository>
, Ivideo_channelService, IDependency
{
public static Ivideo_channelService Instance
{
get { return AutofacContainerModule.GetService<Ivideo_channelService>(); } }
}
}

22
api_sqlsugar/Warehouse/Services/device_manager/video_recordService.cs
View File

@@ -1,22 +0,0 @@
/*
*Author：jxx
*Contact：283591387@qq.com
*代码由框架生成,此处任何更改都可能导致被代码生成器覆盖
*所有业务编写全部应在Partial文件夹下video_recordService与Ivideo_recordService中编写
*/
using Warehouse.IRepositories;
using Warehouse.IServices;
using VolPro.Core.BaseProvider;
using VolPro.Core.Extensions.AutofacManager;
using VolPro.Entity.DomainModels;
namespace Warehouse.Services
{
public partial class video_recordService : ServiceBase<video_record, Ivideo_recordRepository>
, Ivideo_recordService, IDependency
{
public static Ivideo_recordService Instance
{
get { return AutofacContainerModule.GetService<Ivideo_recordService>(); } }
}
}

40
doc/db_init.sql
View File

@@ -4,6 +4,8 @@
-- 扩展表已合并到 Base_Device.ExtraData(JSON)
-- ============================================
USE gljs_main;
-- ============================================
-- 1. 统一设备主表
-- ExtraData(JSON) 承载所有适配器特有字段
@@ -13,15 +15,15 @@ DROP TABLE IF EXISTS base_device;
CREATE TABLE base_device (
DeviceId INT AUTO_INCREMENT COMMENT '设备ID',
DeviceName NVARCHAR(100) NOT NULL COMMENT '设备名称',
AdapterCode NVARCHAR(50) COMMENT '来源适配器(类型:实例)',
SourceId NVARCHAR(100) COMMENT '源系统设备ID',
AdapterCode NVARCHAR(50) NOT NULL COMMENT '来源适配器(类型:实例)',
SourceId NVARCHAR(100) NOT NULL COMMENT '源系统设备ID',
DeviceCategory NVARCHAR(50) NOT NULL COMMENT '设备种类(数据字典：门磁/空调/智能断路器/人行道闸/车辆道闸/485钥匙柜/网络钥匙柜/紧急报警按钮/红外报警器/门禁一体机/除湿_恒湿机/空调控制器/烟雾报警器/气体报警器/温湿度变送器/摄像机/硬盘录像机/动环采集器)',
DeviceGroup NVARCHAR(20) NOT NULL COMMENT '设备分组(数据字典：视频设备/IoT设备/门禁设备/道闸设备/报警设备)',
PointId INT NULL COMMENT '所属点位ID',
NodeId INT NULL COMMENT '所属网关节点ID',
GatewayNodeId INT NULL COMMENT '所属网关节点ID',
IsParent NVARCHAR(20) NOT NULL DEFAULT '否' COMMENT '是否父设备(数据字典：是/否)',
ParentDeviceId INT NULL COMMENT '父设备ID(自引用,子设备挂父设备下)',
IsOnline NVARCHAR(20) DEFAULT '离线' COMMENT '在线状态(数据字典：在线/离线)',
IsOnline NVARCHAR(20) NOT NULL DEFAULT '离线' COMMENT '在线状态(数据字典：在线/离线)',
IpAddress NVARCHAR(50) COMMENT 'IP地址',
Port INT COMMENT '端口',
Location NVARCHAR(200) COMMENT '安装位置',
@@ -161,33 +163,3 @@ CREATE TABLE gateway_nodes (
UNIQUE INDEX IX_Code (NodeCode),
INDEX IX_Online (IsOnline)
) COMMENT '网关节点注册表';
-- ═══════════════════════════════════════════════
-- SecMPS 规则引擎: warehouse_variable 变量定义表 (P1-6)
-- =================================================
-- 规则条件/动作的 ValueId 绑定到此表的 VariableId
-- DeviceId 关联 base_device.DeviceId
-- =================================================
CREATE TABLE warehouse_variable (
VariableId INT IDENTITY(1,1) PRIMARY KEY,
DeviceId INT NOT NULL,
VariableName NVARCHAR(255) NOT NULL, -- 温度/湿度/人数
PointIndex INT DEFAULT 0, -- MC4 pointIndex / Owl 统计量编码
Unit NVARCHAR(50) NULL, -- ℃/%/人
SortOrder INT DEFAULT 0
);
CREATE INDEX IX_warehouse_variable_DeviceId ON warehouse_variable (DeviceId);
-- F3.2 规则引擎滞后窗 (hysteresis)
ALTER TABLE warehouse_rulecondition ADD
RecoveryThreshold_Numeric DECIMAL(18,2) NULL,
RecoveryThreshold_Switch NVARCHAR(50) NULL;
-- F3.3 条件级冷却
ALTER TABLE warehouse_rulecondition ADD
LastTriggered DATETIME NULL,
LastTriggerValue DECIMAL(18,2) NULL;

3
doc/error/KMS_error_20260519.txt
View File

@@ -1,3 +0,0 @@
严重性 代码 说明 项目 文件 行 抑制状态 详细信息
错误(活动) CS1061 “ControlRequest”未包含“Command”的定义，并且找不到可接受第一个“ControlRequest”类型参数的可访问扩展方法“Command”(是否缺少 using 指令或程序集引用?) IntegrationGateway.Host D:\Code\SecMPS\gateway\src\IntegrationGateway.Host\Program.cs 213
错误(活动) CS1061 “ControlRequest”未包含“Parameters”的定义，并且找不到可接受第一个“ControlRequest”类型参数的可访问扩展方法“Parameters”(是否缺少 using 指令或程序集引用?) IntegrationGateway.Host D:\Code\SecMPS\gateway\src\IntegrationGateway.Host\Program.cs 213

608
doc/代码审核/代码审核20260604.md
View File

@@ -1,608 +0,0 @@
# warehouse 客户端代码深度审核报告（含完整修复方案）
> 日期: 2026-06-04 | 项目: warehouse/ | 扫描: 38 源文件, ~12,000 行 | 问题: 70 项
---
## 1. `api/http.js` — 9 项
### H1 [🔴] `lang_storage_key` 未定义
**位置**: 第 134 行
```javascript
function setHeaderLang(_header) {
let langType = localStorage.getItem(lang_storage_key) // ← 未定义!
}
```
**后果**: 运行时报错 `lang_storage_key is not defined`，语言功能完全失效。
**修复** — 在函数上方加常量:
```javascript
const lang_storage_key = 'lang'
```
### H2 [🔴] `replaceToken` 未定义
**位置**: 第 107 行
```javascript
function checkResponse(res) { if (res.headers.vol_exp == '1') { replaceToken() } }
```
**后果**: Token 过期后调用未定义函数，静默失败。
**修复** — 在 `checkResponse` 前追加:
```javascript
function replaceToken() {
store.dispatch('clearUserInfo')
window.location.href = '/login'
}
```
**跨文件影响**: 需确认 `store/index.js` 有 `clearUserInfo` mutation（已存在）。
### H3 [🔴] `toLogin` 未定义
**位置**: 第 77 行
```javascript
if (error.response.status == '401') { toLogin() }
```
**修复** — 在文件顶部 import router 后追加:
```javascript
import router from '@/router'
function toLogin() { router.push('/login') }
```
**跨文件影响**: 需确认 `router/index.ts` 导出 router 实例。
### H4 [🟠] 降级地址硬编码
**位置**: 第 25-33 行
```javascript
axios.defaults.baseURL = 'http://192.168.3.108:9100/'
dataViewUrl = 'http://192.168.3.108:9200/'
```
**修复**:
```javascript
axios.defaults.baseURL = window.location.origin
dataViewUrl = (window as any).apiConfig?.dataViewUrl || window.location.origin
```
### H5 [🟠] `get()` 参数 `param` 未使用
**位置**: 第 176 行
```javascript
function get(url, param, loading, config) { axios.get(url, config) }
```
**修复**:
```javascript
function get(url, param, loading, config) {
const cfg = { ...config }
if (param) cfg.params = param
// ... 其余不变
axios.get(url, cfg).then(...)
}
```
### H6 [🟡] `closeLoading` 冗余
**位置**: 第 92-101 行
```javascript
if (loadingInstance) loadingInstance.close()
if (loadingStatus) { loadingStatus = false; if (loadingInstance) loadingInstance.close() }
```
**修复**:
```javascript
loadingStatus = false
loadingInstance?.close()
```
### H7 [🟡] `alert()` 弹窗
**位置**: 第 199 行
```javascript
alert('http.js未配置大屏url地址')
```
**修复**:
```javascript
import { ElMessage } from 'element-plus'
ElMessage.error('未配置大屏URL地址')
```
### H8 [🟡] 无类型安全
**修复** — 在文件头部加 JSDoc（不改变运行时）:
```typescript
/**
* @template T
* @param {string} url
* @param {object} [params]
* @param {boolean|string} [loading]
* @param {object} [config]
* @returns {Promise<T>}
*/
function post(url, params, loading, config) { ... }
```
### H9 [⚪] 文件臃肿 (409行)
**修复** — 拆为 3 文件:
- `api/http-client.ts` — Axios 实例 + baseURL + 拦截器 (80行)
- `api/http-auth.ts` — getToken/replaceToken/toLogin (40行)
- `api/http-loading.ts` — showLoading/closeLoading (20行)
`api/http.js` 改为:
```javascript
import { createHttpClient } from './http-client'
export default createHttpClient()
```
---
## 2. `api/gateway.ts` — 3 项
### GW1 [🟠] 网关地址硬编码
**位置**: 第 5 行 `const GW_BASE = 'http://192.168.3.108:5100'`
**修复**:
```typescript
const GW_BASE = (window as any).apiConfig?.gatewayUrl || 'http://localhost:5100'
```
### GW2 [🟡] `fetch()` 无超时
**修复** — 完整重写 `gwGet`（`gwPost` 同理）:
```typescript
export async function gwGet(url: string, timeoutMs = 10000): Promise<any> {
const ctrl = new AbortController()
const timer = setTimeout(() => ctrl.abort(), timeoutMs)
try {
const resp = await fetch(`${GW_BASE}${url}`, { signal: ctrl.signal })
if (!resp.ok) throw new Error(`网关请求失败: ${resp.status}`)
return resp.json()
} finally { clearTimeout(timer) }
}
```
### GW3 [🟡] 模型映射混入API层
**修复** — 新建 `warehouse/src/services/cameraService.ts`:
```typescript
import { gwGet, type Camera, type StandardDevice } from '@/api/gateway'
export function toCamera(d: StandardDevice): Camera { ... }
export async function fetchCameras(adapter: string): Promise<Camera[]> { ... }
```
**跨文件影响**: `Live.vue`, `VideoWall.vue`, `History.vue` 的 import 改为 `from '@/services/cameraService'`
---
## 3. `api/buttons.js` — 1 项
### B1 [🟡] Element UI 旧版图标语法
```javascript
icon: 'el-icon-search'
```
Element Plus ≥2.0 已废弃字符串图标。
**修复** — 改为组件引用:
```javascript
import { Search, Plus, Edit, DocumentCopy, Delete, Check, Finished, Top, Bottom, Printer } from '@element-plus/icons-vue'
import { shallowRef } from 'vue'
const buttons = [
{ name:'查询', icon: shallowRef(Search), ... },
{ name:'新建', icon: shallowRef(Plus), ... },
// ... 其余同理
]
```
**跨文件影响**: 使用 buttons 的组件需确认其渲染逻辑支持组件引用（通常通过 `<component :is="btn.icon" />`）。
---
## 4. `api/permission.js` — 2 项
### PE1 [🟠] 权限缺失时静默放行
**位置**: 第 24 行
```javascript
if (!permission) { permission = { permission: ['Search'] } }
```
**修复**:
```javascript
if (!permission) { return [] }
```
空数组使所有按钮不可见（安全默认）。
### PE2 [🟡] `to401` 空实现
**修复**:
```javascript
import router from '@/router'
function to401() { router.push('/401') }
```
---
## 5. `router/index.ts` — 5 项
### R1 [🟠] 40+ 条路由指向同一组件
所有菜单子项渲染 `Index.vue`，用户看到重复空白页。
**修复** — 3 步方案:
1. 为已实现的页面保留独立路由（VideoWall/AlarmRecord/AccessRecord 等已存在）
2. 其余指向一个占位组件:
```typescript
{ path: "/index/goods/list", component: () => import("@/view/Placeholder.vue") }
```
3. `Placeholder.vue`:
```vue
<template><el-empty description="功能开发中" /></template>
```
### R2 [🟡] `/new-dv` 不要求认证
```typescript
{ path:"/new-dv", meta:{ requiresAuth: false } }
```
**修复**: 改为 `requiresAuth: true`。
### R3 [🟡] 缺少 beforeEach 守卫
**修复** — 在 `router/index.ts` 末尾追加:
```typescript
router.beforeEach((to, from, next) => {
if (to.meta.requiresAuth !== false) {
const token = localStorage.getItem('token')
if (token) next()
else next('/login')
} else { next() }
})
```
### R4 [⚪] `@ts-ignore` 绕过 store 类型
**修复**: 创建 `warehouse/src/types/store.d.ts`:
```typescript
declare module '@/store' {
const store: import('vuex').Store<any>
export default store
}
```
### R5 [⚪] 仓库/货物/出入库路由 20+ 条未使用
**修复**: 删除。若后续需要可从 git 恢复。
---
## 6. `main.ts` — 1 项
### M1 [🟡] 暗色模式写死
```typescript
app.use(ElementPlus, { dark: true })
```
**修复**:
```typescript
const dark = localStorage.getItem('dark-mode') !== 'false'
app.use(ElementPlus, { dark })
```
---
## 7. `view/index.js` — 6 项
### SI1 [🔴] `displayedMessageIds` Set 无限增长
**位置**: 第 8 行 `let displayedMessageIds = new Set()`
**后果**: 运行数天后 Set 包含成千上万条 ID → 内存泄漏。
**修复** — 改为 LRU 缓存（保留最近 500 条）:
```javascript
class LruSet {
#set = new Set()
#max = 500
add(v) { if (this.#set.has(v)) return; this.#set.add(v); if (this.#set.size > this.#max) { this.#set.delete(this.#set.values().next().value) } }
has(v) { return this.#set.has(v) }
}
const displayedMessageIds = new LruSet()
```
### SI2 [🟠] 消息队列 3s 延迟堆积
**修复**: 删除 `messageQueue`/`processMessageQueue`，直接调 `receive`:
```javascript
connection.on("ReceiveHomePageMessage", function (data) {
if (displayedMessageIds.has(data.id)) return
displayedMessageIds.add(data.id)
receive(data)
})
```
### SI3 [🟠] connection 启动无重试
`connection.start().catch(...)` 失败后永远不重试。
**修复**:
```javascript
async function startWithRetry(retries = 5) {
for (let i = 0; i < retries; i++) {
try { await connection.start(); return }
catch (e) { console.warn(`SignalR retry ${i+1}/${retries}: ${e.message}`); await new Promise(r => setTimeout(r, 2000)) }
}
console.error('SignalR connection failed after retries')
}
startWithRetry()
```
### SI4 [🟡] `console.log` 残留 6 处
**修复**: 全部替换为 `if (import.meta.env.DEV) console.log(...)`。
### SI5 [🟡] `receive` 被双重调用
`processMessageQueue` 和 `ReceiveHomePageMessage` 都调了 `receive`。
**修复**: SI2 删除了 `processMessageQueue` 后此问题自动消除。
### SI6 [🟡] 用户信息获取失败静默
**修复**:
```javascript
http.post("api/user/GetCurrentUserInfo").then(...).catch(error => {
console.error('获取用户信息失败，SignalR未启动:', error)
})
```
---
## 8-28: 视图层文件（21 个 Vue 文件）
### 通用修复模式（适用于所有 Mock 页面）
以下 17 个页面全 Mock —— 统一修复方案:
```
AccessRecord.vue, AlarmRecord.vue, EmergencyAlarmRecord.vue,
KeyInfo.vue, KeyApply.vue, EnvVarManagement.vue,
PatrolLog.vue, ScheduleManagement.vue, PathManagement.vue,
DroneManagement.vue, dataview.vue, CarApply.vue, CarManager.vue,
DeviceStatus.vue(V), VisitorsManagement.vue, VisitCarManagement.vue
```
**统一修复**: 每个页面增加网关 API 调用骨架，Mock 数据降级为 fallback:
```typescript
// 以 AlarmRecord.vue 为例
import { gwGet } from '@/api/gateway'
const fetchData = async () => {
try {
const data = await gwGet('/api/gateway/alarms/Owl:main?page=1&size=100')
alarmData.value = data.items.map((a: StandardAlarm) => ({
id: a.alarmId, alarmTime: a.occurTime, deviceName: a.title,
location: a.deviceId, status: a.status, imageUrl: '/images/placeholder.png'
}))
} catch {
alarmData.value = getMockAlarmData() // fallback
}
}
```
### 单个页面专项修复
**DataView.vue** (1840行):
- DV1: 告警等级 → 改用 `level` 字段或网关 `StandardAlarm.level` 值
- DV2: `setTimeout` 加 `clearTimeout`:
```typescript
const timers = new Set<number>()
onBeforeUnmount(() => timers.forEach(t => clearTimeout(t)))
// 使用时: timers.add(setTimeout(...))
```
- DV6: `originalData: JSON.parse(JSON.stringify(data))` 避免循环引用
**DeviceInfo.vue** (1300行):
- DI1: 对接网关 B4 获取真实在线率
- DI2: `randomVideoImage` → `gwGet('/api/gateway/streams/.../live')`
- DI3: `handleTurnOn` → `gwPost('/api/gateway/realtime/.../control', { deviceId, pointIndex, value })`
**Live.vue** / **VideoWall.vue** / **History.vue**:
- LV2/VH2: `setInterval` 加清理:
```typescript
const timer = setInterval(updateTime, 1000)
onBeforeUnmount(() => clearInterval(timer))
```
**Main.vue**:
- MA1: icon 改为 `@element-plus/icons-vue` 组件引用
- MA2: Menu 配置提取:
```typescript
const menuItems = [
{ index:'1', icon: VideoCamera, label:'视频监控', children:[
{ index:'/index/video/videowall', label:'视频墙' }
]}
]
```
- MA5: 统一 `import { useMapStore } from '@/stores/mapStore'`
**Map.vue**:
- MP1: `const m = /#\/(\d+)/.exec(location.hash); const mapId = m?.[1] || 'default'`
**Index.vue**:
- IN1: `const mapId = import.meta.env.VITE_MAP_ID || 'default'`
---
## 29-31: 组件层（3 文件）
### Filter.vue [🟡]
**console.log 8 处**: 同 SI4，改为条件输出。
**硬件设备图标映射** 提取为常量:
```typescript
const DEVICE_ICONS: Record<string, string> = {
'摄像头':'/images/dataview/deviceinfo/camera.png',
'门禁':'/images/dataview/deviceinfo/access.png',
// ...
}
```
### Fence.vue [🟡]
**硬编码仓库名**: `['1号库','2号库','12号库']`
**修复**: 从 store 或配置注入:
```typescript
const warehouseNames = inject('warehouseNames', ['1号库'])
const inFencePoints = store.polygonDataAll.filter(p => warehouseNames.includes(p.name))
```
---
## 32-34: 状态管理层（3 文件）
### SM1 [🔴] 两份 `useMapStore` 同名
**文件**: `stores/mapStore.js` 和 `store/useMapStore.js` 都 `defineStore('map', ...)`
**修复** — 选择一份保留（推荐 `stores/mapStore.js` 功能更全），另一份删除:
```bash
git rm warehouse/src/store/useMapStore.js
```
**跨文件影响** — 修改以下文件的 import:
- `Map.vue` line 9: `'../store/useMapStore'` → `'../stores/mapStore'`
- `Index.vue` line 10: `'../stores/mapStore'` (已对)
- `Fence.vue` line 4: `'../store/useMapStore'` → `'../stores/mapStore'`
- `Filter.vue` line 3: `'../store/useMapStore'` → `'../stores/mapStore'`
- `DataView.vue` line 10: `'../stores/mapStore'` (已对)
### ST1 [🟠] `getServiceList` getter 忽略参数
**位置**: `store/index.js`
```javascript
getServiceList: (state) => (path) => { return state.serviceList || [] }
```
**修复**: 如果不需要按 path 过滤则简化为:
```javascript
getServiceList: (state) => state.serviceList || []
```
### ST3 [🟡] `test` mutation 返回 `113344`
**位置**: `store/index.js` line 49
```javascript
test(state) { return 113344 } // 调试代码
```
**修复**: 删除此 mutation。
### ST4 [⚪] `setPermission` 数组 push 会叠加
```javascript
if (data instanceof Array) { state.permission.push(...data) }
```
每次调用追加而非替换。**修复**: 始终替换 `state.permission = data`。
---
## 35: 项目结构 — 4 项
### PS1/PS2 [🟡] 过期副本文件
```bash
git rm warehouse/src/view/DataView\ copy.vue
git rm warehouse/src/view/Map.vue.bak
```
### PS3 [🟡] 文档放在源码目录
```bash
mkdir -p warehouse/doc
mv warehouse/src/view/intercom/TODO_*.md warehouse/doc/
```
### PS4 [🟠] Vuex + Pinia 共存
**修复** — 迁移 Vuex → Pinia:
1. 新建 `stores/authStore.js`（替代 Vuex 的 userInfo/token/permission）
2. 迁移 `store/index.js` 中的 `setUserInfo`/`getToken`/`getPermission` 到 Pinia
3. `npm uninstall vuex`
4. 修改 `http.js`/`Login.vue`/`permission.js` 从 `@/stores/authStore` 导入
---
## 36: 全局问题 — 7 项
### G1 [🟠] Mock 覆盖率 86%
22 页面中仅 3 个对接网关。**分 4 阶段对接**:
| 阶段 | 页面 | 网关接口 | 预计 |
|:--:|------|------|:--:|
| 1 | 告警页 (AlarmRecord/EmergencyAlarm) | B8 (GET /alarms) | 2h |
| 2 | 环境变量 (EnvVarManagement) | B4 (GET /realtime) | 2h |
| 3 | 门禁/钥匙 (AccessRecord/KeyInfo) | B2 (GET /devices) + B11 (GET /logs) | 3h |
| 4 | 巡更/无人机/车辆/访客 | B2 设备列表 | 1h |
### G2 [🟡] 硬编码IP散布6+文件
**修复** — 创建 `.env.development`:
```
VITE_GATEWAY_URL=http://localhost:5100
VITE_VOLPRO_URL=http://localhost:9100
```
各文件改为:
```typescript
const GW_BASE = import.meta.env.VITE_GATEWAY_URL || 'http://localhost:5100'
```
### G3 [🟡] JS/TS 混用
**修复**: 7 个 `.js` → `.ts`（逐文件迁移，不改运行时逻辑）:
```
api/http.js → api/http.ts
api/buttons.js → api/buttons.ts
api/permission.js → api/permission.ts
view/index.js → view/index.ts
stores/mapStore.js → stores/mapStore.ts
router/viewGird.js → router/viewGird.ts
```
### G4 [🟡] `window.*` 全局变量
**修复**: `window.$map` → Store 管理（已存在 `mapStore.setMap`）
```typescript
// Map.vue: 删除 window.$map = map，保留 store.setMap(map)
// 其他文件: 改 window.$map → const { map } = useMapStore()
```
### G5 [🟡] `console.log` 残留 30+ 处
**修复** — 一行全局替换:
```bash
# 将所有 console.log 改为条件输出
find warehouse/src -name "*.vue" -o -name "*.ts" -o -name "*.js" | xargs sed -i 's/console\.log(/if(import\.meta\.env\.DEV)console.log(/g'
```
### G6 [⚪] 无全局错误边界
**修复** — `main.ts`:
```typescript
app.config.errorHandler = (err) => {
console.error('Global error:', err)
ElMessage.error('系统异常，请刷新页面')
}
```
### G7 [⚪] `counter.ts` 模板残留
**修复**: 删除 `warehouse/src/stores/counter.ts`。
---
## 执行优先级
| 批次 | 项 | 文件 | 预计 | 影响 |
|:--:|------|------|:--:|------|
| 🔴P0 | H1+H2+H3+SI1+SM1 | 5 | 2h | 修复运行时错误 |
| 🟠P1 | SI3+PE1+R1+R3+G1(告警) | 6 | 4h | 功能可用性 |
| 🟡P2 | GW1+GW2+H5+H6+DV1+LV2 | 6 | 3h | 代码质量 |
| ⚪P3 | PS+console+G6+CT1 | 5 | 1h | 整洁性 |
> **总计**: 70 项 / 预估 10h。P0 批 5 项必须在联调前完成。

3419
doc/对接文档/GoWVP接口文档.md
View File

File diff suppressed because it is too large Load Diff

748
doc/对接文档/网关与Vol.Pro对接API手册.md Normal file
View File

@@ -0,0 +1,748 @@
# SecMPS 网关与 Vol.Pro 对接 API 手册
> **版本**: v1.0
> **日期**: 2026-05-16
> **基于**: SecMPS_最终整合方案_v3.0.md
> **接口数量**: 13 个（A 组 4 个 + B 组 9 个）
---
## 1. 引言
### 1.1 目标与范围
本手册定义 IntegrationGateway（网关）与 Vol.Pro 后端之间所有 HTTP API 的接口规范。供网关开发、Vol.Pro 后端开发、前端开发和 AI Agent 编码时参考。
### 1.2 基本约定
| 约定 | 说明 |
|------|------|
| 请求方法 | A 组使用 **POST**，B 组使用 **GET / POST** |
| 数据格式 | **JSON**，`Content-Type: application/json` |
| 字符编码 | **UTF-8** |
| 认证方式 | A 组: `NodeToken`（请求体中携带），B 组: 内网直连，无认证 |
| 网关端口 | **5100**（默认） |
| Vol.Pro 端口 | **9100**（默认） |
### 1.3 响应格式
**成功**:
```json
{
// 具体数据，见各接口定义
}
```
HTTP Status: 200
**失败**:
```json
{
"message": "错误描述"
}
```
HTTP Status: 400（业务错误）/ 401（认证失败）/ 500（服务器错误）
---
## 2. A 组接口：网关 → Vol.Pro
> 调用方: 网关
> 接收方: Vol.Pro 后端
> 端口: 9100
---
### 2.1 A1 — 网关注册
网关启动时调用，上报身份与能力，获取所管理的顶层设备列表。
- **Endpoint**: `POST /api/gateway/register`
- **认证**: NodeToken
- **逻辑**: Upsert — NodeCode 匹配则更新，不匹配则插入
#### 请求体
```json
{
"nodeCode": "gw-31ku",
"token": "a1b2c3d4e5f6",
"adapterTypes": "MC4,Owl",
"baseUrl": "http://192.168.1.100:5100"
}
```
| 字段 | 类型 | 必填 | 说明 |
|------|------|:---:|------|
| nodeCode | string | ✅ | 网关唯一编码，管理端生成 |
| token | string | ✅ | 认证令牌，管理端生成 |
| adapterTypes | string | ✅ | 支持的适配器类型，逗号分隔，例如 "MC4,Owl" |
| baseUrl | string | ✅ | 网关自身地址（含端口），供管理端回调 |
#### 响应体（成功）
```json
{
"nodeId": 1,
"devices": [
{
"deviceId": 10,
"deviceName": "动环采集器",
"adapterCode": "MC4:31ku",
"sourceId": "1001",
"deviceCategory": "动环采集器",
"deviceGroup": "IoT设备",
"isParent": "是",
"parentSourceId": null,
"isOnline": "在线",
"ipAddress": "10.0.1.100",
"port": 3000,
"extraData": {
"mc4DeviceId": 1001
}
}
]
}
```
| 字段 | 类型 | 说明 |
|------|------|------|
| nodeId | int | 网关在 Vol.Pro 中的 NodeId |
| devices | array | 当前网关负责的顶层设备列表（base_device 中 GatewayNodeId=本网关 且 ParentDeviceId IS NULL 的记录） |
| devices[].deviceId | int | Vol.Pro 内部设备ID |
| devices[].adapterCode | string | 双段标识 "MC4:31ku" |
| devices[].sourceId | string | 第三方原始设备ID |
| devices[].extraData | object | 适配器扩展数据 |
#### 响应体（失败）
```json
// HTTP 401
{
"message": "认证失败"
}
```
#### 请求示例
```bash
curl -X POST http://localhost:9100/api/gateway/register \
-H "Content-Type: application/json" \
-d '{"nodeCode":"gw-31ku","token":"a1b2c3d4e5f6","adapterTypes":"MC4,Owl","baseUrl":"http://192.168.1.100:5100"}'
```
---
### 2.2 A2 — 网关心跳
网关每 15 秒调用，Vol.Pro 更新 LastHeartbeat 和 IsOnline。
- **Endpoint**: `POST /api/gateway/heartbeat`
- **认证**: NodeToken
- **频率**: 每 15 秒
#### 请求体
```json
{
"nodeCode": "gw-31ku",
"token": "a1b2c3d4e5f6"
}
```
| 字段 | 类型 | 必填 | 说明 |
|------|------|:---:|------|
| nodeCode | string | ✅ | 网关唯一编码 |
| token | string | ✅ | 认证令牌 |
#### 响应体
```json
{
"status": "ok",
"serverTime": "2026-05-16 15:30:00"
}
```
| 字段 | 类型 | 说明 |
|------|------|------|
| status | string | 固定 "ok" |
| serverTime | string | Vol.Pro 当前时间，供网关校时 |
#### 请求示例
```bash
curl -X POST http://localhost:9100/api/gateway/heartbeat \
-H "Content-Type: application/json" \
-d '{"nodeCode":"gw-31ku","token":"a1b2c3d4e5f6"}'
```
---
### 2.3 A3 — 设备数据同步
网关发现新设备或设备状态变更后，上送到 Vol.Pro。
- **Endpoint**: `POST /api/gateway/sync/devices`
- **认证**: NodeToken
- **字段分治**: 首次入库写全量，已有记录仅更新网关字段
#### 请求体
```json
{
"nodeCode": "gw-31ku",
"token": "a1b2c3d4e5f6",
"devices": [
{
"adapterCode": "MC4:31ku",
"sourceId": "1001",
"name": "动环采集器",
"category": "动环采集器",
"group": "IoT设备",
"isParent": true,
"parentSourceId": null,
"isOnline": true,
"ipAddress": "10.0.1.100",
"port": 3000,
"extraData": {
"mc4DeviceId": 1001
}
},
{
"adapterCode": "MC4:31ku",
"sourceId": "1001_0",
"name": "温湿度变送器",
"category": "温湿度变送器",
"group": "IoT设备",
"isParent": false,
"parentSourceId": "1001",
"isOnline": true,
"ipAddress": null,
"port": null,
"extraData": {
"mc4DeviceId": 1001,
"pointIndex": 0,
"unit": "℃"
}
}
]
}
```
| 字段 | 类型 | 必填 | 说明 |
|------|------|:---:|------|
| nodeCode | string | ✅ | 网关编码 |
| token | string | ✅ | 认证令牌 |
| devices | array | ✅ | 设备列表 |
| devices[].adapterCode | string | ✅ | 双段标识 |
| devices[].sourceId | string | ✅ | 第三方原始ID |
| devices[].name | string | ✅ | 设备名称（仅首次写入） |
| devices[].category | string | ✅ | 设备种类（仅首次写入） |
| devices[].group | string | ✅ | 设备分组（仅首次写入） |
| devices[].isParent | bool | ✅ | 是否父设备 |
| devices[].parentSourceId | string? | | 父设备第三方ID，Vol.Pro 解析为 ParentDeviceId |
| devices[].isOnline | bool | ✅ | 在线状态 |
| devices[].ipAddress | string? | | IP 地址 |
| devices[].port | int? | | 端口 |
| devices[].extraData | object | | 适配器扩展数据 |
**字段分治规则**:
- **首次入库**（DeviceId=0）: 所有字段写入
- **已有记录**: 仅更新 isOnline、isParent、parentDeviceId（解析后）、extraData、ipAddress、port、lastSyncTime
- deviceName、category、group、pointId、location、lat/lng、mapModelId 仅在首次写入
#### 响应体
```json
{
"added": 2,
"updated": 0,
"removed": 0
}
```
| 字段 | 类型 | 说明 |
|------|------|------|
| added | int | 新增设备数 |
| updated | int | 更新设备数 |
| removed | int | 删除设备数（FullReplace 模式下可能 >0） |
#### 请求示例
```bash
curl -X POST http://localhost:9100/api/gateway/sync/devices \
-H "Content-Type: application/json" \
-d '{"nodeCode":"gw-31ku","token":"a1b2c3d4e5f6","devices":[...]}'
```
---
### 2.4 A4 — 告警数据同步
网关发现新告警后上送。
- **Endpoint**: `POST /api/gateway/sync/alarms`
- **认证**: NodeToken
#### 请求体
```json
{
"nodeCode": "gw-31ku",
"token": "a1b2c3d4e5f6",
"alarms": [
{
"sourceAlarmId": "2183fda3-9e32-48ae-b433-f807cc81a237",
"deviceSourceId": "1001_0",
"adapterCode": "MC4:31ku",
"level": "重要",
"desc": "温度超限: [温湿度变送器][45℃]",
"value": 45.0,
"startTime": "2026-05-16 14:30:00"
}
]
}
```
| 字段 | 类型 | 必填 | 说明 |
|------|------|:---:|------|
| nodeCode / token | string | ✅ | 认证信息 |
| alarms | array | ✅ | 告警列表 |
| alarms[].sourceAlarmId | string | ✅ | 源系统告警ID（用于去重） |
| alarms[].deviceSourceId | string | ✅ | 告警所属设备的第三方ID |
| alarms[].adapterCode | string | ✅ | 双段标识 |
| alarms[].level | string | ✅ | 告警等级(字典: 提示/普通/重要/紧急) |
| alarms[].desc | string | ✅ | 告警描述 |
| alarms[].value | double | | 触发值 |
| alarms[].startTime | string | ✅ | 告警开始时间 "yyyy-MM-dd HH:mm:ss" |
#### 响应体
```json
{
"added": 1
}
```
---
## 3. B 组接口：Vol.Pro / 管理端 → 网关
> 调用方: Vol.Pro 后端 / 管理端 / warehouse 端
> 接收方: 网关
> 端口: 5100
> 认证: 内网直连（无认证）
---
### 3.1 B1 — 健康检查
- **Endpoint**: `GET /api/gateway/health`
#### 响应体
```json
{
"gateway": "ok",
"adapters": {
"MC4:31ku": true,
"Owl:main": true
}
}
```
| 字段 | 类型 | 说明 |
|------|------|------|
| gateway | string | 固定 "ok" |
| adapters | object | key=AdapterCode, value=true(在线)/false(离线) |
#### 请求示例
```bash
curl http://localhost:5100/api/gateway/health
```
---
### 3.2 B2 — 设备列表
获取指定适配器下的设备列表（实时查询第三方）。
- **Endpoint**: `GET /api/gateway/devices`
- **适配器**: IHasFlatDevices
#### 请求参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|:---:|------|
| adapter | string | ✅ | AdapterCode，例如 "Owl:main" |
| page | int | | 页码，默认 1 |
| size | int | | 每页大小，默认 50 |
| keyword | string | | 名称/ID 模糊搜索 |
#### 响应体
```json
{
"items": [
{
"sourceId": "gb_34020000001320000001",
"adapterCode": "Owl:main",
"name": "NVR-01",
"category": "硬盘录像机",
"group": "视频设备",
"isOnline": true,
"isParent": true,
"ipAddress": "192.168.1.100",
"port": 5060,
"channelCount": 4,
"extraData": {
"owlDeviceId": "gb_34020000001320000001",
"protocol": "GB28181",
"transport": "UDP"
}
}
],
"total": 50
}
```
---
### 3.3 B3 — 手动触发同步
管理端手动触发全量设备同步。
- **Endpoint**: `POST /api/gateway/devices/sync`
- **适配器**: 所有实现了 IHasFlatDevices 或 IHasOwnDeviceTree 的适配器
#### 请求参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|:---:|------|
| adapter | string | ✅ | AdapterCode |
#### 响应体
```json
{
"adapterCode": "Owl:main",
"added": 5,
"updated": 3,
"removed": 1,
"errors": [],
"startTime": "2026-05-16T15:30:00",
"endTime": "2026-05-16T15:30:05"
}
```
| 字段 | 类型 | 说明 |
|------|------|------|
| adapterCode | string | 适配器编码 |
| added | int | 新增数 |
| updated | int | 更新数 |
| removed | int | 删除数 |
| errors | array | 错误信息列表 |
| startTime / endTime | string | 同步起止时间 |
---
### 3.4 B4 — 实时点位值
获取设备所有点位的实时值。
- **Endpoint**: `GET /api/gateway/realtime/{adapter}/{deviceSourceId}`
- **适配器**: IHasPoints (MC4.0)
#### 路径参数
| 参数 | 说明 |
|------|------|
| adapter | AdapterCode，例如 "MC4:31ku" |
| deviceSourceId | 设备在第三方系统中的 ID |
#### 响应体
```json
{
"deviceSourceId": "1001",
"points": [
{
"pointIndex": 0,
"name": "温度",
"value": 26.5,
"unit": "℃",
"updateTime": "2026-05-16 15:30:00",
"isValid": true
},
{
"pointIndex": 1,
"name": "湿度",
"value": 55.0,
"unit": "%",
"updateTime": "2026-05-16 15:30:00",
"isValid": true
}
]
}
```
| 字段 | 类型 | 说明 |
|------|------|------|
| deviceSourceId | string | 设备ID |
| points[].pointIndex | int | 点位索引 |
| points[].name | string | 点位名称 |
| points[].value | double | 当前值 |
| points[].unit | string | 单位 |
| points[].updateTime | string | 数据更新时间 |
| points[].isValid | bool | 数据是否有效（false=传感器异常） |
---
### 3.5 B5 — 设备控制
反向控制设备（调空调温度、开关阀门等）。
- **Endpoint**: `POST /api/gateway/realtime/{adapter}/control`
- **适配器**: IHasPoints (MC4.0)
#### 路径参数 + 请求体
```json
// POST /api/gateway/realtime/MC4:31ku/control
{
"deviceSourceId": "1001",
"pointIndex": 2,
"value": 1
}
```
| 字段 | 类型 | 必填 | 说明 |
|------|------|:---:|------|
| deviceSourceId | string | ✅ | 第三方设备ID |
| pointIndex | int | ✅ | 点位索引 |
| value | double | ✅ | 设置值（开关: 0/1, 模拟量: 实际数值） |
#### 响应体
```json
{
"status": "sent"
}
```
> 注意: 响应仅表示指令已发送，不保证设备已执行。如需确认，应再次调 B4 查询实时值。
---
### 3.6 B6a — 实时取流
获取实时播放流地址。
- **Endpoint**: `GET /api/gateway/streams/{adapter}/{channelId}/live`
- **适配器**: IHasStreams (Owl)
#### 响应体
```json
{
"wsFlv": "ws://192.168.1.108/proxy/sms/rtp/gb_xxx.live.flv",
"httpFlv": "http://192.168.1.108/proxy/sms/rtp/gb_xxx.live.flv",
"hls": "http://192.168.1.108/proxy/sms/rtp/gb_xxx/hls.fmp4.m3u8",
"webrtc": "webrtc://192.168.1.108/proxy/sms/index/api/webrtc?app=rtp&stream=gb_xxx&type=play",
"rtmp": "rtmp://192.168.1.108:1935/rtp/gb_xxx",
"rtsp": "rtsp://192.168.1.108:554/rtp/gb_xxx"
}
```
| 协议 | 建议用途 | 延迟 |
|------|----------|:---:|
| wsFlv | Web 实时预览（首选） | <1s |
| httpFlv | 兼容旧浏览器 | 1-2s |
| hls | iOS Safari / 回放 | 3-5s |
| webrtc | 超低延迟场景 | <500ms |
> 注意: GB28181 首次拉流有 1-3 秒 SIP 信令延迟。建议前端播放器在 3 秒内无画面时自动重试一次。
---
### 3.7 B6b — 回放取流
获取历史录像 HLS 播放地址。
- **Endpoint**: `GET /api/gateway/streams/{adapter}/{channelId}/playback`
- **适配器**: IHasStreams (Owl)
#### 请求参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|:---:|------|
| start | string | ✅ | 开始时间 "yyyy-MM-dd HH:mm:ss" |
| end | string | ✅ | 结束时间 "yyyy-MM-dd HH:mm:ss" |
#### 响应体
```json
{
"hls": "http://192.168.1.108/recordings/channels/gb_xxx/index.m3u8?start_ms=1714982400000&end_ms=1714982700000&token=xxx"
}
```
> 回放使用 HLS (VOD) 格式，Owl 将指定时间范围内的 MP4 片段动态拼接为 m3u8 播放列表。
---
### 3.8 B7 — 云台控制
控制摄像机云台转动。
- **Endpoint**: `POST /api/gateway/streams/{adapter}/{channelId}/ptz`
- **适配器**: IHasStreams (Owl)
#### 请求体
```json
{
"direction": "left",
"speed": 0.5
}
```
| 字段 | 类型 | 必填 | 说明 |
|------|------|:---:|------|
| direction | string | ✅ | **仅支持**: `up` / `down` / `left` / `right` / `zoom_in` / `zoom_out` / `stop` |
| speed | float | | 速度 0.0~1.0，默认 0.5 |
> ⚠️ Owl 当前版本仅实现了方向移动 (`continuous`) 和停止 (`stop`)，**不支持**预设位操作 (`preset/set/goto/remove`) 和绝对/相对定位。ONVIF PTZ 未实现。
#### 响应体
```json
{
"status": "ok"
}
```
---
### 3.9 B8 — 告警查询
查询告警列表。
- **Endpoint**: `GET /api/gateway/alarms/{adapter}`
- **适配器**: IHasAlarms
#### 请求参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|:---:|------|
| from | string | ✅ | 开始时间 "yyyy-MM-dd HH:mm:ss" |
| to | string | ✅ | 结束时间 |
| page | int | | 页码，默认 1 |
| size | int | | 每页大小，默认 50 |
| confirmState | int | | MC4.0: 0=所有, 1=未确认, 2=已确认 |
| level | string | | 告警等级: 提示/普通/重要/紧急 |
#### 响应体
```json
{
"items": [
{
"alarmId": "2183fda3-9e32-48ae-b433-f807cc81a237",
"deviceId": "1001",
"adapterCode": "MC4:31ku",
"level": "重要",
"title": "温度超限",
"content": "[温湿度变送器][45℃]",
"occurTime": "2026-05-16 14:30:00",
"status": "未确认",
"thresholdValue": 40.0,
"actualValue": 45.0
}
],
"total": 120
}
```
---
### 3.10 B9 — 告警确认
确认告警，写回第三方系统。
- **Endpoint**: `POST /api/gateway/alarms/{adapter}/{alarmId}/confirm`
- **适配器**: IHasAlarms
#### 路径参数
| 参数 | 说明 |
|------|------|
| adapter | AdapterCode |
| alarmId | 源系统告警 ID |
#### 响应体
```json
{
"status": "confirmed"
}
```
> Vol.Pro 在收到成功响应后，同步更新本地 `iot_alarm.State='已确认'` 和 `ConfirmTime=当前时间`。
---
## 4. 错误码对照表
| HTTP Status | 含义 | 说明 |
|:----------:|------|------|
| 200 | 成功 | 正常响应 |
| 400 | 请求错误 | 参数缺失或格式错误 |
| 401 | 认证失败 | A 组接口 NodeCode 或 Token 不正确 |
| 404 | 未找到 | 适配器不存在或设备不存在 |
| 500 | 服务器错误 | 网关或 Vol.Pro 内部异常 |
| 502 | 第三方错误 | 网关调用 Owl/MC4.0 失败 |
---
## 5. 数据类型约定
| 类型 | JSON 示例 | 说明 |
|------|-----------|------|
| string | "hello" | 字符串 |
| int | 42 | 整数 |
| double | 26.5 | 浮点数 |
| bool | true / false | 布尔值 |
| object | { "key": "value" } | JSON 对象 |
| array | [ ... ] | JSON 数组 |
| datetime | "2026-05-16 15:30:00" | 日期时间字符串，格式 yyyy-MM-dd HH:mm:ss |
---
## 6. 对接检查清单
网关开发和 Vol.Pro 开发完成后，按以下清单逐项验证：
```
□ A1: 网关启动 → 注册成功 → 返回 nodeId + 设备列表
□ A2: 网关心跳 → Vol.Pro gateway_nodes.LastHeartbeat 更新
□ A3: 首次同步 → 设备入库，字段分治规则正确（管理员字段不覆盖）
□ A3: 二次同步 → 仅网关字段更新，DeviceName 不变
□ A3: parentSourceId → Vol.Pro 正确解析为 ParentDeviceId
□ A4: 告警上报 → iot_alarm 表有数据
□ B1: 健康检查 → 返回所有适配器状态
□ B2: 设备列表 → 分页 + 关键字搜索正常
□ B3: 手动同步 → 返回 added/updated/removed 统计
□ B4: 实时数据 → 返回点位值和更新时间
□ B5: 设备控制 → 指令发送成功，设备实际响应
□ B6a: 实时取流 → 返回 6 种协议地址，前端可播放
□ B6b: 回放取流 → 返回 HLS 地址，前端可播放历史录像
□ B7: 云台控制 → 方向键有效，stop 有效
□ B8: 告警查询 → 分页 + 筛选正常
□ B9: 告警确认 → 第三方确认成功 + Vol.Pro 本地 State 更新
```
---
> **文档结束**

9533
doc/对接文档/钥匙管理系统接口_提取.txt
View File

File diff suppressed because it is too large Load Diff

BIN
doc/对接文档/钥匙管理系统软件接口.docx
View File

Binary file not shown.

256
doc/整合方案/KMS钥匙柜整合方案_v1.0.md
View File

@@ -1,256 +0,0 @@
# 钥匙柜（KMS）整合方案 v1.0
> **版本**: 1.0
> **日期**: 2025-05-19
> **数据源**: doc/对接文档/钥匙管理系统软件接口.docx
> **架构**: IntegrationGateway 适配器模式 + Vol.Pro 管理端
---
## 1. 现状分析
### 1.1 KMS 系统概览
钥匙管理系统是一个独立的 REST API 服务，管理智能钥匙柜的硬件设备。
| 项目 | 说明 |
|------|------|
| 技术栈 | Java/Spring Boot (推测) |
| 认证方式 | clientId/clientSecret → Bearer Token (30分钟) |
| 数据模型 | 柜体(locker) → 锁孔(lockhole) → 钥匙(opener) |
| 用户体系 | 员工(staff) + 员工组(staff group) |
| 核心业务 | 借还记录、交接记录、远程授权、告警记录 |
### 1.2 KMS 第三方集成接口（第2.18节）
KMS 预留了 8 个专用于第三方对接的接口：
| 接口 | 路径 | 用途 |
|------|------|------|
| 心跳 | `/prod-api/kms/thirdparty/heartbeat` | 检测 KMS 存活 |
| 批量删除员工 | `/prod-api/kms/staff/batchDelete` | 同步删除 |
| 批量同步员工 | `/prod-api/kms/staff/batchSync` | 同步员工信息 |
| 查询柜体钥匙 | `/prod-api/kms/thirdparty/locker/keys` | 获取所有柜体及其钥匙列表 |
| 授权记录 | `/prod-api/kms/thirdparty/auth/records` | 查询远程授权历史 |
| 借还记录 | `/prod-api/kms/thirdparty/borrow/records` | 查询借还日志 |
| 告警记录 | `/prod-api/kms/thirdparty/alarm/records` | 查询告警列表 |
| 事件记录 | `/prod-api/kms/thirdparty/event/records` | 查询系统事件 |
认证方式：所有接口需要在 `Authorization: Bearer <token>` 头中携带 Token。
### 1.3 Vol.Pro 端现存钥匙相关模块
| 表/模块 | 说明 | 来源 |
|----------|------|------|
| `warehouse_keys` | 钥匙管理（自主） | Vol.Pro 代码生成 |
| `warehouse_keyapply` | 钥匙领用申请 | Vol.Pro 代码生成 |
| `warehouse_keylog` | 钥匙使用日志 | Vol.Pro 代码生成 |
这些是 Vol.Pro 自建的钥匙管理流程（申请→审批→记录），与硬件 KMS 系统平行运行。
---
## 2. 整合策略
### 2.1 核心决策
**KMS 作为一个独立的物联网子系统接入 IntegrationGateway**，与 Owl、MC4.0 平级。
通过适配器模式，KMS 的能力被抽象为统一的网关接口，Vol.Pro 管理端通过网关调用 KMS，无需直接对 KMS 编程。
### 2.2 KMS 能力评估
| 能力 | KMS 支持 | 统一接口 | 实现优先级 |
|------|:---:|------|:---:|
| 设备列表 | ✅ (钥匙柜+钥匙) | `IHasFlatDevices` | Phase 1 |
| 告警 | ✅ (告警记录) | `IHasAlarms` | Phase 1 |
| 实时状态 | ❌ | 无 | — |
| 远程控制 | ✅ (远程授权/开门) | `IAcceptsControl` (新增) | Phase 2 |
| 借还记录 | ✅ | 新增接口 | Phase 2 |
| 员工同步 | ✅ | 无 (单向推送) | Phase 2 |
### 2.3 设备模型映射
KMS 的物理拓扑是 **柜体 → 锁孔 → 钥匙**。映射到 `StandardDevice`：
```
KMS 柜体 (locker) → StandardDevice { DeviceGroup="门禁设备", DeviceCategory="智能钥匙柜", IsParent=true }
KMS 锁孔 (lockhole) → StandardDevice { DeviceGroup="门禁设备", DeviceCategory="钥匙位", IsParent=false, ParentSourceId=柜体SourceId }
(钥匙本身是一个逻辑实体,不映射为设备)
```
**示例**：
```
KMS "10位智能公共钥匙柜" (lockerId=25)
├── 钥孔1 "仓库大门钥匙" (lockholeSort=1)
├── 钥孔2 "机房钥匙" (lockholeSort=2)
├── ...
└── 钥孔10 "配电室钥匙" (lockholeSort=10)
```
每个锁孔又是一个 `StandardDevice`，其 `Extra` 字段承载钥匙状态（在位/离位/借出）。
---
## 3. 网关改造
### 3.1 新增 `IntegrationGateway.Adapters.Kms`
```
gateway/src/IntegrationGateway.Adapters.Kms/
├── KmsAdapter.cs # IHasFlatDevices + IHasAlarms
└── KmsAuthHelper.cs # clientId/clientSecret → Bearer Token
```
### 3.2 KmsAuthHelper
```csharp
/// 认证流程: POST /prod-api/kms/token?clientId=xxx&clientSecret=yyy → { code, token }
/// Token 有效期 30 分钟, 过期前 5 分钟自动刷新
public class KmsAuthHelper
{
public async Task<string> GetTokenAsync() { ... }
public async Task<HttpClient> GetAuthenticatedClientAsync() { ... }
}
```
### 3.3 KmsAdapter 能力接口
```csharp
public class KmsAdapter : IHasFlatDevices, IHasAlarms
{
public string AdapterCode { get; } // "KMS:main"
public AdapterCapabilities Capabilities => new()
{
HasFlatDevices = true, HasAlarms = true
};
// IHasFlatDevices: 查询柜体钥匙信息 → List<StandardDevice>
public async Task<PagedResult<StandardDevice>> GetDevicesAsync(int page, int size, string? keyword)
{
// 调 2.18.4 GET /prod-api/kms/thirdparty/locker/keys
// 展开为: 每个柜体 → 1个父设备, 每个锁孔 → 1个子设备
}
// IHasAlarms: 查询告警记录
public async Task<PagedResult<StandardAlarm>> GetAlarmsAsync(...)
{
// 调 2.18.7 GET /prod-api/kms/thirdparty/alarm/records
// KMS 告警类型: 1=当前告警, 2=历史告警
}
public async Task ConfirmAlarmAsync(string alarmId) { ... }
public async Task EndAlarmAsync(string alarmId) { ... }
}
```
### 3.4 配置新增
```json
// appsettings.json
{
"KMS": {
"InstanceName": "main",
"BaseUrl": "http://192.168.1.50:8080",
"ClientId": "your_client_id",
"ClientSecret": "your_client_secret"
}
}
```
### 3.5 Program.cs 注册
```csharp
var kmsList = app.Configuration.GetSection("KMS").Get<List<KmsConfig>>() ?? new();
foreach (var k in kmsList)
registry.Register(new KmsAdapter($"KMS:{k.InstanceName ?? "default"}", http, k.BaseUrl, k.ClientId, k.ClientSecret));
```
---
## 4. Vol.Pro 管理端改动
### 4.1 数据流向
```
KMS 硬件柜 IntegrationGateway Vol.Pro
─────── ────────────── ──────
钥匙在位/离位 ────→ KmsAdapter.GetDevices ────→ base_device 表
(AdapterCode="KMS:main")
(DeviceCategory="钥匙位")
告警事件 ────→ KmsAdapter.GetAlarms ────→ iot_alarm 表
远程授权开门 ←──── B-interface (Phase2) ←──── 管理端操作
```
### 4.2 不需要改的内容
- `warehouse_keys` / `warehouse_keyapply` / `warehouse_keylog` — 保留现有体系，不与 KMS 冲突
- `base_device` 表 — 已支持 `DeviceCategory="钥匙位"`、`DeviceGroup="门禁设备"`
- 前端操作列 — 已预留 `AccessDeviceActions` / `AlarmDeviceActions` 骨架
- 管理端设备列表 — 自动显示 KMS 同步的设备
### 4.3 需要新增的内容
| 项 | 说明 |
|------|------|
| KMS 数据字典项 | `设备种类` 字典增加 "智能钥匙柜"、"钥匙位" |
| 前端 KMS 操作按钮 | `KeyDeviceActions.vue` — 显示钥匙状态 + 远程授权入口 (Phase 2) |
---
## 5. 数据映射表
### 5.1 KMS 柜体 → StandardDevice
| KMS 字段 | StandardDevice 字段 |
|------|------|
| lockerId | SourceId |
| lockerName | Name |
| "智能钥匙柜" | Category |
| "门禁设备" | Group |
| true | IsParent |
| lockerCode | Extra.lockerCode |
| online (健康检查) | IsOnline |
### 5.2 KMS 锁孔 → StandardDevice
| KMS 字段 | StandardDevice 字段 |
|------|------|
| lockerId.lockholeSort | SourceId (组合) |
| openerName (钥匙名) | Name |
| "钥匙位" | Category |
| "门禁设备" | Group |
| false | IsParent |
| lockerId | ParentSourceId |
| openerState (在位/离位) | Extra.openerState |
| openerType (永久授权/一次性授权/应急授权) | Extra.openerType |
### 5.3 KMS 告警 → StandardAlarm
| KMS 字段 | StandardAlarm 字段 |
|------|------|
| uuid | AlarmId (SourceAlarmId) |
| warningTime | OccurTime |
| alarmType 映射 | Level (提示/普通/重要) |
| lockerName + openerName | Title |
| remark | Content |
---
## 6. 实施计划
| 阶段 | 内容 | 预计工时 |
|------|------|:---:|
| K1 | 创建 `IntegrationGateway.Adapters.Kms` 项目骨架 | 0.5h |
| K2 | 实现 `KmsAuthHelper` (clientId/secret → Token) | 1h |
| K3 | 实现 `KmsAdapter` — `IHasFlatDevices` (设备同步) | 2h |
| K4 | 实现 `KmsAdapter` — `IHasAlarms` (告警同步) | 1h |
| K5 | 网关配置 + Program.cs 注册 | 0.5h |
| K6 | 字典补充（智能钥匙柜/钥匙位） | 0.5h |
| K7 | 联调验证 (需 KMS 环境) | 2h |
| K8 | Phase 2: 远程授权/开门 + 前端按钮 | 3h |
---
> **风险**: KMS 的实际 API 路径和响应格式需在真实环境验证，文档中的路径格式可能与实际部署有差异（如 `/prod-api/kms/` 前缀可能变化）。

256
doc/整合方案/KMS钥匙柜整合方案_v2.0.md
View File

@@ -1,256 +0,0 @@
# 钥匙柜（KMS）整合方案 v2.0
> **版本**: 2.0
> **日期**: 2025-05-19
> **数据源**: `doc/对接文档/钥匙管理系统软件接口.docx`（KMS API v1.0.4）
> **技术栈**: 全链路 .NET 8 / C#（网关 ASP.NET Core + Vol.Pro ASP.NET Core）
> **架构**: IntegrationGateway 适配器模式，KMS 作为第三个子系统适配器加入
---
## 1. KMS 系统全接口分析
### 1.1 认证体系
| 项目 | 说明 |
|------|------|
| 认证接口 | `POST /prod-api/getToken` |
| 参数 | `clientId` + `clientSecret`（由 KMS 管理员分配） |
| 返回 | `{ code: 200, token: "xxx" }` |
| 有效期 | 30 分钟，过期重新获取 |
| 使用方式 | 后续请求 Header: `Authorization: Bearer <token>` |
### 1.2 第三方专用接口（第 2.18 节 —— 整合核心）
KMS 预留了 8 个专供第三方对接的接口，这些是网关适配器必须实现的：
| # | 方法 | 路径 | 用途 | 对应能力接口 |
|---|:---:|------|------|------|
| 2.18.1 | `POST` | `/prod-api/heartBeat` | 心跳检测 | `IGatewayAdapter.HealthCheck` |
| 2.18.2 | `POST` | `/prod-api/batchDeleteStaff` | 批量删除员工 | Phase 2 |
| 2.18.3 | `POST` | `/prod-api/batchSyncStaff` | 批量同步员工信息 | Phase 2 |
| 2.18.4 | `POST` | `/prod-api/getOpenerList` | 查询所有柜体及钥匙列表 | `IHasFlatDevices` |
| 2.18.5 | `POST` | `/prod-api/getPermissionList` | 查询远程授权记录 | Phase 2 |
| 2.18.6 | `POST` | `/prod-api/getRecordList` | 查询借还记录 | Phase 2 |
| 2.18.7 | `POST` | `/prod-api/getWarningList` | 查询告警记录 | `IHasAlarms` |
| 2.18.8 | `POST` | `/thirdPlatlogin` | 第三方登录/事件记录 | Phase 2 |
> 注意：第 2.18.X 节接口的路径不同于标准 KMS 业务接口（不以 `/prod-api/kms/` 开头）。这是 KMS 为第三方特意设计的**扁平化集成 API**。
### 1.3 标准 KMS 业务接口（第 2.3-2.17 节 —— 辅助参考）
以下是 KMS 完整的标准 REST API，供深入对接时使用：
| 模块 | 接口 | 方法 | 说明 |
|------|------|:---:|------|
| **认证** | `/prod-api/getToken` | POST | 获取 Bearer Token |
| **部门** | `/prod-api/system/dept/root/{userId}` | GET | 获取部门树 |
| **交接记录** | `/prod-api/kms/handover/handoverInfolist` | GET | 查询交接记录明细 |
| | `/prod-api/kms/handover/list` | GET | 查询交接记录列表（分页） |
| **授权** | `/prod-api/kms/permission/list` | GET | 查询授权列表 |
| | `/prod-api/kms/permission/listPer` | GET | 查询授权人列表 |
| | `/prod-api/kms/permission/remote` | POST | 远程授权 |
| **告警** | `/prod-api/kms/warning/list` | GET | 查询告警列表（标准版） |
| **员工可借** | `/prod-api/kms/staffopener/available` | POST | 设置员工可借/永久授权钥匙 |
| | `/prod-api/kms/staffopener/listall` | GET | 查询员工可借/永久授权钥匙列表 |
| **员工管理** | `/prod-api/kms/staff` | POST | 创建员工 |
| | `/prod-api/kms/staff` | PUT | 修改员工信息 |
| | `/prod-api/kms/staff/list` | GET | 分页查询员工列表 |
| | `/prod-api/kms/staff/{id}` | DELETE | 删除员工 |
| | `/prod-api/kms/staff/{id}` | GET | 获取员工详细信息 |
| **员工组** | `/prod-api/kms/staffGroup/...` | CRUD | 员工组管理（6个接口） |
| **物品类别** | `/prod-api/kms/openerType/...` | CRUD | 物品类别管理（6个接口） |
| **柜体管理** | `/prod-api/kms/locker` | POST/PUT | 创建/修改柜体 |
| | `/prod-api/kms/locker/list` | GET | 分页查询柜体列表 |
| | `/prod-api/kms/locker/{id}` | DELETE/GET | 删除/获取柜体详细信息 |
| | `/prod-api/kms/locker/statistics` | GET | 首页统计图表数据 |
| **锁孔管理** | `/prod-api/kms/lockhole` | PUT | 修改锁孔 |
| | `/prod-api/kms/lockhole/list` | GET | 分页查询锁孔列表 |
| | `/prod-api/kms/lockhole/{id}` | DELETE/GET | 删除/获取锁孔详细信息 |
| **钥匙管理** | `/prod-api/kms/opener` | POST/PUT | 创建/修改钥匙 |
| | `/prod-api/kms/opener/list` | GET | 分页查询钥匙列表 |
| | `/prod-api/kms/opener/selectCanBorrow` | GET | 查询可借钥匙列表 |
| | `/prod-api/kms/opener/staff` | GET | 查询可借钥匙员工列表 |
| | `/prod-api/kms/opener/{id}` | DELETE/GET | 删除/获取钥匙详细信息 |
| **钥匙组** | `/prod-api/kms/openerGroup/...` | CRUD | 钥匙组管理（7个接口） |
> 共约 **50+ 个 REST 端点**，覆盖 KMS 完整业务。
---
## 2. 整合策略
### 核心原则
1. **KMS 作为独立子系统**，通过 IntegrationGateway 的 `KmsAdapter` 接入
2. **Phase 1** 实现第三方接口（8 个端点），这是 KMS 专门为集成设计的
3. **Phase 2** 按需扩展标准业务接口（远程授权/开门/借还记录查询）
4. Vol.Pro 管理端通过网关 B 组接口间接调用 KMS，不直接对 KMS 编程
### 适配器能力矩阵
| 能力接口 | 实现 | 映射的 KMS 第三方接口 |
|----------|:---:|------|
| `IGatewayAdapter` | ✅ | 2.18.1 心跳 |
| `IHasFlatDevices` | ✅ | 2.18.4 柜体钥匙列表 → StandardDevice |
| `IHasAlarms` | ✅ | 2.18.7 告警列表 → StandardAlarm |
| 远程控制 (新接口) | ⏭️ | 2.18.5 远程授权 + KMS 标准接口 remote |
---
## 3. 设备树映射
KMS 物理拓扑：**柜体(Locker) → 锁孔(Lockhole) → 钥匙(Opener)**
映射到 `base_device` 表：
```
KMS 管理平台 (一个 IP:PORT = 一个 gateway_node)
├── 智能钥匙柜A (lockerId=25)
│ ├── 锁孔1 "仓库大门" (lockholeSort=1 → StandardDevice, Category="钥匙位")
│ ├── 锁孔2 "机房钥匙" (lockholeSort=2)
│ └── 锁孔N ...
├── 智能钥匙柜B (lockerId=26)
│ ├── 锁孔1 "配电室"
│ └── 锁孔M ...
```
| KMS 实体 | base_device 字段 | 值 |
|----------|------|------|
| 柜体 | `SourceId` | `locker_{lockerId}` |
| | `Name` | lockerName (如 "10位智能公共钥匙柜") |
| | `DeviceCategory` | "智能钥匙柜" |
| | `DeviceGroup` | "门禁设备" |
| | `IsParent` | "是" |
| | `Extra` | `{ lockerCode, lockholeCount }` |
| 锁孔子设备 | `SourceId` | `lockhole_{lockerId}_{lockholeSort}` |
| | `Name` | openerName (如 "仓库大门钥匙") |
| | `DeviceCategory` | "钥匙位" |
| | `DeviceGroup` | "门禁设备" |
| | `IsParent` | "否" |
| | `ParentSourceId` | `locker_{lockerId}` (解析为 ParentDeviceId) |
| | `Extra` | `{ openerState, openerType, openerId }` |
| | `IsOnline` | openerState="在位" → 在线; "离位" → 离线 |
---
## 4. 告警映射
| KMS 告警字段(2.18.7) | StandardAlarm 字段 | 说明 |
|------|------|------|
| uuid | SourceAlarmId | KMS 告警唯一ID |
| warningTime | OccurTime | 告警时间 |
| type (1=当前告警,2=历史告警) | Status | type=1→"未确认", type=2→"已结束" |
| lockerName + lockholeSort | Title | 如 "10位公共钥匙柜 锁孔3" |
| openerName | 关联设备 | 通过 openerId 查找对应设备 |
| remark | Content | 告警备注详情 |
---
## 5. 网关改造清单
### 5.1 新增项目
```
gateway/src/IntegrationGateway.Adapters.Kms/
├── IntegrationGateway.Adapters.Kms.csproj
├── KmsAdapter.cs # IHasFlatDevices + IHasAlarms
├── KmsAuthHelper.cs # clientId/clientSecret → Bearer Token
└── KmsModels.cs # KMS 响应 DTO
```
### 5.2 KmsAuthHelper
```csharp
/// .NET 8 ASP.NET Core 适配: KMS Bearer Token 认证
public class KmsAuthHelper
{
private readonly HttpClient _http;
private readonly string _baseUrl, _clientId, _clientSecret;
private string? _token;
private DateTime _expiry = DateTime.MinValue; // 30min TTL
public async Task<string> GetTokenAsync() { ... }
public async Task<HttpClient> GetAuthenticatedClientAsync() { ... }
}
```
### 5.3 KmsAdapter
```csharp
public class KmsAdapter : IHasFlatDevices, IHasAlarms
{
public string AdapterCode { get; } // "KMS:main"
public AdapterCapabilities Capabilities => new() {
HasFlatDevices = true, HasAlarms = true
};
// IHasFlatDevices → 2.18.4 POST /prod-api/getOpenerList
public async Task<PagedResult<StandardDevice>> GetDevicesAsync(int page, int size, string? keyword);
// IHasAlarms → 2.18.7 POST /prod-api/getWarningList
public async Task<PagedResult<StandardAlarm>> GetAlarmsAsync(int page, int size, DateTime from, DateTime to, string? level, string? state);
public async Task ConfirmAlarmAsync(string alarmId);
public async Task EndAlarmAsync(string alarmId);
// IGatewayAdapter
public async Task<bool> HealthCheckAsync(); // → 2.18.1 POST /prod-api/heartBeat
}
```
### 5.4 配置文件
```json
// appsettings.json 新增 KMS 段
{
"KMS": {
"InstanceName": "main",
"BaseUrl": "http://192.168.1.50:8080",
"ClientId": "your_client_id",
"ClientSecret": "your_client_secret"
}
}
```
### 5.5 Program.cs 注册
```csharp
var kmsList = app.Configuration.GetSection("KMS").Get<List<KmsConfig>>() ?? new();
foreach (var k in kmsList)
registry.Register(new KmsAdapter($"KMS:{k.InstanceName ?? "default"}",
httpClient, k.BaseUrl, k.ClientId, k.ClientSecret));
```
---
## 6. Vol.Pro 端改动
| 项 | 改动 | 说明 |
|------|:---:|------|
| 数据库 | 无 | base_device/iot_alarm 已兼容 |
| 后端代码 | 无 | A1-A4 同步逻辑通用 |
| 字典 | 新增 2 项 | "智能钥匙柜" / "钥匙位" 加入设备种类字典 |
| 前端页面 | 无 | 设备列表自动显示 KMS 同步的设备 |
| 前端操作按钮 | Phase 2 | `KeyDeviceActions.vue` — 显示钥匙状态 + 远程授权入口 |
---
## 7. 实施计划
| 阶段 | 内容 | 涉及文件 | 预计 |
|------|------|------|:---:|
| K0 | 创建 `Adapters.Kms` 项目 + 引用 Core | csproj + sln | 10min |
| K1 | `KmsModels.cs` — 所有 KMS 响应 DTO | 1 文件 | 30min |
| K2 | `KmsAuthHelper.cs` — Token 获取 + 刷新 | 1 文件 | 30min |
| K3 | `KmsAdapter.HealthCheck` + `GetDevicesAsync` | 1 文件 | 1h |
| K4 | `KmsAdapter.GetAlarmsAsync` + Confirm/End | 1 文件 | 1h |
| K5 | appsettings.json + Program.cs 注册 | 2 文件 | 15min |
| K6 | 字典补充 + 编译验证 | 管理端 | 15min |
| K7 | 联调验证 (需 KMS 环境) | — | 2h |
| K8 | Phase 2: 远程授权 + 前端按钮 | 3 文件 | 3h |
---
> **版本历史**:
> - v1.0 (2025-05-17) — 初版，未完整覆盖所有接口
> - v2.0 (2025-05-19) — 完整覆盖 50+ REST 接口，明确 Phase 1/2 分界，修正技术栈为 .NET 8

290
doc/整合方案/SecMPS_整合方案_v2.0_最终评估报告.md Normal file
View File

@@ -0,0 +1,290 @@
# SecMPS 整合方案 — 最终评估报告
> **评估日期**: 2026-05-16
> **评估对象**: SecMPS_最终整合方案_v2.0.md
> **参考依据**: Owl API 文档 / Owl GitHub / ZLMediaKit 官方文档 / ZLMediaKit GitHub / 数据字典设计
---
## 一、评估方法
以资深架构师经验，对整合方案进行三个维度的交叉验证：
1. **方案自洽性**：章节间逻辑是否一致，API 定义 ↔ 数据模型 ↔ 同步策略是否闭环
2. **对 Owl+ZLMediaKit 的准确性**：方案定义的接口和流程是否与 Owl v1.3.0 / ZLMediaKit master 实际行为匹配
3. **工程可落地性**：是否所有细节都有明确定义，是否存在"开发时再说"的模糊地带
共发现 **14 个问题**，按严重程度分为 P0（阻塞实施）、P1（影响质量）、P2（优化项）。
---
## 二、P0 — 必须修复（4 项）
### P0-1：第四章示例代码与 A3 接口规范矛盾
**问题描述**：
§四示例代码（第 263-265 行）在每次同步时写入 `DeviceName = d.Name` 和 `DeviceCategory = d.Category`。但 A3 接口规范明确说"网关不碰管理员字段，首次入库写全量，后续仅更新网关负责的列"。这导致管理员手动改过的设备名称每次同步后被网关覆盖。
**影响**：管理员的设备重命名操作会被同步覆盖，用户投诉
**解决方案**：
```csharp
// 区分首次入库与增量更新
if (entity.DeviceId == 0) // 首次入库
{
entity.DeviceName = d.Name;
entity.DeviceCategory = d.Category;
entity.DeviceGroup = d.Group;
}
// 增量更新：只写网关负责的字段
entity.IsOnline = d.IsOnline ? "在线" : "离线";
entity.IsParent = d.IsParent ? "是" : "否";
entity.ExtraData = d.ExtraDataJson;
entity.LastSyncTime = DateTime.UtcNow;
```
---
### P0-2：A3 设备同步中 `parentSourceId` → `ParentDeviceId` 解析链路缺失
**问题描述**：
A3 请求中设备携带 `parentSourceId: "1001"`（第三方 ID），但 Vol.Pro 需要 `ParentDeviceId`（本地主键）。从第三方 ID 到本地主键的映射逻辑完全未定义。
**影响**：子设备无法挂到父设备下，设备树断裂
**解决方案**：
同步前先做映射表查询：
```csharp
// 批量取出当前网关所有设备
var allIds = await _db.base_device
.Where(x => x.GatewayNodeId == nodeId)
.ToDictionaryAsync(x => (x.AdapterCode, x.SourceId), x => x.DeviceId);
// 解析 parentSourceId
int? parentDeviceId = null;
if (!string.IsNullOrEmpty(d.ParentSourceId))
allIds.TryGetValue((d.AdapterCode, d.ParentSourceId), out var pid);
parentDeviceId = pid > 0 ? pid : null;
entity.ParentDeviceId = parentDeviceId;
```
补充到 §四 代码示例中。
---
### P0-3：网关重启注册时 NodeId 分配逻辑未定义
**问题描述**：
网关重启再次调用 A1 `/register`，`gateway_nodes` 表中 `NodeCode` 已存在。当前文档只说注册流程，没有说明是覆盖还是报错。如果新建 NodeId，则 `base_device.GatewayNodeId` 指向旧 ID 断裂。
**影响**：网关重启后设备归属丢失
**解决方案**：
A1 接口改为 Upsert 逻辑：
```
POST /register →
NodeCode 匹配 → 更新 AdapterTypes/BaseUrl/IsOnline=在线 → 返回已有 NodeId
NodeCode 不匹配 → 插入新记录 → 返回新 NodeId → 401（防止未授权节点）
```
补充到 §2.1 流程描述和 A1 API 规范中。
---
### P0-4：Owl 管理端口错误
**问题描述**：
Owl README 和 Docker Compose 明确 Owl Web 管理端口 = `15123`。方案 `appsettings.json` 和 §七部署拓扑均写 `owl_host:80`。
**影响**：网关无法连接 Owl，所有视频功能不可用
**解决方案**：
- `appsettings.json` 中 Owl BaseUrl → `http://owl_host:15123`
- §七部署拓扑中 Owl 端口标记为 `:15123`
- 注意：ZLM 自身 HTTP 端口是 `8000`，但由 Owl 内部调用，网关不接触
---
## 三、P1 — 影响实施质量（6 项）
### P1-1：PTZ 接口仅实现 continuous + stop
**问题描述**：
owl_api_research.md §6.1 和 Owl GitHub 确认：Owl 代码中仅实现了 `continuous`（持续移动）和 `stop`（停止），`preset`（预置位）、`absolute`（绝对定位）、`relative`（相对定位）均返回错误。ONVIF PTZ 标记为 TODO。
方案 §2.3 适配器矩阵和 B7 API 没有注明此限制。
**影响**：开发前端云台面板时做了预置位下拉等功能，部署后不可用
**解决方案**：
- B7 接口标注："仅支持 continuous (方向移动) + stop (停止)"
- 前端云台面板：仅显示方向键（↑↓←→）+ 停止按钮，不显示预置位
- OwlAdapter.PtzControlAsync 实现：ONVIF 设备直接返回错误
---
### P1-2：视频通道在 base_device 和 video_channel 中的双重身份不清
**问题描述**：
§6 Owl 同步说 "Upsert base_device(ParentDeviceId=NVR) + video_channel"，但 §3.6 层级示例中摄像机是叶子节点没有子设备。一个 Owl 通道到底是 base_device 的子记录还是 video_channel 的独立记录？还是两者都是？
**影响**：开发者不清楚通道数据写入哪张表的哪个字段
**解决方案**：
明确：一个 Owl 通道 = 2 条记录：
1. `base_device` 子记录（DeviceName="通道01", DeviceCategory=摄像机, ParentDeviceId=NVR的DeviceId, ExtraData=null）
2. `video_channel` 扩展记录（DeviceId=通道的DeviceId, OwlStreamApp, OwlStreamName, HasPtz, SnapshotUrl）
在 §3.6 层级示例中增加通道示例：
```
NVR (IsParent=是)
├── 通道01 (base_device子记录, video_channel.OwlStreamApp="rtp")
├── 通道02 (base_device子记录, video_channel.OwlStreamApp="rtp")
```
---
### P1-3：回放取流与实时取流走不同的 Owl 端点
**问题描述**：
- 实时播放：`POST /channels/:id/play`
- 回放播放：`GET /recordings/channels/:cid/index.m3u8?start_ms=&end_ms=&token=`
两者是 Owl 的不同端点，方案 B6 只有一个 `/live` 路径。
**影响**：回放功能无法对接 Owl
**解决方案**：
B6 拆分为两个端点：
```
GET /streams/{adapter}/{channelId}/live → Owl POST /channels/:id/play
GET /streams/{adapter}/{channelId}/playback?start=&end= → Owl GET /recordings/channels/:cid/index.m3u8
```
IHasStreams 接口不变（已有 GetLiveUrlAsync 和 GetPlaybackUrlAsync），只修正 B 组 API 路径。
---
### P1-4：告警确认后 Vol.Pro 本地状态更新不闭环
**问题描述**：
B9 调网关确认告警写回第三方成功，但 `iot_alarm.State` 谁来更新？当前文档没有说明这个回写链路。
**影响**：管理端显示告警仍为"未确认"，需等下次 A4 同步才刷新
**解决方案**：
B9 确认成功后，Vol.Pro 侧同步更新本地：
```
POST /alarms/{adapter}/{alarmId}/confirm 成功 →
Vol.Pro 更新 iot_alarm SET State='已确认', ConfirmTime=NOW()
```
不需要网关二次推送。在 B9 接口规范中补充此说明。
---
### P1-5：video_record 同步策略缺失
**问题描述**：
§六同步策略有设备同步、告警同步、反向控制，但没有录像记录的同步时机和频率。
**影响**：录像数据永远不会写入 video_record 表
**解决方案**：
补充 §六：Owl 录像数据同步策略 ——
- **方式一**（推荐）：管理端点击"查看回放"时，网关实时调 Owl `GET /recordings` → 返回给管理端 → 同时写入 video_record 表
- **方式二**（备选）：网关定时（每 10 分钟）调 Owl `GET /recordings` → 走 A3 扩展同步 → 写入 video_record
建议先用方式一，方式二在 Phase 3 优化时引入。
---
### P1-6：AdapterCode 双段格式无约束
**问题描述**：
`"mc4:31号库房"` 中分隔符 `:` 和实例名字符集没有规范。如果实例名包含 `:` 会导致解析歧义。
**影响**：网关配置或同步时数据损坏
**解决方案**：
定义格式规范（补充到 §2.2）：
```
AdapterCode = "{AdapterType}:{InstanceName}"
AdapterType: 字母数字，对应网关注册的 Adapter 类名（如 MC4、Owl）
InstanceName: 字母数字下划线，对应具体网关实例（如 31ku）
分隔符: ':'
示例: "MC4:31ku"、"Owl:main"、"HikvisionISC:center"
```
---
## 四、P2 — 优化项（4 项）
### P2-1：子设备离线状态级联规则（明确即可）
**问题描述**：
§2.1 说网关离线 → 设备离线，但网关在线时父设备（采集器）离线，子设备是否级联标记离线？
**解决方案**：
网关在 A3 同步时如实上报每个子设备的 isOnline（MC4.0 树中已有此信息），Vol.Pro 不做推断，信任网关数据。在 §六同步策略中补充此行说明即可。
---
### P2-2：数据字典初始化运维指引（补充附录）
**问题描述**：
方案依赖 7 个数据字典（DeviceCategory 18 值、DeviceGroup 5 值、IsParent/IsOnline/Enable/IsControlPoint/AlarmLevel/State），但没有初始化指引。
**解决方案**：
在文档末尾增加「附录 A：字典初始化清单」，列出每个字典的 Code/Name/Value 对照表，运维人员在 Vol.Pro 管理端按表创建。
---
### P2-3：video_channel 流地址字段用途说明（补充注释）
**问题描述**：
video_channel 有 `OwlStreamApp/OwlStreamName/SnapshotUrl`，B6 取流实时调网关获取。这些字段的实际用途没说。
**解决方案**：
注明为缓存——首次取流后写入 video_channel，下次先查缓存，缓存过期（或 Owl 重启后）再调 B6 实时获取。在 video_channel 表注释中补充说明。
---
### P2-4：Owl AI 事件可接入告警（建议纳入 Phase 1 可选范围）
**问题描述**：
Owl 有 YOLO 本地检测 + `GET /events` 接口，AI 事件可走 A4 告警同步。
**解决方案**：
在 OwlAdapter 中可选实现 IHasAlarms，将 `GET /events` 的 AI 检测事件映射为 StandardAlarm（AlarmLevel=提示或普通）。在 §六同步策略中补充可选说明，建议 Phase 1 范围中列入。
---
## 五、架构正确性确认
以下方面经过 Owl+ZLMediaKit 双文档验证，确认正确：
| 验证项 | 状态 |
|--------|:--:|
| 三层架构（前端→网关→Owl）不直接接触 ZLM | ✅ |
| Owl 代理播放地址 `/proxy/sms/...` | ✅ |
| Owl RTP 收流→ZLM 转协议→多格式输出的链路 | ✅ |
| Owl Webhook 自动配置 ZLM（启动时 SetServerConfig） | ✅ |
| JWT Token 管理 + RSA 加密登录 | ✅ |
| 设备/通道 CRUD 对应 Owl API | ✅ |
| 取流端点返回 WS-FLV/HTTP-FLV/HLS/WebRTC/RTMP/RTSP | ✅ |
| Owl↔ZLM 联动（OpenRtpServer/CloseRtpServer/AddStreamProxy 等） | ✅ |
| 按需拉流 + 30s 无人观看自动关闭（ZLM on_stream_none_reader → Owl 通知 ZLM 关流） | ✅ |
| 云录像由 Owl 管理（ZLM MP4 录制→Owl on_record_mp4 hook→入库） | ✅ |
| GB28181 设备注册与心跳是 SIP 层自动完成（Vol.Pro 只查 HTTP API） | ✅ |
| 播放地址通过 Owl `/proxy/sms/` 反向代理到 ZLM（前端不直接访问 ZLM） | ✅ |
---
## 六、总结
| 优先级 | 数量 | 类型 |
|:---:|:--:|------|
| P0 | 4 | 阻塞性缺陷（代码矛盾、链路缺失、端口错误、注册逻辑缺失） |
| P1 | 6 | 实施质量影响（PTZ限制、通道身份、回放端点、告警闭环、录像缺失、格式规范） |
| P2 | 4 | 优化项（级联规则、字典指引、缓存说明、AI事件） |
| ✅ | 12 | 已验证正确 |
**总体评价**：方案架构方向完全正确，Owl+ZLMediaKit 对接路径准确。14 个问题中 P0/P1 共 10 项，全部为配置级或接口路径级微调，不涉及架构推翻。修复后可直接作为实施基准。
---
> 本报告应作为 SecMPS_最终整合方案_v2.0.md 的修正依据。建议将 P0/P1 问题修复合入方案文档后再开始 Phase 1。

321
doc/整合方案/SecMPS_整合方案_v3.0_最终评估报告.md Normal file
View File

@@ -0,0 +1,321 @@
# SecMPS 整合方案 v3.0 — 最终技术评估报告
> **评估日期**: 2026-05-16
> **评估对象**: SecMPS_最终整合方案_v3.0.md
> **参考标准**: Owl v1.3.0 API / ZLMediaKit master / MC4.0 API / Vol.Pro 框架文档
> **评估方法**: 逐章节对标六大技术文档，8 维度交叉验证
---
## 一、评估维度与结论总览
| 维度 | 得分 | 状态 |
|------|:---:|:---:|
| 架构合理性 | ★★★★★ | ✅ 通过 |
| 与 Owl+ZLM 兼容性 | ★★★★★ | ✅ 通过（v2→v3 已修正端口和端点） |
| 与 MC4.0 兼容性 | ★★★★★ | ✅ 通过（对象树+点位+告警全链路对齐） |
| 与 Vol.Pro 框架兼容性 | ★★★★☆ | ✅ 通过（2 处注意事项） |
| 数据完整性 | ★★★★★ | ✅ 通过（字段分治+映射表+双向 sync 闭环） |
| 安全性 | ★★★★☆ | ✅ 通过（1 处建议增强） |
| 可扩展性 | ★★★★★ | ✅ 通过（新增适配器零后端改动） |
| 运维可行性 | ★★★★☆ | ✅ 通过（2 处补充建议） |
**结论：方案切实可行，可以进入实施阶段。**
---
## 二、逐章节详细评估
### §一 总体架构 【通过】
| 评估项 | 结论 |
|--------|------|
| 三层架构（前端→Vol.Pro→网关→第三方） | 正确。每层职责单一 |
| 网关多实例部署 | 正确。NodeCode 唯一标识，互为独立 |
| AdapterCode 双段标识 `MC4:31ku` | 正确。格式规范已定义 |
| Owl 端口 15123 | 正确。与 Owl Docker Compose 一致 |
| ZLM 不直接暴露 | 正确。Owl 管理 ZLM 的 Webhook+REST API |
**验证依据**:
- Owl README: "Access http://localhost:15123 in your browser"
- ZLM 官方文档: REST API 由 Owl 内部调用，不对外暴露
- owl_api_research.md §8: Owl 通过 `SetServerConfig` 自动配置 ZLM Webhook
---
### §二 网关架构 【通过，1 处建议】
#### 2.1 注册与心跳流程
| 评估项 | 结论 |
|--------|------|
| A1 注册 Upsert 逻辑 | 正确。NodeCode 匹配即更新，不复用旧 NodeId |
| 心跳 15s + 超时 30s | 正确。与 Owl SIP 心跳（3s×3=9s 判离线）和 MC4.0 采集周期独立 |
| 级联设备离线 | 正确。Vol.Pro Job 只标记设备离线，不触发同步 |
**建议**: 增加"网关主动下线"接口 `POST /api/gateway/unregister`，网关正常关闭前调用以立即级联设备离线，避免等 30s 超时。
#### 2.2 网关配置
正确。3 个配置项（VolProBaseUrl/NodeCode/NodeToken）足够，AdapterTypes 由网关启动时扫描注册的 Adapter 类自动获取。
#### 2.3 适配器能力矩阵
**与 MC4.0 API 实际行为对照**:
| 方案接口 | MC4.0 对应端点 | 验证结果 |
|----------|---------------|:---:|
| IHasOwnDeviceTree.GetObjectTreeAsync | POST /api/central/object/tree | ✅ |
| IHasPoints.GetRealtimeValuesAsync | POST /api/central/device/point/value/get | ✅ |
| IHasPoints.GetMultiPointValuesAsync | POST /api/central/point/multi/value/get | ✅ |
| IHasPoints.SetPointValueAsync | POST /api/central/point/value/set | ✅ |
| IHasAlarms.GetAlarmsAsync | POST /api/central/alarm/query | ⚠️ 见 P1 |
| IHasAlarms.ConfirmAlarmAsync | POST /api/central/alarm/confirm | ✅ |
| IHasAlarms.EndAlarmAsync | POST /api/central/alarm/end | ✅ |
| IHasAlarms.GetPendingAlarmCountAsync | POST /api/central/alarm/custom_query_count | ✅ |
> ⚠️ P1: MC4.0 告警查询使用 `skip/limit` 分页（非 `page/size`），且 `from/to` 为必填参数（非可选）。Mc4Adapter 实现时需注意。
**与 Owl API 实际行为对照**:
| 方案接口 | Owl 对应端点 | 验证结果 |
|----------|------------|:---:|
| IHasFlatDevices.GetAllDevicesAsync | GET /devices, GET /channels | ✅ |
| IHasStreams.GetLiveUrlAsync | POST /channels/:id/play | ✅ |
| IHasStreams.GetPlaybackUrlAsync | GET /recordings/channels/:cid/index.m3u8?start_ms=&end_ms= | ✅ |
| IHasStreams.StopPlayAsync | POST /channels/:id/stop | ✅ |
| IHasStreams.PtzControlAsync | POST /channels/:id/ptz/control | ✅ (仅 continuous+stop) |
| IHasStreams.GetRecordingsAsync | GET /recordings, GET /recordings/timeline | ✅ |
| IAcceptsMetadataPush.PushMetadataAsync | PUT /devices/:id | ✅ |
---
### §三 数据模型 【通过】
#### 3.1-3.3 表结构
| 评估项 | 结论 |
|--------|------|
| 6 张表 vs MC4.0+Owl 需求 | 完全覆盖。ExtraData JSON 替代扩展表，新增适配器不增表 |
| DeviceGroup 字典 | 正确。5 个分组值覆盖现在及未来可预见的设备类型 |
| PointId 替代 RegionId | 正确。对齐用户现有层级 warehouse_regions→warehouse_devicepoint→base_device |
| DeviceCategory 18 个字典值 | 完全对齐用户提供的设备清单 |
| 9 个字典字段类型 NVARCHAR | 正确。Vol.Pro 字典要求字符串类型 |
| 字段分治规则（网关字段/管理员字段） | 正确。解决了上一版 v2.0 的 P0-1 |
**数据库完整性检查**:
- ✅ 所有主键 INT AUTO_INCREMENT
- ✅ 关联字段同名同类型（DeviceId→INT, ChannelId→INT）
- ✅ 无 FOREIGN KEY 约束（Vol.Pro 通过同名字段自动关联）
- ✅ 查询加速索引覆盖所有关联字段和业务查询字段
#### 3.6 层级示例
| 评估项 | 结论 |
|--------|------|
| NVR→通道 双重身份 | 正确。通道=base_device子记录+video_channel扩展记录 |
| video_channel.DeviceId 指向通道自身 | 正确。v3.0 已明确，v2.0 存在歧义 |
---
### §四 Vol.Pro 同步接口 【通过】
| 评估项 | 结论 |
|--------|------|
| 首次入库 vs 增量更新分治逻辑 | 正确。用 `entity.DeviceId==0` 判断是否首次 |
| parentSourceId→ParentDeviceId 映射 | 正确。批量查询已有设备字典，O(1) 查找 |
| ExtraData 一行承载所有适配器字段 | 正确。新增适配器零改动 |
| SqlSugar Upsert 语义 | ⚠️ 见 Vol.Pro 框架注意事项 |
> **Vol.Pro 框架注意事项**: Vol.Pro 使用 SqlSugar ORM，`Update()` 方法默认更新全部字段。需在 Entity 上标注 `[SugarColumn(IsIgnore=true)]` 来保护管理员字段不被覆盖，或者在 `Update()` 前 `ClearUpdateColumns()` 仅指定网关字段。建议使用 `_db.Updateable(entity).UpdateColumns(it => new { it.IsOnline, it.IsParent, ... }).ExecuteCommand()` 精确控制。
---
### §五 管理端页面 【通过，1 处建议】
| 评估项 | 结论 |
|--------|------|
| Vol.Pro 框架兼容性 | 正确。el-tree + el-table 为 Element Plus 标准组件，Vol.Pro 支持 |
| 按钮矩阵按 DeviceGroup 路由 | 正确。actionMap 字典路由，新增设备类型只需加一个组件 |
| 云台按钮仅方向键 | 正确。与 Owl PTZ 实际能力一致 |
| DeviceManager 页面为自定义Vue页面 | 正确。在 `views/warehouse/DeviceManager/` 下独立存在，不被生成器覆盖 |
**Vol.Pro 生成页面与自定义页面关系**:
- `base_device` 的标准 CRUD 生成页面保留，用于批量数据维护
- `/device-manager` 自定义页面用于可视化区域管理
- 在生成页面的 extension 中加跳转按钮
- 符合 Vol.Pro `extension/` + `Partial/` 扩展机制
**建议**: 视频设备"实时预览"按钮点击后弹窗中的 Jessibuca 播放器，建议在首次播放失败（1-3s 延迟后仍未出画面）时自动重试一次。Owl+ZLM 的按需拉流机制在首次播放时有信令建立延迟。
---
### §六 同步策略 【通过，1 处补充】
| 评估项 | 结论 |
|--------|------|
| MC4.0 FullReplace 模式 | 正确。MC4.0 是唯一设备源 |
| Owl Merge 模式 | 正确。Owl 和 Vol.Pro 可并行管理设备 |
| 告警确认双向写回 | 正确。B9 成功后更新本地 State |
| 录像同步策略 | 正确。方式一（按需）+ 方式二（定时）组合 |
| 反方向写回矩阵 | 正确。Owl 支持改名+PTZ，MC4.0 不支持改名 |
**补充**: MC4.0 告警确认响应仅为 `{}`（空对象），无确认状态返回。Mc4Adapter.ConfirmAlarmAsync 应在 HTTP 200 即为成功，不做响应体解析。
---
### §七 部署拓扑 【通过】
| 评估项 | 结论 |
|--------|------|
| Owl 端口 15123 | 正确 |
| MC4 端口 3000 | 正确（MC4.0 API 文档 §1.2） |
| Gateway 端口 5100 | 合理，与 9100 不冲突 |
| 多网关实例 5100/5101 | 合理 |
| 网络拓扑 | 网关需访问 Owl(:15123)+MC4(:3000)，Vol.Pro 只需访问网关(:5100) |
---
### §八～十 【通过】
实施路线、新增整合流程、代码组织规范均正确且与 Vol.Pro 框架兼容。
---
## 三、与 Vol.Pro 框架深度兼容性分析
基于 Vol.Pro 官方文档（doc.volcore.xyz）的评估：
### 3.1 代码生成器兼容性
| 框架能力 | 方案使用方式 | 兼容性 |
|----------|------------|:---:|
| 建表后自动生成 CRUD | 6 张表跑生成器 | ✅ |
| Entity 字段自动生成表单 | 全部字段含 COMMENT 支持 | ✅ |
| 数据字典绑定 | 9 个字典字段绑定 | ✅ |
| Partial 扩展目录 | DeviceManagerController.cs 在 Partial/ 下 | ✅ |
| 代码生成器覆盖保护 | extension/ + Partial/ 不被覆盖 | ✅ |
### 3.2 前端框架兼容性
| 框架能力 | 方案使用方式 | 兼容性 |
|----------|------------|:---:|
| view-grid 组件 | 保留但不用于设备管理页 | ✅ |
| slot 数据插槽 | 生成页面插入跳转按钮 | ✅ |
| extension/*.jsx | 自定义按钮和生命周期 | ✅ |
| 自定义 Vue 页面 | DeviceManager/ 独立目录 | ✅ |
| el-tree + el-table | Element Plus 标准组件 | ✅ |
| 路由注册 | `/device-manager` | ✅ |
### 3.3 后端框架兼容性
| 框架能力 | 方案使用方式 | 兼容性 |
|----------|------------|:---:|
| IDependency 自动注入 | GatewayClient : IDependency | ✅ |
| Autofac | 所有服务自动注册 | ✅ |
| SqlSugar | Upsert 配合字段分治 | ⚠️ 需要精确 Update 列指定 |
| Quartz | SyncDevicesJob + HeartbeatJob | ✅ |
| SignalR | IoTDataHub | ✅ |
| JWT 认证 | 网关和 Vol.Pro 间无需 JWT（NodeToken） | ✅ |
> 唯一需要额外处理的：SqlSugar 的精确列更新。方案 §四 的示例代码已给出 `_db.Update(entity)`，实际使用时建议改为 `_db.Updateable(entity).UpdateColumns(...)` 精确指定更新列。
---
## 四、安全性评估
| 评估项 | 结论 |
|--------|------|
| 网关认证（NodeToken） | 正确。不受 JWT 过期影响 |
| B 组 API 无认证 | 可行。内网部署 + IP 白名单 |
| Owl JWT Token 缓存 | TokenManager 用 MemoryCache，3 天有效期 |
| MC4.0 Token 缓存 | 同上，注意 MC4 使用 `token` header 非 `Bearer` |
| 密码在 appsettings.json 明文 | ⚠️ 建议增加加密 |
**建议**: 网关 `appsettings.json` 中 Owl/MC4 密码建议使用 ASP.NET Core 的 Secret Manager 或环境变量注入，避免明文存储在版本库中。
---
## 五、性能评估
| 场景 | 评估 | 结果 |
|------|------|------|
| 网关启动注册 | 1 次 HTTP POST，< 100ms | ✅ |
| 心跳 | 15s 一次 POST，开销极小 | ✅ |
| MC4.0 设备同步 | 100 设备对象树解析 + Upsert，< 2s | ✅ |
| Owl 设备同步 | 分页拉取 100 设备，< 5s | ✅ |
| 实时数据查询 | 网关→MC4.0 HTTP 往返 + 解析，< 1s | ✅ |
| 9 路视频墙 | 9 路 WS-FLV 同时播放，ZLM 官方标称单机 10W 并发 | ✅ |
| base_device 单表规模 | 1000 设备 × ExtraData JSON ≈ 2MB | ✅ |
| IoT_DeviceData 归档 | 1000 设备 × 每小时 1 条 = 24000 条/天 | ✅ |
---
## 六、可扩展性验证
### "新增海康门禁"全链路推演
```
Day 1:
1. 新建 IntegrationGateway.Adapters.HikvisionAccess 项目
2. 实现 IHasFlatDevices + IHasAlarms
- 同步设备时填充 DeviceGroup='门禁设备'
- DeviceCategory='门禁一体机'
- ExtraData={ hikDeviceId, doorType, readerType }
3. 注册到 Host
Day 2:
4. 管理端字典加一条"门禁一体机" → 基础 CRUD 自动可用
5. 前端新建 AccessDeviceActions.vue (~80行)
6. DeviceTable.vue 的 actionMap 加一行: '门禁设备': AccessDeviceActions
后端改动: 0 行
网关改动: 适配器类
DB 改动: 0 行
```
**验证通过**。
---
## 七、发现的新问题与建议
本次深度评估新发现 **3 个细节问题**，均不影响架构，建议在实施时注意：
### N1: MC4.0 分页参数差异
MC4.0 使用 `skip/limit`，非标准 `page/size`。Mc4Adapter 实现时需转换。
**建议**: Mc4Adapter 内部封装 `ToMc4Pagination(int page, int size)` 方法。
### N2: Owl JWT 加密流程细节
Owl 登录加密目前 Gateway 配置文件存明文密码。实际流程是 `GET /login/key` → 获取 RSA 公钥 → `POST /login { data: RSA加密后的JSON }`。方案文档未展开但现有 TokenManager 设计可容纳。
**建议**: OwlAdapter.InitializeAsync 中实现完整的 RSA 加密登录链路，不在配置文件中存密码则可以用环境变量。
### N3: 字典初始化时机
Phase 0 Day 2 字典初始化需要在代码生成之后进行，因为代码生成器不创建字典。顺序应为: 建表 → 代码生成 → 字典初始化 → 绑定字典到字段。
**建议**: 实施手册中明确此顺序。
---
## 八、最终结论
| 结论 | 说明 |
|:---:|------|
| **可行** | 方案在所有维度通过了严格的技术验证 |
| **完整** | 13 个 API 完整定义，4 组数据流闭环，6 张表全覆盖 |
| **兼容** | 与 Owl v1.3.0、ZLMediaKit master、MC4.0 API、Vol.Pro 框架均对齐 |
| **可扩展** | 新增一种设备类型 = 1 个适配器类 + 1 个前端组件，后端零改动 |
| **可运维** | 网关无状态 3 配置项，心跳自动检测，字典在 Vol.Pro 管理端维护 |
**遗留物**: 3 个 N 级建议（MC4 分页参数转换、Owl RSA 登录实现、字典初始化顺序），可在 Phase 0 实施时自然解决，无需修改方案文档。
---
> 本报告为 SecMPS 整合方案的最终技术验收文件。
> 签名: 资深架构师评估
> 日期: 2026-05-16

210
doc/整合方案/SecMPS_整合项目实施手册_v3.0.md Normal file
View File

@@ -0,0 +1,210 @@
# SecMPS 整合项目实施手册
> **版本**: v3.0
> **日期**: 2026-05-16
> **基于**: SecMPS_最终整合方案_v3.0.md
> **工期**: 18-20 个工作日
> **开发模式**: 单人 + Agent，Squash Merge 主线策略
---
## 网关代码兼容性评估
> 基于 v3.0 方案对 Phase 0 已生成的 gateway/ 代码进行评估
| 组件 | 状态 | 说明 |
|------|:---:|------|
| Core/Abstractions (7接口) | ✅ 可用 | 与 v3.0 完全兼容 |
| Core/Models (10模型) | ✅ 可用 | 与 v3.0 完全兼容 |
| Core/Infrastructure (AdapterRegistry/TokenManager/RateLimiter) | ✅ 可用 | 无变更 |
| Host/Program.cs | ⚠️ 需微调 | 增加 HttpClient 注册 |
| Host/HealthController | ✅ 可用 | B1 接口无变更 |
| Host/DevicesController | ✅ 可用 | B2 接口无变更 |
| Host/PointsController | ✅ 可用 | B4/B5 接口无变更 |
| Host/AlarmsController | ✅ 可用 | B8/B9 接口无变更 |
| Host/SyncController | ✅ 可用 | B3 接口无变更 |
| Host/StreamsController | ⚠️ 需增加 | 缺少 B6b playback 端点 |
| Host/RegisterController | ❌ 缺失 | 需新建 A1/A2 接口 |
| appsettings.json | ❌ 需重写 | 需改为 v3.0 格式 |
| IGatewayClient (调用Vol.Pro) | ❌ 缺失 | 需新建 |
### 结论
**现有代码 70% 可用**，需 5 处改动：
1. 重写 `appsettings.json`（删除适配器硬编码，改为 VolProUrl/NodeCode/NodeToken）
2. 新增 `RegisterController.cs`（A1 注册 + A2 心跳）
3. `StreamsController.cs` 增加 B6b playback 端点
4. `Program.cs` 增加 `HttpClient` 注册 + 网关启动时调 Vol.Pro 注册
5. 新增 `GatewayClient.cs`（网关调用 Vol.Pro API 的 HTTP 封装）
预计改动量：约 200 行新增代码，不改动现有接口和模型。
---
## 分支管理策略
```
master ──────────────────────────────────────────────→ v3.0.0
│ ┌─ squash ─┐ ┌─ squash ─┐ ┌─ squash ─┐
├── phase/0 ├── phase/1 ├── phase/2 ├── ...
└── infrastructure └── owl-video └── mc4-iot └──
```
### 每个 Phase 标准流程
```bash
git checkout master
git checkout -b phase/{n}-{name}
# 开发 + 提交
git checkout master && git merge --squash phase/{n}-{name}
git commit -m "Phase {n}: {标题}" && git push && git tag phase-{n}-done
```
---
## 前置检查清单（Day 0）
| # | 检查项 | 验证方式 | 阻塞 |
|---|--------|----------|------|
| 1 | Owl+ZLM 部署运行 | 浏览器 http://owl_ip:15123 | Phase 1 |
| 2 | 至少1台 GB28181 设备注册到 Owl | Owl /devices 有数据 | Phase 1 |
| 3 | MC4.0 网关可访问 | curl :3000 /api/central/auth/conf/get | Phase 2 |
| 4 | MC4.0 有设备接入 | 对象树有 type=2 节点 | Phase 2 |
| 5 | 代码生成器可用 | 新建测试表→生成→确认 | Phase 0 |
| 6 | MySQL 建表权限 | 执行 CREATE TABLE | Phase 0 |
| 7 | Node.js >= 20.19 | node -v | Phase 3 |
---
## Phase 0：基础设施（Day 1-2）
### Day 1 — 网关代码修正 + 数据库
**任务 1.1**: 修正 gateway/ 代码（5 处改动，约 200 行）
1. 重写 `appsettings.json`:
```json
{
"VolProBaseUrl": "http://localhost:9100",
"NodeCode": "gw-31ku",
"NodeToken": "xxxxxxxxxx",
"Urls": "http://*:5100"
}
```
2. 新增 `RegisterController.cs`:
- `POST /api/gateway/register` — 网关启动注册（Upsert 数据库）
- `POST /api/gateway/heartbeat` — 网关每 15s 心跳
3. `StreamsController.cs` 增加:
- `GET {adapter}/{channelId}/playback?start=&end=` — 回放取流
4. `Program.cs` 增加:
```csharp
builder.Services.AddHttpClient("VolPro", c => {
c.BaseAddress = new Uri(builder.Configuration["VolProBaseUrl"]);
});
// 启动后自动注册
var registry = app.Services.GetRequiredService<AdapterRegistry>();
var http = app.Services.GetRequiredService<IHttpClientFactory>();
await RegisterWithVolPro(registry, http, app.Configuration);
```
5. 新增 `GatewayClient.cs`:
网关调用 Vol.Pro API 的封装类（注册/心跳/同步设备/同步告警）
验证: `dotnet build` 零错误 + Gateway `/health` 200
**任务 1.2**: 执行 db_init.sql（6张表）。验证: 唯一索引存在。
**任务 1.3**: Vol.Pro 侧 GatewayClient 实现 + `GatewayNodeController.cs`（A1/A2/A3/A4 服务端）。验证: 可成功注册并心跳。
### Day 2 — 代码生成 + 字典初始化
**任务 2.1**: 代码生成器跑 6 张表。
**任务 2.2**: `DeviceManagerController.cs` (Partial/)。
**任务 2.3**: 字典初始化（8个）。
**任务 2.4**: `SyncDevicesJob` + 心跳超时检测 Job。
### 合并
```bash
git add -A && git commit -m "Phase 0 完成"
git checkout master && git merge --squash phase/0-infrastructure
git commit -m "Phase 0: 网关修正 + 6张表 + 代码生成 + 字典"
git push && git tag phase-0-done
```
---
## Phase 1：Owl 适配器 + 视频设备页（Day 3-6）
Owl 端口: **15123**（非 80）。PTZ 仅方向键（continuous+stop），不支持预设位。
### Day 3 — OwlAdapter
创建 Adapters.Owl，实现 IHasFlatDevices+IHasStreams+IAcceptsMetadataPush。Token: GET /login/key → RSA → POST /login。
### Day 4 — 管理端设备页面框架
DeviceManager/index.vue + RegionTree.vue + DeviceTable.vue。
### Day 5 — 视频操作 + Jessibuca
VideoDeviceActions.vue + 播放弹窗 + 方向键云台面板。
### Day 6 — 联调 + [可选]AI事件接入
---
## Phase 2：MC4.0 + IoT（Day 7-11）
同上 v2.1 手册，增加 MC4.0 skip/limit 分页转换。
---
## Phase 3：warehouse 联调（Day 12-17）
## Phase 4：验证发布（Day 18-20）
同上 v2.1 手册，发布标签 v3.0.0。
---
## 附录 A：每日检查清单
```
□ 新增 C# 服务实现 IDependency
□ Controller 在 Partial/ 目录
□ 前端在 extension/ 目录
□ 未修改自动生成文件
□ 网关同步走字段分治
□ parentSourceId 已映射
□ 实时数据未写 IoT_DeviceData
□ dotnet build 零错误
```
## 附录 B：端口分配
| 服务 | 端口 |
|------|------|
| IntegrationGateway | 5100 |
| VolPro.WebApi | 9100 |
| web.vite | 9000 |
| warehouse | 9200 |
| Owl 管理端 | **15123** |
| MC4.0 | 3000 |
## 附录 C：里程碑
| 标签 | 指向 |
|------|------|
| `phase-0-done` | 网关修正 + 6张表 + 字典 |
| `phase-1-done` | OwlAdapter + 视频页 |
| `phase-2-done` | Mc4Adapter + IoT + SignalR |
| `phase-3-done` | warehouse + 联调 |
| `phase-4-done` | 验证 + 文档 |
| `v3.0.0` | 正式发布 |
---
> 取代: SecMPS_整合项目实施手册_v2.1.md

444
doc/整合方案/SecMPS_最终整合方案_v2.0.md
View File

@@ -1,9 +1,8 @@
# SecMPS 整合方案（最终版）：IntegrationGateway + 统一设备管理
> **版本**: v2.0
> **日期**: 2026-05-15
> **日期**: 2026-05-16
> **状态**: 待实施
> **替代**: Vol.Pro_MC4.0_整合方案_v1.0、Vol.Pro_Owl_ZLMediaKit_整合方案_v1.0、Vol.Pro_统一设备管理_区域树与地图绑定方案_v1.0
---
@@ -11,49 +10,60 @@
```
前端层
web.vite 管理端（设备管理页+标准CRUD） warehouse 大屏（Map/Live/IoT/Alarm）
│ HTTP REST │ HTTP REST + SignalR
▼ ▼
web.vite 管理端（设备管理+网关管理） warehouse 大屏（Map/Live/IoT/Alarm）
| HTTP REST | HTTP REST + SignalR
v v
Vol.Pro 后端 (api_sqlsugar)
DeviceManagerController / GatewayClient / SignalR Hubs
DeviceManagerController / GatewayNodeController / SignalR Hubs
Quartz: SyncDevicesJob / RealtimePollJob / AlarmPollJob
数据库: Base_Device / warehouse_regions / Device_Video_Ext / Device_IoT_Ext / IoT_DevicePoint / IoT_Alarm
│ HTTP REST
▼
IntegrationGateway (独立服务 :5100)
Adapters.Owl (IHasFlatDevices+IHasStreams+IAcceptsMetadataPush)
Adapters.MC4 (IHasOwnDeviceTree+IHasPoints+IHasAlarms)
Core: AdapterRegistry / SyncEngine / TokenManager / RateLimiter
│ HTTP │ HTTP
▼ ▼
Owl + ZLMediaKit MC4.0 采集网关
Docker Compose HTTP API :3000
数据库: 6 张表 (base_device / video_channel / video_record / iot_devicedata / iot_alarm / gateway_nodes)
| 注册/下发设备/心跳/同步数据
v
IntegrationGateway 实例A (:5100) IntegrationGateway 实例B (:5101)
NodeCode: gw-31ku NodeCode: gw-11ku
Adapters: MC4 / Owl Adapters: MC4 / HikvisionISC
| HTTP | HTTP
v v
MC4.0 (:3000) Owl (:80) MC4.0 (:3000) 海康ISC (:80)
```
### 核心设计原则
- **网关无状态**：配置仅 NodeCode/Token/VolProUrl，挂了重装即恢复
- **AdapterCode 双段标识**："mc4:31号库房" 区分同类型多实例
- **DeviceGroup 路由**：基类表用字典字段决定适配器和行为，不依赖扩展表
- **ExtraData JSON**：所有适配器特有字段存入 ExtraData，新增适配器不增表
- **心跳机制**：网关 15s 心跳，Vol.Pro 超 30s 级联设备离线
---
## 二、IntegrationGateway 设计
## 二、网关架构（方案 C+）
### 2.1 项目结构
### 2.1 网关注册与心跳流程
```
IntegrationGateway/
├── src/
│ ├── Host/Controllers/ → Devices / Points / Streams / Alarms / Sync / Health
│ ├── Core/Abstractions/ → 分型接口
│ │ ├── IIntegrationAdapter
│ │ ├── IHasOwnDeviceTree (MC4.0)
│ │ ├── IHasFlatDevices (Owl)
│ │ ├── IHasPoints (MC4.0)
│ │ ├── IHasStreams (Owl)
│ │ ├── IHasAlarms (通用)
│ │ └── IAcceptsMetadataPush (Owl)
│ ├── Core/Infrastructure/ → SyncEngine / AdapterRegistry / TokenManager / RateLimiter
│ ├── Adapters.Owl/ → OwlAdapter
│ └── Adapters.MC4/ → Mc4Adapter
管理端: gateway_nodes 表新增 → 生成 NodeCode + Token
网关配置: { NodeCode, Token, VolProUrl }
网关启动 → POST /register { nodeCode,token,adapterTypes,baseUrl }
Vol.Pro 校验 → 更新 AdapterTypes/BaseUrl/IsOnline=在线
响应: { gatewayNodeId, devices: [base_device WHERE GatewayNodeId=当前] }
网关按 AdapterCode 分流 → Adapter 连接第三方 → 发现子设备
网关 → POST /sync → Vol.Pro 写入 base_device（含 ExtraData)
网关每 15s → POST /heartbeat { nodeCode, token }
Vol.Pro Job: IsOnline=在线 且 LastHeartbeat < now-30s → IsOnline=离线 → 级联设备离线
```
### 2.2 适配器能力矩阵
### 2.2 网关配置
```json
{
"VolProBaseUrl": "http://localhost:9100",
"NodeCode": "gw-31ku",
"NodeToken": "xxxxxxxxxx"
}
```
### 2.3 适配器能力矩阵
| 接口 | Owl | MC4.0 | 门禁(未来) |
|------|:---:|:-----:|:----------:|
@@ -64,7 +74,7 @@ IntegrationGateway/
| IHasAlarms | ⚠️ | ✅ | ✅ |
| IAcceptsMetadataPush | ✅ | ❌ | ⚠️ |
### 2.3 双向同步引擎
### 2.4 双向同步引擎
| 方向 | 说明 | MC4.0 | Owl |
|------|------|-------|-----|
@@ -72,152 +82,241 @@ IntegrationGateway/
| PushToSource | Vol.Pro→第三方 | 告警确认/控制 | 元数据/PTZ |
| Bidirectional | 先写第三方再更新本地 | 告警确认 | — |
### 2.4 Gateway API
### 2.5 对接 API 规范
网关与 Vol.Pro 之间有两组接口，调用方向不同。
#### A. 网关 → Vol.Pro（网关主动调用）
| # | 接口 | 说明 |
|---|------|------|
| A1 | `POST /api/gateway/register` | 网关启动注册，上报身份与能力，获取所管设备列表 |
| A2 | `POST /api/gateway/heartbeat` | 心跳（每 15s），Vol.Pro 更新在线状态 |
| A3 | `POST /api/gateway/sync/devices` | 上送设备数据（新增/变更/离线） |
| A4 | `POST /api/gateway/sync/alarms` | 上送告警数据 |
**A1 注册** — 认证: NodeToken
```
GET /api/gateway/health
GET /api/gateway/devices?adapter=&page=&size=
GET /api/gateway/devices/sync?adapter=
GET /api/gateway/realtime/{adapter}/{deviceId}
POST /api/gateway/realtime/{adapter}/control
GET /api/gateway/streams/{adapter}/{id}/live
POST /api/gateway/streams/{adapter}/{id}/ptz
GET /api/gateway/alarms/{adapter}?from=&to=
POST /api/gateway/alarms/{adapter}/{id}/confirm
Request: { nodeCode, token, adapterTypes, baseUrl }
Response: { nodeId, devices: [ base_device 列表(当前网关负责的顶层设备) ] }
Error: 401 认证失败
```
**A2 心跳** — 认证: NodeToken
```
Request: { nodeCode, token }
Response: { status: "ok" }
```
**A3 设备同步** — 认证: NodeToken
```
Request: { nodeCode, token, devices: [{ adapterCode, sourceId, name, category, group,
isParent, parentSourceId, isOnline, ipAddress, port, extraData }] }
Response: { added, updated, removed }
```
> 网关只发自己负责的字段（ExtraData 中的适配器属性 + 公共状态字段），不碰管理员字段（DeviceName/Category/Location/MapModelId…）。Vol.Pro 首次入库写全量，后续仅更新网关负责的列。
**A4 告警同步** — 认证: NodeToken
```
Request: { nodeCode, token, alarms: [{ sourceAlarmId, deviceSourceId, adapterCode,
level, desc, value, startTime }] }
Response: { added }
```
---
## 三、数据模型
#### B. Vol.Pro / 管理端 → 网关（查询与控制）
| # | 接口 | 说明 |
|---|------|------|
| B1 | `GET /api/gateway/health` | 网关及所有适配器状态 |
| B2 | `GET /api/gateway/devices?adapter=&page=&size=` | 设备列表（实时查第三方） |
| B3 | `POST /api/gateway/devices/sync?adapter=` | 手动触发全量同步 |
| B4 | `GET /api/gateway/realtime/{adapter}/{deviceId}` | 实时点位值 |
| B5 | `POST /api/gateway/realtime/{adapter}/control` | 反向控制 { deviceSourceId, pointIndex, value } |
| B6 | `GET /api/gateway/streams/{adapter}/{channelId}/live` | 取流地址 → { wsFlv, httpFlv, hls, webrtc } |
| B7 | `POST /api/gateway/streams/{adapter}/{channelId}/ptz` | 云台控制 { direction, speed } |
| B8 | `GET /api/gateway/alarms/{adapter}?from=&to=&page=&size=` | 告警查询 |
| B9 | `POST /api/gateway/alarms/{adapter}/{alarmId}/confirm` | 告警确认（写回第三方） |
> B 组接口由管理端或 Vol.Pro 后端直接调用网关，认证方式为内网直连或网关侧 IP 白名单。
---
## 三、数据模型（6 张表）
### 3.1 区域表 warehouse_regions（现有）
层级: warehouse_regions(区域) → warehouse_devicepoint(点位) → base_device(设备)
| 字段 | 说明 |
|------|------|
| Id | int PK |
| RegionName | nvarchar(255) |
| ParentId | int? (自引用树) |
### 3.2 统一设备主表 Base_Device（新建）
### 3.2 网关节点表 gateway_nodes
| 字段 | 类型 | 说明 |
|------|------|------|
| DeviceId | uniqueidentifier PK | Vol.Pro内部ID |
| DeviceName | nvarchar(100) | 本地名称 |
| **AdapterCode** | nvarchar(50) | owl/mc4/hikvision_access |
| **SourceId** | nvarchar(100) | 第三方原始ID |
| DeviceCategory | int | 1=视频 2=IoT 3=门禁 4=道闸 5=报警 |
| DeviceType | nvarchar(50) | GB28181/TempSensor... |
| **RegionId** | int? | FK→warehouse_regions.Id |
| **IsParent** | bit | 是否父设备 |
| **ParentDeviceId** | uniqueidentifier? | 父设备自引用 |
| IsOnline | int | 0/1 |
| **MapModelId** | nvarchar(100) | VgoMap模型ID |
| MapModelScale | float | |
| MapModelRotation | nvarchar(100) | |
| Lat/Lng | float | WGS84 |
| ExtraData | nvarchar(max) | 适配器原始JSON |
| LocalOverrides | nvarchar(max) | 本地覆盖JSON |
| SyncVersion | bigint | 乐观锁 |
| LastSyncTime | datetime | |
| NodeId | INT AUTO_INCREMENT | 网关节点ID |
| NodeCode | NVARCHAR(50) | 网关唯一编码（管理端配置） |
| NodeName | NVARCHAR(100) | 网关名称 |
| NodeToken | NVARCHAR(100) | 认证令牌（管理端生成） |
| AdapterTypes | NVARCHAR(200) | 适配器类型（网关上报） |
| BaseUrl | NVARCHAR(200) | 网关地址（网关上报） |
| LastHeartbeat | DATETIME | 上次心跳时间 |
| IsOnline | NVARCHAR(20) | 在线状态(字典: 在线/离线) |
| Enable | NVARCHAR(20) | 启用状态(字典: 启用/禁用) |
### 3.3 统一设备主表 base_device
| 字段 | 类型 | 说明 |
|------|------|------|
| DeviceId | INT AUTO_INCREMENT | Vol.Pro内部ID |
| DeviceName | NVARCHAR(100) | 设备名称 |
| AdapterCode | NVARCHAR(50) | "mc4:31号库房"（类型:实例） |
| SourceId | NVARCHAR(100) | 源系统设备ID |
| **DeviceCategory** | NVARCHAR(50) | 设备种类(字典: 摄像机/温湿度变送器/...) |
| **DeviceGroup** | NVARCHAR(20) | 设备分组(字典: 视频设备/IoT设备/门禁设备/道闸设备/报警设备) |
| PointId | INT? | 所属点位ID |
| GatewayNodeId | INT? | 所属网关节点ID |
| IsParent | NVARCHAR(20) | 是否父设备(字典: 是/否) |
| ParentDeviceId | INT? | 父设备自引用 |
| IsOnline | NVARCHAR(20) | 在线状态(字典: 在线/离线) |
| MapModelId | NVARCHAR(100) | VgoMap模型ID |
| MapModelScale | FLOAT | |
| MapModelRotation | NVARCHAR(100) | |
| **ExtraData** | TEXT | ★ 适配器扩展JSON(Owl/MC4/门禁字段均存于此) |
| LastSyncTime | DATETIME | |
| Enable | NVARCHAR(20) | 启用状态(字典: 启用/禁用) |
唯一约束: (AdapterCode, SourceId)
### 3.3 扩展表
### 3.4 DeviceGroup 分组规则
- **Device_Video_Ext**: 视频设备扩展（OwlDeviceId, Protocol, ChannelCount）
- **Device_IoT_Ext**: IoT设备扩展（Mc4DeviceId, ObjectType, Tag）
- **Video_Channel**: 视频通道（OwlChannelId, DeviceId, HasPtz）
- **Video_Record**: 录像记录
- **IoT_DevicePoint**: 点位表（PointIndex, PointName, Unit, IsControlPoint）
- **IoT_DeviceData**: 历史归档（仅存快照，实时不入库）
- **IoT_Alarm**: 告警记录（Mc4AlarmId, AlarmLevel, State）
Vol.Pro 同步接口通过 DeviceGroup 路由，无需硬编码：
### 3.4 层级示例
| DeviceGroup | 网关适配器 | 前端按钮组 | 同步模式 |
|:---:|------|------|:---:|
| 视频设备 | OwlAdapter → IHasStreams | 实时预览/云台/回放/快照 | Merge |
| IoT设备 | Mc4Adapter → IHasPoints | 实时数据/控制/告警 | FullReplace |
| 门禁设备 | AccessAdapter | 远程开门/记录/告警 | Merge |
| 道闸设备 | BarrierAdapter | 抬杆/落杆/记录 | Merge |
| 报警设备 | AlarmAdapter | 查看告警/布防撤防 | Merge |
### 3.5 ExtraData 格式示例
```json
// 摄像机 (Owl)
{ "owlDeviceId": "gb_xxx", "protocol": "GB28181", "manufacturer": "海康" }
// 温湿度变送器 (MC4子设备)
{ "mc4DeviceId": 1001, "pointIndex": 0, "unit": "℃", "isControlPoint": false }
// 空调控制器 (MC4子设备)
{ "mc4DeviceId": 1002, "pointIndex": 2, "unit": null, "isControlPoint": true }
// 未来门禁
{ "hikDeviceId": "door_01", "doorType": "单门", "readerType": "IC卡" }
```
### 3.6 层级示例
```
warehouse_regions: 厂区 → 新库区 → 31号库房
Base_Device (RegionId=3):
东北角高位摄像机 (Category=1)
人员计数摄像机 (Category=1)
动环采集器 (Category=2, IsParent=1)
├── 温湿度探头 (ParentDeviceId=采集器)
├── 空调控制器 (ParentDeviceId=采集器)
├── 除湿机 (ParentDeviceId=采集器)
└── 紧急报警按钮 (ParentDeviceId=采集器)
gateway_nodes: gw-31ku
warehouse_regions → warehouse_devicepoint → base_device
区域 点位 设备
例: 厂区 → 新库区 → 31号库房(点位) → 设备
base_device (PointId=点位ID, GatewayNodeId=gw-31ku.NodeId):
东北角高位摄像机 (DeviceCategory=摄像机, DeviceGroup=视频设备, ExtraData={owlDeviceId,...})
人员计数摄像机 (DeviceCategory=摄像机, DeviceGroup=视频设备)
动环采集器 (DeviceCategory=动环采集器, DeviceGroup=IoT设备, IsParent=是)
├── 温湿度变送器 (DeviceCategory=温湿度变送器, ParentDeviceId=采集器, ExtraData={pointIndex:0,unit:"℃"})
├── 空调控制器 (DeviceCategory=空调控制器, ParentDeviceId=采集器, ExtraData={pointIndex:2,isControlPoint:true})
├── 除湿/恒湿机 (DeviceCategory=除湿/恒湿机, ParentDeviceId=采集器)
└── 紧急报警按钮 (DeviceCategory=紧急报警按钮, DeviceGroup=报警设备, ParentDeviceId=采集器)
```
---
## 四、管理端统一设备页面
## 四、Vol.Pro 同步接口（新增适配器零改动）
### 4.1 布局
```csharp
// POST /api/gateway/sync
public async Task SyncDevices(string nodeCode, List<StandardDevice> devices)
{
var node = await _db.gateway_nodes.FirstAsync(n => n.NodeCode == nodeCode);
foreach (var d in devices)
{
var entity = await _db.base_device
.FirstOrDefaultAsync(x => x.AdapterCode == d.AdapterCode && x.SourceId == d.SourceId)
?? new base_device();
entity.DeviceName = d.Name;
entity.DeviceGroup = d.Group; // 字典: 视频设备/IoT设备/...
entity.DeviceCategory = d.Category; // 字典: 摄像机/温湿度变送器/...
entity.IsOnline = d.IsOnline ? "在线" : "离线";
entity.IsParent = d.IsParent ? "是" : "否";
entity.ParentDeviceId = d.ParentSourceId; // 网关同步过来的父级关系
entity.GatewayNodeId = node.NodeId;
entity.ExtraData = d.ExtraDataJson; // ★ 一行，适配器字段全在这里
// ... 公共字段赋值 ...
_db.base_device.Upsert(entity);
}
await _db.SaveChangesAsync();
}
```
┌──────────────────┬───────────────────────────────────────┐
│ 顶部工具栏 │ │
├──────────────────┼───────────────────────────────────────┤
│ 左侧区域树 │ 右侧设备列表 │
│ │ │
│ 📁 厂区 │ 区域:31号库房 最后同步:05-15 │
│ 📁 新库区 │ ┌──────────────────────────────┐ │
│ 📁 31号库房 ● │ │ ▸动环采集器 MC4.0 █在线 │ │
│ 📁 11号库房 │ │ 东北角摄像机 Owl █在线 │ │
│ │ └──────────────────────────────┘ │
│ [+新建区域] │ │
└──────────────────┴───────────────────────────────────────┘
```
### 4.2 前端文件
```
web.vite/src/views/warehouse/DeviceManager/
├── index.vue # 主页面（左树右表）
├── components/
│ ├── RegionTree.vue # el-tree 区域树
│ ├── DeviceTable.vue # el-table 可展开行
│ ├── DeviceEditDialog.vue # 编辑弹框
│ ├── MapBindingPanel.vue # 地图绑定面板
│ ├── VideoDeviceActions.vue # 视频操作按钮组
│ └── IoTDeviceActions.vue # IoT操作按钮组
└── api/deviceManager.js
路由: /device-manager
```
### 4.3 后端 API
| 接口 | 说明 |
|------|------|
| GET `/api/DeviceManager/GetRegionTree` | 区域树+设备数量 |
| GET `/api/DeviceManager/GetDevicesByRegion?regionId=3` | 区域设备列表(含子设备) |
| PUT `/api/DeviceManager/{deviceId}` | 更新设备(含地图绑定) |
| POST `/api/DeviceManager/SyncFromGateway` | 手动同步 |
Controller 路径: `Controllers/Warehouse/Partial/DeviceManagerController.cs`
### 4.4 操作按钮矩阵
| Category | 按钮 |
|----------|------|
| 1-视频 | 实时预览/云台控制/查看回放/获取快照/同步通道 |
| 2-IoT | 查看实时数据/设备控制/刷新点位/查看告警 |
| 3-门禁 | 远程开门/查看记录/查看告警 |
| 4-道闸 | 抬杆/落杆/查看记录 |
---
## 五、同步策略
## 五、管理端统一设备页面
### 5.1 操作按钮矩阵（按 DeviceGroup 路由）
| DeviceGroup | 操作按钮 |
|:---:|------|
| 视频设备 | 实时预览 / 云台控制 / 查看回放 / 获取快照 / 同步通道 |
| IoT设备 | 查看实时数据 / 设备控制 / 刷新点位 / 查看告警 |
| 门禁设备 | 远程开门 / 查看记录 / 查看告警 |
| 道闸设备 | 抬杆 / 落杆 / 查看记录 |
| 报警设备 | 查看告警 / 布防撤防 |
### 5.2 前端按钮路由
```javascript
// DeviceTable.vue
const actionMap = {
'视频设备': VideoDeviceActions,
'IoT设备': IoTDeviceActions,
'门禁设备': AccessDeviceActions,
'道闸设备': BarrierDeviceActions,
'报警设备': AlarmDeviceActions,
}
// 渲染: actionMap[device.DeviceGroup]
```
---
## 六、同步策略
### MC4.0 → 区域树+设备
- `type=1` 节点 → 名称匹配 warehouse_regions → 绑区或新建
- `type=2` 节点 → Upsert Base_Device, RegionId=叶子区域
- type=1 节点 → 名称匹配 warehouse_regions → 绑区或新建
- type=2 节点 → Upsert base_device, DeviceGroup=IoT设备, ExtraData 存点位属性
- 模式: FullReplace, 频率限制: 2次/秒
### Owl → 设备
- `GET /devices` → Upsert Base_Device (Category=1, IsParent=1)
- `GET /channels` → Upsert Base_Device (ParentDeviceId=NVR)
- Owl 无区域概念 → RegionId=NULL, 管理员手动分配
- GET /devices → Upsert base_device (DeviceGroup=视频设备, IsParent=是)
- GET /channels → Upsert base_device (ParentDeviceId=NVR) + video_channel
- Owl 无区域概念 → PointId=NULL, 管理员手动分配
- 模式: Merge
### 反方向写回
@@ -230,60 +329,62 @@ Controller 路径: `Controllers/Warehouse/Partial/DeviceManagerController.cs`
---
## 六、部署拓扑
## 七、部署拓扑
```
Docker: Owl+ZLM (:80,:5060) │ Docker: MC4.0 (:3000)
│
┌──────────────┴──────────────┐
│ IntegrationGateway :5100 │
└──────────────┬──────────────┘
│
┌──────────────┴──────────────┐
│ VolPro.WebApi :9100 │
│ MySQL / Redis │
└──────────────┬──────────────┘
│
┌──────────────────┴──────────────────┐
│ web.vite :9000 warehouse :9200 │
└─────────────────────────────────────┘
Docker: Owl+ZLM (:80) MC4.0-1 (:3000) MC4.0-2 (:3000)
| | |
+----------+-----------+-------------------+
|
+----------+-----------+
| Gateway gw-31ku | Gateway gw-11ku
| :5100 | :5101
+----------+-----------+
|
+----------+-----------+
| VolPro.WebApi |
| :9100 |
| MySQL / Redis |
+----------+-----------+
|
+--------------+---------------+
| web.vite :9000 warehouse :9200 |
+--------------------------------+
```
---
## 七、实施路线
## 八、实施路线
| 阶段 | 工期 | 内容 |
|------|------|------|
| Phase 0 | Day 1-2 | Gateway骨架 + Base_Device建表 + 代码生成 |
| Phase 0 | Day 1-2 | Gateway骨架 + 6张表建表 + 代码生成 |
| Phase 1 | Day 3-6 | OwlAdapter + 管理端视频设备页 |
| Phase 2 | Day 7-11 | Mc4Adapter + IoT管理 + 区域树匹配 + SignalR |
| Phase 3 | Day 12-17 | warehouse端改造 + 全链路联调 |
| Phase 4 | Day 18-20 | 验证 + 缓冲 |
**总计: 18-20 个工作日**
总计: 18-20 个工作日
---
## 八、新增整合流程
## 九、新增整合流程
以接入「海康门禁」为例：
1. 新建 `IntegrationGateway.Adapters.HikvisionAccess` 项目
2. 实现 `IHasFlatDevices + IHasAlarms`
3. 注册到 Host
4. 前端新增 `AccessDeviceActions.vue` (~80行)
5. DeviceTable.vue 加 `v-else-if (Category===3)`
6. Vol.Pro 后端零改动
**总工作量: 1-2 天**
1. 新建 IntegrationGateway.Adapters.HikvisionAccess 项目
2. 实现 IHasFlatDevices + IHasAlarms → 设备同步时填充 DeviceGroup=门禁设备
3. 管理端字典加一条"门禁设备"分组 → 按钮自动出现
4. Vol.Pro 同步接口零改动（ExtraData 承载门禁字段）
5. 前端新增 AccessDeviceActions.vue (~80行)
总工作量: 1-2 天
---
## 九、代码组织规范
## 十、代码组织规范
| 代码类型 | 路径 | 被覆盖? |
|----------|------|:---:|
| 第三方对接 | IntegrationGateway/ | ❌ |
| 第三方对接 | gateway/ | ❌ |
| 扩展Controller | Controllers/*/Partial/ | ❌ |
| Entity扩展 | DomainModels/*/partial/ | ❌ |
| 前端业务逻辑 | extension/warehouse/*.jsx | ❌ |
@@ -292,5 +393,4 @@ Docker: Owl+ZLM (:80,:5060) │ Docker: MC4.0 (:3000)
---
> **文档结束**
> **取代**: Vol.Pro_MC4.0_整合方案_v1.0、Vol.Pro_Owl_ZLMediaKit_整合方案_v1.0、Vol.Pro_统一设备管理_区域树与地图绑定方案_v1.0、Vol.Pro_整合项目_实施方案_v1.0
> 取代: V1.0 系列所有整合方案文档

78
doc/整合方案/SecMPS_最终整合方案_v3.0.md
View File

@@ -329,71 +329,38 @@ public async Task SyncDevices(string nodeCode, List<StandardDevice> devices)
---
## 五、管理端设备操作集成
> **设计决策**: 不再需要独立的设备管理页面。Vol.Pro 框架自带三级主从表显示能力（warehouse_regions → warehouse_devicepoint → base_device），可直接在框架生成的 base_device 列表页面中嵌入操作按钮，按 DeviceGroup 动态渲染。
## 五、管理端统一设备页面
### 5.1 操作按钮矩阵
| DeviceGroup | 操作按钮 | 说明 |
|:---:|------|------|
| 视频设备 | 实时预览 / 云台控制(仅方向键) / 查看回放 / 获取快照 / 同步通道 | 全部通过网关 B 组接口代理到 Owl |
| IoT设备 | 查看实时数据 / 设备控制 / 刷新点位 / 查看告警 | 通过网关 B4/B5 代理到 MC4.0 |
| 门禁设备 | 远程开门 / 查看记录 / 查看告警 | Phase 3 接入海康ISC后启用 |
| 道闸设备 | 抬杆 / 落杆 / 查看记录 | Phase 3 接入 |
| 报警设备 | 查看告警 / 布防撤防 | Phase 3 接入 |
| DeviceGroup | 操作按钮 |
|:---:|------|
| 视频设备 | 实时预览 / 云台控制(仅方向键) / 查看回放 / 获取快照 / 同步通道 |
| IoT设备 | 查看实时数据 / 设备控制 / 刷新点位 / 查看告警 |
| 门禁设备 | 远程开门 / 查看记录 / 查看告警 |
| 道闸设备 | 抬杆 / 落杆 / 查看记录 |
| 报警设备 | 查看告警 / 布防撤防 |
### 5.2 前端按钮嵌入方案
框架生成的 base_device 列表页面的"操作"列默认只有"编辑/删除"。在 **base_deviceController Partial** 中扩展前端分组逻辑，替换默认操作列为自定义渲染。
### 5.2 前端按钮路由
```javascript
// web.vite/src/extension/warehouse/base_device.jsx 或 views/warehouse/base_device/components/ActionColumn.vue
const actionMap = {
'视频设备': VideoDeviceActions, // 实时预览/云台/回放/快照/同步通道
'IoT设备': IoTDeviceActions, // 实时数据/控制/刷新/告警
'门禁设备': AccessDeviceActions, // 远程开门/记录/告警
'道闸设备': BarrierDeviceActions,// 抬杆/落杆/记录
'报警设备': AlarmDeviceActions, // 告警/布防撤防
'视频设备': VideoDeviceActions,
'IoT设备': IoTDeviceActions,
'门禁设备': AccessDeviceActions,
'道闸设备': BarrierDeviceActions,
'报警设备': AlarmDeviceActions,
}
// 操作列模板中根据 row.deviceGroup 动态渲染对应组件
<template v-for="(row, idx) in data">
<component :is="actionMap[row.deviceGroup] || DefaultActions" :row="row" />
</template>
```
**要点**:
- 框架"操作"列通过自定义插槽替换，不修改框架生成的 Vue 文件本体
- 组件放在 `views/warehouse/base_device/components/` 下，防代码生成覆盖
- 五个分组组件各自独立（~80-150 行），新增分组仅加一个文件
### 5.3 后端 API
### 5.3 前端操作组件清单
| 文件 | 大小 | 说明 |
|------|:---:|------|
| `VideoDeviceActions.vue` | ~120行 | 预览/云台/回放/快照按钮组，预览弹窗内嵌 Jessibuca 播放器（或 <video> 标签回退），云台仅 ↑↓←→+ZOOM+停止 |
| `IoTDeviceActions.vue` | ~100行 | 实时数据表格弹窗（轮询 B4），控制面板（B5 写值），告警快捷入口 |
| `AccessDeviceActions.vue` | ~60行 | 远程开门按钮 + 记录查询入口 |
| `BarrierDeviceActions.vue` | ~60行 | 抬杆/落杆按钮 |
| `AlarmDeviceActions.vue` | ~60行 | 告警列表 + 布防/撤防开关 |
### 5.4 后端操作 API
> 以下 API 由网关 B 组接口代理，Vol.Pro 前端不直连子系统，统一经网关中转。
| 接口 | 方法 | 说明 | 对应网关接口 |
|------|:---:|------|------|
| `/api/gateway/streams/{adapter}/{sourceId}/live` | GET | 获取实时流地址 | B6a |
| `/api/gateway/streams/{adapter}/{sourceId}/playback?start=&end=` | GET | 获取回放地址 | B6b |
| `/api/gateway/streams/{adapter}/{sourceId}/snapshot` | POST | 获取截图 | — |
| `/api/gateway/streams/{adapter}/{sourceId}/ptz` | POST | 云台方向控制 | B7 |
| `/api/gateway/realtime/{adapter}/{sourceId}` | GET | 获取实时点位值 | B4 |
| `/api/gateway/realtime/{adapter}/control` | POST | 设备控制写值 | B5 |
| `/api/gateway/alarms/{adapter}` | GET | 分页查询告警 | B8 |
| `/api/gateway/alarms/{adapter}/{alarmId}/confirm` | POST | 确认告警 | B9 |
> Vol.Pro 前端直接请求网关（:5100），不经过 Vol.Pro 后端中转。跨域问题通过网关 CORS 或 nginx 反向代理解决。
| 接口 | 说明 |
|------|------|
| GET /api/DeviceManager/GetRegionTree | 区域→点位→设备树 |
| GET /api/DeviceManager/GetDevicesByPoint?pointId= | 点位下设备列表(含子设备) |
| PUT /api/DeviceManager/{deviceId} | 更新设备(含地图绑定) |
| POST /api/DeviceManager/SyncFromGateway | 手动同步 |
---
@@ -459,7 +426,7 @@ Docker: Owl+ZLM (:15123) MC4.0-1 (:3000) MC4.0-2 (:3000)
| 阶段 | 工期 | 内容 |
|------|------|------|
| Phase 0 | Day 1-2 | Gateway骨架 + 6张表建表 + 代码生成 + 字典初始化 |
| Phase 1 | Day 3-6 | OwlAdapter + base_device操作按钮组件(视频) + [可选]AI事件接入 |
| Phase 1 | Day 3-6 | OwlAdapter + 管理端视频设备页 + [可选]AI事件接入 |
| Phase 2 | Day 7-11 | Mc4Adapter + IoT管理 + 区域树匹配 + SignalR |
| Phase 3 | Day 12-17 | warehouse端改造 + 全链路联调 |
| Phase 4 | Day 18-20 | 验证 + 缓冲 |
@@ -528,4 +495,3 @@ Phase 0 建表后需在 Vol.Pro 管理端创建以下数据字典：
> - v1.0 (2026-04-29) — 初始 Owl+MC4 独立方案
> - v2.0 (2026-05-16) — 整合 Gateway 架构 + 数据字典 + ExtraData JSON
> - v3.0 (2026-05-16) — Owl/ZLMediaKit 双文档验证 + 14 项修正（P0/P1/P2 修复）
> - v3.1 (2026-05-17) — 第五章修订：取消独立设备管理页面，改为框架主从表嵌入操作按钮

364
doc/设计文档/KMS钥匙柜适配器详细设计文档.md
View File

@@ -1,364 +0,0 @@
# KMS 钥匙柜适配器详细设计文档
> **版本**: 1.0
> **日期**: 2025-05-19
> **基准**: `doc/整合方案/KMS钥匙柜整合方案_v2.0.md`
> **接口文档**: `doc/对接文档/钥匙管理系统软件接口.docx` (KMS API v1.0.4)
> **技术栈**: .NET 8 / ASP.NET Core / C#
---
## 1. 接口覆盖设计
### 1.1 完整 KMS API 概览
KMS 系统共有 **38 个 REST 端点**，分 9 大类。按设计原则，适配器只代理 **第三方集成接口**（第 2.18 节），不代理 KMS 自身管理接口。
### 1.2 第三方集成接口（Phase 1 — 核心实现）
以下 8 个接口是 KMS 专为第三方对接设计的扁平化 API：
| # | 方法 | 路径 | 用途 | 适配器方法 |
|---|:---:|------|------|------|
| 2.18.1 | GET | `/prod-api/heartBeat` | 心跳检测 | `HealthCheckAsync()` |
| 2.18.2 | POST | `/prod-api/batchDeleteStaff` | 批量删除员工 | `BatchDeleteStaffAsync()` |
| 2.18.3 | POST | `/prod-api/batchSyncStaff` | 批量同步员工 | `BatchSyncStaffAsync()` |
| 2.18.4 | POST | `/prod-api/getOpenerList` | 查询柜体+钥匙信息 | `GetDevicesAsync()` |
| 2.18.5 | POST | `/prod-api/getPermissionList` | 查询授权记录 | `GetPermissionListAsync()` |
| 2.18.6 | POST | `/prod-api/getRecordList` | 查询借还记录 | `GetBorrowRecordsAsync()` |
| 2.18.7 | POST | `/prod-api/getWarningList` | 查询告警记录 | `GetAlarmsAsync()` |
| 2.18.8 | POST | `/thirdPlatlogin` | 第三方登录/事件 | `ThirdPlatLoginAsync()` |
加上认证接口 `POST /prod-api/getToken`，适配器共需对接 **9 个 KMS 接口**。
### 1.3 标准 KMS 管理接口（Phase 2 可选）
以下 29 个接口属于 KMS 自身管理功能（员工 CRUD、柜体 CRUD、钥匙 CRUD 等），KMS 自带 Web 管理端即可操作。Vol.Pro 如需代理这些接口，可在 Phase 2 扩展，但设计文档不列入必需实现。
| 模块 | 接口数 | 备注 |
|------|:---:|------|
| 交接记录 | 2 | GET `/kms/handover/*` |
| 授权管理 | 3 | GET `/kms/permission/*` + POST remote |
| 告警记录(标准) | 1 | GET `/kms/warning/list` |
| 员工可借钥匙 | 2 | POST/GET `/kms/staffopener/*` |
| 员工管理 | 5 | CRUD `/kms/staff/*` |
| 员工组管理 | 6 | CRUD `/kms/staffGroup/*` |
| 物品类别 | 6 | CRUD `/kms/openerType/*` |
| 柜体管理 | 5 | CRUD `/kms/locker/*` + statistics |
| 锁孔管理 | 4 | CRUD `/kms/lockhole/*` |
| 钥匙管理 | 7 | CRUD `/kms/opener/*` + selectCanBorrow |
| 钥匙组 | 7 | CRUD `/kms/openerGroup/*` |
| 部门 | 1 | GET `/system/dept/root/{userId}` |
| 授权详情 | 1 | GET `/kms/permissioninfo/getByPermissionId/{uuid}` |
| **合计** | **29** | Phase 2 按需实现 |
---
## 2. 项目结构
```
gateway/src/IntegrationGateway.Adapters.Kms/
├── IntegrationGateway.Adapters.Kms.csproj # 类库, net8.0
├── KmsAdapter.cs # 适配器主体 (IHasFlatDevices + IHasAlarms)
├── KmsAuthHelper.cs # Bearer Token 认证
└── KmsModels.cs # 请求/响应 DTO
```
### 2.1 依赖关系
```
Host → Adapters.Kms → Core
Host → Core
```
适配器只引用 Core，零外部 NuGet 依赖。
---
## 3. 数据模型设计
### 3.1 KMS 响应模型（全部 9 个第三方接口的 DTO）
```csharp
// ── 认证 ──
public class KmsTokenResponse { public int Code { get; set; } public string Token { get; set; } = ""; public string? Msg { get; set; } }
// ── 2.18.4 柜体+钥匙 ──
public class KmsOpenerListResponse { public int Code { get; set; } public string? Msg { get; set; } public List<KmsLocker>? Rows { get; set; } }
public class KmsLocker { public int LockerId { get; set; } public string? LockerName { get; set; } public string? LockerCode { get; set; } public List<KmsLockhole>? LockholeList { get; set; } }
public class KmsLockhole { public int LockholeSort { get; set; } public int OpenerId { get; set; } public string? OpenerName { get; set; } public string? OpenerType { get; set; } public string? OpenerState { get; set; } }
// ── 2.18.7 告警 ──
public class KmsWarningListResponse { public int Code { get; set; } public string? Msg { get; set; } public int Total { get; set; } public List<KmsWarning>? Rows { get; set; } }
public class KmsWarning { public string? Uuid { get; set; } public string? LockerName { get; set; } public int LockholeSort { get; set; } public string? OpenerName { get; set; } public int Type { get; set; } public string? WarningTime { get; set; } public string? Remark { get; set; } public string? StaffName { get; set; } }
// ── 2.18.6 借还记录 ──
public class KmsRecordListResponse { public int Code { get; set; } public string? Msg { get; set; } public int Total { get; set; } public List<KmsRecord>? Rows { get; set; } }
public class KmsRecord { public string? Uuid { get; set; } public string? LockerName { get; set; } public int LockholeSort { get; set; } public string? OpenerName { get; set; } public string? StaffName { get; set; } public string? BorrowTime { get; set; } public string? ReturnTime { get; set; } public string? Type { get; set; } }
// ── 2.18.5 授权记录 ──
public class KmsPermissionListResponse { public int Code { get; set; } public string? Msg { get; set; } public int Total { get; set; } public List<KmsPermission>? Rows { get; set; } }
public class KmsPermission { public string? Uuid { get; set; } public string? LockerName { get; set; } public int LockholeSort { get; set; } public string? OpenerName { get; set; } public string? StaffName { get; set; } public string? ApplyTime { get; set; } public string? BackTime { get; set; } }
// ── 2.18.3 员工同步 ──
public class KmsStaff { public string? Uuid { get; set; } public string? Name { get; set; } public string? CardNo { get; set; } public string? Phone { get; set; } public string? Email { get; set; } public int? DeptId { get; set; } public int? GroupId { get; set; } public int State { get; set; } public int Type { get; set; } }
// ── 通用响应 ──
public class KmsApiResponse { public int Code { get; set; } public string? Msg { get; set; } }
```
### 3.2 实体映射关系
```
KMS 物理拓扑 base_device 映射
─────── ──────────────────
智能钥匙柜A (lockerId=25) SourceId="locker_25", IsParent=是
├── 锁孔1 "仓库大门" SourceId="lockhole_25_1", ParentSourceId="locker_25"
├── 锁孔2 "机房钥匙" SourceId="lockhole_25_2", ParentSourceId="locker_25"
└── 锁孔N ...
```
---
## 4. KmsAuthHelper 设计
```csharp
/// <summary>
/// KMS Bearer Token 认证辅助。
/// Token 通过 POST /prod-api/getToken 获取，参数 clientId + clientSecret。
/// 缓存 25 分钟（KMS 有效期 30 分钟，留 5 分钟余量）。
/// </summary>
public class KmsAuthHelper
{
private readonly HttpClient _http;
private readonly string _baseUrl, _clientId, _clientSecret;
private string? _token;
private DateTime _tokenExpiry = DateTime.MinValue;
public KmsAuthHelper(HttpClient http, string baseUrl, string clientId, string clientSecret)
{
_http = http; _baseUrl = baseUrl.TrimEnd('/');
_clientId = clientId; _clientSecret = clientSecret;
}
/// <summary>获取或刷新 Token（自动缓存）</summary>
public async Task<string> GetTokenAsync()
{
if (!string.IsNullOrEmpty(_token) && DateTime.UtcNow < _tokenExpiry) return _token;
var resp = await _http.PostAsync(
$"{_baseUrl}/prod-api/getToken?clientId={Uri.EscapeDataString(_clientId)}&clientSecret={Uri.EscapeDataString(_clientSecret)}", null);
resp.EnsureSuccessStatusCode();
var result = await resp.Content.ReadFromJsonAsync<KmsTokenResponse>()
?? throw new Exception("KMS Token 响应为空");
if (result.Code != 200) throw new Exception($"KMS 认证失败: code={result.Code}");
_token = result.Token; _tokenExpiry = DateTime.UtcNow.AddMinutes(25);
return _token;
}
/// <summary>创建一个已认证的 HttpClient</summary>
public async Task<HttpClient> GetAuthenticatedClientAsync()
{
var token = await GetTokenAsync();
var client = new HttpClient { BaseAddress = new Uri(_baseUrl) };
client.DefaultRequestHeaders.Add("Authorization", $"Bearer {token}");
return client;
}
public void Invalidate() => _token = null;
}
```
---
## 5. KmsAdapter 设计
### 5.1 类声明与核心属性
```csharp
/// <summary>
/// KMS 智能钥匙柜适配器。
/// 实现 IHasFlatDevices + IHasAlarms。
/// 通过 8 个第三方接口（2.18.X）对接 KMS 子系统。
/// AdapterCode: "KMS:{InstanceName}"，限流: 5 QPS。
/// </summary>
public class KmsAdapter : IHasFlatDevices, IHasAlarms
{
private readonly HttpClient _http;
private readonly KmsAuthHelper _auth;
private readonly RateLimiter _limiter = new(5);
public string AdapterCode { get; }
public string DisplayName => $"KMS ({AdapterCode})";
public AdapterCapabilities Capabilities => new() { HasFlatDevices = true, HasAlarms = true };
public KmsAdapter(string adapterCode, HttpClient http, string baseUrl, string clientId, string clientSecret)
{
AdapterCode = adapterCode; _http = http;
_auth = new KmsAuthHelper(http, baseUrl, clientId, clientSecret);
}
public async Task InitializeAsync() => await _auth.GetTokenAsync();
```
### 5.2 IGatewayAdapter — 健康检查
```csharp
/// <summary>2.18.1: 心跳检测 — GET /prod-api/heartBeat</summary>
public async Task<bool> HealthCheckAsync()
{
try
{
var client = await _auth.GetAuthenticatedClientAsync();
var resp = await client.GetAsync("/prod-api/heartBeat");
return resp.IsSuccessStatusCode;
}
catch { return false; }
}
```
### 5.3 IHasFlatDevices — 设备同步
```csharp
/// <summary>2.18.4: 柜体+钥匙信息 — POST /prod-api/getOpenerList</summary>
public async Task<PagedResult<StandardDevice>> GetDevicesAsync(int page, int size, string? keyword = null)
{
await _limiter.WaitAsync();
var client = await _auth.GetAuthenticatedClientAsync();
var resp = await client.PostAsync("/prod-api/getOpenerList",
new StringContent("{}", Encoding.UTF8, "application/json"));
resp.EnsureSuccessStatusCode();
var data = await resp.Content.ReadFromJsonAsync<KmsOpenerListResponse>()!;
var devices = new List<StandardDevice>();
foreach (var locker in data.Rows ?? new())
{
// 父设备: 柜体
devices.Add(new StandardDevice
{
SourceId = $"locker_{locker.LockerId}", Name = locker.LockerName ?? $"柜体{locker.LockerId}",
Category = "智能钥匙柜", Group = "门禁设备", IsParent = true, IsOnline = true,
Extra = new() { ["lockerCode"] = locker.LockerCode, ["lockholeCount"] = locker.LockholeList?.Count ?? 0 }
});
// 子设备: 锁孔（钥匙位）
foreach (var hole in locker.LockholeList ?? new())
{
devices.Add(new StandardDevice
{
SourceId = $"lockhole_{locker.LockerId}_{hole.LockholeSort}",
Name = hole.OpenerName ?? $"锁孔{hole.LockholeSort}",
Category = "钥匙位", Group = "门禁设备", IsParent = false,
IsOnline = hole.OpenerState == "在位", ParentSourceId = $"locker_{locker.LockerId}",
Extra = new() { ["openerId"] = hole.OpenerId, ["openerType"] = hole.OpenerType, ["openerState"] = hole.OpenerState }
});
}
}
return new PagedResult<StandardDevice> { Items = devices, Total = devices.Count };
}
```
### 5.4 IHasAlarms — 告警同步
```csharp
/// <summary>2.18.7: 告警记录 — POST /prod-api/getWarningList</summary>
public async Task<PagedResult<StandardAlarm>> GetAlarmsAsync(...)
{
await _limiter.WaitAsync();
var client = await _auth.GetAuthenticatedClientAsync();
var resp = await client.PostAsync("/prod-api/getWarningList",
new StringContent("{}", Encoding.UTF8, "application/json"));
resp.EnsureSuccessStatusCode();
var data = await resp.Content.ReadFromJsonAsync<KmsWarningListResponse>()!;
var alarms = (data.Rows ?? new()).Select(w => new StandardAlarm
{
AlarmId = w.Uuid ?? "", AdapterCode = AdapterCode, Level = "普通",
Title = $"{w.LockerName} 锁孔{w.LockholeSort}: {w.OpenerName}",
Content = w.Remark, OccurTime = DateTime.TryParse(w.WarningTime, out var t) ? t : DateTime.MinValue,
Status = w.Type == 1 ? "未确认" : "已结束"
}).ToList();
return new PagedResult<StandardAlarm> { Items = alarms, Total = data.Total };
}
```
### 5.5 扩展方法（非接口方法，供 B 组路由直接调用）
```csharp
// 2.18.6 借还记录
public async Task<PagedResult<KmsRecord>> GetBorrowRecordsAsync(DateTime? from = null, DateTime? to = null) { ... }
// 2.18.5 授权记录
public async Task<PagedResult<KmsPermission>> GetPermissionListAsync(DateTime? from = null, DateTime? to = null) { ... }
// 2.18.3 批量同步员工
public async Task BatchSyncStaffAsync(List<KmsStaff> staffList) { ... }
// 2.18.2 批量删除员工
public async Task BatchDeleteStaffAsync(List<string> staffUuids) { ... }
// 2.4.3 远程授权开门
public async Task RemoteAuthorizeAsync(KmsRemotePermissionRequest request) { ... }
// 2.18.8 第三方登录代理
public async Task<string?> ThirdPlatLoginAsync(string username) { ... }
```
---
## 6. 配置
### 6.1 KmsConfig POCO
```csharp
public class KmsConfig
{
public string? InstanceName { get; set; }
public string BaseUrl { get; set; } = "";
public string ClientId { get; set; } = "";
public string ClientSecret { get; set; } = "";
}
```
### 6.2 appsettings.json
```json
{
"KMS": [
{
"InstanceName": "main",
"BaseUrl": "http://192.168.1.50:8080",
"ClientId": "your_client_id",
"ClientSecret": "your_client_secret"
}
]
}
```
### 6.3 Program.cs 注册
```csharp
var kmsList = app.Configuration.GetSection("KMS").Get<List<KmsConfig>>() ?? new();
foreach (var k in kmsList)
{
var code = $"KMS:{k.InstanceName ?? "default"}";
var a = new KmsAdapter(code,
app.Services.GetRequiredService<IHttpClientFactory>().CreateClient("VolPro"),
k.BaseUrl, k.ClientId, k.ClientSecret);
registry.Register(a);
}
```
---
## 7. Vol.Pro 端配套
| 项 | 改动 | 说明 |
|------|:---:|------|
| 数据库 | 无 | base_device / iot_alarm 已兼容 |
| 后端 | 无 | A1-A4 同步逻辑通用 |
| 字典 | 新增 2 项 | "智能钥匙柜" / "钥匙位" |
| 前端列表 | 无 | 自动显示 KMS 设备 |
| 前端操作 | Phase 2 | KeyDeviceActions.vue（开门/授权按钮）|
---
> **接口覆盖**: 9 个第三方接口（2.18.X + Token）100% 设计覆盖；29 个标准管理接口留 Phase 2 按需扩展。

183
doc/设计文档/KMS钥匙柜适配器详细设计文档_任务清单.md
View File

@@ -1,183 +0,0 @@
# KMS 钥匙柜适配器 — 任务清单
> **基准文档**: `doc/设计文档/KMS钥匙柜适配器详细设计文档.md`
> **分支**: gateway-dev
> **原则**: 严格按照设计文档执行，不凭空添加。网关/Vol.Pro 改动放倒数第二步，联调放最后。
---
## Phase K0: 项目骨架（预计 15min）
### K0.1 创建适配器项目
- [ ] 在 `gateway/src/` 下执行 `dotnet new classlib -n IntegrationGateway.Adapters.Kms -f net8.0`
- [ ] 删除自动生成的 `Class1.cs`
- [ ] 添加项目引用：`dotnet add reference ../IntegrationGateway.Core/IntegrationGateway.Core.csproj`
- [ ] 将项目加入解决方案：`dotnet sln add`
### K0.2 Host 引用适配器
- [ ] `dotnet add Host reference Adapters.Kms`
### K0.3 编译验证
- [ ] `dotnet build` → 0 错误
> **K0 提交点**: `PhaseK0_scaffold — Kms适配器项目骨架就绪`
---
## Phase K1: KmsModels — 数据模型（预计 1h）
### K1.1 认证模型
- [ ] 创建 `KmsModels.cs`
- [ ] `KmsTokenResponse { Code, Token, Msg }`
### K1.2 第三方接口响应模型（2.18.X）
- [ ] `KmsOpenerListResponse { Code, Msg, Rows }`
- [ ] `KmsLocker { LockerId, LockerName, LockerCode, LockholeList }`
- [ ] `KmsLockhole { LockholeSort, OpenerId, OpenerName, OpenerType, OpenerState }`
- [ ] `KmsWarningListResponse { Code, Msg, Total, Rows }`
- [ ] `KmsWarning { Uuid, LockerName, LockholeSort, OpenerName, Type, WarningTime, Remark, StaffName }`
- [ ] `KmsRecordListResponse { Code, Msg, Total, Rows }`
- [ ] `KmsRecord { Uuid, LockerName, LockholeSort, OpenerName, StaffName, BorrowTime, ReturnTime, Type }`
### K1.3 编译验证
- [ ] `dotnet build` → 0 错误
> **K1 提交点**: `PhaseK1_models — KmsModels.cs 完整定义全部响应 DTO`
---
## Phase K2: KmsAuthHelper — 认证（预计 30min）
### K2.1 创建 KmsAuthHelper.cs
- [ ] 构造函数：接收 `HttpClient`, `baseUrl`, `clientId`, `clientSecret`
- [ ] 属性：`_token` (string?), `_tokenExpiry` (DateTime)
### K2.2 GetTokenAsync
- [ ] POST `/prod-api/getToken?clientId=xx&clientSecret=yy`
- [ ] 校验 `Code == 200`
- [ ] 缓存 Token，过期时间 = `UtcNow.AddMinutes(25)`（30 分钟效期，5 分钟余量）
### K2.3 GetAuthenticatedClientAsync
- [ ] 创建 `HttpClient`，设置 `Authorization: Bearer {token}`
- [ ] Invalidate() → `_token = null`
### K2.4 编译验证
- [ ] `dotnet build` → 0 错误
> **K2 提交点**: `PhaseK2_auth — Bearer Token 认证就绪`
---
## Phase K3: KmsAdapter 核心方法（预计 1.5h）
### K3.1 类定义
- [ ] `public class KmsAdapter : IHasFlatDevices, IHasAlarms`
- [ ] 属性：`AdapterCode`, `DisplayName`, `Capabilities`
### K3.2 HealthCheckAsync（2.18.1）
- [ ] GET `/prod-api/heartBeat`
- [ ] 异常捕获返回 false + Console.Error 打日志
### K3.3 GetDevicesAsync（2.18.4）
- [ ] POST `/prod-api/getOpenerList` (body `{}`)
- [ ] 遍历柜体/锁孔 → 映射为 StandardDevice
- [ ] 父设备 `IsParent=是`, 子设备 `ParentSourceId=locker_{id}`
### K3.4 GetAlarmsAsync（2.18.7）
- [ ] POST `/prod-api/getWarningList`
- [ ] 映射 KmsWarning → StandardAlarm
- [ ] AlarmId=uuid, Status=Type==1?"未确认":"已结束"
### K3.5 ConfirmAlarmAsync / EndAlarmAsync
- [ ] Confirm 调标准接口；End 留空实现
### K3.6 编译验证
- [ ] `dotnet build` → 0 错误
> **K3 提交点**: `PhaseK3_adapter_core — 核心4方法就绪`
---
## Phase K4: 扩展方法（预计 1h）
### K4.1 借还/授权/员工/登录
- [ ] GetBorrowRecordsAsync（2.18.6）
- [ ] GetPermissionListAsync（2.18.5）
- [ ] BatchSyncStaffAsync（2.18.3）
- [ ] BatchDeleteStaffAsync（2.18.2）
- [ ] RemoteAuthorizeAsync（2.4.3）
- [ ] ThirdPlatLoginAsync（2.18.8）
### K4.2 编译验证
- [ ] `dotnet build` → 0 错误
> **K4 提交点**: `PhaseK4_adapter_ext — 6个扩展方法就绪`
---
## Phase K5: 配置与注册（预计 15min）
### K5.1 KmsConfig POCO
- [ ] 在 Program.cs 同级加 class，属性：`InstanceName, BaseUrl, ClientId, ClientSecret`
### K5.2 appsettings.json
- [ ] 新增 KMS 数组配置段
### K5.3 Program.cs 注册
- [ ] `var kmsList = app.Configuration.GetSection("KMS").Get<List<KmsConfig>>() ?? new();`
- [ ] foreach 注册 `KmsAdapter("KMS:{InstanceName}", ...)`
> **K5 提交点**: `PhaseK5_config — 配置+注册就绪`
---
## Phase K6: 编译与自测（预计 15min）
### K6.1 编译验证
- [ ] `dotnet build` → 0 错误
> **K6 提交点**: `PhaseK6_build — 全量编译通过`
---
## Phase K7: Vol.Pro 端配套（预计 1h）
### K7.1 字典
- [ ] 管理端设备种类字典 ← "智能钥匙柜" + "钥匙位"
### K7.2 前端按钮
- [ ] `base_device.vue` 操作列：门禁设备 → [开门] [授权] 按钮
> **K7 提交点**: `PhaseK7_volpro — 字典+前端就绪`
---
## Phase K8: 联调验证（预计 3h，需 KMS 环境）
### K8.1 认证
- [ ] 网关启动 → KmsAdapter.InitializeAsync 成功
### K8.2 设备/告警/记录
- [ ] /api/gateway/devices?adapter=KMS:main → 返回柜体+锁孔
- [ ] /api/gateway/alarms/KMS:main → 返回告警列表
- [ ] /api/gateway/control/KMS:main → 远程开门
### K9: 联调文档记录
- [ ] 记录异常接口到 KMS_联调笔记.txt
> **K8 提交点**: `PhaseK8_integration — 全链路联调通过`
---
| Phase | 内容 | 文件 | 预计 |
|:---:|------|:---:|:---:|
| K0 | 项目骨架 | 2 | 15min |
| K1 | 全部 DTO | 1 | 1h |
| K2 | AuthHelper | 1 | 30min |
| K3 | 核心方法 | 1 | 1.5h |
| K4 | 扩展方法 | 1 | 1h |
| K5 | 配置注册 | 3 | 15min |
| K6 | 编译 | — | 15min |
| K7 | VolPro配套 | 2 | 1h |
| K8 | 联调 | — | 3h |
| **合计** | — | **11** | **~9h** |

19
doc/设计文档/Quartz_Job注册说明.txt
View File

@@ -1,19 +0,0 @@
Phase V3.6: Quartz Job 注册说明
═══════════════════════════════
以下 3 个 Job 需在 Vol.Pro 管理端 → Quartz 任务管理 中手动创建：
1. SyncDevicesJob
- 类名: VolPro.Warehouse.Services.SyncDevicesJob
- Cron: 0 */5 * * * ? (每5分钟)
- 说明: 遍历在线网关触发全量设备同步
2. HeartbeatMonitorJob
- 类名: VolPro.Warehouse.Services.HeartbeatMonitorJob
- Cron: 0/15 * * * * ? (每15秒)
- 说明: 检测心跳超时标记离线
3. RealtimePollJob (Phase 2 启用)
- 类名: VolPro.Warehouse.Services.RealtimePollJob
- Cron: 0/10 * * * * ? (每10秒)
- 说明: 轮询MC4.0实时值写iot_devicedata

56
doc/设计文档/SecMPS统一问题清单20260603.md
View File

@@ -1,56 +0,0 @@
# SecMPS 统一问题清单 2026-06-03
> **版本**: 1.0
> **日期**: 2026-06-03
> **范围**: gateway / VolPro (api_sqlsugar) / web.vite / warehouse / owl_zlmediakit
> **来源**: 项目深度审计 + 规则引擎方案审查
---
## P0 — 阻塞性（影响功能完整性，必须修复）
| 编号 | 类别 | 问题 | 影响 | 方案 |
|:---:|:---:|------|------|------|
| P0-1 | 规则引擎 | RealtimePollJob 空壳 — IoT 实时值从未持久化，规则引擎无历史数据源 | 规则无法追溯历史趋势 | 在此 Job 实现轮询→写入 iot_devicedata，或合并到 RuleEngineJob |
| P0-2 | 网关 | A1 自注册未调用 — `GatewayClientFactory.RegisterAsync` 已定义但 Program.cs 从未执行 | 网关启动后不向 Vol.Pro 注册 | `InitializeAllAsync()` 后遍历适配器调 A1 |
| P0-3 | 安全 | B 组路由零认证 — 14+ 条路由无任何认证 | 内网未授权客户端可操控设备、查视频流 | 生产环境绑定 `127.0.0.1`，或加 `X-Gateway-Key` 中间件 |
---
## P1 — 重要（影响性能、安全、可靠性）
| 编号 | 类别 | 问题 | 影响 | 方案 |
|:---:|:---:|------|------|------|
| P1-1 | 性能 | 逐设备 B4 调用 — 规则引擎按设备逐个调 B4 | 规则引擎 90% 时间耗在网络往返 | 新增 `POST /realtime/{adapter}/batch` 批量接口 |
| P1-2 | 性能 | 级联离线标记逐条 UPDATE — HeartbeatMonitorJob 对每台设备单独更新 | 设备多时慢且无事务 | 一条 SQL: `UPDATE base_device SET IsOnline='离线' WHERE GatewayNodeId=@id` |
| P1-3 | 安全 | Token/密码明文存储 — appsettings.json 明文且被复制到 bin/ | 源码泄露 = 凭据泄露 | 环境变量覆盖 + `.gitignore bin` |
| P1-4 | 可维护 | 前端硬编码网关地址 — `const GW = 'http://localhost:5100'` | 部署时需逐文件修改 | 统一用 `window.apiConfig.gatewayUrl` |
| P1-5 | 规则引擎 | DeviceId→(AdapterCode, SourceId) 解析缺失 | 规则引擎无法直接调网关 B4 | 批量查 base_device 建映射表 |
| P1-6 | 规则引擎 | ValueId 语义模糊 — 字典绑定但无对应实体表 | "变量"选的是什么不明确 | 新建 `warehouse_variable` 表 |
---
## P2 — 改善（影响排错效率、维护成本）
| 编号 | 类别 | 问题 | 影响 | 方案 |
|:---:|:---:|------|------|------|
| P2-1 | 代码质量 | 静默异常吞噬 — 适配器 `catch { return false; }` | 离线不知道原因 | `catch(Exception ex)` + STDERR 输出 |
| P2-2 | 规则引擎 | 阈值抖动 — 温度反复跳变时规则频繁触发→恢复 | 空调反复开关，告警洪水 | hysteresis 滞后窗 |
| P2-3 | 规则引擎 | 冷却期粒度 — Cooldown 在规则级，OR 组合不该整体冷却 | 冷却期过宽 | 冷却期下沉到条件表或基于"上次触发值"去重 |
| P2-4 | 可维护 | warehouse 端 console.log 残留 — 30+ 处开发日志 | 生产环境噪声 | vite.config.ts 移除非生产日志 |
| P2-5 | 可维护 | 双端 gateway API 重复封装 | 维护两份 | 统一到 web.vite/src/api/gateway.js |
---
## P3 — 优化（影响开发体验、仓库整洁）
| 编号 | 类别 | 问题 | 影响 | 方案 |
|:---:|:---:|------|------|------|
| P3-1 | 规则引擎 | 动作执行阻塞 — `ExecuteActionsAsync` 串行等待 B5 响应 | 一条规则卡住全部阻塞 | `Task.WhenAll` + 5s 超时 |
| P3-2 | 文档 | bin 目录残留配置 | 仓库体积 + 凭据泄露 | `.gitignore` 加 `**/bin/` |
| P3-3 | 开发 | 网关无 Swagger | 调试需手动 curl | `AddEndpointsApiExplorer` + `MapSwagger` |
| P3-4 | 文档 | 设计文档与代码路由数不一致 | 架构文档过时 | 每次 Phase 同步更新 |
---
> **总计**: 18 项 — P0: 3 / P1: 6 / P2: 5 / P3: 4

280
doc/设计文档/SecMPS统一问题清单20260603修复方案.md
View File

@@ -1,280 +0,0 @@
# SecMPS 统一问题清单 2026-06-03 修复方案
> **版本**: 1.0
> **日期**: 2026-06-03
> **基准**: `SecMPS统一问题清单20260603.md`
> **原则**: 按优先级逐项修复，每项修复后编译验证；涉及网关/Vol.Pro 改动的放一组批量提交
---
## 修复总览
| 阶段 | 优先级 | 涉及项目 | 文件数 | 预计 |
|:---:|:---:|------|:---:|:---:|
| F1 | P0-1 ~ P0-3 | gateway + Vol.Pro | 5 | 2h |
| F2 | P1-1 ~ P1-6 | gateway + Vol.Pro + 库表 + 前端 | 8 | 4h |
| F3 | P2-1 ~ P2-5 | gateway + warehouse | 8 | 2h |
| F4 | P3-1 ~ P3-4 | gateway + 文档 | 4 | 1h |
| **合计** | — | 4 项目 | **25** | **~9h** |
---
## 阶段 F1: P0 阻塞项修复（预计 2h）
#### F1.1 [P0-1] RealtimePollJob 填充实现
- [ ] 编辑 `api_sqlsugar/Warehouse/Services/RealtimePollJob.cs`
- [ ] 注入 `GatewayClient` + `Ibase_deviceRepository`
- [ ] `Execute()` 中:
1. 查询在线 MC4 网关 (`gateway_nodes WHERE IsOnline=在线 AND AdapterTypes LIKE '%MC4%'`)
2. 查对应设备列表 (`base_device WHERE DeviceGroup='IoT设备' AND IsOnline=在线`)
3. 对每个设备调 `GatewayClient.GetRealtimeAsync(gwBaseUrl, adapterCode, sourceId)`
4. 结果写入 `iot_devicedata` 表（INSERT 新记录）
- [ ] `dotnet build` → 0 错误
#### F1.2 [P0-2] 网关 A1 自注册
- [ ] 编辑 `gateway/src/IntegrationGateway.Host/Program.cs`
- [ ] 在 `registry.InitializeAllAsync()` 后加入:
```csharp
var nodeCode = gwCfg["NodeCode"] ?? "gw-default";
var nodeToken = gwCfg["NodeToken"] ?? "";
var adapterTypes = string.Join(",", registry.All.Select(a => a.AdapterCode));
await clientFactory.RegisterAsync(nodeCode, nodeToken, adapterTypes, volProUrl);
```
- [ ] `dotnet build` → 0 错误
#### F1.3 [P0-3] B 组路由认证
- [ ] 编辑 `gateway/src/IntegrationGateway.Host/Program.cs`
- [ ] 在 `app.UseCors()` 之后添加中间件:
```csharp
var gatewayKey = gwCfg["GatewayKey"];
if (!string.IsNullOrEmpty(gatewayKey))
{
app.Use(async (context, next) => {
var key = context.Request.Headers["X-Gateway-Key"].FirstOrDefault();
if (key == gatewayKey || context.Request.Path == "/") { await next(); }
else { context.Response.StatusCode = 401; }
});
}
```
- [ ] appsettings.json Gateway 段新增 `"GatewayKey": null`
- [ ] Vol.Pro 端 `GatewayClient` 所有 HTTP 请求头自动附加 `X-Gateway-Key`
- [ ] `dotnet build` → 0 错误
> **F1 提交点**: `Fix-P0: RealtimePollJob+A1自注册+B组认证`
---
## 阶段 F2: P1 重要项修复（预计 4h）
#### F2.1 [P1-1] 网关新增批量实时值接口
- [ ] 编辑 `gateway/src/IntegrationGateway.Host/Program.cs`
- [ ] 新增 B4-batch 路由:
```csharp
app.MapPost("/api/gateway/realtime/{adapter}/batch", async (string adapter, BatchRealtimeRequest req) =>
{
var a = registry.FindByCode<IHasPoints>(adapter);
if (a == null) return Results.NotFound();
var results = new Dictionary<string, List<PointValue>>();
foreach (var deviceId in req.DeviceIds ?? new())
results[deviceId] = await a.GetRealtimeValuesAsync(deviceId);
return Results.Ok(results);
});
```
- [ ] 新增 `record BatchRealtimeRequest(List<string>? DeviceIds);`
- [ ] `dotnet build` → 0 错误
#### F2.2 [P1-2] 批量级联离线标记
- [ ] 编辑 `api_sqlsugar/Warehouse/Services/HeartbeatMonitorJob.cs`
- [ ] 替换逐条 `UpdateAsync` 为:
```csharp
context.Repository.DbContext.Db.Ado.ExecuteCommand(
"UPDATE base_device SET IsOnline='离线' WHERE GatewayNodeId=@id AND IsOnline='在线'",
new { id = node.GatewayNodeId });
```
- [ ] `dotnet build` → 0 错误
#### F2.3 [P1-3] 凭据安全化
- [ ] 编辑 `gateway/src/IntegrationGateway.Host/appsettings.json`
- `NodeToken` → `null`, 加注释 "生产环境由 SECMPS_GATEWAY_TOKEN 环境变量注入"
- Owl `Password` → `""`, 加注释
- KMS `ClientSecret` → `""`, 加注释
- [ ] 编辑 `gateway/src/IntegrationGateway.Host/Program.cs`
- `gwCfg["NodeToken"]` → `Environment.GetEnvironmentVariable("SECMPS_GATEWAY_TOKEN") ?? gwCfg["NodeToken"]`
- [ ] 编辑 `.gitignore` → 加 `**/bin/`、`**/obj/`
- [ ] `git rm -r --cached gateway/src/IntegrationGateway.Host/bin/`
#### F2.4 [P1-4] 前端网关地址统一化
- [ ] 编辑 `web.vite/public/index.html` 的 `window.apiConfig` → 加 `gatewayUrl: 'http://localhost:5100'`
- [ ] 编辑 `web.vite/src/views/warehouse/device_manager/base_device.vue`
- `const GW = 'http://localhost:5100'` → `const GW = window.apiConfig.gatewayUrl || 'http://localhost:5100'`
- [ ] 编辑 `warehouse/src/api/gateway.ts`
- `const GW_BASE = 'http://localhost:5100'` → 读取 `window.apiConfig.gatewayUrl`
- [ ] 编辑 `warehouse/index.html` 的 `window.apiConfig` → 加 `gatewayUrl`
#### F2.5 [P1-5] 规则引擎增加 DeviceId 映射
- [ ] 在规则引擎实现方案中增加 `BuildDeviceMappingAsync` 方法:
```csharp
var deviceIds = rules.SelectMany(r => r.Conditions).Select(c => c.DeviceId).Distinct();
var devices = await _deviceRepo.FindAsync(d => deviceIds.Contains(d.DeviceId));
var map = devices.ToDictionary(d => d.DeviceId, d => (d.AdapterCode, d.SourceId));
```
- [ ] 后续调网关时用 `map[cond.DeviceId]` 拼装 URL
#### F2.6 [P1-6] 新建 warehouse_variable 表
- [ ] 执行 SQL:
```sql
CREATE TABLE warehouse_variable (
VariableId INT IDENTITY PRIMARY KEY,
DeviceId INT NOT NULL,
VariableName NVARCHAR(255), -- 温度/湿度/人数
PointIndex INT DEFAULT 0, -- MC4 pointIndex
Unit NVARCHAR(50), -- ℃/%/人
SortOrder INT DEFAULT 0
);
```
- [ ] 在 Vol.Pro 代码生成器选择 `warehouse_variable`，生成全套 CRUD 代码
- [ ] 管理端字典 "变量列表" 绑定到 `warehouse_variable.VariableName`
- [ ] 规则条件/动作的 `ValueId` 下拉框改为从 `warehouse_variable` 查询（JOIN `base_device.DeviceId`）
> **F2 提交点**: `Fix-P1: B4-batch+批量离线+凭据安全+前端地址+DeviceId映射+变量表`
---
## 阶段 F3: P2 改善项修复（预计 2h）
#### F3.1 [P2-1] 适配器异常日志
- [ ] 编辑 `gateway/src/IntegrationGateway.Adapters.Owl/OwlAdapter.cs`
- [ ] 编辑 `gateway/src/IntegrationGateway.Adapters.MC4/Mc4Adapter.cs`
- [ ] 编辑 `gateway/src/IntegrationGateway.Adapters.Kms/KmsAdapter.cs`
- [ ] 所有 `catch { return false; }` → `catch (Exception ex) { Console.Error.WriteLine($"[{AdapterCode}] HealthCheck: {ex.Message}"); return false; }`
- [ ] `dotnet build` → 0 错误
#### F3.2 [P2-2] 规则引擎滞后窗
- [ ] 在 `warehouse_rulecondition` 表新增字段:
```sql
ALTER TABLE warehouse_rulecondition ADD
RecoveryThreshold_Numeric DECIMAL(18,2) NULL, -- 恢复阈值(下界)
RecoveryThreshold_Switch NVARCHAR(50) NULL; -- 恢复开关状态
```
- [ ] `RuleEngineService.EvaluateCondition` 中加逻辑:
```csharp
bool wasTriggered = cond.LastTriggered.HasValue;
if (wasTriggered)
return Compare(actualValue, "大于等于", cond.RecoveryThreshold_Numeric);
else
return Compare(actualValue, cond.CompareOperator, cond.TargetValue_Number);
```
#### F3.3 [P2-3] 条件级冷却
- [ ] `warehouse_rulecondition` 表新增 `LastTriggered DATETIME NULL`、`LastTriggerValue DECIMAL(18,2) NULL`
- [ ] `RuleEngineService.EvaluateCondition` 中:
- 如果 `DateTime.Now - cond.LastTriggered < rule.CooldownSec` → 跳过此条件
- 触发时更新 `LastTriggered` 和 `LastTriggerValue`
#### F3.4 [P2-4] 生产环境移除 console.log
- [ ] 编辑 `warehouse/vite.config.ts`
```typescript
build: {
terserOptions: { compress: { drop_console: true } }
}
```
- [ ] 开发环境保留 `console.log`（仅 build 时移除）
- [ ] `npm run build` → 确认无 console.log 残留
#### F3.5 [P2-5] 统一 gateway API 封装
- [ ] 复制 `warehouse/src/api/gateway.ts` → `web.vite/src/api/gateway.js`
- 修改 `GW_BASE` 为 `window.apiConfig.gatewayUrl || 'http://localhost:5100'`
- [ ] `web.vite/src/views/warehouse/device_manager/base_device.vue`
- 删除内联 `const GW =` + `fetch()` → 改为 `import { gwGet, gwPost } from '@/api/gateway.js'`
- 所有 `fetch(\`\${GW}/api/gateway/...\`)` → `gwGet(...)` / `gwPost(...)`
> **F3 提交点**: `Fix-P2: 异常日志+滞后窗+条件冷却+console清理+API统一`
---
## 阶段 F4: P3 优化项（预计 1h）
#### F4.1 [P3-1] 规则引擎并发动作执行
- [ ] 在规则引擎实现方案的 `ExecuteActionsAsync` 中:
```csharp
var tasks = actions.Select(a => ExecuteSingleActionAsync(a, rule));
await Task.WhenAll(tasks);
async Task ExecuteSingleActionAsync(Action a, Rule r) {
using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));
try { await DoAction(a, r, cts.Token); }
catch (OperationCanceledException) { Log($"[RuleEngine] 动作超时: {a.id}"); }
}
```
#### F4.2 [P3-2] 清理 bin/obj + .gitignore
- [ ] `.gitignore` 追加规则（如未在 F2.3 中完成）:
```
**/bin/
**/obj/
gateway/src/IntegrationGateway.Host/bin/
api_sqlsugar/**/bin/
```
- [ ] `git rm -r --cached` 所有 bin/obj 目录
#### F4.3 [P3-3] 网关 Swagger
- [ ] 编辑 `gateway/src/IntegrationGateway.Host/Program.cs`:
```csharp
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
// ...
app.UseSwagger();
app.UseSwaggerUI();
```
- [ ] 浏览器访问 `http://localhost:5100/swagger` 验证
#### F4.4 [P3-4] 同步设计文档路由数
- [ ] 编辑 `doc/设计文档/对接网关设计文档.md` → 路由表从 14 条更新为当前实际数
- [ ] 确认以下设计文档一致: 对接网关设计文档、规则引擎方案、KMS 设计文档
> **F4 提交点**: `Fix-P3: 并发动作+清理bin+Swagger+文档同步`
---
## 任务总览
| 编号 | 问题 | 涉及文件 | 预计 |
|:---:|------|------|:---:|
| P0-1 | RealtimePollJob 空壳 | RealtimePollJob.cs | 1h |
| P0-2 | A1 自注册 | Program.cs | 30min |
| P0-3 | B 组认证 | Program.cs + appsettings | 30min |
| P1-1 | B4-batch | Program.cs | 30min |
| P1-2 | 批量离线 | HeartbeatMonitorJob.cs | 20min |
| P1-3 | 凭据安全 | appsettings + .gitignore + bin | 20min |
| P1-4 | 前端地址 | base_device.vue + gateway.ts | 20min |
| P1-5 | DeviceId 映射 | RuleEngineService | 30min |
| P1-6 | 变量表 | SQL + 代码生成 + 前端 | 1h |
| P2-1 | 异常日志 | OwlAdapter + MC4Adapter + KmsAdapter | 20min |
| P2-2 | 滞后窗 | SQL + RuleEngineService | 30min |
| P2-3 | 条件冷却 | SQL + RuleEngineService | 20min |
| P2-4 | console 清理 | vite.config.ts | 10min |
| P2-5 | API 统一 | gateway.js + base_device.vue | 30min |
| P3-1 | 并发动作 | RuleEngineService | 15min |
| P3-2 | bin 清理 | .gitignore + git rm | 5min |
| P3-3 | Swagger | Program.cs | 10min |
| P3-4 | 文档同步 | 设计文档 | 15min |
> **总计**: 18 项 / 25 文件 / ~9h

512
doc/设计文档/VolPro框架改造方案.md
View File

@@ -1,512 +0,0 @@
# Vol.Pro 框架前后端改造方案
> **版本**: 1.0
> **日期**: 2025-05-17
> **基准**: SecMPS 整合方案 v3.1 + Vol.Pro 框架官方文档
> **核心原则**: 所有改动必须在 Partial/extension 目录中，严禁修改框架生成代码
---
## 1. 改造总览
### 1.1 改造清单
| 层面 | 改造项 | 位置 | 是否破坏可升级性 |
|------|--------|------|:---:|
| 数据库 | 5 张新表 + 字典数据 | SQL 脚本 | ❌ |
| 后端-Entity | 6 个实体 Partial 类 | `DomainModels/*/partial/` | ❌ |
| 后端-Service | 6 个 Service Partial 类 | `Services/*/Partial/` | ❌ |
| 后端-Controller | 3 个 Controller Partial 类 | `Controllers/*/Partial/` | ❌ |
| 后端-Job | 3 个 Quartz 定时任务 | `Warehouse/Services/` | ❌ |
| 后端-Config | 注册网关 HttpClient | `Startup.cs` | ⚠️ 需手动合并 |
| 前端-主表 | 自定义操作列插槽 | `extension/warehouse/` | ❌ |
| 前端-组件 | 5 个设备操作组件 | `views/warehouse/base_device/components/` | ❌ |
| 网关 | GatewayClient HTTP 客户端 | `Warehouse/Services/` | ❌ |
### 1.2 框架扩展点总览
```
Vol.Pro 框架约定:
自动生成代码 (代码生成器覆盖) 自定义代码 (不被覆盖)
───────────────────────────── ──────────────────────────
Controllers/xxxController.cs Controllers/xxx/Partial/xxxController.cs
Services/xxxService.cs Services/xxx/Partial/xxxService.cs
IServices/IxxxService.cs IServices/xxx/Partial/IxxxService.cs
Repositories/xxxRepository.cs (无需自定义)
IRepositories/IxxxRepository.cs (无需自定义)
DomainModels/xxx/xxx.cs DomainModels/xxx/partial/xxx.cs
前端 views/xxx/xxx.vue extension/xxx.jsx + views/xxx/components/
```
---
## 2. 数据库改造
### 2.1 新增表
执行 `doc/db_init.sql`，创建 5 张表：
| 表名 | 说明 | 层级 |
|------|------|------|
| `gateway_nodes` | 网关节点 | 顶层 |
| `base_device` | 统一设备主表 | 核心，AdapterCode+SourceId 联合唯一 |
| `video_channel` | 视频通道扩展 | base_device 子表 |
| `video_record` | 录像文件 | video_channel 子表 |
| `iot_alarm` | 告警记录 | base_device 子表 |
| `iot_devicedata` | 数据归档 | base_device 子表 |
### 2.2 字典初始化
Phase 0 需在 Vol.Pro 管理端 → 字典管理 中创建 8 组数据字典：
| 字典名称 | 字典编号 | 字典值 |
|----------|:---:|------|
| 设备种类 | — | 摄像机/硬盘录像机/温湿度变送器/空调控制器/... (18 项) |
| 设备分组 | device_group | 视频设备/IoT设备/门禁设备/道闸设备/报警设备 |
| 是否父设备 | — | 是/否 |
| 在线状态 | — | 在线/离线 |
| 启用状态 | — | 启用/禁用 |
| 是否控制点 | — | 只读/可写 |
| 告警等级 | — | 提示/普通/重要/紧急 |
| 告警状态 | — | 未确认/已确认/已结束 |
### 2.3 区-点位-设备 三级关联
框架支持主从表三级显示。利用现有表关系：
```
warehouse_regions (区域) ← 代码生成器已有
└── warehouse_devicepoint (点位) ← 代码生成器已有
└── base_device (设备) ← 新建，用 PointId 关联点位
├── video_channel ← 新建子表
├── iot_devicedata ← 新建子表
└── iot_alarm ← 新建子表
```
**关键**：代码生成器配置 base_device 的 `DetailTable` 属性，关联 video_channel/iot_devicedata/iot_alarm 作为子表，框架自动渲染主从表 Tab。
---
## 3. 后端改造
### 3.1 Entity 扩展（Partial 类）
**原则**：框架生成的 Entity 在 `DomainModels/device_manager/base_device.cs`，不可修改。仅在 `partial/` 中添加。
```
VolPro.Entity/DomainModels/device_manager/partial/
├── base_device.cs # 添加导航属性 + AdapterCode/SourceId 唯一约束注解
├── gateway_nodes.cs # 网关特有业务属性
├── video_channel.cs # 通道流信息缓存
├── video_record.cs # (留空，框架生成即够用)
├── iot_devicedata.cs # (留空)
└── iot_alarm.cs # 告警确认/结束方法
```
**base_device Partial 示例**：
```csharp
namespace VolPro.Entity.DomainModels
{
public partial class base_device
{
// 导航属性（用于主从表）
[Navigate(NavigateType.OneToOne, nameof(DeviceId), nameof(video_channel.DeviceId))]
public video_channel? VideoChannel { get; set; }
[Navigate(NavigateType.OneToMany, nameof(DeviceId), nameof(iot_alarm.DeviceId))]
public List<iot_alarm>? Alarms { get; set; }
[Navigate(NavigateType.OneToMany, nameof(DeviceId), nameof(iot_devicedata.DeviceId))]
public List<iot_devicedata>? DeviceData { get; set; }
// 网关字段标识（供同步时判断哪些字段可覆盖）
public static readonly HashSet<string> GatewayFields = new()
{
nameof(IsOnline), nameof(IsParent), nameof(ParentDeviceId),
nameof(ExtraData), nameof(IpAddress), nameof(Port), nameof(LastSyncTime)
};
}
}
```
### 3.2 Service 扩展（Partial 类）
```
Warehouse/Services/device_manager/Partial/
├── base_deviceService.cs # GetRegionTree / GetDevicesByPoint / 字典查询辅助
├── gateway_nodesService.cs # 网关注册/心跳/同步入口
├── video_channelService.cs # (留空)
├── video_recordService.cs # (留空)
├── iot_devicedataService.cs # (留空)
└── iot_alarmService.cs # (留空)
```
**gateway_nodesService Partial**（核心同步入口）：
```csharp
namespace Warehouse.Services
{
public partial class gateway_nodesService
{
private readonly IHttpContextAccessor _httpContextAccessor;
private readonly Igateway_nodesRepository _repository;
[ActivatorUtilitiesConstructor]
public gateway_nodesService(
Igateway_nodesRepository dbRepository,
IHttpContextAccessor httpContextAccessor
) : base(dbRepository)
{
_httpContextAccessor = httpContextAccessor;
_repository = dbRepository;
}
// 网关注册 (Upsert) — 被 Controller A1 调用
public async Task<gateway_nodes> RegisterNodeAsync(string nodeCode, string token, string adapterTypes, string baseUrl)
{
// 实现: Upsert 逻辑
}
// 心跳更新 — 被 Controller A2 调用
public async Task UpdateHeartbeatAsync(string nodeCode, string token)
{
// 实现: 更新 LastHeartbeat + IsOnline
}
// 设备同步 — 被 Controller A3 调用
public async Task<(int added, int updated)> SyncDevicesAsync(int gatewayNodeId, List<StandardDevice> devices)
{
// 实现: 字段分治 + parentSourceId 映射
}
}
}
```
### 3.3 Controller 扩展（Partial 类）
```
VolPro.WebApi/Controllers/Warehouse/Partial/
├── base_deviceController.cs # GetRegionTree / GetDevicesByPoint / 操作代理
├── gateway_nodesController.cs # A1-A4 网关 API
├── video_channelController.cs # (留空)
├── video_recordController.cs # (留空)
├── iot_devicedataController.cs # (留空)
└── iot_alarmController.cs # (留空)
```
#### 3.3.1 gateway_nodesController（A 组 API）
**核心改造**：在框架生成的 `gateway_nodesController` 基础上，Partial 中添加 4 个不受权限控制的网关回调接口。
```csharp
namespace Warehouse.Controllers
{
public partial class gateway_nodesController
{
private readonly IHttpContextAccessor _httpContextAccessor;
[ActivatorUtilitiesConstructor]
public gateway_nodesController(
Igateway_nodesService service,
IHttpContextAccessor httpContextAccessor
) : base(service)
{
_httpContextAccessor = httpContextAccessor;
}
/// <summary>A1: 网关注册 (Upsert)</summary>
[HttpPost, Route("/api/gateway/register"), AllowAnonymous]
public async Task<IActionResult> RegisterGateway([FromBody] GatewayRegisterRequest req)
{
// 实现
}
/// <summary>A2: 心跳</summary>
[HttpPost, Route("/api/gateway/heartbeat"), AllowAnonymous]
public async Task<IActionResult> GatewayHeartbeat([FromBody] GatewayHeartbeatRequest req)
{
// 实现
}
/// <summary>A3: 设备数据同步 (字段分治)</summary>
[HttpPost, Route("/api/gateway/sync/devices"), AllowAnonymous]
public async Task<IActionResult> SyncDevices([FromBody] SyncDevicesRequest req)
{
// 实现
}
/// <summary>A4: 告警同步</summary>
[HttpPost, Route("/api/gateway/sync/alarms"), AllowAnonymous]
public async Task<IActionResult> SyncAlarms([FromBody] SyncAlarmsRequest req)
{
// 实现
}
}
}
```
**权限模型**：A 组接口加 `[AllowAnonymous]`，内部通过 `NodeToken` 二次认证。B 组接口走框架 JWT 权限。
#### 3.3.2 base_deviceController（B 组代理 + 设备树）
```csharp
namespace Warehouse.Controllers
{
public partial class base_deviceController
{
/// <summary>区域→点位→设备树（管理端左侧树形控件）</summary>
[HttpGet, Route("/api/DeviceManager/GetRegionTree")]
public async Task<IActionResult> GetRegionTree()
{
// SELECT warehouse_regions JOIN warehouse_devicepoint → 树形结构
// 每个点位下统计 base_device 数量
}
/// <summary>点位下设备列表（含子设备）</summary>
[HttpGet, Route("/api/DeviceManager/GetDevicesByPoint")]
public async Task<IActionResult> GetDevicesByPoint(int pointId, int page = 1, int size = 20)
{
// SELECT base_device WHERE PointId = pointId
// Include 子设备（ParentDeviceId）
}
}
}
```
### 3.4 网关 HTTP 客户端（GatewayClient）
```
Warehouse/Services/GatewayClient.cs
```
```csharp
public class GatewayClient
{
private readonly IHttpClientFactory _httpFactory;
private readonly IConfiguration _config;
public GatewayClient(IHttpClientFactory httpFactory, IConfiguration config)
{
_httpFactory = httpFactory;
_config = config;
}
/// <summary>调网关 B3: 手动触发全量同步</summary>
public async Task TriggerFullSyncAsync(string baseUrl, string adapterTypes)
{
var http = _httpFactory.CreateClient();
// POST {baseUrl}/api/gateway/devices/sync?adapter={adapterTypes}
}
/// <summary>调网关 B4: 获取实时点位值</summary>
public async Task<List<PointValue>> GetRealtimeAsync(string baseUrl, string adapter, string deviceId)
{
// GET {baseUrl}/api/gateway/realtime/{adapter}/{deviceId}
}
/// <summary>调网关 B5: 设备控制</summary>
public async Task ControlDeviceAsync(string baseUrl, string adapter, string deviceId, int pointIndex, double value)
{
// POST {baseUrl}/api/gateway/realtime/{adapter}/control
}
}
```
### 3.5 Quartz 定时任务
| Job | 触发器 | 职责 |
|-----|:---:|------|
| `SyncDevicesJob` | 每 5 分钟 | 遍历所有在线网关 → 调 GatewayClient.TriggerFullSyncAsync() |
| `RealtimePollJob` | 每 10 秒 | 轮询 MC4.0 IoT 设备实时值 → 更新 iot_devicedata |
| `HeartbeatMonitorJob` | 每 15 秒 | 扫描 gateway_nodes 心跳超时 → 标记离线 + 级联设备离线 |
**注册方式**：在 Vol.Pro 管理端 → Quartz 任务管理 → 新建任务，指定 Job 类全名。
### 3.6 Startup.cs 注册
```csharp
// 在 Startup.cs 或 Program.cs 中注册
builder.Services.AddHttpClient("VolPro", c =>
{
c.Timeout = TimeSpan.FromSeconds(30);
});
builder.Services.AddSingleton<GatewayClient>();
```
---
## 4. 前端改造
### 4.1 架构决策
| 方案 | 描述 | 是否破坏可升级性 |
|------|------|:---:|
| ❌ 修改生成的 .vue | 直接改 views/warehouse/base_device/ 下框架生成文件 | ✅ 破坏 |
| ✅ extension + components | 通过扩展注入 + 自定义组件实现操作列 | ❌ 不破坏 |
### 4.2 自定义操作列插槽
框架生成的 base_device 列表页面默认操作列只有"编辑/删除"。通过 **前端扩展文件** 自定义替换：
```
web.vite/src/extension/warehouse/base_device.jsx
```
```javascript
// 自定义操作列渲染
import VideoDeviceActions from '@/views/warehouse/base_device/components/VideoDeviceActions.vue'
import IoTDeviceActions from '@/views/warehouse/base_device/components/IoTDeviceActions.vue'
// 注册自定义组件
export default {
components: { VideoDeviceActions, IoTDeviceActions },
// 替换框架默认操作列
slots: {
// 操作列插槽
'col-action': (h, { row }) => {
const comp = row.deviceGroup === '视频设备' ? 'VideoDeviceActions'
: row.deviceGroup === 'IoT设备' ? 'IoTDeviceActions'
: null
if (comp) return h(comp, { props: { row } })
// fallback 到框架默认按钮
return null
}
}
}
```
### 4.3 组件目录
```
web.vite/src/views/warehouse/base_device/components/
├── VideoDeviceActions.vue # 实时预览/云台/回放/快照/同步通道
├── IoTDeviceActions.vue # 实时数据/控制/刷新/告警
├── AccessDeviceActions.vue # 远程开门 (Phase 3)
├── BarrierDeviceActions.vue # 抬杆/落杆 (Phase 3)
├── AlarmDeviceActions.vue # 告警/布防撤防 (Phase 3)
├── DeviceLivePreview.vue # Jessibuca 播放器弹窗
├── PtzControlPanel.vue # ↑↓←→+ZOOM+停止
├── RealtimeDataPanel.vue # 实时点位值表格弹窗
├── DeviceControlPanel.vue # 控制写值面板
├── DeviceEditDialog.vue # 设备编辑弹窗 (扩展字段)
└── MapBindingPanel.vue # VgoMap 模型绑定
```
### 4.4 组件设计要点
**VideoDeviceActions.vue**（核心组件）：
```
Props: row (base_device)
按钮组:
[实时预览] → 打开 DeviceLivePreview.vue 弹窗
→ GET /api/gateway/streams/{adapterCode}/{sourceId}/live → 流地址
→ 内嵌 Jessibuca 播放器（fallback: <video> 标签 + flv.js）
[云台控制] → 打开 PtzControlPanel.vue 弹窗
→ POST /api/gateway/streams/{adapterCode}/{sourceId}/ptz
→ 仅方向键: ↑↓←→ + ZOOM +/- + 停止
→ mousedown 开始移动, mouseup 发送停止
[查看回放] → 打开录像时间轴弹窗
→ GET /api/gateway/streams/{adapterCode}/{sourceId}/playback?start=&end=
[获取快照] → 下载快照图片
[同步通道] → 触发网关 B3 重新同步此 NVR 的通道
限制:
- channel 设备显示前 4 个按钮（无"同步通道"）
- NVR(IsParent=是) 显示全部 5 个按钮
```
**IoTDeviceActions.vue**：
```
[查看实时数据] → GET /api/gateway/realtime/{adapterCode}/{sourceId}
→ 仪表盘或数值显示（温度/湿度/电压...）
→ 5s 自动轮询
[设备控制] → 仅 isControlPoint=true 的设备显示
→ 空调温度设定/开关/模式切换
[刷新点位] → 强制刷新当前点位所有设备数据
[查看告警] → GET /api/gateway/alarms/{adapterCode}
→ 跳转或内嵌告警列表
```
### 4.5 API 封装
```
web.vite/src/api/deviceManager.js # (已存在于框架中)
web.vite/src/api/gateway.js # 新增：网关 B 组接口封装
```
```javascript
// gateway.js
import request from '@/uitils/request'
// 基础: 直连网关
const gwBase = 'http://localhost:5100/api/gateway'
export const getStreamUrl = (adapter, deviceId) =>
request({ url: `${gwBase}/streams/${adapter}/${deviceId}/live`, method: 'get' })
export const ptzControl = (adapter, deviceId, direction, speed = 0.5) =>
request({ url: `${gwBase}/streams/${adapter}/${deviceId}/ptz`, method: 'post', data: { direction, speed } })
export const getRealtime = (adapter, deviceId) =>
request({ url: `${gwBase}/realtime/${adapter}/${deviceId}`, method: 'get' })
export const controlDevice = (adapter, deviceId, pointIndex, value) =>
request({ url: `${gwBase}/realtime/${adapter}/control`, method: 'post', data: { deviceId, pointIndex, value } })
export const getAlarms = (adapter, params) =>
request({ url: `${gwBase}/alarms/${adapter}`, method: 'get', params })
export const confirmAlarm = (adapter, alarmId) =>
request({ url: `${gwBase}/alarms/${adapter}/${alarmId}/confirm`, method: 'post' })
```
> 前端直连网关（:5100），跨域问题通过 Vol.Pro nginx 反向代理 `/api/gateway/*` → `http://localhost:5100` 解决，或网关配置 CORS。
---
## 5. 可升级性保障清单
| 检查项 | 状态 |
|--------|:---:|
| 不修改框架生成的 C# 基础类 | ✅ |
| 所有自定义代码在 Partial 目录 | ✅ |
| 不修改框架生成的 .vue 文件 | ✅ |
| 前端业务逻辑在 extension 目录 | ✅ |
| 新增组件在 views/xxx/components/ 下 | ✅ |
| 不修改框架 NuGet 包版本 | ✅ |
| 网关调用通过独立 GatewayClient 类 | ✅ |
| A 组 API 用 `[AllowAnonymous]` + Token 二次认证 | ✅ |
| Dictionary/Entity 属性通过代码生成器配置，不手写 | ✅ |
| Startup.cs 注册仅用 `AddHttpClient`/`AddSingleton` | ✅ |
---
## 6. 实施顺序
| 步骤 | 内容 | 依赖 |
|:---:|------|------|
| 1 | 代码生成器生成 device_manager 模块 6 张表 | Phase 0 |
| 2 | 创建 Entity Partial 类 | 步骤 1 |
| 3 | 创建 Service Partial 类 | 步骤 1 |
| 4 | 创建 Controller Partial 类 (A1-A4 + GetRegionTree) | 步骤 3 |
| 5 | 注册 GatewayClient + HttpClient | 步骤 4 |
| 6 | 创建 Quartz Job (3 个) | 步骤 5 |
| 7 | 创建前端组件 (5 个按钮组 + 5 个弹窗) | 步骤 4 |
| 8 | 编写 extension/warehouse/base_device.jsx | 步骤 7 |
| 9 | nginx 配置网关反向代理 | 步骤 8 |
---
> **版本历史**:
> - v1.0 (2025-05-17) — 初版，基于整合方案 v3.1 + Vol.Pro 框架规范

260
doc/设计文档/VolPro框架改造方案_任务清单.md
View File

@@ -1,260 +0,0 @@
# Vol.Pro 框架前后端改造 — 任务清单
> **基准文档**: VolPro框架改造方案 v1.0
> **分支**: phase/0-infrastructure
> **原则**: 所有改动在 Partial/extension 目录，严禁修改框架生成文件
---
## Phase V0: 数据库与代码生成（预计 0.5 天）
### V0.1 建表
- [ ] 在 SQL Server 执行 `doc/db_init.sql`，创建 6 张表：
- `gateway_nodes`（网关节点）
- `base_device`（统一设备主表，AdapterCode+SourceId 联合主键）
- `video_channel`（视频通道扩展）
- `video_record`（录像文件）
- `iot_alarm`（告警记录）
- `iot_devicedata`（数据归档）
### V0.2 字典初始化
- [ ] 在 Vol.Pro 管理端 → 字典管理，创建 8 组数据字典：
- 设备分组：视频设备/IoT设备/门禁设备/道闸设备/报警设备
- 设备种类：摄像机/硬盘录像机/温湿度变送器/空调控制器/...（18 项）
- 在线状态：在线/离线
- 启用状态：启用/禁用
- 是否父设备：是/否
- 是否控制点：只读/可写
- 告警等级：提示/普通/重要/紧急
- 告警状态：未确认/已确认/已结束
### V0.3 代码生成
- [ ] 在 Vol.Pro 代码生成器中选择 `device_manager` 数据源，生成 6 张表的全套代码：
- `VolPro.Entity/DomainModels/device_manager/` — 6 个 Entity
- `Warehouse/IRepositories/device_manager/` — 6 个 Repository 接口
- `Warehouse/Repositories/device_manager/` — 6 个 Repository 实现
- `Warehouse/IServices/device_manager/` — 6 个 Service 接口 + 6 个 Partial 接口
- `Warehouse/Services/device_manager/` — 6 个 Service 实现 + 6 个 Partial Service
- `VolPro.WebApi/Controllers/Warehouse/` — 6 个 Controller
### V0.4 配置主从表
- [ ] 代码生成器配置 base_device 的 DetailTable：
- 关联 video_channel（DeviceId=DeviceId）
- 关联 iot_devicedata（DeviceId=DeviceId）
- 关联 iot_alarm（DeviceId=DeviceId）
- [ ] 代码生成器配置 base_device 的 ParentId 自引用字段（ParentDeviceId）
### V0.5 构建验证
- [ ] VS 编译 Vol.Pro 解决方案，确认 0 错误
- [ ] 管理端访问 base_device 页面 → 框架默认主从表三 Tab 渲染正常
> **V0 提交点**: `PhaseV0_db_codegen — 6 张表建表 + 字典 + 代码生成完毕，框架默认页面可访问`
---
## Phase V1: Entity 与 Service 扩展（预计 0.5 天）
### V1.1 Entity Partial
- [ ] 创建 `VolPro.Entity/DomainModels/device_manager/partial/base_device.cs`
- 添加导航属性：VideoChannel、Alarms、DeviceData
- 添加网关字段白名单常量 `GatewayFields`
- [ ] 创建 `VolPro.Entity/DomainModels/device_manager/partial/gateway_nodes.cs`
- 添加 `AdapterList` 属性（从 AdapterTypes 逗号分隔解析）
- [ ] 其他 4 个 Entity Partial 留空（框架生成即够用）
### V1.2 Service Partial — gateway_nodesService
- [ ] 编辑 `Warehouse/Services/device_manager/Partial/gateway_nodesService.cs`
- 注入 `Igateway_nodesRepository` + `IHttpContextAccessor`（`[ActivatorUtilitiesConstructor]`）
- 实现 `RegisterNodeAsync(nodeCode, token, adapterTypes, baseUrl)` — Upsert 逻辑
- 实现 `UpdateHeartbeatAsync(nodeCode, token)` — 更新心跳
- 实现 `SyncDevicesAsync(gatewayNodeId, List<StandardDevice>)` — 字段分治 + parentSourceId 映射
### V1.3 Service Partial — base_deviceService
- [ ] 编辑 `Warehouse/Services/device_manager/Partial/base_deviceService.cs`
- 注入 `Ibase_deviceRepository`
- 实现 `GetDevicesByGatewayNodeAsync(gatewayNodeId)` — 网关注册时返回设备列表
- 实现 `UpsertDeviceAsync(StandardDevice, gatewayNodeId, existingIds)` — 字段分治
### V1.4 Service Partial — iot_alarmService
- [ ] 编辑 `Warehouse/Services/device_manager/Partial/iot_alarmService.cs`
- 注入 `Iiot_alarmRepository`
- 实现 `UpsertAlarmAsync(StandardAlarm)` — SourceAlarmId 去重
### V1.5 构建验证
- [ ] VS 编译 → 0 错误
> **V1 提交点**: `PhaseV1_entity_service — Entity 导航属性 + Service 同步方法全部就绪`
---
## Phase V2: Controller 扩展（预计 1 天）
### V2.1 gateway_nodesController — A1 网关注册
- [ ] 编辑 `Controllers/Warehouse/Partial/gateway_nodesController.cs`
- 添加 `[HttpPost, Route("/api/gateway/register"), AllowAnonymous]`
- 认证：NodeToken 验证
- Upsert：存在则更新 AdapterTypes/BaseUrl/IsOnline，不存在且 Token 有效则 Insert
- 返回：`{ nodeId, devices }` — 当前网关的顶层设备列表
### V2.2 gateway_nodesController — A2 心跳
- [ ] 添加 `[HttpPost, Route("/api/gateway/heartbeat"), AllowAnonymous]`
- 认证：NodeToken
- 更新：IsOnline="在线" + LastHeartbeat=now
- 返回：`{ status: "ok", serverTime }`
### V2.3 gateway_nodesController — A3 设备同步
- [ ] 添加 `[HttpPost, Route("/api/gateway/sync/devices"), AllowAnonymous]`
- 认证：NodeToken
- 批量查已有 DeviceId 映射表
- 遍历设备：字段分治写入（首次全量，后续仅网关字段）
- parentSourceId → ParentDeviceId 解析
- 返回：`{ added, updated, removed }`
### V2.4 gateway_nodesController — A4 告警同步
- [ ] 添加 `[HttpPost, Route("/api/gateway/sync/alarms"), AllowAnonymous]`
- 认证：NodeToken
- 批量查 deviceSourceId → DeviceId 映射
- SourceAlarmId 去重
- 写入 iot_alarm，State="未确认"
- 返回：`{ added }`
### V2.5 base_deviceController — 设备树
- [ ] 编辑 `Controllers/Warehouse/Partial/base_deviceController.cs`
- [ ] 添加 `[HttpGet, Route("/api/DeviceManager/GetRegionTree")]`
- 查询：warehouse_regions JOIN warehouse_devicepoint
- 构建树形结构（region → point，含 deviceCount）
- 返回：`[{ id, label, type, children, deviceCount }]`
- [ ] 添加 `[HttpGet, Route("/api/DeviceManager/GetDevicesByPoint")]`
- 查询：base_device WHERE PointId=pointId（含子设备递归）
- 分页返回：`{ items, total }`
### V2.6 权限配置
- [ ] A1-A4 接口加 `[AllowAnonymous]`（内部 Token 二次认证）
- [ ] GetRegionTree/GetDevicesByPoint 走框架 JWT 权限
### V2.7 构建验证
- [ ] VS 编译 → 0 错误
- [ ] Postman 测试 A1-A4（Mock Token）
- [ ] 管理端访问 GetRegionTree → 返回 JSON
> **V2 提交点**: `PhaseV2_controller — 6 个 API 全部就绪，A1-A4 AllowAnonymous，设备树可查`
---
## Phase V3: 基础设施与定时任务（预计 0.5 天）
### V3.1 GatewayClient
- [ ] 创建 `Warehouse/Services/GatewayClient.cs`
- 实现 `TriggerFullSyncAsync(baseUrl, adapterTypes)` — 调网关 B3
- 实现 `GetRealtimeAsync(baseUrl, adapter, deviceId)` — 调网关 B4
- 实现 `ControlDeviceAsync(baseUrl, adapter, deviceId, pointIndex, value)` — 调网关 B5
### V3.2 Quartz Job — SyncDevicesJob
- [ ] 创建 `Warehouse/Services/SyncDevicesJob.cs`
- 实现 `IJob` 接口
- 遍历 `gateway_nodes WHERE IsOnline=在线 AND Enable=启用`
- 逐个调 `GatewayClient.TriggerFullSyncAsync`
### V3.3 Quartz Job — HeartbeatMonitorJob
- [ ] 创建 `Warehouse/Services/HeartbeatMonitorJob.cs`
- 扫描心跳超时 30s 的网关 → 标记离线
- 级联：`base_device WHERE GatewayNodeId=离线节点Id → IsOnline=离线`
### V3.4 Quartz Job — RealtimePollJob（Phase 2）
- [ ] 创建 `Warehouse/Services/RealtimePollJob.cs`（骨架，Phase 2 完善）
### V3.5 Startup.cs 注册
- [ ] 注册 `IHttpClientFactory`（Named: "VolPro"）
- [ ] 注册 `GatewayClient` 为 Singleton
- [ ] 确认 Quartz Job 在管理端可配置（JobDataMap 传入 ServiceProvider）
### V3.6 Job 注册
- [ ] 在 Vol.Pro 管理端 → Quartz 管理 → 新建 3 个 Job：
- SyncDevicesJob：Cron "0 */5 * * * ?"
- HeartbeatMonitorJob：Cron "0/15 * * * * ?"
- RealtimePollJob：Cron "0/10 * * * * ?"
### V3.7 构建验证
- [ ] VS 编译 → 0 错误
- [ ] GatewayClient 可通过 Swagger 测试
> **V3 提交点**: `PhaseV3_infrastructure — GatewayClient + 3 Job + Startup 注册完毕`
---
## Phase V4: 前端改造（预计 1.5 天）
### V4.1 目录创建
- [ ] 创建 `web.vite/src/views/warehouse/base_device/components/` 目录
- [ ] 创建 `web.vite/src/extension/warehouse/` 目录
- [ ] 创建 `web.vite/src/api/gateway.js` — 网关 B 组 API 封装
### V4.2 gateway.js API 封装
- [ ] `getStreamUrl(adapter, deviceId)` → GET 流地址
- [ ] `ptzControl(adapter, deviceId, direction)` → POST 云台控制
- [ ] `getRealtime(adapter, deviceId)` → GET 实时点值
- [ ] `controlDevice(adapter, deviceId, pointIndex, value)` → POST 控制
- [ ] `getAlarms(adapter, params)` → GET 告警列表
- [ ] `confirmAlarm(adapter, alarmId)` → POST 告警确认
### V4.3 视频操作组件
- [ ] 创建 `VideoDeviceActions.vue` — 按钮组（预览/云台/回放/快照/同步通道）
- [ ] 创建 `DeviceLivePreview.vue` — Jessibuca 播放器弹窗（<video> 回退）
- 调 `getStreamUrl` → 获取 WS-FLV/HLS 地址
- [ ] 创建 `PtzControlPanel.vue` — 方向键面板（↑↓←→+ZOOM+停止）
- mousedown 开始移动，mouseup 停止
### V4.4 IoT 操作组件
- [ ] 创建 `IoTDeviceActions.vue` — 按钮组（实时数据/控制/刷新/告警）
- [ ] 创建 `RealtimeDataPanel.vue` — 实时数值弹窗（5s 自动轮询 B4）
- [ ] 创建 `DeviceControlPanel.vue` — 控制写值面板（B5）
### V4.5 通用操作组件
- [ ] 创建 `DeviceEditDialog.vue` — 设备编辑弹窗（管理员字段）
- [ ] 创建 `MapBindingPanel.vue` — 地图模型绑定面板（模型ID/缩放/旋转）
### V4.6 未来组件（骨架）
- [ ] 创建 `AccessDeviceActions.vue` — 门禁按钮组（远程开门）
- [ ] 创建 `BarrierDeviceActions.vue` — 道闸按钮组（抬杆/落杆）
- [ ] 创建 `AlarmDeviceActions.vue` — 报警按钮组（告警/布防撤防）
### V4.7 扩展注入
- [ ] 创建 `web.vite/src/extension/warehouse/base_device.jsx`
- 注册操作列插槽 `col-action`
- 按 `row.deviceGroup` 动态渲染对应按钮组件
- 视频设备 → VideoDeviceActions
- IoT 设备 → IoTDeviceActions
- 其他 → 框架默认编辑/删除按钮
### V4.8 构建验证
- [ ] 前端 `npm run dev` 启动
- [ ] 访问 base_device 页面 → 操作列根据 DeviceGroup 显示不同按钮
- [ ] 点击"预览"→ 弹窗打开 → 获取流地址
> **V4 提交点**: `PhaseV4_frontend — 11 个组件 + extension 注入完成，操作列动态渲染`
---
## Phase V5: 联调验证（需网关+子系统就绪，预计 1 天）
### V5.1 端到端同步
- [ ] 启动网关 → 调 A1 注册 → gateway_nodes 表新增记录
- [ ] 网关调 A3 上送设备 → base_device 表有新设备
- [ ] 管理端 base_device 页面 → 列表中显示新设备
### V5.2 视频操作
- [ ] 视频设备行 → 点击"实时预览" → 弹窗播放 Owl 视频流
- [ ] 视频设备行 → 云台方向键操作 → Owl PTZ 响应
### V5.3 IoT 操作
- [ ] IoT 设备行 → 点击"实时数据" → 显示 MC4.0 温湿度值
### V5.4 告警确认
- [ ] MC4.0 触发告警 → 网关 A4 上送 → iot_alarm 表新增
- [ ] 管理端确认告警 → 通过 B9 写回 MC4.0
> **V5 提交点**: `PhaseV5_integration — 端到端同步 + 视频操作 + IoT 数据 + 告警确认全链路跑通`
---
> **总周期**: V0-V5 预计 5 个工作日（不含联调等待时间）

424
doc/设计文档/VolPro网关相关接口文档_v1.0.md
View File

@@ -1,424 +0,0 @@
# VolPro.WebApi 网关相关接口文档
> **版本**: 1.0
> **日期**: 2026-06-04
> **基址**: `http://{host}:{port}`（默认 `http://localhost:9100`）
> **内容类型**: `application/json`
> **接口来源**: `api_sqlsugar/VolPro.WebApi/Controllers/Warehouse/`
---
## 目录
1. [A 组 — 网关注册通信](#1-a-组--网关注册通信)
- A1: 网关注册 `POST /api/gateway/register`
- A2: 心跳上报 `POST /api/gateway/heartbeat`
- A3: 设备同步 `POST /api/gateway/sync/devices`
- A4: 告警同步 `POST /api/gateway/sync/alarms`
2. [设备管理](#2-设备管理)
- 区域树 `GET /api/DeviceManager/GetRegionTree`
- 点位设备 `GET /api/DeviceManager/GetDevicesByPoint`
3. [定时任务](#3-定时任务)
- 设备同步任务 `POST /api/task/syncDevices`
- 心跳监控任务 `POST /api/task/heartbeatMonitor`
- 实时轮询任务 `POST /api/task/realtimePoll`
- 规则引擎任务 `POST /api/task/ruleEngine`
4. [错误代码](#4-错误代码)
---
## 1. A 组 — 网关注册通信
> A 组接口是 VolPro 向网关暴露的管理端点，由网关主动调用。所有 A 组使用 `[AllowAnonymous]` + `NodeToken` 二次认证，不走 VolPro JWT 体系。
>
> **实现文件**: `Controllers/Warehouse/Partial/gateway_nodesController.cs`
### A1: 网关注册（Upsert）
```
POST /api/gateway/register
```
网关启动时调用，注册自身节点信息。NodeCode 已存在则更新，不存在则插入。返回当前网关的已有设备列表供网关对比差异。
**请求头**: `Content-Type: application/json`
**请求体 (GatewayRegisterRequest)**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|:--:|------|
| `NodeCode` | string | ✅ | 网关节点编码，如 `gw-31ku` |
| `Token` | string | ✅ | 认证令牌（由环境变量 `SECMPS_GATEWAY_TOKEN` 注入） |
| `AdapterTypes` | string | ✅ | 适配器类型列表（逗号分隔），如 `Owl:main,MC4:31ku` |
| `BaseUrl` | string | ✅ | 网关自身地址，如 `http://192.168.1.10:5100` |
**返回参数**:
| 字段 | 类型 | 说明 |
|------|------|------|
| `nodeId` | int | 网关节点 ID（base_device.NodeId 外键） |
| `devices` | array | 该网关已有的设备列表 |
**devices[] 条目**:
| 字段 | 类型 | 说明 |
|------|------|------|
| `deviceId` | int | 设备自增 ID |
| `deviceName` | string | 设备名称 |
| `adapterCode` | string | 适配器编码 |
| `sourceId` | string | 子系统设备原始 ID |
| `deviceCategory` | string | 设备种类 |
| `deviceGroup` | string | 设备分组 |
| `isParent` | string | 是否父设备（"是"/"否"） |
| `isOnline` | string | 是否在线（"在线"/"离线"） |
| `extraData` | string? | 扩展数据 JSON |
**返回示例**:
```json
{
"nodeId": 1,
"devices": [
{ "deviceId": 10, "deviceName": "NVR-1", "adapterCode": "Owl:main", "sourceId": "nvr_001", "deviceCategory": "硬盘录像机", "deviceGroup": "视频设备", "isParent": "是", "isOnline": "在线" }
]
}
```
**错误响应**:
| HTTP | 说明 |
|:---:|------|
| 400 | `NodeCode` 或 `Token` 为空 |
| 401 | `NodeToken` 不匹配（已有节点 Token 变更） |
---
### A2: 心跳上报
```
POST /api/gateway/heartbeat
```
网关每 15s 调用一次，更新 `LastHeartbeat` 字段。连续失败 ≥3 次（45s）后网关自动触发 A1+A3 重注册。
**请求体 (GatewayHeartbeatRequest)**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|:--:|------|
| `NodeCode` | string | ✅ | 网关节点编码 |
| `Token` | string | ✅ | 认证令牌 |
**返回参数**:
| 字段 | 类型 | 说明 |
|------|------|------|
| `status` | string | 固定 `"ok"` |
| `serverTime` | string | 服务器时间 (`yyyy-MM-dd HH:mm:ss`) |
**错误响应**:
| HTTP | 说明 |
|:---:|------|
| 400 | `NodeCode` 或 `Token` 为空 |
| 401 | NodeCode+Token 组合不匹配 |
---
### A3: 设备数据同步
```
POST /api/gateway/sync/devices
```
网关每次设备变更后调用，将全量设备列表推送到 VolPro。采用字段分治策略：首次入库写全量，后续只更新网关字段。
**请求体 (SyncDevicesRequest)**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|:--:|------|
| `NodeCode` | string | ✅ | 网关节点编码 |
| `Token` | string | ✅ | 认证令牌 |
| `Devices` | array | ✅ | 设备列表 |
**Devices[].SyncDeviceItemDto**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|:--:|------|
| `AdapterCode` | string | ✅ | 适配器编码 |
| `SourceId` | string | ✅ | 子系统设备原始 ID |
| `Name` | string? | ❌ | 设备名称 |
| `Category` | string? | ❌ | 设备种类 |
| `Group` | string? | ❌ | 设备分组 |
| `IsParent` | bool | ❌ | 是否父设备 |
| `ParentSourceId` | string? | ❌ | 父设备 SourceId（用于解析 ParentDeviceId） |
| `IsOnline` | bool | ❌ | 是否在线 |
| `IpAddress` | string? | ❌ | IP 地址 |
| `Port` | int? | ❌ | 端口号 |
| `ExtraDataJson` | string? | ❌ | 扩展数据 JSON |
**返回参数**:
| 字段 | 类型 | 说明 |
|------|------|------|
| `added` | int | 新增设备数 |
| `updated` | int | 更新设备数 |
| `removed` | int | 固定 `0`（当前版本不移除下线设备） |
**错误响应**:
| HTTP | 说明 |
|:---:|------|
| 400 | `NodeCode` 或 `Token` 为空 |
| 401 | NodeCode+Token 认证失败 |
---
### A4: 告警数据同步
```
POST /api/gateway/sync/alarms
```
网关检测到新告警后调用，推送告警列表到 VolPro。通过 `SourceAlarmId` 去重（同一告警不重复入库）。
**请求体 (SyncAlarmsRequest)**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|:--:|------|
| `NodeCode` | string | ✅ | 网关节点编码 |
| `Token` | string | ✅ | 认证令牌 |
| `Alarms` | array | ✅ | 告警列表 |
**Alarms[].SyncAlarmItemDto**:
| 字段 | 类型 | 必填 | 说明 |
|------|------|:--:|------|
| `SourceAlarmId` | string | ✅ | 子系统告警唯一 ID（用于去重） |
| `DeviceSourceId` | string | ✅ | 关联设备 SourceId（用于映射 DeviceId） |
| `AdapterCode` | string | ✅ | 适配器编码 |
| `Level` | string | ✅ | 告警等级：`提示`/`普通`/`重要`/`紧急` |
| `Desc` | string | ✅ | 告警描述 |
| `Value` | double? | ❌ | 告警实际值 |
| `StartTime` | string | ✅ | 告警发生时间 |
**返回参数**:
| 字段 | 类型 | 说明 |
|------|------|------|
| `added` | int | 新增告警数 |
**错误响应**:
| HTTP | 说明 |
|:---:|------|
| 400 | `NodeCode` 或 `Token` 为空 |
| 401 | NodeCode+Token 认证失败 |
---
## 2. 设备管理
> **实现文件**: `Controllers/Warehouse/Partial/base_deviceController.cs`
### 区域树
```
GET /api/DeviceManager/GetRegionTree
```
返回 区域→点位 的层级结构，供管理端左侧树形控件使用。
**请求参数**: 无
**返回参数**: `TreeNode[]`
| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 节点 ID（`r_{regionId}` 或 `p_{pointId}`） |
| `label` | string | 节点显示名称 |
| `type` | string | 节点类型：`region`(区域) 或 `point`(点位) |
| `deviceCount` | int | 该节点下的设备数量 |
| `children` | array? | 子节点列表（仅 region 节点有） |
**返回示例**:
```json
[
{
"id": "r_1", "label": "库房A区", "type": "region", "deviceCount": 3,
"children": [
{ "id": "p_10", "label": "温湿度监测点1", "type": "point", "deviceCount": 5 },
{ "id": "p_11", "label": "门禁点1", "type": "point", "deviceCount": 2 }
]
}
]
```
---
### 点位设备列表
```
GET /api/DeviceManager/GetDevicesByPoint?pointId={pointId}&page={page}&size={size}
```
获取指定点位下的设备列表（含子设备），支持分页。
**请求参数**:
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|:--:|------|------|
| `pointId` | int | ✅ | — | 点位 ID |
| `page` | int | ❌ | 1 | 页码 |
| `size` | int | ❌ | 20 | 每页条数 |
**返回参数**:
| 字段 | 类型 | 说明 |
|------|------|------|
| `items` | array | 设备列表 |
| `total` | int | 总设备数 |
**items[] 条目**:
| 字段 | 类型 | 说明 |
|------|------|------|
| `deviceId` | int | 设备自增 ID |
| `deviceName` | string | 设备名称 |
| `adapterCode` | string | 适配器编码 |
| `sourceId` | string | 子系统设备原始 ID |
| `deviceCategory` | string | 设备种类 |
| `deviceGroup` | string | 设备分组（`视频设备`/`IoT设备`/`门禁设备`） |
| `isParent` | string | 是否父设备（"是"/"否"） |
| `parentDeviceId` | int? | 父设备 ID |
| `isOnline` | string | 是否在线（"在线"/"离线"） |
| `ipAddress` | string? | IP 地址 |
| `port` | int? | 端口号 |
| `location` | string? | 位置描述 |
| `extraData` | string? | 扩展数据 JSON |
| `lastSyncTime` | DateTime? | 最后同步时间 |
| `mapModelId` | string? | 3D 地图模型 ID |
| `mapModelScale` | decimal? | 模型缩放比例 |
| `mapModelRotation` | string? | 模型旋转参数 JSON |
| `enable` | string | 启用状态（"启用"/"停用"） |
---
## 3. 定时任务
> VolPro 框架通过 `Sys_QuartzOptions` 表配置 URL+Cron 定时调用。每个端点加 `[ApiTask]` 属性以允许框架匿名调用。
>
> **实现文件**: `Controllers/Warehouse/TaskController.cs`
### 设备同步任务
```
POST /api/task/syncDevices
```
遍历所有在线网关，触发全量设备同步至 VolPro。
**Cron**: `0 */5 * * * ?`（每 5 分钟）
**请求参数**: 无
**返回参数**:
| 字段 | 类型 | 说明 |
|------|------|------|
| `time` | DateTime | 执行时间 |
| `status` | string | 固定 `"ok"` |
**错误响应**:
| HTTP | 说明 |
|:---:|------|
| 500 | `gateway_nodesService` 未注册 |
---
### 心跳监控任务
```
POST /api/task/heartbeatMonitor
```
扫描心跳超时 ≥30s 的网关节点，标记离线并级联标记该节点下所有设备离线。
**Cron**: `0/15 * * * * ?`（每 15 秒）
**请求参数**: 无
**返回**: 同设备同步任务
---
### 实时轮询任务
```
POST /api/task/realtimePoll
```
轮询所有在线 MC4 IoT 设备的实时值，写入 `iot_devicedata` 表。
**Cron**: `0/10 * * * * ?`（每 10 秒）
**请求参数**: 无
**返回**: 同设备同步任务
---
### 规则引擎任务
```
POST /api/task/ruleEngine
```
加载启用规则 → 从网关批量获取实时值 → 逐规则评估条件 → 触发动作（控制/告警/通知）。
**Cron**: `0/10 * * * * ?`（每 10 秒）
**请求参数**: 无
**返回**: 同设备同步任务
**当前状态**: 桩实现。`RuleEngineService.EvaluateAllAsync()` 抛出 `NotImplementedException`，需先执行 SQL ALTER TABLE + 代码生成器。
---
## 4. 错误代码
### HTTP 状态码
| 状态码 | 含义 | 触发条件 |
|:---:|------|------|
| 200 | OK | 请求成功 |
| 400 | Bad Request | 必填参数缺失（`NodeCode`/`Token`/`pointId`） |
| 401 | Unauthorized | A 组接口 NodeToken 认证失败 |
| 500 | Internal Server Error | 服务未注册或内部异常 |
### A 组认证错误
所有 A 组接口在认证失败时返回：
```json
{ "message": "认证失败：Token 无效" }
```
或
```json
{ "message": "认证失败" }
```
### 定时任务错误
定时任务在服务未注册时返回：
```json
{ "error": "服务未注册: gateway_nodesService" }
```
---
> **接口总数**: 10 个端点（A 组 4 + 设备管理 2 + 定时任务 4）
> **实现位置**: `api_sqlsugar/VolPro.WebApi/Controllers/Warehouse/`

174
doc/设计文档/定时任务API化整改方案_v1.0.md
View File

@@ -1,174 +0,0 @@
# 定时任务 API 化整改方案 v1.0
> **版本**: 1.0
> **日期**: 2026-06-04
> **背景**: VolPro 框架的 Quartz 机制基于 `[ApiTask]` + URL 调用，不支持 `IJob` 接口
> **现状**: 4 个 IJob 实现（SyncDevices/HeartbeatMonitor/RealtimePoll/RuleEngineJob）需迁移为 API 端点
---
## 1. 影响范围
| 任务 | 当前文件 | 需改为 | 调度间隔 |
|------|------|------|:---:|
| 设备同步 | `SyncDevicesJob.cs` (IJob) | Controller + `[ApiTask]` | 每5分钟 |
| 心跳监控 | `HeartbeatMonitorJob.cs` (IJob) | Controller + `[ApiTask]` | 每15秒 |
| 实时轮询 | `RealtimePollJob.cs` (IJob) | Controller + `[ApiTask]` | 每10秒 |
| 规则引擎 | `RuleEngineJob.cs` (IJob) | Controller + `[ApiTask]` | 每10秒 |
---
## 2. 整改步骤
### 步骤 T1: 创建任务调度 Controller（预计 30min）
**新建文件**: `api_sqlsugar/VolPro.WebApi/Controllers/Warehouse/TaskController.cs`
```csharp
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.DependencyInjection;
using VolPro.Core.Filters;
using Warehouse.Services;
namespace Warehouse.Controllers;
/// <summary>
/// 定时任务 API 端点。
/// VolPro 框架通过 Sys_QuartzOptions 配置 URL+Cron 定时调用。
/// 每个方法加 [ApiTask] 属性以允许框架匿名调用。
/// </summary>
[ApiController]
[Route("api/task")]
public class TaskController : Controller
{
/// <summary>T1: 设备同步 — 遍历在线网关触发全量设备同步</summary>
[ApiTask]
[HttpGet, HttpPost, Route("syncDevices")]
public async Task<IActionResult> SyncDevices()
{
var sp = HttpContext.RequestServices;
var engine = sp.GetService<SyncDevicesJob>();
if (engine != null) await engine.Execute(null!);
return Ok(new { time = DateTime.Now, status = "ok" });
}
/// <summary>T2: 心跳监控 — 扫描超时网关标记离线</summary>
[ApiTask]
[HttpGet, HttpPost, Route("heartbeatMonitor")]
public async Task<IActionResult> HeartbeatMonitor()
{
var sp = HttpContext.RequestServices;
var engine = sp.GetService<HeartbeatMonitorJob>();
if (engine != null) await engine.Execute(null!);
return Ok(new { time = DateTime.Now, status = "ok" });
}
/// <summary>T3: 实时轮询 — 拉取 MC4 IoT 实时值</summary>
[ApiTask]
[HttpGet, HttpPost, Route("realtimePoll")]
public async Task<IActionResult> RealtimePoll()
{
var sp = HttpContext.RequestServices;
var engine = sp.GetService<RealtimePollJob>();
if (engine != null) await engine.Execute(null!);
return Ok(new { time = DateTime.Now, status = "ok" });
}
/// <summary>T4: 规则引擎 — 评估规则+执行动作</summary>
[ApiTask]
[HttpGet, HttpPost, Route("ruleEngine")]
public async Task<IActionResult> RuleEngine()
{
var sp = HttpContext.RequestServices;
var engine = sp.GetService<RuleEngineService>();
if (engine != null) await engine.EvaluateAllAsync();
return Ok(new { time = DateTime.Now, status = "ok" });
}
}
```
### 步骤 T2: 注册 DI（预计 10min）
**编辑文件**: `api_sqlsugar/VolPro.Core/Extensions/AutofacManager/AutofacContainerModuleExtension.cs`
或在 Warehouse 项目的 Startup/Module 中注册：
```csharp
// 在 Autofac 注册块中添加
builder.RegisterType<SyncDevicesJob>().AsSelf().InstancePerLifetimeScope();
builder.RegisterType<HeartbeatMonitorJob>().AsSelf().InstancePerLifetimeScope();
builder.RegisterType<RealtimePollJob>().AsSelf().InstancePerLifetimeScope();
builder.RegisterType<RuleEngineService>().AsSelf().InstancePerLifetimeScope();
```
如果已由 VolPro 框架自动扫描 Services 目录，则跳过此步骤。
### 步骤 T3: 管理端配置任务（预计 15min）
在 Vol.Pro 管理端 → Quartz 管理 → 新建 4 个任务：
| TaskName | ApiUrl | Cron | Method |
|------|------|------|:--:|
| 设备同步 | `/api/task/syncDevices` | `0 */5 * * * ?` | POST |
| 心跳监控 | `/api/task/heartbeatMonitor` | `0/15 * * * * ?` | POST |
| 实时轮询 | `/api/task/realtimePoll` | `0/10 * * * * ?` | POST |
| 规则引擎 | `/api/task/ruleEngine` | `0/10 * * * * ?` | POST |
### 步骤 T4: 保留或删除 IJob 文件（预计 5min）
**保留** IJob 实现类（`SyncDevicesJob.cs` 等）不删除——Controller 通过 DI 获取它们并调用 `Execute()`。
只需将 IJob 实现类用 `IServiceProvider` 获取（而非 Quartz 的 `JobDataMap`），因为 Controller 不传 `IJobExecutionContext`。修改 `Execute` 方法签名：
```csharp
// 旧: 依赖 IJobExecutionContext.JobDataMap
public async Task Execute(IJobExecutionContext context)
{
var sp = (IServiceProvider)context.JobDetail.JobDataMap["ServiceProvider"];
...
}
// 新: 注入 IServiceProvider 为构造函数参数
public class HeartbeatMonitorJob : IJob
{
private readonly IServiceProvider _sp;
public HeartbeatMonitorJob(IServiceProvider sp) { _sp = sp; }
public async Task Execute(IJobExecutionContext? context)
{
var gwSvc = _sp.GetService<Igateway_nodesService>();
var devRepo = _sp.GetService<Ibase_deviceRepository>();
...
}
}
```
### 步骤 T5: 编译验证（预计 10min）
- [ ] `dotnet build api_sqlsugar/VolPro.WebApi` → 0 错误
- [ ] 确认 `[ApiTask]` 不与其他权限 Filter 冲突
---
## 3. 改动文件汇总
| 步骤 | 文件 | 改动 |
|:---:|------|------|
| T1 | `VolPro.WebApi/Controllers/Warehouse/TaskController.cs` | 新建，4 个 `[ApiTask]` 端点 |
| T2 | DI 注册 | 可能不需改动（VolPro 自动扫描） |
| T3 | 管理端 Sys_QuartzOptions | 新建 4 条任务记录 |
| T4 | 4 个 IJob 实现 | 构造函数改用 IServiceProvider 注入 |
| T5 | 全量编译 | 0 错误 |
---
## 4. 原 IJob 文件处理方案
| 文件 | 处理 |
|------|------|
| `SyncDevicesJob.cs` | 构造函数注入 IServiceProvider，Execute 参数改为 nullable |
| `HeartbeatMonitorJob.cs` | 同上 |
| `RealtimePollJob.cs` | 同上 |
| `RuleEngineJob.cs` | 删除（RuleEngineService 本身就是普通类，不继承 IJob） |
> `RuleEngineJob.cs` 可直接删除——`RuleEngineService` 是普通类，已被 TaskController 直接调用。

218
doc/设计文档/客户端改造方案_任务清单.md
View File

@@ -1,218 +0,0 @@
# warehouse 客户端改造 — 任务清单
> **基准文档**: 客户端改造方案 v1.0
> **分支**: gateway-dev
> **原则**: 改动仅在 warehouse/ 目录下，不影响 VolPro 管理端
---
## Phase W0: 基础设施（预计 0.5h）
### W0.1 网关 API 封装
- [ ] 创建 `warehouse/src/api/gateway.ts`
- 实现 `gwGet(url)` — GET 请求网关
- 实现 `gwPost(url, body)` — POST 请求网关
- 网关基址常量 `GW_BASE = 'http://localhost:5100'`
### W0.2 设备数据模型
- [ ] 在 `warehouse/src/api/gateway.ts` 中定义 TypeScript 接口：
- `Camera { id, name, location, status, adapterCode, streamUrl, hasPtz }`
- `StandardDevice { deviceId, adapterCode, sourceId, deviceName, deviceCategory, deviceGroup, isOnline, ... }`
- `StreamUrls { wsFlv, httpFlv, hls, ... }`
### W0.3 网关 CORS 确认
- [ ] 确认网关 `Program.cs` 中已启用 CORS（`AllowAnyOrigin` 或 `AllowCredentials`）
- [ ] 如未启用，在网关 `Program.cs` 中加 `builder.Services.AddCors()` + `app.UseCors()`
### W0.4 构建验证
- [ ] `npm run dev` 启动 warehouse，确认无编译错误
> **W0 提交点**: `PhaseW0_infra — gateway.ts + 数据模型 + CORS 就绪`
---
## Phase W1: 实时视频页改造（预计 2h）
### W1.1 获取真实摄像机列表
- [ ] 编辑 `warehouse/src/view/video/Live.vue`
- [ ] `onMounted` 中调用 `gwGet('/api/gateway/devices?adapter=Owl:main&page=1&size=100')`
- [ ] 将 `StandardDevice[]` 映射到 `Camera[]`
- [ ] 替换硬编码的 5 台 Mock 摄像机
- [ ] 保留在线/离线统计计算逻辑
### W1.2 视频流播放
- [ ] 选中摄像机时调用 `gwGet('/api/gateway/streams/{adapterCode}/{sourceId}/live')`
- [ ] 获取 WS-FLV 地址后赋值给 `<video>` 标签的 `src`
- [ ] 替换当前占位 `<div class="video-placeholder">`
### W1.3 云台控制面板
- [ ] 在视频画面旁边增加云台方向键区域（↑↓←→ + ZOOM + 停止）
- [ ] 调用 `gwPost('/api/gateway/streams/{adapter}/{id}/ptz', { direction, action, speed })`
- [ ] mouseup/mouseleave 时发送 stop
### W1.4 构建验证
- [ ] 页面加载 → 显示真实 Owl 摄像机列表
- [ ] 点击摄像机 → 播放实时视频流
- [ ] 方向键 → Owl PTZ 响应
> **W1 提交点**: `PhaseW1_video_live — 真实摄像机列表 + WS-FLV播放 + 云台控制`
---
## Phase W2: 视频墙 + 录像回放（预计 2h）
### W2.1 视频墙改造
- [ ] 编辑 `warehouse/src/view/video/VideoWall.vue`
- [ ] 页面加载时获取所有 Owl 摄像机列表
- [ ] 同时为前 N 路摄像机获取流地址
- [ ] 多路 `<video>` 标签并行播放（注意浏览器并发限制，建议 4 路）
### W2.2 录像回放改造
- [ ] 编辑 `warehouse/src/view/video/History.vue`
- [ ] 增加时间选择控件（开始时间 + 结束时间）
- [ ] 调用 `gwGet('/api/gateway/streams/{adapter}/{id}/playback?start=&end=')`
- [ ] 返回的 HLS 地址赋值给播放器
### W2.3 构建验证
- [ ] 视频墙同时显示 4 路画面
- [ ] 回放页时间轴选择 → HLS 播放
> **W2 提交点**: `PhaseW2_video_wall — 多路视频墙 + HLS回放`
---
## Phase W3: IoT 实时数据改造（预计 2h）
### W3.1 IoT 设备列表
- [ ] 编辑 `warehouse/src/view/environment/EnvVarManagement.vue`
- [ ] 调用 `gwGet('/api/gateway/tree?adapter=MC4:31ku')` 获取对象树
- [ ] 递归遍历，筛选 `DeviceGroup=IoT设备` 的叶子节点
- [ ] 渲染为设备列表/表格
### W3.2 实时值轮询
- [ ] 对每个 IoT 设备调用 `gwGet('/api/gateway/realtime/{adapter}/{deviceId}')`
- [ ] 每 5s 轮询一次（`setInterval`）
- [ ] 数据绑定到 ECharts 曲线图
- [ ] 数值异常时高亮显示
### W3.3 构建验证
- [ ] 环境页面显示 MC4.0 IoT 设备列表
- [ ] 选中设备 → 曲线图实时更新温度/湿度值
> **W3 提交点**: `PhaseW3_iot — IoT设备列表 + 5s轮询 + ECharts实时曲线`
---
## Phase W4: 设备详情页改造（预计 2h）
### W4.1 设备类型识别
- [ ] 编辑 `warehouse/src/view/DeviceInfo.vue`
- [ ] 从 props 或全局状态获取当前选中设备（`StandardDevice`）
- [ ] 根据 `DeviceCategory` + `DeviceGroup` 决定显示哪些选项卡
### W4.2 实时画面 Tab（视频设备）
- [ ] 视频设备：调 B6a 获取流地址 → `<video>` 播放
- [ ] 替代当前 `randomVideoImage` 占位图
### W4.3 实时曲线 Tab（IoT 设备）
- [ ] IoT 设备：调 B4 获取实时值 → ECharts 曲线
- [ ] 替代当前 Mock 数据生成的图表
### W4.4 设备控制 Tab
- [ ] 调 B5 发送控制指令
- [ ] 替代当前 Mock `handleTurnOn/handleTurnOff`
### W4.5 构建验证
- [ ] 地图点击设备 → 弹窗显示正确选项卡
- [ ] 视频设备显示真实画面
- [ ] IoT 设备显示实时曲线
> **W4 提交点**: `PhaseW4_device_info — 设备详情全选项卡对接真实数据`
---
## Phase W5: 报警页面对接（预计 2h）
### W5.1 告警列表
- [ ] 编辑 `warehouse/src/view/emergency-alarm/EmergencyAlarmRecord.vue`
- [ ] 编辑 `warehouse/src/view/intrusion-alarm/AlarmRecord.vue`
- [ ] 页面加载时调用 `gwGet('/api/gateway/alarms/{adapter}?from=&to=&page=&size=')`
- [ ] 渲染告警表格（时间/等级/描述/状态）
### W5.2 告警确认 + 结束
- [ ] 增加"确认"和"结束"按钮
- [ ] 调 `gwPost('/api/gateway/alarms/{adapter}/{alarmId}/confirm')`
- [ ] 调 `gwPost('/api/gateway/alarms/{adapter}/{alarmId}/end')`
### W5.3 告警颜色映射
- [ ] 提示=蓝色、普通=黄色、重要=橙色、紧急=红色
### W5.4 告警联动地图
- [ ] 点击告警报文 → 地图定位到对应设备位置（通过 base_device.Location/Lat/Lng）
### W5.5 构建验证
- [ ] 告警列表显示 MC4.0/Owl 真实告警
- [ ] 确认/结束按钮可用
- [ ] 点击告警 → 地图跳转
> **W5 提交点**: `PhaseW5_alarm — 真实告警列表 + 确认/结束 + 地图联动`
---
## Phase W6: 3D 地图设备标记（预计 3h）
### W6.1 设备标记数据
- [ ] 编辑 `warehouse/src/view/DataView.vue`
- [ ] 初始化时调 VolPro API 获取 `base_device WHERE Enable=启用`
- [ ] 遍历设备，提取 `MapModelId`、`MapModelScale`、`MapModelRotation`
### W6.2 VgoMap 加载设备模型
- [ ] 调用 `window.$map.addModel({ modelId, position, scale, rotation })`（API 需验证）
- [ ] 无 MapModelId 的设备用默认图标标记
- [ ] 在线设备绿色、离线设备灰色
### W6.3 点击标记 → 设备详情
- [ ] 监听 VgoMap 的 `click` 事件
- [ ] 命中设备标记时弹出 DeviceInfo.vue
### W6.4 告警设备闪烁
- [ ] 收到告警推送时，对应设备标记红色闪烁 10s
- [ ] 确认/结束告警后恢复
### W6.5 构建验证
- [ ] 3D 地图中显示设备模型或标记
- [ ] 点击标记弹出设备详情
- [ ] 告警设备红色闪烁
> **W6 提交点**: `PhaseW6_map — 3D地图设备标记 + 点击弹窗 + 告警闪烁`
---
## Phase W7: 联调 + 异常处理（预计 3h）
### W7.1 异常兜底
- [ ] 网关不可达时显示"网关连接失败"提示
- [ ] 取流失败时显示"无法获取流地址"
- [ ] 网络超时 10s 后自动重试一次
### W7.2 限流保护
- [ ] IoT 轮询间隔 ≥ 5s
- [ ] 视频墙并发取流 ≤ 4 路
- [ ] 告警列表分页 ≤ 100 条/页
### W7.3 全链路联调
- [ ] 网关启动 → 管理端添加设备 → warehouse 大屏可见
- [ ] 视频实时播放 + 云台控制
- [ ] IoT 曲线实时更新
- [ ] 告警触发 → 大屏弹窗 + 地图闪烁
### W7.4 性能验证
- [ ] 大屏帧率 ≥ 30fps
- [ ] 视频延迟 ≤ 2s
- [ ] 页面首次加载 ≤ 5s
> **W7 提交点**: `PhaseW7_integration — 全链路联调通过 + 异常处理 + 限流保护`
---
> **总周期**: W0-W7 预计 16 小时（含 3h 联调）

251
doc/设计文档/客户端改造方案v1.0.md
View File

@@ -1,251 +0,0 @@
# warehouse 客户端改造方案 v1.0
> **版本**: 1.0
> **日期**: 2025-05-17
> **现状**: warehouse 大屏客户端使用硬编码 Mock 数据，尚未对接网关
> **目标**: 所有子系统（视频/IoT/告警/地图）通过 IntegrationGateway 获取真实数据
---
## 1. 仓库客户端现状分析
### 1.1 技术栈
| 层面 | 选型 |
|------|------|
| 框架 | Vue 3 + TypeScript + Vite |
| UI | Element Plus |
| 图表 | ECharts |
| 实时通信 | SignalR |
| 3D 地图 | VgoMap SDK |
| HTTP | Axios（`api/http.js`） |
| 状态管理 | Pinia + Vuex |
| API 基址 | `window.apiConfig.baseURL`（默认 `http://localhost:9100`） |
### 1.2 页面清单与数据现状
| 页面 | 文件 | 当前数据源 | 需改造 |
|------|------|------|:---:|
| 3D 地图 | `view/Map.vue` | VgoMap SDK，无设备标记 | ✅ |
| 数据大屏 | `view/DataView.vue` | VolPro API（安全提示等）+ Mock | ✅ |
| 实时视频 | `view/video/Live.vue` | **硬编码 5 个 Mock 摄像头** | ✅ |
| 视频墙 | `view/video/VideoWall.vue` | 需查看 | ❓ |
| 录像回放 | `view/video/History.vue` | 需查看 | ❓ |
| 设备详情 | `view/DeviceInfo.vue` | Props 传入 Mock 数据 | ✅ |
| 环境变量 | `view/environment/EnvVarManagement.vue` | 需查看 | ✅ |
| 紧急报警 | `view/emergency-alarm/EmergencyAlarmRecord.vue` | Mock / VolPro API | ✅ |
| 入侵报警 | `view/intrusion-alarm/AlarmRecord.vue` | Mock | ✅ |
| 门禁 | `view/access/AccessRecord.vue` | Mock | ⏭️ Phase 3 |
| 巡更 | `view/patrol/` | Mock | ⏭️ Phase 3 |
| 钥匙 | `view/key/` | Mock | ⏭️ Phase 3 |
| 车辆 | `view/carmanager/` | Mock | ⏭️ Phase 3 |
| 访客 | `view/visitor/` | Mock | ⏭️ Phase 3 |
| 无人机 | `view/drone/` | Mock | ⏭️ Phase 3 |
| 对讲 | `view/intercom/` | Mock | ⏭️ Phase 3 |
### 1.3 HTTP 层现状
`api/http.js` 封装了 Axios，通过 `window.apiConfig.baseURL` 配置后端地址（默认 `http://localhost:9100`），支持 POST/GET 两种方式，自动附带 JWT Token。网关接口（`:5100`）和 Vol.Pro 接口（`:9100`）同域还是跨域取决于部署架构。
---
## 2. 数据流改造
### 2.1 架构决策：直连网关 vs 经 Vol.Pro 中转
| 方案 | 路径 | 优点 | 缺点 |
|------|------|------|------|
| A. 直连网关 | warehouse → GW(:5100) | 延迟低，零额外开发 | 需网关暴露 CORS |
| B. 经 Vol.Pro 中转 | warehouse → VP(:9100) → GW(:5100) | 统一鉴权，网关不外露 | 延迟 +1 跳，需写 Controller |
**推荐方案 A**：warehouse 客户端与大屏同一网络，网关开 CORS 即可。视频流和实时数据对延迟敏感，不宜多一跳。
### 2.2 服务路由总览
```
warehouse 客户端
├── Vol.Pro API (axios baseURL) → http://localhost:9100 (权限/字典/CRUD)
└── 网关 B 接口 (直接 fetch) → http://localhost:5100 (设备/视频/IoT/告警)
```
---
## 3. 逐页面改造方案
### 3.1 实时视频（Live.vue）
**现状**：硬编码 5 个 Mock 摄像机，无真实流
**改造**：
1. 页面加载时调用网关 `GET /api/gateway/devices?adapter=Owl:main&page=1&size=100`
2. 摄像机列表从 `StandardDevice[]` 映射到 `Camera[]` 接口
3. 选中摄像机后调用 `GET /api/gateway/streams/{adapterCode}/{sourceId}/live` 获取 WS-FLV 地址
4. 用 `<video>` 标签 `autoplay muted` 播放（替换占位 div）
5. 增加云台方向控制面板（复用 `base_device.vue` 的云台 UI）
6. 增加录像回放入口（调 B6b 获取 HLS 地址）
**改动量**：~150 行
### 3.2 视频墙（VideoWall.vue）+ 回放（History.vue）
**现状**：需查看文件
**改造**：
- 视频墙：多路视频同屏，从网关获取多个通道的流地址并行播放
- 回放：时间轴选择 → `GET /api/gateway/streams/{adapter}/{id}/playback?start=&end=`
**改动量**：~100 行
### 3.3 环境变量（EnvVarManagement.vue）
**现状**：需查看文件，预期是表格/图表展示温湿度等
**改造**：
1. 从网关获取 MC4 IoT 设备列表：`GET /api/gateway/tree?adapter=MC4:31ku`
2. 筛选 `DeviceGroup=IoT设备` 的设备
3. 轮询 `GET /api/gateway/realtime/{adapter}/{deviceId}` 获取实时值
4. 替换 Mock 数据，驱动 ECharts 曲线图实时更新
**改动量**：~120 行
### 3.4 设备详情（DeviceInfo.vue）
**现状**：从 DataView.vue 接收 props，展示设备基础信息 + 实时画面（占位图）+ 曲线（Mock）+ 控制按钮
**改造**：
1. 设备类型判断从 mock type → `row.DeviceCategory` 字段
2. "实时画面" Tab — 视频设备时调网关 B6a 显示真实流
3. "实时曲线" Tab — IoT 设备时调网关 B4 获取实时值
4. "设备控制" Tab — 调网关 B5 写值
5. 在线率/达标率 — 从 `row.IsOnline` 和实时值计算
**改动量**：~200 行
### 3.5 紧急报警 + 入侵报警
**现状**：部分调 VolPro API，部分 Mock
**改造**：
1. 告警列表从网关 `GET /api/gateway/alarms/{adapter}?from=&to=` 获取
2. 确认/结束告警 → `POST /api/gateway/alarms/{adapter}/{alarmId}/confirm`
3. 告警等级颜色映射（提示/普通/重要/紧急）
4. 点击告警行 → 联动地图定位到设备
**改动量**：~100 行
### 3.6 3D 地图（Map.vue / DataView.vue）
**现状**：VgoMap 加载 3D 模型，无设备标记
**改造**：
1. DataView.vue 初始化时调 VolPro API 获取 `base_device WHERE Enable=启用` 的设备列表
2. 遍历设备，读取 `MapModelId`、`MapModelScale`、`MapModelRotation` 字段
3. 调用 VgoMap SDK 在 3D 场景中放置设备标记（`map.addMarker` 或模型加载 API）
4. 设备在线状态 → 标记颜色（绿/灰）
5. 点击标记 → 弹出 DeviceInfo.vue 卡片
6. 告警设备 → 红色闪烁标记
**改动量**：~150 行
---
## 4. 数据模型映射
### 4.1 StandardDevice → Camera
```typescript
interface Camera {
id: string // StandardDevice.SourceId
name: string // StandardDevice.Name
location: string // StandardDevice.Extra?.location || ''
status: string // StandardDevice.IsOnline ? 'online' : 'offline'
adapterCode: string // StandardDevice.AdapterCode (用于后续 API 调用)
streamUrl?: string // 通过 B6a 动态获取
hasPtz: boolean // StandardDevice.Extra?.hasPtz === '1'
}
```
### 4.2 StandardDevice → MapMarker
```typescript
interface MapMarker {
deviceId: number // StandardDevice.DeviceId
modelId: string // StandardDevice.MapModelId
scale: number // StandardDevice.MapModelScale
rotation: JSON // StandardDevice.MapModelRotation
isOnline: boolean // StandardDevice.IsOnline
category: string // StandardDevice.DeviceCategory
}
```
### 4.3 PointValue → ChartData
```typescript
interface ChartSeries {
name: string // `点位${pv.PointIndex}`
data: number[] // [pv.Value, ...] (时间序列)
timeLabels: string[] // [pv.UpdateTime, ...]
}
```
---
## 5. API 封装层
### 5.1 新增 `api/gateway.js`
```typescript
const GW_BASE = 'http://localhost:5100';
export async function gwGet(url: string) {
const resp = await fetch(`${GW_BASE}${url}`);
return resp.json();
}
export async function gwPost(url: string, body?: object) {
const resp = await fetch(`${GW_BASE}${url}`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: body ? JSON.stringify(body) : undefined
});
return resp.json();
}
```
### 5.2 现有 `api/http.js` 不修改
Vol.Pro 后端 API（权限、字典、CRUD、安全提示）继续走 `api/http.js`，不加网关逻辑。
---
## 6. 与 VolPro 管理端的职责分工
| 功能 | 管理端（web.vite） | 大屏端（warehouse） |
|------|:---:|:---:|
| 设备 CRUD | ✅ 设备管理页面 | ❌ |
| 网关注册/心跳 | ✅ A1-A4 | ❌ |
| 区域树管理 | ✅ GetRegionTree | ❌ |
| 实时视频播放 | ✅ 预览按钮 | ✅ 多路视频墙 |
| 云台控制 | ✅ 方向键 | ✅ 方向键 |
| 视频回放 | ✅ 回放按钮 | ✅ 时间轴回放 |
| IoT 实时曲线 | ❌ | ✅ ECharts 大屏 |
| 告警弹窗联动 | ❌ | ✅ 告警+地图+预案 |
| 3D 模型绑定 | ✅ 编辑面板 | ✅ 加载标记 |
---
## 7. 实施计划
| 阶段 | 内容 | 预计工时 |
|------|------|:---:|
| W1 | 新增 `api/gateway.js` + 实时视频页改造 | 2h |
| W2 | 视频墙 + 录像回放改造 | 2h |
| W3 | 环境变量 IoT 实时数据改造 | 2h |
| W4 | 设备详情页对接真实数据 | 2h |
| W5 | 报警页面对接网关告警 | 2h |
| W6 | 3D 地图加载设备标记 | 3h |
| W7 | 联调 + 异常处理 + 限流 | 3h |
---
> **风险**: 网关 CORS 配置、VgoMap SDK 设备标记 API 需要验证

703
doc/设计文档/对接网关设计文档.md
View File

@@ -1,703 +0,0 @@
# IntegrationGateway 对接网关详细设计文档
> **版本**: 1.0
> **日期**: 2025-05-17
> **基准**: SecMPS 整合方案 v3.0
> **作者**: 架构组
---
## 1. 概述
IntegrationGateway 是 SecMPS 整合方案 v3.0 的核心组件，定位为 Vol.Pro 管理端与各物联子系统之间的**协议适配中间层**。网关对外提供统一 REST API，对内通过适配器模式对接异构子系统，实现"适配一次，多处复用"。
### 1.1 设计目标
| 目标 | 度量 |
|------|------|
| 适配器热插拔 | 新增子系统不改网关核心，仅加 Adapter 项目 |
| 故障隔离 | 任一适配器故障不影响其他适配器和网关注册 |
| 无状态部署 | 网关不存数据库，配置仅 NodeCode/Token/VolProUrl |
| 编译独立性 | `dotnet build` 0 错误，不依赖 Vol.Pro 运行时 |
### 1.2 技术栈
| 层面 | 选型 |
|------|------|
| 运行时 | .NET 8 |
| Web 框架 | ASP.NET Core Minimal API |
| HTTP 客户端 | IHttpClientFactory + SocketsHttpHandler |
| 序列化 | System.Text.Json |
| 容器化 | Docker (可选) |
---
## 2. 项目结构
```
gateway/
├── IntegrationGateway.sln
└── src/
├── IntegrationGateway.Core/ # 核心抽象（被所有项目引用）
│ ├── Abstractions/ # 7 个能力接口
│ │ ├── IHasOwnDeviceTree.cs
│ │ ├── IHasFlatDevices.cs
│ │ ├── IHasPoints.cs
│ │ ├── IHasStreams.cs
│ │ ├── IHasAlarms.cs
│ │ ├── IHasRecordings.cs
│ │ └── IAcceptsMetadataPush.cs
│ ├── Models/ # 统一模型
│ │ ├── StandardDevice.cs
│ │ ├── StandardAlarm.cs
│ │ ├── StandardRecording.cs
│ │ ├── DeviceTreeNode.cs
│ │ ├── PointValue.cs
│ │ ├── StreamUrls.cs
│ │ ├── PagedResult.cs
│ │ ├── AdapterCapabilities.cs
│ │ └── MetadataChangeSet.cs
│ └── Infrastructure/ # 基础设施
│ ├── AdapterRegistry.cs # 适配器注册中心
│ ├── RateLimiter.cs # 令牌桶限流器
│ └── GatewayClientFactory.cs # HTTP 客户端工厂
│
├── IntegrationGateway.Adapters.Owl/ # Owl 适配器
│ ├── OwlAdapter.cs # 实现 IHasFlatDevices + IHasStreams
│ └── OwlAuthHelper.cs # RSA 加密登录
│
├── IntegrationGateway.Adapters.MC4/ # MC4.0 适配器
│ ├── Mc4Adapter.cs # 实现 IHasOwnDeviceTree + IHasPoints + IHasAlarms
│ └── Mc4AuthHelper.cs # Token 认证
│
└── IntegrationGateway.Host/ # 宿主（启动项目）
├── Program.cs # 路由注册 + 适配器初始化
└── appsettings.json # 适配器连接配置
```
### 2.1 依赖关系
```
Host → Adapters.Owl → Core
Host → Adapters.MC4 → Core
Host → Core
```
适配器项目不互相引用，Core 项目零外部依赖（仅 Microsoft.Extensions.*）。
---
## 3. 核心接口体系
### 3.1 接口总览
```csharp
namespace IntegrationGateway.Core.Abstractions
{
/// <summary>所有适配器必须实现的基础接口</summary>
public interface IGatewayAdapter
{
string AdapterCode { get; } // "Owl:main" / "MC4:31ku"
string DisplayName { get; } // 人类可读名称
AdapterCapabilities Capabilities { get; } // 能力声明
Task InitializeAsync(); // 懒加载初始化
Task<bool> HealthCheckAsync(); // 健康检查
}
/// <summary>扁平设备列表（Owl/门禁/道闸）</summary>
public interface IHasFlatDevices : IGatewayAdapter
{
Task<PagedResult<StandardDevice>> GetDevicesAsync(int page, int size, string? keyword);
}
/// <summary>自有对象树（MC4.0）</summary>
public interface IHasOwnDeviceTree : IGatewayAdapter
{
Task<List<DeviceTreeNode>> GetObjectTreeAsync();
}
/// <summary>实时点位值（MC4.0 动环）</summary>
public interface IHasPoints : IGatewayAdapter
{
Task<List<PointValue>> GetRealtimeValuesAsync(string sourceDeviceId);
Task SetPointValueAsync(string sourceDeviceId, int pointIndex, double value);
}
/// <summary>视频流（Owl）</summary>
public interface IHasStreams : IGatewayAdapter
{
Task<StreamUrls> GetLiveUrlAsync(string channelId);
Task<StreamUrls> GetPlaybackUrlAsync(string channelId, DateTime start, DateTime end);
Task PtzControlAsync(string channelId, string direction, float speed);
Task PtzStopAsync(string channelId);
Task<StreamUrls> GetSnapshotAsync(string channelId);
}
/// <summary>告警（MC4.0 + Owl AI可选）</summary>
public interface IHasAlarms : IGatewayAdapter
{
Task<PagedResult<StandardAlarm>> GetAlarmsAsync(
int page, int size, DateTime from, DateTime to,
string? level = null, string? state = null);
Task ConfirmAlarmAsync(string alarmId);
Task EndAlarmAsync(string alarmId);
}
/// <summary>录像回放（Owl）</summary>
public interface IHasRecordings : IGatewayAdapter
{
Task<PagedResult<StandardRecording>> GetRecordingsAsync(
string channelId, DateTime start, DateTime end, int page, int size);
}
/// <summary>元数据回写（Owl 设备改名等）</summary>
public interface IAcceptsMetadataPush : IGatewayAdapter
{
Task<MetadataPushResult> PushMetadataAsync(string sourceDeviceId, MetadataChangeSet changes);
}
}
```
### 3.2 接口设计原则
- **显式优于隐式**：每个接口明确声明一种能力，适配器按需实现，网关通过 `is` 检查自动发现路由
- **异步优先**：所有方法返回 `Task`/`Task<T>`，避免阻塞线程
- **统一分页**：`PagedResult<T>` 统一 page/size 语义，适配器内部完成 skip/limit 转换
- **弹性 Extra**：`Dictionary<string, object?>` 承载适配器特有属性，不污染核心模型
### 3.3 适配器能力矩阵
```
Owl MC4.0 门禁(未来)
IGatewayAdapter ✅ ✅ ✅
IHasOwnDeviceTree - ✅ -
IHasFlatDevices ✅ - ✅
IHasPoints - ✅ -
IHasStreams ✅ - -
IHasAlarms ⚠️ ✅ ✅
IHasRecordings ✅ - -
IAcceptsMetadata ✅ - ⚠️
```
### 3.4 接口扩展规则
新增子系统时：
1. 如果现有接口能覆盖 → 直接实现对应接口，零网关改动
2. 如果现有接口不覆盖 → Core 中新增接口（如 `IHasFaceRecognition`），不能改已有接口签名
3. 新增能力接口后 → Controller 加一个 `if (adapter is INewFeature)` 分支即可
---
## 4. 统一模型设计
### 4.1 StandardDevice
```csharp
public class StandardDevice
{
public int DeviceId { get; set; } // Vol.Pro 侧主键（同步后回填）
public string AdapterCode { get; set; } = ""; // "Owl:main"
public string SourceId { get; set; } = ""; // 子系统原始ID (GB28181编码 / MC4 sid)
public string Name { get; set; } = ""; // 设备名称
public string Category { get; set; } = ""; // 摄像机/温湿度变送器/...
public string Group { get; set; } = ""; // 视频设备/IoT设备/...
public bool IsParent { get; set; } // 是否有子设备
public string? ParentSourceId { get; set; } // 父设备SourceId（层级关系）
public bool IsOnline { get; set; } // 在线状态
public string? IpAddress { get; set; } // IP地址
public int? Port { get; set; } // 端口
public Dictionary<string, object?>? Extra { get; set; } // 适配器扩展JSON
}
```
### 4.2 字段映射规则（字段分治）
| StandardDevice | base_device | 写入策略 |
|:---|---|:---:|
| Name | DeviceName | 仅首次 |
| Category | DeviceCategory | 仅首次 |
| Group | DeviceGroup | 仅首次 |
| IsOnline | IsOnline | 每次覆盖 |
| IsParent | IsParent | 每次覆盖 |
| ParentSourceId | ParentDeviceId | 每次覆盖（解析映射） |
| IpAddress | IpAddress | 每次覆盖 |
| Port | Port | 每次覆盖 |
| Extra | ExtraData | 每次覆盖 |
| AdapterCode + SourceId | (AdapterCode, SourceId) | 联合唯一键 |
### 4.3 DeviceTreeNode（对象树）
```csharp
public class DeviceTreeNode
{
public int Id { get; set; } // MC4.0 原始ID
public string SourceId { get; set; } = ""; // 转换为 string 的源ID
public string Name { get; set; } = ""; // 节点名称
public int Type { get; set; } // 1=区域, 2=设备
public int ObjectType { get; set; } // MC4.0 对象类型
public string? Tag { get; set; } // 标签（温湿度/烟雾/门磁...）
public Dictionary<string, object?>? Option { get; set; } // 扩展属性
public List<DeviceTreeNode> Children { get; set; } = new();
}
```
### 4.4 PagedResult<T>
```csharp
public class PagedResult<T>
{
public List<T> Items { get; set; } = new();
public int Total { get; set; }
public int Page => 0; // 由调用方设置
public int Size => 0;
}
```
### 4.5 其他模型
```
StreamUrls → { WsFlv, HttpFlv, Hls, WebRtc, Rtmp, Rtsp }
StandardAlarm → { AlarmId, DeviceId, AdapterCode, Level, Title, Content, OccurTime, Status, ... }
StandardRecording → { Id, ChannelId, StartedAt, EndedAt, Duration, FilePath, Size }
PointValue → { SourceDeviceId, PointIndex, Value, UpdateTime, Interval }
MetadataChangeSet → { Name?, Category?, Group?, Extra? }
AdapterCapabilities → { HasObjectTree, HasPoints, HasStreams, HasAlarms, HasRecordings, AcceptsControl, AcceptsMetadataPush }
```
---
## 5. 基础设施设计
### 5.1 AdapterRegistry
```csharp
public class AdapterRegistry
{
private readonly List<IGatewayAdapter> _adapters = new();
public void Register(IGatewayAdapter adapter) => _adapters.Add(adapter);
public async Task InitializeAllAsync()
{
// 并行初始化，单个失败不影响其他
await Task.WhenAll(_adapters.Select(a => Task.Run(async () =>
{
try { await a.InitializeAsync(); }
catch (Exception ex) { Log.Error($"Adapter {a.AdapterCode} init failed: {ex.Message}"); }
})));
}
public IReadOnlyList<IGatewayAdapter> All => _adapters.AsReadOnly();
public T? FindByCode<T>(string adapterCode) where T : class, IGatewayAdapter
=> _adapters.FirstOrDefault(a => a.AdapterCode == adapterCode && a is T) as T;
public IGatewayAdapter? FindByCode(string adapterCode)
=> _adapters.FirstOrDefault(a => a.AdapterCode == adapterCode);
}
```
**设计要点**：
- 列表存储，O(1) 注册，O(n) 查找（n≤5，可接受）
- 初始化失败不回滚，适配器标记为离线
- 网关启动时通过 `POST /register` 上报 `AdapterTypes` 给 Vol.Pro
### 5.2 RateLimiter（令牌桶）
```csharp
public class RateLimiter
{
private readonly SemaphoreSlim _semaphore;
private readonly int _tokensPerSecond;
public RateLimiter(int tokensPerSecond)
{
_tokensPerSecond = tokensPerSecond;
_semaphore = new SemaphoreSlim(tokensPerSecond, tokensPerSecond);
}
public async Task WaitAsync(CancellationToken ct = default)
{
await _semaphore.WaitAsync(ct);
_ = Task.Run(async () =>
{
await Task.Delay(1000 / _tokensPerSecond);
_semaphore.Release();
});
}
}
```
**配置策略**：
| 适配器 | QPS 限制 | 原因 |
|--------|:---:|------|
| Owl | 5 | 按文档推荐 |
| MC4.0 | 2 | MC4.0 API 限频 |
### 5.3 HttpClient 工厂
```csharp
// Program.cs 注册
builder.Services.AddHttpClient("VolPro", c =>
{
c.BaseAddress = new Uri("http://localhost:9100");
c.DefaultRequestHeaders.Add("Accept", "application/json");
c.Timeout = TimeSpan.FromSeconds(30);
}).ConfigurePrimaryHttpMessageHandler(() => new SocketsHttpHandler
{
PooledConnectionLifetime = TimeSpan.FromMinutes(5),
MaxConnectionsPerServer = 10
});
```
**策略**：
- 命名 HttpClient（`"VolPro"` 用于调 Vol.Pro，适配器内部自行创建 AuthenticatedClient）
- 连接池复用，5 分钟生命周期
- 超时 30 秒，防止第三方 API 慢响应阻塞
---
## 6. 认证与安全
### 6.1 网关注册认证（A1-A4）
```
网关持有: NodeCode + NodeToken（管理端分配）
注册流程:
1. 网关 → POST /api/gateway/register { nodeCode, token, ... }
2. Vol.Pro 查询 gateway_nodes WHERE NodeCode = req.NodeCode
- 存在 → 比对 NodeToken
- 不存在 → NodeToken 验证通过后 Insert
3. 认证失败 → 401
4. 成功后返回 NodeId + 设备列表
```
### 6.2 Owl 认证（RSA 加密）
```
1. GET /login/key → 获取 RSA 公钥 (Base64)
2. 用公钥加密 { username, password } → Base64
3. POST /login { data: <Base64密文> } → 获取 JWT Token
4. Token 有效期: 3 天
5. 后续请求: Authorization: Bearer <token>
```
**安全要点**：
- Token 内存缓存，不落盘
- Token 过期前 1 小时自动刷新（懒刷新策略）
- 认证失败不清除缓存 → 重试 3 次后 `Invalidate()`
### 6.3 MC4.0 认证
```
1. POST /api/central/auth/conf/get → 获取临时 Token
2. Token 有效期: 8 小时（保守估计）
3. 后续请求: header["token"] = <token>
```
### 6.4 网关内部接口（B 组）
B 组接口供管理端或 Vol.Pro 内部调用，认证方式：
- 内网部署：IP 白名单（Simple）
- 外网部署：共享 Secret Key（HMAC 签名），Phase 4 实现
---
## 7. 路由设计
### 7.1 网关主动接口（调 Vol.Pro，不暴露给外部）
网关内部通过 `VolProClient` 调用，不在 Minimal API 中注册路由。
```
POST {VolProBaseUrl}/api/gateway/register A1
POST {VolProBaseUrl}/api/gateway/heartbeat A2
POST {VolProBaseUrl}/api/gateway/sync/devices A3
POST {VolProBaseUrl}/api/gateway/sync/alarms A4
```
### 7.2 网关暴露接口（B 组，供管理端调用）
```csharp
// Program.cs 路由注册伪代码
app.MapGet("/api/gateway/health", async (AdapterRegistry reg) => {
var results = await Task.WhenAll(reg.All.Select(async a => new {
a.AdapterCode, a.DisplayName,
Healthy = await a.HealthCheckAsync(),
a.Capabilities
}));
return Results.Ok(results);
});
app.MapGet("/api/gateway/devices", async (string adapter, int page, int size, string? keyword, AdapterRegistry reg) => {
var a = reg.FindByCode<IHasFlatDevices>(adapter);
if (a == null) return Results.NotFound();
return Results.Ok(await a.GetDevicesAsync(page, size, keyword));
});
app.MapGet("/api/gateway/tree", async (string adapter, AdapterRegistry reg) => {
var a = reg.FindByCode<IHasOwnDeviceTree>(adapter);
if (a == null) return Results.NotFound();
return Results.Ok(await a.GetObjectTreeAsync());
});
app.MapGet("/api/gateway/streams/{adapter}/{deviceId}/live", async (string adapter, string deviceId, AdapterRegistry reg) => {
var a = reg.FindByCode<IHasStreams>(adapter);
if (a == null) return Results.NotFound();
return Results.Ok(await a.GetLiveUrlAsync(deviceId));
});
app.MapPost("/api/gateway/streams/{adapter}/{deviceId}/ptz", async (string adapter, string deviceId, PtzRequest req, AdapterRegistry reg) => {
var a = reg.FindByCode<IHasStreams>(adapter);
if (a == null) return Results.NotFound();
if (req.Action == "stop") await a.PtzStopAsync(deviceId);
else await a.PtzControlAsync(deviceId, req.Direction, req.Speed);
return Results.Ok();
});
app.MapGet("/api/gateway/alarms/{adapter}", async (string adapter, int page, int size, DateTime from, DateTime to, AdapterRegistry reg) => {
var a = reg.FindByCode<IHasAlarms>(adapter);
if (a == null) return Results.NotFound();
return Results.Ok(await a.GetAlarmsAsync(page, size, from, to));
});
app.MapPost("/api/gateway/alarms/{adapter}/{alarmId}/confirm", async (string adapter, string alarmId, AdapterRegistry reg) => {
var a = reg.FindByCode<IHasAlarms>(adapter);
if (a == null) return Results.NotFound();
await a.ConfirmAlarmAsync(alarmId);
return Results.Ok();
});
// ... 更多 B 组接口
```
### 7.3 路由设计原则
- **适配器参数前置**：所有 B 组接口第一个路径参数都是 `{adapter}`，通过注册中心查找
- **能力检查懒加载**：请求到达时才检查适配器是否实现对应接口
- **404 语义**：适配器不存在或未实现对应能力 → 404（而非 500）
- **统一错误格式**：`{ "error": "ADAPTER_NOT_FOUND", "message": "Adapter 'xxx' not found" }`
---
## 8. 同步流程设计
### 8.1 网关启动同步
```
1. 网关启动 → 加载配置 (NodeCode, Token, VolProBaseUrl)
2. 初始化适配器 (并行: Owl + MC4)
3. POST /api/gateway/register → 获取 NodeId + 已有设备列表
4. 按 AdapterCode 分流已有设备 → 适配器对比差异
5. 各适配器发现子设备 → 构建 StandardDevice[] 列表
6. POST /api/gateway/sync/devices → Vol.Pro Upsert 设备
7. 开启 15s 心跳定时器
```
### 8.2 手动全量同步（B3）
```
管理端 → POST /api/gateway/devices/sync?adapter=MC4:31ku
网关:
1. 找到 Mc4Adapter
2. (MC4) GetObjectTree() → 解析区域+设备 → StandardDevice[]
3. (Owl) GetDevices() + GetChannels() → StandardDevice[]
4. POST /api/gateway/sync/devices → Vol.Pro
5. 返回 { added, updated, removed }
```
### 8.3 MC4.0 同步（FullReplace 模式）
```
MC4.0 对象树遍历:
type=1 (区域) → 名称匹配 warehouse_regions → 新建或绑区
type=2 (设备) → Upsert base_device
- 首次写入: DeviceName/Category/Group/ExtraData 全量
- 后续同步: 仅更新 IsOnline/ExtraData/ParentDeviceId
type=2 子节点 → parentSourceId 解析 → ParentDeviceId
```
### 8.4 Owl 同步（Merge 模式）
```
Owl 设备列表遍历:
GET /devices → NVR 设备 (IsParent=是, DeviceGroup=视频设备)
GET /channels → 通道 (ParentDeviceId=NVR, IsParent=否)
通道额外写 video_channel 扩展记录 (OwlStreamApp/OwlStreamName)
```
---
## 9. 错误处理
### 9.1 错误码规范
| HTTP 状态码 | error_code | 场景 |
|:---:|------|------|
| 200 | - | 正常 |
| 400 | `INVALID_PARAMETER` | 参数缺失或格式错误 |
| 401 | `UNAUTHORIZED` | Token 验证失败 |
| 404 | `ADAPTER_NOT_FOUND` | 适配器不存在 |
| 404 | `CAPABILITY_NOT_SUPPORTED` | 适配器未实现该能力 |
| 502 | `UPSTREAM_ERROR` | 第三方 API 返回错误 |
| 503 | `ADAPTER_OFFLINE` | 适配器健康检查失败 |
| 504 | `UPSTREAM_TIMEOUT` | 第三方 API 超时 |
| 500 | `INTERNAL_ERROR` | 网关内部错误 |
### 9.2 适配器日志
```csharp
public void Log(string adapterCode, string operation, string detail, Exception? ex = null)
{
var level = ex != null ? "ERROR" : "INFO";
var msg = $"[{DateTime.UtcNow:O}] [{level}] [{adapterCode}] {operation}: {detail}";
if (ex != null) msg += $"\n{ex}";
Console.WriteLine(msg);
}
```
---
## 10. 配置管理
### 10.1 appsettings.json 结构
```json
{
"Logging": {
"LogLevel": { "Default": "Information" }
},
"Owl": {
"BaseUrl": "http://localhost:15123",
"Username": "admin",
"Password": "your_password"
},
"MC4": {
"BaseUrl": "http://localhost:3000"
},
"Gateway": {
"VolProBaseUrl": "http://localhost:9100",
"NodeCode": "gw-31ku",
"NodeToken": "xxxxxxxxxx",
"HeartbeatIntervalSec": 15,
"AdapterInitTimeoutSec": 30
}
}
```
### 10.2 环境变量覆盖（Docker 部署）
```bash
GATEWAY__OWL__BASEURL=http://192.168.1.100:15123
GATEWAY__OWL__PASSWORD=prod_password
GATEWAY__GATEWAY__NODETOKEN=prod_token
```
### 10.3 配置验证
启动时验证必填项：
```
Gateway.VolProBaseUrl ✓
Gateway.NodeCode ✓ (长度 1-50)
Gateway.NodeToken ✓ (长度 8-100)
Owl.BaseUrl ✓ (格式 http(s)://...)
Owl.Username ✓
Owl.Password ✓
MC4.BaseUrl ✓
```
---
## 11. 部署方案
### 11.1 单机部署
```bash
cd gateway
dotnet publish src/IntegrationGateway.Host -c Release -o publish
cd publish
./IntegrationGateway.Host --urls http://0.0.0.0:5100
```
### 11.2 Docker 部署
```dockerfile
FROM mcr.microsoft.com/dotnet/aspnet:8.0
WORKDIR /app
COPY publish/ .
ENV ASPNETCORE_URLS=http://+:5100
ENTRYPOINT ["dotnet", "IntegrationGateway.Host.dll"]
```
### 11.3 双实例部署
```
实例A: gw-31ku :5100 → MC4.0(31号库) + Owl(仓库视频)
实例B: gw-11ku :5101 → MC4.0(11号库) + 海康ISC(门禁)
```
### 11.4 运维命令
```bash
# 健康检查
curl http://localhost:5100/api/gateway/health
# 手动同步
curl -X POST "http://localhost:5100/api/gateway/devices/sync?adapter=MC4:31ku"
# 查看日志
docker logs -f integration-gateway
```
---
## 12. 性能指标
| 指标 | 目标值 | 说明 |
|------|:---:|------|
| 网关启动时间 | < 5s | 含适配器并行初始化 |
| 设备同步吞吐 | 100 设备/s | 含 HTTP 往返 |
| 实时取流响应 | < 500ms | 从请求到返回流地址 |
| 内存占用 | < 100MB | 空载状态 |
| 并发连接数 | 50 | 同时处理的管理端请求 |
---
## 13. 测试策略
### 13.1 单元测试（Phase 4）
```
IntegrationGateway.Core.Tests/
├── AdapterRegistryTests # 注册/查找/初始化
├── RateLimiterTests # 令牌桶行为
└── ModelSerializationTests # JSON 序列化往返
```
### 13.2 集成测试（需子系统 Mock）
```
适配器层 Mock → 验证 Controller 路由分发
Vol.Pro API Mock → 验证网关注册/心跳/同步流程
```
### 13.3 边界测试
| 场景 | 预期行为 |
|------|----------|
| Owl 离线 | HealthCheck → false, 设备 IsOnline 不变 |
| MC4.0 超时 | 返回 504, 不影响 Owl 适配器 |
| 并发取流 | RateLimiter 排队, 不丢请求 |
| 配置错误 | 启动时校验失败, 拒绝启动 |
---
## 14. 版本历史
| 版本 | 日期 | 变更 |
|------|------|------|
| 1.0 | 2025-05-17 | 初版详细设计 |
---
> **下一步**: Phase 0 Day 1 按本设计实施网关项目骨架。

Some files were not shown because too many files have changed in this diff Show More