doc: 增加代码注释

backend/cmd/main.go

@@ -1,3 +1,4 @@
+// gen2d backend 入口
 package main
 
 import (
@@ -16,9 +17,10 @@ func main() {
 	gin.SetMode(cfg.Mode)
 
 	r := gin.New()
-	r.Use(gin.Recovery())
+	r.Use(gin.Recovery()) // panic 恢复中间件，防止服务因未捕获异常宕机
 
-	r.GET("/api/v1/health", handler.Health)
+	// API v1 路由组
+	r.GET("/api/v1/health", handler.Health) // 健康检查
 
 	addr := fmt.Sprintf(":%d", cfg.Port)
 	log.Printf("gen2d backend starting on %s", addr)

backend/internal/config/config.go

@@ -1,3 +1,4 @@
+// Package config 负责从环境变量加载应用配置。
 package config
 
 import (
@@ -5,12 +6,14 @@ import (
 	"strconv"
 )
 
+// Config 应用全局配置，优先读取环境变量，未设置时使用默认值。
 type Config struct {
-	Port        int
-	Mode        string
-	MaxFileSize int64 // bytes
+	Port        int   // HTTP 监听端口，默认 8080，环境变量 GEN2D_PORT
+	Mode        string // Gin 运行模式 (debug/release)，环境变量 GEN2D_MODE
+	MaxFileSize int64  // 上传文件大小上限（字节），默认 10MB
 }
 
+// Load 从环境变量加载配置并返回。
 func Load() *Config {
 	cfg := &Config{
 		Port:        8080,

backend/internal/handler/health.go

@@ -6,6 +6,7 @@ import (
 	"github.com/gin-gonic/gin"
 )
 
+// Health 健康检查接口，返回服务运行状态。
 func Health(c *gin.Context) {
 	c.JSON(200, model.OK(gin.H{"status": "healthy"}))
 }

backend/internal/model/response.go

@@ -1,15 +1,19 @@
+// Package model 定义请求/响应的数据结构。
 package model
 
+// Response 统一 API 响应格式，所有接口均返回此结构。
 type Response struct {
-	Code    int    `json:"code"`
-	Message string `json:"message"`
-	Data    any    `json:"data,omitempty"`
+	Code    int    `json:"code"`              // 业务状态码，0 表示成功
+	Message string `json:"message"`           // 状态描述
+	Data    any    `json:"data,omitempty"`    // 响应数据，错误时省略
 }
 
+// OK 构造成功响应。
 func OK(data any) Response {
 	return Response{Code: 0, Message: "ok", Data: data}
 }
 
+// Fail 构造错误响应。
 func Fail(code int, msg string) Response {
 	return Response{Code: code, Message: msg}
 }