pangolin/server/internal/usage/contract_test.go

package usage

// contract_test.go — HTTP 契约快照(支柱 2:契约单源)。
//
// 冻结 /v1/usage(UsagePoint)与 /v1/usage/devices(deviceUsageResponse + DeviceUsagePoint)
// 的字段面。改字段会让本测试失败,逼同步客户端 model + 文档。
//
// ⚠️ 与客户端冻结集对账:client/test/contract/api_contract_test.dart 的
// _frozenUsagePointKeys / _frozenDeviceUsageKeys。两端必须一致。

import (
	"reflect"
	"strings"
	"testing"
)

func jsonTagSet(v any) map[string]struct{} {
	t := reflect.TypeOf(v)
	if t.Kind() == reflect.Ptr {
		t = t.Elem()
	}
	set := map[string]struct{}{}
	for i := 0; i < t.NumField(); i++ {
		tag := t.Field(i).Tag.Get("json")
		if tag == "" || tag == "-" {
			continue
		}
		name := strings.SplitN(tag, ",", 2)[0]
		if name != "" {
			set[name] = struct{}{}
		}
	}
	return set
}

func assertFrozenKeys(t *testing.T, name string, got map[string]struct{}, want ...string) {
	t.Helper()
	wantSet := make(map[string]struct{}, len(want))
	for _, k := range want {
		wantSet[k] = struct{}{}
	}
	for k := range got {
		if _, ok := wantSet[k]; !ok {
			t.Errorf("%s: 出现未冻结字段 %q —— 改契约需同步另一端(客户端 model)+ 文档", name, k)
		}
	}
	for _, k := range want {
		if _, ok := got[k]; !ok {
			t.Errorf("%s: 缺失冻结字段 %q", name, k)
		}
	}
}

func TestContractUsagePoint(t *testing.T) {
	assertFrozenKeys(t, "/v1/usage UsagePoint", jsonTagSet(UsagePoint{}),
		"date", "bytes_up", "bytes_down", "minutes_used",
	)
}

// 注:/v1/usage/devices(DeviceUsagePoint + deviceUsageResponse)契约待 stats-overhaul
// 合并后补——这两个 struct 当前是未提交 WIP,引用它们会让 CI 编译失败。