diff --git a/doc/设计文档/VolPro框架改造方案_任务清单.md b/doc/设计文档/VolPro框架改造方案_任务清单.md new file mode 100644 index 0000000..91b65a0 --- /dev/null +++ b/doc/设计文档/VolPro框架改造方案_任务清单.md @@ -0,0 +1,260 @@ +# 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)` — 字段分治 + 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 播放器弹窗(