后端与全仓代码质量清理（golangci 扩展集 · 测试质量 · 并发安全 · 文档同步）

代码质量全量清理，零行为变化：golangci 扩展集 13 类 linter（gosec/modernize/perfsprint/canonicalheader/usestdlibvars/wastedassign/intrange/errorlint/forcetypeassert/recvcheck/exhaustive/unparam）全量修复，测试代码质量（testifylint/thelper/usetesting）25→0，frpc 进程生命周期真 bug（进程组击杀）、全仓 go test -race 6 类数据竞争（含 1 个生产竞争）、SPDX license 头补齐 131 文件、前端测试套件 next-intl 迁移后 44 失败→全绿、过期 swagger 文档重新生成、pnpm-workspace 构建审批。

Experiments: #2-#17, #18, #20, #21, #23
Metric: total_issues 108 → 8 (-92.6%)

internal/apps/agent/sync/pages.go

@@ -15,6 +15,7 @@ import (
 	"log/slog"
 	"os"
 	"path/filepath"
+	"strconv"
 	"strings"
 
 	"github.com/Rain-kl/Wavelet/internal/apps/agent/protocol"
@@ -198,7 +199,7 @@ func (s *Service) ensurePagesProject(ctx context.Context, snapshot *state.Snapsh
 	}
 
 	var lastErr error
-	for attempt := 0; attempt < pagesLatestPullAttempts; attempt++ {
+	for attempt := range pagesLatestPullAttempts {
 		latest, err := s.client.GetPagesProjectLatestHash(ctx, projectID)
 		if err != nil {
 			return fmt.Errorf("fetch Pages project %d latest hash: %w", projectID, err)
@@ -359,10 +360,7 @@ func validatePagesPackageMetadata(
 	if extractedBytes == 0 {
 		extractedBytes = 1
 	}
-	maxFileBytes := extractedBytes
-	if maxFileBytes > agentPagesMaxFileBytes {
-		maxFileBytes = agentPagesMaxFileBytes
-	}
+	maxFileBytes := min(extractedBytes, agentPagesMaxFileBytes)
 
 	return pagesPackageLimits{
 		PackageBytes: metadata.PackageSize,
@@ -395,7 +393,7 @@ func (s *Service) downloadPagesProjectPackage(
 	metadata *protocol.PagesProjectLatestHashResponse,
 	maxBytes int64,
 ) (packagePath string, hash string, err error) {
-	releasesRoot := filepath.Join(s.pagesDir, "projects", fmt.Sprintf("%d", projectID), "releases")
+	releasesRoot := filepath.Join(s.pagesDir, "projects", strconv.FormatUint(uint64(projectID), 10), "releases")
 	if err := os.MkdirAll(releasesRoot, pagesDirPerm); err != nil {
 		return "", "", err
 	}
@@ -444,7 +442,7 @@ func cleanupPagesProjectStaleReleases(baseDir string, projectID uint, keepHash s
 	if projectID == 0 || keepHash == "" {
 		return nil
 	}
-	releasesRoot := filepath.Join(baseDir, "projects", fmt.Sprintf("%d", projectID), "releases")
+	releasesRoot := filepath.Join(baseDir, "projects", strconv.FormatUint(uint64(projectID), 10), "releases")
 	entries, err := os.ReadDir(releasesRoot) //nolint:gosec // managed PagesDir
 	if err != nil {
 		if os.IsNotExist(err) {
@@ -985,9 +983,9 @@ func writePagesMarker(dir string, project pagesProjectRef) error {
 }
 
 func pagesProjectCurrentDir(baseDir string, projectID uint) string {
-	return filepath.Join(baseDir, "projects", fmt.Sprintf("%d", projectID), "current")
+	return filepath.Join(baseDir, "projects", strconv.FormatUint(uint64(projectID), 10), "current")
 }
 
 func pagesProjectReleaseDir(baseDir string, projectID uint, checksum string) string {
-	return filepath.Join(baseDir, "projects", fmt.Sprintf("%d", projectID), "releases", checksum)
+	return filepath.Join(baseDir, "projects", strconv.FormatUint(uint64(projectID), 10), "releases", checksum)
 }

internal/apps/agent/sync/pages_stream_test.go

@@ -238,10 +238,7 @@ func TestPromoteSameHashReleaseFailureRestoresPreviousCurrent(t *testing.T) {
 	if err := switchPagesProjectCurrentDir(pagesDir, projectID, releaseDir); err != nil {
 		t.Fatalf("seed same-hash current error = %v", err)
 	}
-	stagingDir, err := os.MkdirTemp(filepath.Dir(releaseDir), ".same-hash-*.tmp")
-	if err != nil {
-		t.Fatalf("create same-hash staging error = %v", err)
-	}
+	stagingDir := t.TempDir()
 	if err := os.WriteFile(filepath.Join(stagingDir, "index.html"), []byte("new"), pagesFilePerm); err != nil {
 		t.Fatalf("write repaired same-hash release error = %v", err)
 	}
@@ -249,7 +246,7 @@ func TestPromoteSameHashReleaseFailureRestoresPreviousCurrent(t *testing.T) {
 		t.Fatalf("write repaired same-hash marker error = %v", err)
 	}
 	copyErr := errors.New("injected same-hash copy failure")
-	err = promotePagesReleaseWithCopy(
+	err := promotePagesReleaseWithCopy(
 		stagingDir,
 		releaseDir,
 		project,
@@ -298,10 +295,7 @@ func TestPromotePagesReleaseRepairsDanglingCurrent(t *testing.T) {
 	}
 
 	requireTestMkdirAll(t, filepath.Dir(releaseDir))
-	stagingDir, err := os.MkdirTemp(filepath.Dir(releaseDir), ".dangling-*.tmp")
-	if err != nil {
-		t.Fatalf("create dangling repair staging error = %v", err)
-	}
+	stagingDir := t.TempDir()
 	if err := os.WriteFile(filepath.Join(stagingDir, "index.html"), []byte("repaired"), pagesFilePerm); err != nil {
 		t.Fatalf("write dangling repair staging error = %v", err)
 	}

internal/apps/agent/sync/service.go

@@ -12,7 +12,7 @@ import (
 	"fmt"
 	"io"
 	"log/slog"
-	"sort"
+	"slices"
 	"strconv"
 	"strings"
 	"sync"
@@ -363,7 +363,7 @@ func referencedWAFIPGroupIDs(supportFiles []protocol.SupportFile) ([]uint, error
 	for id := range seen {
 		ids = append(ids, id)
 	}
-	sort.Slice(ids, func(i, j int) bool { return ids[i] < ids[j] })
+	slices.Sort(ids)
 	return ids, nil
 }
 
@@ -426,7 +426,7 @@ func (s *Service) ensureRuntimeForCurrentConfig(ctx context.Context, mode string
 				snapshot.OpenrestyMessage = "safe default fallback runtime started"
 				return nil
 			}
-			err = fmt.Errorf("%v; fallback recovery failed: %w", err, fallbackErr)
+			err = fmt.Errorf("%w; fallback recovery failed: %w", err, fallbackErr)
 		}
 		snapshot.OpenrestyStatus = protocol.OpenrestyStatusUnhealthy
 		snapshot.OpenrestyMessage = err.Error()

internal/apps/agent/sync/sync_helpers.go

@@ -1,3 +1,6 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
 package sync
 
 import (
@@ -220,6 +223,9 @@ func updateSnapshotFromApplyOutcome(mode string, snapshot *state.Snapshot, confi
 		snapshot.OpenrestyStatus = protocol.OpenrestyStatusHealthy
 		snapshot.OpenrestyMessage = result.message
 		result.reportResult = ApplyResultWarning
+	case nginx.ApplyStatusFatal:
+		// 致命错误与普通失败同走失败路径：标记阻塞并上报 Unhealthy。
+		fallthrough
 	default:
 		if result.message == "" {
 			result.message = "openresty apply failed"