Add dashboard and latest logs endpoints for smoke tracking

- Introduced a new API endpoint `GET /api/v1/smoke/dashboard` to retrieve a summary of smoking statistics over a specified date range, including today's count and weekly breakdown.
- Added `GET /api/v1/smoke/logs/latest` endpoint to fetch the most recent smoking logs with a configurable limit.
- Updated the smoke handler and service to support the new functionality, including error handling for date parsing and limit validation.
- Enhanced documentation to reflect the new API endpoints and their usage.

internal/smoke/handler/smoke_handler.go

@@ -34,9 +34,9 @@ type createSmokeLogRequest struct {
 	SmokeTime string `json:"smoke_time"`
 	// 真实抽烟时间（精确到时分秒，可补录）
 	SmokeAt string `json:"smoke_at"`
-	Remark    string `json:"remark"`
-	Level     int64  `json:"level"`
-	Num       int    `json:"num"`
+	Remark  string `json:"remark"`
+	Level   int64  `json:"level"`
+	Num     int    `json:"num"`
 }
 
 func (h *SmokeHandler) Create(c *gin.Context) {
@@ -161,6 +161,87 @@ func (h *SmokeHandler) List(c *gin.Context) {
 	}))
 }
 
+func (h *SmokeHandler) Dashboard(c *gin.Context) {
+	user, ok := middleware.CurrentUser(c)
+	if !ok {
+		c.JSON(http.StatusUnauthorized, model.Error(http.StatusUnauthorized, "未登录或登录已过期"))
+		return
+	}
+
+	now := time.Now()
+	defaultStart, defaultEnd := defaultDashboardRange(now)
+
+	startDate := defaultStart
+	startProvided := false
+	if v := c.Query("start"); v != "" {
+		parsed, err := time.ParseInLocation(dateLayout, v, time.Local)
+		if err != nil {
+			c.JSON(http.StatusBadRequest, model.Error(http.StatusBadRequest, "start 格式错误，应为 YYYY-MM-DD"))
+			return
+		}
+		startDate = parsed
+		startProvided = true
+	}
+
+	endDate := defaultEnd
+	if v := c.Query("end"); v != "" {
+		parsed, err := time.ParseInLocation(dateLayout, v, time.Local)
+		if err != nil {
+			c.JSON(http.StatusBadRequest, model.Error(http.StatusBadRequest, "end 格式错误，应为 YYYY-MM-DD"))
+			return
+		}
+		endDate = parsed
+	} else if startProvided {
+		endDate = startDate.AddDate(0, 0, 6)
+	}
+
+	if endDate.Before(startDate) {
+		c.JSON(http.StatusBadRequest, model.Error(http.StatusBadRequest, "end 不能早于 start"))
+		return
+	}
+
+	result, err := h.smokeLogService.Dashboard(c.Request.Context(), int(user.ID), smokeservice.SmokeDashboardRequest{
+		Start: startDate,
+		End:   endDate,
+	})
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, model.Error(http.StatusInternalServerError, "获取看板概览失败，请稍后重试"))
+		return
+	}
+
+	c.JSON(http.StatusOK, model.Success(result))
+}
+
+func (h *SmokeHandler) LatestLogs(c *gin.Context) {
+	user, ok := middleware.CurrentUser(c)
+	if !ok {
+		c.JSON(http.StatusUnauthorized, model.Error(http.StatusUnauthorized, "未登录或登录已过期"))
+		return
+	}
+
+	limit, err := strconv.Atoi(c.DefaultQuery("limit", "20"))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, model.Error(http.StatusBadRequest, "limit 应为数字"))
+		return
+	}
+	if limit <= 0 {
+		limit = 20
+	}
+	if limit > 100 {
+		limit = 100
+	}
+
+	items, err := h.smokeLogService.ListLatest(c.Request.Context(), int(user.ID), limit)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, model.Error(http.StatusInternalServerError, "获取最近记录失败，请稍后重试"))
+		return
+	}
+
+	c.JSON(http.StatusOK, model.Success(gin.H{
+		"items": items,
+	}))
+}
+
 type updateSmokeLogRequest struct {
 	SmokeTime *string `json:"smoke_time"`
 	SmokeAt   *string `json:"smoke_at"`
@@ -265,3 +346,17 @@ func (h *SmokeHandler) Delete(c *gin.Context) {
 		"deleted": true,
 	}))
 }
+
+// defaultDashboardRange 返回“本周一到本周日”的日期范围，供看板默认使用。
+func defaultDashboardRange(now time.Time) (time.Time, time.Time) {
+	local := now.In(time.Local)
+	weekday := local.Weekday()
+	// 转为以周一为 0
+	daysSinceMonday := int(weekday) - int(time.Monday)
+	if daysSinceMonday < 0 {
+		daysSinceMonday += 7
+	}
+	start := time.Date(local.Year(), local.Month(), local.Day(), 0, 0, 0, 0, time.Local).AddDate(0, 0, -daysSinceMonday)
+	end := start.AddDate(0, 0, 6)
+	return start, end
+}