后端与全仓代码质量清理（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/flared/config/config.go

@@ -1,3 +1,6 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
 // Package config loads and persists flared daemon configuration.
 package config
 

internal/apps/flared/config/version.go

@@ -1,3 +1,6 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
 package config
 
 // Version is the flared daemon build version string.

internal/apps/flared/flared/runner.go

@@ -1,3 +1,6 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
 // Package flared implements the tunnel client daemon runtime loop.
 package flared
 

internal/apps/flared/frpc/manager.go

@@ -1,3 +1,6 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
 // Package frpc manages frpc child processes for tunnel relay connections.
 package frpc
 
@@ -195,6 +198,17 @@ func (m *Manager) restartProcess(ctx context.Context, relayID string, configPath
 			var stderrBuf bytes.Buffer
 			cmd.Stderr = &stderrBuf
 
+			// frpc 及其中间子进程必须整体随上下文终止：CommandContext 默认只杀
+			// 直接子进程，孤儿孙进程会继续持有 stderr 管道导致 cmd.Wait 阻塞到其
+			// 自然退出。这里为 frpc 单独建进程组并整组 SIGKILL。
+			cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}
+			cmd.Cancel = func() error {
+				if cmd.Process == nil {
+					return nil
+				}
+				return syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL)
+			}
+
 			m.mu.Lock()
 			proc.Cmd = cmd
 			proc.Status = "running"
@@ -203,7 +217,7 @@ func (m *Manager) restartProcess(ctx context.Context, relayID string, configPath
 			startedAt := time.Now()
 			err := cmd.Start()
 			if err == nil {
-				_ = os.WriteFile(pidPath, []byte(fmt.Sprintf("%d", cmd.Process.Pid)), frpcConfigFilePerm)
+				_ = os.WriteFile(pidPath, fmt.Appendf(nil, "%d", cmd.Process.Pid), frpcConfigFilePerm)
 				err = cmd.Wait()
 			}
 			_ = os.Remove(pidPath)

internal/apps/flared/frpc/manager_test.go

@@ -1,3 +1,6 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
 package frpc
 
 import (
@@ -7,6 +10,7 @@ import (
 	"os/exec"
 	"path/filepath"
 	"strings"
+	"syscall"
 	"testing"
 	"time"
 
@@ -16,6 +20,7 @@ import (
 
 // Helper to write control file for the dummy script
 func writeControl(t *testing.T, dir string, exitCode int, delaySeconds int) {
+	t.Helper()
 	controlPath := filepath.Join(dir, "control.txt")
 	content := fmt.Sprintf("%d %d\n", exitCode, delaySeconds)
 	err := os.WriteFile(controlPath, []byte(content), 0644)
@@ -26,6 +31,7 @@ func writeControl(t *testing.T, dir string, exitCode int, delaySeconds int) {
 
 // Setup a dummy executable script that reads control.txt to decide exit code and sleep duration
 func setupDummyScript(t *testing.T) (string, string) {
+	t.Helper()
 	dir := t.TempDir()
 	scriptPath := filepath.Join(dir, "dummy_frpc")
 
@@ -53,12 +59,17 @@ exit "${EXIT_CODE:-0}"
 
 // Helper to poll for status to eliminate timing flakiness in tests
 func assertStatusEventually(t *testing.T, m *Manager, relayID string, expectedStatus string, timeout time.Duration) {
+	t.Helper()
 	deadline := time.Now().Add(timeout)
 	for time.Now().Before(deadline) {
 		m.mu.RLock()
 		proc, ok := m.processes[relayID]
+		var status string
+		if ok {
+			status = proc.Status
+		}
 		m.mu.RUnlock()
-		if ok && proc.Status == expectedStatus {
+		if ok && status == expectedStatus {
 			return
 		}
 		time.Sleep(50 * time.Millisecond)
@@ -77,6 +88,7 @@ func assertStatusEventually(t *testing.T, m *Manager, relayID string, expectedSt
 	t.Fatalf("expected status eventually %s, got %s (err: %s)", expectedStatus, got, errStr)
 }
 
+// assertCommandExitedEventually 等待测试自建进程退出（本测试持有其 Wait 权）。
 func assertCommandExitedEventually(t *testing.T, cmd *exec.Cmd, timeout time.Duration) {
 	t.Helper()
 
@@ -92,6 +104,22 @@ func assertCommandExitedEventually(t *testing.T, cmd *exec.Cmd, timeout time.Dur
 	}
 }
 
+// assertManagedCommandExitedEventually 探测受管进程是否已退出。不能对其调用
+// Wait —— Wait 由 Manager 拥有，测试并发 Wait 会与 os/exec 的 ctxResult
+// 通道竞争而永久挂起；Signal(0) 在进程被 Manager 收割后即报错。
+func assertManagedCommandExitedEventually(t *testing.T, cmd *exec.Cmd, timeout time.Duration) {
+	t.Helper()
+
+	deadline := time.Now().Add(timeout)
+	for time.Now().Before(deadline) {
+		if err := cmd.Process.Signal(syscall.Signal(0)); err != nil {
+			return
+		}
+		time.Sleep(50 * time.Millisecond)
+	}
+	t.Fatalf("expected managed process pid=%d to exit within %s", cmd.Process.Pid, timeout)
+}
+
 func TestStartProcessSuccess(t *testing.T) {
 	scriptPath, dir := setupDummyScript(t)
 	writeControl(t, dir, 0, 5) // exit code 0, sleep 5s
@@ -377,7 +405,7 @@ func TestStopCancelsRunningProcesses(t *testing.T) {
 	m.mu.RUnlock()
 
 	m.Stop()
-	assertCommandExitedEventually(t, cmd, 2*time.Second)
+	assertManagedCommandExitedEventually(t, cmd, 2*time.Second)
 
 	m.mu.RLock()
 	defer m.mu.RUnlock()

internal/apps/flared/heartbeat/service.go

@@ -1,3 +1,6 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
 // Package heartbeat runs the periodic flared heartbeat loop against the control plane.
 package heartbeat
 

internal/apps/flared/httpclient/client.go

@@ -1,3 +1,6 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
 // Package httpclient provides the HTTP client used by the flared agent to communicate with the Wavelet server.
 package httpclient
 

internal/apps/flared/sync/service.go

@@ -1,3 +1,6 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
 // Package sync periodically fetches and applies the active tunnel configuration.
 package sync
 

internal/apps/flared/updater/updater.go

@@ -1,3 +1,6 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
 // Package updater provides update service capabilities for flared.
 package updater
 

internal/apps/flared/wsclient/client.go

@@ -1,3 +1,6 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
 // Package wsclient provides a WebSocket client for flared control-plane communication.
 package wsclient