ProjectAGiPrompt/8-CMII-RMDC/3-rmdc-exchange-hub/5-rmdc-exchange-hub-command-time.md

RMDC-Exchange-Hub 指令执行时间计算规范

1. 概述

本文档定义了 RMDC-Exchange-Hub 模块中指令执行全生命周期的时间追踪与计算规范。

---

2. 时间点定义

2.1 指令生命周期时间点

sequenceDiagram
    participant BM as 业务模块
    participant EH as Exchange Hub
    participant MQTT as MQTT Broker
    participant WD as Watchdog
    participant EX as 执行体

    Note over EH: ① created_at<br/>指令创建时间
    BM->>EH: 发起指令请求
    
    Note over EH: ② sent_at<br/>发送到MQTT时间
    EH->>MQTT: Publish指令
    
    Note over WD: ③ acked_at<br/>Watchdog确认接收
    MQTT->>WD: 推送指令
    WD-->>EH: (可选) ACK确认
    
    Note over WD: ④ started_at<br/>开始执行时间
    WD->>EX: 调用执行体
    
    Note over EX: ⑤ start_time (ms)<br/>执行体内部开始
    EX->>EX: 执行指令...
    Note over EX: ⑥ end_time (ms)<br/>执行体内部结束
    
    EX->>WD: 返回结果
    
    Note over WD: ⑦ 消息上行
    WD->>MQTT: ExecResult上行
    
    Note over EH: ⑧ received_at<br/>Exchange Hub接收
    MQTT->>EH: 推送结果
    
    Note over EH: ⑨ completed_at<br/>指令完成时间

2.2 时间点存储位置

时间点	字段名	存储表	类型	说明
指令创建	created_at	command_trackers	TIMESTAMP	自动记录
发送到MQTT	sent_at	command_trackers	TIMESTAMP	调用MQTT Publish时记录
Watchdog确认	acked_at	command_trackers	TIMESTAMP	收到ACK消息时记录
开始执行	started_at	command_trackers	TIMESTAMP	收到running状态时记录
执行开始(内部)	start_time	command_results	INT64 (ms)	Watchdog侧记录
执行结束(内部)	end_time	command_results	INT64 (ms)	Watchdog侧记录
结果接收	received_at	command_results	TIMESTAMP	Exchange Hub接收结果时记录
指令完成	completed_at	command_trackers	TIMESTAMP	更新为终态时记录

---

3. 时间耗时计算公式

3.1 核心耗时指标

指标名称	计算公式	单位	含义
指令下发耗时	acked_at - sent_at	ms	指令从Exchange Hub到达Watchdog的网络耗时
指令执行耗时	end_time - start_time (或 duration)	ms	指令在执行体内的实际执行时间
指令上行耗时	received_at - end_time	ms	执行结果从Watchdog返回Exchange Hub的耗时
总体耗时	completed_at - sent_at	ms	从发送到完成的总时间

3.2 扩展耗时指标

指标名称	计算公式	单位	含义
排队耗时	sent_at - created_at	ms	指令在Exchange Hub等待发送的时间
处理准备耗时	started_at - acked_at	ms	Watchdog接收到开始执行的准备时间

---

4. 数据结构定义

4.1 CommandTracker 时间字段

type CommandTracker struct {
    // ... 其他字段 ...
    
    // 时间追踪字段
    SentAt      *time.Time // 发送到MQTT时间戳
    AckedAt     *time.Time // Watchdog确认接收时间戳  
    StartedAt   *time.Time // 开始执行时间戳
    CompletedAt *time.Time // 完成时间戳
    CreatedAt   time.Time  // 创建时间
    TimeoutAt   *time.Time // 超时时间
}

4.2 CommandResult 时间字段

type CommandResult struct {
    // ... 其他字段 ...
    
    // 执行时间字段 (来自Watchdog)
    StartTime  int64     // 执行开始时间戳(ms)
    EndTime    int64     // 执行结束时间戳(ms)
    Duration   int64     // 执行时长(ms)
    
    // 上行时间字段 (Exchange Hub记录)
    ReceivedAt     time.Time // 结果接收时间
    UploadDuration int64     // 上行耗时(ms) = ReceivedAt - EndTime
}

4.3 时间详情DTO

// CommandTimeDurations 指令时间耗时详情
type CommandTimeDurations struct {
    DeliveryDuration      int64  `json:"delivery_duration"`       // 下发耗时(ms)
    ExecDuration          int64  `json:"exec_duration"`           // 执行耗时(ms)
    UploadDuration        int64  `json:"upload_duration"`         // 上行耗时(ms)
    TotalDuration         int64  `json:"total_duration"`          // 总体耗时(ms)
    QueueDuration         int64  `json:"queue_duration,omitempty"` // 排队耗时(ms)
}

---

5. API响应格式

5.1 查询指令响应增强

{
    "code": 0,
    "message": "success",
    "data": {
        "command_id": "k8s_exec-proj_001-241222114530",
        "project_id": "proj_001",
        "status": "success",
        "created_at": "2024-12-22 11:45:30",
        "completed_at": "2024-12-22 11:45:35",
        "time_durations": {
            "delivery_duration": 150,
            "exec_duration": 4500,
            "upload_duration": 120,
            "total_duration": 4850
        },
        "result": { ... }
    }
}

5.2 同步指令响应

{
    "code": 0,
    "message": "success",
    "data": {
        "command_id": "k8s_exec-proj_001-241222114530",
        "status": "success",
        "exit_code": 0,
        "output": "...",
        "duration": 4500,
        "time_durations": {
            "delivery_duration": 150,
            "exec_duration": 4500,
            "upload_duration": 120,
            "total_duration": 4850
        }
    }
}

---

6. 计算实现伪代码

// CalculateCommandDurations 计算指令时间耗时
func CalculateCommandDurations(
    tracker *entity.CommandTracker,
    result *entity.CommandResult,
) *dto.CommandTimeDurations {
    durations := &dto.CommandTimeDurations{}
    
    // 1. 下发耗时
    if tracker.SentAt != nil && tracker.AckedAt != nil {
        durations.DeliveryDuration = tracker.AckedAt.Sub(*tracker.SentAt).Milliseconds()
    }
    
    // 2. 执行耗时 (优先使用Watchdog计算值)
    if result != nil && result.Duration > 0 {
        durations.ExecDuration = result.Duration
    } else if result != nil && result.StartTime > 0 && result.EndTime > 0 {
        durations.ExecDuration = result.EndTime - result.StartTime
    }
    
    // 3. 上行耗时
    if result != nil && result.EndTime > 0 {
        receivedAtMs := result.ReceivedAt.UnixMilli()
        durations.UploadDuration = receivedAtMs - result.EndTime
    }
    
    // 4. 总体耗时
    if tracker.SentAt != nil && tracker.CompletedAt != nil {
        durations.TotalDuration = tracker.CompletedAt.Sub(*tracker.SentAt).Milliseconds()
    }
    
    // 5. 排队耗时 (可选)
    if tracker.SentAt != nil {
        durations.QueueDuration = tracker.SentAt.Sub(tracker.CreatedAt).Milliseconds()
    }
    
    return durations
}

---

7. 注意事项

1. 时区统一: 所有时间必须使用统一时区 (Asia/Shanghai, UTC+8)
2. 精度要求: 毫秒级精度，int64存储
3. 空值处理: 计算时需检查时间字段是否为nil
4. Watchdog时间: start_time/end_time 由Watchdog本地时间生成，可能存在时钟偏差