WebAPI 支持摄像头启停控制、码流切换、审计日志的提供

2025-12-26 12:15:10 +08:00
parent e9f5975a79
commit adcdc56c7a
12 changed files with 1176 additions and 357 deletions
--- a/SHH.CameraSdk/Controllers/Dto/BindHandleDto.cs
+++ b/SHH.CameraSdk/Controllers/Dto/BindHandleDto.cs
@@ -0,0 +1,23 @@
+using System.ComponentModel.DataAnnotations;
+
+namespace SHH.CameraSdk;
+
+/// <summary>
+/// 句柄绑定 DTO
+/// 用于前端向后端传递窗口渲染句柄，实现视频流的硬件解码渲染
+/// </summary>
+public class BindHandleDto
+{
+    /// <summary>
+    /// 窗口句柄 (IntPtr 转换为 long 类型传输，避免跨平台序列化问题)
+    /// </summary>
+    [Required(ErrorMessage = "渲染窗口句柄不能为空")]
+    [Range(1, long.MaxValue, ErrorMessage = "句柄必须为有效的非负整数")]
+    public long Handle { get; set; }
+
+    /// <summary>
+    /// 用途描述 (用于审计日志，如 "Main_Preview"、"AI_Analysis_Window")
+    /// </summary>
+    [MaxLength(64, ErrorMessage = "用途描述长度不能超过 64 个字符")]
+    public string Purpose { get; set; } = string.Empty;
+}
--- a/SHH.CameraSdk/Controllers/Dto/CameraConfigDto.cs
+++ b/SHH.CameraSdk/Controllers/Dto/CameraConfigDto.cs
@@ -0,0 +1,123 @@
+using System.ComponentModel.DataAnnotations;
+
+namespace SHH.CameraSdk;
+
+// ==============================================================================
+// 1. 物理与运行配置 DTO (对应 CRUD 操作)
+// 用于设备新增/全量配置查询，包含基础身份、连接信息、运行参数等全量字段
+// ==============================================================================
+public class CameraConfigDto
+{
+    // --- 基础身份 (Identity) ---
+    /// <summary>
+    /// 设备唯一标识
+    /// </summary>
+    [Required(ErrorMessage = "设备ID不能为空")]
+    [Range(1, long.MaxValue, ErrorMessage = "设备ID必须为正整数")]
+    public long Id { get; set; }
+
+    /// <summary>
+    /// 设备友好名称
+    /// </summary>
+    [MaxLength(64, ErrorMessage = "设备名称长度不能超过64个字符")]
+    public string Name { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 摄像头品牌类型 (0:HikVision, 1:Dahua, 2:RTSP...)
+    /// </summary>
+    [Range(0, 10, ErrorMessage = "品牌类型值必须在0-10范围内")]
+    public int Brand { get; set; }
+
+    /// <summary>
+    /// 设备安装位置描述
+    /// </summary>
+    [MaxLength(128, ErrorMessage = "安装位置长度不能超过128个字符")]
+    public string Location { get; set; } = string.Empty;
+
+    // --- 核心连接 (Connectivity) - 修改此类参数触发冷重启 ---
+    /// <summary>
+    /// 摄像头IP地址
+    /// </summary>
+    [Required(ErrorMessage = "IP地址不能为空")]
+    [RegularExpression(@"^((25[0-5]|2[0-4]\d|[01]?\d\d?)\.){3}(25[0-5]|2[0-4]\d|[01]?\d\d?)$",
+        ErrorMessage = "请输入合法的IPv4地址")]
+    public string IpAddress { get; set; } = string.Empty;
+
+    /// <summary>
+    /// SDK端口 (如海康默认8000)
+    /// </summary>
+    [Range(1, 65535, ErrorMessage = "端口号必须在1-65535范围内")]
+    public ushort Port { get; set; } = 8000;
+
+    /// <summary>
+    /// 登录用户名
+    /// </summary>
+    [MaxLength(32, ErrorMessage = "用户名长度不能超过32个字符")]
+    public string Username { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 登录密码
+    /// </summary>
+    [MaxLength(64, ErrorMessage = "密码长度不能超过64个字符")]
+    public string Password { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 通道号 (通常为1)
+    /// </summary>
+    [Range(1, 32, ErrorMessage = "通道号必须在1-32范围内")]
+    public int ChannelIndex { get; set; } = 1;
+
+    /// <summary>
+    /// RTSP流路径 (备用或非SDK模式使用)
+    /// </summary>
+    [MaxLength(256, ErrorMessage = "RTSP地址长度不能超过256个字符")]
+    public string RtspPath { get; set; } = string.Empty;
+
+    // --- 主板关联信息 (Metadata) ---
+    /// <summary>
+    /// 关联主板IP地址
+    /// </summary>
+    [RegularExpression(@"^((25[0-5]|2[0-4]\d|[01]?\d\d?)\.){3}(25[0-5]|2[0-4]\d|[01]?\d\d?)?$",
+        ErrorMessage = "请输入合法的IPv4地址")]
+    public string MainboardIp { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 关联主板端口
+    /// </summary>
+    [Range(1, 65535, ErrorMessage = "主板端口号必须在1-65535范围内")]
+    public int MainboardPort { get; set; } = 80;
+
+    // --- 运行时参数 (Runtime Options) - 支持热更新 ---
+    /// <summary>
+    /// 码流类型 (0:主码流, 1:子码流)
+    /// </summary>
+    [Range(0, 1, ErrorMessage = "码流类型只能是0(主码流)或1(子码流)")]
+    public int StreamType { get; set; } = 0;
+
+    /// <summary>
+    /// 是否使用灰度图 (用于AI分析场景加速)
+    /// </summary>
+    public bool UseGrayscale { get; set; } = false;
+
+    /// <summary>
+    /// 是否启用图像增强 (去噪/锐化等)
+    /// </summary>
+    public bool EnhanceImage { get; set; } = true;
+
+    // --- 画面变换 (Transform) - 支持热更新 ---
+    /// <summary>
+    /// 是否允许图像压缩 (降低带宽占用)
+    /// </summary>
+    public bool AllowCompress { get; set; } = true;
+
+    /// <summary>
+    /// 是否允许图像放大 (提升渲染质量)
+    /// </summary>
+    public bool AllowExpand { get; set; } = false;
+
+    /// <summary>
+    /// 目标分辨率 (格式如 1920x1080，空则保持原图)
+    /// </summary>
+    [RegularExpression(@"^\d+x\d+$", ErrorMessage = "分辨率格式必须为 宽度x高度 (如 1920x1080)")]
+    public string TargetResolution { get; set; } = string.Empty;
+}
--- a/SHH.CameraSdk/Controllers/Dto/DeviceUpdateDto.cs
+++ b/SHH.CameraSdk/Controllers/Dto/DeviceUpdateDto.cs
@@ -0,0 +1,96 @@
+using System.ComponentModel.DataAnnotations;
+
+namespace SHH.CameraSdk;
+
+/// <summary>
+/// 设备配置更新传输对象
+/// <para>用于接收前端的编辑请求，支持部分更新（字段为 null 表示不修改）</para>
+/// <para>自动区分 <b>冷更新参数</b>（需重启连接）和 <b>热更新参数</b>（无感生效）</para>
+/// </summary>
+public class DeviceUpdateDto
+{
+    // ==============================================================================
+    // 1. 冷更新参数 (Cold Update)
+    // 修改此类参数涉及物理连接变更，后端会自动执行 "Stop -> Update -> Start" 流程
+    // ==============================================================================
+
+    /// <summary>摄像头IP地址</summary>
+    [RegularExpression(@"^((25[0-5]|2[0-4]\d|[01]?\d\d?)\.){3}(25[0-5]|2[0-4]\d|[01]?\d\d?)$",
+        ErrorMessage = "请输入合法的IPv4地址")]
+    public string? IpAddress { get; set; }
+
+    /// <summary>SDK端口 (如海康 8000)</summary>
+    [Range(1, 65535, ErrorMessage = "端口号必须在 1-65535 范围内")]
+    public ushort? Port { get; set; }
+
+    /// <summary>登录用户名</summary>
+    [MaxLength(32, ErrorMessage = "用户名长度不能超过 32 个字符")]
+    public string? Username { get; set; }
+
+    /// <summary>登录密码</summary>
+    [MaxLength(64, ErrorMessage = "密码长度不能超过 64 个字符")]
+    public string? Password { get; set; }
+
+    /// <summary>通道号 (默认 1)</summary>
+    [Range(1, 32, ErrorMessage = "通道号必须在 1-32 范围内")]
+    public int? ChannelIndex { get; set; }
+
+    /// <summary>摄像头品牌类型 (0:Hik, 1:Dahua...)</summary>
+    [Range(0, 10, ErrorMessage = "品牌类型值必须在 0-10 范围内")]
+    public int? Brand { get; set; }
+
+    /// <summary>RTSP流地址 (非SDK模式下使用)</summary>
+    [MaxLength(256, ErrorMessage = "RTSP地址长度不能超过 256 个字符")]
+    public string? RtspPath { get; set; }
+
+    /// <summary>关联的主板IP (用于联动控制)</summary>
+    [RegularExpression(@"^((25[0-5]|2[0-4]\d|[01]?\d\d?)\.){3}(25[0-5]|2[0-4]\d|[01]?\d\d?)?$",
+        ErrorMessage = "请输入合法的IPv4地址")]
+    public string? MainboardIp { get; set; }
+
+    /// <summary>关联的主板端口</summary>
+    [Range(1, 65535, ErrorMessage = "主板端口号必须在 1-65535 范围内")]
+    public int? MainboardPort { get; set; }
+
+    // ==============================================================================
+    // 2. 热更新参数 (Hot Update)
+    // 修改此类参数仅刷新运行时状态，不中断物理连接，无感生效
+    // ==============================================================================
+
+    /// <summary>设备名称/别名</summary>
+    [MaxLength(64, ErrorMessage = "设备名称长度不能超过 64 个字符")]
+    public string? Name { get; set; }
+
+    /// <summary>安装位置描述</summary>
+    [MaxLength(128, ErrorMessage = "安装位置长度不能超过 128 个字符")]
+    public string? Location { get; set; }
+
+    /// <summary>码流类型 (0:主码流, 1:子码流)</summary>
+    [Range(0, 1, ErrorMessage = "码流类型只能是 0(主码流) 或 1(子码流)")]
+    public int? StreamType { get; set; }
+
+    /// <summary>渲染句柄 (IntPtr 的 Long 形式)</summary>
+    [Range(0, long.MaxValue, ErrorMessage = "渲染句柄必须是非负整数")]
+    public long? RenderHandle { get; set; }
+
+    // ==============================================================================
+    // 3. 图像处理参数 (Image Processing - Hot Update)
+    // 影响解码后的 SmartFrame 数据格式
+    // ==============================================================================
+
+    /// <summary>是否允许压缩 (影响传输带宽)</summary>
+    public bool? AllowCompress { get; set; }
+
+    /// <summary>是否允许放大 (影响渲染质量)</summary>
+    public bool? AllowExpand { get; set; }
+
+    /// <summary>目标分辨率 (格式如 "1920x1080"，空则保持原图)</summary>
+    [RegularExpression(@"^\d+x\d+$", ErrorMessage = "分辨率格式必须为 宽度x高度 (如 1920x1080)")]
+    public string? TargetResolution { get; set; }
+
+    /// <summary>是否启用图像增强 (去噪/锐化等)</summary>
+    public bool? EnhanceImage { get; set; }
+
+    /// <summary>是否转为灰度图 (用于 AI 纯分析场景加速)</summary>
+    public bool? UseGrayscale { get; set; }
+}
--- a/SHH.CameraSdk/Controllers/Dto/SubscriptionDto.cs
+++ b/SHH.CameraSdk/Controllers/Dto/SubscriptionDto.cs
@@ -0,0 +1,31 @@
+using System.ComponentModel.DataAnnotations;
+
+namespace SHH.CameraSdk;
+
+// ==============================================================================
+// 2. 订阅策略 DTO (对应 A/B/C/D 进程需求)
+// 用于多进程帧需求的注册与更新，支持显示帧和分析帧的独立配置
+// ==============================================================================
+public class SubscriptionDto
+{
+    /// <summary>
+    /// 进程唯一标识 (如 "AI_Process_01"、"Main_Display_02")
+    /// </summary>
+    [Required(ErrorMessage = "进程标识 AppId 不能为空")]
+    [MaxLength(50, ErrorMessage = "AppId 长度不能超过 50 个字符")]
+    public string AppId { get; set; } = string.Empty;
+
+    /// <summary>
+    /// 显示帧率需求 (单位: fps)
+    /// <para>不需要显示则设为 0，控制器会自动注销该类型需求</para>
+    /// </summary>
+    [Range(0, 60, ErrorMessage = "显示帧率需在 0-60 fps 范围内")]
+    public int DisplayFps { get; set; }
+
+    /// <summary>
+    /// 分析帧率需求 (单位: fps)
+    /// <para>不需要分析则设为 0，控制器会自动注销该类型需求</para>
+    /// </summary>
+    [Range(0, 30, ErrorMessage = "分析帧率需在 0-30 fps 范围内")]
+    public int AnalysisFps { get; set; }
+}