✨ feat(agent): 添加 token 鉴权和流程文档

* 默认监听调整为 0.0.0.0:8080，并要求查询参数 token
* 支持首次 run 自动生成含随机 token 的配置文件
* 补充 HTTP 鉴权、配置校验和相关测试
* 完善代码注释，覆盖缓存、上报、服务和平台采集路径
* 新增架构与开发流程文档，补充一键构建脚本

internal/httpapi/server_test.go

@@ -10,15 +10,22 @@ import (
 	"mfd-monitor-agent/internal/status"
 )
 
+const testToken = "test-token"
+
+// withToken 为请求 URL 附加鉴权查询参数。
+func withToken(path string) string {
+	return path + "?token=" + testToken
+}
+
 // TestStatusReturnsCachedSnapshot 验证 /status 读取提供者缓存。
 func TestStatusReturnsCachedSnapshot(t *testing.T) {
 	provider := StaticProvider{Snapshot: status.HostStatus{
 		Agent: status.AgentInfo{Version: "test", SnapshotAt: time.Now(), SnapshotStatus: "ok"},
 		Host:  status.HostInfo{Hostname: "host-a"},
 	}, OK: true}
-	server := New(provider)
+	server := New(provider, testToken)
 
-	req := httptest.NewRequest(http.MethodGet, "/status", nil)
+	req := httptest.NewRequest(http.MethodGet, withToken("/status"), nil)
 	rec := httptest.NewRecorder()
 	server.ServeHTTP(rec, req)
 
@@ -39,9 +46,9 @@ func TestHealthReportsSnapshotMetadata(t *testing.T) {
 	provider := StaticProvider{Snapshot: status.HostStatus{
 		Agent: status.AgentInfo{Version: "test", SnapshotAt: time.Unix(10, 0), SnapshotStatus: "partial"},
 	}, OK: true}
-	server := New(provider)
+	server := New(provider, testToken)
 
-	req := httptest.NewRequest(http.MethodGet, "/health", nil)
+	req := httptest.NewRequest(http.MethodGet, withToken("/health"), nil)
 	rec := httptest.NewRecorder()
 	server.ServeHTTP(rec, req)
 
@@ -59,9 +66,9 @@ func TestHealthReportsSnapshotMetadata(t *testing.T) {
 
 // TestStatusReturnsServiceUnavailableBeforeSnapshot 验证 /status 不会在请求时实时采集。
 func TestStatusReturnsServiceUnavailableBeforeSnapshot(t *testing.T) {
-	server := New(StaticProvider{OK: false})
+	server := New(StaticProvider{OK: false}, testToken)
 
-	req := httptest.NewRequest(http.MethodGet, "/status", nil)
+	req := httptest.NewRequest(http.MethodGet, withToken("/status"), nil)
 	rec := httptest.NewRecorder()
 	server.ServeHTTP(rec, req)
 
@@ -72,9 +79,9 @@ func TestStatusReturnsServiceUnavailableBeforeSnapshot(t *testing.T) {
 
 // TestHealthReturnsStartingBeforeSnapshot 验证 /health 在启动阶段暴露 starting 状态。
 func TestHealthReturnsStartingBeforeSnapshot(t *testing.T) {
-	server := New(StaticProvider{OK: false})
+	server := New(StaticProvider{OK: false}, testToken)
 
-	req := httptest.NewRequest(http.MethodGet, "/health", nil)
+	req := httptest.NewRequest(http.MethodGet, withToken("/health"), nil)
 	rec := httptest.NewRecorder()
 	server.ServeHTTP(rec, req)
 
@@ -92,9 +99,9 @@ func TestHealthReturnsStartingBeforeSnapshot(t *testing.T) {
 
 // TestStatusRejectsNonGET 验证 /status 仅接受 GET 请求。
 func TestStatusRejectsNonGET(t *testing.T) {
-	server := New(StaticProvider{OK: true})
+	server := New(StaticProvider{OK: true}, testToken)
 
-	req := httptest.NewRequest(http.MethodPost, "/status", nil)
+	req := httptest.NewRequest(http.MethodPost, withToken("/status"), nil)
 	rec := httptest.NewRecorder()
 	server.ServeHTTP(rec, req)
 
@@ -105,9 +112,9 @@ func TestStatusRejectsNonGET(t *testing.T) {
 
 // TestHealthRejectsNonGET 验证 /health 仅接受 GET 请求。
 func TestHealthRejectsNonGET(t *testing.T) {
-	server := New(StaticProvider{OK: true})
+	server := New(StaticProvider{OK: true}, testToken)
 
-	req := httptest.NewRequest(http.MethodPost, "/health", nil)
+	req := httptest.NewRequest(http.MethodPost, withToken("/health"), nil)
 	rec := httptest.NewRecorder()
 	server.ServeHTTP(rec, req)
 
@@ -115,3 +122,29 @@ func TestHealthRejectsNonGET(t *testing.T) {
 		t.Fatalf("status code = %d", rec.Code)
 	}
 }
+
+// TestMissingTokenReturnsUnauthorized 验证缺少 token 时返回 401。
+func TestMissingTokenReturnsUnauthorized(t *testing.T) {
+	server := New(StaticProvider{OK: true}, testToken)
+
+	req := httptest.NewRequest(http.MethodGet, "/status", nil)
+	rec := httptest.NewRecorder()
+	server.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusUnauthorized {
+		t.Fatalf("status code = %d", rec.Code)
+	}
+}
+
+// TestWrongTokenReturnsUnauthorized 验证错误 token 时返回 401。
+func TestWrongTokenReturnsUnauthorized(t *testing.T) {
+	server := New(StaticProvider{OK: true}, testToken)
+
+	req := httptest.NewRequest(http.MethodGet, "/status?token=wrong", nil)
+	rec := httptest.NewRecorder()
+	server.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusUnauthorized {
+		t.Fatalf("status code = %d", rec.Code)
+	}
+}