feat[Go]: implement Box OAuth connector start/callback/result APIs

Ports the full Box OAuth web flow from Python (connector_api.py) to Go,
addressing issue #15662 and the review on PR #15664.

  POST /api/v1/connectors/box/oauth/web/start    (StartBoxWebOAuth)
  GET  /api/v1/connectors/box/oauth/web/callback (BoxWebOAuthCallback)
  POST /api/v1/connectors/box/oauth/web/result   (PollBoxWebOAuthResult)

Review fix (Hz-186): the /start endpoint was missing, so the frontend could
not initiate the flow (no flow_id generated, no initial state written to Redis,
404 on the Go backend). Implemented StartBoxWebOAuth for full parity with
Python start_box_web_oauth:
  - validates client_id / client_secret (ARGUMENT_ERROR when missing)
  - resolves redirect_uri (request value or BOX_WEB_OAUTH_REDIRECT_URI)
  - generates a flow_id, builds the Box authorize URL
    (https://account.box.com/api/oauth2/authorize?...&state=flow_id)
  - writes the initial boxWebOAuthState to Redis under the box flow-state key
    with the standard web-flow TTL
  - returns {flow_id, authorization_url, expires_in}
Wired the authenticated POST route in the /api/v1/connectors group and added
the service-interface method on the handler.

Also addressed CodeRabbit's docstring-coverage warning: documented the
Box request/response/state types, the new start + URL-builder helpers, and the
previously-undocumented boxOAuthTokenResponse and defaultBoxWebOAuthRedirectURI.

Author: hunnyboy1217

internal/handler/connector.go

@@ -42,6 +42,9 @@ type connectorServiceIface interface {
 	StartGoogleWebOAuth(userID, source string, req *service.StartGoogleWebOAuthRequest) (*service.StartGoogleWebOAuthResponse, common.ErrorCode, error)
 	GoogleWebOAuthCallback(source, stateID, oauthError, errorDescription, code string) string
 	PollGoogleWebOAuthResult(userID, source string, req *service.PollGoogleWebOAuthResultRequest) (*service.PollGoogleWebOAuthResultResponse, common.ErrorCode, error)
+	StartBoxWebOAuth(userID string, req *service.StartBoxWebOAuthRequest) (*service.StartBoxWebOAuthResponse, common.ErrorCode, error)
+	BoxWebOAuthCallback(stateID, oauthError, errorDescription, code string) string
+	PollBoxWebOAuthResult(userID string, req *service.PollBoxWebOAuthResultRequest) (*service.PollBoxWebOAuthResultResponse, common.ErrorCode, error)
 }
 
 // ConnectorHandler connector handler
@@ -504,3 +507,107 @@ func (h *ConnectorHandler) googleWebOAuthCallback(c *gin.Context, source string)
 	)
 	c.Data(http.StatusOK, "text/html; charset=utf-8", []byte(html))
 }
