feat(log): decouple log storage from ClickHouse with switchable logstore

- New internal/repository/logstore abstraction: exported domain interfaces
  (AccessLogStore/ObservabilityStore/UserAccessLogStore/StatusStore),
  config-driven provider (Active/Build/Migrating/SetConfigReader), GORM
  implementation for PostgreSQL/SQLite (incl. hourly rollups computed in
  real time, migration listers, PG partition maintenance), and a ClickHouse
  wrapper preserving the native batch path; repository facade delegates to
  logstore; import-lint test enforces apps never import analyticsrepo.
- ClickHouse is now optional: the log DB is either the main DB (postgres
  when database.enabled, else sqlite) or clickhouse; boot validation +
  first-run seed; log_database / log_db_migration are protected keys.
- New user task 切换日志数据库 (of_log_db_switch): freeze log writes,
  drain batch writers, copy all 6 raw log tables by id (preserving IDs)
  with target-partition pre-creation for PG, flip log_database on success,
  clear the freeze flag on failure.
- Per-store retention (log_retention_days_*) with expiry cleanup folded
  into the daily system_cleanup task; legacy database_auto_cleanup_* and
  of_database_auto_cleanup decommissioned.
- goose migrations: 6 log tables in PG (2 monthly-partitioned) + SQLite,
  retention config seeds, schedule cleanup; GET
  /api/v1/admin/status/log-database endpoint; frontend retention settings,
  switch-task UI and status badge; changelog and docs updated.

docs(plan): log database decoupling implementation plan

docs(design): log database decoupling design (ClickHouse optional)

internal/apps/admin/status/clickhouse.go

@@ -4,43 +4,117 @@
 package status
 
 import (
+	"context"
 	"net/http"
 
 	"github.com/Rain-kl/Wavelet/internal/apps/openflare/chwriter"
 	"github.com/Rain-kl/Wavelet/internal/apps/risk_control"
 	"github.com/Rain-kl/Wavelet/internal/infra/config"
-	db "github.com/Rain-kl/Wavelet/internal/infra/persistence"
 	"github.com/Rain-kl/Wavelet/internal/infra/persistence/batchwriter"
-	analyticsrepo "github.com/Rain-kl/Wavelet/internal/repository/analytics"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	analyticsmodel "github.com/Rain-kl/Wavelet/internal/model/analytics"
+	"github.com/Rain-kl/Wavelet/internal/repository"
+	"github.com/Rain-kl/Wavelet/internal/repository/logstore"
 	"github.com/Rain-kl/Wavelet/internal/shared/response"
+	"github.com/Rain-kl/Wavelet/pkg/logger"
 	"github.com/gin-gonic/gin"
 )
 
-// GetClickHouseStatus returns ClickHouse operational metrics for administrators.
-// @Summary 获取 ClickHouse 运行指标
-// @Description 返回 ClickHouse parts、mutation、async_insert 队列及进程内 batch writer 指标，需要管理员权限
+// 日志库名取值（与 model 配置值、logstore provider 分支保持一致）。
+const (
+	logDBNamePostgres   = "postgres"
+	logDBNameSQLite     = "sqlite"
+	logDBNameClickHouse = "clickhouse"
+)
+
+// defaultLogRetentionDays 日志保留天数配置缺失时的兜底值（与 seed 默认一致）。
+const defaultLogRetentionDays = 90
+
+// LogDatabaseStatus 日志库状态。
+type LogDatabaseStatus struct {
+	ActiveDatabase   string                                     `json:"active_database"`
+	Migration        string                                     `json:"migration"` // idle | migrating
+	RetentionDays    map[string]int                             `json:"retention_days"`
+	AvailableTargets []string                                   `json:"available_targets"`
+	ClickHouse       *analyticsmodel.ClickHouseOperationalStats `json:"clickhouse,omitempty"`
+}
+
+// GetLogDatabaseStatus 返回当前日志库状态。
+// @Summary 获取日志数据库状态
+// @Description 返回当前日志主库、迁移状态、各库保留天数与合法迁移目标，需要管理员权限
 // @Tags admin
 // @Produce json
 // @Security SessionCookie
