xiamen-sb/计时器接口请求参数文档.md

计时器管理接口请求参数文档

接口基础信息

• 基础URL: /timer
• 控制器: TimerRecordController
• 功能描述: 设备计时器相关接口，支持开始、暂停、恢复、停止计时等操作

接口列表

1. 开始计时

接口地址: POST /timer/start
功能描述: 启动指定设备的计时器

请求参数

参数名	类型	必填	描述
referenceId	String	是	关联ID（设备ID或其他业务标识）

请求示例

// 请求URL
POST /timer/start?referenceId=DEVICE_001

// 或者使用JSON格式
{
  "referenceId": "DEVICE_001"
}

响应结果

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "TIMER_RECORD_001",
    "referenceId": "DEVICE_001",
    "userId": "USER_001",
    "userName": "张三",
    "startTime": "2026-02-26T10:30:00",
    "status": "RUNNING",
    "accumulatedTime": 0
  }
}

---

2. 暂停计时

接口地址: POST /timer/pause
功能描述: 暂停指定设备的计时器

请求参数

参数名	类型	必填	描述
referenceId	String	是	关联ID（设备ID或其他业务标识）

请求示例

// 请求URL
POST /timer/pause?referenceId=DEVICE_001

响应结果

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "TIMER_RECORD_001",
    "referenceId": "DEVICE_001",
    "userId": "USER_001",
    "userName": "张三",
    "startTime": "2026-02-26T10:30:00",
    "pauseTime": "2026-02-26T11:30:00",
    "status": "PAUSED",
    "accumulatedTime": 3600000
  }
}

---

3. 恢复计时

接口地址: POST /timer/resume
功能描述: 恢复指定设备的计时器

请求参数

参数名	类型	必填	描述
referenceId	String	是	关联ID（设备ID或其他业务标识）

请求示例

// 请求URL
POST /timer/resume?referenceId=DEVICE_001

响应结果

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "TIMER_RECORD_001",
    "referenceId": "DEVICE_001",
    "userId": "USER_001",
    "userName": "张三",
    "startTime": "2026-02-26T10:30:00",
    "resumeTime": "2026-02-26T11:45:00",
    "status": "RUNNING",
    "accumulatedTime": 3600000
  }
}

---

4. 停止计时

接口地址: POST /timer/stop
功能描述: 停止指定设备的计时器并保存最终累计时间

请求参数

参数名	类型	必填	描述
referenceId	String	是	关联ID（设备ID或其他业务标识）
finalAccumulatedTime	Long	是	最终累计时间(毫秒)

请求示例

// 请求URL
POST /timer/stop?referenceId=DEVICE_001&finalAccumulatedTime=7200000

// 或者使用JSON格式
{
  "referenceId": "DEVICE_001",
  "finalAccumulatedTime": 7200000
}

响应结果

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "TIMER_RECORD_001",
    "referenceId": "DEVICE_001",
    "userId": "USER_001",
    "userName": "张三",
    "startTime": "2026-02-26T10:30:00",
    "stopTime": "2026-02-26T12:30:00",
    "status": "STOPPED",
    "accumulatedTime": 7200000
  }
}

---

5. 获取计时状态

接口地址: GET /timer/status
功能描述: 查询指定设备的计时器当前状态

请求参数

参数名	类型	必填	描述
referenceId	String	是	关联ID（设备ID或其他业务标识）

请求示例

// 请求URL
GET /timer/status?referenceId=DEVICE_001

响应结果

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "TIMER_RECORD_001",
    "referenceId": "DEVICE_001",
    "userId": "USER_001",
    "userName": "张三",
    "startTime": "2026-02-26T10:30:00",
    "status": "RUNNING",
    "accumulatedTime": 5400000
  }
}

---

6. 获取累计时间

接口地址: GET /timer/accumulated-time
功能描述: 获取指定设备的累计计时时间

请求参数

参数名	类型	必填	描述
referenceId	String	是	关联ID（设备ID或其他业务标识）

请求示例

// 请求URL
GET /timer/accumulated-time?referenceId=DEVICE_001

响应结果

{
  "code": 0,
  "message": "success",
  "data": 7200000
}

状态码说明

状态码	说明
RUNNING	正在计时
PAUSED	已暂停
STOPPED	已停止

时间格式说明

• 时间单位: 毫秒(ms)
• 时间计算:
  • 1秒 = 1000毫秒
  • 1分钟 = 60000毫秒
  • 1小时 = 3600000毫秒
• 时间显示建议: 前端可将毫秒转换为 HH:mm:ss 格式显示

错误处理

常见错误响应格式：

{
  "code": 1,
  "message": "错误描述信息",
  "data": null
}

使用注意事项

1. 所有接口都需要用户认证（OAuth2）
2. referenceId 应该是全局唯一的业务标识
3. 建议在页面加载时先调用状态查询接口获取当前计时状态
4. 前端应实时更新累计时间显示（可通过轮询或WebSocket实现）
5. 停止计时时，finalAccumulatedTime 应该是前端计算的最终时间

前端集成建议

// 示例：计时器前端逻辑
class TimerManager {
  constructor(deviceId) {
    this.deviceId = deviceId;
    this.timer = null;
    this.displayTime = 0;
  }
  
  // 开始计时
  async startTimer() {
    const response = await fetch(`/timer/start?referenceId=${this.deviceId}`, {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer ' + getToken()
      }
    });
    const result = await response.json();
    if (result.code === 0) {
      this.startLocalTimer();
    }
  }
  
  // 本地计时器（用于实时显示）
  startLocalTimer() {
    this.timer = setInterval(() => {
      this.displayTime += 1000;
      this.updateDisplay();
    }, 1000);
  }
  
  // 更新显示
  updateDisplay() {
    const hours = Math.floor(this.displayTime / 3600000);
    const minutes = Math.floor((this.displayTime % 3600000) / 60000);
    const seconds = Math.floor((this.displayTime % 60000) / 1000);
    document.getElementById('timer-display').textContent = 
      `${hours.toString().padStart(2, '0')}:${minutes.toString().padStart(2, '0')}:${seconds.toString().padStart(2, '0')}`;
  }
}