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

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

## 接口列表

### 1. 开始计时
**接口地址**: `POST /timer/start`  
**功能描述**: 启动指定设备的计时器

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

#### 请求示例
```javascript
// 请求URL
POST /timer/start?referenceId=DEVICE_001

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

#### 响应结果
```json
{
  "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或其他业务标识） |

#### 请求示例
```javascript
// 请求URL
POST /timer/pause?referenceId=DEVICE_001
```

#### 响应结果
```json
{
  "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或其他业务标识） |

#### 请求示例
```javascript
// 请求URL
POST /timer/resume?referenceId=DEVICE_001
```

#### 响应结果
```json
{
  "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 | 是 | 最终累计时间(毫秒) |

#### 请求示例
```javascript
// 请求URL
POST /timer/stop?referenceId=DEVICE_001&finalAccumulatedTime=7200000

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

#### 响应结果
```json
{
  "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或其他业务标识） |

#### 请求示例
```javascript
// 请求URL
GET /timer/status?referenceId=DEVICE_001
```

#### 响应结果
```json
{
  "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或其他业务标识） |

#### 请求示例
```javascript
// 请求URL
GET /timer/accumulated-time?referenceId=DEVICE_001
```

#### 响应结果
```json
{
  "code": 0,
  "message": "success",
  "data": 7200000
}
```

## 状态码说明

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

## 时间格式说明

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

## 错误处理

常见错误响应格式：
```json
{
  "code": 1,
  "message": "错误描述信息",
  "data": null
}
```

## 使用注意事项

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

## 前端集成建议

```javascript
// 示例：计时器前端逻辑
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')}`;
  }
}
```