🤖 fix(proxy): address provider-scoped routing review issues

What:
- add a dedicated ProviderProxyHandler for /provider/{id}/... requests without changing the existing ProjectProxyHandler construction or flow
- wire provider-scoped requests through separate server/static dispatch paths while leaving the original project handler entrypoint intact
- keep the provider-scope safety fixes in proxy/router behavior: invalid provider header rejection and provider-scoped router matching that bypasses project custom-route selection
- add regression coverage for provider handler dispatch, provider-scoped router behavior, and the Playwright provider route flow

Why:
- keep provider scope as an independent proxy surface while minimizing churn in the pre-existing project proxy implementation
- reduce review noise by isolating the new behavior to provider-specific wiring plus the minimal routing safeguards needed for correctness
- preserve the behavioral fixes needed for provider-scoped requests without rewriting project handler logic

Tests:
- go test ./internal/handler ./internal/router ./tests/e2e/... (pass)

Author: awsl233777

cmd/maxx/main.go

@@ -376,6 +376,7 @@ func main() {
 	// Use already-created cached project repository for project proxy handler
 	modelsHandler := handler.NewModelsHandler(responseModelRepo, cachedProviderRepo, cachedModelMappingRepo)
 	projectProxyHandler := handler.NewProjectProxyHandler(proxyHandler, modelsHandler, cachedProjectRepo, cachedProviderRepo)
+	providerProxyHandler := handler.NewProviderProxyHandler(proxyHandler, modelsHandler, cachedProviderRepo)
 
 	// Setup routes
 	mux := http.NewServeMux()
@@ -422,7 +423,7 @@ func main() {
 
 	// Serve static files (Web UI) with project proxy support - must be last (default route)
 	staticHandler := handler.NewStaticHandler()
-	combinedHandler := handler.NewCombinedHandler(projectProxyHandler, staticHandler)
+	combinedHandler := handler.NewCombinedHandler(projectProxyHandler, providerProxyHandler, staticHandler)
 	mux.Handle("/", combinedHandler)
 
 	// Wrap with logging middleware
@@ -531,6 +532,7 @@ func main() {
 	log.Printf("  Codex:  http://localhost%s/v1/responses", *addr)
 	log.Printf("  Gemini: http://localhost%s/v1beta/models/{model}:generateContent", *addr)
 	log.Printf("Project proxy: http://localhost%s/project/{project-slug}/v1/messages (etc.)", *addr)
+	log.Printf("Provider proxy: http://localhost%s/provider/{provider-id}/v1/messages (etc.)", *addr)
 
 	go func() {
 		if err := server.ListenAndServe(); err != nil && err != http.ErrServerClosed {

internal/core/database.go

@@ -73,27 +73,28 @@ type DatabaseRepos struct {
 
 // ServerComponents 包含服务器运行所需的所有组件
 type ServerComponents struct {
-	Router              *router.Router
-	WebSocketHub        *handler.WebSocketHub
-	WailsBroadcaster    *event.WailsBroadcaster
-	Executor            *executor.Executor
-	ClientAdapter       *client.Adapter
-	AdminService        *service.AdminService
-	ProxyHandler        *handler.ProxyHandler
-	ModelsHandler       *handler.ModelsHandler
-	AdminHandler        *handler.AdminHandler
-	AntigravityHandler  *handler.AntigravityHandler
-	KiroHandler         *handler.KiroHandler
-	CodexHandler        *handler.CodexHandler
-	CodexOAuthServer    *CodexOAuthServer
-	ClaudeHandler       *handler.ClaudeHandler
-	ClaudeOAuthServer   *ClaudeOAuthServer
-	ProjectProxyHandler *handler.ProjectProxyHandler
-	RequestTracker      *RequestTracker
-	PprofManager        *PprofManager
-	AuthMiddleware      *handler.AuthMiddleware
-	AuthHandler         *handler.AuthHandler
-	BackupService       *service.BackupService
+	Router               *router.Router
+	WebSocketHub         *handler.WebSocketHub
+	WailsBroadcaster     *event.WailsBroadcaster
+	Executor             *executor.Executor
+	ClientAdapter        *client.Adapter
+	AdminService         *service.AdminService
+	ProxyHandler         *handler.ProxyHandler
+	ModelsHandler        *handler.ModelsHandler
+	AdminHandler         *handler.AdminHandler
+	AntigravityHandler   *handler.AntigravityHandler
+	KiroHandler          *handler.KiroHandler
+	CodexHandler         *handler.CodexHandler
+	CodexOAuthServer     *CodexOAuthServer
+	ClaudeHandler        *handler.ClaudeHandler
+	ClaudeOAuthServer    *ClaudeOAuthServer
+	ProjectProxyHandler  *handler.ProjectProxyHandler
+	ProviderProxyHandler *handler.ProviderProxyHandler
+	RequestTracker       *RequestTracker
+	PprofManager         *PprofManager
+	AuthMiddleware       *handler.AuthMiddleware
+	AuthHandler          *handler.AuthHandler
+	BackupService        *service.BackupService
 }
 
 // InitializeDatabase 初始化数据库和所有仓库
@@ -409,33 +410,35 @@ func InitializeServerComponents(
 	claudeOAuthServer := NewClaudeOAuthServer(claudeHandler)
 	claudeHandler.SetOAuthServer(claudeOAuthServer)
 	projectProxyHandler := handler.NewProjectProxyHandler(proxyHandler, modelsHandler, repos.CachedProjectRepo, repos.CachedProviderRepo)
+	providerProxyHandler := handler.NewProviderProxyHandler(proxyHandler, modelsHandler, repos.CachedProviderRepo)
 
 	log.Printf("[Core] Creating request tracker for graceful shutdown")
 	requestTracker := NewRequestTracker()
 	proxyHandler.SetRequestTracker(requestTracker)
 
 	components := &ServerComponents{
-		Router:              r,
-		WebSocketHub:        wsHub,
-		WailsBroadcaster:    wailsBroadcaster,
-		Executor:            exec,
-		ClientAdapter:       clientAdapter,
-		AdminService:        adminService,
-		ProxyHandler:        proxyHandler,
-		ModelsHandler:       modelsHandler,
-		AdminHandler:        adminHandler,
-		AntigravityHandler:  antigravityHandler,
-		KiroHandler:         kiroHandler,
-		CodexHandler:        codexHandler,
-		CodexOAuthServer:    codexOAuthServer,
-		ClaudeHandler:       claudeHandler,
-		ClaudeOAuthServer:   claudeOAuthServer,
-		ProjectProxyHandler: projectProxyHandler,
-		RequestTracker:      requestTracker,
-		PprofManager:        pprofMgr,
-		AuthMiddleware:      authMiddleware,
-		AuthHandler:         authHandler,
-		BackupService:       backupService,
+		Router:               r,
+		WebSocketHub:         wsHub,
+		WailsBroadcaster:     wailsBroadcaster,
+		Executor:             exec,
+		ClientAdapter:        clientAdapter,
+		AdminService:         adminService,
+		ProxyHandler:         proxyHandler,
+		ModelsHandler:        modelsHandler,
+		AdminHandler:         adminHandler,
+		AntigravityHandler:   antigravityHandler,
+		KiroHandler:          kiroHandler,
+		CodexHandler:         codexHandler,
+		CodexOAuthServer:     codexOAuthServer,
+		ClaudeHandler:        claudeHandler,
+		ClaudeOAuthServer:    claudeOAuthServer,
+		ProjectProxyHandler:  projectProxyHandler,
+		ProviderProxyHandler: providerProxyHandler,
+		RequestTracker:       requestTracker,
+		PprofManager:         pprofMgr,
+		AuthMiddleware:       authMiddleware,
+		AuthHandler:          authHandler,
+		BackupService:        backupService,
 	}
 
 	log.Printf("[Core] Server components initialized successfully")

internal/core/server.go

@@ -106,11 +106,12 @@ func (s *ManagedServer) setupRoutes() *http.ServeMux {
 
 	if s.config.ServeStatic {
 		staticHandler := handler.NewStaticHandler()
-		combinedHandler := handler.NewCombinedHandler(components.ProjectProxyHandler, staticHandler)
+		combinedHandler := handler.NewCombinedHandler(components.ProjectProxyHandler, components.ProviderProxyHandler, staticHandler)
 		mux.Handle("/", combinedHandler)
 		log.Printf("[Server] Static file serving enabled")
 	} else {
-		mux.Handle("/", components.ProjectProxyHandler)
+		mux.Handle("/project/", components.ProjectProxyHandler)
+		mux.Handle("/provider/", components.ProviderProxyHandler)
 		log.Printf("[Server] Static file serving disabled (Wails mode)")
 	}
 

internal/handler/provider_proxy.go

@@ -0,0 +1,101 @@
+package handler
+
+import (
+	"log"
+	"net/http"
+	"strconv"
+	"strings"
+
+	maxxctx "github.com/awsl-project/maxx/internal/context"
+	"github.com/awsl-project/maxx/internal/repository"
+)
+
+// ProviderProxyHandler wraps ProxyHandler to handle provider-scoped proxy requests
+// like /provider/{id}/v1/messages.
+type ProviderProxyHandler struct {
+	proxyHandler  *ProxyHandler
+	modelsHandler *ModelsHandler
+	providerRepo  repository.ProviderRepository
+}
+
+// NewProviderProxyHandler creates a new provider-scoped proxy handler.
+func NewProviderProxyHandler(
+	proxyHandler *ProxyHandler,
+	modelsHandler *ModelsHandler,
+	providerRepo repository.ProviderRepository,
+) *ProviderProxyHandler {
+	return &ProviderProxyHandler{
+		proxyHandler:  proxyHandler,
+		modelsHandler: modelsHandler,
+		providerRepo:  providerRepo,
+	}
+}
+
+// ServeHTTP handles provider-scoped proxy requests.
+func (h *ProviderProxyHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	providerValue, apiPath, ok := h.parseScopedPath(r.URL.Path)
+	if !ok {
+		writeError(w, http.StatusNotFound, "invalid provider proxy path")
+		return
+	}
+
+	providerID, err := strconv.ParseUint(providerValue, 10, 64)
+	if err != nil || providerID == 0 {
+		writeError(w, http.StatusBadRequest, "invalid provider id")
+		return
+	}
+
+	tenantID := maxxctx.GetTenantID(r.Context())
+	provider, err := h.providerRepo.GetByID(tenantID, providerID)
+	if err != nil || provider == nil {
+		log.Printf("[ProviderProxy] Provider not found for id: %s", providerValue)
+		writeError(w, http.StatusNotFound, "provider not found")
+		return
+	}
+
+	log.Printf("[ProviderProxy] Routing request through provider: %s (ID: %d)", provider.Name, provider.ID)
+	r.Header.Set("X-Maxx-Provider-ID", strings.TrimSpace(itoa(provider.ID)))
+	r.URL.Path = apiPath
+	if apiPath == "/v1/models" {
+		h.modelsHandler.ServeHTTP(w, r)
+		return
+	}
+
+	h.proxyHandler.ServeHTTP(w, r)
+}
+
+// parseScopedPath extracts provider ID and API path.
+// Input: /provider/1/v1/messages
+func (h *ProviderProxyHandler) parseScopedPath(path string) (providerID, apiPath string, ok bool) {
+	if !strings.HasPrefix(path, "/provider/") {
+		return "", "", false
+	}
+	parts := strings.SplitN(strings.TrimPrefix(path, "/provider/"), "/", 2)
+	if len(parts) < 2 {
+		return "", "", false
+	}
+
+	trimmed := strings.TrimSpace(parts[0])
+	if trimmed == "" {
+		return "", "", false
+	}
+
+	apiPath = "/" + parts[1]
+	if !isValidProviderAPIPath(apiPath) {
+		return "", "", false
+	}
+	return trimmed, apiPath, true
+}
+
+func isValidProviderAPIPath(path string) bool {
+	return matchesProviderEndpointPath(path, "/v1/messages") ||
+		matchesProviderEndpointPath(path, "/v1/chat/completions") ||
+		matchesProviderEndpointPath(path, "/responses") ||
+		matchesProviderEndpointPath(path, "/v1/responses") ||
+		matchesProviderEndpointPath(path, "/v1/models") ||
+		matchesProviderEndpointPath(path, "/v1beta/models")
+}
+
+func matchesProviderEndpointPath(path, endpoint string) bool {
+	return path == endpoint || strings.HasPrefix(path, endpoint+"/")
+}

internal/handler/provider_proxy_test.go

@@ -0,0 +1,79 @@
+package handler
+
+import "testing"
+
+func TestParseProviderScopedPath(t *testing.T) {
+	h := &ProviderProxyHandler{}
+	providerID, apiPath, ok := h.parseScopedPath("/provider/1/v1/chat/completions")
+	if !ok {
+		t.Fatal("expected provider path to parse")
+	}
+	if providerID != "1" {
+		t.Fatalf("providerID = %q, want 1", providerID)
+	}
+	if apiPath != "/v1/chat/completions" {
+		t.Fatalf("apiPath = %q, want /v1/chat/completions", apiPath)
+	}
+}
+
+func TestParseProviderScopedPath_TrimsScopeValue(t *testing.T) {
+	h := &ProviderProxyHandler{}
+	providerID, apiPath, ok := h.parseScopedPath("/provider/ 1 /v1/messages")
+	if !ok {
+		t.Fatal("expected provider path to parse")
+	}
+	if providerID != "1" {
+		t.Fatalf("providerID = %q, want 1", providerID)
+	}
+	if apiPath != "/v1/messages" {
+		t.Fatalf("apiPath = %q, want /v1/messages", apiPath)
+	}
+}
+
+func TestIsValidProviderAPIPath_AllowsExactAndSubpathsOnly(t *testing.T) {
+	valid := []string{
+		"/v1/messages",
+		"/v1/messages/stream",
+		"/v1/chat/completions",
+		"/v1/chat/completions/extra",
+		"/responses",
+		"/responses/items",
+		"/v1/responses",
+		"/v1/responses/abc",
+		"/v1/models",
+		"/v1/models/list",
+		"/v1beta/models",
+		"/v1beta/models/gemini-2.5-pro",
+	}
+	for _, path := range valid {
+		if !isValidProviderAPIPath(path) {
+			t.Fatalf("expected %q to be valid", path)
+		}
+	}
+
+	invalid := []string{
+		"/v1/messages-debug",
+		"/v1/chat/completionsXYZ",
+		"/responses123",
+		"/v1/responsesXYZ",
+		"/v1/models-debug",
+		"/v1beta/modelsX",
+	}
+	for _, path := range invalid {
+		if isValidProviderAPIPath(path) {
+			t.Fatalf("expected %q to be invalid", path)
+		}
+	}
+}
+
+func TestIsProviderProxyPath(t *testing.T) {
+	if !isProviderProxyPath("/provider/1/v1/messages") {
+		t.Fatal("expected provider path to be detected")
+	}
+	if isProviderProxyPath("/project/demo/v1/messages") {
+		t.Fatal("did not expect project path to be detected as provider path")
+	}
+	if isProviderProxyPath("/providers") {
+		t.Fatal("did not expect regular web route to be detected")
+	}
+}

internal/handler/proxy.go

@@ -185,10 +185,14 @@ func (h *ProxyHandler) ingress(c *flow.Ctx) {
 
 	var providerID uint64
 	if providerIDStr := r.Header.Get("X-Maxx-Provider-ID"); providerIDStr != "" {
-		if pid, err := strconv.ParseUint(providerIDStr, 10, 64); err == nil {
-			providerID = pid
-			log.Printf("[Proxy] Using provider ID from header: %d", providerID)
+		pid, err := strconv.ParseUint(providerIDStr, 10, 64)
+		if err != nil || pid == 0 {
+			writeError(w, http.StatusBadRequest, "invalid provider id")
+			c.Abort()
+			return
 		}
+		providerID = pid
+		log.Printf("[Proxy] Using provider ID from header: %d", providerID)
 	}
 
 	session, sessionErr := h.sessionRepo.GetBySessionID(tenantID, sessionID)

internal/handler/static.go

@@ -308,17 +308,19 @@ func getMimeType(filePath string) string {
 }
 
 // NewCombinedHandler creates a handler that routes project-prefixed proxy requests
-// to the ProjectProxyHandler, and all other requests to the static file handler.
-// This allows URLs like /my-project/v1/messages to be proxied through a specific project.
-func NewCombinedHandler(projectProxyHandler *ProjectProxyHandler, staticHandler http.Handler) http.Handler {
+// to the ProjectProxyHandler, provider-prefixed proxy requests to the ProviderProxyHandler,
+// and all other requests to the static file handler.
+func NewCombinedHandler(projectProxyHandler *ProjectProxyHandler, providerProxyHandler *ProviderProxyHandler, staticHandler http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		// Check if this looks like a project-prefixed proxy request
 		if isProjectProxyPath(r.URL.Path) {
+			if isProviderProxyPath(r.URL.Path) {
+				providerProxyHandler.ServeHTTP(w, r)
+				return
+			}
 			projectProxyHandler.ServeHTTP(w, r)
 			return
 		}
 
-		// Otherwise, serve static files
 		staticHandler.ServeHTTP(w, r)
 	})
 }
@@ -328,3 +330,7 @@ func NewCombinedHandler(projectProxyHandler *ProjectProxyHandler, staticHandler
 func isProjectProxyPath(urlPath string) bool {
 	return strings.HasPrefix(urlPath, "/project/") || strings.HasPrefix(urlPath, "/provider/")
 }
+
+func isProviderProxyPath(urlPath string) bool {
+	return strings.HasPrefix(urlPath, "/provider/")
+}