dao

type ConversationListEntry struct {
	Conversation defs.Conversation `json:"conversation"`
	RootSession  defs.Session      `json:"root_session"`
}

type ConversationMutation interface {
	// SetConversation 追加对话的 metadata 日志，写入归档状态对应分组的索引，并删掉另一个分组里的旧索引。
	SetConversation(context.Context, defs.Conversation) error
}

type ConversationQuery interface {
	// GetConversation 读取指定对话，返回记录及是否找到。
	GetConversation(context.Context, defs.ConversationID) (defs.Conversation, bool, error)
	// ListConversations 返回筛选后的一页对话及各自的根 Session；根 Session 记录缺失或损坏时返回错误。
	ListConversations(context.Context, ListConversationsRequest) (storage.Page[ConversationListEntry, RecordCursor[defs.ConversationID]], error)
}

type DAOOpt struct {
	Records storage.RecordStorage
	Logs    storage.LogStorage
}

type ItemMutation interface {
	// AppendItems 追加一批 Item，返回带对外序号和保存时间的副本；不修改传入的 Item。
	AppendItems(context.Context, defs.ConversationID, defs.SessionID, ...*defs.Item) ([]LoggedItem, error)
}

type ItemQuery interface {
	// ListItems 按对外序号分页读取 Session 日志。对外序号是调用方看到的 Item 序号：用户分叉的根 Session 前面接上
	// 来源对话的历史，序号从来源的第 1 条连续排下来，接续标记本身不返回；来源读不到时那一段当作空。
	ListItems(context.Context, ListItemsRequest) (storage.Page[LoggedItem, storage.Ordinal], error)
	// ScanItems 按方向逐条读取 Session 日志，调用方 break 后不再读后续页。
	ScanItems(context.Context, defs.ConversationID, defs.SessionID, storage.Direction) iter.Seq2[*defs.Item, error]
}

type ListConversationsRequest struct {
	// Directories 精确匹配 local 工作目录；为空时不限目录，多个目录命中任意一个。
	Directories []string
	// SearchTerm 按区分大小写的普通子串匹配标题；为空时不筛选标题。
	SearchTerm string
	Order      storage.Order
	// Cursor 是上一页最后一条的位置；零值从头开始。
	Cursor RecordCursor[defs.ConversationID]
	Limit  int
	// Archived 是否只列归档的对话？false 时只列没归档的。
	Archived bool
}

type ListItemsRequest struct {
	ConversationID defs.ConversationID
	SessionID      defs.SessionID
	Order          storage.Direction
	// Cursor 是上一页返回的 Next；0 时从这个方向的起点读。
	Cursor storage.Ordinal
	Limit  int
}

type ListSessionsRequest struct {
	ConversationID defs.ConversationID
	Order          storage.Order
	// Cursor 是上一页最后一条的位置；零值从头开始。
	Cursor RecordCursor[defs.SessionID]
	Limit  int
}

type ListTurnsRequest struct {
	SessionID defs.SessionID
	Order     storage.Order
	// Cursor 是上一页最后一条的位置；零值从头开始。
	Cursor RecordCursor[defs.TurnID]
	Limit  int
}

type LoggedItem struct {
	// Ordinal 是对外序号；用户分叉的根 Session 已经接在来源历史的序号之后。
	Ordinal storage.Ordinal
	Item    *defs.Item
}

type Mutation interface {
	ConversationMutation
	SessionMutation
	TurnMutation
	ItemMutation
	// DeleteConversation 先在 metadata 日志里记下删除，再删除对话的各级索引和全部日志；对话不存在时直接返回。
	DeleteConversation(ctx context.Context, conversationID defs.ConversationID) error
}

type Query interface {
	ConversationQuery
	SessionQuery
	TurnQuery
	ItemQuery
}

type RebuildMetadataIndexResult struct {
	// RebuiltConversations 是写入索引的对话数。
	RebuiltConversations int
	// SkippedConversations 是因 metadata 不完整或损坏而没有写入索引的对话及原因；没有时为空切片。
	SkippedConversations []SkippedConversation
	// DeletedConversations 是 metadata 日志里记了删除、这次重建顺带删掉目录的对话；没有时为空切片。
	DeletedConversations []defs.ConversationID
}

type RecordCursor[ID ~string] struct {
	// ID 是上一页最后一条记录的 ID；为空时从头开始。
	ID ID `json:"id"`
	// UpdatedAt 是上一页最后一条记录的更新时间；按 Key 排序时不用。
	UpdatedAt int64 `json:"updated_at,omitempty"`
}

type SessionMutation interface {
	// SetSession 保存 Session 的日志和索引。
	SetSession(context.Context, defs.Session) error
	// DeleteSession 先在 metadata 日志里记下删除，再删除 Session 的 Turn 索引、Item 日志和 Session 索引；Session 不存在时直接返回。
	DeleteSession(context.Context, defs.ConversationID, defs.SessionID) error
}

type SessionQuery interface {
	// GetSession 读取对话内指定 Session，返回记录及是否找到。
	GetSession(context.Context, defs.ConversationID, defs.SessionID) (defs.Session, bool, error)
	// GetSessionByID 只凭 Session ID 读取记录；Session 还没写过 Item 时返回未找到。
	GetSessionByID(ctx context.Context, sessionID defs.SessionID) (defs.Session, bool, error)
	// ListSessions 分页读取对话内的 Session。
	ListSessions(context.Context, ListSessionsRequest) (storage.Page[defs.Session, RecordCursor[defs.SessionID]], error)
	// ScanSessions 按排序逐条读取对话内全部 Session，调用方 break 后停止。
	ScanSessions(context.Context, defs.ConversationID, storage.Order) iter.Seq2[defs.Session, error]
}

type SkippedConversation struct {
	// ConversationID 是对话 ID，也是它的日志目录名。
	ConversationID defs.ConversationID
	// Reason 是跳过的原因。
	Reason error
}

type TurnMutation interface {
	// SetTurn 保存 Turn 的日志和索引。
	SetTurn(context.Context, defs.Turn) error
}

type TurnQuery interface {
	// GetTurn 读取 Session 内指定 Turn，返回记录及是否找到。
	GetTurn(context.Context, defs.SessionID, defs.TurnID) (defs.Turn, bool, error)
	// GetTurns 按输入 ID 顺序返回 Session 中找到的 Turn，跳过不存在的记录。
	GetTurns(ctx context.Context, sessionID defs.SessionID, ids []defs.TurnID) ([]defs.Turn, error)
	// ListTurns 分页读取 Session 内的 Turn。
	ListTurns(context.Context, ListTurnsRequest) (storage.Page[defs.Turn, RecordCursor[defs.TurnID]], error)
}