flowchart TB
    subgraph Client["客户端层 (Client Layer)"]
        HTTPClient["HTTP/REST Client<br/>📱 Web/Mobile App<br/>端口: 8080"]
        WSClient["WebSocket Client<br/>🎙️ Real-time Voice<br/>端口: 8081"]
    end

    subgraph Server["接入层 (Server Layer)<br/>internal/server"]
        HTTPServer["HTTPServer (http.go)<br/>Gin Framework<br/>• 路由注册<br/>• 请求绑定<br/>• 响应封装"]

        Middleware["中间件栈 (middleware.go)<br/>• RecoveryMiddleware<br/>• CORSMiddleware<br/>• TracingMiddleware (OpenTelemetry)<br/>• LoggingMiddleware (Kratos)<br/>• TimeoutMiddleware (30s)<br/>• AuthMiddleware (JWT)<br/>• RateLimitMiddleware"]
    end

    subgraph Service["服务层 (Service Layer)<br/>internal/service"]
        ConvService["ConversationService<br/>(conversation_service.go)<br/>🎯 服务门面模式<br/>• 协调 Usecase<br/>• 无业务逻辑<br/>• 纯转发"]
    end

    subgraph Business["业务逻辑层 (Business Logic Layer)<br/>internal/biz"]
        ConvUsecase["ConversationUsecase<br/>(conversation_usecase.go)<br/>📋 会话生命周期<br/>• CreateConversation<br/>• UpdateTitle<br/>• Archive/Delete<br/>• ListConversations"]

        MsgUsecase["MessageUsecase<br/>(message_usecase.go)<br/>💬 消息管理<br/>• SendMessage<br/>• GetMessage<br/>• ListMessages<br/>• GetRecentMessages"]

        CtxCompressor["ContextCompressor<br/>(context_compression.go)<br/>🗜️ 四种压缩策略<br/>• Token Pruning<br/>• Summarization<br/>• LLMLingua<br/>• Hybrid"]

        TitleGen["TitleGenerator<br/>(title_generator_usecase.go)<br/>📝 智能标题<br/>• LLM 生成<br/>• 关键词提取"]
    end

    subgraph Domain["领域层 (Domain Layer)<br/>internal/domain"]
        Conversation["Conversation<br/>(conversation.go)<br/>🏛️ 会话聚合根<br/>• 状态机 (4种状态)<br/>• 业务不变式<br/>• CanSendMessage()<br/>• IncrementMessageCount()"]

        Message["Message<br/>(message.go)<br/>📨 消息实体<br/>• 4种角色<br/>• 4种内容类型<br/>• SetTokens()<br/>• SetModel()"]

        ContextMgr["ContextManager<br/>(context_manager.go)<br/>🧠 上下文智能管理<br/>• GetContext()<br/>• UpdateContext()<br/>• CompressContext()<br/>• estimateTokens()<br/>• trimMessages()"]

        WindowStrategy["WindowStrategy<br/>(window_strategy.go)<br/>📐 窗口选择策略<br/>• RecentWindowStrategy<br/>• RelevantWindowStrategy"]

        Repository["Repository Interfaces<br/>(repository.go)<br/>🗄️ 依赖倒置<br/>• ConversationRepository<br/>• MessageRepository<br/>• ContextRepository"]
    end

    subgraph Data["数据访问层 (Data Access Layer)<br/>internal/data"]
        ConvRepo["ConversationRepository<br/>(conversation_repo.go)<br/>💾 会话持久化<br/>• GORM 实现<br/>• JSONB 存储 Limits<br/>• Soft Delete"]

        MsgRepo["MessageRepository<br/>(message_repo.go)<br/>💾 消息持久化<br/>• 按时间序列<br/>• 分页优化<br/>• 角色过滤"]

        CtxCache["ContextCache<br/>(context_cache.go)<br/>⚡ Redis 缓存<br/>• GetContext()<br/>• SetContext()<br/>• AppendMessage()<br/>• truncateContext()<br/>• TTL 24h"]

        CtxRepo["ContextRepository<br/>(context_repo.go)<br/>🗃️ 缓存协调<br/>• Cache First<br/>• DB Fallback"]
    end

    subgraph Storage["存储层 (Storage Layer)"]
        PostgreSQL["PostgreSQL<br/>🐘 主数据库<br/>Schema: conversation<br/>• conversations 表<br/>• messages 表<br/>• 索引优化<br/>• JSONB 字段"]

        Redis["Redis<br/>⚡ 缓存层<br/>• context:{id}<br/>• TTL 管理<br/>• 自动截断 (4000 tokens)<br/>• 批量操作"]

        Kafka["Kafka<br/>📢 事件总线<br/>• conversation.created<br/>• message.sent<br/>• context.compressed"]
    end

    subgraph External["外部依赖服务 (External Services)"]
        AIOrchestrator["AI Orchestrator<br/>🤖 AI 编排<br/>• 流式生成<br/>• 模型路由<br/>• Token 计算"]

        Identity["Identity Service<br/>🔐 身份认证<br/>• JWT 验证<br/>• 权限管理"]

        Analytics["Analytics Service<br/>📊 数据分析<br/>• 统计上报<br/>• 成本计算"]
    end

    %% 客户端到服务器
    HTTPClient --> HTTPServer
    WSClient --> HTTPServer

    %% 服务器到中间件
    HTTPServer --> Middleware

    %% 中间件到服务层
    Middleware --> ConvService

    %% 服务层到业务层
    ConvService --> ConvUsecase
    ConvService --> MsgUsecase

    %% 业务层内部协作
    MsgUsecase --> CtxCompressor
    ConvUsecase --> TitleGen

    %% 业务层到领域层
    ConvUsecase --> Conversation
    MsgUsecase --> Message
    MsgUsecase --> ContextMgr
    CtxCompressor --> ContextMgr
    ContextMgr --> WindowStrategy

    %% 业务层到仓储接口（依赖倒置）
    ConvUsecase --> Repository
    MsgUsecase --> Repository
    ContextMgr --> Repository

    %% 仓储接口到数据层实现
    Repository -.实现.-> ConvRepo
    Repository -.实现.-> MsgRepo
    Repository -.实现.-> CtxRepo

    %% 数据层到缓存
    CtxRepo --> CtxCache
    MsgRepo --> CtxCache

    %% 数据层到存储
    ConvRepo --> PostgreSQL
    MsgRepo --> PostgreSQL
    CtxCache --> Redis

    %% 事件发布（异步）
    ConvRepo -.异步.-> Kafka
    MsgRepo -.异步.-> Kafka

    %% 外部服务调用
    CtxCompressor --> AIOrchestrator
    TitleGen --> AIOrchestrator
    Middleware --> Identity
    ConvService -.异步.-> Analytics

    %% 样式定义
    style Client fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
    style Server fill:#fff3e0,stroke:#f57c00,stroke-width:2px
    style Service fill:#e8f5e9,stroke:#388e3c,stroke-width:2px
    style Business fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
    style Domain fill:#fce4ec,stroke:#c2185b,stroke-width:2px
    style Data fill:#fff9c4,stroke:#f9a825,stroke-width:2px
    style Storage fill:#e0f2f1,stroke:#00897b,stroke-width:2px
    style External fill:#f1f8e9,stroke:#558b2f,stroke-width:2px

