refactor(server): 会话/访客/设置业务逻辑下沉 internal/service 层，handler 瘦身

- handler 只保留请求绑定、权限检查与响应映射；业务校验顺序、状态码与文案逐字保留
- 新增 service.Error 语义错误，由 handler 统一映射 HTTP 响应
- session 875→361 行、widget 745→321 行、settings 540→73 行
- 自动分配/租户设置(工作时间、欢迎语)/消息校验/黑名单检查/联系方式提取随迁 service 包
- 相关单元测试随迁 service 包，go test ./... 全部通过

server/internal/handler/session.go

@@ -1,18 +1,14 @@
 package handler
 
 import (
+	"errors"
 	"net/http"
-	"sort"
 	"strconv"
 	"strings"
-	"time"
-	"unicode/utf8"
 
 	"github.com/gin-gonic/gin"
-	"gorm.io/gorm"
 	"kefu-cloud/server/internal/middleware"
-	"kefu-cloud/server/internal/model"
-	"kefu-cloud/server/internal/ws"
+	"kefu-cloud/server/internal/service"
 )
 
 type SessionHandler struct{}
@@ -24,75 +20,10 @@ type SendMessageReq struct {
 	Type    string `json:"type"`
 }
 
-type SessionListItem struct {
-	model.Session
-	UnreadCount   int        `json:"unread_count"`
-	LastMessage   string     `json:"last_message"`
-	LastMessageAt *time.Time `json:"last_message_at,omitempty"`
-	MessageCount  int        `json:"message_count"`
-	CustomerName  string     `json:"customer_name"`
-	AgentName     string     `json:"agent_name"`
-	ChannelName   string     `json:"channel_name"`
-	ChannelType   string     `json:"channel_type"`
-}
-
 type CreateNoteReq struct {
 	Content string `json:"content" binding:"required"`
 }
 
