refactor(core): align with cordis spatiotemporal composability architecture

- Purify core micro-kernel by removing context hardcoded helpers and reverse dependencies
- Eliminate init() side effects in infra plugins with reversible lifecycle disposal
- Completely isolate plugins by removing cross-plugin imports and using core/contracts
- Introduce TaskService and RiskControlService contracts for unified cross-plugin APIs
- Regenerate Swagger documentation and update developer guide matrix
- Achieve 0 violations in check_cordis_architecture.sh and 100% test pass

backend/plugins/infra/database/clickhouse.go

@@ -13,13 +13,14 @@ import (
 	"strings"
 	"time"
 
-	"Wavelet/pkg/config"
 	"github.com/ClickHouse/clickhouse-go/v2"
 	"github.com/ClickHouse/clickhouse-go/v2/lib/driver"
 	"go.opentelemetry.io/otel/attribute"
 	clickhouseDriver "gorm.io/driver/clickhouse"
 	"gorm.io/gorm"
 	"gorm.io/plugin/opentelemetry/tracing"
+
+	"Wavelet/pkg/config"
 )
 
 const (

backend/plugins/infra/database/plugin.go

@@ -7,9 +7,10 @@ package database
 import (
 	"context"
 
+	"gorm.io/gorm"
+
 	"Wavelet/core"
 	"Wavelet/core/contracts"
-	"gorm.io/gorm"
 )
 
 // Option configures the database plugin.
@@ -60,7 +61,11 @@ func (p *Plugin) Name() string {
 func (p *Plugin) Apply(ctx *core.Context) error {
 	targetDB := p.db
 	if targetDB == nil {
-		targetDB = DB(context.Background())
+		var err error
+		targetDB, err = InitDB()
+		if err != nil {
+			return err
+		}
 	}
 
 	svc := &dbServiceImpl{
@@ -68,10 +73,21 @@ func (p *Plugin) Apply(ctx *core.Context) error {
 		namedDBs: p.namedDBs,
 	}
 
+	if sqlDB, err := targetDB.DB(); err == nil && sqlDB != nil {
+		ctx.OnDispose(func() error {
+			return sqlDB.Close()
+		})
+	}
+
 	core.Provide[contracts.DBService](ctx, svc)
 	return nil
 }
 
+// NewService wraps a GORM DB instance into a contracts.DBService.
+func NewService(primary *gorm.DB) contracts.DBService {
+	return &dbServiceImpl{primary: primary}
+}
+
 type dbServiceImpl struct {
 	primary  *gorm.DB
 	namedDBs map[string]*gorm.DB

backend/plugins/infra/database/postgres.go

@@ -11,38 +11,36 @@ import (
 	"strconv"
 	"time"
 
-	"Wavelet/pkg/config"
 	"github.com/glebarez/sqlite"
 	"go.opentelemetry.io/otel/attribute"
 	"gorm.io/driver/postgres"
 	"gorm.io/gorm"
 	"gorm.io/plugin/dbresolver"
 	"gorm.io/plugin/opentelemetry/tracing"
+
+	"Wavelet/pkg/config"
 )
 
 var (
 	db *gorm.DB
 )
 
-func init() {
+// InitDB 初始化主数据库实例（支持 PostgreSQL / SQLite）
+func InitDB() (*gorm.DB, error) {
 	if !config.Config.Database.Enabled {
-		// PostgreSQL 禁用，使用 SQLite
-		initSQLite()
-		return
+		return initSQLite()
 	}
-
-	initPostgres()
+	return initPostgres()
 }
 
 // initSQLite 初始化 SQLite 数据库（PostgreSQL 禁用时的后备方案）
-func initSQLite() {
+func initSQLite() (*gorm.DB, error) {
 	sqlitePath := config.Config.Database.SQLitePath
 	if sqlitePath == "" {
 		sqlitePath = "./data/wavelet.db"
 	}
 
-	var err error
-	db, err = gorm.Open(sqlite.Open(sqlitePath), &gorm.Config{
+	targetDB, err := gorm.Open(sqlite.Open(sqlitePath), &gorm.Config{
 		DisableForeignKeyConstraintWhenMigrating: true,
 		Logger: &gormZapLogger{
 			logLevel:                  parseLogLevel(config.Config.Database.LogLevel),
@@ -51,11 +49,11 @@ func initSQLite() {
 		},
 	})
 	if err != nil {
-		log.Fatalf("[SQLite] init connection failed: %v\n", err)
+		return nil, err
 	}
 
 	// Trace 注入
-	if err = db.Use(
+	if err = targetDB.Use(
 		tracing.NewPlugin(
 			tracing.WithoutMetrics(),
 			tracing.WithAttributes(
@@ -64,15 +62,16 @@ func initSQLite() {
 			),
 		),
 	); err != nil {
-		log.Fatalf("[SQLite] init trace failed: %v\n", err)
+		return nil, err
 	}
 
+	db = targetDB
 	log.Printf("[SQLite] initialized (path: %s)\n", sqlitePath)
+	return targetDB, nil
 }
 
 // initPostgres 初始化 PostgreSQL 数据库
-func initPostgres() {
-	var err error
+func initPostgres() (*gorm.DB, error) {
 	dbConfig := config.Config.Database
 
 	// 构建主库 DSN 并连接
@@ -83,7 +82,7 @@ func initPostgres() {
 		PreferSimpleProtocol: dbConfig.PreferSimpleProtocol,
 	}
 
-	db, err = gorm.Open(postgres.New(pgConfig), &gorm.Config{
+	targetDB, err := gorm.Open(postgres.New(pgConfig), &gorm.Config{
 		DisableForeignKeyConstraintWhenMigrating: true,
 		Logger: &gormZapLogger{
 			logLevel:                  parseLogLevel(config.Config.Database.LogLevel),
@@ -92,11 +91,11 @@ func initPostgres() {
 		},
 	})
 	if err != nil {
-		log.Fatalf("[PostgreSQL] init connection failed: %v\n", err)
+		return nil, err
 	}
 
 	// Trace 注入
-	if err = db.Use(
+	if err = targetDB.Use(
 		tracing.NewPlugin(
 			tracing.WithoutMetrics(),
 			tracing.WithAttributes(
@@ -107,7 +106,7 @@ func initPostgres() {
 			),
 		),
 	); err != nil {
-		log.Fatalf("[PostgreSQL] init trace failed: %v\n", err)
+		return nil, err
 	}
 
 	if len(dbConfig.Replicas) > 0 {
@@ -138,8 +137,8 @@ func initPostgres() {
 			SetConnMaxLifetime(time.Duration(dbConfig.ConnMaxLifetime) * time.Second).
 			SetConnMaxIdleTime(time.Duration(dbConfig.ConnMaxIdleTime) * time.Second)
 
-		if err = db.Use(resolver); err != nil {
-			log.Fatalf("[PostgreSQL] init dbresolver failed: %v\n", err)
+		if err = targetDB.Use(resolver); err != nil {
+			return nil, err
 		}
 		log.Printf("[PostgreSQL] initialized in Primary-Replica mode (%d replicas)\n", len(dbConfig.Replicas))
 	} else {
@@ -147,15 +146,18 @@ func initPostgres() {
 	}
 
 	// 获取通用数据库对象设置连接池
-	sqlDB, err := db.DB()
+	sqlDB, err := targetDB.DB()
 	if err != nil {
-		log.Fatalf("[PostgreSQL] load sql db failed: %v\n", err)
+		return nil, err
 	}
 
 	sqlDB.SetMaxIdleConns(dbConfig.MaxIdleConn)
 	sqlDB.SetMaxOpenConns(dbConfig.MaxOpenConn)
 	sqlDB.SetConnMaxLifetime(time.Duration(dbConfig.ConnMaxLifetime) * time.Second)
 	sqlDB.SetConnMaxIdleTime(time.Duration(dbConfig.ConnMaxIdleTime) * time.Second)
+
+	db = targetDB
+	return targetDB, nil
 }
 
 // buildDSN 构建 PostgreSQL DSN

backend/plugins/infra/database/postgres_logger.go

@@ -10,9 +10,10 @@ import (
 	"strings"
 	"time"
 
-	"Wavelet/pkg/logger"
 	"gorm.io/gorm"
 	gormLogger "gorm.io/gorm/logger"
+
+	"Wavelet/pkg/logger"
 )
 
 // nanoToMilli 纳秒转毫秒的除数