sequenceDiagram
    autonumber
    participant Client as 客户端
    participant HTTP as HTTP Server
    participant Middleware as 中间件
    participant Service as ConversationService
    participant ConvUC as ConversationUsecase
    participant MsgUC as MessageUsecase
    participant Domain as Domain Model
    participant ConvRepo as ConversationRepo
    participant MsgRepo as MessageRepo
    participant Cache as ContextCache
    participant DB as PostgreSQL
    participant Redis as Redis
    participant Kafka as Kafka
    participant AI as AI Orchestrator

    rect rgb(230, 240, 255)
    Note over Client,Kafka: 场景1：创建会话
    Client->>HTTP: POST /conversations
    HTTP->>Middleware: 请求处理
    Middleware->>Middleware: 认证 & 限流
    Middleware->>Service: CreateConversation(...)
    Service->>ConvUC: CreateConversation(...)
    ConvUC->>Domain: NewConversation(...)
    Note over Domain: 应用业务规则<br/>初始化状态机
    Domain-->>ConvUC: Conversation
    ConvUC->>ConvRepo: CreateConversation(...)
    ConvRepo->>DB: INSERT INTO conversations
    DB-->>ConvRepo: success
    ConvRepo->>Kafka: Publish(conversation.created)
    ConvRepo-->>ConvUC: nil
    ConvUC-->>Service: Conversation
    Service-->>HTTP: 201 Created
    HTTP-->>Client: conversation JSON
    end

    rect rgb(240, 255, 240)
    Note over Client,Kafka: 场景2：发送消息（串行执行）
    Client->>HTTP: POST /conversations/:id/messages
    HTTP->>Service: SendMessage(...)
    Service->>MsgUC: SendMessage(...)

    Note over MsgUC: 步骤1：查询会话
    MsgUC->>ConvRepo: GetConversation(id)
    ConvRepo->>DB: SELECT * FROM conversations<br/>WHERE id=? AND status!='deleted'
    DB-->>ConvRepo: row (20ms)
    ConvRepo-->>MsgUC: *Conversation

    Note over MsgUC: 步骤2：权限验证
    MsgUC->>MsgUC: conversation.UserID == userID?
    MsgUC->>Domain: conversation.CanSendMessage()
    Note over Domain: 检查：<br/>• status == active<br/>• current_messages < max_messages
    Domain-->>MsgUC: true

    Note over MsgUC: 步骤3：创建消息
    MsgUC->>Domain: NewMessage(...)
    Domain-->>MsgUC: *Message

    Note over MsgUC: 步骤4：保存消息
    MsgUC->>MsgRepo: CreateMessage(message)
    MsgRepo->>DB: INSERT INTO messages<br/>(id, conversation_id, role, content, ...)
    DB-->>MsgRepo: success (20ms)
    MsgRepo-->>MsgUC: nil

    Note over MsgUC: 步骤5：更新会话统计
    MsgUC->>Domain: conversation.IncrementMessageCount()
    Note over Domain: current_messages++<br/>last_active_at = now()
    MsgUC->>ConvRepo: UpdateConversation(conversation)
    ConvRepo->>DB: UPDATE conversations<br/>SET current_messages=?, last_active_at=?<br/>WHERE id=?
    DB-->>ConvRepo: success (15ms)
    ConvRepo-->>MsgUC: nil

    MsgUC-->>Service: *Message
    Service-->>HTTP: 201 Created
    HTTP-->>Client: message JSON

    Note over Client,Kafka: 总耗时：60-80ms<br/>查询: 20ms<br/>插入: 20ms<br/>更新: 15ms
    end

    rect rgb(255, 240, 240)
    Note over Client,AI: 场景3：获取上下文（带缓存）
    Client->>HTTP: GET /conversations/:id/context
    HTTP->>Service: GetContext(...)
    Service->>MsgUC: GetContext(...)
    MsgUC->>Cache: GetCached(id)
    Cache->>Redis: GET context:id

    alt 缓存命中
        Redis-->>Cache: cached data
        Cache-->>MsgUC: ManagedContext
        MsgUC-->>Service: ManagedContext
    else 缓存未命中
        Redis-->>Cache: nil
        MsgUC->>MsgRepo: ListMessages(id, limit)
        MsgRepo->>DB: SELECT * FROM messages
        DB-->>MsgRepo: rows
        MsgRepo-->>MsgUC: Messages
        Note over MsgUC: 应用窗口策略<br/>Token估算<br/>裁剪消息
        MsgUC->>Cache: Cache(context, TTL)
        Cache->>Redis: SET context:id
        Redis-->>Cache: OK
        MsgUC-->>Service: ManagedContext
    end

    Service-->>HTTP: 200 OK
    HTTP-->>Client: context JSON
    end

    rect rgb(255, 255, 230)
    Note over Client,AI: 场景4：流式对话
    Client->>HTTP: POST /conversations/:id/messages/stream
    HTTP->>Service: SendMessageStream(...)
    Service->>MsgUC: SendMessage(...)
    Note over MsgUC: 保存用户消息
    MsgUC-->>Service: OK

    Service->>AI: GenerateStream(...)
    loop 流式接收
        AI-->>Service: chunk
        Service-->>HTTP: SSE event
        HTTP-->>Client: data: chunk
    end
    AI-->>Service: done

    Service->>MsgUC: SaveAssistantMessage(...)
    MsgUC-->>Service: OK
    Service-->>HTTP: SSE close
    HTTP-->>Client: connection closed
    end