-func (h *SessionHandler) SendMessage(c *gin.Context) {
-	userID := middleware.GetUserID(c)
-	id := c.Param("id")
-
-	var req SendMessageReq
-	if err := c.ShouldBindJSON(&req); err != nil {
-		c.JSON(http.StatusBadRequest, gin.H{"code": 400, "message": "参数错误"})
-		return
-	}
-	if req.Type == "" {
-		req.Type = "text"
-	}
-	content, err := validateMessageContent(req.Type, req.Content)
-	if err != nil {
-		c.JSON(http.StatusBadRequest, gin.H{"code": 400, "message": err.Error()})
-		return
-	}
-
-	session, ok := loadTenantSession(c, id)
-	if !ok {
-		return
-	}
-	if !canOperateSession(c, session) {
-		c.JSON(http.StatusForbidden, gin.H{"code": 403, "message": "无权向该会话发送消息"})
-		return
-	}
-	if session.Status == "ended" || session.Status == "archived" {
-		c.JSON(http.StatusConflict, gin.H{"code": 409, "message": "会话已结束"})
-		return
-	}
-
-	msg := model.Message{
-		SessionID:  session.ID,
-		SenderType: "agent",
-		SenderID:   &userID,
-		Content:    content,
-		Type:       req.Type,
-		SentAt:     time.Now(),
-	}
-
-	if err := model.CreateMessage(&msg); err != nil {
-		c.JSON(http.StatusInternalServerError, gin.H{"code": 500, "message": "发送失败"})
-		return
-	}
-	if !middleware.CanAccessAllData(c, "session") {
-		model.DB.Model(&model.Session{}).Where("id = ?", session.ID).Update("last_read_seq", msg.Seq)
-		session.LastReadSeq = msg.Seq
-	}
-	broadcastSessionMessage(session, msg)
-
-	middleware.JSON(c, msg)
-}
-
 type CreateSessionReq struct {
 	ChannelID  uint   `json:"channel_id"`
 	CustomerID uint   `json:"customer_id"`
@@ -103,309 +34,108 @@ type AssignSessionReq struct {
 	AgentID uint `json:"agent_id"`
 }
 
-func isTenantManager(c *gin.Context) bool {
-	return middleware.CanAccessAllData(c, "session")
-}
-
-func loadTenantSession(c *gin.Context, id string) (*model.Session, bool) {
-	var session model.Session
-	if err := model.DB.First(&session, id).Error; err != nil {
-		c.JSON(http.StatusNotFound, gin.H{"code": 404, "message": "会话不存在"})
-		return nil, false
-	}
-	if session.TenantID != middleware.GetTenantID(c) {
-		c.JSON(http.StatusForbidden, gin.H{"code": 403, "message": "无权访问其他租户会话"})
-		return nil, false
-	}
-	return &session, true
-}
-
-func canReadSession(c *gin.Context, session *model.Session) bool {
-	module := "session"
-	if session.Status == "ended" || session.Status == "archived" {
-		module = "chat_history"
-	}
-	if middleware.CanAccessAllData(c, module) {
-		return true
-	}
-	userID := middleware.GetUserID(c)
-	return session.Status == "waiting" || (session.AgentID != nil && *session.AgentID == userID)
-}
-
-func canOperateSession(c *gin.Context, session *model.Session) bool {
-	if isTenantManager(c) {
-		return true
-	}
-	return session.AgentID != nil && *session.AgentID == middleware.GetUserID(c)
-}
-
-func broadcastSessionMessage(session *model.Session, message model.Message) {
-	payload, err := ws.NewEvent("message", session.ID, message)
-	if err == nil {
-		ws.DefaultHub.BroadcastToSession(session.TenantID, session.ID, session.AgentID, payload)
+// sessionActor 从鉴权中间件结果构造 service 层发起者。
+func sessionActor(c *gin.Context) service.Actor {
+	return service.Actor{
+		UserID:     middleware.GetUserID(c),
+		SessionAll: middleware.CanAccessAllData(c, "session"),
+		HistoryAll: middleware.CanAccessAllData(c, "chat_history"),
 	}
 }
 
-func broadcastSessionUpdate(session *model.Session) {
-	payload, err := ws.NewEvent("session_updated", session.ID, gin.H{"status": session.Status})
-	if err != nil {
+// respondServiceError 将 service 业务错误映射为 HTTP 响应。
+func respondServiceError(c *gin.Context, err error) {
+	var be *service.Error
+	if errors.As(err, &be) {
+		c.JSON(be.Status, gin.H{"code": be.Status, "message": be.Message})
 		return
 	}
-	// 坐席列表需要刷新；访客也必须收到 ended/active，才能弹出评价或更新接待状态
-	ws.DefaultHub.BroadcastToTenantStaff(session.TenantID, payload)
-	ws.DefaultHub.BroadcastToVisitor(session.TenantID, session.ID, payload)
+	c.JSON(http.StatusInternalServerError, gin.H{"code": 500, "message": "服务器内部错误"})
 }
 
-func loadAssignableAgent(tenantID, agentID uint) error {
-	var agent model.User
-	if err := model.DB.First(&agent, agentID).Error; err != nil {
-		return err
+func (h *SessionHandler) SendMessage(c *gin.Context) {
+	var req SendMessageReq
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"code": 400, "message": "参数错误"})
+		return
 	}
-	if agent.TenantID != tenantID || agent.Status == "disabled" {
-		return gorm.ErrRecordNotFound
+	if req.Type == "" {
+		req.Type = "text"
 	}
-	if agent.Role == "agent" {
-		return nil
+	// 先校验内容，再加载会话（与原校验顺序一致）
+	content, err := service.ValidateMessageContent(req.Type, req.Content)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"code": 400, "message": err.Error()})
+		return
 	}
-	var count int64
-	if err := model.DB.Table("roles r").
-		Joins("JOIN role_permissions rp ON rp.role_id = r.id").
-		Joins("JOIN permissions p ON p.id = rp.permission_id").
-		Where("r.tenant_id = ? AND r.code = ? AND r.type = ? AND p.code = ?", tenantID, agent.Role, "custom", "session.reply").
-		Count(&count).Error; err != nil || count == 0 {
-		return gorm.ErrRecordNotFound
+	session, err := service.LoadTenantSession(c.Param("id"), middleware.GetTenantID(c))
+	if err != nil {
+		respondServiceError(c, err)
+		return
 	}
-	return nil
-}
-
-func assignableRoleCodes(tenantID uint) []string {
-	codes := []string{"agent"}
-	var customCodes []string
-	model.DB.Table("roles r").
-		Joins("JOIN role_permissions rp ON rp.role_id = r.id").
-		Joins("JOIN permissions p ON p.id = rp.permission_id").
-		Where("r.tenant_id = ? AND r.type = ? AND p.code = ?", tenantID, "custom", "session.reply").
-		Distinct().Pluck("r.code", &customCodes)
-	return append(codes, customCodes...)
-}
-
-func unreadCount(session model.Session) int {
-	var count int64
-	model.DB.Model(&model.Message{}).
-		Where("session_id = ? AND sender_type = ? AND seq > ?", session.ID, "visitor", session.LastReadSeq).
-		Count(&count)
-	return int(count)
+	msg, err := service.AgentSendMessage(session, sessionActor(c), req.Type, content)
+	if err != nil {
+		respondServiceError(c, err)
+		return
+	}
+	middleware.JSON(c, msg)
 }
 
 func (h *SessionHandler) List(c *gin.Context) {
-	tenantID := middleware.GetTenantID(c)
 	page, pageSize := middleware.GetPageParams(c)
-	status := c.Query("status")
-	priority := c.Query("priority")
-	agentID := c.Query("agent_id")
-	channelID := c.Query("channel_id")
-	search := strings.TrimSpace(c.Query("search"))
-	from := c.Query("from")
-	to := c.Query("to")
-
-	var sessions []model.Session
-	var total int64
-
-	query := model.DB.Model(&model.Session{}).Where("sessions.tenant_id = ?", tenantID)
-	if !middleware.CanAccessAllData(c, "session") || !middleware.CanAccessAllData(c, "chat_history") {
-		query = query.Where("sessions.agent_id = ? OR sessions.status = ?", middleware.GetUserID(c), "waiting")
+	f := service.SessionFilter{
+		Status:    c.Query("status"),
+		Priority:  c.Query("priority"),
+		AgentID:   c.Query("agent_id"),
+		ChannelID: c.Query("channel_id"),
+		Search:    strings.TrimSpace(c.Query("search")),
+		From:      c.Query("from"),
+		To:        c.Query("to"),
+		Page:      page,
+		PageSize:  pageSize,
 	}
-	if status != "" {
-		query = query.Where("sessions.status = ?", status)
-	}
-	if priority != "" {
-		query = query.Where("sessions.priority = ?", priority)
-	}
-	if agentID != "" {
-		query = query.Where("sessions.agent_id = ?", agentID)
-	}
-	if channelID != "" {
-		query = query.Where("sessions.channel_id = ?", channelID)
-	}
-	if from != "" {
-		if t, err := time.ParseInLocation("2006-01-02", from, time.Local); err == nil {
-			query = query.Where("sessions.created_at >= ?", t)
-		}
-	}
-	if to != "" {
-		if t, err := time.ParseInLocation("2006-01-02", to, time.Local); err == nil {
-			query = query.Where("sessions.created_at < ?", t.Add(24*time.Hour))
-		}
-	}
-	if search != "" {
-		like := "%" + search + "%"
-		query = query.Joins("LEFT JOIN customers ON customers.id = sessions.customer_id").
-			Where("customers.name LIKE ? OR CAST(sessions.id AS TEXT) LIKE ? OR COALESCE(sessions.end_reason, '') LIKE ?", like, like, like)
-	}
-
-	query.Count(&total)
-	if err := query.Order("sessions.created_at desc").Offset((page - 1) * pageSize).Limit(pageSize).Find(&sessions).Error; err != nil {
-		c.JSON(http.StatusInternalServerError, gin.H{"code": 500, "message": "查询会话失败"})
+	items, total, err := service.ListSessions(sessionActor(c), middleware.GetTenantID(c), f)
+	if err != nil {
+		respondServiceError(c, err)
 		return
 	}
-
-	// 批量补全客户 / 客服 / 渠道 / 消息数
-	customerIDs := make([]uint, 0)
-	agentIDs := make([]uint, 0)
-	channelIDs := make([]uint, 0)
-	sessionIDs := make([]uint, 0, len(sessions))
-	for _, s := range sessions {
-		sessionIDs = append(sessionIDs, s.ID)
-		customerIDs = append(customerIDs, s.CustomerID)
-		channelIDs = append(channelIDs, s.ChannelID)
-		if s.AgentID != nil {
-			agentIDs = append(agentIDs, *s.AgentID)
-		}
-	}
-	customerMap := map[uint]model.Customer{}
-	if len(customerIDs) > 0 {
-		var customers []model.Customer
-		model.DB.Where("id IN ?", uniqueUint(customerIDs)).Find(&customers)
-		for _, cu := range customers {
-			customerMap[cu.ID] = cu
-		}
-	}
-	agentMap := map[uint]model.User{}
-	if len(agentIDs) > 0 {
-		var users []model.User
-		model.DB.Where("id IN ?", uniqueUint(agentIDs)).Find(&users)
-		for _, u := range users {
-			agentMap[u.ID] = u
-		}
-	}
-	channelMap := map[uint]model.Channel{}
-	if len(channelIDs) > 0 {
-		var channels []model.Channel
-		model.DB.Where("id IN ?", uniqueUint(channelIDs)).Find(&channels)
-		for _, ch := range channels {
-			channelMap[ch.ID] = ch
-		}
-	}
-	msgCountMap := map[uint]int{}
-	if len(sessionIDs) > 0 {
-		type row struct {
-			SessionID uint
-			Cnt       int
-		}
-		var rows []row
-		model.DB.Model(&model.Message{}).
-			Select("session_id, COUNT(*) as cnt").
-			Where("session_id IN ?", sessionIDs).
-			Group("session_id").
-			Scan(&rows)
-		for _, r := range rows {
-			msgCountMap[r.SessionID] = r.Cnt
-		}
-	}
-
-	items := make([]SessionListItem, 0, len(sessions))
-	for _, session := range sessions {
-		item := SessionListItem{Session: session, MessageCount: msgCountMap[session.ID]}
-		if !middleware.CanAccessAllData(c, "session") && session.AgentID != nil && *session.AgentID == middleware.GetUserID(c) {
-			item.UnreadCount = unreadCount(session)
-		}
-		if cu, ok := customerMap[session.CustomerID]; ok {
-			item.CustomerName = cu.Name
-		}
-		if session.AgentID != nil {
-			if u, ok := agentMap[*session.AgentID]; ok {
-				item.AgentName = u.Nickname
-			}
-		}
-		if ch, ok := channelMap[session.ChannelID]; ok {
-			item.ChannelName = ch.Name
-			item.ChannelType = ch.Type
-		}
-		var lastMsg model.Message
-		if err := model.DB.Where("session_id = ?", session.ID).Order("seq desc").First(&lastMsg).Error; err == nil {
-			if lastMsg.Type == "image" {
-				item.LastMessage = "[图片]"
-			} else {
-				item.LastMessage = lastMsg.Content
-				if utf8.RuneCountInString(item.LastMessage) > 40 {
-					runes := []rune(item.LastMessage)
-					item.LastMessage = string(runes[:40]) + "…"
-				}
-			}
-			t := lastMsg.SentAt
-			item.LastMessageAt = &t
-		}
-		items = append(items, item)
-	}
-
 	middleware.JSONList(c, items, total, page, pageSize)
 }
 
-func uniqueUint(ids []uint) []uint {
-	seen := make(map[uint]struct{}, len(ids))
-	out := make([]uint, 0, len(ids))
-	for _, id := range ids {
-		if id == 0 {
-			continue
-		}
-		if _, ok := seen[id]; ok {
-			continue
-		}
-		seen[id] = struct{}{}
-		out = append(out, id)
-	}
-	return out
-}
-
 func (h *SessionHandler) Get(c *gin.Context) {
-	id := c.Param("id")
-
-	session, ok := loadTenantSession(c, id)
-	if !ok {
+	session, err := service.LoadTenantSession(c.Param("id"), middleware.GetTenantID(c))
+	if err != nil {
+		respondServiceError(c, err)
 		return
 	}
-	if !canReadSession(c, session) {
+	if !service.CanReadSession(sessionActor(c), session) {
 		c.JSON(http.StatusForbidden, gin.H{"code": 403, "message": "无权查看该会话"})
 		return
 	}
-
-	var messages []model.Message
-	if err := model.DB.Where("session_id = ?", session.ID).Order("seq asc").Find(&messages).Error; err != nil {
-		c.JSON(http.StatusInternalServerError, gin.H{"code": 500, "message": "查询消息失败"})
+	detail, err := service.SessionDetail(session)
+	if err != nil {
+		respondServiceError(c, err)
 		return
 	}
-	var events []model.SessionEvent
-	model.DB.Where("session_id = ?", session.ID).Order("created_at asc").Find(&events)
-	var pageViews []model.VisitorPageView
-	// 最新在前，坐席侧无需滚到底
-	model.DB.Where("session_id = ?", session.ID).Order("entered_at desc").Limit(maxPageViewsPerSession).Find(&pageViews)
-	var pendingCount int64
-	model.DB.Model(&model.Session{}).Where("customer_id = ? AND tenant_id = ? AND status = ?", session.CustomerID, session.TenantID, "waiting").Count(&pendingCount)
-
-	maxSeq := 0
-	for _, m := range messages {
-		if m.Seq > maxSeq {
-			maxSeq = m.Seq
-		}
-	}
 	middleware.JSON(c, gin.H{
 		"session":       session,
-		"messages":      messages,
-		"events":        events,
-		"page_views":    pageViews,
-		"pending_count": pendingCount,
-		"max_seq":       maxSeq,
+		"messages":      detail.Messages,
+		"events":        detail.Events,
+		"page_views":    detail.PageViews,
+		"pending_count": detail.PendingCount,
+		"max_seq":       detail.MaxSeq,
 	})
 }
 
 // ListMessages 按 seq 增量拉取消息：after_seq 之后的新消息（重连 catch-up）。
 // GET /sessions/:id/messages?after_seq=12
 func (h *SessionHandler) ListMessages(c *gin.Context) {
-	session, ok := loadTenantSession(c, c.Param("id"))
-	if !ok {
+	session, err := service.LoadTenantSession(c.Param("id"), middleware.GetTenantID(c))
+	if err != nil {
+		respondServiceError(c, err)
 		return
 	}
-	if !canReadSession(c, session) {
+	if !service.CanReadSession(sessionActor(c), session) {
 		c.JSON(http.StatusForbidden, gin.H{"code": 403, "message": "无权查看该会话消息"})
 		return
 	}
@@ -430,65 +160,44 @@ func (h *SessionHandler) ListMessages(c *gin.Context) {
 		}
 	}
 
-	query := model.DB.Where("session_id = ?", session.ID)
-	if afterSeq > 0 {
-		query = query.Where("seq > ?", afterSeq)
-	}
-
-	var messages []model.Message
-	if err := query.Order("seq asc").Limit(limit).Find(&messages).Error; err != nil {
-		c.JSON(http.StatusInternalServerError, gin.H{"code": 500, "message": "查询消息失败"})
+	page, err := service.SessionMessagePage(session.ID, afterSeq, limit)
+	if err != nil {
+		respondServiceError(c, err)
 		return
 	}
-
-	var maxSeq int
-	if err := model.DB.Model(&model.Message{}).
-		Where("session_id = ?", session.ID).
-		Select("COALESCE(MAX(seq), 0)").
-		Scan(&maxSeq).Error; err != nil {
-		c.JSON(http.StatusInternalServerError, gin.H{"code": 500, "message": "查询消息失败"})
-		return
-	}
-
 	middleware.JSON(c, gin.H{
-		"messages":  messages,
-		"after_seq": afterSeq,
-		"max_seq":   maxSeq,
-		"has_more":  len(messages) >= limit && (len(messages) == 0 || messages[len(messages)-1].Seq < maxSeq),
+		"messages":  page.Messages,
+		"after_seq": page.AfterSeq,
+		"max_seq":   page.MaxSeq,
+		"has_more":  page.HasMore,
 	})
 }
 
 func (h *SessionHandler) MarkRead(c *gin.Context) {
-	session, ok := loadTenantSession(c, c.Param("id"))
-	if !ok {
+	session, err := service.LoadTenantSession(c.Param("id"), middleware.GetTenantID(c))
+	if err != nil {
+		respondServiceError(c, err)
 		return
 	}
-	if !canReadSession(c, session) {
+	if !service.CanReadSession(sessionActor(c), session) {
 		c.JSON(http.StatusForbidden, gin.H{"code": 403, "message": "无权标记该会话已读"})
 		return
 	}
-	if session.AgentID == nil || middleware.CanAccessAllData(c, "session") || *session.AgentID != middleware.GetUserID(c) {
-		middleware.JSON(c, gin.H{"last_read_seq": session.LastReadSeq})
+	lastReadSeq, err := service.MarkSessionRead(session, sessionActor(c))
+	if err != nil {
+		respondServiceError(c, err)
 		return
 	}
-	var maxSeq int
-	if err := model.DB.Model(&model.Message{}).Where("session_id = ?", session.ID).Select("COALESCE(MAX(seq), 0)").Scan(&maxSeq).Error; err != nil {
-		c.JSON(http.StatusInternalServerError, gin.H{"code": 500, "message": "标记已读失败"})
-		return
-	}
-	if err := model.DB.Model(&model.Session{}).Where("id = ?", session.ID).Update("last_read_seq", maxSeq).Error; err != nil {
-		c.JSON(http.StatusInternalServerError, gin.H{"code": 500, "message": "标记已读失败"})
-		return
-	}
-	middleware.JSON(c, gin.H{"last_read_seq": maxSeq})
+	middleware.JSON(c, gin.H{"last_read_seq": lastReadSeq})
 }
 
 func (h *SessionHandler) AddNote(c *gin.Context) {
-	session, ok := loadTenantSession(c, c.Param("id"))
-	if !ok {
+	session, err := service.LoadTenantSession(c.Param("id"), middleware.GetTenantID(c))
+	if err != nil {
+		respondServiceError(c, err)
 		return
 	}
-	if !canOperateSession(c, session) {
+	if !service.CanOperateSession(sessionActor(c), session) {
 		c.JSON(http.StatusForbidden, gin.H{"code": 403, "message": "无权添加内部备注"})
 		return
 	}
@@ -497,58 +206,28 @@ func (h *SessionHandler) AddNote(c *gin.Context) {
 		c.JSON(http.StatusBadRequest, gin.H{"code": 400, "message": "参数错误"})
 		return
 	}
-	content := strings.TrimSpace(req.Content)
-	if content == "" || utf8.RuneCountInString(content) > 500 {
-		c.JSON(http.StatusBadRequest, gin.H{"code": 400, "message": "内部备注需为 1 至 500 字"})
-		return
-	}
-	event := model.SessionEvent{SessionID: session.ID, OperatorID: middleware.GetUserID(c), Action: "note", Detail: content}
-	if err := model.DB.Create(&event).Error; err != nil {
-		c.JSON(http.StatusInternalServerError, gin.H{"code": 500, "message": "保存内部备注失败"})
+	event, err := service.AddSessionNote(session, middleware.GetUserID(c), req.Content)
+	if err != nil {
+		respondServiceError(c, err)
 		return
 	}
 	middleware.JSON(c, event)
 }
 
 func (h *SessionHandler) ListAvailableAgents(c *gin.Context) {
-	type agentItem struct {
-		ID       uint   `json:"id"`
-		Nickname string `json:"nickname"`
-		Status   string `json:"status"` // online | busy | offline | disabled
-		Role     string `json:"role,omitempty"`
-	}
 	// all=1 返回租户全部坐席（含离线），用于对话记录筛选；
 	// 默认：可转接坐席（role=agent，在线/忙碌），便于前端展示状态
-	tenantID := middleware.GetTenantID(c)
-	q := model.DB.Where("tenant_id = ? AND role IN ?", tenantID, assignableRoleCodes(tenantID))
-	if c.Query("all") != "1" {
-		q = q.Where("status IN ?", []string{"online", "busy"})
-	}
-	var users []model.User
-	if err := q.Order("nickname asc").Find(&users).Error; err != nil {
-		c.JSON(http.StatusInternalServerError, gin.H{"code": 500, "message": "查询客服失败"})
+	items, err := service.ListAvailableAgents(middleware.GetTenantID(c), c.Query("all") == "1")
+	if err != nil {
+		respondServiceError(c, err)
 		return
 	}
-	// 在线优先，其次忙碌，再按昵称
-	statusRank := map[string]int{"online": 0, "busy": 1, "offline": 2, "disabled": 3}
-	sort.SliceStable(users, func(i, j int) bool {
-		ri, rj := statusRank[users[i].Status], statusRank[users[j].Status]
-		if ri != rj {
-			return ri < rj
-		}
-		return users[i].Nickname < users[j].Nickname
-	})
-	items := make([]agentItem, 0, len(users))
-	for _, user := range users {
-		items = append(items, agentItem{
-			ID: user.ID, Nickname: user.Nickname, Status: user.Status, Role: user.Role,
-		})
-	}
 	middleware.JSON(c, items)
 }
 
 func (h *SessionHandler) Create(c *gin.Context) {
-	if !isTenantManager(c) {
+	actor := sessionActor(c)
+	if !actor.SessionAll {
 		c.JSON(http.StatusForbidden, gin.H{"code": 403, "message": "仅主管或管理员可创建会话"})
 		return
 	}
@@ -557,45 +236,18 @@ func (h *SessionHandler) Create(c *gin.Context) {
 		c.JSON(http.StatusBadRequest, gin.H{"code": 400, "message": "参数错误"})
 		return
 	}
-
-	tenantID := middleware.GetTenantID(c)
-	var channel model.Channel
-	if err := model.DB.Where("id = ? AND tenant_id = ? AND status = ?", req.ChannelID, tenantID, "enabled").First(&channel).Error; err != nil {
-		c.JSON(http.StatusBadRequest, gin.H{"code": 400, "message": "渠道不存在或未启用"})
+	session, err := service.CreateSession(middleware.GetTenantID(c), req.ChannelID, req.CustomerID, req.Priority)
+	if err != nil {
+		respondServiceError(c, err)
 		return
 	}
-	var customer model.Customer
-	if err := model.DB.Where("id = ? AND tenant_id = ?", req.CustomerID, tenantID).First(&customer).Error; err != nil {
-		c.JSON(http.StatusBadRequest, gin.H{"code": 400, "message": "客户不存在"})
-		return
-	}
-
-	session := model.Session{
-		TenantID:   tenantID,
-		ChannelID:  req.ChannelID,
-		CustomerID: req.CustomerID,
-		Priority:   req.Priority,
-		Status:     "waiting",
-	}
-
-	if session.Priority == "" {
-		session.Priority = "normal"
-	}
-
-	if err := model.DB.Create(&session).Error; err != nil {
-		c.JSON(http.StatusInternalServerError, gin.H{"code": 500, "message": "创建会话失败"})
-		return
-	}
-	model.DB.Model(&model.Customer{}).Where("id = ? AND tenant_id = ?", customer.ID, tenantID).
-		Updates(map[string]interface{}{"conversation_count": gorm.Expr("conversation_count + 1"), "last_contact_at": time.Now()})
-
 	middleware.JSON(c, session)
 }
 
 func (h *SessionHandler) Assign(c *gin.Context) {
-	id := c.Param("id")
-	session, ok := loadTenantSession(c, id)
-	if !ok {
+	session, err := service.LoadTenantSession(c.Param("id"), middleware.GetTenantID(c))
+	if err != nil {
+		respondServiceError(c, err)
 		return
 	}
 	var req AssignSessionReq
@@ -603,81 +255,21 @@ func (h *SessionHandler) Assign(c *gin.Context) {
 		c.JSON(http.StatusBadRequest, gin.H{"code": 400, "message": "参数错误"})
 		return
 	}
-
-	if session.Status != "waiting" {
-		c.JSON(http.StatusConflict, gin.H{"code": 409, "message": "会话已被分配"})
+	detail, err := service.AssignSession(session, sessionActor(c), middleware.HasPermission(c, "session.transfer"), req.AgentID)
+	if err != nil {
+		respondServiceError(c, err)
 		return
 	}
-	if !middleware.HasPermission(c, "session.transfer") {
-		req.AgentID = middleware.GetUserID(c)
-	} else if !isTenantManager(c) && req.AgentID != middleware.GetUserID(c) {
-		c.JSON(http.StatusForbidden, gin.H{"code": 403, "message": "无权分配会话"})
-		return
-	}
-	if req.AgentID == 0 {
-		c.JSON(http.StatusBadRequest, gin.H{"code": 400, "message": "请选择目标客服"})
-		return
-	}
-	if err := loadAssignableAgent(session.TenantID, req.AgentID); err != nil {
-		c.JSON(http.StatusBadRequest, gin.H{"code": 400, "message": "目标客服不存在或不可用"})
-		return
-	}
-
-	result := model.DB.Model(&model.Session{}).
-		Where("id = ? AND tenant_id = ? AND status = ?", session.ID, session.TenantID, "waiting").
-		Updates(map[string]interface{}{"agent_id": req.AgentID, "status": "active", "last_read_seq": 0})
-
-	if result.Error != nil {
-		c.JSON(http.StatusInternalServerError, gin.H{"code": 500, "message": "分配失败"})
-		return
-	}
-	if result.RowsAffected == 0 {
-		c.JSON(http.StatusConflict, gin.H{"code": 409, "message": "会话已被分配"})
-		return
-	}
-
-	operatorID := middleware.GetUserID(c)
-	operatorName := userDisplayName(operatorID)
-	targetName := userDisplayName(req.AgentID)
-	detail := "会话分配给 " + targetName
-	if operatorID == req.AgentID {
-		detail = operatorName + " 领取了会话"
-	} else {
-		detail = operatorName + " 将会话分配给 " + targetName
-	}
-	model.DB.Create(&model.SessionEvent{
-		SessionID:  session.ID,
-		OperatorID: operatorID,
-		Action:     "assign",
-		Detail:     detail,
-	})
-	session.AgentID = &req.AgentID
-	session.Status = "active"
-	broadcastSessionUpdate(session)
 	middleware.JSON(c, gin.H{"message": "分配成功", "detail": detail})
 }
 
-func userDisplayName(userID uint) string {
-	var user model.User
-	if err := model.DB.Select("id", "nickname", "username").First(&user, userID).Error; err != nil {
-		return "未知坐席"
-	}
-	if strings.TrimSpace(user.Nickname) != "" {
-		return user.Nickname
-	}
-	if strings.TrimSpace(user.Username) != "" {
-		return user.Username
-	}
-	return "未知坐席"
-}
-
 func (h *SessionHandler) Transfer(c *gin.Context) {
-	id := c.Param("id")
-	session, ok := loadTenantSession(c, id)
-	if !ok {
+	session, err := service.LoadTenantSession(c.Param("id"), middleware.GetTenantID(c))
+	if err != nil {
+		respondServiceError(c, err)
 		return
 	}
-	if !canOperateSession(c, session) {
+	if !service.CanOperateSession(sessionActor(c), session) {
 		c.JSON(http.StatusForbidden, gin.H{"code": 403, "message": "无权转接该会话"})
 		return
 	}
@@ -686,123 +278,45 @@ func (h *SessionHandler) Transfer(c *gin.Context) {
 		c.JSON(http.StatusBadRequest, gin.H{"code": 400, "message": "参数错误"})
 		return
 	}
-
-	if err := loadAssignableAgent(session.TenantID, req.AgentID); err != nil {
-		c.JSON(http.StatusBadRequest, gin.H{"code": 400, "message": "目标客服不存在或不可用"})
+	detail, err := service.TransferSession(session, sessionActor(c), req.AgentID)
+	if err != nil {
+		respondServiceError(c, err)
 		return
 	}
-	if session.AgentID != nil && *session.AgentID == req.AgentID {
-		c.JSON(http.StatusBadRequest, gin.H{"code": 400, "message": "不能转接给当前接待坐席"})
-		return
-	}
-
-	operatorID := middleware.GetUserID(c)
-	operatorName := userDisplayName(operatorID)
-	targetName := userDisplayName(req.AgentID)
-	fromName := ""
-	if session.AgentID != nil {
-		fromName = userDisplayName(*session.AgentID)
-	}
-
-	result := model.DB.Model(&model.Session{}).
-		Where("id = ? AND tenant_id = ? AND status = ?", session.ID, session.TenantID, "active").
-		Updates(map[string]interface{}{"agent_id": req.AgentID, "last_read_seq": 0})
-	if result.Error != nil {
-		c.JSON(http.StatusInternalServerError, gin.H{"code": 500, "message": "转接失败"})
-		return
-	}
-	if result.RowsAffected == 0 {
-		c.JSON(http.StatusConflict, gin.H{"code": 409, "message": "会话不可转接"})
-		return
-	}
-
-	// 详情写明「谁 → 谁」，便于接手坐席在备注/时间线中一眼看清
-	detail := operatorName + " 转接给 " + targetName
-	if fromName != "" && fromName != operatorName {
-		detail = operatorName + " 将会话由 " + fromName + " 转接给 " + targetName
-	}
-
-	model.DB.Create(&model.SessionEvent{
-		SessionID:  session.ID,
-		OperatorID: operatorID,
-		Action:     "transfer",
-		Detail:     detail,
-	})
-	session.AgentID = &req.AgentID
-	broadcastSessionUpdate(session)
-
 	middleware.JSON(c, gin.H{"message": "转接成功", "detail": detail})
 }
 
 func (h *SessionHandler) End(c *gin.Context) {
-	id := c.Param("id")
-	reason := c.Query("reason")
-	session, ok := loadTenantSession(c, id)
-	if !ok {
+	session, err := service.LoadTenantSession(c.Param("id"), middleware.GetTenantID(c))
+	if err != nil {
+		respondServiceError(c, err)
 		return
 	}
-	if !canOperateSession(c, session) {
+	if !service.CanOperateSession(sessionActor(c), session) {
 		c.JSON(http.StatusForbidden, gin.H{"code": 403, "message": "无权结束该会话"})
 		return
 	}
-	if reason == "" {
-		c.JSON(http.StatusBadRequest, gin.H{"code": 400, "message": "请填写结束原因"})
+	if err := service.EndSession(session, middleware.GetUserID(c), c.Query("reason")); err != nil {
+		respondServiceError(c, err)
 		return
 	}
-	if reason != "resolved" && reason != "no_response" && reason != "visitor_left" && reason != "transferred" && reason != "other" {
-		c.JSON(http.StatusBadRequest, gin.H{"code": 400, "message": "结束原因无效"})
-		return
-	}
-	now := time.Now()
-
-	result := model.DB.Model(&model.Session{}).
-		Where("id = ? AND tenant_id = ? AND status <> ?", session.ID, session.TenantID, "ended").
-		Updates(map[string]interface{}{"status": "ended", "end_reason": reason, "ended_at": now})
-
-	if result.RowsAffected == 0 {
-		c.JSON(http.StatusNotFound, gin.H{"code": 404, "message": "会话不存在"})
-		return
-	}
-
-	model.DB.Create(&model.SessionEvent{
-		SessionID:  session.ID,
-		OperatorID: middleware.GetUserID(c),
-		Action:     "end",
-		Detail:     "结束会话: " + reason,
-	})
-	session.Status = "ended"
-	session.EndedAt = &now
-	broadcastSessionUpdate(session)
-
 	middleware.JSON(c, gin.H{"message": "已结束"})
 }
 
 func (h *SessionHandler) UpdatePriority(c *gin.Context) {
-	id := c.Param("id")
-	priority := c.Query("priority")
-	session, ok := loadTenantSession(c, id)
-	if !ok {
+	session, err := service.LoadTenantSession(c.Param("id"), middleware.GetTenantID(c))
+	if err != nil {
+		respondServiceError(c, err)
 		return
 	}
-	if !canOperateSession(c, session) {
+	if !service.CanOperateSession(sessionActor(c), session) {
 		c.JSON(http.StatusForbidden, gin.H{"code": 403, "message": "无权更新该会话"})
 		return
 	}
-	if priority != "urgent" && priority != "normal" {
-		c.JSON(http.StatusBadRequest, gin.H{"code": 400, "message": "优先级无效"})
+	if err := service.UpdateSessionPriority(session, sessionActor(c), c.Query("priority")); err != nil {
+		respondServiceError(c, err)
 		return
 	}
-
-	result := model.DB.Model(&model.Session{}).
-		Where("id = ? AND tenant_id = ?", session.ID, session.TenantID).
-		Update("priority", priority)
-	if result.Error != nil || result.RowsAffected == 0 {
-		c.JSON(http.StatusInternalServerError, gin.H{"code": 500, "message": "更新失败"})
-		return
-	}
-	session.Priority = priority
-	broadcastSessionUpdate(session)
-
 	middleware.JSON(c, gin.H{"message": "已更新"})
 }
 
@@ -812,30 +326,17 @@ func (h *SessionHandler) Archive(c *gin.Context) {
 		c.JSON(http.StatusForbidden, gin.H{"code": 403, "message": "仅主管或管理员可归档"})
 		return
 	}
-	session, ok := loadTenantSession(c, c.Param("id"))
-	if !ok {
+	session, err := service.LoadTenantSession(c.Param("id"), middleware.GetTenantID(c))
+	if err != nil {
+		respondServiceError(c, err)
 		return
 	}
-	if session.Status != "ended" {
-		c.JSON(http.StatusBadRequest, gin.H{"code": 400, "message": "仅已结束的会话可归档"})
+	archived, err := service.ArchiveSession(session, middleware.GetUserID(c))
+	if err != nil {
+		respondServiceError(c, err)
 		return
 	}
-	result := model.DB.Model(&model.Session{}).
-		Where("id = ? AND tenant_id = ? AND status = ?", session.ID, session.TenantID, "ended").
-		Update("status", "archived")
-	if result.Error != nil || result.RowsAffected == 0 {
-		c.JSON(http.StatusInternalServerError, gin.H{"code": 500, "message": "归档失败"})
-		return
-	}
-	model.DB.Create(&model.SessionEvent{
-		SessionID:  session.ID,
-		OperatorID: middleware.GetUserID(c),
-		Action:     "archive",
-		Detail:     "会话已归档",
-	})
-	session.Status = "archived"
-	broadcastSessionUpdate(session)
-	middleware.JSON(c, gin.H{"message": "已归档", "session": session})
+	middleware.JSON(c, gin.H{"message": "已归档", "session": archived})
 }
 
 // BatchArchive 批量归档已结束会话
@@ -847,29 +348,14 @@ func (h *SessionHandler) BatchArchive(c *gin.Context) {
 	var req struct {
 		IDs []uint `json:"ids" binding:"required"`
 	}
-	if err := c.ShouldBindJSON(&req); err != nil || len(req.IDs) == 0 {
+	if err := c.ShouldBindJSON(&req); err != nil {
 		c.JSON(http.StatusBadRequest, gin.H{"code": 400, "message": "请选择要归档的会话"})
 		return
 	}
-	if len(req.IDs) > 100 {
-		c.JSON(http.StatusBadRequest, gin.H{"code": 400, "message": "单次最多归档 100 条"})
+	count, err := service.BatchArchiveSessions(middleware.GetTenantID(c), middleware.GetUserID(c), req.IDs)
+	if err != nil {
+		respondServiceError(c, err)
 		return
 	}
-	tenantID := middleware.GetTenantID(c)
-	result := model.DB.Model(&model.Session{}).
-		Where("tenant_id = ? AND status = ? AND id IN ?", tenantID, "ended", req.IDs).
-		Update("status", "archived")
-	if result.Error != nil {
-		c.JSON(http.StatusInternalServerError, gin.H{"code": 500, "message": "批量归档失败"})
-		return
-	}
-	for _, id := range req.IDs {
-		model.DB.Create(&model.SessionEvent{
-			SessionID:  id,
-			OperatorID: middleware.GetUserID(c),
-			Action:     "archive",
-			Detail:     "会话已归档",
-		})
-	}
-	middleware.JSON(c, gin.H{"message": "已归档", "count": result.RowsAffected})
+	middleware.JSON(c, gin.H{"message": "已归档", "count": count})
 }