新增注释

internal/api/limit_board_handler.go

@@ -11,14 +11,17 @@ import (
 	"level_go/internal/service"
 )
 
+// LimitBoardHandler 承载涨停板相关 HTTP 接口。
 type LimitBoardHandler struct {
-	Service *service.LimitBoardService
+	Service *service.LimitBoardService // 涨停板服务，封装统计、分组和导出逻辑。
 }
 
+// NewLimitBoardHandler 创建涨停板接口 Handler。
 func NewLimitBoardHandler(s *service.LimitBoardService) *LimitBoardHandler {
 	return &LimitBoardHandler{Service: s}
 }
 
+// GetOverview 返回指定交易日的涨停股连板概览。
 func (h *LimitBoardHandler) GetOverview(c *gin.Context) {
 	var req model.LimitBoardRequest
 	if err := c.ShouldBindQuery(&req); err != nil || req.TradeDate == "" {
@@ -35,6 +38,7 @@ func (h *LimitBoardHandler) GetOverview(c *gin.Context) {
 	c.JSON(http.StatusOK, resp)
 }
 
+// GetOpenLowerGroups 返回昨日涨停且今日继续涨停股票的开盘对比分组。
 func (h *LimitBoardHandler) GetOpenLowerGroups(c *gin.Context) {
 	var req model.LimitBoardRequest
 	if err := c.ShouldBindQuery(&req); err != nil || req.TradeDate == "" {
@@ -51,6 +55,7 @@ func (h *LimitBoardHandler) GetOpenLowerGroups(c *gin.Context) {
 	c.JSON(http.StatusOK, resp)
 }
 
+// GetBreakNextPerformance 返回首板后次日炸板股票的 T+1 表现分页结果。
 func (h *LimitBoardHandler) GetBreakNextPerformance(c *gin.Context) {
 	req, err := parseLimitBreakNextPerformanceRequest(c, true)
 	if err != nil {
@@ -67,6 +72,9 @@ func (h *LimitBoardHandler) GetBreakNextPerformance(c *gin.Context) {
 	c.JSON(http.StatusOK, resp)
 }
 
+// parseLimitBreakNextPerformanceRequest 解析炸板次日表现接口的查询参数。
+//
+// includePagination 为 false 时跳过分页参数，供 CSV 导出复用同一套日期和过滤条件解析逻辑。
 func parseLimitBreakNextPerformanceRequest(c *gin.Context, includePagination bool) (model.LimitBreakNextPerformanceRequest, error) {
 	req := model.LimitBreakNextPerformanceRequest{
 		TradeStartDate: strings.TrimSpace(c.DefaultQuery("tradeStartDate", c.Query("start_date"))),
@@ -116,6 +124,9 @@ func parseLimitBreakNextPerformanceRequest(c *gin.Context, includePagination boo
 	return req, nil
 }
 
+// parseOptionalBoolQuery 从多个兼容参数名中读取可选布尔值。
+//
+// 返回 nil 表示用户没有传入该过滤项；返回 *bool 表示需要按 true/false 过滤。
 func parseOptionalBoolQuery(c *gin.Context, keys ...string) (*bool, error) {
 	for _, key := range keys {
 		valueText, exists := c.GetQuery(key)
@@ -135,6 +146,7 @@ func parseOptionalBoolQuery(c *gin.Context, keys ...string) (*bool, error) {
 	return nil, nil
 }
 
+// GetOpenThresholdGroups 返回昨日涨停股今日开盘是否低于前收 101% 的分组。
 func (h *LimitBoardHandler) GetOpenThresholdGroups(c *gin.Context) {
 	var req model.LimitBoardRequest
 	if err := c.ShouldBindQuery(&req); err != nil || req.TradeDate == "" {