// 建议使用事务保证一致性
func (uc *MessageUsecase) SendMessage(...) (*domain.Message, error) {
    return uc.db.Transaction(func(tx *gorm.DB) (interface{}, error) {
        // 在事务中执行 INSERT 和 UPDATE
        // ...
    })
}

查询流程：
Application → ContextCache.GetContext() → Redis GET
├─ 命中 → 直接返回（<5ms）
└─ 未命中 → MessageRepo → PostgreSQL SELECT → 构建上下文 → Redis SET → 返回

func (c *ContextCompressor) compressWithTokenPrune(
    ctx context.Context,
    messages []*domain.Message,
) ([]*domain.Message, error) {
    targetTokens := int(float64(c.countTokens(messages)) * c.config.TargetCompressionRatio)

    // 从最新消息开始保留
    var compressed []*domain.Message
    currentTokens := 0

    for i := len(messages) - 1; i >= 0; i-- {
        msg := messages[i]
        tokens := c.countMessageTokens(msg)

        if currentTokens+tokens <= targetTokens {
            compressed = append([]*domain.Message{msg}, compressed...)
            currentTokens += tokens
        } else {
            break
        }
    }

    return compressed, nil
}

func (c *ContextCompressor) compressWithSummarize(
    ctx context.Context,
    messages []*domain.Message,
) ([]*domain.Message, error) {
    // 1. 将历史消息分段（每 10 条一段）
    segments := c.segmentMessages(messages, 10)

    // 2. 对每段生成摘要（调用 LLM）
    var compressed []*domain.Message
    for _, segment := range segments {
        summary, err := c.summarizeSegment(ctx, segment)
        if err != nil {
            return nil, err
        }

        summaryMsg := &domain.Message{
            Role:    "system",
            Content: fmt.Sprintf("[历史摘要] %s", summary),
        }
        compressed = append(compressed, summaryMsg)
    }

    // 3. 保留最近 5 条原始消息
    recentCount := 5
    compressed = append(compressed, messages[len(messages)-recentCount:]...)

    return compressed, nil
}

