MailUI4Agents/gateway/internal/handler/thread.go

package handler

import (
	"net/http"
	"strconv"

	"github.com/agentmail/gateway/internal/middleware"
	"github.com/agentmail/gateway/internal/repo"
	"github.com/google/uuid"
)

// ---------- 对话树（按方向分块加载） ----------

// 分页参数。上限存在的意义是防止 ?limit=100000 一次把整条线索拉走 ——
// 那就等于绕过了分块加载。
const (
	threadDefaultLimit = 40
	threadMaxLimit     = 200
)

// threadNode 是返回给前端的树节点。
//
// Detached 表示「这封的父邮件当前不在返回集里」，两种原因：
//   - 父邮件不可见（转发把线索引到别处，下游往来不回流给上游参与者）
//   - 父邮件还没加载（分块加载的边界，往上滑会补上）
//
// 前端据此画出断点，而不是因为找不到父节点就把它悄悄丢掉。
// 两种原因用 ParentHidden 区分：不可见是永久的，未加载是暂时的。
type threadNode struct {
	repo.TreeMail
	Detached bool `json:"detached,omitempty"`
	// ParentHidden 为真表示父邮件确实存在但无权查看（不是尚未加载）
	ParentHidden bool `json:"parent_hidden,omitempty"`
}

// GET /api/v1/mail/{id}/thread
//
// 以给定邮件为锚点，按方向分块返回线索：
//
//	?dir=around（默认）  锚点 + 一批祖先 + 一批子孙，首屏用
//	?dir=up&offset=N     继续往上取祖先（上滑加载）
//	?dir=down&offset=N   继续往下取子孙
//
// offset 是**相对锚点**的偏移：up 方向按层数（已取到的祖先数），
// down 方向按节点数（已取到的子孙数）。锚点本身只在 around/down&offset=0 时返回。
//
// 树可跨会话（转发是新线索但仍指向原件），因此**逐个会话鉴权**，
// 只返回当前用户有权访问的节点。被过滤掉的计入 hidden。
func GetMailThread(w http.ResponseWriter, r *http.Request) {
	user := middleware.GetUser(r)
	if user == nil {
		Error(w, http.StatusUnauthorized, "not authenticated")
		return
	}
	mailID, ok := pathUUID(w, r, "id")
	if !ok {
		return
	}

	// 先确认调用者确实看得到作为锚点的这封邮件，否则等于给了一个
	// 「随便报 mail_id 就能探测线索存在性」的接口
	mail, err := repo.GetMailByID(r.Context(), mailID)
	if err != nil {
		Error(w, http.StatusNotFound, "Mail not found")
		return
	}
	allowed, err := repo.UserCanAccessSession(r.Context(), user, mail.SessionID)
	if err != nil {
		Error(w, http.StatusInternalServerError, "Failed to check permission")
		return
	}
	if !allowed {
		Error(w, http.StatusForbidden, "无权访问该邮件")
		return
	}

	dir := r.URL.Query().Get("dir")
	if dir == "" {
		dir = "around"
	}
	if dir != "around" && dir != "up" && dir != "down" {
		Error(w, http.StatusBadRequest, "dir 只能是 around、up 或 down")
		return
	}
	limit := intQuery(r, "limit", threadDefaultLimit, 1, threadMaxLimit)
	offset := intQuery(r, "offset", 0, 0, 1<<20)

	// 会话鉴权结果按会话缓存：一条线索里同一会话通常有多封，逐封查是浪费
	seen := map[uuid.UUID]bool{}
	canSee := func(sid uuid.UUID) bool {
		if v, ok := seen[sid]; ok {
			return v
		}
		v, err := repo.UserCanAccessSession(r.Context(), user, sid)
		if err != nil {
			v = false // 查不出来就当看不到：宁可少给，不可多给
		}
		seen[sid] = v
		return v
	}

	var (
		raw        []repo.TreeMail
		hasMoreUp  bool
		hasMoreDn  bool
		wantUp     = dir == "around" || dir == "up"
		wantDown   = dir == "around" || dir == "down"
		upOffset   = offset
		downOffset = offset
	)

	// around 时两个方向各取一半，避免首屏一次要求 2×limit。
	// 两边至少各给 1：否则 limit=1 时会算出 downLimit=0，连锚点自己都不返回。
	upLimit, downLimit := limit, limit
	if dir == "around" {
		upLimit = limit / 2
		if upLimit < 1 {
			upLimit = 1
		}
		downLimit = limit - upLimit
		if downLimit < 1 {
			downLimit = 1
		}
		upOffset, downOffset = 0, 0
	}

	if wantUp {
		anc, more, err := repo.AncestorsRaw(r.Context(), mailID, upOffset, upLimit)
		if err != nil {
			Error(w, http.StatusInternalServerError, "Failed to load ancestors")
			return
		}
		raw = append(raw, anc...)
		hasMoreUp = more
	}
	if wantDown {
		// around 与 down&offset=0 会带上锚点自己（Depth 0）；
		// up 方向单独请求时不带，前端已经有它了
		desc, more, err := repo.DescendantsRaw(r.Context(), mailID, downOffset, downLimit)
		if err != nil {
			Error(w, http.StatusInternalServerError, "Failed to load descendants")
			return
		}
		raw = append(raw, desc...)
		hasMoreDn = more
	}

	// 可见性过滤。父节点是否在**本次返回集**里决定 detached；
	// 父存在却不在集里，再判断是"无权看"还是"没加载"。
	visible := map[uuid.UUID]bool{}
	for _, m := range raw {
		if canSee(m.SessionID) {
			visible[m.ID] = true
		}
	}

	nodes := []threadNode{}
	for _, m := range raw {
		if !visible[m.ID] {
			continue
		}
		n := threadNode{TreeMail: m}
		if m.ParentMailID != nil && !visible[*m.ParentMailID] {
			n.Detached = true
			// 父邮件在本次结果里出现过但被过滤掉 = 确实无权查看；
			// 完全没出现过 = 只是还没加载到，往上滑会补上
			for _, other := range raw {
				if other.ID == *m.ParentMailID {
					n.ParentHidden = true
					break
				}
			}
		}
		nodes = append(nodes, n)
	}

	JSON(w, http.StatusOK, map[string]interface{}{
		"anchor_mail_id": mailID,
		"dir":            dir,
		"nodes":          nodes,
		"total":          len(nodes),
		"hidden":         len(raw) - len(nodes),
		// 下一页的 offset。前端把它原样回传即可，不必自己算已加载数量。
		"has_more_up":   hasMoreUp,
		"has_more_down": hasMoreDn,
		"next_up":       upOffset + upLimit,
		"next_down":     downOffset + downLimit,
	})
}

// intQuery 读取整数 query 参数并夹到 [min, max]。
// 非法值一律回落到默认值 —— 分页参数不该因为一个笔误就让整个请求失败。
func intQuery(r *http.Request, key string, def, min, max int) int {
	s := r.URL.Query().Get(key)
	if s == "" {
		return def
	}
	v, err := strconv.Atoi(s)
	if err != nil {
		return def
	}
	if v < min {
		return min
	}
	if v > max {
		return max
	}
	return v
}