CamTalk/backend/internal/session/manager.go

// Package session 提供会话生命周期管理能力。
package session

import (
	"context"
	"errors"
	"time"

	"github.com/hhs/camtalk/internal/models"
)

// ErrSessionNotFound 会话不存在或已过期。
var ErrSessionNotFound = errors.New("session not found")

// ConversationSummary 对话摘要（列表展示用）。
type ConversationSummary struct {
	ID           string    `json:"id"`
	Title        string    `json:"title"`
	LastMessage  string    `json:"last_message"`
	MessageCount int       `json:"message_count"`
	CreatedAt    time.Time `json:"created_at"`
	UpdatedAt    time.Time `json:"updated_at"`
}

// Manager 会话管理器接口。
// WebSocket Handler 通过此接口操作会话，不直接接触存储层。
type Manager interface {
	// Create 创建新会话，返回 session ID。userID 为空表示匿名会话。
	Create(ctx context.Context, userID string, config models.SessionConfig) (string, error)

	// Get 获取会话（含 config）。不存在返回 ErrSessionNotFound。
	Get(ctx context.Context, sessionID string) (*models.Session, error)

	// UpdateConfig 更新会话配置（config 消息触发）。
	UpdateConfig(ctx context.Context, sessionID string, patch models.SessionConfigPatch) error

	// UpdateTitle 更新会话标题。
	UpdateTitle(ctx context.Context, sessionID string, title string) error

	// ListByUser 获取用户的对话列表（分页，按 UpdatedAt 降序）。
	ListByUser(ctx context.Context, userID string, page, size int) ([]ConversationSummary, int, error)

	// GetHistory 获取最近 N 轮对话历史（供 Orchestrator 构建 LLM 上下文）。
	GetHistory(ctx context.Context, sessionID string, limit int) ([]models.Message, error)

	// AppendMessage 追加一条对话消息，同时刷新 TTL。
	AppendMessage(ctx context.Context, sessionID string, msg models.Message) error

	// SetActiveRequest 标记当前正在处理的请求 ID（interrupt 用）。
	SetActiveRequest(ctx context.Context, sessionID string, requestID string) error

	// GetActiveRequestID 获取当前活跃请求 ID。
	GetActiveRequestID(ctx context.Context, sessionID string) (string, error)

	// ClearActiveRequest 清除活跃请求标记（请求完成或中断后）。
	ClearActiveRequest(ctx context.Context, sessionID string) error

	// Touch 刷新 TTL（心跳时调用）。
	Touch(ctx context.Context, sessionID string) error

	// Destroy 显式销毁会话（REST API DELETE 或连接断开清理）。
	Destroy(ctx context.Context, sessionID string) error

	// ActiveCount 返回当前活跃会话数（健康检查用）。
	ActiveCount() int
}