JydApp.Framework 1.0.11

JydApp.Framework

JydApp 通用应用层框架 —— 为景悦达多个垂直行业应用（配电室、安防管理、轨道安防、智慧体育、智慧医院）提供统一的后端基座。

架构概览

┌─────────────────────────────────────────────────────────────┐
│  垂直应用: PowerRoom / SafeGuard / TransitSecurity / ...     │
├─────────────────────────────────────────────────────────────┤
│  JydApp.Framework（本项目）                                  │
├──────────────────────┬──────────────────────────────────────┤
│  IotMatrix 物联网中台  │  JydGBS 视频平台 (CMS + SMS)         │
└──────────────────────┴──────────────────────────────────────┘

分层结构

JydApp.Framework.sln
├── 00-Core/
│   └── JydApp.Framework.Domain           领域层（实体、仓储接口、集成接口）
├── 01-Application/
│   └── JydApp.Framework.Application      应用层（服务接口+实现、DTO）
├── 02-Services/
│   ├── JydApp.Framework.Event            事件处理（MQ 消息处理器、定时任务）
│   └── JydApp.Framework.RuleEngine       规则引擎（图形化规则执行器）
├── 03-Infrastructure/
│   └── JydApp.Framework.Infrastructure   基础设施（DB、Redis、MQ、外部客户端）
└── 04-Presentation/
    └── JydApp.Framework.Api              API层（控制器、中间件、Hub）

技术栈

• .NET 9 / ASP.NET Core Web API
• SqlSugar ORM + PostgreSQL
• FreeRedis (缓存、分布式锁)
• RabbitMQ (消息队列)
• SignalR (WebSocket 实时推送)
• IotMatrix North API (物联网设备数据)
• JydGBS (GB28181 视频平台)

快速开始

构建

cd JydApp.Framework
dotnet restore
dotnet build

垂直应用引用方式

// Program.cs
var builder = WebApplication.CreateBuilder(args);

// 1. 框架基础设施
builder.Services.AddAppFrameworkInfrastructure(builder.Configuration);

// 2. 应用服务自动注册（扫描框架 + 垂直应用程序集）
builder.Services.AddApplicationServices(
    typeof(YourApp.Application.SomeAppService).Assembly
);

// 3. 事件处理器注册
builder.Services.AddAppFrameworkEvent(
    typeof(YourApp.Event.SomeHandler).Assembly
);

// 4. API 配置
builder.Services.AddAppFrameworkApi(builder.Configuration);

var app = builder.Build();
app.UseAppFrameworkMiddleware();
app.MapControllers();
app.MapCommonHubs();
app.Run();

核心实体（30个）

身份与权限

空间与组织

| Area | app_area | 层级区域树 | | AreaDevice | app_area_device | 区域-设备绑定 | | AreaUser | app_area_user | 区域-用户访问绑定 |

IoT 核心

| Product | app_product | IoT 产品类型 | | Device | app_device | 设备实例 | | DataSyncLog | app_data_sync_log | IotMatrix 数据同步日志 |

告警与事件

| AlarmRecord | app_alarm_record | 告警记录（含 AI/门禁/周界/消防来源） | | EventRecord | app_event_record | 事件记录（客观事实，不需处理） | | EventAlarmRule | app_event_alarm_rule | 事件升级规则（事件→告警的匹配条件和升级参数） | | AlarmActionConfig | app_alarm_action_config | 告警联动配置 | | AlarmActionLog | app_alarm_action_log | 联动执行日志 | | StrategyRule | app_strategy_rule | 规则引擎规则 | | StrategyRecord | app_strategy_record | 规则执行记录 |

运维管理

| WorkOrder | app_work_order | 工单 | | Notification | app_notification | 系统通知 |

系统支撑

| DictionarySet | sys_dictionary_set | 数据字典组 | | DictionaryData | sys_dictionary_data | 字典值 | | CodeDefinition | sys_code_definition | 自动编码规则 | | File | sys_file | 文件上传记录 | | OperationLog | sys_operation_log | 操作审计日志 | | LoginLog | sys_login_log | 登录历史 |

工作流

| WfProcessDefinition | wf_process_definition | 流程模板 | | WfNodeDefinition | wf_node_definition | 流程节点 | | WfProcessInstance | wf_process_instance | 流程实例 | | WfTaskInstance | wf_task_instance | 待办任务 |

框架提供的应用服务

IotMatrix 集成

数据流转