-// @Success 200 {object} response.Any{data=analyticsrepo.ClickHouseOperationalStats} "获取成功"
-// @Failure 400 {object} response.Any "ClickHouse 未启用"
+// @Success 200 {object} response.Any{data=status.LogDatabaseStatus} "获取成功"
 // @Failure 401 {object} response.Any "未登录"
 // @Failure 403 {object} response.Any "无管理员权限"
 // @Failure 500 {object} response.Any "内部错误"
-// @Router /api/v1/admin/status/clickhouse [get]
-func GetClickHouseStatus(c *gin.Context) {
-	if !config.Config.ClickHouse.Enabled || !db.ChConnReady() {
-		response.AbortWithError(c, http.StatusBadRequest, "ClickHouse 存储服务未启用")
+// @Router /api/v1/admin/status/log-database [get]
+func GetLogDatabaseStatus(c *gin.Context) {
+	ctx := c.Request.Context()
+	store, err := logstore.Active(ctx)
+	if err != nil {
+		response.AbortInternal(c, "日志存储初始化失败")
 		return
 	}
 
-	stats, err := analyticsrepo.GetClickHouseOperationalStats(c.Request.Context())
+	// 分支判定复用同一 store 实例的 ActiveDatabase，避免与 Active 解析之间出现 TOCTOU。
+	activeDB, err := store.Status.ActiveDatabase(ctx)
 	if err != nil {
-		response.AbortInternal(c, "获取 ClickHouse 运行指标失败")
+		response.AbortInternal(c, "获取日志库状态失败")
 		return
 	}
-	stats.BatchWriters = collectBatchWriterStats()
-	c.JSON(http.StatusOK, response.OK(stats))
+	migration := "idle"
+	if logstore.Migrating(ctx) {
+		migration = "migrating"
+	}
+
+	out := LogDatabaseStatus{
+		ActiveDatabase: activeDB,
+		Migration:      migration,
+		RetentionDays: map[string]int{
+			logDBNamePostgres:   retentionOr(ctx, model.ConfigKeyLogRetentionDaysPostgres),
+			logDBNameSQLite:     retentionOr(ctx, model.ConfigKeyLogRetentionDaysSQLite),
+			logDBNameClickHouse: retentionOr(ctx, model.ConfigKeyLogRetentionDaysClickHouse),
+		},
+		AvailableTargets: availableTargets(activeDB),
+	}
+
+	if activeDB == logDBNameClickHouse {
+		stats, err := store.Status.ClickHouseOperationalStats(ctx)
+		if err != nil {
+			logger.ErrorF(ctx, "获取 ClickHouse 运行指标失败: %v", err)
+		} else {
+			stats.BatchWriters = collectBatchWriterStats()
+			out.ClickHouse = stats
+		}
+	}
+
+	c.JSON(http.StatusOK, response.OK(out))
+}
+
+// retentionOr 读取保留天数配置，缺失或非法时返回默认值。
+func retentionOr(ctx context.Context, key string) int {
+	v, err := repository.GetIntByKey(ctx, key)
+	if err != nil {
+		return defaultLogRetentionDays
+	}
+	return v
+}
+
+// availableTargets 返回当前日志主库的合法迁移目标（复用调用方已解析的 active）：
+// 当前为 clickhouse 时目标为主库（postgres/sqlite 按启动配置）；当前为主库时目标为 clickhouse（仅 CH 启用时）。
+func availableTargets(active string) []string {
+	if active == logDBNameClickHouse {
+		if config.Config.Database.Enabled {
+			return []string{logDBNamePostgres}
+		}
+		return []string{logDBNameSQLite}
+	}
+	if config.Config.ClickHouse.Enabled {
+		return []string{logDBNameClickHouse}
+	}
+	return []string{}
 }
 
 func collectBatchWriterStats() []batchwriter.Stats {

internal/apps/admin/status/clickhouse_test.go

@@ -0,0 +1,115 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package status
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"reflect"
+	"testing"
+
+	"github.com/Rain-kl/Wavelet/internal/infra/config"
+	"github.com/Rain-kl/Wavelet/internal/repository/logstore"
+	"github.com/gin-gonic/gin"
+)
+
+// restoreConfig 恢复测试中临时修改的全局配置。
+func restoreConfig(t *testing.T) {
+	t.Helper()
+	dbEnabled := config.Config.Database.Enabled
+	chEnabled := config.Config.ClickHouse.Enabled
+	t.Cleanup(func() {
+		config.Config.Database.Enabled = dbEnabled
+		config.Config.ClickHouse.Enabled = chEnabled
+	})
+}
+
+func TestAvailableTargets(t *testing.T) {
+	restoreConfig(t)
+	logstore.ResetForTest()
+	t.Cleanup(logstore.ResetForTest)
+
+	// 当前 clickhouse → 主库（postgres/sqlite 按启动配置）。
+	logstore.SetConfigReader(func(_ context.Context, key string) (string, error) {
+		if key == "log_database" {
+			return logDBNameClickHouse, nil
+		}
+		return "", nil
+	})
+	config.Config.Database.Enabled = true
+	config.Config.ClickHouse.Enabled = true
+	if got := availableTargets(logDBNameClickHouse); !reflect.DeepEqual(got, []string{logDBNamePostgres}) {
+		t.Fatalf("clickhouse active + postgres main: got %v, want [postgres]", got)
+	}
+
+	config.Config.Database.Enabled = false
+	if got := availableTargets(logDBNameClickHouse); !reflect.DeepEqual(got, []string{logDBNameSQLite}) {
+		t.Fatalf("clickhouse active + sqlite main: got %v, want [sqlite]", got)
+	}
+
+	// 当前主库 → clickhouse（CH 启用时）。
+	logstore.SetConfigReader(func(_ context.Context, key string) (string, error) {
+		if key == "log_database" {
+			return logDBNamePostgres, nil
+		}
+		return "", nil
+	})
+	config.Config.ClickHouse.Enabled = true
+	if got := availableTargets(logDBNamePostgres); !reflect.DeepEqual(got, []string{logDBNameClickHouse}) {
+		t.Fatalf("postgres active: got %v, want [clickhouse]", got)
+	}
+
+	// CH 禁用时排除 clickhouse。
+	config.Config.ClickHouse.Enabled = false
+	if got := availableTargets(logDBNamePostgres); len(got) != 0 {
+		t.Fatalf("CH disabled: got %v, want empty", got)
+	}
+}
+
+// TestGetLogDatabaseStatusSmoke 覆盖 handler 的 CH 激活分支（无需 DB/CH 连接）。
+func TestGetLogDatabaseStatusSmoke(t *testing.T) {
+	restoreConfig(t)
+	logstore.ResetForTest()
+	t.Cleanup(logstore.ResetForTest)
+
+	logstore.SetConfigReader(func(_ context.Context, key string) (string, error) {
+		if key == "log_database" {
+			return logDBNameClickHouse, nil
+		}
+		return "", nil
+	})
+
+	gin.SetMode(gin.TestMode)
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest(http.MethodGet, "/api/v1/admin/status/log-database", nil)
+
+	GetLogDatabaseStatus(c)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status code = %d, want 200; body=%s", w.Code, w.Body.String())
+	}
+	var resp struct {
+		Data LogDatabaseStatus `json:"data"`
+	}
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("unmarshal body: %v", err)
+	}
+	if resp.Data.ActiveDatabase != logDBNameClickHouse {
+		t.Fatalf("active_database = %q, want clickhouse", resp.Data.ActiveDatabase)
+	}
+	if resp.Data.Migration != "idle" {
+		t.Fatalf("migration = %q, want idle", resp.Data.Migration)
+	}
+	for _, key := range []string{logDBNamePostgres, logDBNameSQLite, logDBNameClickHouse} {
+		if got := resp.Data.RetentionDays[key]; got != defaultLogRetentionDays {
+			t.Fatalf("retention_days[%s] = %d, want default %d", key, got, defaultLogRetentionDays)
+		}
+	}
+	if got := resp.Data.AvailableTargets; !reflect.DeepEqual(got, []string{logDBNameSQLite}) {
+		t.Fatalf("available_targets = %v, want [sqlite] (test main DB disabled)", got)
+	}
+}