func (c *ContextCompressor) compressWithHybrid(
    ctx context.Context,
    messages []*domain.Message,
) ([]*domain.Message, error) {
    // 1. 对旧消息（前 50%）使用摘要
    midPoint := len(messages) / 2
    oldMessages := messages[:midPoint]
    summarized, err := c.compressWithSummarize(ctx, oldMessages)
    if err != nil {
        return nil, err
    }

    // 2. 对较新消息（后 50%）使用 Token 剪枝
    recentMessages := messages[midPoint:]
    pruned, err := c.compressWithTokenPrune(ctx, recentMessages)
    if err != nil {
        return nil, err
    }

    // 3. 合并
    result := append(summarized, pruned...)
    return result, nil
}

func (c *ContextCompressor) compressWithLLMLingua(
    ctx context.Context,
    messages []*domain.Message,
) ([]*domain.Message, error) {
    conversationText := c.messagesToText(messages)

    request := map[string]interface{}{
        "text":              conversationText,
        "compression_ratio": c.config.TargetCompressionRatio,
        "preserve_keywords": c.config.PreserveKeywords,
    }

    response, err := c.aiClient.CallLLMLingua(ctx, request)
    if err != nil {
        return nil, err
    }

    compressedText := response["compressed_text"].(string)
    compressed := c.textToMessages(compressedText, messages)

    return compressed, nil
}

go func() {
    // 操作1：保存消息
    msgRepo.CreateMessage(ctx, message)
}()

go func() {
    // 操作2：更新会话统计
    convRepo.UpdateConversation(ctx, conversation)
}()

go func() {
    // 操作3：清除缓存
    cache.InvalidateContext(ctx, conversationID)
}()

// 等待所有操作完成
wg.Wait()

{
  "event_type": "message.sent",
  "event_id": "evt_1234567890",
  "timestamp": "2025-01-27T10:30:00Z",
  "conversation_id": "conv_abc123",
  "message_id": "msg_xyz789",
  "tenant_id": "tenant_001",
  "user_id": "user_456",
  "metadata": {
    "role": "user",
    "tokens": 150,
    "model": "gpt-4"
  }
}

classDiagram
    class Conversation {
        +string ID
        +string TenantID
        +string UserID
        +string Title
        +ConversationMode Mode
        +ConversationStatus Status
        +ConversationLimits* Limits
        +map[string]string Metadata
        +time.Time CreatedAt
        +time.Time UpdatedAt
        +time.Time LastActiveAt
        +UpdateTitle(title string)
        +Archive() error
        +Delete()
        +UpdateActivity()
        +CanSendMessage() bool
        +IncrementMessageCount()
        +AddTokens(tokens int)
    }

    class ConversationLimits {
        +int MaxMessages
        +int CurrentMessages
        +int TokenLimit
        +int CurrentTokens
        +string SystemPrompt
        +map[string]string Variables
    }

    class Message {
        +string ID
        +string ConversationID
        +string TenantID
        +string UserID
        +MessageRole Role
        +string Content
        +ContentType ContentType
        +int Tokens
        +string Model
        +string Provider
        +map[string]string Metadata
        +time.Time CreatedAt
        +SetTokens(tokens int)
        +SetModel(model, provider string)
    }

    class ContextManager {
        -MessageRepository messageRepo
        -ContextRepository contextRepo
        -int maxTokens
        -WindowStrategy windowStrategy
        +GetContext(ctx, conversationID, options) ManagedContext
        +UpdateContext(ctx, conversationID, newMessage) error
        +CompressContext(ctx, conversationID) error
        -estimateTokens(messages) int
        -trimMessages(messages, maxTokens) []Message
    }

    class ManagedContext {
        +string ConversationID
        +[]Message Messages
        +string CompressedSummary
        +int TotalTokens
        +string Strategy
        +time.Time GeneratedAt
        +string CacheKey
    }

    class WindowStrategy {
        <<interface>>
        +Select(ctx, repo, conversationID, options) []Message
    }

    class RecentWindowStrategy {
        +Select(ctx, repo, conversationID, options) []Message
    }

    class RelevantWindowStrategy {
        +Select(ctx, repo, conversationID, options) []Message
    }

    Conversation "1" *-- "1" ConversationLimits
    Conversation "1" -- "0..*" Message : contains
    ContextManager ..> ManagedContext : creates
    ContextManager ..> WindowStrategy : uses
    WindowStrategy <|.. RecentWindowStrategy : implements
    WindowStrategy <|.. RelevantWindowStrategy : implements

-- 主键索引
PRIMARY KEY (id)

-- 租户+用户查询（列出会话）
CREATE INDEX idx_conversations_tenant_user ON conversations(tenant_id, user_id);

-- 按活跃时间排序
CREATE INDEX idx_conversations_last_active ON conversations(last_active_at DESC);

-- 软删除过滤
WHERE status != 'deleted'  -- 在查询中应用，无需单独索引

