feat(架构): 完善基础架构设计

internal/shared/http/router.go

@@ -8,6 +8,8 @@ import (
 	"time"
 
 	"github.com/gin-gonic/gin"
+	swaggerFiles "github.com/swaggo/files"
+	ginSwagger "github.com/swaggo/gin-swagger"
 	"go.uber.org/zap"
 
 	"tyapi-server/internal/config"
@@ -51,7 +53,7 @@ func (r *GinRouter) RegisterHandler(handler interfaces.HTTPHandler) error {
 	// 注册路由
 	r.engine.Handle(handler.GetMethod(), handler.GetPath(), append(middlewares, handler.Handle)...)
 
-	r.logger.Info("Registered HTTP handler",
+	r.logger.Info("已注册HTTP处理器",
 		zap.String("method", handler.GetMethod()),
 		zap.String("path", handler.GetPath()))
 
@@ -62,7 +64,7 @@ func (r *GinRouter) RegisterHandler(handler interfaces.HTTPHandler) error {
 func (r *GinRouter) RegisterMiddleware(middleware interfaces.Middleware) error {
 	r.middlewares = append(r.middlewares, middleware)
 
-	r.logger.Info("Registered middleware",
+	r.logger.Info("已注册中间件",
 		zap.String("name", middleware.GetName()),
 		zap.Int("priority", middleware.GetPriority()))
 
@@ -93,7 +95,7 @@ func (r *GinRouter) Start(addr string) error {
 		IdleTimeout:  r.config.Server.IdleTimeout,
 	}
 
-	r.logger.Info("Starting HTTP server", zap.String("addr", addr))
+	r.logger.Info("正在启动HTTP服务器", zap.String("addr", addr))
 
 	// 启动服务器
 	if err := r.server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
@@ -109,15 +111,15 @@ func (r *GinRouter) Stop(ctx context.Context) error {
 		return nil
 	}
 
-	r.logger.Info("Stopping HTTP server...")
+	r.logger.Info("正在关闭HTTP服务器...")
 
 	// 优雅关闭服务器
 	if err := r.server.Shutdown(ctx); err != nil {
-		r.logger.Error("Failed to shutdown server gracefully", zap.Error(err))
+		r.logger.Error("优雅关闭服务器失败", zap.Error(err))
 		return err
 	}
 
-	r.logger.Info("HTTP server stopped")
+	r.logger.Info("HTTP服务器已关闭")
 	return nil
 }
 
@@ -137,7 +139,7 @@ func (r *GinRouter) applyMiddlewares() {
 	for _, middleware := range r.middlewares {
 		if middleware.IsGlobal() {
 			r.engine.Use(middleware.Handle())
-			r.logger.Debug("Applied global middleware",
+			r.logger.Debug("已应用全局中间件",
 				zap.String("name", middleware.GetName()),
 				zap.Int("priority", middleware.GetPriority()))
 		}
@@ -156,6 +158,18 @@ func (r *GinRouter) SetupDefaultRoutes() {
 		})
 	})
 
+	// 详细健康检查
+	r.engine.GET("/health/detailed", func(c *gin.Context) {
+		c.JSON(http.StatusOK, gin.H{
+			"status":      "healthy",
+			"timestamp":   time.Now().Unix(),
+			"service":     r.config.App.Name,
+			"version":     r.config.App.Version,
+			"uptime":      time.Now().Unix(),
+			"environment": r.config.App.Env,
+		})
+	})
+
 	// API信息
 	r.engine.GET("/info", func(c *gin.Context) {
 		c.JSON(http.StatusOK, gin.H{
@@ -166,11 +180,37 @@ func (r *GinRouter) SetupDefaultRoutes() {
 		})
 	})
 
+	// Swagger文档路由 (仅在开发环境启用)
+	if !r.config.App.IsProduction() {
+		// Swagger UI
+		r.engine.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
+
+		// API文档重定向
+		r.engine.GET("/docs", func(c *gin.Context) {
+			c.Redirect(http.StatusMovedPermanently, "/swagger/index.html")
+		})
+
+		// API文档信息
+		r.engine.GET("/api/docs", func(c *gin.Context) {
+			c.JSON(http.StatusOK, gin.H{
+				"swagger_ui":   fmt.Sprintf("http://%s/swagger/index.html", c.Request.Host),
+				"openapi_json": fmt.Sprintf("http://%s/swagger/doc.json", c.Request.Host),
+				"redoc":        fmt.Sprintf("http://%s/redoc", c.Request.Host),
+				"message":      "API文档已可用",
+			})
+		})
+
+		r.logger.Info("Swagger documentation enabled",
+			zap.String("swagger_url", "/swagger/index.html"),
+			zap.String("docs_url", "/docs"),
+			zap.String("api_docs_url", "/api/docs"))
+	}
+
 	// 404处理
 	r.engine.NoRoute(func(c *gin.Context) {
 		c.JSON(http.StatusNotFound, gin.H{
 			"success":   false,
-			"message":   "Route not found",
+			"message":   "路由未找到",
 			"path":      c.Request.URL.Path,
 			"method":    c.Request.Method,
 			"timestamp": time.Now().Unix(),
@@ -181,7 +221,7 @@ func (r *GinRouter) SetupDefaultRoutes() {
 	r.engine.NoMethod(func(c *gin.Context) {
 		c.JSON(http.StatusMethodNotAllowed, gin.H{
 			"success":   false,
-			"message":   "Method not allowed",
+			"message":   "请求方法不允许",
 			"path":      c.Request.URL.Path,
 			"method":    c.Request.Method,
 			"timestamp": time.Now().Unix(),