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/service/agent_async_pipeline.go

@@ -15,11 +15,16 @@ import (
 	"gorm.io/gorm"
 )
 
-// AgentAsyncPipeline 负责 outbox 扫描、Kafka 投递与消费落库。
+// AgentAsyncPipeline 负责 outbox 的“异步可靠链路”：
+// 1) 业务侧写 outbox（pending）；
+// 2) dispatch loop 扫描并投递 Kafka（published）；
+// 3) consume loop 消费并落库（consumed）；
+// 4) 任一步失败按重试策略回到 pending 或 dead。
 type AgentAsyncPipeline struct {
 	outboxRepo *dao.OutboxDAO
 	producer   *kafkabus.Producer
 	consumer   *kafkabus.Consumer
+	brokers    []string
 	topic      string
 	maxRetry   int
 	scanEvery  time.Duration
@@ -43,6 +48,7 @@ func NewAgentAsyncPipeline(outboxRepo *dao.OutboxDAO, cfg kafkabus.Config) (*Age
 		outboxRepo: outboxRepo,
 		producer:   producer,
 		consumer:   consumer,
+		brokers:    cfg.Brokers,
 		topic:      cfg.Topic,
 		maxRetry:   cfg.MaxRetry,
 		scanEvery:  cfg.RetryScanInterval,
@@ -50,10 +56,23 @@ func NewAgentAsyncPipeline(outboxRepo *dao.OutboxDAO, cfg kafkabus.Config) (*Age
 	}, nil
 }
 
+// Start 启动两个后台协程：
+// - startDispatchLoop：扫描 pending 并投递 Kafka
+// - startConsumeLoop：消费 Kafka 并执行业务落库
 func (p *AgentAsyncPipeline) Start(ctx context.Context) {
 	if p == nil {
 		return
 	}
+
+	log.Printf("Kafka async pipeline starting: topic=%s brokers=%v retry_scan=%s batch=%d", p.topic, p.brokers, p.scanEvery, p.scanBatch)
+	if err := kafkabus.WaitTopicReady(ctx, p.brokers, p.topic, 30*time.Second); err != nil {
+		// 首次部署常见情况：broker 已起来但 topic/partition 尚未可用。
+		// 这里明确打印，避免“消息堆积但控制台无提示”的观感。
+		log.Printf("Kafka topic not ready before consume loop start: %v", err)
+	} else {
+		log.Printf("Kafka topic is ready: %s", p.topic)
+	}
+
 	go p.startDispatchLoop(ctx)
 	go p.startConsumeLoop(ctx)
 }
@@ -70,6 +89,10 @@ func (p *AgentAsyncPipeline) Close() {
 	}
 }
 
