mcp接口增加分页

internal/service/spatial_test.go

@@ -13,9 +13,9 @@ import (
 func TestSpatialServiceSearchesUserConfirmablePlaceCandidates(t *testing.T) {
 	var captured domain.PlaceSearchQuery
 	repository := &fakeSpatialRepository{
-		places: func(_ context.Context, query domain.PlaceSearchQuery) ([]domain.PlaceCandidate, error) {
+		places: func(_ context.Context, query domain.PlaceSearchQuery) (domain.Page[domain.PlaceCandidate], error) {
 			captured = query
-			return []domain.PlaceCandidate{{
+			return domain.Page[domain.PlaceCandidate]{Items: []domain.PlaceCandidate{{
 				SourceRecordID: "station-1",
 				PlaceType:      "fire_check_station",
 				Name:           "观水检查站",
@@ -23,7 +23,7 @@ func TestSpatialServiceSearchesUserConfirmablePlaceCandidates(t *testing.T) {
 				MatchedText:    "观水检查站",
 				MatchKind:      "partial",
 				LocationKind:   "recorded_point",
-			}}, nil
+			}}, TotalCount: 1}, nil
 		},
 	}
 	spatial, err := NewSpatialService(repository, domain.SpatialScope{AllTowns: true}, time.Second)
@@ -31,11 +31,11 @@ func TestSpatialServiceSearchesUserConfirmablePlaceCandidates(t *testing.T) {
 		t.Fatalf("NewSpatialService() error = %v", err)
 	}
 
-	result, err := spatial.SearchPlaceCandidates(context.Background(), " 观水 ", 0)
+	result, err := spatial.SearchPlaceCandidates(context.Background(), " 观水 ", 0, 0)
 	if err != nil {
 		t.Fatalf("SearchPlaceCandidates() error = %v", err)
 	}
-	if captured.PlaceName != "观水" || captured.Limit != 10 || !captured.Scope.AllTowns {
+	if captured.PlaceName != "观水" || captured.Limit != 10 || captured.Offset != 0 || !captured.Scope.AllTowns {
 		t.Fatalf("captured query = %#v", captured)
 	}
 	if result.Status != "ok" || result.Metadata.ResultCount != 1 || len(result.Data) != 1 {
@@ -71,7 +71,7 @@ func TestSpatialServiceRejectsInvalidPlaceSearch(t *testing.T) {
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			_, err := spatial.SearchPlaceCandidates(context.Background(), tt.placeName, tt.limit)
+			_, err := spatial.SearchPlaceCandidates(context.Background(), tt.placeName, tt.limit, 0)
 			if !errors.Is(err, ErrInvalidArgument) {
 				t.Fatalf("error = %v, want ErrInvalidArgument", err)
 			}
@@ -82,9 +82,9 @@ func TestSpatialServiceRejectsInvalidPlaceSearch(t *testing.T) {
 func TestSpatialServiceUsesTrustedScopeAndDefaults(t *testing.T) {
 	var captured domain.NearbyQuery
 	repository := &fakeSpatialRepository{
-		water: func(_ context.Context, query domain.NearbyQuery) ([]domain.WaterSource, error) {
+		water: func(_ context.Context, query domain.NearbyQuery) (domain.Page[domain.WaterSource], error) {
 			captured = query
-			return []domain.WaterSource{{SourceRecordID: "152", Category: "water_source"}}, nil
+			return domain.Page[domain.WaterSource]{Items: []domain.WaterSource{{SourceRecordID: "152", Category: "water_source"}}, TotalCount: 1}, nil
 		},
 	}
 	towns := []string{"莒格庄镇"}
@@ -96,7 +96,7 @@ func TestSpatialServiceUsesTrustedScopeAndDefaults(t *testing.T) {
 	fixedNow := time.Date(2026, 9, 4, 8, 30, 0, 0, time.FixedZone("CST", 8*60*60))
 	spatial.now = func() time.Time { return fixedNow }
 
-	result, err := spatial.FindNearbyWaterSources(context.Background(), domain.Coordinate{Longitude: 121.75, Latitude: 37.19}, 0, 0)
+	result, err := spatial.FindNearbyWaterSources(context.Background(), domain.Coordinate{Longitude: 121.75, Latitude: 37.19}, 0, 0, 0)
 	if err != nil {
 		t.Fatalf("FindNearbyWaterSources() error = %v", err)
 	}
@@ -126,9 +126,9 @@ func TestSpatialServiceUsesTrustedScopeAndDefaults(t *testing.T) {
 func TestSpatialServiceUsesAllTownsScope(t *testing.T) {
 	var captured domain.NearbyQuery
 	repository := &fakeSpatialRepository{
-		water: func(_ context.Context, query domain.NearbyQuery) ([]domain.WaterSource, error) {
+		water: func(_ context.Context, query domain.NearbyQuery) (domain.Page[domain.WaterSource], error) {
 			captured = query
-			return []domain.WaterSource{}, nil
+			return domain.Page[domain.WaterSource]{Items: []domain.WaterSource{}}, nil
 		},
 	}
 	spatial, err := NewSpatialService(repository, domain.SpatialScope{AllTowns: true}, time.Second)
@@ -136,7 +136,7 @@ func TestSpatialServiceUsesAllTownsScope(t *testing.T) {
 		t.Fatalf("NewSpatialService() error = %v", err)
 	}
 
-	result, err := spatial.FindNearbyWaterSources(context.Background(), domain.Coordinate{Longitude: 121.75, Latitude: 37.19}, 100, 1)
+	result, err := spatial.FindNearbyWaterSources(context.Background(), domain.Coordinate{Longitude: 121.75, Latitude: 37.19}, 100, 1, 0)
 	if err != nil {
 		t.Fatalf("FindNearbyWaterSources() error = %v", err)
 	}
@@ -171,18 +171,132 @@ func TestSpatialServiceReturnsExplicitNoResults(t *testing.T) {
 		t.Fatalf("NewSpatialService() error = %v", err)
 	}
 
-	result, err := spatial.ResolveIncidentContext(context.Background(), domain.Coordinate{Longitude: 121, Latitude: 37})
+	result, err := spatial.ResolveIncidentContext(context.Background(), domain.Coordinate{Longitude: 121, Latitude: 37}, 0, 0)
 	if err != nil {
 		t.Fatalf("ResolveIncidentContext() error = %v", err)
 	}
-	if result.Status != "no_results" || result.Data == nil || len(result.Data) != 0 || result.Metadata.ResultCount != 0 {
+	if result.Status != "no_results" || result.Data == nil || len(result.Data) != 0 || result.Metadata.ResultCount != 0 || result.Metadata.TotalCount != 0 {
 		t.Fatalf("unexpected no-results response: %#v", result)
 	}
+	if result.Metadata.Limit != 20 || result.Metadata.Offset != 0 || result.Metadata.HasMore || result.Metadata.NextOffset != nil {
+		t.Fatalf("unexpected no-results pagination metadata: %#v", result.Metadata)
+	}
 	if len(result.Warnings) == 0 {
 		t.Fatal("no-results response must retain data-quality warnings")
 	}
 }
 
+func TestSpatialServiceUsesPointQueryPaginationDefaults(t *testing.T) {
+	var captured domain.PointQuery
+	repository := &fakeSpatialRepository{
+		resolve: func(_ context.Context, query domain.PointQuery) (domain.Page[domain.IncidentContext], error) {
+			captured = query
+			return domain.Page[domain.IncidentContext]{Items: []domain.IncidentContext{{GridID: "2897"}}, TotalCount: 1}, nil
+		},
+	}
+	spatial, err := NewSpatialService(repository, domain.SpatialScope{AllowedTowns: []string{"文化街道"}}, time.Second)
+	if err != nil {
+		t.Fatalf("NewSpatialService() error = %v", err)
+	}
+
+	result, err := spatial.ResolveIncidentContext(context.Background(), domain.Coordinate{Longitude: 121.6, Latitude: 37.3}, 0, 0)
+	if err != nil {
+		t.Fatalf("ResolveIncidentContext() error = %v", err)
+	}
+	if captured.Limit != 20 || captured.Offset != 0 || captured.Point.Longitude != 121.6 {
+		t.Fatalf("captured query = %#v", captured)
+	}
+	if captured.Scope.AllTowns || len(captured.Scope.AllowedTowns) != 1 || captured.Scope.AllowedTowns[0] != "文化街道" {
+		t.Fatalf("captured scope = %#v", captured.Scope)
+	}
+	if result.Metadata.Limit != 20 || result.Metadata.Offset != 0 || result.Metadata.TotalCount != 1 {
+		t.Fatalf("metadata = %#v", result.Metadata)
+	}
+}
+
+func TestSpatialServiceReturnsPaginationMetadata(t *testing.T) {
+	tests := []struct {
+		name           string
+		offset         int
+		items          []domain.WaterSource
+		totalCount     int64
+		wantStatus     string
+		wantHasMore    bool
+		wantNextOffset *int
+	}{
+		{name: "first page", offset: 0, items: make([]domain.WaterSource, 10), totalCount: 25, wantStatus: statusOK, wantHasMore: true, wantNextOffset: intPointer(10)},
+		{name: "last page", offset: 20, items: make([]domain.WaterSource, 5), totalCount: 25, wantStatus: statusOK},
+		{name: "past last page", offset: 30, items: []domain.WaterSource{}, totalCount: 25, wantStatus: statusOK},
+		{name: "no matches", offset: 0, items: nil, totalCount: 0, wantStatus: statusNoResults},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			var captured domain.NearbyQuery
+			repository := &fakeSpatialRepository{
+				water: func(_ context.Context, query domain.NearbyQuery) (domain.Page[domain.WaterSource], error) {
+					captured = query
+					return domain.Page[domain.WaterSource]{Items: tt.items, TotalCount: tt.totalCount}, nil
+				},
+			}
+			spatial, err := NewSpatialService(repository, domain.SpatialScope{AllTowns: true}, time.Second)
+			if err != nil {
+				t.Fatalf("NewSpatialService() error = %v", err)
+			}
+
+			result, err := spatial.FindNearbyWaterSources(context.Background(), domain.Coordinate{Longitude: 121, Latitude: 37}, 100, 10, tt.offset)
+			if err != nil {
+				t.Fatalf("FindNearbyWaterSources() error = %v", err)
+			}
+			if captured.Limit != 10 || captured.Offset != tt.offset {
+				t.Fatalf("captured query = %#v", captured)
+			}
+			metadata := result.Metadata
+			if result.Status != tt.wantStatus || metadata.ResultCount != len(tt.items) || metadata.TotalCount != tt.totalCount || metadata.Limit != 10 || metadata.Offset != tt.offset || metadata.HasMore != tt.wantHasMore {
+				t.Fatalf("result = %#v", result)
+			}
+			if (metadata.NextOffset == nil) != (tt.wantNextOffset == nil) || metadata.NextOffset != nil && *metadata.NextOffset != *tt.wantNextOffset {
+				t.Fatalf("next_offset = %#v, want %#v", metadata.NextOffset, tt.wantNextOffset)
+			}
+			if result.Data == nil {
+				t.Fatal("data must serialize as an array, not null")
+			}
+		})
+	}
+}
+
+func TestSpatialServiceValidatesPaginationBounds(t *testing.T) {
+	spatial, err := NewSpatialService(&fakeSpatialRepository{}, domain.SpatialScope{AllTowns: true}, time.Second)
+	if err != nil {
+		t.Fatalf("NewSpatialService() error = %v", err)
+	}
+	point := domain.Coordinate{Longitude: 121, Latitude: 37}
+	tests := []struct {
+		name string
+		call func() error
+	}{
+		{name: "negative offset", call: func() error {
+			_, err := spatial.SearchPlaceCandidates(context.Background(), "观水镇", 10, -1)
+			return err
+		}},
+		{name: "offset too large", call: func() error {
+			_, err := spatial.GetResponsibleUnits(context.Background(), point, 20, MaxPageOffset+1)
+			return err
+		}},
+		{name: "negative limit", call: func() error { _, err := spatial.ResolveIncidentContext(context.Background(), point, -1, 0); return err }},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if err := tt.call(); !errors.Is(err, ErrInvalidArgument) {
+				t.Fatalf("error = %v, want ErrInvalidArgument", err)
+			}
+		})
+	}
+
+	if _, err := spatial.FindNearbyRiskAreas(context.Background(), point, 100, 20, MaxPageOffset); err != nil {
+		t.Fatalf("maximum offset must be accepted: %v", err)
+	}
+}
+
 func TestSpatialServiceRejectsUnboundedInputs(t *testing.T) {
 	repository := &fakeSpatialRepository{}
 	spatial, err := NewSpatialService(repository, domain.SpatialScope{AllowedTowns: []string{"高陵镇"}}, time.Second)
@@ -197,28 +311,28 @@ func TestSpatialServiceRejectsUnboundedInputs(t *testing.T) {
 		{
 			name: "longitude",
 			call: func() error {
-				_, err := spatial.ResolveIncidentContext(context.Background(), domain.Coordinate{Longitude: 181, Latitude: 37})
+				_, err := spatial.ResolveIncidentContext(context.Background(), domain.Coordinate{Longitude: 181, Latitude: 37}, 1, 0)
 				return err
 			},
 		},
 		{
 			name: "water radius",
 			call: func() error {
-				_, err := spatial.FindNearbyWaterSources(context.Background(), domain.Coordinate{Longitude: 121, Latitude: 37}, 30_001, 1)
+				_, err := spatial.FindNearbyWaterSources(context.Background(), domain.Coordinate{Longitude: 121, Latitude: 37}, 30_001, 1, 0)
 				return err
 			},
 		},
 		{
 			name: "access radius",
 			call: func() error {
-				_, err := spatial.ListNearbyAccessLines(context.Background(), domain.Coordinate{Longitude: 121, Latitude: 37}, 10_001, 1)
+				_, err := spatial.ListNearbyAccessLines(context.Background(), domain.Coordinate{Longitude: 121, Latitude: 37}, 10_001, 1, 0)
 				return err
 			},
 		},
 		{
 			name: "limit",
 			call: func() error {
-				_, err := spatial.FindNearbyRiskAreas(context.Background(), domain.Coordinate{Longitude: 121, Latitude: 37}, 100, 21)
+				_, err := spatial.FindNearbyRiskAreas(context.Background(), domain.Coordinate{Longitude: 121, Latitude: 37}, 100, 21, 0)
 				return err
 			},
 		},
@@ -235,14 +349,14 @@ func TestSpatialServiceRejectsUnboundedInputs(t *testing.T) {
 func TestSpatialServiceClassifiesRepositoryFailures(t *testing.T) {
 	t.Run("data source", func(t *testing.T) {
 		spatial, err := NewSpatialService(&fakeSpatialRepository{
-			water: func(context.Context, domain.NearbyQuery) ([]domain.WaterSource, error) {
-				return nil, errors.New("driver detail must stay internal")
+			water: func(context.Context, domain.NearbyQuery) (domain.Page[domain.WaterSource], error) {
+				return domain.Page[domain.WaterSource]{}, errors.New("driver detail must stay internal")
 			},
 		}, domain.SpatialScope{AllowedTowns: []string{"高陵镇"}}, time.Second)
 		if err != nil {
 			t.Fatalf("NewSpatialService() error = %v", err)
 		}
-		_, err = spatial.FindNearbyWaterSources(context.Background(), domain.Coordinate{Longitude: 121, Latitude: 37}, 100, 1)
+		_, err = spatial.FindNearbyWaterSources(context.Background(), domain.Coordinate{Longitude: 121, Latitude: 37}, 100, 1, 0)
 		if !errors.Is(err, ErrDataSourceUnavailable) {
 			t.Fatalf("error = %v, want ErrDataSourceUnavailable", err)
 		}
@@ -250,15 +364,15 @@ func TestSpatialServiceClassifiesRepositoryFailures(t *testing.T) {
 
 	t.Run("timeout", func(t *testing.T) {
 		spatial, err := NewSpatialService(&fakeSpatialRepository{
-			water: func(ctx context.Context, _ domain.NearbyQuery) ([]domain.WaterSource, error) {
+			water: func(ctx context.Context, _ domain.NearbyQuery) (domain.Page[domain.WaterSource], error) {
 				<-ctx.Done()
-				return nil, ctx.Err()
+				return domain.Page[domain.WaterSource]{}, ctx.Err()
 			},
 		}, domain.SpatialScope{AllowedTowns: []string{"高陵镇"}}, 5*time.Millisecond)
 		if err != nil {
 			t.Fatalf("NewSpatialService() error = %v", err)
 		}
-		_, err = spatial.FindNearbyWaterSources(context.Background(), domain.Coordinate{Longitude: 121, Latitude: 37}, 100, 1)
+		_, err = spatial.FindNearbyWaterSources(context.Background(), domain.Coordinate{Longitude: 121, Latitude: 37}, 100, 1, 0)
 		if !errors.Is(err, ErrQueryTimeout) {
 			t.Fatalf("error = %v, want ErrQueryTimeout", err)
 		}
@@ -274,61 +388,65 @@ func containsString(values []string, target string) bool {
 	return false
 }
 
-type fakeSpatialRepository struct {
-	places      func(context.Context, domain.PlaceSearchQuery) ([]domain.PlaceCandidate, error)
-	resolve     func(context.Context, domain.Coordinate, domain.SpatialScope) ([]domain.IncidentContext, error)
-	water       func(context.Context, domain.NearbyQuery) ([]domain.WaterSource, error)
-	commandPost func(context.Context, domain.NearbyQuery) ([]domain.CommandPostCandidate, error)
-	access      func(context.Context, domain.NearbyQuery) ([]domain.AccessLine, error)
-	units       func(context.Context, domain.Coordinate, domain.SpatialScope) ([]domain.ResponsibleUnit, error)
-	risks       func(context.Context, domain.NearbyQuery) ([]domain.RiskArea, error)
+func intPointer(value int) *int {
+	return &value
 }
 
-func (f *fakeSpatialRepository) SearchPlaceCandidates(ctx context.Context, query domain.PlaceSearchQuery) ([]domain.PlaceCandidate, error) {
+type fakeSpatialRepository struct {
+	places      func(context.Context, domain.PlaceSearchQuery) (domain.Page[domain.PlaceCandidate], error)
+	resolve     func(context.Context, domain.PointQuery) (domain.Page[domain.IncidentContext], error)
+	water       func(context.Context, domain.NearbyQuery) (domain.Page[domain.WaterSource], error)
+	commandPost func(context.Context, domain.NearbyQuery) (domain.Page[domain.CommandPostCandidate], error)
+	access      func(context.Context, domain.NearbyQuery) (domain.Page[domain.AccessLine], error)
+	units       func(context.Context, domain.PointQuery) (domain.Page[domain.ResponsibleUnit], error)
+	risks       func(context.Context, domain.NearbyQuery) (domain.Page[domain.RiskArea], error)
+}
+
+func (f *fakeSpatialRepository) SearchPlaceCandidates(ctx context.Context, query domain.PlaceSearchQuery) (domain.Page[domain.PlaceCandidate], error) {
 	if f.places == nil {
-		return []domain.PlaceCandidate{}, nil
+		return domain.Page[domain.PlaceCandidate]{Items: []domain.PlaceCandidate{}}, nil
 	}
 	return f.places(ctx, query)
 }
 
-func (f *fakeSpatialRepository) ResolveIncidentContext(ctx context.Context, point domain.Coordinate, scope domain.SpatialScope) ([]domain.IncidentContext, error) {
+func (f *fakeSpatialRepository) ResolveIncidentContext(ctx context.Context, query domain.PointQuery) (domain.Page[domain.IncidentContext], error) {
 	if f.resolve == nil {
-		return []domain.IncidentContext{}, nil
+		return domain.Page[domain.IncidentContext]{Items: []domain.IncidentContext{}}, nil
 	}
-	return f.resolve(ctx, point, scope)
+	return f.resolve(ctx, query)
 }
 
-func (f *fakeSpatialRepository) FindNearbyWaterSources(ctx context.Context, query domain.NearbyQuery) ([]domain.WaterSource, error) {
+func (f *fakeSpatialRepository) FindNearbyWaterSources(ctx context.Context, query domain.NearbyQuery) (domain.Page[domain.WaterSource], error) {
 	if f.water == nil {
-		return []domain.WaterSource{}, nil
+		return domain.Page[domain.WaterSource]{Items: []domain.WaterSource{}}, nil
 	}
 	return f.water(ctx, query)
 }
 
-func (f *fakeSpatialRepository) FindCommandPostCandidates(ctx context.Context, query domain.NearbyQuery) ([]domain.CommandPostCandidate, error) {
+func (f *fakeSpatialRepository) FindCommandPostCandidates(ctx context.Context, query domain.NearbyQuery) (domain.Page[domain.CommandPostCandidate], error) {
 	if f.commandPost == nil {
-		return []domain.CommandPostCandidate{}, nil
+		return domain.Page[domain.CommandPostCandidate]{Items: []domain.CommandPostCandidate{}}, nil
 	}
 	return f.commandPost(ctx, query)
 }
 
-func (f *fakeSpatialRepository) ListNearbyAccessLines(ctx context.Context, query domain.NearbyQuery) ([]domain.AccessLine, error) {
+func (f *fakeSpatialRepository) ListNearbyAccessLines(ctx context.Context, query domain.NearbyQuery) (domain.Page[domain.AccessLine], error) {
 	if f.access == nil {
-		return []domain.AccessLine{}, nil
+		return domain.Page[domain.AccessLine]{Items: []domain.AccessLine{}}, nil
 	}
 	return f.access(ctx, query)
 }
 
-func (f *fakeSpatialRepository) GetResponsibleUnits(ctx context.Context, point domain.Coordinate, scope domain.SpatialScope) ([]domain.ResponsibleUnit, error) {
+func (f *fakeSpatialRepository) GetResponsibleUnits(ctx context.Context, query domain.PointQuery) (domain.Page[domain.ResponsibleUnit], error) {
 	if f.units == nil {
-		return []domain.ResponsibleUnit{}, nil
+		return domain.Page[domain.ResponsibleUnit]{Items: []domain.ResponsibleUnit{}}, nil
 	}
-	return f.units(ctx, point, scope)
+	return f.units(ctx, query)
 }
 
-func (f *fakeSpatialRepository) FindNearbyRiskAreas(ctx context.Context, query domain.NearbyQuery) ([]domain.RiskArea, error) {
+func (f *fakeSpatialRepository) FindNearbyRiskAreas(ctx context.Context, query domain.NearbyQuery) (domain.Page[domain.RiskArea], error) {
 	if f.risks == nil {
-		return []domain.RiskArea{}, nil
+		return domain.Page[domain.RiskArea]{Items: []domain.RiskArea{}}, nil
 	}
 	return f.risks(ctx, query)
 }