feat(t224): add incremental freight sync

backend-api/internal/platform/erpconnector/client.go

@@ -57,11 +57,33 @@ func New(baseURL, apiKey string, timeout time.Duration) (*Client, error) {
 func (client *Client) QueryOrder(
 	ctx context.Context,
 	orderNumber string,
+) (domain.FreightSourceBatch, error) {
+	return client.query(ctx, map[string]string{
+		"mode":         domain.FreightSyncOrderNumber,
+		"order_number": orderNumber,
+	}, domain.FreightSyncOrderNumber, "", "")
+}
+
+func (client *Client) QueryCreatedRange(
+	ctx context.Context,
+	createdFrom, createdTo string,
+) (domain.FreightSourceBatch, error) {
+	return client.query(ctx, map[string]string{
+		"mode":         domain.FreightSyncCreatedRange,
+		"created_from": createdFrom,
+		"created_to":   createdTo,
+	}, domain.FreightSyncCreatedRange, createdFrom, createdTo)
+}
+
+func (client *Client) query(
+	ctx context.Context,
+	payload map[string]string,
+	expectedMode, expectedFrom, expectedTo string,
 ) (domain.FreightSourceBatch, error) {
 	if client.apiKey == "" {
 		return domain.FreightSourceBatch{}, ErrNotConfigured
 	}
-	body, err := json.Marshal(map[string]string{"order_number": orderNumber})
+	body, err := json.Marshal(payload)
 	if err != nil {
 		return domain.FreightSourceBatch{}, ErrProtocol
 	}
@@ -106,9 +128,19 @@ func (client *Client) QueryOrder(
 	if err := decoder.Decode(&extra); !errors.Is(err, io.EOF) {
 		return domain.FreightSourceBatch{}, ErrProtocol
 	}
-	if result.SchemaVersion != 1 || result.Query.Mode != "ORDER_NUMBER" ||
+	if result.SchemaVersion != 1 || result.Query.Mode != expectedMode ||
 		result.Orders == nil {
 		return domain.FreightSourceBatch{}, ErrProtocol
 	}
+	if expectedMode == domain.FreightSyncOrderNumber {
+		if result.Query.CreatedFrom != nil || result.Query.CreatedTo != nil {
+			return domain.FreightSourceBatch{}, ErrProtocol
+		}
+	} else if result.Query.CreatedFrom == nil ||
+		result.Query.CreatedTo == nil ||
+		*result.Query.CreatedFrom != expectedFrom ||
+		*result.Query.CreatedTo != expectedTo {
+		return domain.FreightSourceBatch{}, ErrProtocol
+	}
 	return result, nil
 }

backend-api/internal/platform/erpconnector/client_test.go

@@ -2,6 +2,7 @@ package erpconnector
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
 	"net/http"
 	"net/http/httptest"
@@ -61,6 +62,85 @@ func TestQueryOrderAcceptsAllowlistResponse(t *testing.T) {
 	}
 }
 
+func TestQueryCreatedRangeUsesStrictContract(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(
+		writer http.ResponseWriter,
+		request *http.Request,
+	) {
+		var body map[string]string
+		if err := json.NewDecoder(request.Body).Decode(&body); err != nil {
+			t.Fatalf("decode request: %v", err)
+		}
+		if body["mode"] != "CREATED_RANGE" ||
+			body["created_from"] != "2026-07-22" ||
+			body["created_to"] != "2026-07-28" ||
+			len(body) != 3 {
+			t.Fatalf("request body = %#v", body)
+		}
+		writer.Header().Set("Content-Type", "application/json")
+		_, _ = writer.Write([]byte(`{
+			"schema_version":1,
+			"query":{
+				"mode":"CREATED_RANGE",
+				"created_from":"2026-07-22",
+				"created_to":"2026-07-28"
+			},
+			"orders":[]
+		}`))
+	}))
+	defer server.Close()
+	client, _ := New(
+		server.URL,
+		"12345678901234567890123456789012",
+		time.Second,
+	)
+
+	result, err := client.QueryCreatedRange(
+		context.Background(),
+		"2026-07-22",
+		"2026-07-28",
+	)
+
+	if err != nil || result.Query.CreatedFrom == nil ||
+		*result.Query.CreatedFrom != "2026-07-22" {
+		t.Fatalf("QueryCreatedRange() = %+v, %v", result, err)
+	}
+}
+
+func TestQueryCreatedRangeRejectsMismatchedResponseWindow(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(
+		writer http.ResponseWriter,
+		_ *http.Request,
+	) {
+		writer.Header().Set("Content-Type", "application/json")
+		_, _ = writer.Write([]byte(`{
+			"schema_version":1,
+			"query":{
+				"mode":"CREATED_RANGE",
+				"created_from":"2026-07-21",
+				"created_to":"2026-07-28"
+			},
+			"orders":[]
+		}`))
+	}))
+	defer server.Close()
+	client, _ := New(
+		server.URL,
+		"12345678901234567890123456789012",
+		time.Second,
+	)
+
+	_, err := client.QueryCreatedRange(
+		context.Background(),
+		"2026-07-22",
+		"2026-07-28",
+	)
+
+	if !errors.Is(err, ErrProtocol) {
+		t.Fatalf("QueryCreatedRange() error = %v", err)
+	}
+}
+
 func TestQueryOrderRejectsUnexpectedPIIField(t *testing.T) {
 	server := httptest.NewServer(http.HandlerFunc(func(
 		writer http.ResponseWriter,