完善气站资源列表搜索契约

backend/api/internal/logic/gas/resource_contract.go

@@ -1,4 +1,6 @@
-package gas
+package gas
+
+import "git.apinb.com/heqiapp/platforms/backend/api/internal/logic/common"
 
 type ResourceMode string
 
@@ -10,11 +12,12 @@ const (
 )
 
 type ResourceContract struct {
-	Domain   string       `json:"domain"`
-	Name     string       `json:"name"`
-	Path     string       `json:"path"`
-	PageKind string       `json:"pageKind"`
-	Mode     ResourceMode `json:"mode"`
+	Domain       string                      `json:"domain"`
+	Name         string                      `json:"name"`
+	Path         string                      `json:"path"`
+	PageKind     string                      `json:"pageKind"`
+	Mode         ResourceMode                `json:"mode"`
+	SearchFields []common.KeywordSearchField `json:"searchFields,omitempty"`
 }
 
 func ExpectedResources() []ResourceContract {
@@ -39,6 +42,7 @@ func ExpectedResources() []ResourceContract {
 	for _, item := range items {
 		result = append(result, ResourceContract{
 			Domain: item.domain, Name: item.name, Path: "/" + item.name, PageKind: "list", Mode: item.mode,
+			SearchFields: resourceSearchFields(item.name),
 		})
 	}
 	return result

backend/api/internal/logic/gas/resource_contract_test.go

@@ -0,0 +1,20 @@
+package gas
+
+import "testing"
+
+// TestExpectedResourcesExposeExplicitSearchContract 验证支持搜索和不支持搜索的资源边界明确。
+func TestExpectedResourcesExposeExplicitSearchContract(t *testing.T) {
+	resources := ExpectedResources()
+	byName := make(map[string]ResourceContract, len(resources))
+	for _, resource := range resources {
+		byName[resource.Name] = resource
+	}
+
+	staffFields := byName["staff_account"].SearchFields
+	if len(staffFields) != 2 || staffFields[0].Key != "username" || staffFields[1].Key != "role_code" {
+		t.Fatalf("工作人员搜索字段 = %#v，期望 username、role_code", staffFields)
+	}
+	if len(byName["user_address"].SearchFields) != 0 {
+		t.Fatalf("用户地址不应公开模糊搜索字段：%#v", byName["user_address"].SearchFields)
+	}
+}

backend/api/internal/logic/gas/resource_search.go

@@ -0,0 +1,51 @@
+// Package gas 定义气站管理端各资源公开的可见字段搜索契约。
+// 版本：v1.0.0
+package gas
+
+import "git.apinb.com/heqiapp/platforms/backend/api/internal/logic/common"
+
+// gasResourceSearchFields 仅声明页面能够准确解释且服务端允许匹配的字段。
+var gasResourceSearchFields = map[string][]common.KeywordSearchField{
+	"delivery_basic":   {textSearchField("delivery_code"), textSearchField("name")},
+	"delivery_account": {textSearchField("username"), textSearchField("display_name"), enumSearchField("role_code", searchValue("admin", "配送点管理员"))},
+	"staff_account": {textSearchField("username"), enumSearchField("role_code",
+		searchValue("installer", "安装人员"), searchValue("delivery", "配送人员"), searchValue("operations", "运维人员"))},
+	"staff_credential":  {textSearchField("credential_type")},
+	"user_account":      {textSearchField("username")},
+	"gasorder_contract": {textSearchField("contract_no"), textSearchField("title")},
+	"gasorder_basic": {textSearchField("request_no"), enumSearchField("creator_type",
+		searchValue("user", "用户"), searchValue("staff", "工作人员"), searchValue("delivery", "配送站"), searchValue("gas", "气站"))},
+	"product_info":      {textSearchField("code"), textSearchField("name")},
+	"wallet_basic":      {textSearchField("owner_type")},
+	"payment_refund":    {textSearchField("refund_no")},
+	"wallet_apply_cash": {textSearchField("cash_no")},
+	"fin_settlement":    {textSearchField("settlement_no"), textSearchField("subject_type")},
+	"cs_ticket":         {textSearchField("ticket_no"), textSearchField("category"), textSearchField("priority")},
+}
+
+// resourceSearchFields 返回资源搜索契约副本；未配置资源明确不支持搜索。
+func resourceSearchFields(name string) []common.KeywordSearchField {
+	fields := gasResourceSearchFields[name]
+	result := make([]common.KeywordSearchField, 0, len(fields))
+	for _, field := range fields {
+		copied := field
+		copied.Values = append([]common.KeywordSearchValue(nil), field.Values...)
+		result = append(result, copied)
+	}
+	return result
+}
+
+// textSearchField 创建文本包含匹配字段。
+func textSearchField(key string) common.KeywordSearchField {
+	return common.KeywordSearchField{Key: key, Kind: common.KeywordSearchText}
+}
+
+// enumSearchField 创建仅按中文展示名称匹配的枚举字段。
+func enumSearchField(key string, values ...common.KeywordSearchValue) common.KeywordSearchField {
+	return common.KeywordSearchField{Key: key, Kind: common.KeywordSearchEnum, Values: values}
+}
+
+// searchValue 绑定枚举编码和页面中文名称。
+func searchValue(code, label string) common.KeywordSearchValue {
+	return common.KeywordSearchValue{Value: code, Label: label}
+}