# 时间处理规范

## 核心原则

所有在前端和后端之间传输、以及在数据库中存储的时间，**必须统一为东八区时间 (Asia/Shanghai, UTC+8)**。

## 指定工具库

| 端 | 工具库路径 |
|----|-----------|
| 后端 | `rmdc-common/utils/TimeUtils.go` |
| 前端 | `TonyMask/src/utils/timeUtils.ts` |

## 时间格式

- API 响应中的 `timestamp` 字段统一使用 **RFC3339** 格式
- 示例：`2024-01-15T14:30:00+08:00`

## 禁止与必须

### 禁止直接使用

```go
// ❌ 禁止
time.Now()
time.Parse(layout, value)
t.Format(layout)
```

### 必须使用工具库

```go
// ✅ 正确
TimeUtils.Now()
TimeUtils.Parse(layout, value)
TimeUtils.Format(t, layout)
```

## 常用场景示例

### 获取当前时间

```go
// ❌ 错误
now := time.Now()

// ✅ 正确
now := TimeUtils.Now()
```

### 格式化时间戳

```go
// ❌ 错误
timestamp := time.Now().Format(time.RFC3339)

// ✅ 正确
timestamp := TimeUtils.Now().Format(time.RFC3339)
```

### 解析时间字符串

```go
// ❌ 错误
t, err := time.Parse(time.RFC3339, timeStr)

// ✅ 正确
t, err := TimeUtils.Parse(time.RFC3339, timeStr)
```

### 数据库时间字段

```go
type Order struct {
    ID        int64     `gorm:"primaryKey"`
    CreatedAt time.Time `gorm:"autoCreateTime"`  // GORM 自动处理
    UpdatedAt time.Time `gorm:"autoUpdateTime"`  // GORM 自动处理
    ExpireAt  time.Time                          // 业务时间使用 TimeUtils
}

// 设置业务时间
order.ExpireAt = TimeUtils.Now().Add(24 * time.Hour)
```

### API 响应时间

```go
type Response struct {
    Code      int         `json:"code"`
    Status    int         `json:"status"`
    Timestamp string      `json:"timestamp"` // RFC3339 格式
    Data      interface{} `json:"data"`
}

// 构建响应
resp := Response{
    Timestamp: TimeUtils.Now().Format(time.RFC3339),
    // ...
}
```

## TimeUtils 常用方法

| 方法 | 说明 |
|------|------|
| `Now()` | 获取当前东八区时间 |
| `Parse(layout, value)` | 解析时间字符串（东八区） |
| `Format(t, layout)` | 格式化时间 |
| `StartOfDay(t)` | 获取当天零点 |
| `EndOfDay(t)` | 获取当天 23:59:59 |
| `AddDays(t, days)` | 增加天数 |

## 时区配置

确保服务器和数据库时区配置正确：

```go
// 数据库连接配置
dsn := "user:pass@tcp(host:3306)/db?charset=utf8mb4&parseTime=True&loc=Asia%2FShanghai"
```