type ConversationDO struct {
    ID           string    `gorm:"primaryKey"`
    TenantID     string    `gorm:"index"`
    UserID       string    `gorm:"index"`
    Title        string
    Mode         string
    Status       string
    ContextJSON  string    `gorm:"type:jsonb"`
    MetadataJSON string    `gorm:"type:jsonb"`
    CreatedAt    time.Time
    UpdatedAt    time.Time
    LastActiveAt time.Time
}

func (ConversationDO) TableName() string {
    return "conversation.conversations"
}

-- 主键索引
PRIMARY KEY (id)

-- 会话消息查询（最常用）
CREATE INDEX idx_messages_conversation_created ON messages(conversation_id, created_at DESC);

-- 租户消息查询（跨会话）
CREATE INDEX idx_messages_tenant_created ON messages(tenant_id, created_at DESC);

-- 按角色过滤（系统消息、用户消息等）
-- 不建索引，通过 conversation_id 索引后再过滤

type MessageDO struct {
    ID             string    `gorm:"primaryKey"`
    ConversationID string    `gorm:"index"`
    TenantID       string    `gorm:"index"`
    UserID         string    `gorm:"index"`
    Role           string
    Content        string    `gorm:"type:text"`
    ContentType    string
    Tokens         int
    Model          string
    Provider       string
    MetadataJSON   string    `gorm:"type:jsonb"`
    CreatedAt      time.Time
}

func (MessageDO) TableName() string {
    return "conversation.messages"
}

type CreateConversationRequest struct {
    TenantID string             `json:"tenant_id" binding:"required"` // 租户ID
    UserID   string             `json:"user_id" binding:"required"`   // 用户ID
    Title    string             `json:"title" binding:"required"`     // 会话标题
    Mode     ConversationMode   `json:"mode" binding:"required"`      // 对话模式
}

type ConversationMode string

const (
    ModeText  ConversationMode = "text"  // 文本对话
    ModeVoice ConversationMode = "voice" // 语音对话
    ModeVideo ConversationMode = "video" // 视频对话
)

type Conversation struct {
    ID          string              `json:"id"`            // 会话ID
    TenantID    string              `json:"tenant_id"`     // 租户ID
    UserID      string              `json:"user_id"`       // 用户ID
    Title       string              `json:"title"`         // 会话标题
    Mode        ConversationMode    `json:"mode"`          // 对话模式
    Status      ConversationStatus  `json:"status"`        // 会话状态
    Limits      *ConversationLimits `json:"limits"`        // 会话限制
    Metadata    map[string]string   `json:"metadata"`      // 元数据
    CreatedAt   time.Time           `json:"created_at"`    // 创建时间
    UpdatedAt   time.Time           `json:"updated_at"`    // 更新时间
    LastActiveAt time.Time          `json:"last_active_at"` // 最后活跃时间
}

type ConversationStatus string

const (
    StatusActive   ConversationStatus = "active"   // 活跃
    StatusPaused   ConversationStatus = "paused"   // 暂停
    StatusArchived ConversationStatus = "archived" // 归档
    StatusDeleted  ConversationStatus = "deleted"  // 删除
)

type ConversationLimits struct {
    MaxMessages     int               `json:"max_messages"`     // 最大消息数
    CurrentMessages int               `json:"current_messages"` // 当前消息数
    TokenLimit      int               `json:"token_limit"`      // Token限制
    CurrentTokens   int               `json:"current_tokens"`   // 当前Token数
    SystemPrompt    string            `json:"system_prompt"`    // 系统提示词
    Variables       map[string]string `json:"variables"`        // 上下文变量
}

// 入口函数
func (uc *ConversationUsecase) CreateConversation(
    ctx context.Context,
    tenantID, userID, title string,
    mode domain.ConversationMode,
) (*domain.Conversation, error) {
    // 1. 创建会话领域对象（应用业务规则）
    conversation := domain.NewConversation(tenantID, userID, title, mode)

    // 2. 保存到数据库
    if err := uc.conversationRepo.CreateConversation(ctx, conversation); err != nil {
        return nil, fmt.Errorf("failed to create conversation: %w", err)
    }

    return conversation, nil
}

// 领域对象构造函数
func NewConversation(tenantID, userID, title string, mode ConversationMode) *Conversation {
    now := time.Now()
    return &Conversation{
        ID:          generateConversationID(),
        TenantID:    tenantID,
        UserID:      userID,
        Title:       title,
        Mode:        mode,
        Status:      StatusActive,
        Limits: &ConversationLimits{
            MaxMessages:     100,          // 默认最大100条消息
            CurrentMessages: 0,
            TokenLimit:      4000,         // 默认4000 tokens
            CurrentTokens:   0,
            Variables:       make(map[string]string),
        },
        Metadata:     make(map[string]string),
        CreatedAt:    now,
        UpdatedAt:    now,
        LastActiveAt: now,
    }
}

