新增注释

internal/service/limit_board_overview_service.go

@@ -6,11 +6,15 @@ import (
 	"level_go/internal/model"
 )
 
+// limitBoardHistoryRow 是连板计算所需的最小历史涨停记录。
 type limitBoardHistoryRow struct {
-	TsCode    string `gorm:"column:ts_code"`
-	TradeDate string `gorm:"column:trade_date"`
+	TsCode    string `gorm:"column:ts_code"`    // 股票代码。
+	TradeDate string `gorm:"column:trade_date"` // 涨停交易日。
 }
 
+// GetLimitBoardOverview 返回指定交易日的涨停连板概览。
+//
+// 结果包括最近 30 个交易日最高连板数、当日涨停股按连板数分组后的列表和汇总统计。
 func (s *LimitBoardService) GetLimitBoardOverview(tradeDate string) (model.LimitBoardResponse, error) {
 	resp := model.LimitBoardResponse{TradeDate: tradeDate}
 
@@ -51,6 +55,7 @@ func (s *LimitBoardService) GetLimitBoardOverview(tradeDate string) (model.Limit
 	return resp, nil
 }
 
+// buildRecentMaxBoardStats 计算最近最多 30 个交易日的每日最高连板数。
 func (s *LimitBoardService) buildRecentMaxBoardStats(tradeDates []string, dateIndex int) ([]model.LimitBoardDailyMax, error) {
 	startIndex := 0
 	if dateIndex >= 29 {
@@ -83,6 +88,7 @@ func (s *LimitBoardService) buildRecentMaxBoardStats(tradeDates []string, dateIn
 		maxBoardByDate[tradeDate] = 0
 	}
 
+	// 对每只股票在窗口内逐日回看连续涨停天数，并更新当天最高连板数。
 	for _, limitDates := range dateByCode {
 		for idx, tradeDate := range windowDates {
 			if _, ok := limitDates[tradeDate]; !ok {
@@ -114,6 +120,7 @@ func (s *LimitBoardService) buildRecentMaxBoardStats(tradeDates []string, dateIn
 	return stats, nil
 }
 
+// loadCurrentLimitStocks 查询指定交易日所有最终状态为涨停的股票。
 func (s *LimitBoardService) loadCurrentLimitStocks(tradeDate string) ([]model.LimitBoardStock, error) {
 	var stocks []model.LimitBoardStock
 	query := `SELECT
@@ -147,6 +154,7 @@ func (s *LimitBoardService) loadCurrentLimitStocks(tradeDate string) ([]model.Li
 	return stocks, err
 }
 
+// loadLimitHistory 查询指定股票集合在 tradeDate 之前及当天的涨停历史。
 func (s *LimitBoardService) loadLimitHistory(stocks []model.LimitBoardStock, tradeDate string) (map[string]map[string]struct{}, error) {
 	codes := make([]string, 0, len(stocks))
 	for _, stock := range stocks {
@@ -172,6 +180,7 @@ func (s *LimitBoardService) loadLimitHistory(stocks []model.LimitBoardStock, tra
 	return historyMap, nil
 }
 
+// buildLimitBoardGroups 计算每只股票的连板数，并按连板数构造分组映射。
 func buildLimitBoardGroups(stocks []model.LimitBoardStock, tradeDates []string, dateIndex int, historyMap map[string]map[string]struct{}) (map[int][]model.LimitBoardStock, int) {
 	groupMap := make(map[int][]model.LimitBoardStock)
 	maxBoardCount := 0
@@ -191,6 +200,7 @@ func buildLimitBoardGroups(stocks []model.LimitBoardStock, tradeDates []string,
 	return groupMap, maxBoardCount
 }
 
+// calcBoardCount 从目标交易日向前回溯，直到遇到非涨停日为止，得到连续涨停天数。
 func calcBoardCount(tradeDates []string, dateIndex int, limitDates map[string]struct{}) int {
 	boardCount := 0
 	for i := dateIndex; i >= 0; i-- {
@@ -202,6 +212,7 @@ func calcBoardCount(tradeDates []string, dateIndex int, limitDates map[string]st
 	return boardCount
 }
 
+// sortLimitBoardGroups 将连板分组按连板数倒序排列，组内按涨跌幅降序排列。
 func sortLimitBoardGroups(groupMap map[int][]model.LimitBoardStock) []model.LimitBoardGroup {
 	boardCounts := make([]int, 0, len(groupMap))
 	for boardCount := range groupMap {