refactor(repository): 收敛 model/repository 分层为唯一持久化入口

将 OpenFlare 与平台业务的数据访问从 model 与 apps 直连迁入 repository，
model 仅保留实体与无 IO 规则；补充 code-check 架构守卫与开发规范。

internal/apps/openflare/agent/auth_cache.go

@@ -10,6 +10,8 @@ import (
 	"sync"
 	"time"
 
+	"github.com/Rain-kl/Wavelet/internal/repository"
+
 	"github.com/Rain-kl/Wavelet/internal/model"
 	"gorm.io/gorm"
 )
@@ -39,7 +41,7 @@ func newAccessTokenAuthCache() *accessTokenAuthCache {
 		positive:        make(map[string]cachedAgentNode),
 		negative:        make(map[string]time.Time),
 		now:             time.Now,
-		loadNodeByToken: model.GetOpenFlareNodeByAccessToken,
+		loadNodeByToken: repository.GetOpenFlareNodeByAccessToken,
 	}
 }
 

internal/apps/openflare/agent/config.go

@@ -9,14 +9,15 @@ import (
 	"errors"
 	"strings"
 
+	"github.com/Rain-kl/Wavelet/internal/repository"
+
 	"github.com/Rain-kl/Wavelet/internal/apps/openflare/pages"
-	"github.com/Rain-kl/Wavelet/internal/model"
 	openrestyrender "github.com/Rain-kl/Wavelet/pkg/render/openresty"
 	"gorm.io/gorm"
 )
 
 func getActiveConfigMeta(ctx context.Context) (*ActiveConfigMeta, error) {
-	version, err := model.GetActiveConfigVersion(ctx)
+	version, err := repository.GetActiveConfigVersion(ctx)
 	if err != nil {
 		return nil, err
 	}
@@ -27,7 +28,7 @@ func getActiveConfigMeta(ctx context.Context) (*ActiveConfigMeta, error) {
 }
 
 func getActiveConfigForAgent(ctx context.Context) (*ConfigResponse, error) {
-	version, err := model.GetActiveConfigVersion(ctx)
+	version, err := repository.GetActiveConfigVersion(ctx)
 	if err != nil {
 		return nil, err
 	}

internal/apps/openflare/agent/logics.go

@@ -9,11 +9,11 @@ import (
 	"strings"
 	"time"
 
+	"github.com/Rain-kl/Wavelet/internal/repository"
+
 	ofgeoip "github.com/Rain-kl/Wavelet/internal/apps/openflare/geoip"
 	"github.com/Rain-kl/Wavelet/internal/apps/openflare/node"
-	db "github.com/Rain-kl/Wavelet/internal/infra/persistence"
 	"github.com/Rain-kl/Wavelet/internal/model"
-	"gorm.io/gorm"
 )
 
 // RegisterWithAccessToken registers an agent on a reserved node token.
@@ -27,7 +27,7 @@ func RegisterWithAccessToken(ctx context.Context, authNode *model.OpenFlareNode,
 		return nil, err
 	}
 	applyNodeRuntime(ctx, authNode, payload, true)
-	if err := model.SaveOpenFlareNode(ctx, authNode); err != nil {
+	if err := repository.SaveOpenFlareNode(ctx, authNode); err != nil {
 		return nil, err
 	}
 	RefreshAccessTokenCache(ctx, authNode)
@@ -71,7 +71,7 @@ func RegisterWithDiscovery(ctx context.Context, payload NodePayload) (*Registrat
 	}
 	applyNodeRuntime(ctx, record, payload, false)
 
-	if err = model.CreateOpenFlareNode(ctx, record); err != nil {
+	if err = repository.CreateOpenFlareNode(ctx, record); err != nil {
 		if isUniqueConstraintError(err) {
 			return nil, errors.New(errNodeIDConflict)
 		}
@@ -115,7 +115,7 @@ func HeartbeatNode(ctx context.Context, authNode *model.OpenFlareNode, payload N
 		for field := range changes {
 			fields = append(fields, field)
 		}
-		if err := model.UpdateOpenFlareNodeFields(ctx, authNode, fields...); err != nil {
+		if err := repository.UpdateOpenFlareNodeFields(ctx, authNode, fields...); err != nil {
 			return nil, err
 		}
 	}
@@ -181,12 +181,12 @@ func ReportApplyLog(ctx context.Context, payload ApplyLogPayload) (*model.OpenFl
 		return nil, errors.New(errInvalidApplyResult)
 	}
 
-	latest, err := model.GetLatestOpenFlareApplyLogByNodeID(ctx, payload.NodeID)
+	latest, err := repository.GetLatestOpenFlareApplyLogByNodeID(ctx, payload.NodeID)
 	if err != nil {
 		return nil, err
 	}
 	if model.IsRepeatSuccessApplyLog(latest, payload.Version, payload.Checksum, payload.Result) {
-		if err := updateNodeFromApplyLog(ctx, payload, now); err != nil {
+		if err := repository.UpdateOpenFlareNodeFromApplyResult(ctx, payload.NodeID, payload.Result, payload.Version, payload.Message, now); err != nil {
 			return nil, err
 		}
 		return latest, nil
@@ -204,49 +204,12 @@ func ReportApplyLog(ctx context.Context, payload ApplyLogPayload) (*model.OpenFl
 		CreatedAt:           now,
 	}
 
-	conn := db.DB(ctx)
-	if conn == nil {
-		return nil, errors.New("database not initialized")
-	}
-
-	err = conn.Transaction(func(tx *gorm.DB) error {
-		if err := tx.Create(log).Error; err != nil {
-			return err
-		}
-		return updateNodeFromApplyLogTx(tx, payload, now)
-	})
-	if err != nil {
+	if err := repository.CreateOpenFlareApplyLogAndUpdateNode(ctx, log, payload.Result, payload.Version, payload.Message); err != nil {
 		return nil, err
 	}
 	return log, nil
 }
 
-func updateNodeFromApplyLog(ctx context.Context, payload ApplyLogPayload, now time.Time) error {
-	conn := db.DB(ctx)
-	if conn == nil {
-		return errors.New("database not initialized")
-	}
-	return conn.Transaction(func(tx *gorm.DB) error {
-		return updateNodeFromApplyLogTx(tx, payload, now)
-	})
-}
-
-func updateNodeFromApplyLogTx(tx *gorm.DB, payload ApplyLogPayload, now time.Time) error {
-	record := &model.OpenFlareNode{}
-	if err := tx.Where("node_id = ?", payload.NodeID).First(record).Error; err != nil {
-		return err
-	}
-	record.Status = nodeStatusOnline
-	record.LastSeenAt = &now
-	if payload.Result == applyResultOK {
-		record.CurrentVersion = payload.Version
-		record.LastError = ""
-	} else {
-		record.LastError = payload.Message
-	}
-	return tx.Model(record).Select("status", "last_seen_at", "current_version", "last_error").Updates(record).Error
-}
-
 // ValidateDiscoveryToken delegates to the node package discovery token helper.
 func ValidateDiscoveryToken(ctx context.Context, token string) error {
 	return node.ValidateDiscoveryToken(ctx, token)

internal/apps/openflare/agent/observability.go

@@ -10,23 +10,16 @@ import (
 	"strings"
 	"time"
 
-	db "github.com/Rain-kl/Wavelet/internal/infra/persistence"
+	"github.com/Rain-kl/Wavelet/internal/repository"
+
 	"github.com/Rain-kl/Wavelet/internal/model"
 	"go.uber.org/zap"
-	"gorm.io/gorm"
-	"gorm.io/gorm/clause"
 )
 
 const (
-	healthEventStatusActive       = "active"
-	healthEventStatusResolved     = "resolved"
-	healthSeverityInfo            = "info"
-	healthSeverityWarning         = "warning"
-	healthSeverityCritical        = "critical"
 	accessLogPathMaxLength        = 100
 	accessLogUserAgentMaxLength   = 512
 	accessLogCacheStatusMaxLength = 32
-	healthEventMessageMaxLength   = 4096
 )
 
 // PersistHeartbeatObservability stores profile, host metrics, edge health, and access logs.
@@ -43,28 +36,23 @@ func PersistHeartbeatObservability(ctx context.Context, nodeID string, payload N
 		return
 	}
 
-	conn := db.DB(ctx)
-	if conn == nil {
-		return
-	}
-
 	accessLogRecords, err := buildNodeAccessLogRecords(nodeID, payload.AccessLogs, payload.Buffered, reportedAt)
 	if err != nil {
 		zap.L().Error("build heartbeat access logs failed", zap.String("node_id", nodeID), zap.Error(err))
 		return
 	}
 
-	if err := conn.Transaction(func(tx *gorm.DB) error {
-		if err := persistNodeSystemProfile(tx, nodeID, payload.Profile, reportedAt); err != nil {
-			return err
-		}
-		if payload.HealthEvents != nil {
-			if err := reconcileNodeHealthEvents(tx, nodeID, payload.HealthEvents, reportedAt); err != nil {
-				return err
-			}
-		}
-		return nil
-	}); err != nil {
+	profile := buildNodeSystemProfileModel(nodeID, payload.Profile, reportedAt)
+	healthEvents := healthEventInputs(payload.HealthEvents)
+	if err := repository.PersistOpenFlareNodePGObservability(
+		ctx,
+		profile,
+		nodeID,
+		healthEvents,
+		payload.HealthEvents != nil,
+		reportedAt,
+		nil,
+	); err != nil {
 		zap.L().Error("persist heartbeat observability failed", zap.String("node_id", nodeID), zap.Error(err))
 		return
 	}
@@ -107,7 +95,7 @@ func persistNodeEdgeHealth(ctx context.Context, nodeID string, health *NodeEdgeH
 	if status == "" {
 		status = openrestyStatusUnknown
 	}
-	return model.InsertOpenFlareEdgeHealth(ctx, &model.OpenFlareEdgeHealth{
+	return repository.InsertOpenFlareEdgeHealth(ctx, &model.OpenFlareEdgeHealth{
 		NodeID:      nodeID,
 		CapturedAt:  timeFromUnix(health.CapturedAtUnix, reportedAt),
 		Status:      status,
@@ -115,11 +103,11 @@ func persistNodeEdgeHealth(ctx context.Context, nodeID string, health *NodeEdgeH
 	})
 }
 
-func persistNodeSystemProfile(tx *gorm.DB, nodeID string, profile *NodeSystemProfile, reportedAt time.Time) error {
+func buildNodeSystemProfileModel(nodeID string, profile *NodeSystemProfile, reportedAt time.Time) *model.OpenFlareNodeSystemProfile {
 	if profile == nil {
 		return nil
 	}
-	record := &model.OpenFlareNodeSystemProfile{
+	return &model.OpenFlareNodeSystemProfile{
 		NodeID:           nodeID,
 		Hostname:         strings.TrimSpace(profile.Hostname),
 		OSName:           strings.TrimSpace(profile.OSName),
@@ -133,23 +121,23 @@ func persistNodeSystemProfile(tx *gorm.DB, nodeID string, profile *NodeSystemPro
 		UptimeSeconds:    profile.UptimeSeconds,
 		ReportedAt:       timeFromUnix(profile.ReportedAtUnix, reportedAt),
 	}
-	return tx.Clauses(clause.OnConflict{
-		Columns: []clause.Column{{Name: "node_id"}},
-		DoUpdates: clause.AssignmentColumns([]string{
-			"hostname",
-			"os_name",
-			"os_version",
-			"kernel_version",
-			"architecture",
-			"cpu_model",
-			"cpu_cores",
-			"total_memory_bytes",
-			"total_disk_bytes",
-			"uptime_seconds",
-			"reported_at",
-			"updated_at",
-		}),
-	}).Create(record).Error
+}
+
+func healthEventInputs(events []NodeHealthEvent) []repository.OpenFlareHealthEventInput {
+	if events == nil {
+		return nil
+	}
+	out := make([]repository.OpenFlareHealthEventInput, 0, len(events))
+	for _, event := range events {
+		out = append(out, repository.OpenFlareHealthEventInput{
+			EventType:       event.EventType,
+			Severity:        event.Severity,
+			Message:         event.Message,
+			TriggeredAtUnix: event.TriggeredAtUnix,
+			Metadata:        event.Metadata,
+		})
+	}
+	return out
 }
 
 func persistNodeMetricSnapshot(ctx context.Context, nodeID string, snapshot *NodeMetricSnapshot, reportedAt time.Time) error {
@@ -168,7 +156,7 @@ func persistNodeMetricSnapshot(ctx context.Context, nodeID string, snapshot *Nod
 		DiskWriteBytes:    snapshot.DiskWriteBytes,
 		// NetworkRx/Tx no longer collected from agents; CH columns remain 0.
 	}
-	return model.InsertOpenFlareMetricSnapshot(ctx, record)
+	return repository.InsertOpenFlareMetricSnapshot(ctx, record)
 }
 
 func buildNodeAccessLogRecords(nodeID string, direct []NodeAccessLog, buffered []BufferedObservabilityRecord, reportedAt time.Time) ([]*model.OpenFlareAccessLog, error) {
@@ -234,123 +222,12 @@ func persistNodeAccessLogs(ctx context.Context, _ string, records []*model.OpenF
 	if len(records) == 0 {
 		return nil
 	}
-	return model.InsertOpenFlareAccessLogsBatch(ctx, records)
-}
-
-func reconcileNodeHealthEvents(tx *gorm.DB, nodeID string, events []NodeHealthEvent, reportedAt time.Time) error {
-	return ReconcileScopedNodeHealthEvents(tx, nodeID, events, reportedAt, nil)
+	return repository.InsertOpenFlareAccessLogsBatch(ctx, records)
 }
 
 // ReconcileScopedNodeHealthEvents reconciles health events, optionally scoped to managed event types.
-func ReconcileScopedNodeHealthEvents(tx *gorm.DB, nodeID string, events []NodeHealthEvent, reportedAt time.Time, managedEventTypes map[string]struct{}) error {
-	activeTypes := make(map[string]NodeHealthEvent, len(events))
-	for _, event := range events {
-		eventType := normalizeHealthEventType(event.EventType)
-		if eventType == "" {
-			continue
-		}
-		if len(managedEventTypes) > 0 {
-			if _, ok := managedEventTypes[eventType]; !ok {
-				continue
-			}
-		}
-		event.EventType = eventType
-		event.Severity = normalizeHealthSeverity(event.Severity)
-		if event.TriggeredAtUnix <= 0 {
-			event.TriggeredAtUnix = reportedAt.Unix()
-		}
-		activeTypes[eventType] = event
-	}
-
-	var activeEvents []*model.OpenFlareHealthEvent
-	query := tx.Where("node_id = ? AND status = ?", nodeID, healthEventStatusActive)
-	if len(managedEventTypes) > 0 {
-		scopedTypes := make([]string, 0, len(managedEventTypes))
-		for eventType := range managedEventTypes {
-			eventType = normalizeHealthEventType(eventType)
-			if eventType != "" {
-				scopedTypes = append(scopedTypes, eventType)
-			}
-		}
-		if len(scopedTypes) == 0 {
-			return nil
-		}
-		query = query.Where("event_type IN ?", scopedTypes)
-	}
-	if err := query.Find(&activeEvents).Error; err != nil {
-		return err
-	}
-
-	activeByType := make(map[string]*model.OpenFlareHealthEvent, len(activeEvents))
-	for _, event := range activeEvents {
-		activeByType[event.EventType] = event
-	}
-
-	for eventType, event := range activeTypes {
-		triggeredAt := timeFromUnix(event.TriggeredAtUnix, reportedAt)
-		if existing, ok := activeByType[eventType]; ok {
-			existing.Severity = event.Severity
-			existing.Message = normalizeHealthEventMessage(event.Message)
-			existing.LastTriggeredAt = triggeredAt
-			existing.ReportedAt = reportedAt
-			existing.MetadataJSON = marshalJSON(event.Metadata)
-			existing.ResolvedAt = nil
-			if err := tx.Save(existing).Error; err != nil {
-				return err
-			}
-			continue
-		}
-		record := &model.OpenFlareHealthEvent{
-			NodeID:           nodeID,
-			EventType:        eventType,
-			Severity:         event.Severity,
-			Status:           healthEventStatusActive,
-			Message:          normalizeHealthEventMessage(event.Message),
-			FirstTriggeredAt: triggeredAt,
-			LastTriggeredAt:  triggeredAt,
-			ReportedAt:       reportedAt,
-			MetadataJSON:     marshalJSON(event.Metadata),
-		}
-		if err := tx.Create(record).Error; err != nil {
-			return err
-		}
-	}
-
-	for _, existing := range activeEvents {
-		if _, ok := activeTypes[existing.EventType]; ok {
-			continue
-		}
-		resolvedAt := reportedAt
-		existing.Status = healthEventStatusResolved
-		existing.ReportedAt = reportedAt
-		existing.ResolvedAt = &resolvedAt
-		if err := tx.Save(existing).Error; err != nil {
-			return err
-		}
-	}
-
-	return nil
-}
-
-func normalizeHealthEventType(eventType string) string {
-	eventType = strings.TrimSpace(strings.ToLower(eventType))
-	eventType = strings.ReplaceAll(eventType, " ", "_")
-	return eventType
-}
-
-func normalizeHealthSeverity(severity string) string {
-	switch strings.ToLower(strings.TrimSpace(severity)) {
-	case healthSeverityCritical:
-		return healthSeverityCritical
-	case healthSeverityInfo:
-		return healthSeverityInfo
-	default:
-		return healthSeverityWarning
-	}
-}
-
-func normalizeHealthEventMessage(message string) string {
-	return truncateForDatabase(message, healthEventMessageMaxLength)
+func ReconcileScopedNodeHealthEvents(ctx context.Context, nodeID string, events []NodeHealthEvent, reportedAt time.Time, managedEventTypes map[string]struct{}) error {
+	return repository.ReconcileOpenFlareHealthEvents(ctx, nodeID, healthEventInputs(events), reportedAt, managedEventTypes)
 }
 
 func timeFromUnix(unixSeconds int64, fallback time.Time) time.Time {

internal/apps/openflare/agent/waf_ip_group.go

@@ -15,6 +15,8 @@ import (
 	"strconv"
 	"strings"
 
+	"github.com/Rain-kl/Wavelet/internal/repository"
+
 	"github.com/Rain-kl/Wavelet/internal/model"
 	"github.com/Rain-kl/Wavelet/pkg/protocol"
 	openrestyrender "github.com/Rain-kl/Wavelet/pkg/render/openresty"
@@ -96,7 +98,7 @@ func buildAgentWAFIPGroups(ctx context.Context, ids []uint) ([]WAFIPGroup, error
 		return []WAFIPGroup{}, nil
 	}
 	sort.Slice(ids, func(i, j int) bool { return ids[i] < ids[j] })
-	groups, err := model.ListOpenFlareWAFIPGroupsByIDs(ctx, ids)
+	groups, err := repository.ListOpenFlareWAFIPGroupsByIDs(ctx, ids)
 	if err != nil {
 		return nil, err
 	}
@@ -158,7 +160,7 @@ func checksumAgentWAFIPGroup(group WAFIPGroup) string {
 }
 
 func activeConfigWAFIPGroupIDs(ctx context.Context) ([]uint, error) {
-	version, err := model.GetActiveConfigVersion(ctx)
+	version, err := repository.GetActiveConfigVersion(ctx)
 	if err != nil {
 		if isActiveConfigNotFound(err) {
 			return []uint{}, nil

internal/apps/openflare/agent/waf_ip_group_test.go

@@ -10,6 +10,8 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/Rain-kl/Wavelet/internal/repository"
+
 	db "github.com/Rain-kl/Wavelet/internal/infra/persistence"
 	"github.com/Rain-kl/Wavelet/internal/model"
 	"github.com/Rain-kl/Wavelet/pkg/protocol"
@@ -124,7 +126,7 @@ func TestChangedWAFIPGroupsForAgentDiscoversGraphReferences(t *testing.T) {
 		Enabled: true,
 		IPList:  `["192.0.2.88"]`,
 	}
-	require.NoError(t, model.CreateOpenFlareWAFIPGroup(ctx, ipGroup))
+	require.NoError(t, repository.CreateOpenFlareWAFIPGroup(ctx, ipGroup))
 	seedActiveConfigWithWAFGraphIPGroup(t, ctx, ipGroup.ID)
 
 	groups, err := ChangedWAFIPGroupsForAgent(ctx, nil, nil)
@@ -163,7 +165,7 @@ func TestChangedWAFIPGroupsForAgentRejectsOversizedSnapshotBeforeChecksumDelta(t
 		Enabled: true,
 		IPList:  `[]`,
 	}
-	require.NoError(t, model.CreateOpenFlareWAFIPGroup(ctx, ipGroup))
+	require.NoError(t, repository.CreateOpenFlareWAFIPGroup(ctx, ipGroup))
 	agentGroup, err := buildAgentWAFIPGroup(ipGroup)
 	require.NoError(t, err)
 
@@ -185,7 +187,7 @@ func TestChangedWAFIPGroupsForAgentReturnsChecksumDelta(t *testing.T) {
 		Enabled: true,
 		IPList:  `["203.0.113.44"]`,
 	}
-	require.NoError(t, model.CreateOpenFlareWAFIPGroup(ctx, ipGroup))
+	require.NoError(t, repository.CreateOpenFlareWAFIPGroup(ctx, ipGroup))
 	seedActiveConfigWithWAFIPGroup(t, ctx, ipGroup.ID)
 
 	groups, err := ChangedWAFIPGroupsForAgent(ctx, nil, nil)
@@ -201,7 +203,7 @@ func TestChangedWAFIPGroupsForAgentReturnsChecksumDelta(t *testing.T) {
 	assert.Empty(t, same)
 
 	ipGroup.IPList = `["203.0.113.45"]`
-	require.NoError(t, model.UpdateOpenFlareWAFIPGroup(ctx, ipGroup))
+	require.NoError(t, repository.UpdateOpenFlareWAFIPGroup(ctx, ipGroup))
 
 	delta, err := ChangedWAFIPGroupsForAgent(ctx, nil, map[string]string{groupKey: groups[0].Checksum})
 	require.NoError(t, err)
@@ -222,7 +224,7 @@ func TestSyncWAFIPGroupsReturnsChangedGroups(t *testing.T) {
 		Enabled: true,
 		IPList:  `["198.51.100.10"]`,
 	}
-	require.NoError(t, model.CreateOpenFlareWAFIPGroup(ctx, ipGroup))
+	require.NoError(t, repository.CreateOpenFlareWAFIPGroup(ctx, ipGroup))
 	seedActiveConfigWithWAFIPGroup(t, ctx, ipGroup.ID)
 
 	result, err := SyncWAFIPGroups(ctx, WAFIPGroupSyncInput{
@@ -255,9 +257,9 @@ func TestChangedWAFIPGroupsForAgentDisabledGroupClearsIPList(t *testing.T) {
 		Enabled: true,
 		IPList:  `["203.0.113.10"]`,
 	}
-	require.NoError(t, model.CreateOpenFlareWAFIPGroup(ctx, ipGroup))
+	require.NoError(t, repository.CreateOpenFlareWAFIPGroup(ctx, ipGroup))
 	ipGroup.Enabled = false
-	require.NoError(t, model.UpdateOpenFlareWAFIPGroup(ctx, ipGroup))
+	require.NoError(t, repository.UpdateOpenFlareWAFIPGroup(ctx, ipGroup))
 	seedActiveConfigWithWAFIPGroup(t, ctx, ipGroup.ID)
 
 	groups, err := ChangedWAFIPGroupsForAgent(ctx, nil, nil)

internal/apps/openflare/agent/ws_status.go

@@ -8,8 +8,9 @@ import (
 	"encoding/json"
 	"log/slog"
 
+	"github.com/Rain-kl/Wavelet/internal/repository"
+
 	ofws "github.com/Rain-kl/Wavelet/internal/apps/openflare/websocket"
-	"github.com/Rain-kl/Wavelet/internal/model"
 )
 
 // HandleWSStatus processes an agent websocket status payload (replaces HTTP heartbeat in WS mode).
@@ -20,7 +21,7 @@ func HandleWSStatus(ctx context.Context, nodeID, remoteAddr string, rawPayload j
 		return
 	}
 
-	authNode, err := model.GetOpenFlareNodeByNodeID(ctx, nodeID)
+	authNode, err := repository.GetOpenFlareNodeByNodeID(ctx, nodeID)
 	if err != nil {
 		slog.Debug("agent ws status reload node failed", "node_id", nodeID, "error", err)
 		return