第1层：HTTP Handler
  文件：cmd/conversation-service/internal/server/http.go
  函数：func (s *HTTPServer) createConversation(c *gin.Context)
  职责：
    • 请求参数绑定：c.ShouldBindJSON(&req)
    • 基础参数验证：required 标签验证
    • 调用服务层：s.service.CreateConversation(...)
  耗时：<1ms
  关键代码：
    ```go
    var req struct {
        TenantID string `json:"tenant_id" binding:"required"`
        UserID   string `json:"user_id" binding:"required"`
        Title    string `json:"title" binding:"required"`
        Mode     string `json:"mode" binding:"required"`
    }
    if err := c.ShouldBindJSON(&req); err != nil {
        c.JSON(400, Response{Code: 400, Message: err.Error()})
        return
    }
    ```

第2层：Service Layer（门面）
  文件：cmd/conversation-service/internal/service/conversation_service.go
  函数：func (s *ConversationService) CreateConversation(...)
  职责：
    • 纯转发，无业务逻辑
    • 协调 Usecase
  耗时：<1ms
  关键代码：
    ```go
    return s.conversationUc.CreateConversation(ctx, tenantID, userID, title, mode)
    ```

第3层：Usecase Layer（业务逻辑）
  文件：cmd/conversation-service/internal/biz/conversation_usecase.go
  函数：func (uc *ConversationUsecase) CreateConversation(...)
  职责：
    • 调用领域对象工厂方法
    • 调用仓储持久化
  耗时：<1ms
  关键代码：
    ```go
    conversation := domain.NewConversation(tenantID, userID, title, mode)
    if err := uc.conversationRepo.CreateConversation(ctx, conversation); err != nil {
        return nil, fmt.Errorf("failed to create conversation: %w", err)
    }
    return conversation, nil
    ```

第4层：Domain Layer（领域模型）
  文件：cmd/conversation-service/internal/domain/conversation.go
  函数：func NewConversation(tenantID, userID, title string, mode ConversationMode) *Conversation
  职责：
    • 生成会话 ID：generateConversationID()
    • 设置初始状态：StatusActive
    • 初始化限制：MaxMessages=100, TokenLimit=4000
    • 初始化元数据
  耗时：<1ms
  关键代码：
    ```go
    return &Conversation{
        ID:       generateConversationID(),  // conv_时间戳
        TenantID: tenantID,
        UserID:   userID,
        Title:    title,
        Mode:     mode,
        Status:   StatusActive,
        Limits: &ConversationLimits{
            MaxMessages:     100,
            CurrentMessages: 0,
            TokenLimit:      4000,
            CurrentTokens:   0,
            Variables:       make(map[string]string),
        },
        Metadata:     make(map[string]string),
        CreatedAt:    now,
        UpdatedAt:    now,
        LastActiveAt: now,
    }
    ```

第5层：Repository Layer（数据访问）
  文件：cmd/conversation-service/internal/data/conversation_repo.go
  函数：func (r *ConversationRepository) CreateConversation(ctx, conversation)
  职责：
    • 领域对象 → 数据对象转换：toDataObject()
    • GORM INSERT 操作
    • 异步 Kafka 事件发布（待实现）
  耗时：20-30ms（数据库写入）
  关键代码：
    ```go
    do := r.toDataObject(conversation)
    return r.db.WithContext(ctx).Create(do).Error
    ```

第6层：Storage Layer（数据库）
  数据库：PostgreSQL
  表：conversation.conversations
  操作：INSERT INTO conversations (id, tenant_id, user_id, title, mode, status, ...)
  索引命中：tenant_id, user_id 复合索引
  耗时：20-30ms

异步事件发布（待实现）：
  Topic：voiceassistant.conversations
  事件：conversation.created
  分区键：tenant_id
  耗时：不阻塞主流程（go 异步）

// 第1层：HTTP Handler
func (s *HTTPServer) createConversation(c *gin.Context) {
    var req struct {
        TenantID string `json:"tenant_id" binding:"required"`
        UserID   string `json:"user_id" binding:"required"`
        Title    string `json:"title" binding:"required"`
        Mode     string `json:"mode" binding:"required"`
    }

    // 参数绑定和验证
    if err := c.ShouldBindJSON(&req); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
        return
    }

    // 调用服务层
    conversation, err := s.service.CreateConversation(
        c.Request.Context(),
        req.TenantID,
        req.UserID,
        req.Title,
        domain.ConversationMode(req.Mode),
    )

    if err != nil {
        c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
        return
    }

    c.JSON(http.StatusCreated, conversation)
}

// 第2层：Service Layer（直接转发）
func (s *ConversationService) CreateConversation(
    ctx context.Context,
    tenantID, userID, title string,
    mode domain.ConversationMode,
) (*domain.Conversation, error) {
    return s.conversationUc.CreateConversation(ctx, tenantID, userID, title, mode)
}