+
+// StartBoxWebOAuth initiates the Box OAuth web flow for the authenticated user.
+// It returns the authorization URL the frontend should open along with the flow
+// ID and expiry, and writes the initial flow state to Redis.
+// @Summary Start Box OAuth Web Flow
+// @Description Begin the Box OAuth web flow: generate a flow ID, build the Box
+// authorization URL, and persist the initial state in Redis.
+// @Tags connector
+// @Accept json
+// @Produce json
+// @Param request body service.StartBoxWebOAuthRequest true "Box client credentials"
+// @Success 200 {object} map[string]interface{}
+// @Router /api/v1/connectors/box/oauth/web/start [post]
+func (h *ConnectorHandler) StartBoxWebOAuth(c *gin.Context) {
+	user, errorCode, errorMessage := GetUser(c)
+	if errorCode != common.CodeSuccess {
+		jsonError(c, errorCode, errorMessage)
+		return
+	}
+
+	var req service.StartBoxWebOAuthRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{
+			"code":    common.CodeBadRequest,
+			"data":    nil,
+			"message": err.Error(),
+		})
+		return
+	}
+
+	data, code, err := h.connectorService.StartBoxWebOAuth(user.ID, &req)
+	if err != nil {
+		jsonError(c, code, err.Error())
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{
+		"code":    common.CodeSuccess,
+		"data":    data,
+		"message": "success",
+	})
+}
+
+// BoxWebOAuthCallback handles the redirect from Box after the user grants access.
+// This endpoint is public (no auth middleware) — Box redirects the user's browser here.
+// @Summary Box OAuth Web Callback
+// @Description Receives the authorization code from Box, exchanges it for tokens,
+// stores the result in Redis, and renders a self-closing popup page.
+// @Tags connector
+// @Produce text/html
+// @Param state query string true "OAuth state (flow ID)"
+// @Param code query string false "Authorization code"
+// @Param error query string false "Error code from Box"
+// @Param error_description query string false "Human-readable error from Box"
+// @Router /api/v1/connectors/box/oauth/web/callback [get]
+func (h *ConnectorHandler) BoxWebOAuthCallback(c *gin.Context) {
+	htmlPage := h.connectorService.BoxWebOAuthCallback(
+		c.Query("state"),
+		c.Query("error"),
+		c.Query("error_description"),
+		c.Query("code"),
+	)
+	c.Data(http.StatusOK, "text/html; charset=utf-8", []byte(htmlPage))
+}
+
+// PollBoxWebOAuthResult polls for the result of a Box OAuth web flow.
+// @Summary Poll Box OAuth Result
+// @Description Check whether the Box OAuth callback has completed and retrieve the credentials.
+// Returns code 106 (RUNNING) while authorization is still pending.
+// @Tags connector
+// @Accept json
+// @Produce json
+// @Param body body service.PollBoxWebOAuthResultRequest true "Flow ID"
+// @Success 200 {object} map[string]interface{}
+// @Router /api/v1/connectors/box/oauth/web/result [post]
+func (h *ConnectorHandler) PollBoxWebOAuthResult(c *gin.Context) {
+	user, errorCode, errorMessage := GetUser(c)
+	if errorCode != common.CodeSuccess {
+		jsonError(c, errorCode, errorMessage)
+		return
+	}
+
+	var req service.PollBoxWebOAuthResultRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{
+			"code":    common.CodeBadRequest,
+			"data":    nil,
+			"message": err.Error(),
+		})
+		return
+	}
+
+	data, code, err := h.connectorService.PollBoxWebOAuthResult(user.ID, &req)
+	if err != nil {
+		jsonError(c, code, err.Error())
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{
+		"code":    common.CodeSuccess,
+		"data":    data,
+		"message": "success",
+	})
+}

internal/router/router.go

@@ -123,6 +123,7 @@ func (r *Router) Setup(engine *gin.Engine) {
 	// the RAGFlow auth middleware.
 	engine.GET("/connectors/gmail/oauth/web/callback", r.connectorHandler.GmailWebOAuthCallback)
 	engine.GET("/connectors/google-drive/oauth/web/callback", r.connectorHandler.GoogleDriveWebOAuthCallback)
+	engine.GET("/connectors/box/oauth/web/callback", r.connectorHandler.BoxWebOAuthCallback)
 
 	apiNoAuth := engine.Group("/api/v1")
 	{
@@ -150,9 +151,11 @@ func (r *Router) Setup(engine *gin.Engine) {
 		// Document images are embedded directly in pages and match Python's public route.
 		apiNoAuth.GET("/documents/images/:image_id", r.documentHandler.GetDocumentImage)
 
-		// Google redirects here after Gmail / Google Drive web OAuth completes.
+		// OAuth callbacks — Gmail, Google Drive, and Box redirect the user's browser here;
+		// no auth middleware is applied on this group.
 		apiNoAuth.GET("/connectors/gmail/oauth/web/callback", r.connectorHandler.GmailWebOAuthCallback)
 		apiNoAuth.GET("/connectors/google-drive/oauth/web/callback", r.connectorHandler.GoogleDriveWebOAuthCallback)
+		apiNoAuth.GET("/connectors/box/oauth/web/callback", r.connectorHandler.BoxWebOAuthCallback)
 	}
 
 	// Protected routes
@@ -398,6 +401,8 @@ func (r *Router) Setup(engine *gin.Engine) {
 				connector.POST("/", r.connectorHandler.CreateConnector)
 				connector.POST("/google/oauth/web/start", r.connectorHandler.StartGoogleWebOAuth)
 				connector.POST("/google/oauth/web/result", r.connectorHandler.PollGoogleWebOAuthResult)
+				connector.POST("/box/oauth/web/start", r.connectorHandler.StartBoxWebOAuth)
+				connector.POST("/box/oauth/web/result", r.connectorHandler.PollBoxWebOAuthResult)
 				connector.GET("/:connector_id", r.connectorHandler.GetConnector)
 				connector.GET("/:connector_id/logs", r.connectorHandler.ListLogs)
 				connector.DELETE("/:connector_id", r.connectorHandler.DeleteConnector)