上传源代码版本
This commit is contained in:
Im-Jenisson
164
.trae/documents/ops_monitor_dashboard_verification_plan.md
Normal file
164
.trae/documents/ops_monitor_dashboard_verification_plan.md
Normal file
@@ -0,0 +1,164 @@
|
||||
# 运维监控看板 — 现状核查与验证计划
|
||||
|
||||
## 背景
|
||||
|
||||
本轮会话目标：在 `batch_query.html` 数据看板中新增「📈 运维监控」Tab，通过调用存储过程 `sp_GetOperationsMonitor()` 将每日运营监控数据展示在界面上，且不影响其他模块。
|
||||
|
||||
经核查，上一轮会话已完成全部代码实现，**无需重复开发**。本计划仅针对「核查发现的问题」进行修复和补充。
|
||||
|
||||
---
|
||||
|
||||
## 一、已完成内容（已核实，无需修改）
|
||||
|
||||
| 层级 | 文件 | 状态 |
|
||||
|------|------|------|
|
||||
| 数据库层 | `database/migrations/003_add_join_indexes.sql` | ✅ 已建 |
|
||||
| 数据库层 | `database/migrations/004_create_sp_operations_monitor.sql`（472行） | ✅ 已建 |
|
||||
| 调用入口 | `运营监控_优化版.sql` | ✅ 已建 |
|
||||
| DTO | `src/MDL/DTOs/OpsMonitorDto.cs` | ✅ 已建（13个字段） |
|
||||
| Repository 接口 | `src/DAL/Interfaces/ILabelReplaceRepository.cs` 第171行 | ✅ 已追加 |
|
||||
| Repository 实现 | `src/DAL/repositories/LabelReplaceRepository.cs`（第1664-1702行） | ✅ 已实现 |
|
||||
| Service 接口 | `src/BLL/Interfaces/ILabelReplaceService.cs` 第134行 | ✅ 已追加 |
|
||||
| Service 实现 | `src/BLL/Services/LabelReplaceService.cs`（第1044-1055行） | ✅ 已实现 |
|
||||
| Controller | `src/CONTROLLER/Controllers/DashboardController.cs`（第368-414行） | ✅ 已追加 |
|
||||
| 前端 Tab 按钮 | `batch_query.html` 第786行 | ✅ 已追加 |
|
||||
| 前端 Tab 面板 | `batch_query.html` 第1819-1884行（4卡片+13列表格） | ✅ 已追加 |
|
||||
| 前端 JS 逻辑 | `batch_query.html` 第4745-4867行 | ✅ 已追加 |
|
||||
|
||||
---
|
||||
|
||||
## 二、当前核查发现的问题
|
||||
|
||||
### 问题1：`loadOpsMonitorData()` 使用 JSONP，但同域部署时更推荐直接 JSON
|
||||
|
||||
**发现**：前端 `loadOpsMonitorData()` 使用 `dataType: 'jsonp'`，如果 `batch_query.html` 与后端同域部署，JSONP 会正常工作（后端已支持 callback 参数），但如果浏览器从本地 `file://` 协议打开，JSONP 会由于浏览器安全限制失败。
|
||||
|
||||
**当前后端**：`DashboardController.GetOpsMonitorData` 已支持 JSONP（`callback` 参数）和直接 JSON 两种模式。
|
||||
|
||||
**结论**：JSONP 模式在同域或跨域部署时均可工作，不影响功能。**无需修改**。
|
||||
|
||||
---
|
||||
|
||||
### 问题2：`loadOpsMonitorData()` 中 `_opsMonitorLoaded = true` 设置时机
|
||||
|
||||
**发现**：`_opsMonitorLoaded` 在请求成功后设为 `true`，意味着只要成功加载过一次，切换 Tab 不再自动重新加载（懒加载设计）。用户可通过「🔄 刷新数据」按钮手动刷新。
|
||||
|
||||
**结论**：这是预期的懒加载行为，符合其他 Tab 的设计模式。**无需修改**。
|
||||
|
||||
---
|
||||
|
||||
### 问题3（需要确认）：`data[0]` 作为「今日」数据的假设
|
||||
|
||||
**发现**：`displayOpsMonitorTable(data)` 中用 `var today = data[0]` 作为今日汇总卡片数据来源，依赖存储过程 `ORDER BY dm.日期 DESC` 返回最新数据在第一行。
|
||||
|
||||
**存储过程末尾**：已确认使用 `ORDER BY dm.日期 DESC`，第一行确实是最新日期数据。**逻辑正确，无需修改**。
|
||||
|
||||
---
|
||||
|
||||
### 问题4（需要修复）：`data[0]` 的字段名大小写
|
||||
|
||||
**发现**：前端 JS 中使用 `today.ShouldReplaceCount`、`today.DailySuccessCount` 等驼峰命名，但 ASP.NET Core 默认的 `System.Text.Json` 序列化器使用**属性原始名称（PascalCase）**，而非 camelCase。
|
||||
|
||||
**后端 DTO 字段**（以 PascalCase 定义）：
|
||||
```csharp
|
||||
public string Date { get; set; }
|
||||
public int ShouldReplaceCount { get; set; }
|
||||
// ...
|
||||
```
|
||||
|
||||
**ASP.NET Core 默认行为**：`System.Text.Json.JsonSerializer.Serialize()` 默认保留 PascalCase，即 JSON 输出为 `ShouldReplaceCount`，与前端 `today.ShouldReplaceCount` 一致。
|
||||
|
||||
**结论**：字段名匹配，**无需修改**。
|
||||
|
||||
---
|
||||
|
||||
## 三、实施步骤
|
||||
|
||||
由于核查未发现需要修复的代码问题，本计划的实施步骤聚焦于**确保代码完整性**：
|
||||
|
||||
### 步骤 1：确认 batch_query.html Tab 结构完整
|
||||
- 验证第786行 Tab 按钮代码存在且格式正确
|
||||
- 验证第1819-1884行 Tab 面板代码完整
|
||||
- 验证第4745-4867行 JS 函数完整
|
||||
|
||||
### 步骤 2：确认后端三层代码完整
|
||||
- 确认 `OpsMonitorDto.cs` 命名空间为 `MDL.DTOs`（已修复）
|
||||
- 确认 `DashboardController.cs` 顶部有 `using MDL.DTOs;`（已修复）
|
||||
- 确认无编译诊断错误
|
||||
|
||||
### 步骤 3：确认存储过程文件完整
|
||||
- `004_create_sp_operations_monitor.sql`（472行）结构完整，含 DELIMITER 和 END$$
|
||||
|
||||
---
|
||||
|
||||
## 四、数据流架构图
|
||||
|
||||
```
|
||||
浏览器 batch_query.html
|
||||
│
|
||||
│ 切换到「📈 运维监控」Tab（首次触发懒加载）
|
||||
│ 或点击「🔄 刷新数据」按钮
|
||||
│
|
||||
↓ GET /api/dashboard/ops-monitor?callback=jQuery_xxx (JSONP)
|
||||
│
|
||||
ASP.NET Core DashboardController.GetOpsMonitorData()
|
||||
│
|
||||
↓ await _labelReplaceService.GetOpsMonitorDataAsync()
|
||||
│
|
||||
LabelReplaceService.GetOpsMonitorDataAsync()
|
||||
│
|
||||
↓ await _labelReplaceRepository.GetOpsMonitorDataAsync()
|
||||
│
|
||||
LabelReplaceRepository（直接使用 MySqlConnection）
|
||||
│
|
||||
↓ CALL sp_GetOperationsMonitor(); (CommandTimeout=120s)
|
||||
│
|
||||
MySQL 8.0 存储过程
|
||||
│ 临时表链路：
|
||||
│ tmp_scan_agg → tmp_daily_scan → tmp_form_order
|
||||
│ → tmp_form_first_scan → tmp_form_stats
|
||||
│ → tmp_form_push_ranked → tmp_order_full
|
||||
│ → tmp_should_replace_dedup → tmp_label_push → tmp_daily_metrics
|
||||
│
|
||||
↓ SELECT 13列数据 ORDER BY 日期 DESC
|
||||
│
|
||||
List<OpsMonitorDto> → JSON → JSONP 包装
|
||||
│
|
||||
↓ 返回浏览器
|
||||
│
|
||||
displayOpsMonitorTable(data)
|
||||
│ ├─ 4张汇总卡片（今日应换单数/完成数/24H成功数/完成率）
|
||||
│ └─ 13列历史数据表格（完成率≥80%绿色/＜50%红色）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、不影响其他模块的保证
|
||||
|
||||
1. **Tab 按钮**：独立 `<li>` 元素追加到导航栏末尾，不修改现有 Tab
|
||||
2. **Tab 面板**：独立 `<div class="tab-pane">` 追加，不修改现有面板
|
||||
3. **JS 函数**：`loadOpsMonitorData`、`displayOpsMonitorTable`、`exportOpsMonitorToExcel` 均为新增，无同名冲突
|
||||
4. **变量名**：`_opsMonitorLoaded`、`_opsMonitorData` 前缀唯一，无冲突
|
||||
5. **元素 ID**：`opsMonitorTableBody`、`opsCard_*`、`opsMonitorFetchTime` 均为新增，无冲突
|
||||
6. **后端接口**：新增 `GET /api/dashboard/ops-monitor`，不修改现有接口
|
||||
7. **数据库**：存储过程 `sp_GetOperationsMonitor` 为新增，不修改现有表结构
|
||||
|
||||
---
|
||||
|
||||
## 六、部署前置条件
|
||||
|
||||
在运行前，需确保以下操作已在数据库执行：
|
||||
|
||||
```sql
|
||||
-- 1. 添加索引（003文件）
|
||||
ALTER TABLE label_replace_requests
|
||||
ADD INDEX IF NOT EXISTS idx_bill_of_lading_number (BillOfLadingNumber),
|
||||
ADD INDEX IF NOT EXISTS idx_master_package_number (MasterPackageNumber);
|
||||
|
||||
-- 2. 创建存储过程（执行 004 文件全部内容）
|
||||
-- CALL sp_GetOperationsMonitor(); -- 验证用
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**计划状态**：代码实现已全部完成，无新增修改项，仅需确认文件完整性。
|
||||
Reference in New Issue
Block a user