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

What:
- add a dedicated ProviderProxyHandler for /provider/{id}/... requests while keeping the existing scoped project handler intact
- wire provider-scoped requests through separate server/static dispatch paths instead of routing them through the project handler entrypoint
- keep the provider-scope safety fixes for path validation, invalid provider header rejection, and router matching
- add regression coverage for provider handler dispatch, provider-scoped router behavior, and the Playwright provider route flow

Why:
- make provider scope an independent proxy surface without rewriting the existing project-scoped implementation more than necessary
- reduce project-related churn in this PR while still fixing the provider-scoped control-flow problems caught in review
- leave the codepath easier to review by isolating the new behavior to provider-specific wiring plus the minimal shared safeguards

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/project_proxy.go

@@ -95,11 +95,16 @@ func (h *ProjectProxyHandler) parseScopedPath(path string) (scopeType, scopeValu
 
 func parseScopePath(scopeType, path string) (resolvedType, scopeValue, apiPath string, ok bool) {
 	parts := strings.SplitN(path, "/", 2)
-	if len(parts) < 2 || strings.TrimSpace(parts[0]) == "" {
+	if len(parts) < 2 {
 		return "", "", "", false
 	}
 
-	scopeValue = parts[0]
+	trimmed := strings.TrimSpace(parts[0])
+	if trimmed == "" {
+		return "", "", "", false
+	}
+
+	scopeValue = trimmed
 	apiPath = "/" + parts[1]
 	if !isValidAPIPath(apiPath) {
 		return "", "", "", false
@@ -109,25 +114,16 @@ func parseScopePath(scopeType, path string) (resolvedType, scopeValue, apiPath s
 
 // isValidAPIPath checks if the path is a known proxy API endpoint.
 func isValidAPIPath(path string) bool {
-	if strings.HasPrefix(path, "/v1/messages") {
-		return true
-	}
-	if strings.HasPrefix(path, "/v1/chat/completions") {
-		return true
-	}
-	if strings.HasPrefix(path, "/responses") {
-		return true
-	}
-	if strings.HasPrefix(path, "/v1/responses") {
-		return true
-	}
-	if strings.HasPrefix(path, "/v1/models") {
-		return true
-	}
-	if strings.HasPrefix(path, "/v1beta/models/") {
-		return true
-	}
-	return false
+	return matchesEndpointPath(path, "/v1/messages") ||
+		matchesEndpointPath(path, "/v1/chat/completions") ||
+		matchesEndpointPath(path, "/responses") ||
+		matchesEndpointPath(path, "/v1/responses") ||
+		matchesEndpointPath(path, "/v1/models") ||
+		matchesEndpointPath(path, "/v1beta/models")
+}
+
+func matchesEndpointPath(path, endpoint string) bool {
+	return path == endpoint || strings.HasPrefix(path, endpoint+"/")
 }
 
 func itoa(n uint64) string {

internal/handler/project_proxy_test.go

@@ -40,10 +40,62 @@ func TestIsProjectProxyPath(t *testing.T) {
 	if !isProjectProxyPath("/project/demo/v1/messages") {
 		t.Fatal("expected project path to be detected")
 	}
-	if !isProjectProxyPath("/provider/1/v1/messages") {
-		t.Fatal("expected provider path to be detected")
+	if isProjectProxyPath("/provider/1/v1/messages") {
+		t.Fatal("did not expect provider path to be detected as project path")
 	}
 	if isProjectProxyPath("/projects") {
 		t.Fatal("did not expect regular web route to be detected")
 	}
 }
+
+func TestParseScopePath_TrimsScopeValue(t *testing.T) {
+	scopeType, scopeValue, apiPath, ok := parseScopePath("project", " demo /v1/messages")
+	if !ok {
+		t.Fatal("expected scoped path to parse")
+	}
+	if scopeType != "project" {
+		t.Fatalf("scopeType = %q, want project", scopeType)
+	}
+	if scopeValue != "demo" {
+		t.Fatalf("scopeValue = %q, want demo", scopeValue)
+	}
+	if apiPath != "/v1/messages" {
+		t.Fatalf("apiPath = %q, want /v1/messages", apiPath)
+	}
+}
+
+func TestIsValidAPIPath_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 !isValidAPIPath(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 isValidAPIPath(path) {
+			t.Fatalf("expected %q to be invalid", path)
+		}
+	}
+}

internal/handler/provider_proxy.go

@@ -0,0 +1,75 @@
+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
+	}
+	_, providerID, apiPath, ok = parseScopePath("provider", strings.TrimPrefix(path, "/provider/"))
+	return providerID, apiPath, ok
+}

internal/handler/provider_proxy_test.go

@@ -0,0 +1,29 @@
+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 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)