IotMatrix North API（X-Api-Key 认证）
│
├── RabbitMQ 推送（实时）
│   ├── Exchange: north.telemetry
│   │   └── {pk}.{dn}          → NorthTelemetryEventHandler  → Redis 缓存 + SignalR 推送
│   │
│   └── Exchange: north.events
│       ├── device.online.#     → DeviceStatusEventHandler    → 更新设备状态 + EventRecord + 规则评估
│       ├── device.offline.#    → DeviceStatusEventHandler    → 更新设备状态 + EventRecord + 规则评估
│       ├── alarm.#             → NorthAlarmEventHandler      → EventRecord → EventAlarmEvaluator → AlarmRecord + 联动
│       └── device.event.info.# → DeviceEventHandler          → EventRecord → EventAlarmEvaluator → 按规则升级
│
├── REST API（按需查询）
│   ├── GET  /products                       → 产品列表/详情/TSL 物模型
│   ├── GET  /devices                        → 设备列表/状态/标签
│   ├── GET  /devices/{id}/telemetry/latest  → 最新遥测（IotMatrix Redis）
│   ├── GET  /devices/{id}/telemetry/history → 历史遥测（IotMatrix InfluxDB）
│   ├── POST /devices/{id}/telemetry/reading → 表计抄读
│   ├── POST /devices/{id}/properties        → 设备属性控制
│   └── POST /devices/{id}/services/{name}   → 调用设备服务
│
└── 定时同步（IotMatrixSyncService）
    ├── ProductSyncTask（每 30 分钟）→ 同步产品 + TSL 物模型
    └── DeviceSyncTask（每 5 分钟） → 同步设备 + 关联产品

内置 MQ 消息处理器

数据同步服务（IotMatrixSyncService）

框架提供 IIotMatrixSyncService，由两个定时任务驱动：

• ProductSyncTask：每 30 分钟，启动延迟 15 秒

  • 分页获取 IotMatrix 产品 → 新增/更新本地 Product 实体
  • 同步每个产品的 TSL（物模型）JSON
  • IotMatrix 中已删除的产品 → 本地标记 Status=0（停用，不删除）

• DeviceSyncTask：每 5 分钟，启动延迟 30 秒

  • 分页获取 IotMatrix 设备 → 新增/更新本地 Device 实体
  • 通过 IotMatrixProductId 关联本地 Product
  • IotMatrix 中已删除的设备 → 本地标记 OnlineStatus="removed", Status=0（不删除，保留历史数据）

• DataSyncLog：每次同步记录日志（sync_type, sync_status, total_count, success_count, error_message, end_time）

同步策略：只增不删。从 IotMatrix 删除设备后，本地设备不会被删除，仅标记为停用/已移除。这保证了告警记录、事件记录、工单等历史数据的引用完整性。

设计原则

• 不缓存遥测到 PostgreSQL：最新值存 Redis（TTL 5分钟），历史查询透传 IotMatrix InfluxDB
• 告警记录持久化：告警存本地 PostgreSQL，支持全生命周期管理
• 设备/产品定期同步：IotMatrixSyncService 定时从 IotMatrix 同步，只增不删，保留数据引用完整性

告警系统

告警来源与类型

AlarmRecord 支持多种告警来源（AlarmSource）：

• device — 设备遥测越限（自动恢复: AutoRecoverable=true）
• ai — AI 视频分析检测
• rule — 规则引擎触发
• manual — 人工创建
• access — 门禁系统
• perimeter — 周界安防
• fire — 消防系统

告警严重级别：Critical / Major / Minor / Warning

告警生命周期：Active → Acknowledged → Resolved

告警详情聚合（AlarmDetailDto）

IAlarmRecordAppService.GetDetailAsync 聚合告警弹窗所需的全部数据：

AlarmDetailDto（继承 AlarmRecordDto）
├── 基础告警信息（级别、来源、状态、时间...）
├── 设备信息（DeviceCode, ProductName, OnlineStatus, IpAddress, Location）
├── AI 证据（SnapshotUrl, VideoClipUrl, AiModelId, AiConfidence, CameraId）
└── ExtendedInfo（Dictionary<string, object>? —— 来自 IAlarmDetailEnricher）

IAlarmDetailEnricher — 垂直应用扩展点：

• 框架提供 DefaultAlarmDetailEnricher（返回空）
• 配电室可注入摄像头画面、电气参数
• 校园可注入门禁记录、人脸识别截图
• 注册方式：services.AddScoped<IAlarmDetailEnricher, YourEnricher>()

告警联动系统

告警触发 → AlarmActionDispatcher
               │ 查询 AlarmActionConfig（匹配来源/类型/级别/区域/设备）
               ▼
         IAlarmActionHandler 实现
         ├── NotifyAlarmActionHandler（框架内置：发通知）
         ├── LogAlarmActionHandler（框架内置：记日志）
         ├── WorkOrderHandler（垂直应用实现：创建工单）
         ├── EmergencyPlanHandler（垂直应用实现：执行预案）
         └── DeviceControlHandler（垂直应用实现：联动设备）

