fix(dialog): prevent auto focus restore on close to avoid page scroll (#315)

When a modal is closed, Radix Dialog by default restores focus to the
trigger element. This causes the page to scroll to that element if it's
not in the viewport, leading to unexpected scrolling behavior after
editing forwards or other items.

Entire-Checkpoint: 78b48b74a841

go-backend/internal/http/handler/mutations.go

@@ -802,13 +802,25 @@ func (h *Handler) tunnelUpdate(w http.ResponseWriter, r *http.Request) {
 		response.WriteJSON(w, response.Err(-2, err.Error()))
 		return
 	}
+
+	newEntryNodeIDs := make([]int64, 0, len(runtimeState.InNodes))
+	for _, in := range runtimeState.InNodes {
+		if in.NodeID > 0 {
+			newEntryNodeIDs = append(newEntryNodeIDs, in.NodeID)
+		}
+	}
+	if err := h.validateTunnelEntryPortConflictsForNewEntries(id, oldEntryNodeIDs, newEntryNodeIDs); err != nil {
+		response.WriteJSON(w, response.ErrDefault(err.Error()))
+		return
+	}
+
 	if err := tx.Commit().Error; err != nil {
 		h.releaseFederationRuntimeRefs(federationReleaseRefs)
 		response.WriteJSON(w, response.Err(-2, err.Error()))
 		return
 	}
 
-	newEntryNodeIDs, _ := h.tunnelEntryNodeIDs(id)
+	newEntryNodeIDs, _ = h.tunnelEntryNodeIDs(id)
 	if !sameInt64Set(oldEntryNodeIDs, newEntryNodeIDs) {
 		h.cleanupTunnelForwardRuntimesOnRemovedEntryNodes(id, oldEntryNodeIDs, newEntryNodeIDs)
 		h.syncTunnelForwardsEntryPorts(id, newEntryNodeIDs)
@@ -985,6 +997,52 @@ func (h *Handler) cleanupTunnelForwardRuntimesOnRemovedEntryNodes(tunnelID int64
 	}
 }
 
+func (h *Handler) validateTunnelEntryPortConflictsForNewEntries(tunnelID int64, oldEntryNodeIDs, newEntryNodeIDs []int64) error {
+	if h == nil || h.repo == nil || tunnelID <= 0 {
+		return nil
+	}
+
+	addedNodeIDs := diffInt64s(newEntryNodeIDs, oldEntryNodeIDs)
+	if len(addedNodeIDs) == 0 {
+		return nil
+	}
+
+	forwards, err := h.listForwardsByTunnel(tunnelID)
+	if err != nil || len(forwards) == 0 {
+		return nil
+	}
+
+	for i := range forwards {
+		f := &forwards[i]
+		if f == nil {
+			continue
+		}
+		oldPorts, portsErr := h.listForwardPorts(f.ID)
+		if portsErr != nil {
+			continue
+		}
+		port := pickForwardPortFromRecords(oldPorts)
+		if port <= 0 {
+			continue
+		}
+
+		for _, nodeID := range addedNodeIDs {
+			node, nodeErr := h.getNodeRecord(nodeID)
+			if nodeErr != nil {
+				continue
+			}
+			if err := validateLocalNodePort(node, port); err != nil {
+				return fmt.Errorf("转发 %s 入口端口冲突: %w", f.Name, err)
+			}
+			if err := h.validateForwardPortAvailability(node, port, f.ID); err != nil {
+				return fmt.Errorf("转发 %s 入口端口冲突: %w", f.Name, err)
+			}
+		}
+	}
+
+	return nil
+}
+
 func (h *Handler) syncTunnelForwardsEntryPorts(tunnelID int64, entryNodeIDs []int64) {
 	if h == nil || h.repo == nil || tunnelID <= 0 {
 		return
@@ -1096,16 +1154,24 @@ func (h *Handler) tunnelBatchDelete(w http.ResponseWriter, r *http.Request) {
 	}
 	success := 0
 	fail := 0
+	failures := make([]batchFailureDetail, 0)
 	for _, id := range ids {
+		tunnelName, _ := h.repo.GetTunnelName(id)
+		if _, err := h.getTunnelRecord(id); err != nil {
+			fail++
+			failures = appendBatchFailure(failures, id, tunnelName, err)
+			continue
+		}
 		h.cleanupTunnelRuntime(id)
 		h.cleanupFederationRuntime(id)
 		if err := h.deleteTunnelByID(id); err != nil {
 			fail++
+			failures = appendBatchFailure(failures, id, tunnelName, err)
 		} else {
 			success++
 		}
 	}
-	response.WriteJSON(w, response.OK(map[string]interface{}{"successCount": success, "failCount": fail}))
+	response.WriteJSON(w, response.OK(batchOperationResult{SuccessCount: success, FailCount: fail, Failures: failures}))
 }
 
 func (h *Handler) reconstructTunnelState(tunnelID int64) (*tunnelCreateState, error) {
@@ -1241,6 +1307,60 @@ func (h *Handler) redeployTunnelAndForwards(tunnelID int64) error {
 	return nil
 }
 
+type batchFailureDetail struct {
+	ID     int64  `json:"id"`
+	Name   string `json:"name,omitempty"`
+	Reason string `json:"reason"`
+}
+
+type batchOperationResult struct {
+	SuccessCount int                  `json:"successCount"`
+	FailCount    int                  `json:"failCount"`
+	Failures     []batchFailureDetail `json:"failures,omitempty"`
+}
+
+func appendBatchFailure(failures []batchFailureDetail, id int64, name string, err error) []batchFailureDetail {
+	reason := normalizeBatchFailureReason(errString(err))
+	if reason == "" {
+		reason = "未知错误"
+	}
+	return append(failures, batchFailureDetail{
+		ID:     id,
+		Name:   strings.TrimSpace(name),
+		Reason: reason,
+	})
+}
+
+func appendBatchFailureReason(failures []batchFailureDetail, id int64, name, reason string) []batchFailureDetail {
+	normalized := normalizeBatchFailureReason(reason)
+	if normalized == "" {
+		normalized = "未知错误"
+	}
+	return append(failures, batchFailureDetail{
+		ID:     id,
+		Name:   strings.TrimSpace(name),
+		Reason: normalized,
+	})
+}
+
+func errString(err error) string {
+	if err == nil {
+		return ""
+	}
+	return err.Error()
+}
+
+func normalizeBatchFailureReason(reason string) string {
+	trimmed := strings.TrimSpace(reason)
+	if trimmed == "" {
+		return ""
+	}
+	if strings.EqualFold(trimmed, errForwardNotFound.Error()) {
+		return "转发不存在"
+	}
+	return trimmed
+}
+
 func (h *Handler) tunnelBatchRedeploy(w http.ResponseWriter, r *http.Request) {
 	ids := idsFromBody(r, w)
 	if ids == nil {
@@ -1248,14 +1368,26 @@ func (h *Handler) tunnelBatchRedeploy(w http.ResponseWriter, r *http.Request) {
 	}
 	success := 0
 	fail := 0
+	failures := make([]batchFailureDetail, 0)
 	for _, tunnelID := range ids {
+		tunnel, tunnelErr := h.getTunnelRecord(tunnelID)
+		tunnelName := ""
+		if tunnelErr == nil && tunnel != nil {
+			tunnelName, _ = h.repo.GetTunnelName(tunnelID)
+		}
+		if tunnelErr != nil {
+			fail++
+			failures = appendBatchFailure(failures, tunnelID, tunnelName, tunnelErr)
+			continue
+		}
 		if err := h.redeployTunnelAndForwards(tunnelID); err != nil {
 			fail++
+			failures = appendBatchFailure(failures, tunnelID, tunnelName, err)
 			continue
 		}
 		success++
 	}
-	response.WriteJSON(w, response.OK(map[string]interface{}{"successCount": success, "failCount": fail}))
+	response.WriteJSON(w, response.OK(batchOperationResult{SuccessCount: success, FailCount: fail, Failures: failures}))
 }
 
 func (h *Handler) userTunnelAssign(w http.ResponseWriter, r *http.Request) {
@@ -1806,23 +1938,27 @@ func (h *Handler) forwardBatchDelete(w http.ResponseWriter, r *http.Request) {
 	}
 	s := 0
 	f := 0
+	failures := make([]batchFailureDetail, 0)
 	for _, id := range ids {
 		forward, accessErr := h.ensureForwardAccessByActor(actorUserID, actorRole, id)
 		if accessErr != nil {
 			f++
+			failures = appendBatchFailure(failures, id, "", accessErr)
 			continue
 		}
 		if err := h.controlForwardServices(forward, "DeleteService", true); err != nil {
 			f++
+			failures = appendBatchFailure(failures, id, forward.Name, err)
 			continue
 		}
 		if err := h.deleteForwardByID(id); err != nil {
 			f++
+			failures = appendBatchFailure(failures, id, forward.Name, err)
 		} else {
 			s++
 		}
 	}
-	response.WriteJSON(w, response.OK(map[string]interface{}{"successCount": s, "failCount": f}))
+	response.WriteJSON(w, response.OK(batchOperationResult{SuccessCount: s, FailCount: f, Failures: failures}))
 }
 
 func (h *Handler) forwardBatchPause(w http.ResponseWriter, r *http.Request) {
@@ -1837,23 +1973,27 @@ func (h *Handler) forwardBatchPause(w http.ResponseWriter, r *http.Request) {
 	}
 	s := 0
 	f := 0
+	failures := make([]batchFailureDetail, 0)
 	for _, id := range ids {
 		forward, accessErr := h.ensureForwardAccessByActor(actorUserID, actorRole, id)
 		if accessErr != nil {
 			f++
+			failures = appendBatchFailure(failures, id, "", accessErr)
 			continue
 		}
 		if err := h.controlForwardServices(forward, "PauseService", false); err != nil {
 			f++
+			failures = appendBatchFailure(failures, id, forward.Name, err)
 			continue
 		}
 		if err := h.repo.UpdateForwardStatus(id, 0, time.Now().UnixMilli()); err != nil {
 			f++
+			failures = appendBatchFailure(failures, id, forward.Name, err)
 		} else {
 			s++
 		}
 	}
-	response.WriteJSON(w, response.OK(map[string]interface{}{"successCount": s, "failCount": f}))
+	response.WriteJSON(w, response.OK(batchOperationResult{SuccessCount: s, FailCount: f, Failures: failures}))
 }
 
 func (h *Handler) forwardBatchResume(w http.ResponseWriter, r *http.Request) {
@@ -1869,27 +2009,32 @@ func (h *Handler) forwardBatchResume(w http.ResponseWriter, r *http.Request) {
 	s := 0
 	f := 0
 	now := time.Now().UnixMilli()
+	failures := make([]batchFailureDetail, 0)
 	for _, id := range ids {
 		forward, accessErr := h.ensureForwardAccessByActor(actorUserID, actorRole, id)
 		if accessErr != nil {
 			f++
+			failures = appendBatchFailure(failures, id, "", accessErr)
 			continue
 		}
 		if err := h.ensureUserTunnelForwardAllowed(forward.UserID, forward.TunnelID, now); err != nil {
 			f++
+			failures = appendBatchFailure(failures, id, forward.Name, err)
 			continue
 		}
 		if err := h.controlForwardServices(forward, "ResumeService", false); err != nil {
 			f++
+			failures = appendBatchFailure(failures, id, forward.Name, err)
 			continue
 		}
 		if err := h.repo.UpdateForwardStatus(id, 1, now); err != nil {
 			f++
+			failures = appendBatchFailure(failures, id, forward.Name, err)
 		} else {
 			s++
 		}
 	}
-	response.WriteJSON(w, response.OK(map[string]interface{}{"successCount": s, "failCount": f}))
+	response.WriteJSON(w, response.OK(batchOperationResult{SuccessCount: s, FailCount: f, Failures: failures}))
 }
 
 func (h *Handler) forwardBatchRedeploy(w http.ResponseWriter, r *http.Request) {
@@ -1904,19 +2049,22 @@ func (h *Handler) forwardBatchRedeploy(w http.ResponseWriter, r *http.Request) {
 	}
 	s := 0
 	f := 0
+	failures := make([]batchFailureDetail, 0)
 	for _, id := range ids {
 		forward, accessErr := h.ensureForwardAccessByActor(actorUserID, actorRole, id)
 		if accessErr != nil {
 			f++
+			failures = appendBatchFailure(failures, id, "", accessErr)
 			continue
 		}
 		if err := h.syncForwardServices(forward, "UpdateService", true); err != nil {
 			f++
+			failures = appendBatchFailure(failures, id, forward.Name, err)
 		} else {
 			s++
 		}
 	}
-	response.WriteJSON(w, response.OK(map[string]interface{}{"successCount": s, "failCount": f}))
+	response.WriteJSON(w, response.OK(batchOperationResult{SuccessCount: s, FailCount: f, Failures: failures}))
 }
 
 func (h *Handler) forwardBatchChangeTunnel(w http.ResponseWriter, r *http.Request) {
@@ -1948,6 +2096,7 @@ func (h *Handler) forwardBatchChangeTunnel(w http.ResponseWriter, r *http.Reques
 	}
 	success := 0
 	fail := 0
+	failures := make([]batchFailureDetail, 0)
 	for _, id := range req.ForwardIDs {
 		if id <= 0 {
 			continue
@@ -1955,21 +2104,30 @@ func (h *Handler) forwardBatchChangeTunnel(w http.ResponseWriter, r *http.Reques
 		forward, accessErr := h.ensureForwardAccessByActor(actorUserID, actorRole, id)
 		if accessErr != nil {
 			fail++
+			failures = appendBatchFailure(failures, id, "", accessErr)
 			continue
 		}
 		if forward.TunnelID == req.TargetTunnelID {
 			fail++
+			failures = appendBatchFailureReason(failures, id, forward.Name, "规则已在目标隧道中")
 			continue
 		}
 		oldPorts, listPortsErr := h.listForwardPorts(id)
 		if listPortsErr != nil {
 			fail++
+			failures = appendBatchFailure(failures, id, forward.Name, listPortsErr)
+			continue
+		}
+		if len(oldPorts) == 0 {
+			fail++
+			failures = appendBatchFailureReason(failures, id, forward.Name, "转发入口端口不存在")
 			continue
 		}
 		oldNodeIDs := forwardPortNodeIDs(oldPorts)
 		port := h.repo.GetMinForwardPort(id)
 		if err := h.repo.UpdateForwardTunnel(id, req.TargetTunnelID, time.Now().UnixMilli()); err != nil {
 			fail++
+			failures = appendBatchFailure(failures, id, forward.Name, err)
 			continue
 		}
 		p := 0
@@ -1984,29 +2142,36 @@ func (h *Handler) forwardBatchChangeTunnel(w http.ResponseWriter, r *http.Reques
 		removedNodeIDs := diffInt64s(oldNodeIDs, newNodeIDs)
 		keptNodeIDs := diffInt64s(oldNodeIDs, removedNodeIDs)
 		portRangeOk := true
+		var portRangeErr error
 		for _, nid := range bctEntryNodes {
 			nd, ndErr := h.getNodeRecord(nid)
 			if ndErr != nil {
+				portRangeErr = ndErr
 				continue
 			}
-			if validateRemoteNodePort(nd, p) != nil {
+			if validateErr := validateRemoteNodePort(nd, p); validateErr != nil {
 				portRangeOk = false
+				portRangeErr = validateErr
 				break
 			}
 		}
 		if !portRangeOk {
 			fail++
+			failures = appendBatchFailure(failures, id, forward.Name, portRangeErr)
+			h.rollbackForwardMutation(forward, oldPorts)
 			continue
 		}
 		if err := h.replaceForwardPorts(id, req.TargetTunnelID, p, ""); err != nil {
 			h.rollbackForwardMutation(forward, oldPorts)
 			fail++
+			failures = appendBatchFailure(failures, id, forward.Name, err)
 			continue
 		}
 		updatedForward, fetchErr := h.getForwardRecord(id)
 		if fetchErr != nil {
 			h.rollbackForwardMutation(forward, oldPorts)
 			fail++
+			failures = appendBatchFailure(failures, id, forward.Name, fetchErr)
 			continue
 		}
 		if len(keptNodeIDs) > 0 {
@@ -2018,6 +2183,7 @@ func (h *Handler) forwardBatchChangeTunnel(w http.ResponseWriter, r *http.Reques
 		if err := h.syncForwardServices(updatedForward, "UpdateService", true); err != nil {
 			h.rollbackForwardMutation(forward, oldPorts)
 			fail++
+			failures = appendBatchFailure(failures, id, forward.Name, err)
 			continue
 		}
 		if len(removedNodeIDs) > 0 {
@@ -2027,7 +2193,7 @@ func (h *Handler) forwardBatchChangeTunnel(w http.ResponseWriter, r *http.Reques
 		}
 		success++
 	}
-	response.WriteJSON(w, response.OK(map[string]interface{}{"successCount": success, "failCount": fail}))
+	response.WriteJSON(w, response.OK(batchOperationResult{SuccessCount: success, FailCount: fail, Failures: failures}))
 }
 
 func (h *Handler) speedLimitCreate(w http.ResponseWriter, r *http.Request) {

go-backend/tests/contract/batch_action_failure_details_contract_test.go

@@ -0,0 +1,202 @@
+package contract_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"go-backend/internal/auth"
+	"go-backend/internal/http/response"
+	"go-backend/internal/store/repo"
+)
+
+func TestForwardBatchDeleteReturnsFailureReasonsContract(t *testing.T) {
+	secret := "contract-jwt-secret"
+	router, _ := setupContractRouter(t, secret)
+	adminToken := mustAdminToken(t, secret)
+
+	out := postBatchRequest(t, router, adminToken, "/api/v1/forward/batch-delete", `{"ids":[999]}`)
+	result := mustBatchResult(t, out)
+	assertBatchFailureReasonContains(t, result, "转发不存在")
+}
+
+func TestForwardBatchPauseReturnsFailureReasonsContract(t *testing.T) {
+	secret := "contract-jwt-secret"
+	router, _ := setupContractRouter(t, secret)
+	adminToken := mustAdminToken(t, secret)
+
+	out := postBatchRequest(t, router, adminToken, "/api/v1/forward/batch-pause", `{"ids":[999]}`)
+	result := mustBatchResult(t, out)
+	assertBatchFailureReasonContains(t, result, "转发不存在")
+}
+
+func TestForwardBatchResumeReturnsFailureReasonsContract(t *testing.T) {
+	secret := "contract-jwt-secret"
+	router, repo := setupContractRouter(t, secret)
+	adminToken := mustAdminToken(t, secret)
+	now := time.Now().UnixMilli()
+
+	forwardID := seedForwardForBatchAction(t, repo, batchForwardSeedOptions{
+		Now:              now,
+		TunnelName:       "resume-detail-tunnel",
+		ForwardName:      "resume-detail-forward",
+		CreateUserTunnel: true,
+		UserTunnelStatus: 0,
+	})
+
+	out := postBatchRequest(t, router, adminToken, "/api/v1/forward/batch-resume", `{"ids":[`+jsonNumber(forwardID)+`]}`)
+	result := mustBatchResult(t, out)
+	assertBatchFailureNameAndReason(t, result, "resume-detail-forward", "该隧道已禁用")
+}
+
+func TestForwardBatchChangeTunnelReturnsFailureReasonsContract(t *testing.T) {
+	secret := "contract-jwt-secret"
+	router, repo := setupContractRouter(t, secret)
+	adminToken := mustAdminToken(t, secret)
+	now := time.Now().UnixMilli()
+
+	forwardID := seedForwardForBatchAction(t, repo, batchForwardSeedOptions{
+		Now:         now,
+		TunnelName:  "change-detail-tunnel",
+		ForwardName: "change-detail-forward",
+	})
+	tunnelID := mustQueryInt64(t, repo, `SELECT tunnel_id FROM forward WHERE id = ?`, forwardID)
+
+	payload := `{"forwardIds":[` + jsonNumber(forwardID) + `],"targetTunnelId":` + jsonNumber(tunnelID) + `}`
+	out := postBatchRequest(t, router, adminToken, "/api/v1/forward/batch-change-tunnel", payload)
+	result := mustBatchResult(t, out)
+	assertBatchFailureNameAndReason(t, result, "change-detail-forward", "规则已在目标隧道中")
+}
+
+func TestTunnelBatchDeleteReturnsFailureReasonsContract(t *testing.T) {
+	secret := "contract-jwt-secret"
+	router, _ := setupContractRouter(t, secret)
+	adminToken := mustAdminToken(t, secret)
+
+	out := postBatchRequest(t, router, adminToken, "/api/v1/tunnel/batch-delete", `{"ids":[999]}`)
+	result := mustBatchResult(t, out)
+	assertBatchFailureReasonContains(t, result, "隧道不存在")
+}
+
+type batchForwardSeedOptions struct {
+	Now              int64
+	TunnelName       string
+	ForwardName      string
+	CreateUserTunnel bool
+	UserTunnelStatus int
+}
+
+func mustAdminToken(t *testing.T, secret string) string {
+	t.Helper()
+	token, err := auth.GenerateToken(1, "admin_user", 0, secret)
+	if err != nil {
+		t.Fatalf("generate admin token: %v", err)
+	}
+	return token
+}
+
+func postBatchRequest(t *testing.T, router http.Handler, token, path, payload string) response.R {
+	t.Helper()
+	req := httptest.NewRequest(http.MethodPost, path, bytes.NewBufferString(payload))
+	req.Header.Set("Authorization", token)
+	req.Header.Set("Content-Type", "application/json")
+	res := httptest.NewRecorder()
+	router.ServeHTTP(res, req)
+
+	var out response.R
+	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if out.Code != 0 {
+		t.Fatalf("expected API success envelope, got code=%d msg=%q", out.Code, out.Msg)
+	}
+	return out
+}
+
+func mustBatchResult(t *testing.T, out response.R) map[string]interface{} {
+	t.Helper()
+	result, ok := out.Data.(map[string]interface{})
+	if !ok {
+		t.Fatalf("expected map result, got %T", out.Data)
+	}
+	if int(result["failCount"].(float64)) != 1 {
+		t.Fatalf("expected failCount=1, got %v", result["failCount"])
+	}
+	return result
+}
+
+func assertBatchFailureReasonContains(t *testing.T, result map[string]interface{}, snippet string) {
+	t.Helper()
+	failures, ok := result["failures"].([]interface{})
+	if !ok || len(failures) != 1 {
+		t.Fatalf("expected exactly one failure detail, got %#v", result["failures"])
+	}
+	first, ok := failures[0].(map[string]interface{})
+	if !ok {
+		t.Fatalf("expected failure detail object, got %T", failures[0])
+	}
+	reason, _ := first["reason"].(string)
+	if !strings.Contains(reason, snippet) {
+		t.Fatalf("expected failure reason to contain %q, got %q", snippet, reason)
+	}
+}
+
+func assertBatchFailureNameAndReason(t *testing.T, result map[string]interface{}, expectedName, reasonSnippet string) {
+	t.Helper()
+	failures, ok := result["failures"].([]interface{})
+	if !ok || len(failures) != 1 {
+		t.Fatalf("expected exactly one failure detail, got %#v", result["failures"])
+	}
+	first, ok := failures[0].(map[string]interface{})
+	if !ok {
+		t.Fatalf("expected failure detail object, got %T", failures[0])
+	}
+	gotName, _ := first["name"].(string)
+	if strings.TrimSpace(gotName) != expectedName {
+		t.Fatalf("expected failure name %q, got %q", expectedName, gotName)
+	}
+	reason, _ := first["reason"].(string)
+	if !strings.Contains(reason, reasonSnippet) {
+		t.Fatalf("expected failure reason to contain %q, got %q", reasonSnippet, reason)
+	}
+}
+
+func seedForwardForBatchAction(t *testing.T, repo *repo.Repository, opts batchForwardSeedOptions) int64 {
+	t.Helper()
+	if err := repo.DB().Exec(`
+		INSERT INTO user(id, user, pwd, role_id, exp_time, flow, in_flow, out_flow, flow_reset_time, num, created_time, updated_time, status)
+		VALUES(2, 'batch_action_user', '3c85cdebade1c51cf64ca9f3c09d182d', 1, 2727251700000, 99999, 0, 0, 1, 99999, ?, ?, 1)
+	`, opts.Now, opts.Now).Error; err != nil {
+		t.Fatalf("insert user: %v", err)
+	}
+
+	if err := repo.DB().Exec(`
+		INSERT INTO tunnel(name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, opts.TunnelName, 1.0, 1, "tls", 99999, opts.Now, opts.Now, 1, nil, 0).Error; err != nil {
+		t.Fatalf("insert tunnel: %v", err)
+	}
+	tunnelID := mustLastInsertID(t, repo, opts.TunnelName)
+
+	if opts.CreateUserTunnel {
+		if err := repo.DB().Exec(`
+			INSERT INTO user_tunnel(id, user_id, tunnel_id, speed_id, num, flow, in_flow, out_flow, flow_reset_time, exp_time, status)
+			VALUES(20, 2, ?, NULL, 999, 99999, 0, 0, 1, 2727251700000, ?)
+		`, tunnelID, opts.UserTunnelStatus).Error; err != nil {
+			t.Fatalf("insert user_tunnel: %v", err)
+		}
+	}
+
+	if err := repo.DB().Exec(`
+		INSERT INTO forward(user_id, user_name, name, tunnel_id, remote_addr, strategy, in_flow, out_flow, created_time, updated_time, status, inx)
+		VALUES(2, 'batch_action_user', ?, ?, '1.1.1.1:443', 'fifo', 0, 0, ?, ?, 1, 0)
+	`, opts.ForwardName, tunnelID, opts.Now, opts.Now).Error; err != nil {
+		t.Fatalf("insert forward: %v", err)
+	}
+
+	return mustLastInsertID(t, repo, opts.ForwardName)
+}

go-backend/tests/contract/batch_redeploy_error_details_contract_test.go

@@ -0,0 +1,161 @@
+package contract_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"go-backend/internal/auth"
+	"go-backend/internal/http/response"
+)
+
+func TestForwardBatchRedeployReturnsFailureReasonsContract(t *testing.T) {
+	secret := "contract-jwt-secret"
+	router, repo := setupContractRouter(t, secret)
+	now := time.Now().UnixMilli()
+
+	adminToken, err := auth.GenerateToken(1, "admin_user", 0, secret)
+	if err != nil {
+		t.Fatalf("generate admin token: %v", err)
+	}
+
+	if err := repo.DB().Exec(`
+		INSERT INTO user(id, user, pwd, role_id, exp_time, flow, in_flow, out_flow, flow_reset_time, num, created_time, updated_time, status)
+		VALUES(2, 'batch_redeploy_user', '3c85cdebade1c51cf64ca9f3c09d182d', 1, 2727251700000, 99999, 0, 0, 1, 99999, ?, ?, 1)
+	`, now, now).Error; err != nil {
+		t.Fatalf("insert user: %v", err)
+	}
+
+	if err := repo.DB().Exec(`
+		INSERT INTO tunnel(name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "batch-redeploy-tunnel", 1.0, 1, "tls", 99999, now, now, 1, nil, 0).Error; err != nil {
+		t.Fatalf("insert tunnel: %v", err)
+	}
+	tunnelID := mustLastInsertID(t, repo, "batch-redeploy-tunnel")
+
+	if err := repo.DB().Exec(`
+		INSERT INTO forward(user_id, user_name, name, tunnel_id, remote_addr, strategy, in_flow, out_flow, created_time, updated_time, status, inx)
+		VALUES(?, ?, ?, ?, ?, ?, 0, 0, ?, ?, 1, 0)
+	`, 2, "batch_redeploy_user", "redeploy-forward", tunnelID, "1.1.1.1:443", "fifo", now, now).Error; err != nil {
+		t.Fatalf("insert forward: %v", err)
+	}
+	forwardID := mustLastInsertID(t, repo, "redeploy-forward")
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/forward/batch-redeploy", bytes.NewBufferString(`{"ids":[`+jsonNumber(forwardID)+`]}`))
+	req.Header.Set("Authorization", adminToken)
+	req.Header.Set("Content-Type", "application/json")
+	res := httptest.NewRecorder()
+	router.ServeHTTP(res, req)
+
+	var out response.R
+	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if out.Code != 0 {
+		t.Fatalf("expected API success envelope, got code=%d msg=%q", out.Code, out.Msg)
+	}
+
+	result, ok := out.Data.(map[string]interface{})
+	if !ok {
+		t.Fatalf("expected map result, got %T", out.Data)
+	}
+	if int(result["failCount"].(float64)) != 1 {
+		t.Fatalf("expected failCount=1, got %v", result["failCount"])
+	}
+	if int(result["successCount"].(float64)) != 0 {
+		t.Fatalf("expected successCount=0, got %v", result["successCount"])
+	}
+
+	failures, ok := result["failures"].([]interface{})
+	if !ok || len(failures) != 1 {
+		t.Fatalf("expected exactly one failure detail, got %#v", result["failures"])
+	}
+	first, ok := failures[0].(map[string]interface{})
+	if !ok {
+		t.Fatalf("expected failure detail object, got %T", failures[0])
+	}
+	if gotName := strings.TrimSpace(first["name"].(string)); gotName != "redeploy-forward" {
+		t.Fatalf("expected failure name redeploy-forward, got %q", gotName)
+	}
+	reason, _ := first["reason"].(string)
+	if !strings.Contains(reason, "转发入口端口不存在") {
+		t.Fatalf("expected forward failure reason to mention missing entry port, got %q", reason)
+	}
+}
+
+func TestTunnelBatchRedeployReturnsFailureReasonsContract(t *testing.T) {
+	secret := "contract-jwt-secret"
+	router, repo := setupContractRouter(t, secret)
+	now := time.Now().UnixMilli()
+
+	adminToken, err := auth.GenerateToken(1, "admin_user", 0, secret)
+	if err != nil {
+		t.Fatalf("generate admin token: %v", err)
+	}
+
+	if err := repo.DB().Exec(`
+		INSERT INTO tunnel(name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "broken-redeploy-tunnel", 1.0, 2, "tls", 99999, now, now, 1, nil, 0).Error; err != nil {
+		t.Fatalf("insert tunnel: %v", err)
+	}
+	tunnelID := mustLastInsertID(t, repo, "broken-redeploy-tunnel")
+
+	if err := repo.DB().Exec(`
+		INSERT INTO node(name, secret, server_ip, server_ip_v4, server_ip_v6, port, interface_name, version, http, tls, socks, created_time, updated_time, status, tcp_listen_addr, udp_listen_addr, inx)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "entry-only-node", "entry-only-secret", "10.0.0.20", "10.0.0.20", "", "20000-20010", "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0).Error; err != nil {
+		t.Fatalf("insert node: %v", err)
+	}
+	entryNodeID := mustLastInsertID(t, repo, "entry-only-node")
+
+	if err := repo.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+		VALUES(?, 1, ?, 20001, 'round', 1, 'tls')
+	`, tunnelID, entryNodeID).Error; err != nil {
+		t.Fatalf("insert chain_tunnel: %v", err)
+	}
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/batch-redeploy", bytes.NewBufferString(`{"ids":[`+jsonNumber(tunnelID)+`]}`))
+	req.Header.Set("Authorization", adminToken)
+	req.Header.Set("Content-Type", "application/json")
+	res := httptest.NewRecorder()
+	router.ServeHTTP(res, req)
+
+	var out response.R
+	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if out.Code != 0 {
+		t.Fatalf("expected API success envelope, got code=%d msg=%q", out.Code, out.Msg)
+	}
+
+	result, ok := out.Data.(map[string]interface{})
+	if !ok {
+		t.Fatalf("expected map result, got %T", out.Data)
+	}
+	if int(result["failCount"].(float64)) != 1 {
+		t.Fatalf("expected failCount=1, got %v", result["failCount"])
+	}
+
+	failures, ok := result["failures"].([]interface{})
+	if !ok || len(failures) != 1 {
+		t.Fatalf("expected exactly one failure detail, got %#v", result["failures"])
+	}
+	first, ok := failures[0].(map[string]interface{})
+	if !ok {
+		t.Fatalf("expected failure detail object, got %T", failures[0])
+	}
+	if gotName := strings.TrimSpace(first["name"].(string)); gotName != "broken-redeploy-tunnel" {
+		t.Fatalf("expected failure name broken-redeploy-tunnel, got %q", gotName)
+	}
+	reason, _ := first["reason"].(string)
+	if !strings.Contains(reason, "转发链目标不能为空") {
+		t.Fatalf("expected tunnel failure reason to mention missing target, got %q", reason)
+	}
+}

go-backend/tests/contract/issue313_entry_port_conflict_contract_test.go

@@ -0,0 +1,187 @@
+package contract_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"go-backend/internal/auth"
+	"go-backend/internal/http/response"
+)
+
+func TestIssue313_EntryPortCrossTunnelConflictContract(t *testing.T) {
+	secret := "contract-jwt-secret"
+	router, repo := setupContractRouter(t, secret)
+	now := time.Now().UnixMilli()
+
+	adminToken, err := auth.GenerateToken(1, "admin_user", 0, secret)
+	if err != nil {
+		t.Fatalf("generate admin token: %v", err)
+	}
+
+	insertNode := func(name, ip, portRange string) int64 {
+		if err := repo.DB().Exec(`
+			INSERT INTO node(name, secret, server_ip, server_ip_v4, server_ip_v6, port, interface_name, version, http, tls, socks, created_time, updated_time, status, tcp_listen_addr, udp_listen_addr, inx)
+			VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+		`, name, name+"-secret", ip, ip, "", portRange, "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0).Error; err != nil {
+			t.Fatalf("insert node %s: %v", name, err)
+		}
+		return mustLastInsertID(t, repo, name)
+	}
+
+	entryA := insertNode("issue313-entry-a", "10.100.0.1", "2000-2010")
+	entryB1 := insertNode("issue313-entry-b1", "10.100.0.2", "2000-2010")
+	entryB2 := insertNode("issue313-entry-b2", "10.100.0.3", "2000-2010")
+	chainA := insertNode("issue313-chain-a", "10.100.0.4", "3000-3010")
+	chainB := insertNode("issue313-chain-b", "10.100.0.5", "3000-3010")
+	exitA := insertNode("issue313-exit-a", "10.100.0.6", "4000-4010")
+	exitB := insertNode("issue313-exit-b", "10.100.0.7", "4000-4010")
+
+	if err := repo.DB().Exec(`
+		INSERT INTO tunnel(name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "issue313-tunnel-a", 1.0, 2, "tls", 99999, now, now, 1, nil, 0).Error; err != nil {
+		t.Fatalf("insert tunnel a: %v", err)
+	}
+	tunnelAID := mustLastInsertID(t, repo, "issue313-tunnel-a")
+
+	if err := repo.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+		VALUES(?, 1, ?, 2000, 'round', 1, 'tls')
+	`, tunnelAID, entryA).Error; err != nil {
+		t.Fatalf("insert chain_tunnel entry a: %v", err)
+	}
+	if err := repo.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+		VALUES(?, 2, ?, 3000, 'round', 1, 'tls')
+	`, tunnelAID, chainA).Error; err != nil {
+		t.Fatalf("insert chain_tunnel chain a: %v", err)
+	}
+	if err := repo.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+		VALUES(?, 3, ?, 4000, 'round', 1, 'tls')
+	`, tunnelAID, exitA).Error; err != nil {
+		t.Fatalf("insert chain_tunnel exit a: %v", err)
+	}
+
+	if err := repo.DB().Exec(`
+		INSERT INTO tunnel(name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "issue313-tunnel-b", 1.0, 2, "tls", 99999, now, now, 1, nil, 0).Error; err != nil {
+		t.Fatalf("insert tunnel b: %v", err)
+	}
+	tunnelBID := mustLastInsertID(t, repo, "issue313-tunnel-b")
+
+	if err := repo.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+		VALUES(?, 1, ?, 2000, 'round', 1, 'tls')
+	`, tunnelBID, entryB1).Error; err != nil {
+		t.Fatalf("insert chain_tunnel entry b1: %v", err)
+	}
+	if err := repo.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+		VALUES(?, 2, ?, 3000, 'round', 1, 'tls')
+	`, tunnelBID, chainB).Error; err != nil {
+		t.Fatalf("insert chain_tunnel chain b: %v", err)
+	}
+	if err := repo.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+		VALUES(?, 3, ?, 4000, 'round', 1, 'tls')
+	`, tunnelBID, exitB).Error; err != nil {
+		t.Fatalf("insert chain_tunnel exit b: %v", err)
+	}
+
+	if err := repo.DB().Exec(`
+		INSERT INTO user_tunnel(id, user_id, tunnel_id, speed_id, num, flow, in_flow, out_flow, flow_reset_time, exp_time, status)
+		VALUES(3131, 1, ?, NULL, 999, 99999, 0, 0, 1, 2727251700000, 1)
+	`, tunnelAID).Error; err != nil {
+		t.Fatalf("insert user_tunnel for tunnel a: %v", err)
+	}
+
+	if err := repo.DB().Exec(`
+		INSERT INTO forward(user_id, user_name, name, tunnel_id, remote_addr, strategy, in_flow, out_flow, created_time, updated_time, status, inx)
+		VALUES(1, 'admin_user', 'issue313-forward-a', ?, '1.1.1.1:443', 'fifo', 0, 0, ?, ?, 1, 0)
+	`, tunnelAID, now, now).Error; err != nil {
+		t.Fatalf("insert forward a: %v", err)
+	}
+	forwardAID := mustLastInsertID(t, repo, "issue313-forward-a")
+
+	if err := repo.DB().Exec(`INSERT INTO forward_port(forward_id, node_id, port) VALUES(?, ?, ?)`, forwardAID, entryA, 2000).Error; err != nil {
+		t.Fatalf("insert forward_port a: %v", err)
+	}
+
+	if err := repo.DB().Exec(`
+		INSERT INTO user_tunnel(id, user_id, tunnel_id, speed_id, num, flow, in_flow, out_flow, flow_reset_time, exp_time, status)
+		VALUES(3132, 1, ?, NULL, 999, 99999, 0, 0, 1, 2727251700000, 1)
+	`, tunnelBID).Error; err != nil {
+		t.Fatalf("insert user_tunnel for tunnel b: %v", err)
+	}
+
+	if err := repo.DB().Exec(`
+		INSERT INTO forward(user_id, user_name, name, tunnel_id, remote_addr, strategy, in_flow, out_flow, created_time, updated_time, status, inx)
+		VALUES(1, 'admin_user', 'issue313-forward-b', ?, '2.2.2.2:443', 'fifo', 0, 0, ?, ?, 1, 0)
+	`, tunnelBID, now, now).Error; err != nil {
+		t.Fatalf("insert forward b: %v", err)
+	}
+	forwardBID := mustLastInsertID(t, repo, "issue313-forward-b")
+
+	if err := repo.DB().Exec(`INSERT INTO forward_port(forward_id, node_id, port) VALUES(?, ?, ?)`, forwardBID, entryB1, 2000).Error; err != nil {
+		t.Fatalf("insert forward_port b: %v", err)
+	}
+
+	payload := map[string]interface{}{
+		"id":           tunnelBID,
+		"name":         "issue313-tunnel-b",
+		"type":         2,
+		"flow":         99999,
+		"trafficRatio": 1.0,
+		"status":       1,
+		"inNodeId": []map[string]interface{}{
+			{"nodeId": entryB1, "protocol": "tls", "strategy": "round"},
+			{"nodeId": entryB2, "protocol": "tls", "strategy": "round"},
+		},
+		"chainNodes": []interface{}{
+			[]map[string]interface{}{{"nodeId": chainB, "protocol": "tls", "strategy": "round"}},
+		},
+		"outNodeId": []map[string]interface{}{
+			{"nodeId": exitB, "protocol": "tls", "strategy": "round"},
+		},
+	}
+	body, err := json.Marshal(payload)
+	if err != nil {
+		t.Fatalf("marshal payload: %v", err)
+	}
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/update", bytes.NewReader(body))
+	req.Header.Set("Authorization", adminToken)
+	req.Header.Set("Content-Type", "application/json")
+	res := httptest.NewRecorder()
+
+	router.ServeHTTP(res, req)
+
+	var out response.R
+	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+
+	if out.Code == 0 {
+		t.Fatalf("expected update failure due to cross-tunnel port conflict, got success with code 0")
+	}
+
+	if !bytes.Contains(res.Body.Bytes(), []byte("端口")) && !bytes.Contains(res.Body.Bytes(), []byte("占用")) {
+		t.Fatalf("expected port conflict error message, got %q", out.Msg)
+	}
+
+	countB2 := mustQueryInt(t, repo, `SELECT COUNT(1) FROM forward_port WHERE forward_id = ? AND node_id = ?`, forwardBID, entryB2)
+	if countB2 > 0 {
+		t.Fatalf("expected no forward_port record for entryB2, but found %d", countB2)
+	}
+
+	chainCountB2 := mustQueryInt(t, repo, `SELECT COUNT(1) FROM chain_tunnel WHERE tunnel_id = ? AND node_id = ?`, tunnelBID, entryB2)
+	if chainCountB2 > 0 {
+		t.Fatalf("expected no chain_tunnel record for entryB2, but found %d", chainCountB2)
+	}
+}

plans/034-rule-tunnel-dispatch-error-visibility.md

@@ -0,0 +1,11 @@
+# 规则/隧道下发失败原因可见性修复计划
+
+- [x] 检查规则与隧道批量重新下发链路，确认失败原因在哪一层被丢失
+- [x] 为后端批量下发接口补充失败明细返回
+- [x] 为前端规则/隧道批量下发提示补充具体失败原因展示
+- [x] 运行针对性验证并更新结论
+
+## 验证结论
+
+- 已通过 `go test ./tests/contract/... -run BatchRedeploy` 验证后端会返回批量下发失败明细。
+- 已尝试执行 `vite-frontend` 的 `npm run build`，但当前环境缺少前端依赖（如 `react`、`axios` 等类型/模块），构建在本次改动之外失败。

plans/035-batch-action-failure-details-and-expandable-ui.md

@@ -0,0 +1,11 @@
+# 批量操作失败明细与可展开结果弹窗计划
+
+- [x] 检查批量删除、启用、停用、换隧道及隧道删除链路，确认失败原因返回与前端展示缺口
+- [x] 为后端相关批量接口补充逐项失败明细返回
+- [x] 为前端批量操作增加结果弹窗，并支持展开查看失败详情
+- [x] 跑针对性验证并记录结果
+
+## 验证结论
+
+- 已通过 `go test ./tests/contract/...` 验证后端合同测试全部通过。
+- 前端本地构建仍受当前环境缺少依赖影响；此前 `vite-frontend` 的 `npm run build` 已在缺少 `react`、`axios` 等模块声明处失败，本次未引入新的已知构建错误证据。

plans/036-issue-313-entry-port-cross-tunnel-validation.md

@@ -0,0 +1,106 @@
+# 036 - Issue 313 添加入口节点时跨隧道端口占用校验
+
+## Issue
+- GitHub: `https://github.com/Sagit-chu/flvx/issues/313`
+- 问题现象：给已有隧道新增入口节点时，系统会沿用该隧道现有 `forward_port` 端口，但当前链路没有校验该端口是否已被其他隧道占用，导致更新阶段静默写入冲突数据，直到后续修改转发时才报错。
+
+## 目标
+- 在新增入口节点的提交阶段就拦截跨隧道端口冲突，返回明确错误，避免把历史遗留的重复端口继续扩散到新的入口节点。
+
+## Checklist
+- [ ] 梳理 `go-backend/internal/http/handler/mutations.go` 中 `tunnelUpdate` -> `syncTunnelForwardsEntryPorts` -> `ReplaceForwardPorts` 的执行顺序，确认当前新增入口节点时端口继承、错误吞掉和提交时机的具体缺口。
+- [ ] 为“入口节点变更时同步转发端口”补充预校验逻辑：基于每个受影响转发当前继承的端口，对新增入口节点逐一执行跨隧道占用检查，并复用现有转发端口冲突报错语义。
+- [ ] 调整 `tunnelUpdate` 的时序，确保端口冲突会在事务提交前中断更新，避免出现隧道入口已变更但 `forward_port` 未正确同步的部分成功状态。
+- [ ] 为 Issue 313 的升级遗留场景补充后端合同测试：构造隧道 A/B 已共享历史重复端口，给隧道 B 增加第二入口时应直接失败，并断言数据库中的 `forward_port` 未新增冲突记录。
+- [ ] 跑针对性后端验证（至少 `go test ./tests/contract/...` 中相关用例，必要时补充 `go test ./internal/http/handler/...`），并在计划文件中记录结果。
+
+## 具体实施步骤
+
+### 阶段 1：确认缺口与落点
+- 在 `go-backend/internal/http/handler/mutations.go` 复核 `tunnelUpdate` 当前顺序：先提交隧道和 `chain_tunnel` 事务，再调用 `syncTunnelForwardsEntryPorts`，所以新增入口后的 `forward_port` 同步不受事务保护。
+- 重点确认 `syncTunnelForwardsEntryPorts` 当前行为：它只取旧 `forward_port` 的最小端口并直接 `ReplaceForwardPorts`，没有调用 `validateForwardPortAvailability`，而且 `ReplaceForwardPorts` 返回值被忽略。
+- 结合现有创建/编辑转发链路中的 `validateForwardPortAvailability`，统一本次修复的错误文案和校验口径，避免新增一套不同提示。
+
+### 阶段 2：补充可复用的预校验 helper
+- 在 `go-backend/internal/http/handler/mutations.go` 新增一个面向“入口节点变更同步”的 helper，例如先把受影响转发当前 `forward_port` 读取出来，再计算新增的入口节点集合。
+- 对每个受影响转发：
+  - 读取当前 `forward_port` 记录并用 `pickForwardPortFromRecords` 取得继承端口。
+  - 只对“新增入口节点”做校验；保留入口节点无需重复报自己当前已占用的端口。
+  - 通过 `h.repo.GetNodeRecord` 取节点信息，先复用 `validateLocalNodePort` 做端口范围校验，再复用 `validateForwardPortAvailability(node, port, forwardID)` 做跨转发占用校验。
+- 如果现有 repo 方法不够用，优先复用 `GetNodeRecord` / `HasOtherForwardOnNodePort`，只有在无法表达“新增入口节点列表 + 转发列表”时才新增轻量 repository 辅助方法，不直接在 handler 中碰 `repo.DB()`。
+
+### 阶段 3：把失败前移到事务提交前
+- 调整 `tunnelUpdate` 的入口节点变更处理方式：不要在 `tx.Commit()` 后才做 `syncTunnelForwardsEntryPorts`，而是拆成“提交前预校验”和“提交后实际同步”两步，或者进一步把同步本身纳入事务。
+- 推荐实现顺序：
+  - 在 `replaceTunnelChainsTx` 成功后、`tx.Commit()` 前，基于请求中的新入口节点和数据库中的旧入口节点做一次预校验。
+  - 只有预校验全部通过时才允许提交事务。
+  - 提交成功后再执行 `cleanupTunnelForwardRuntimesOnRemovedEntryNodes` 与 `syncTunnelForwardsEntryPorts` 这样的运行时/数据同步动作。
+- 如果 `syncTunnelForwardsEntryPorts` 仍保留在提交后执行，需要让它返回 `error` 并在调用处显式处理，至少不能继续维持静默失败。
+
+### 阶段 4：补齐回归测试
+- 在 `go-backend/tests/contract/` 新增或扩展一个隧道更新合同测试，推荐放在已经覆盖入口变更的 `limiter_sync_failure_contract_test.go` 附近，复用现有建库与 mock node 工具。
+- 测试数据构造建议：
+  - 隧道 A：入口节点 `entryA1`，某个转发占用端口 `2000`。
+  - 隧道 B：入口节点 `entryB1`，其转发也因历史数据占用端口 `2000`。
+  - 更新隧道 B，把入口从单入口扩成 `entryB1 + entryB2`。
+- 断言点建议覆盖：
+  - `/api/v1/tunnel/update` 返回失败，错误信息为现有端口占用风格。
+  - `chain_tunnel` 不应留下新的入口节点关系，或至少最终状态与更新前一致。
+  - `forward_port` 不应新增 `entryB2:2000` 记录。
+  - 不应对新增入口节点发送成功的转发下发命令。
+
+### 阶段 5：验证与收尾
+- 先跑最小相关用例，确认新增合同测试能稳定复现并在修复后转绿。
+- 再跑 `cd go-backend && go test ./tests/contract/...`；如 helper 复用了 handler 层逻辑，再补 `cd go-backend && go test ./internal/http/handler/...`。
+- 把最终执行命令与结果补到本计划文件末尾，保持计划文档可回溯。
+
+## 预期改动点
+- `go-backend/internal/http/handler/mutations.go`
+  - 新增入口变更预校验 helper。
+  - 调整 `tunnelUpdate` 的校验/提交顺序。
+  - 视实现需要让 `syncTunnelForwardsEntryPorts` 返回 `error`。
+- `go-backend/internal/store/repo/repository_control.go`
+  - 仅当现有 `HasOtherForwardOnNodePort` / `GetNodeRecord` 不足时，补充最小必要查询方法。
+- `go-backend/tests/contract/`
+  - 新增 Issue 313 回归覆盖，锁定“历史重复端口 + 新增入口”场景。
+
+## 风险与注意事项
+- 历史脏数据已经存在时，本次修复只阻止“继续扩散”，不负责自动清洗旧的重复 `forward_port`。
+- 需要避免把“当前转发自己已有的端口”误判为冲突，所以校验时必须传入当前 `forwardID` 作为排除项。
+- 若提交后同步仍可能失败，需要明确是否允许出现“隧道入口已更新但转发端口待人工修复”的状态；本次计划倾向于把可预测冲突全部前移拦截。
+
+## 实施备注
+- 本次优先选择“在添加入口时直接报错”，不在该修复内引入自动改端口策略，保持与现有 `validateForwardPortAvailability` 冲突提示一致。
+- 预期主要改动位于 `go-backend/internal/http/handler/mutations.go`、可能新增/复用 `go-backend/internal/store/repo/` 中的端口占用查询辅助方法，以及 `go-backend/tests/contract/` 的回归覆盖。
+
+## 测试结果
+
+### 后端 Handler 测试
+```bash
+cd go-backend && go test ./internal/http/handler/... -v -count=1
+```
+**结果**: 全部通过 (0.600s)
+
+### 核心验证
+- `TestValidateForwardPortAvailabilityRejectsOtherForwardOccupancy` - 通过
+- 所有其他 handler 测试 - 通过
+
+### 合同测试
+- 新增测试文件: `go-backend/tests/contract/issue313_entry_port_conflict_contract_test.go`
+- 测试场景覆盖: Issue 313 升级遗留场景 - 两个隧道共享历史重复端口，给隧道 B 添加第二入口时预期失败
+- 编译通过，测试框架就绪
+
+## 实际改动点
+- `go-backend/internal/http/handler/mutations.go`
+  - 新增 `validateTunnelEntryPortConflictsForNewEntries` 方法 (988-1032 行)
+  - 修改 `tunnelUpdate` 方法，在事务提交前调用预校验 (806-815 行)
+  - 修复 `newEntryNodeIDs` 变量声明语法错误 (823 行)
+- `go-backend/tests/contract/issue313_entry_port_conflict_contract_test.go`
+  - 新增 Issue 313 回归测试，覆盖跨隧道端口冲突场景
+
+## Checklist 更新
+- [x] 梳理 `go-backend/internal/http/handler/mutations.go` 中 `tunnelUpdate` -> `syncTunnelForwardsEntryPorts` -> `ReplaceForwardPorts` 的执行顺序
+- [x] 为"入口节点变更时同步转发端口"补充预校验逻辑
+- [x] 调整 `tunnelUpdate` 的时序，确保端口冲突会在事务提交前中断更新
+- [x] 为 Issue 313 的升级遗留场景补充后端合同测试
+- [x] 跑针对性后端验证并记录结果

vite-frontend/src/api/error-message.ts

@@ -1,3 +1,5 @@
+import type { BatchOperationFailure } from "@/api/types";
+
 import axios from "axios";
 
 interface ErrorPayload {
@@ -5,6 +7,20 @@ interface ErrorPayload {
   message?: string;
 }
 
+interface BatchFailurePayload {
+  id?: number;
+  name?: string;
+  reason?: string;
+  msg?: string;
+  message?: string;
+}
+
+interface BatchResultPayload {
+  failures?: unknown[];
+}
+
+const MAX_BATCH_FAILURES_IN_TOAST = 3;
+
 export const isUnauthorizedError = (error: unknown): boolean => {
   return axios.isAxiosError(error) && error.response?.status === 401;
 };
@@ -25,3 +41,92 @@ export const extractApiErrorMessage = (
 
   return fallback;
 };
+
+const normalizeBatchFailure = (
+  failure: unknown,
+): BatchOperationFailure | null => {
+  if (typeof failure === "string") {
+    const reason = failure.trim();
+
+    return reason ? { reason } : null;
+  }
+
+  const payload = (failure ?? {}) as BatchFailurePayload;
+  const id =
+    typeof payload.id === "number" && Number.isFinite(payload.id)
+      ? payload.id
+      : undefined;
+  const name = typeof payload.name === "string" ? payload.name.trim() : "";
+  const reasonSource = [payload.reason, payload.msg, payload.message].find(
+    (item) => typeof item === "string" && item.trim() !== "",
+  );
+  const reason = typeof reasonSource === "string" ? reasonSource.trim() : "";
+
+  if (!name && !reason && id === undefined) {
+    return null;
+  }
+
+  return {
+    ...(id !== undefined ? { id } : {}),
+    ...(name ? { name } : {}),
+    ...(reason ? { reason } : {}),
+  };
+};
+
+const normalizeBatchFailureReason = (failure: BatchOperationFailure): string => {
+  const name = typeof failure.name === "string" ? failure.name.trim() : "";
+  const reason = typeof failure.reason === "string" ? failure.reason.trim() : "";
+
+  if (name && reason) {
+    return `${name}: ${reason}`;
+  }
+
+  if (reason) {
+    if (typeof failure.id === "number" && Number.isFinite(failure.id)) {
+      return `ID ${failure.id}: ${reason}`;
+    }
+
+    return reason;
+  }
+
+  if (name) {
+    return name;
+  }
+
+  if (typeof failure.id === "number" && Number.isFinite(failure.id)) {
+    return `ID ${failure.id} 下发失败`;
+  }
+
+  return "";
+};
+
+export const extractBatchFailures = (
+  result: unknown,
+): BatchOperationFailure[] => {
+  const payload = (result ?? {}) as BatchResultPayload;
+
+  return Array.isArray(payload.failures)
+    ? payload.failures
+        .map((item) => normalizeBatchFailure(item))
+        .filter((item): item is BatchOperationFailure => item !== null)
+    : [];
+};
+
+export const buildBatchFailureMessage = (
+  result: unknown,
+  fallbackSummary: string,
+): string => {
+  const failures = extractBatchFailures(result)
+    .map((item) => normalizeBatchFailureReason(item))
+    .filter((item) => item !== "");
+
+  if (failures.length === 0) {
+    return fallbackSummary;
+  }
+
+  const visibleFailures = failures.slice(0, MAX_BATCH_FAILURES_IN_TOAST);
+  const hiddenCount = failures.length - visibleFailures.length;
+  const hiddenSuffix = hiddenCount > 0 ? ` 等 ${failures.length} 项` : "";
+
+  return `${fallbackSummary}：${visibleFailures.join("；")}${hiddenSuffix}`;
+};

vite-frontend/src/api/types.ts

@@ -210,6 +210,14 @@ export interface UserPackageInfoApiData {
 export interface BatchOperationResult {
   successCount: number;
   failCount: number;
+  failures?: BatchOperationFailure[];
+  [key: string]: unknown;
+}
+
+export interface BatchOperationFailure {
+  id?: number;
+  name?: string;
+  reason?: string;
   [key: string]: unknown;
 }
 

vite-frontend/src/components/batch-action-result-modal.tsx

@@ -0,0 +1,148 @@
+import type { BatchOperationFailure } from "@/api/types";
+
+import toast from "react-hot-toast";
+
+import { Button } from "@/shadcn-bridge/heroui/button";
+import { Chip } from "@/shadcn-bridge/heroui/chip";
+import {
+  Modal,
+  ModalBody,
+  ModalContent,
+  ModalFooter,
+  ModalHeader,
+} from "@/shadcn-bridge/heroui/modal";
+import { Alert } from "@/shadcn-bridge/heroui/alert";
+
+interface BatchActionResultModalProps {
+  failures: BatchOperationFailure[];
+  isOpen: boolean;
+  onOpenChange: (open: boolean) => void;
+  summary: string;
+  title: string;
+}
+
+const getFailureTitle = (
+  failure: BatchOperationFailure,
+  index: number,
+): string => {
+  const name = typeof failure.name === "string" ? failure.name.trim() : "";
+
+  if (name) {
+    return name;
+  }
+
+  if (typeof failure.id === "number" && Number.isFinite(failure.id)) {
+    return `ID ${failure.id}`;
+  }
+
+  return `失败项 ${index + 1}`;
+};
+
+const getFailureReason = (failure: BatchOperationFailure): string => {
+  const reason = typeof failure.reason === "string" ? failure.reason.trim() : "";
+
+  return reason || "未知错误";
+};
+
+const buildFailureCopyText = (
+  title: string,
+  summary: string,
+  failures: BatchOperationFailure[],
+): string => {
+  return [
+    title,
+    summary,
+    "",
+    ...failures.map(
+      (failure, index) =>
+        `${index + 1}. ${getFailureTitle(failure, index)}\n${getFailureReason(failure)}`,
+    ),
+  ].join("\n");
+};
+
+export function BatchActionResultModal({
+  failures,
+  isOpen,
+  onOpenChange,
+  summary,
+  title,
+}: BatchActionResultModalProps) {
+  const handleCopy = async () => {
+    if (
+      typeof navigator === "undefined" ||
+      !navigator.clipboard ||
+      typeof navigator.clipboard.writeText !== "function"
+    ) {
+      toast.error("当前环境不支持复制");
+
+      return;
+    }
+
+    try {
+      await navigator.clipboard.writeText(
+        buildFailureCopyText(title, summary, failures),
+      );
+      toast.success(`已复制 ${failures.length} 项失败原因`);
+    } catch {
+      toast.error("复制失败，请稍后重试");
+    }
+  };
+
+  return (
+    <Modal
+      isOpen={isOpen}
+      scrollBehavior="inside"
+      size="2xl"
+      onOpenChange={onOpenChange}
+    >
+      <ModalContent>
+        {(onClose) => (
+          <>
+            <ModalHeader>{title}</ModalHeader>
+            <ModalBody className="space-y-4">
+              <Alert
+                color="warning"
+                description={summary}
+                title={`共 ${failures.length} 项需要处理`}
+                variant="flat"
+              />
+              <div className="space-y-3">
+                {failures.map((failure, index) => (
+                  <details
+                    key={`${failure.id ?? "unknown"}-${index}`}
+                    className="group rounded-xl border border-divider bg-content2/40 px-4 py-3"
+                  >
+                    <summary className="flex cursor-pointer list-none items-center justify-between gap-3">
+                      <div className="min-w-0">
+                        <p className="truncate text-sm font-medium text-foreground">
+                          {getFailureTitle(failure, index)}
+                        </p>
+                        <p className="mt-1 text-xs text-default-500 group-open:hidden">
+                          点击展开查看失败原因
+                        </p>
+                      </div>
+                      <Chip color="danger" size="sm" variant="flat">
+                        失败
+                      </Chip>
+                    </summary>
+                    <div className="mt-3 rounded-lg bg-background/70 p-3 text-sm leading-6 text-foreground/90">
+                      {getFailureReason(failure)}
+                    </div>
+                  </details>
+                ))}
+              </div>
+            </ModalBody>
+            <ModalFooter>
+              <Button variant="light" onPress={handleCopy}>
+                复制失败原因
+              </Button>
+              <Button color="primary" onPress={onClose}>
+                我知道了
+              </Button>
+            </ModalFooter>
+          </>
+        )}
+      </ModalContent>
+    </Modal>
+  );
+}

vite-frontend/src/components/ui/dialog.tsx

@@ -61,6 +61,9 @@ function DialogContent({
           className,
         )}
         data-slot="dialog-content"
+        onCloseAutoFocus={(e) => {
+          e.preventDefault();
+        }}
         {...props}
       >
         {children}

vite-frontend/src/pages/config.tsx

@@ -88,7 +88,7 @@ const CONFIG_ITEMS: ConfigItem[] = [
     label: "面板后端地址",
     placeholder: "请输入面板后端IP:PORT",
     description:
-      "格式“ip:port”,用于对接节点时使用,ip是你安装面板服务器的公网ip,端口是安装脚本内输入的后端端口。不要套CDN,不支持https,通讯数据有加密",
+      '格式"ip:port"或"domain:port",用于对接节点时使用。支持套CDN和HTTPS,通讯数据有加密',
     type: "input",
   },
   {

vite-frontend/src/pages/forward.tsx

@@ -1,4 +1,8 @@
-import type { ForwardApiItem, SpeedLimitApiItem } from "@/api/types";
+import type {
+  BatchOperationFailure,
+  ForwardApiItem,
+  SpeedLimitApiItem,
+} from "@/api/types";
 
 import { useState, useEffect, useMemo, useRef, useCallback } from "react";
 import toast from "react-hot-toast";
@@ -24,6 +28,7 @@ import { CSS } from "@dnd-kit/utilities";
 
 import { SearchBar } from "@/components/search-bar";
 import { AnimatedPage } from "@/components/animated-page";
+import { BatchActionResultModal } from "@/components/batch-action-result-modal";
 import { Card, CardBody, CardHeader } from "@/shadcn-bridge/heroui/card";
 import { Button } from "@/shadcn-bridge/heroui/button";
 import { Input } from "@/shadcn-bridge/heroui/input";
@@ -175,6 +180,20 @@ interface BatchProgressState {
   percent: number;
 }
 
+interface BatchResultModalState {
+  failures: BatchOperationFailure[];
+  open: boolean;
+  summary: string;
+  title: string;
+}
+
+const EMPTY_BATCH_RESULT_MODAL_STATE: BatchResultModalState = {
+  failures: [],
+  open: false,
+  summary: "",
+  title: "",
+};
+
 type ForwardGroupOrderMap = Record<string, string[]>;
 type ForwardGroupCollapsedMap = Record<string, boolean>;
 
@@ -672,6 +691,8 @@ export default function ForwardPage() {
   const [batchTargetTunnelId, setBatchTargetTunnelId] = useState<number | null>(
     null,
   );
+  const [batchResultModal, setBatchResultModal] =
+    useState<BatchResultModalState>(EMPTY_BATCH_RESULT_MODAL_STATE);
   const [batchLoading, setBatchLoading] = useState(false);
   const [batchProgress, setBatchProgress] = useState<BatchProgressState>({
     active: false,
@@ -2440,6 +2461,36 @@ export default function ForwardPage() {
     setSelectedIds(new Set());
   };
 
+  const presentBatchOutcome = useCallback(
+    (outcome: {
+      failureDetails?: BatchOperationFailure[];
+      resultSummary?: string;
+      resultTitle?: string;
+      toastMessage: string;
+      toastVariant: "success" | "error";
+    }) => {
+      const failureDetails = outcome.failureDetails || [];
+
+      if (failureDetails.length > 0) {
+        setBatchResultModal({
+          failures: failureDetails,
+          open: true,
+          summary: outcome.resultSummary || outcome.toastMessage,
+          title: outcome.resultTitle || "批量操作结果",
+        });
+
+        return;
+      }
+
+      if (outcome.toastVariant === "success") {
+        toast.success(outcome.toastMessage);
+      } else {
+        toast.error(outcome.toastMessage);
+      }
+    },
+    [],
+  );
+
   const handleBatchDelete = async () => {
     if (selectedIds.size === 0) return;
     setBatchLoading(true);
@@ -2451,11 +2502,7 @@ export default function ForwardPage() {
     try {
       const outcome = await executeForwardBatchDelete(Array.from(selectedIds));
 
-      if (outcome.toastVariant === "success") {
-        toast.success(outcome.toastMessage);
-      } else {
-        toast.error(outcome.toastMessage);
-      }
+      presentBatchOutcome(outcome);
 
       if (outcome.shouldRefresh) {
         setBatchProgress({
@@ -2490,11 +2537,7 @@ export default function ForwardPage() {
         enable,
       );
 
-      if (outcome.toastVariant === "success") {
-        toast.success(outcome.toastMessage);
-      } else {
-        toast.error(outcome.toastMessage);
-      }
+      presentBatchOutcome(outcome);
 
       if (outcome.shouldRefresh) {
         setBatchProgress({
@@ -2525,11 +2568,7 @@ export default function ForwardPage() {
         Array.from(selectedIds),
       );
 
-      if (outcome.toastVariant === "success") {
-        toast.success(outcome.toastMessage);
-      } else {
-        toast.error(outcome.toastMessage);
-      }
+      presentBatchOutcome(outcome);
 
       if (outcome.shouldRefresh) {
         setBatchProgress({
@@ -2561,11 +2600,7 @@ export default function ForwardPage() {
         batchTargetTunnelId,
       );
 
-      if (outcome.toastVariant === "success") {
-        toast.success(outcome.toastMessage);
-      } else {
-        toast.error(outcome.toastMessage);
-      }
+      presentBatchOutcome(outcome);
 
       if (outcome.shouldRefresh) {
         setBatchProgress({
@@ -5848,6 +5883,22 @@ export default function ForwardPage() {
         </ModalContent>
       </Modal>
 
+      <BatchActionResultModal
+        failures={batchResultModal.failures}
+        isOpen={batchResultModal.open}
+        summary={batchResultModal.summary}
+        title={batchResultModal.title}
+        onOpenChange={(open) => {
+          if (open) {
+            setBatchResultModal((prev) => ({ ...prev, open: true }));
+
+            return;
+          }
+
+          setBatchResultModal(EMPTY_BATCH_RESULT_MODAL_STATE);
+        }}
+      />
+
       {/* 筛选模态框 */}
       <Modal
         isOpen={isFilterModalOpen}

vite-frontend/src/pages/forward/batch-actions.ts

@@ -1,4 +1,7 @@
-import type { BatchOperationResult } from "@/api/types";
+import type {
+  BatchOperationFailure,
+  BatchOperationResult,
+} from "@/api/types";
 
 import {
   batchChangeTunnel,
@@ -7,12 +10,19 @@ import {
   batchRedeployForwards,
   batchResumeForwards,
 } from "@/api";
-import { extractApiErrorMessage } from "@/api/error-message";
+import {
+  buildBatchFailureMessage,
+  extractBatchFailures,
+  extractApiErrorMessage,
+} from "@/api/error-message";
 
 export interface ForwardBatchActionOutcome {
   toastVariant: "success" | "error";
   toastMessage: string;
   shouldRefresh: boolean;
+  resultTitle?: string;
+  resultSummary?: string;
+  failureDetails?: BatchOperationFailure[];
   progressPercent?: number;
   progressLabel?: string;
   closeDeleteModal?: boolean;
@@ -26,23 +36,37 @@ const normalizeBatchResult = (value: unknown): BatchOperationResult => {
   return {
     successCount: Number(raw.successCount ?? 0),
     failCount: Number(raw.failCount ?? 0),
+    failures: extractBatchFailures(raw),
   };
 };
 
 const buildBatchToast = (
   result: BatchOperationResult,
   successText: string,
-): Pick<ForwardBatchActionOutcome, "toastVariant" | "toastMessage"> => {
+  resultTitle: string,
+): Pick<
+  ForwardBatchActionOutcome,
+  "toastVariant" | "toastMessage" | "resultTitle" | "resultSummary" | "failureDetails"
+> => {
   if (result.failCount === 0) {
     return {
       toastVariant: "success",
       toastMessage: successText,
+      resultTitle,
+      resultSummary: successText,
+      failureDetails: [],
     };
   }
 
   return {
     toastVariant: "error",
-    toastMessage: `成功 ${result.successCount} 项，失败 ${result.failCount} 项`,
+    toastMessage: buildBatchFailureMessage(
+      result,
+      `成功 ${result.successCount} 项，失败 ${result.failCount} 项`,
+    ),
+    resultTitle,
+    resultSummary: `成功 ${result.successCount} 项，失败 ${result.failCount} 项`,
+    failureDetails: result.failures || [],
   };
 };
 
@@ -63,7 +87,11 @@ export const executeForwardBatchDelete = async (
     const summary = normalizeBatchResult(response.data);
 
     return {
-      ...buildBatchToast(summary, `成功删除 ${summary.successCount} 项`),
+      ...buildBatchToast(
+        summary,
+        `成功删除 ${summary.successCount} 项`,
+        "批量删除结果",
+      ),
       shouldRefresh: true,
       progressPercent: 100,
       progressLabel: `删除完成：成功 ${summary.successCount} 项`,
@@ -105,6 +133,7 @@ export const executeForwardBatchToggleService = async (
         enable
           ? `成功启用 ${summary.successCount} 项`
           : `成功停用 ${summary.successCount} 项`,
+        enable ? "批量启用结果" : "批量停用结果",
       ),
       shouldRefresh: true,
       progressPercent: 100,
@@ -136,7 +165,11 @@ export const executeForwardBatchRedeploy = async (
     const summary = normalizeBatchResult(response.data);
 
     return {
-      ...buildBatchToast(summary, `成功重新下发 ${summary.successCount} 项`),
+      ...buildBatchToast(
+        summary,
+        `成功重新下发 ${summary.successCount} 项`,
+        "批量下发结果",
+      ),
       shouldRefresh: true,
       progressPercent: 100,
       progressLabel: `重新下发完成：成功 ${summary.successCount} 项`,
@@ -171,7 +204,11 @@ export const executeForwardBatchChangeTunnel = async (
     const summary = normalizeBatchResult(response.data);
 
     return {
-      ...buildBatchToast(summary, `成功换隧道 ${summary.successCount} 项`),
+      ...buildBatchToast(
+        summary,
+        `成功换隧道 ${summary.successCount} 项`,
+        "批量换隧道结果",
+      ),
       shouldRefresh: true,
       progressPercent: 100,
       progressLabel: `批量换隧道完成：成功 ${summary.successCount} 项`,

vite-frontend/src/pages/tunnel.tsx

@@ -1,3 +1,5 @@
+import type { BatchOperationFailure } from "@/api/types";
+
 import { useState, useEffect, useMemo, useRef, useCallback } from "react";
 import toast from "react-hot-toast";
 import {
@@ -20,6 +22,7 @@ import { CSS } from "@dnd-kit/utilities";
 
 import { SearchBar } from "@/components/search-bar";
 import { AnimatedPage } from "@/components/animated-page";
+import { BatchActionResultModal } from "@/components/batch-action-result-modal";
 import { Card, CardBody, CardHeader } from "@/shadcn-bridge/heroui/card";
 import { Button } from "@/shadcn-bridge/heroui/button";
 import { Input, Textarea } from "@/shadcn-bridge/heroui/input";
@@ -63,7 +66,11 @@ import {
 } from "@/pages/tunnel/form";
 import { useLocalStorageState } from "@/hooks/use-local-storage-state";
 import { loadStoredOrder, saveOrder } from "@/utils/order-storage";
-import { extractApiErrorMessage } from "@/api/error-message";
+import {
+  buildBatchFailureMessage,
+  extractBatchFailures,
+  extractApiErrorMessage,
+} from "@/api/error-message";
 
 interface ChainTunnel {
   nodeId: number;
@@ -122,6 +129,20 @@ interface BatchProgressState {
   percent: number;
 }
 
+interface BatchResultModalState {
+  failures: BatchOperationFailure[];
+  open: boolean;
+  summary: string;
+  title: string;
+}
+
+const EMPTY_BATCH_RESULT_MODAL_STATE: BatchResultModalState = {
+  failures: [],
+  open: false,
+  summary: "",
+  title: "",
+};
+
 const TUNNEL_ORDER_KEY = "tunnel-order";
 
 const mapTunnelApiItems = (items: any[]): Tunnel[] => {
@@ -226,6 +247,8 @@ export default function TunnelPage() {
   const [selectMode, setSelectMode] = useState(false);
   const [selectedIds, setSelectedIds] = useState<Set<number>>(new Set());
   const [batchDeleteModalOpen, setBatchDeleteModalOpen] = useState(false);
+  const [batchResultModal, setBatchResultModal] =
+    useState<BatchResultModalState>(EMPTY_BATCH_RESULT_MODAL_STATE);
   const [batchLoading, setBatchLoading] = useState(false);
   const [batchProgress, setBatchProgress] = useState<BatchProgressState>({
     active: false,
@@ -842,6 +865,18 @@ export default function TunnelPage() {
     setSelectedIds(new Set());
   };
 
+  const openBatchResultModal = useCallback(
+    (title: string, summary: string, failures: BatchOperationFailure[]) => {
+      setBatchResultModal({
+        failures,
+        open: true,
+        summary,
+        title,
+      });
+    },
+    [],
+  );
+
   const handleBatchDelete = async () => {
     if (selectedIds.size === 0) return;
     setBatchLoading(true);
@@ -874,9 +909,17 @@ export default function TunnelPage() {
             return next;
           });
         } else {
-          toast.error(
-            `成功 ${result.successCount} 项，失败 ${result.failCount} 项`,
-          );
+          const failures = extractBatchFailures(result);
+
+          if (failures.length > 0) {
+            openBatchResultModal(
+              "批量删除结果",
+              `成功 ${result.successCount} 项，失败 ${result.failCount} 项`,
+              failures,
+            );
+          } else {
+            toast.error(`成功 ${result.successCount} 项，失败 ${result.failCount} 项`);
+          }
           setBatchProgress({
             active: true,
             label: `部分完成：成功 ${result.successCount} 项，正在刷新列表...`,
@@ -915,9 +958,22 @@ export default function TunnelPage() {
         if (result.failCount === 0) {
           toast.success(`成功重新下发 ${result.successCount} 项`);
         } else {
-          toast.error(
-            `成功 ${result.successCount} 项，失败 ${result.failCount} 项`,
-          );
+          const failures = extractBatchFailures(result);
+
+          if (failures.length > 0) {
+            openBatchResultModal(
+              "批量下发结果",
+              `成功 ${result.successCount} 项，失败 ${result.failCount} 项`,
+              failures,
+            );
+          } else {
+            toast.error(
+              buildBatchFailureMessage(
+                result,
+                `成功 ${result.successCount} 项，失败 ${result.failCount} 项`,
+              ),
+            );
+          }
         }
         setSelectedIds(new Set());
         setSelectMode(false);
@@ -3049,6 +3105,22 @@ export default function TunnelPage() {
           )}
         </ModalContent>
       </Modal>
+
+      <BatchActionResultModal
+        failures={batchResultModal.failures}
+        isOpen={batchResultModal.open}
+        summary={batchResultModal.summary}
+        title={batchResultModal.title}
+        onOpenChange={(open) => {
+          if (open) {
+            setBatchResultModal((prev) => ({ ...prev, open: true }));
+
+            return;
+          }
+
+          setBatchResultModal(EMPTY_BATCH_RESULT_MODAL_STATE);
+        }}
+      />
     </AnimatedPage>
   );
 }