// 第3层：Usecase Layer
func (uc *ConversationUsecase) CreateConversation(
    ctx context.Context,
    tenantID, userID, title string,
    mode domain.ConversationMode,
) (*domain.Conversation, error) {
    // 创建领域对象（应用业务规则）
    conversation := domain.NewConversation(tenantID, userID, title, mode)

    // 持久化
    if err := uc.conversationRepo.CreateConversation(ctx, conversation); err != nil {
        return nil, fmt.Errorf("failed to create conversation: %w", err)
    }

    return conversation, nil
}

// 第4层：Domain Layer
func NewConversation(tenantID, userID, title string, mode ConversationMode) *Conversation {
    now := time.Now()
    return &Conversation{
        ID:          generateConversationID(),  // conv_时间戳
        TenantID:    tenantID,
        UserID:      userID,
        Title:       title,
        Mode:        mode,
        Status:      StatusActive,  // 初始状态
        Limits: &ConversationLimits{
            MaxMessages:     100,   // 业务规则：最大 100 条消息
            CurrentMessages: 0,
            TokenLimit:      4000,  // 业务规则：最大 4000 tokens
            CurrentTokens:   0,
            Variables:       make(map[string]string),
        },
        Metadata:     make(map[string]string),
        CreatedAt:    now,
        UpdatedAt:    now,
        LastActiveAt: now,
    }
}

// 第5层：Repository Layer
func (r *ConversationRepository) CreateConversation(
    ctx context.Context,
    conversation *domain.Conversation,
) error {
    // 领域对象 → 数据对象转换
    do := r.toDataObject(conversation)

    // GORM 插入
    if err := r.db.WithContext(ctx).Create(do).Error; err != nil {
        return err
    }

    // 异步发布事件
    go func() {
        event := &Event{
            Type:           "conversation.created",
            ConversationID: conversation.ID,
            TenantID:       conversation.TenantID,
            UserID:         conversation.UserID,
            Timestamp:      time.Now(),
        }
        r.kafkaProducer.Publish(event)
    }()

    return nil
}

sequenceDiagram
    autonumber
    participant Client as 客户端
    participant LB as 负载均衡器
    participant HTTP as HTTP Handler
    participant MW as 中间件栈
    participant Service as ConversationService
    participant Usecase as ConversationUsecase
    participant Domain as Domain Model
    participant Repo as ConversationRepo
    participant DB as PostgreSQL
    participant Kafka as Kafka
    participant Cache as Redis

    Client->>LB: POST /api/v1/conversations<br/>{tenant_id, user_id, title, mode}
    LB->>HTTP: 路由请求

    HTTP->>HTTP: 参数绑定<br/>c.ShouldBindJSON(&req)

    HTTP->>MW: 经过中间件栈
    MW->>MW: 1️⃣ 认证中间件<br/>验证 JWT Token
    MW->>MW: 2️⃣ 限流中间件<br/>检查 100/min 限制
    MW->>MW: 3️⃣ 日志中间件<br/>记录请求信息
    MW->>MW: 4️⃣ 指标中间件<br/>Prometheus metrics

    MW->>Service: CreateConversation(...)
    Service->>Usecase: CreateConversation(...)

    Note over Usecase: 业务逻辑层
    Usecase->>Domain: NewConversation(...)

    Note over Domain: 领域对象构造<br/>• 生成 ID<br/>• 设置状态<br/>• 初始化限制<br/>• 应用业务规则
    Domain-->>Usecase: *Conversation

    Usecase->>Repo: CreateConversation(ctx, conversation)

    Note over Repo: 数据持久化层
    Repo->>Repo: toDataObject()<br/>领域对象 → 数据对象
    Repo->>DB: INSERT INTO conversations<br/>(id, tenant_id, user_id, title, ...)
    DB-->>Repo: 影响行数: 1

    par 异步事件发布
        Repo->>Kafka: Publish(conversation.created)
        Note over Kafka: 分区键: tenant_id<br/>Topic: voiceassistant.conversations
        Kafka-->>Repo: ack (异步)
    end

    Repo-->>Usecase: nil (成功)
    Usecase-->>Service: *Conversation
    Service-->>MW: *Conversation
    MW-->>HTTP: *Conversation

    HTTP->>HTTP: 序列化为 JSON
    HTTP-->>LB: 201 Created<br/>Content-Type: application/json
    LB-->>Client: conversation JSON

    Note over Client,Kafka: 整体耗时：50-80ms<br/>数据库: 20-30ms<br/>中间件: 5-10ms<br/>序列化: 1-2ms

type SendMessageRequest struct {
    UserID  string      `json:"user_id" binding:"required"`  // 用户ID
    Role    MessageRole `json:"role" binding:"required"`     // 消息角色
    Content string      `json:"content" binding:"required"`  // 消息内容
}

type MessageRole string

const (
    RoleUser      MessageRole = "user"      // 用户消息
    RoleAssistant MessageRole = "assistant" // 助手回复
    RoleSystem    MessageRole = "system"    // 系统消息
    RoleTool      MessageRole = "tool"      // 工具调用结果
)