实时推送

Application 层: IRealTimePusher（抽象接口）
       ↓ 实现
Api 层: SignalRRealTimePusher（使用 IHubContext）
       ↓ 推送到 SignalR Group
SignalR Hub:
  ├── RealTimeDataHub   /hubs/realtime-data   设备遥测推送  Group: device:{deviceId}
  ├── AlarmHub          /hubs/alarms          告警推送      Group: alarms
  └── NotificationHub   /hubs/notifications   通知推送      Group: user:{userId}

IRealTimePusher 方法：

• PushToDeviceAsync(deviceId, method, data) — 推送到设备订阅组
• PushToAreaAsync(areaId, method, data) — 推送到区域订阅组
• PushAlarmAsync(data) — 广播告警给所有订阅者
• PushNotificationAsync(userId, data) — 推送到指定用户

扩展点

关键文件索引

src/
├── 00-Core/JydApp.Framework.Domain/
│   ├── Common/BaseEntity.cs                    实体基类（UUID PK + 审计 + 软删除）
│   ├── Entities/                               30个核心实体
│   ├── Repositories/IRepository.cs             泛型仓储接口
│   ├── IotMatrix/IIotMatrixClient.cs           IotMatrix North API 客户端接口 + DTO
│   └── MessageQueue/IMessageHandler.cs         消息处理器接口 + 消息模型
│
├── 01-Application/JydApp.Framework.Application/
│   ├── Services/ServiceInterfaces.cs           IIotMatrixSyncService, IStrategyRuleAppService 等接口
│   ├── IotMatrixSync/IotMatrixSyncService.cs   数据同步服务实现（只增不删策略）
│   ├── Alarms/
│   │   ├── IAlarmRecordAppService.cs           告警服务接口 + DTO（含 AlarmDetailDto）
│   │   ├── AlarmRecordAppService.cs            告警服务实现（含详情聚合 + 联动派发）
│   │   └── IAlarmDetailEnricher.cs             告警详情扩展接口 + 默认实现
│   ├── Events/
│   │   ├── EventAlarmEvaluator.cs              事件→告警升级评估器（规则匹配 + Redis 冷却）
│   │   └── EventAlarmRuleAppService.cs         事件升级规则 CRUD
│   └── Common/IRealTimePusher.cs               实时推送抽象接口
│
├── 02-Services/JydApp.Framework.Event/
│   ├── Handlers/
│   │   ├── NorthTelemetryEventHandler.cs       遥测 → Redis + SignalR
│   │   ├── DeviceStatusEventHandler.cs         在线/离线 → DB + Redis + SignalR + EventRecord
│   │   ├── NorthAlarmEventHandler.cs           告警触发/恢复 → EventRecord → 规则评估 → AlarmRecord + 联动
│   │   └── DeviceEventHandler.cs               设备 Info 事件 → EventRecord → 规则评估
│   └── Tasks/
│       └── IotMatrixSyncTasks.cs               ProductSyncTask(30min) + DeviceSyncTask(5min)
│
├── 03-Infrastructure/JydApp.Framework.Infrastructure/
│   └── IotMatrix/IotMatrixClient.cs            IIotMatrixClient HttpClient 实现
│
└── 04-Presentation/JydApp.Framework.Api/
    ├── RealTime/SignalRRealTimePusher.cs        IRealTimePusher 的 SignalR 实现
    └── Extensions/ServiceCollectionExtensions.cs DI 注册入口

配置项

{
  "ConnectionStrings": {
    "PostgreSQL": "Host=localhost;Port=5432;Database=jydapp;Username=postgres;Password=xxx"
  },
  "IotMatrix": {
    "ApiBaseUrl": "https://localhost:41774",
    "ApiKey": "your-api-key"
  },
  "RabbitMq": {
    "HostName": "localhost",
    "Port": 5672,
    "UserName": "guest",
    "Password": "guest",
    "Enabled": true
  },
  "Redis": {
    "ConnectionString": "localhost:6379",
    "Enabled": true,
    "KeyPrefix": "JydApp:"
  },
  "Jwt": {
    "SecretKey": "your-secret-key",
    "Issuer": "JydApp",
    "Audience": "JydApp",
    "AccessTokenExpireMinutes": 120,
    "RefreshTokenExpireDays": 7
  }
}

表命名约定

• sys_ — 系统管理（用户、角色、权限、字典、文件、日志）
• app_ — 通用业务（区域、设备、告警、工单、通知、规则）
• wf_ — 工作流
• 垂直应用使用各自前缀：prp_(配电室), sc_(安防), ts_(轨道), ss_(体育), sh_(医院)