feat(clickhouse): integrate goose migrations and analytics repository

Add a separate ClickHouse OLAP pipeline with goose/clickhouse DDL as the
sole schema source, model/analytics for ORM mapping, and repository/analytics
for reads (ChDB/GORM) and batch writes (ChConn). Refactor risk_control and
admin/logs to use the repository layer instead of inline SQL. Remove the
manual support-files DDL and document the workflow in database-migration skill.

internal/apps/admin/logs/routers.go

@@ -10,15 +10,14 @@ import (
 	"encoding/json"
 	"fmt"
 	"net/http"
-	"sort"
 	"strconv"
-	"strings"
 	"time"
 
 	"github.com/Rain-kl/Wavelet/internal/apps/admin"
 	"github.com/Rain-kl/Wavelet/internal/config"
 	"github.com/Rain-kl/Wavelet/internal/db"
 	"github.com/Rain-kl/Wavelet/internal/model"
+	analyticsrepo "github.com/Rain-kl/Wavelet/internal/repository/analytics"
 	"github.com/Rain-kl/Wavelet/pkg/logger"
 	"github.com/gin-gonic/gin"
 
@@ -31,7 +30,7 @@ const (
 	maxPageSize    = 100
 	hoursInDay     = 24
 	analyticsDays  = 7
-	queryExtraArgs = 2 // pageSize + offset
+	topActiveLimit = 10
 )
 
 // logsResponse 历史日志查询响应
@@ -159,115 +158,75 @@ type accessLogsResponse struct {
 	List  []accessLogItem `json:"list"`
 }
 
-// buildAccessLogFilters 构建 ClickHouse 访问日志查询过滤条件
-func buildAccessLogFilters(ctx context.Context, c *gin.Context) ([]string, []interface{}, []uint64, error) {
-	var conditions []string
-	var args []interface{}
-	var userIDs []uint64
+func buildAccessLogFilter(ctx context.Context, c *gin.Context) (analyticsrepo.AccessLogFilter, error) {
+	filter := analyticsrepo.AccessLogFilter{}
 
-	// 按用户名过滤
 	username := c.Query("username")
 	if username != "" {
+		var userIDs []uint64
 		err := db.DB(ctx).Model(&model.User{}).
 			Where("username LIKE ?", "%"+username+"%").
 			Pluck("id", &userIDs).Error
 		if err != nil {
-			return nil, nil, nil, fmt.Errorf("查询用户信息失败: %w", err)
+			return filter, fmt.Errorf("查询用户信息失败: %w", err)
 		}
-		if len(userIDs) == 0 {
-			return nil, nil, nil, nil // 无匹配用户
-		}
-	}
-
-	if len(userIDs) > 0 {
-		placeholders := make([]string, len(userIDs))
-		for i := range userIDs {
-			placeholders[i] = "?"
-			args = append(args, userIDs[i])
-		}
-		conditions = append(conditions, fmt.Sprintf("user_id IN (%s)", strings.Join(placeholders, ",")))
+		filter.UserIDs = userIDs
 	}
 
 	if path := c.Query("path"); path != "" {
-		conditions = append(conditions, "path LIKE ?")
-		args = append(args, "%"+path+"%")
+		filter.Path = path
 	}
 
 	if startTime := c.Query("start_time"); startTime != "" {
-		if t, err := time.Parse(time.RFC3339, startTime); err == nil {
-			conditions = append(conditions, "created_at >= ?")
-			args = append(args, t)
-		} else if t, err := time.Parse("2006-01-02 15:04:05", startTime); err == nil {
-			conditions = append(conditions, "created_at >= ?")
-			args = append(args, t)
+		if t, err := parseAccessLogTime(startTime); err == nil {
+			filter.StartTime = &t
 		}
 	}
 
 	if endTime := c.Query("end_time"); endTime != "" {
-		if t, err := time.Parse(time.RFC3339, endTime); err == nil {
-			conditions = append(conditions, "created_at <= ?")
-			args = append(args, t)
-		} else if t, err := time.Parse("2006-01-02 15:04:05", endTime); err == nil {
-			conditions = append(conditions, "created_at <= ?")
-			args = append(args, t)
+		if t, err := parseAccessLogTime(endTime); err == nil {
+			filter.EndTime = &t
 		}
 	}
 
-	return conditions, args, userIDs, nil
+	return filter, nil
 }
 
-// fetchAccessLogDetails 查询 ClickHouse 访问日志明细并填充用户名
-func fetchAccessLogDetails(ctx context.Context, whereClause string, args []interface{}, pageSize int, offset int) ([]accessLogItem, error) {
-	dataQuery := fmt.Sprintf(`
-		SELECT id, user_id, path, method, ip, user_agent, headers, status, latency, created_at
-		FROM w_user_access_logs
-		%s
-		ORDER BY created_at DESC, id DESC
-		LIMIT ? OFFSET ?
-	`, whereClause)
-
-	selectArgs := make([]interface{}, len(args), len(args)+queryExtraArgs)
-	copy(selectArgs, args)
-	selectArgs = append(selectArgs, pageSize, offset)
-
-	rows, err := db.ChConn.Query(ctx, dataQuery, selectArgs...)
-	if err != nil {
-		return nil, fmt.Errorf("查询 ClickHouse 日志明细失败: %w", err)
+func parseAccessLogTime(value string) (time.Time, error) {
+	if t, err := time.Parse(time.RFC3339, value); err == nil {
+		return t, nil
 	}
-	defer func() { _ = rows.Close() }()
+	return time.Parse("2006-01-02 15:04:05", value)
+}
 
-	var list []accessLogItem
-	var fetchUserIDs []uint64
-
-	for rows.Next() {
-		var item accessLogItem
-		var createdAt time.Time
-		if err := rows.Scan(&item.ID, &item.UserID, &item.Path, &item.Method, &item.IP, &item.UserAgent, &item.Headers, &item.Status, &item.Latency, &createdAt); err != nil {
-			return nil, fmt.Errorf("读取 ClickHouse 结果失败: %w", err)
-		}
-		item.CreatedAt = createdAt.Format(time.RFC3339)
-		list = append(list, item)
-		fetchUserIDs = append(fetchUserIDs, item.UserID)
+func enrichAccessLogsWithUsers(ctx context.Context, list []accessLogItem) {
+	if len(list) == 0 {
+		return
 	}
 
-	// 反查 Postgres 关联 Username 和 Nickname
-	if len(fetchUserIDs) > 0 {
-		userMap := make(map[uint64]struct{ Username, Nickname string })
-		var users []model.User
-		if err := db.DB(ctx).Where("id IN ?", fetchUserIDs).Find(&users).Error; err == nil {
-			for _, u := range users {
-				userMap[u.ID] = struct{ Username, Nickname string }{Username: u.Username, Nickname: u.Nickname}
-			}
-		}
-		for i := range list {
-			if info, ok := userMap[list[i].UserID]; ok {
-				list[i].Username = info.Username
-				list[i].Nickname = info.Nickname
-			}
+	userIDs := make([]uint64, 0, len(list))
+	seen := make(map[uint64]struct{}, len(list))
+	for _, item := range list {
+		if _, ok := seen[item.UserID]; ok {
+			continue
 		}
+		seen[item.UserID] = struct{}{}
+		userIDs = append(userIDs, item.UserID)
 	}
 
-	return list, nil
+	userMap := make(map[uint64]struct{ Username, Nickname string })
+	var users []model.User
+	if err := db.DB(ctx).Where("id IN ?", userIDs).Find(&users).Error; err == nil {
+		for _, u := range users {
+			userMap[u.ID] = struct{ Username, Nickname string }{Username: u.Username, Nickname: u.Nickname}
+		}
+	}
+	for i := range list {
+		if info, ok := userMap[list[i].UserID]; ok {
+			list[i].Username = info.Username
+			list[i].Nickname = info.Nickname
+		}
+	}
 }
 
 // GetAccessLogs 获取 ClickHouse 异步采集的访问日志
@@ -288,13 +247,12 @@ func fetchAccessLogDetails(ctx context.Context, whereClause string, args []inter
 // @Failure 403 {object} response.Any "无管理员权限"
 // @Router /api/v1/admin/logs/access [get]
 func GetAccessLogs(c *gin.Context) {
-	// 1. 检查 ClickHouse 是否启用
-	if !config.Config.ClickHouse.Enabled || db.ChConn == nil {
+	ctx := c.Request.Context()
+	if !config.Config.ClickHouse.Enabled || db.ChDB(ctx) == nil {
 		response.AbortWithError(c, http.StatusBadRequest, "ClickHouse 存储服务未启用，无法检索访问日志")
 		return
 	}
 
-	// 2. 解析分页参数
 	page, _ := strconv.Atoi(c.DefaultQuery("page", "1"))
 	if page < 1 {
 		page = 1
@@ -306,29 +264,20 @@ func GetAccessLogs(c *gin.Context) {
 	if pageSize > maxPageSize {
 		pageSize = maxPageSize
 	}
-	offset := (page - 1) * pageSize
 
-	// 3. 构建过滤条件
-	conditions, args, userIDs, err := buildAccessLogFilters(c.Request.Context(), c)
+	filter, err := buildAccessLogFilter(ctx, c)
 	if err != nil {
 		response.AbortWithError(c, http.StatusInternalServerError, err.Error())
 		return
 	}
-	if userIDs != nil && len(userIDs) == 0 {
+	if filter.UserIDs != nil && len(filter.UserIDs) == 0 {
 		c.JSON(http.StatusOK, response.OK(accessLogsResponse{Total: 0, List: []accessLogItem{}}))
 		return
 	}
 
-	whereClause := ""
-	if len(conditions) > 0 {
-		whereClause = "WHERE " + strings.Join(conditions, " AND ")
-	}
-
-	// 4. 查询日志总数
-	var total uint64
-	countQuery := fmt.Sprintf("SELECT count() FROM w_user_access_logs %s", whereClause)
-	if err := db.ChConn.QueryRow(c.Request.Context(), countQuery, args...).Scan(&total); err != nil {
-		response.AbortWithError(c, http.StatusInternalServerError, "查询 ClickHouse 日志统计失败: "+err.Error())
+	logs, total, err := analyticsrepo.ListAccessLogs(ctx, filter, page, pageSize)
+	if err != nil {
+		response.AbortWithError(c, http.StatusInternalServerError, err.Error())
 		return
 	}
 	if total == 0 {
@@ -336,12 +285,22 @@ func GetAccessLogs(c *gin.Context) {
 		return
 	}
 
-	// 5. 分页查询明细数据
-	list, err := fetchAccessLogDetails(c.Request.Context(), whereClause, args, pageSize, offset)
-	if err != nil {
-		response.AbortWithError(c, http.StatusInternalServerError, err.Error())
-		return
+	list := make([]accessLogItem, len(logs))
+	for i, logItem := range logs {
+		list[i] = accessLogItem{
+			ID:        logItem.ID,
+			UserID:    logItem.UserID,
+			Path:      logItem.Path,
+			Method:    logItem.Method,
+			IP:        logItem.IP,
+			UserAgent: logItem.UserAgent,
+			Headers:   logItem.Headers,
+			Status:    logItem.Status,
+			Latency:   logItem.Latency,
+			CreatedAt: logItem.CreatedAt.Format(time.RFC3339),
+		}
 	}
+	enrichAccessLogsWithUsers(ctx, list)
 
 	c.JSON(http.StatusOK, response.OK(accessLogsResponse{
 		Total: total,
@@ -388,134 +347,61 @@ type logsAnalyticsResponse struct {
 // @Failure 403 {object} response.Any "无管理员权限"
 // @Router /api/v1/admin/logs/analytics [get]
 func GetLogsAnalytics(c *gin.Context) {
-	// 1. 检查 ClickHouse 是否启用
-	if !config.Config.ClickHouse.Enabled || db.ChConn == nil {
+	ctx := c.Request.Context()
+	if !config.Config.ClickHouse.Enabled || db.ChDB(ctx) == nil {
 		response.AbortWithError(c, http.StatusBadRequest, "ClickHouse 存储服务未启用，无法获取分析数据")
 		return
 	}
 
-	ctx := c.Request.Context()
-	// 7 天前 00:00:00
 	startTime := time.Now().AddDate(0, 0, -(analyticsDays - 1)).Truncate(hoursInDay * time.Hour)
 
-	trendList := queryAccessTrend(ctx, startTime)
-	browserList := queryBrowserDistribution(ctx, startTime)
-	topUsers := queryTopActiveUsers(ctx, startTime)
-
-	c.JSON(http.StatusOK, response.OK(logsAnalyticsResponse{
-		Trend:    trendList,
-		Browsers: browserList,
-		TopUsers: topUsers,
-	}))
-}
-
-// queryAccessTrend 查询最近 7 天的访问趋势
-func queryAccessTrend(ctx context.Context, startTime time.Time) []trendItem {
-	trendRows, err := db.ChConn.Query(ctx, `
-		SELECT toDate(created_at) as date, count() as count
-		FROM w_user_access_logs
-		WHERE created_at >= ?
-		GROUP BY date
-		ORDER BY date ASC
-	`, startTime)
-
-	trendMap := make(map[string]uint64)
-	for i := 0; i < analyticsDays; i++ {
-		dStr := time.Now().AddDate(0, 0, -i).Format("2006-01-02")
-		trendMap[dStr] = 0
+	trendPoints, err := analyticsrepo.GetDailyTrend(ctx, analyticsDays)
+	if err != nil {
+		response.AbortWithError(c, http.StatusInternalServerError, "查询访问趋势失败: "+err.Error())
+		return
 	}
-
-	if err == nil {
-		defer func() { _ = trendRows.Close() }()
-		for trendRows.Next() {
-			var dt time.Time
-			var cnt uint64
-			if errScan := trendRows.Scan(&dt, &cnt); errScan == nil {
-				dStr := dt.Format("2006-01-02")
-				trendMap[dStr] = cnt
-			}
+	trendList := make([]trendItem, len(trendPoints))
+	for i, point := range trendPoints {
+		trendList[i] = trendItem{
+			Date:  point.Date,
+			Count: point.Count,
 		}
 	}
 
-	var trendList []trendItem
-	for i := analyticsDays - 1; i >= 0; i-- {
-		dStr := time.Now().AddDate(0, 0, -i).Format("2006-01-02")
-		trendList = append(trendList, trendItem{
-			Date:  dStr,
-			Count: trendMap[dStr],
-		})
+	browserPoints, err := analyticsrepo.GetBrowserDistribution(ctx, startTime)
+	if err != nil {
+		response.AbortWithError(c, http.StatusInternalServerError, "查询浏览器分布失败: "+err.Error())
+		return
 	}
-	return trendList
-}
-
-// queryBrowserDistribution 查询浏览器分布排行
-func queryBrowserDistribution(ctx context.Context, startTime time.Time) []browserItem {
-	uaRows, err := db.ChConn.Query(ctx, `
-		SELECT user_agent, count() as count
-		FROM w_user_access_logs
-		WHERE created_at >= ?
-		GROUP BY user_agent
-	`, startTime)
-
-	browserCounts := make(map[string]uint64)
-	if err == nil {
-		defer func() { _ = uaRows.Close() }()
-		for uaRows.Next() {
-			var ua string
-			var cnt uint64
-			if errScan := uaRows.Scan(&ua, &cnt); errScan == nil {
-				browser := parseBrowserName(ua)
-				browserCounts[browser] += cnt
-			}
+	browserList := make([]browserItem, len(browserPoints))
+	for i, point := range browserPoints {
+		browserList[i] = browserItem{
+			Browser: point.Browser,
+			Count:   point.Count,
 		}
 	}
 
-	var browserList []browserItem
-	for b, cnt := range browserCounts {
-		browserList = append(browserList, browserItem{
-			Browser: b,
-			Count:   cnt,
-		})
+	topUserPoints, err := analyticsrepo.GetTopActiveUsers(ctx, startTime, topActiveLimit)
+	if err != nil {
+		response.AbortWithError(c, http.StatusInternalServerError, "查询活跃用户失败: "+err.Error())
+		return
 	}
-	sort.Slice(browserList, func(i, j int) bool {
-		return browserList[i].Count > browserList[j].Count
-	})
-	return browserList
-}
 
-// queryTopActiveUsers 查询活跃用户 Top 10
-func queryTopActiveUsers(ctx context.Context, startTime time.Time) []topUserItem {
-	userRows, err := db.ChConn.Query(ctx, `
-		SELECT user_id, count() as count
-		FROM w_user_access_logs
-		WHERE created_at >= ? AND user_id > 0
-		GROUP BY user_id
-		ORDER BY count DESC
-		LIMIT 10
-	`, startTime)
-
-	var topUsers []topUserItem
-	var userIDs []uint64
-	userCountMap := make(map[uint64]uint64)
-
-	if err == nil {
-		defer func() { _ = userRows.Close() }()
-		for userRows.Next() {
-			var uid uint64
-			var cnt uint64
-			if errScan := userRows.Scan(&uid, &cnt); errScan == nil {
-				userIDs = append(userIDs, uid)
-				userCountMap[uid] = cnt
-			}
+	topUsers := make([]topUserItem, len(topUserPoints))
+	userIDs := make([]uint64, len(topUserPoints))
+	for i, point := range topUserPoints {
+		topUsers[i] = topUserItem{
+			UserID: point.UserID,
+			Count:  point.Count,
 		}
+		userIDs[i] = point.UserID
 	}
 
-	// 反查 Postgres 补全活跃用户的用户名和昵称
-	userProfileMap := make(map[uint64]struct {
-		Username string
-		Nickname string
-	})
 	if len(userIDs) > 0 {
+		userProfileMap := make(map[uint64]struct {
+			Username string
+			Nickname string
+		})
 		var users []model.User
 		if errProfile := db.DB(ctx).Where("id IN ?", userIDs).Find(&users).Error; errProfile == nil {
 			for _, u := range users {
@@ -528,40 +414,17 @@ func queryTopActiveUsers(ctx context.Context, startTime time.Time) []topUserItem
 				}
 			}
 		}
+		for i := range topUsers {
+			if profile, ok := userProfileMap[topUsers[i].UserID]; ok {
+				topUsers[i].Username = profile.Username
+				topUsers[i].Nickname = profile.Nickname
+			}
+		}
 	}
 
-	for _, uid := range userIDs {
-		profile := userProfileMap[uid]
-		topUsers = append(topUsers, topUserItem{
-			UserID:   uid,
-			Username: profile.Username,
-			Nickname: profile.Nickname,
-			Count:    userCountMap[uid],
-		})
-	}
-	return topUsers
-}
-
-// parseBrowserName 简易的 User-Agent 浏览器类型识别
-func parseBrowserName(ua string) string {
-	uaLower := strings.ToLower(ua)
-	if strings.Contains(uaLower, "micromessenger") {
-		return "WeChat"
-	}
-	if strings.Contains(uaLower, "postman") {
-		return "Postman"
-	}
-	if strings.Contains(uaLower, "edg/") || strings.Contains(uaLower, "edge") {
-		return "Edge"
-	}
-	if strings.Contains(uaLower, "firefox") {
-		return "Firefox"
-	}
-	if strings.Contains(uaLower, "chrome") {
-		return "Chrome"
-	}
-	if strings.Contains(uaLower, "safari") {
-		return "Safari"
-	}
-	return "Other"
-}
+	c.JSON(http.StatusOK, response.OK(logsAnalyticsResponse{
+		Trend:    trendList,
+		Browsers: browserList,
+		TopUsers: topUsers,
+	}))
+}