+// EnqueueChatHistoryPersist 是业务侧入口：
+// 1) 先写 outbox；
+// 2) 立刻尝试“首发投递”一次（非阻塞主流程）；
+// 3) 失败后由扫描器按 next_retry_at 继续重试。
 func (p *AgentAsyncPipeline) EnqueueChatHistoryPersist(ctx context.Context, payload model.ChatHistoryPersistPayload) error {
 	if p == nil {
 		return errors.New("Kafka 异步链路未初始化")
@@ -84,6 +107,7 @@ func (p *AgentAsyncPipeline) EnqueueChatHistoryPersist(ctx context.Context, payl
 	return nil
 }
 
+// startDispatchLoop 定时扫描 pending 且到期的消息，逐条尝试投递。
 func (p *AgentAsyncPipeline) startDispatchLoop(ctx context.Context) {
 	ticker := time.NewTicker(p.scanEvery)
 	defer ticker.Stop()
@@ -98,6 +122,9 @@ func (p *AgentAsyncPipeline) startDispatchLoop(ctx context.Context) {
 				log.Printf("扫描 outbox 失败: %v", err)
 				continue
 			}
+			if len(pendingMessages) > 0 {
+				log.Printf("outbox due messages=%d, start dispatch", len(pendingMessages))
+			}
 			for _, msg := range pendingMessages {
 				if err = p.dispatchOne(ctx, msg.ID); err != nil {
 					log.Printf("重试投递 outbox 消息失败(id=%d): %v", msg.ID, err)
@@ -107,6 +134,11 @@ func (p *AgentAsyncPipeline) startDispatchLoop(ctx context.Context) {
 	}
 }
 
+// dispatchOne 执行单条 outbox 投递：
+// 1) 读取 outbox 行；
+// 2) 组装 Envelope；
+// 3) 写 Kafka；
+// 4) 回写 published。
 func (p *AgentAsyncPipeline) dispatchOne(ctx context.Context, outboxID int64) error {
 	outboxMsg, err := p.outboxRepo.GetByID(ctx, outboxID)
 	if err != nil {
@@ -115,6 +147,7 @@ func (p *AgentAsyncPipeline) dispatchOne(ctx context.Context, outboxID int64) er
 		}
 		return err
 	}
+	// 终态不再重复投递。
 	if outboxMsg.Status == model.OutboxStatusConsumed || outboxMsg.Status == model.OutboxStatusDead {
 		return nil
 	}
@@ -126,7 +159,8 @@ func (p *AgentAsyncPipeline) dispatchOne(ctx context.Context, outboxID int64) er
 	}
 	raw, err := json.Marshal(envelope)
 	if err != nil {
-		markErr := p.outboxRepo.MarkDead(ctx, outboxMsg.ID, "序列化 outbox 包裹失败: "+err.Error())
+		// 序列化都失败通常是坏数据，直接死信。
+		markErr := p.outboxRepo.MarkDead(ctx, outboxMsg.ID, "序列化 outbox 包装失败: "+err.Error())
 		if markErr != nil {
 			log.Printf("标记 outbox 死信失败(id=%d): %v", outboxMsg.ID, markErr)
 		}
@@ -144,6 +178,7 @@ func (p *AgentAsyncPipeline) dispatchOne(ctx context.Context, outboxID int64) er
 	return nil
 }
 
+// startConsumeLoop 持续从 Kafka 拉取消息并处理。
 func (p *AgentAsyncPipeline) startConsumeLoop(ctx context.Context) {
 	for {
 		select {
@@ -157,7 +192,7 @@ func (p *AgentAsyncPipeline) startConsumeLoop(ctx context.Context) {
 			if errors.Is(err, context.Canceled) {
 				return
 			}
-			log.Printf("Kafka 消费拉取失败: %v", err)
+			log.Printf("Kafka 消费拉取失败(topic=%s): %v", p.topic, err)
 			time.Sleep(300 * time.Millisecond)
 			continue
 		}
@@ -167,21 +202,24 @@ func (p *AgentAsyncPipeline) startConsumeLoop(ctx context.Context) {
 	}
 }
 
+// handleMessage 先解析 Envelope，再按 biz_type 分发到具体处理器。
 func (p *AgentAsyncPipeline) handleMessage(ctx context.Context, msg segmentkafka.Message) error {
 	var envelope kafkabus.Envelope
 	if err := json.Unmarshal(msg.Value, &envelope); err != nil {
+		// 包装体坏数据，提交 offset 跳过，避免阻塞分区。
 		_ = p.consumer.Commit(ctx, msg)
-		return fmt.Errorf("解析 Kafka 包裹失败: %w", err)
+		return fmt.Errorf("解析 Kafka 包装失败: %w", err)
 	}
 	if envelope.OutboxID <= 0 {
 		_ = p.consumer.Commit(ctx, msg)
-		return errors.New("Kafka 包裹缺少 outbox_id")
+		return errors.New("Kafka 包装缺少 outbox_id")
 	}
 
 	switch envelope.BizType {
 	case model.OutboxBizTypeChatHistoryPersist:
 		return p.consumeChatHistory(ctx, msg, envelope)
 	default:
+		// 未知业务类型直接死信并提交，避免反复重试无意义数据。
 		_ = p.outboxRepo.MarkDead(ctx, envelope.OutboxID, "未知业务类型: "+envelope.BizType)
 		if err := p.consumer.Commit(ctx, msg); err != nil {
 			return err
@@ -190,6 +228,10 @@ func (p *AgentAsyncPipeline) handleMessage(ctx context.Context, msg segmentkafka
 	}
 }
 
+// consumeChatHistory 执行“聊天记录持久化”消费逻辑。
+// 提交策略说明：
+// 1) 成功落库后提交；
+// 2) 失败时先回写 outbox（便于重试/排障），再提交，避免分区阻塞。
 func (p *AgentAsyncPipeline) consumeChatHistory(ctx context.Context, msg segmentkafka.Message, envelope kafkabus.Envelope) error {
 	var payload model.ChatHistoryPersistPayload
 	if err := json.Unmarshal(envelope.Payload, &payload); err != nil {