🤖 fix(proxy): add provider-scoped proxy handler

What:
- add a dedicated ProviderProxyHandler for /provider/{id}/... requests
- keep ProjectProxyHandler on its original project-only constructor and flow, and route provider scope through separate wiring
- move provider route registration to explicit /provider/ handlers so static handling does not need provider-specific branching
- rewrite provider route matching as its own router path instead of mixing provider scope into the project-routing control flow
- preserve provider-scoped request propagation from ProviderProxyHandler into ProxyHandler, and keep provider-focused handler/router/e2e/playwright coverage

Why:
- keep provider scope independent from the existing project proxy implementation
- reduce follow-up churn to only the required changes for provider routing
- make provider-scoped matching reviewable as a parallel path instead of a project-routing patch

Tests:
- go test ./internal/handler ./internal/router ./tests/e2e/... (pass)
- MAXX_E2E_BASE_URL=http://127.0.0.1:9880 MAXX_E2E_USERNAME=admin MAXX_E2E_PASSWORD=test123 pnpm --dir tests/e2e/playwright test:provider-proxy-route (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)
+	providerProxyHandler := handler.NewProviderProxyHandler(proxyHandler, modelsHandler, cachedProviderRepo)
 
 	// Setup routes
 	mux := http.NewServeMux()
@@ -409,6 +410,8 @@ func main() {
 	mux.Handle("/v1/responses/", proxyHandler)
 	// Gemini API (Google AI Studio style)
 	mux.Handle("/v1beta/models/", proxyHandler)
+	// Provider-scoped proxy routes
+	mux.Handle("/provider/", providerProxyHandler)
 
 	// Health check
 	mux.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {

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 初始化数据库和所有仓库
@@ -415,27 +416,28 @@ func InitializeServerComponents(
 	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: handler.NewProviderProxyHandler(proxyHandler, modelsHandler, repos.CachedProviderRepo),
+		RequestTracker:       requestTracker,
+		PprofManager:         pprofMgr,
+		AuthMiddleware:       authMiddleware,
+		AuthHandler:          authHandler,
+		BackupService:        backupService,
 	}
 
 	log.Printf("[Core] Server components initialized successfully")

internal/core/server.go

@@ -103,6 +103,7 @@ func (s *ManagedServer) setupRoutes() *http.ServeMux {
 	})
 
 	mux.HandleFunc("/ws", components.WebSocketHub.HandleWebSocket)
+	mux.Handle("/provider/", components.ProviderProxyHandler)
 
 	if s.config.ServeStatic {
 		staticHandler := handler.NewStaticHandler()

internal/executor/flow_state.go

@@ -19,6 +19,7 @@ type execState struct {
 	tenantID            uint64
 	clientType          domain.ClientType
 	projectID           uint64
+	providerID          uint64
 	sessionID           string
 	requestModel        string
 	isStream            bool

internal/executor/middleware_ingress.go

@@ -36,6 +36,11 @@ func (e *Executor) ingress(c *flow.Ctx) {
 			state.projectID = pid
 		}
 	}
+	if v, ok := c.Get(flow.KeyProviderID); ok {
+		if pid, ok := v.(uint64); ok {
+			state.providerID = pid
+		}
+	}
 	if v, ok := c.Get(flow.KeySessionID); ok {
 		if sid, ok := v.(string); ok {
 			state.sessionID = sid
@@ -97,7 +102,7 @@ func (e *Executor) ingress(c *flow.Ctx) {
 		IsStream:     state.isStream,
 		Status:       "PENDING",
 		APITokenID:   state.apiTokenID,
-		DevMode:     state.apiTokenDevMode,
+		DevMode:      state.apiTokenDevMode,
 	}
 
 	clearDetail := e.shouldClearRequestDetailFor(state)

internal/executor/middleware_route_match.go

@@ -24,6 +24,7 @@ func (e *Executor) routeMatch(c *flow.Ctx) {
 		TenantID:     state.tenantID,
 		ClientType:   state.clientType,
 		ProjectID:    state.projectID,
+		ProviderID:   state.providerID,
 		RequestModel: state.requestModel,
 		APITokenID:   state.apiTokenID,
 	})

internal/flow/keys.go

@@ -10,6 +10,7 @@ const (
 	KeyOriginalClientType  = "original_client_type"
 	KeySessionID           = "session_id"
 	KeyProjectID           = "project_id"
+	KeyProviderID          = "provider_id"
 	KeyRequestModel        = "request_model"
 	KeyMappedModel         = "mapped_model"
 	KeyRequestBody         = "request_body"

internal/handler/provider_proxy.go

@@ -0,0 +1,143 @@
+package handler
+
+import (
+	"context"
+	"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-prefixed proxy requests
+// like /provider/{id}/v1/messages, /provider/{id}/v1/chat/completions, etc.
+type ProviderProxyHandler struct {
+	proxyHandler  *ProxyHandler
+	modelsHandler *ModelsHandler
+	providerRepo  repository.ProviderRepository
+}
+
+// NewProviderProxyHandler creates a new provider proxy handler
+func NewProviderProxyHandler(
+	proxyHandler *ProxyHandler,
+	modelsHandler *ModelsHandler,
+	providerRepo repository.ProviderRepository,
+) *ProviderProxyHandler {
+	return &ProviderProxyHandler{
+		proxyHandler:  proxyHandler,
+		modelsHandler: modelsHandler,
+		providerRepo:  providerRepo,
+	}
+}
+
+// ServeHTTP handles provider-prefixed proxy requests
+func (h *ProviderProxyHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	// Parse the path to extract provider ID and API path
+	// Expected format: /provider/{id}/v1/messages, /provider/{id}/v1/chat/completions, etc.
+	providerID, apiPath, ok := h.parseProviderPath(r.URL.Path)
+	if !ok {
+		writeError(w, http.StatusNotFound, "invalid provider proxy path")
+		return
+	}
+
+	// Parse and validate provider ID
+	providerIDNum, err := strconv.ParseUint(providerID, 10, 64)
+	if err != nil || providerIDNum == 0 {
+		writeError(w, http.StatusBadRequest, "invalid provider id")
+		return
+	}
+
+	// Look up provider by ID
+	tenantID := maxxctx.GetTenantID(r.Context())
+	provider, err := h.providerRepo.GetByID(tenantID, providerIDNum)
+	if err != nil {
+		log.Printf("[ProviderProxy] failed to load provider tenant=%d id=%d: %v", tenantID, providerIDNum, err)
+		writeError(w, http.StatusInternalServerError, "internal server error")
+		return
+	}
+	if provider == nil {
+		log.Printf("[ProviderProxy] Provider not found for id: %s", providerID)
+		writeError(w, http.StatusNotFound, "provider not found")
+		return
+	}
+
+	log.Printf("[ProviderProxy] Routing request through provider: %s (ID: %d)", provider.Name, provider.ID)
+
+	r = r.WithContext(context.WithValue(r.Context(), providerIDContextKey{}, provider.ID))
+
+	// Rewrite the URL path to the standard API path
+	r.URL.Path = apiPath
+
+	// Forward to the appropriate handler
+	if apiPath == "/v1/models" {
+		h.modelsHandler.ServeHTTP(w, r)
+		return
+	}
+	h.proxyHandler.ServeHTTP(w, r)
+}
+
+// parseProviderPath extracts the provider ID and API path from a provider-prefixed URL
+// Input: /provider/1/v1/messages
+// Output: ("1", "/v1/messages", true)
+func (h *ProviderProxyHandler) parseProviderPath(path string) (providerID, apiPath string, ok bool) {
+	// Must start with /provider/
+	if !strings.HasPrefix(path, "/provider/") {
+		return "", "", false
+	}
+
+	// Remove /provider/ prefix and split
+	path = strings.TrimPrefix(path, "/provider/")
+	parts := strings.SplitN(path, "/", 2)
+
+	if len(parts) < 2 {
+		return "", "", false
+	}
+
+	providerID = strings.TrimSpace(parts[0])
+	if providerID == "" {
+		return "", "", false
+	}
+
+	apiPath = "/" + parts[1]
+
+	// Validate this looks like a valid API path
+	if !isValidProviderAPIPath(apiPath) {
+		return "", "", false
+	}
+
+	return providerID, apiPath, true
+}
+
+// isValidProviderAPIPath checks if the path is a known proxy API endpoint
+func isProviderProxyPath(urlPath string) bool {
+	return strings.HasPrefix(urlPath, "/provider/")
+}
+
+func isValidProviderAPIPath(path string) bool {
+	// Claude API
+	if path == "/v1/messages" || strings.HasPrefix(path, "/v1/messages/") {
+		return true
+	}
+	// OpenAI API
+	if path == "/v1/chat/completions" || strings.HasPrefix(path, "/v1/chat/completions/") {
+		return true
+	}
+	// Codex API
+	if path == "/responses" || strings.HasPrefix(path, "/responses/") {
+		return true
+	}
+	if path == "/v1/responses" || strings.HasPrefix(path, "/v1/responses/") {
+		return true
+	}
+	// Model list API
+	if path == "/v1/models" || strings.HasPrefix(path, "/v1/models/") {
+		return true
+	}
+	// Gemini API
+	if path == "/v1beta/models" || strings.HasPrefix(path, "/v1beta/models/") {
+		return true
+	}
+	return false
+}

internal/handler/provider_proxy_test.go

@@ -0,0 +1,79 @@
+package handler
+
+import "testing"
+
+func TestParseProviderPath(t *testing.T) {
+	h := &ProviderProxyHandler{}
+	providerID, apiPath, ok := h.parseProviderPath("/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 TestParseProviderPath_TrimsProviderID(t *testing.T) {
+	h := &ProviderProxyHandler{}
+	providerID, apiPath, ok := h.parseProviderPath("/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")
+	}
+}