Version: 0.4.9.dev.260309

feat: 🗄️ 新增自动建表功能

* 新增项目启动时自动建表能力，减少手动初始化数据库步骤
* 解决 `agent_chat` 与 `chat_history` 结构体互相持有对方结构体用于 `preload` 导致的循环依赖问题
* 修复因结构体互相依赖引发的建表失败问题，保证数据库初始化流程稳定

feat: 🐳 Docker Compose 引入 Kafka 分区自动初始化

* 更新 `docker-compose` 配置，引入 Kafka partition 自动初始化脚本
* 保证服务启动后 Topic 即具备可用 partition，实现开箱即用
* 修复转移环境后 MySQL 等容器数据无法持久化的问题，统一改为使用命名卷进行数据持久化

docs: 📚 补充 Outbox + Kafka 持久化链路注释

* 为 Outbox + Kafka 消息持久化链路补充详细代码注释
* 提升异步消息链路的可读性与维护性
* 当前代码 Review 进度约 50%

undo: ⚠️ Kafka 初始化阶段出现消息短暂堆积

* 初次初始化项目时观察到消息在 Kafka 中短暂堆积现象
* 后续被消费者一次性消费且未再次复现
* 已在生产者启动、消费者启动以及消息消费流程中增加控制台日志输出，降低系统黑箱程度
* 后续若条件允许将进一步排查该现象的触发原因

backend/cmd/start.go

@@ -16,14 +16,11 @@ import (
 	"github.com/spf13/viper"
 )
 
-// loadConfig 加载配置
-// 从配置文件中读取配置信息
+// loadConfig 加载应用配置。
 func loadConfig() error {
-	// 设置配置文件路径
 	viper.SetConfigName("config")
 	viper.SetConfigType("yaml")
 	viper.AddConfigPath(".")
-	// 读取配置文件
 	if err := viper.ReadInConfig(); err != nil {
 		return fmt.Errorf("failed to read config file: %w", err)
 	}
@@ -31,31 +28,29 @@ func loadConfig() error {
 	return nil
 }
 
-// Start 启动函数
+// Start 是应用启动入口。
 func Start() {
-	// 加载配置
 	if err := loadConfig(); err != nil {
 		log.Fatalf("Failed to load config: %v", err)
 	}
-	// 初始化数据库
+
 	db, err := inits.ConnectDB()
 	if err != nil {
 		log.Fatalf("Failed to connect to database: %v", err)
 	}
 
 	rdb := inits.InitRedis()
-	// 工具包
 	limiter := pkg.NewRateLimiter(rdb)
-	// 初始化 eino
+
 	aiHub, err := inits.InitEino()
 	if err != nil {
 		log.Fatalf("Failed to initialize Eino: %v", err)
 	}
-	// 中间件
-	// dao 层
+
+	// DAO 层初始化。
 	cacheRepo := dao.NewCacheDAO(rdb)
 	agentCacheRepo := dao.NewAgentCache(rdb)
-	_ = db.Use(middleware.NewGormCachePlugin(cacheRepo)) // 注册 GORM 插件
+	_ = db.Use(middleware.NewGormCachePlugin(cacheRepo))
 	userRepo := dao.NewUserDAO(db)
 	taskRepo := dao.NewTaskDAO(db)
 	courseRepo := dao.NewCourseDAO(db)
@@ -64,7 +59,11 @@ func Start() {
 	manager := dao.NewManager(db)
 	agentRepo := dao.NewAgentDAO(db)
 	outboxRepo := dao.NewOutboxDAO(db)
-	//
+
+	// outbox 异步链路接线：
+	// - 读取 Kafka 配置
+	// - 初始化 producer/consumer
+	// - 启动 dispatch/consume 两个后台循环
 	kafkaCfg := kafkabus.LoadConfig()
 	asyncPipeline, err := service.NewAgentAsyncPipeline(outboxRepo, kafkaCfg)
 	if err != nil {
@@ -78,14 +77,15 @@ func Start() {
 		log.Println("Kafka async pipeline is disabled")
 	}
 
-	// service 层
+	// Service 层初始化。
 	userService := service.NewUserService(userRepo, cacheRepo)
 	taskSv := service.NewTaskService(taskRepo, cacheRepo)
 	courseService := service.NewCourseService(courseRepo, scheduleRepo)
 	taskClassService := service.NewTaskClassService(taskClassRepo, cacheRepo, scheduleRepo, manager)
 	scheduleService := service.NewScheduleService(scheduleRepo, userRepo, taskClassRepo, manager, cacheRepo)
 	agentService := service.NewAgentService(aiHub, agentRepo, agentCacheRepo, asyncPipeline)
-	// api 层
+
+	// API 层初始化。
 	userApi := api.NewUserHandler(userService)
 	taskApi := api.NewTaskHandler(taskSv)
 	courseApi := api.NewCourseHandler(courseService)
@@ -100,6 +100,7 @@ func Start() {
 		ScheduleHandler:  scheduleApi,
 		AgentHandler:     agentApi,
 	}
+
 	r := routers.RegisterRouters(handlers, cacheRepo, limiter)
 	routers.StartEngine(r)
 }