type Message struct {
    ID             string            `json:"id"`              // 消息ID
    ConversationID string            `json:"conversation_id"` // 会话ID
    TenantID       string            `json:"tenant_id"`       // 租户ID
    UserID         string            `json:"user_id"`         // 用户ID
    Role           MessageRole       `json:"role"`            // 消息角色
    Content        string            `json:"content"`         // 消息内容
    ContentType    ContentType       `json:"content_type"`    // 内容类型
    Tokens         int               `json:"tokens"`          // Token数
    Model          string            `json:"model"`           // 使用的模型
    Provider       string            `json:"provider"`        // 模型提供商
    Metadata       map[string]string `json:"metadata"`        // 元数据
    CreatedAt      time.Time         `json:"created_at"`      // 创建时间
}

// 入口函数
func (uc *MessageUsecase) SendMessage(
    ctx context.Context,
    conversationID, userID string,
    role domain.MessageRole,
    content string,
) (*domain.Message, error) {
    // 1. 获取会话并检查权限
    conversation, err := uc.conversationRepo.GetConversation(ctx, conversationID)
    if err != nil {
        return nil, err
    }

    if conversation.UserID != userID {
        return nil, domain.ErrUnauthorized
    }

    // 2. 检查业务规则：是否可以发送消息
    if !conversation.CanSendMessage() {
        return nil, domain.ErrConversationFull
    }

    // 3. 创建消息
    message := domain.NewMessage(conversationID, conversation.TenantID, userID, role, content)

    // 4. 保存消息
    if err := uc.messageRepo.CreateMessage(ctx, message); err != nil {
        return nil, fmt.Errorf("failed to create message: %w", err)
    }

    // 5. 更新会话统计
    conversation.IncrementMessageCount()
    if err := uc.conversationRepo.UpdateConversation(ctx, conversation); err != nil {
        return nil, err
    }

    return message, nil
}

// 业务规则检查
func (c *Conversation) CanSendMessage() bool {
    // 检查会话状态
    if c.Status != StatusActive {
        return false
    }
    // 检查消息数量限制
    if c.Limits.CurrentMessages >= c.Limits.MaxMessages {
        return false
    }
    return true
}

第1层：HTTP Handler
  ↓ 解析路径参数（conversation_id）
  ↓ 绑定请求体（user_id, role, content）
  ↓ 耗时：<1ms

第2层：Service Layer
  ↓ 参数转换和预处理
  ↓ 耗时：<1ms

第3层：MessageUsecase
  ↓ 复杂业务逻辑：
  ↓   1️⃣ 查询会话（权限验证）
  ↓   2️⃣ 检查业务规则（CanSendMessage）
  ↓   3️⃣ 创建消息领域对象
  ↓   4️⃣ 并行执行三个操作：
  ↓      • 保存消息到数据库
  ↓      • 更新会话统计
  ↓      • 失效上下文缓存
  ↓ 耗时：60-100ms（含数据库操作）

第4层：Repository Layer
  ↓ 三个并发操作：
  ↓   • ConversationRepo.GetConversation() → SELECT
  ↓   • MessageRepo.CreateMessage() → INSERT
  ↓   • ConversationRepo.UpdateConversation() → UPDATE
  ↓   • ContextCache.InvalidateContext() → Redis DEL
  ↓ 耗时：并行最大 30ms（非串行）

第5层：Storage Layer
  ↓ PostgreSQL + Redis
  ↓ 事务保证：消息INSERT + 会话UPDATE 在同一事务
  ↓ 耗时：20-30ms

// 第3层：MessageUsecase.SendMessage()
func (uc *MessageUsecase) SendMessage(
    ctx context.Context,
    conversationID, userID string,
    role domain.MessageRole,
    content string,
) (*domain.Message, error) {
    // 步骤1：查询会话（权限验证）
    conversation, err := uc.conversationRepo.GetConversation(ctx, conversationID)
    if err != nil {
        return nil, err
    }

    // 步骤2：权限检查
    if conversation.UserID != userID {
        return nil, domain.ErrUnauthorized
    }

    // 步骤3：业务规则验证
    if !conversation.CanSendMessage() {
        return nil, domain.ErrConversationFull
    }

    // 步骤4：创建消息领域对象
    message := domain.NewMessage(conversationID, conversation.TenantID, userID, role, content)

    // 步骤5：并行执行三个操作
    errGroup, ctx := errgroup.WithContext(ctx)

    // 操作1：保存消息
    errGroup.Go(func() error {
        return uc.messageRepo.CreateMessage(ctx, message)
    })

    // 操作2：更新会话统计
    errGroup.Go(func() error {
        conversation.IncrementMessageCount()
        return uc.conversationRepo.UpdateConversation(ctx, conversation)
    })

    // 操作3：失效缓存
    errGroup.Go(func() error {
        return uc.contextCache.InvalidateContext(ctx, conversationID)
    })

    // 等待所有操作完成
    if err := errGroup.Wait(); err != nil {
        return nil, err
    }

    return message, nil
}