fix: 优化后端各模块 handler

- database_handler, knowledge_handler, model_handler
- neo4j_handler, sub_table_handler
- system_handler, upload_handler
- knowledge_service, upload_service

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

server/internal/handler/database_handler.go

@@ -17,7 +17,16 @@ func NewDatabaseHandler(svc *service.DatabaseService) *DatabaseHandler {
 	return &DatabaseHandler{service: svc}
 }
 
-// Check 检查数据库连接
+// @Summary 检查数据库连接
+// @Description 测试数据库连接是否正常
+// @Tags 数据库管理
+// @Accept json
+// @Produce json
+// @Param request body model.CheckRequest true "数据库连接信息"
+// @Success 200 {object} map[string]interface{}
+// @Failure 400 {object} map[string]string
+// @Failure 500 {object} map[string]string
+// @Router /database/check [post]
 func (h *DatabaseHandler) Check(c *gin.Context) {
 	var req model.CheckRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
@@ -34,7 +43,16 @@ func (h *DatabaseHandler) Check(c *gin.Context) {
 	c.JSON(http.StatusOK, result)
 }
 
-// Create 创建数据库信息
+// @Summary 创建数据库
+// @Description 添加新的数据库连接信息
+// @Tags 数据库管理
+// @Accept json
+// @Produce json
+// @Param request body model.CreateDatabaseRequest true "数据库信息"
+// @Success 201 {object} model.DatabaseInfo
+// @Failure 400 {object} map[string]string
+// @Failure 500 {object} map[string]string
+// @Router /database/add [post]
 func (h *DatabaseHandler) Create(c *gin.Context) {
 	var req model.CreateDatabaseRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
@@ -51,7 +69,15 @@ func (h *DatabaseHandler) Create(c *gin.Context) {
 	c.JSON(http.StatusCreated, info)
 }
 
-// GetByID 获取详情
+// @Summary 获取数据库详情
+// @Description 根据ID获取数据库详细信息
+// @Tags 数据库管理
+// @Accept json
+// @Produce json
+// @Param id path string true "数据库ID"
+// @Success 200 {object} model.DatabaseInfo
+// @Failure 404 {object} map[string]string
+// @Router /database/{id} [get]
 func (h *DatabaseHandler) GetByID(c *gin.Context) {
 	id := c.Param("id")
 
@@ -64,7 +90,14 @@ func (h *DatabaseHandler) GetByID(c *gin.Context) {
 	c.JSON(http.StatusOK, info)
 }
 
-// List 获取列表
+// @Summary 获取数据库列表
+// @Description 获取所有已添加的数据库列表
+// @Tags 数据库管理
+// @Accept json
+// @Produce json
+// @Success 200 {object} map[string]interface{}
+// @Failure 500 {object} map[string]string
+// @Router /database/list [get]
 func (h *DatabaseHandler) List(c *gin.Context) {
 	list, err := h.service.List()
 	if err != nil {
@@ -79,7 +112,17 @@ func (h *DatabaseHandler) List(c *gin.Context) {
 	c.JSON(http.StatusOK, gin.H{"list": list})
 }
 
-// Update 更新
+// @Summary 更新数据库信息
+// @Description 更新指定数据库的信息
+// @Tags 数据库管理
+// @Accept json
+// @Produce json
+// @Param id path string true "数据库ID"
+// @Param request body model.UpdateDatabaseRequest true "更新信息"
+// @Success 200 {object} model.DatabaseInfo
+// @Failure 400 {object} map[string]string
+// @Failure 404 {object} map[string]string
+// @Router /database/{id} [put]
 func (h *DatabaseHandler) Update(c *gin.Context) {
 	id := c.Param("id")
 
@@ -98,7 +141,16 @@ func (h *DatabaseHandler) Update(c *gin.Context) {
 	c.JSON(http.StatusOK, info)
 }
 
-// SaveGraph 保存图谱信息
+// @Summary 保存图谱信息
+// @Description 保存数据库的图谱结构信息
+// @Tags 数据库管理
+// @Accept json
+// @Produce json
+// @Param request body model.SaveGraphRequest true "图谱信息"
+// @Success 200 {object} map[string]interface{}
+// @Failure 400 {object} map[string]string
+// @Failure 500 {object} map[string]string
+// @Router /database/graph/save [post]
 func (h *DatabaseHandler) SaveGraph(c *gin.Context) {
 	var req model.SaveGraphRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
@@ -115,7 +167,15 @@ func (h *DatabaseHandler) SaveGraph(c *gin.Context) {
 	c.JSON(http.StatusOK, result)
 }
 
-// Delete 删除
+// @Summary 删除数据库
+// @Description 删除指定的数据库连接
+// @Tags 数据库管理
+// @Accept json
+// @Produce json
+// @Param id path string true "数据库ID"
+// @Success 200 {object} map[string]string
+// @Failure 404 {object} map[string]string
+// @Router /database/{id} [delete]
 func (h *DatabaseHandler) Delete(c *gin.Context) {
 	id := c.Param("id")
 

server/internal/handler/knowledge_handler.go

@@ -17,7 +17,15 @@ func NewKnowledgeHandler(s *service.KnowledgeService) *KnowledgeHandler {
 	return &KnowledgeHandler{service: s}
 }
 
-// Create 创建知识库
+// @Summary 创建知识库
+// @Description 创建一个新的知识库
+// @Tags 知识库
+// @Accept json
+// @Produce json
+// @Param request body model.CreateKnowledgeRequest true "知识库信息"
+// @Success 200 {object} map[string]interface{}
+// @Failure 400 {object} map[string]string
+// @Router /api/knowledge/create [post]
 func (h *KnowledgeHandler) Create(c *gin.Context) {
 	var req model.CreateKnowledgeRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
@@ -38,7 +46,14 @@ func (h *KnowledgeHandler) Create(c *gin.Context) {
 	})
 }
 
-// List 获取知识库列表
+// @Summary 获取知识库列表
+// @Description 获取所有知识库列表
+// @Tags 知识库
+// @Accept json
+// @Produce json
+// @Success 200 {object} map[string]interface{}
+// @Failure 500 {object} map[string]string
+// @Router /api/knowledge/list [get]
 func (h *KnowledgeHandler) List(c *gin.Context) {
 	list, err := h.service.List()
 	if err != nil {
@@ -49,7 +64,16 @@ func (h *KnowledgeHandler) List(c *gin.Context) {
 	c.JSON(http.StatusOK, gin.H{"success": true, "data": list})
 }
 
-// GetByID 获取知识库详情
+// @Summary 获取知识库详情
+// @Description 根据ID获取知识库详细信息
+// @Tags 知识库
+// @Accept json
+// @Produce json
+// @Param id path string true "知识库ID"
+// @Success 200 {object} map[string]interface{}
+// @Failure 400 {object} map[string]string
+// @Failure 404 {object} map[string]string
+// @Router /api/knowledge/{id} [get]
 func (h *KnowledgeHandler) GetByID(c *gin.Context) {
 	id := c.Param("id")
 	if id == "" {
@@ -66,7 +90,17 @@ func (h *KnowledgeHandler) GetByID(c *gin.Context) {
 	c.JSON(http.StatusOK, gin.H{"success": true, "data": kb})
 }
 
-// Update 更新知识库
+// @Summary 更新知识库
+// @Description 更新指定知识库的信息
+// @Tags 知识库
+// @Accept json
+// @Produce json
+// @Param id path string true "知识库ID"
+// @Param request body model.UpdateKnowledgeRequest true "更新信息"
+// @Success 200 {object} map[string]interface{}
+// @Failure 400 {object} map[string]string
+// @Failure 500 {object} map[string]string
+// @Router /api/knowledge/{id} [put]
 func (h *KnowledgeHandler) Update(c *gin.Context) {
 	id := c.Param("id")
 	if id == "" {
@@ -88,7 +122,16 @@ func (h *KnowledgeHandler) Update(c *gin.Context) {
 	c.JSON(http.StatusOK, gin.H{"success": true, "message": "Knowledge base updated"})
 }
 
-// Delete 删除知识库
+// @Summary 删除知识库
+// @Description 删除指定的知识库
+// @Tags 知识库
+// @Accept json
+// @Produce json
+// @Param id path string true "知识库ID"
+// @Success 200 {object} map[string]interface{}
+// @Failure 400 {object} map[string]string
+// @Failure 500 {object} map[string]string
+// @Router /api/knowledge/{id} [delete]
 func (h *KnowledgeHandler) Delete(c *gin.Context) {
 	id := c.Param("id")
 	if id == "" {
@@ -104,7 +147,17 @@ func (h *KnowledgeHandler) Delete(c *gin.Context) {
 	c.JSON(http.StatusOK, gin.H{"success": true, "message": "Knowledge base deleted"})
 }
 
-// ListDocuments 获取知识库下的文档列表
+// @Summary 获取知识库文档列表
+// @Description 获取指定知识库下的所有文档
+// @Tags 知识库
+// @Accept json
+// @Produce json
+// @Param id path string true "知识库ID"
+// @Param status query string false "文档状态筛选"
+// @Success 200 {object} map[string]interface{}
+// @Failure 400 {object} map[string]string
+// @Failure 500 {object} map[string]string
+// @Router /api/knowledge/{id}/documents [get]
 func (h *KnowledgeHandler) ListDocuments(c *gin.Context) {
 	id := c.Param("id")
 	if id == "" {
@@ -122,7 +175,17 @@ func (h *KnowledgeHandler) ListDocuments(c *gin.Context) {
 	c.JSON(http.StatusOK, gin.H{"success": true, "data": list})
 }
 
-// UploadDocument 上传文档到知识库
+// @Summary 上传文档
+// @Description 上传文档到指定知识库
+// @Tags 知识库
+// @Accept multipart/form-data
+// @Produce json
+// @Param id path string true "知识库ID"
+// @Param file formData file true "文档文件"
+// @Success 200 {object} map[string]interface{}
+// @Failure 400 {object} map[string]string
+// @Failure 500 {object} map[string]string
+// @Router /api/knowledge/{id}/documents [post]
 func (h *KnowledgeHandler) UploadDocument(c *gin.Context) {
 	id := c.Param("id")
 	if id == "" {
@@ -161,7 +224,17 @@ func (h *KnowledgeHandler) UploadDocument(c *gin.Context) {
 	})
 }
 
-// DeleteDocument 删除文档
+// @Summary 删除文档
+// @Description 删除知识库中的指定文档
+// @Tags 知识库
+// @Accept json
+// @Produce json
+// @Param id path string true "知识库ID"
+// @Param doc_id path string true "文档ID"
+// @Success 200 {object} map[string]interface{}
+// @Failure 400 {object} map[string]string
+// @Failure 500 {object} map[string]string
+// @Router /api/knowledge/{id}/documents/{doc_id} [delete]
 func (h *KnowledgeHandler) DeleteDocument(c *gin.Context) {
 	id := c.Param("id")
 	docID := c.Param("doc_id")
@@ -179,7 +252,17 @@ func (h *KnowledgeHandler) DeleteDocument(c *gin.Context) {
 	c.JSON(http.StatusOK, gin.H{"success": true, "message": "Document deleted"})
 }
 
-// ReparseDocument 重新解析文档
+// @Summary 重新解析文档
+// @Description 重新解析指定文档（用于更新解析结果）
+// @Tags 知识库
+// @Accept json
+// @Produce json
+// @Param id path string true "知识库ID"
+// @Param doc_id path string true "文档ID"
+// @Success 200 {object} map[string]interface{}
+// @Failure 400 {object} map[string]string
+// @Failure 500 {object} map[string]string
+// @Router /api/knowledge/{id}/documents/{doc_id}/reparse [post]
 func (h *KnowledgeHandler) ReparseDocument(c *gin.Context) {
 	id := c.Param("id")
 	docID := c.Param("doc_id")
@@ -197,7 +280,18 @@ func (h *KnowledgeHandler) ReparseDocument(c *gin.Context) {
 	c.JSON(http.StatusOK, gin.H{"success": true, "message": "Document reparse started"})
 }
 
-// GetDocumentPreview 获取文档预览
+// @Summary 获取文档预览
+// @Description 获取文档的解析预览内容
+// @Tags 知识库
+// @Accept json
+// @Produce json
+// @Param id path string true "知识库ID"
+// @Param doc_id path string true "文档ID"
+// @Param page query int false "页码"
+// @Success 200 {object} map[string]interface{}
+// @Failure 400 {object} map[string]string
+// @Failure 500 {object} map[string]string
+// @Router /api/knowledge/{id}/documents/{doc_id}/preview [get]
 func (h *KnowledgeHandler) GetDocumentPreview(c *gin.Context) {
 	id := c.Param("id")
 	docID := c.Param("doc_id")

server/internal/handler/model_handler.go

@@ -17,7 +17,14 @@ func NewModelHandler(svc *service.ModelService) *ModelHandler {
 	return &ModelHandler{service: svc}
 }
 
-// List 获取列表
+// @Summary 获取模型列表
+// @Description 获取所有已添加的AI模型列表
+// @Tags 模型管理
+// @Accept json
+// @Produce json
+// @Success 200 {object} map[string]interface{}
+// @Failure 500 {object} map[string]string
+// @Router /model/list [get]
 func (h *ModelHandler) List(c *gin.Context) {
 	list, err := h.service.List()
 	if err != nil {
@@ -32,7 +39,15 @@ func (h *ModelHandler) List(c *gin.Context) {
 	c.JSON(http.StatusOK, gin.H{"list": list})
 }
 
-// GetByID 获取详情
+// @Summary 获取模型详情
+// @Description 根据ID获取模型详细信息
+// @Tags 模型管理
+// @Accept json
+// @Produce json
+// @Param id path string true "模型ID"
+// @Success 200 {object} model.ModelInfo
+// @Failure 404 {object} map[string]string
+// @Router /model/{id} [get]
 func (h *ModelHandler) GetByID(c *gin.Context) {
 	id := c.Param("id")
 	model, err := h.service.GetByID(id)
@@ -43,7 +58,16 @@ func (h *ModelHandler) GetByID(c *gin.Context) {
 	c.JSON(http.StatusOK, model)
 }
 
-// Create 创建
+// @Summary 添加模型
+// @Description 添加新的AI模型配置
+// @Tags 模型管理
+// @Accept json
+// @Produce json
+// @Param request body model.CreateModelRequest true "模型信息"
+// @Success 200 {object} map[string]interface{}
+// @Failure 400 {object} map[string]string
+// @Failure 500 {object} map[string]string
+// @Router /model/add [post]
 func (h *ModelHandler) Create(c *gin.Context) {
 	var req model.CreateModelRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
@@ -60,7 +84,17 @@ func (h *ModelHandler) Create(c *gin.Context) {
 	c.JSON(http.StatusOK, result)
 }
 
-// Update 更新
+// @Summary 更新模型
+// @Description 更新指定模型的信息
+// @Tags 模型管理
+// @Accept json
+// @Produce json
+// @Param id path string true "模型ID"
+// @Param request body model.UpdateModelRequest true "更新信息"
+// @Success 200 {object} map[string]interface{}
+// @Failure 400 {object} map[string]string
+// @Failure 500 {object} map[string]string
+// @Router /model/{id} [put]
 func (h *ModelHandler) Update(c *gin.Context) {
 	id := c.Param("id")
 	var req model.UpdateModelRequest
@@ -78,7 +112,15 @@ func (h *ModelHandler) Update(c *gin.Context) {
 	c.JSON(http.StatusOK, result)
 }
 
-// Delete 删除
+// @Summary 删除模型
+// @Description 删除指定的AI模型
+// @Tags 模型管理
+// @Accept json
+// @Produce json
+// @Param id path string true "模型ID"
+// @Success 200 {object} map[string]bool
+// @Failure 500 {object} map[string]string
+// @Router /model/{id} [delete]
 func (h *ModelHandler) Delete(c *gin.Context) {
 	id := c.Param("id")
 	err := h.service.Delete(id)
@@ -90,7 +132,16 @@ func (h *ModelHandler) Delete(c *gin.Context) {
 	c.JSON(http.StatusOK, gin.H{"success": true})
 }
 
-// Test 测试连接
+// @Summary 测试模型连接
+// @Description 测试AI模型连接是否正常
+// @Tags 模型管理
+// @Accept json
+// @Produce json
+// @Param request body model.TestModelRequest true "模型测试请求"
+// @Success 200 {object} map[string]interface{}
+// @Failure 400 {object} map[string]string
+// @Failure 500 {object} map[string]string
+// @Router /model/test [post]
 func (h *ModelHandler) Test(c *gin.Context) {
 	var req model.TestModelRequest
 	if err := c.ShouldBindJSON(&req); err != nil {

server/internal/handler/neo4j_handler.go

@@ -17,7 +17,16 @@ func NewNeo4jHandler(svc *service.Neo4jService) *Neo4jHandler {
 	return &Neo4jHandler{service: svc}
 }
 
-// Check 检查 Neo4j 连接
+// @Summary 检查 Neo4j 连接
+// @Description 测试 Neo4j 数据库连接是否正常
+// @Tags Neo4j
+// @Accept json
+// @Produce json
+// @Param request body model.Neo4jCheckRequest true "Neo4j连接信息"
+// @Success 200 {object} map[string]interface{}
+// @Failure 400 {object} map[string]string
+// @Failure 500 {object} map[string]string
+// @Router /neo4j/check [post]
 func (h *Neo4jHandler) Check(c *gin.Context) {
 	var req model.Neo4jCheckRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
@@ -34,7 +43,16 @@ func (h *Neo4jHandler) Check(c *gin.Context) {
 	c.JSON(http.StatusOK, result)
 }
 
-// GetGraphs 获取图谱概览数据
+// @Summary 获取图谱概览
+// @Description 获取 Neo4j 中的图谱概览数据
+// @Tags Neo4j
+// @Accept json
+// @Produce json
+// @Param request body model.Neo4jGraphRequest true "图谱查询请求"
+// @Success 200 {object} map[string]interface{}
+// @Failure 400 {object} map[string]string
+// @Failure 500 {object} map[string]string
+// @Router /neo4j/graphs [post]
 func (h *Neo4jHandler) GetGraphs(c *gin.Context) {
 	var req model.Neo4jGraphRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
@@ -51,7 +69,16 @@ func (h *Neo4jHandler) GetGraphs(c *gin.Context) {
 	c.JSON(http.StatusOK, result)
 }
 
-// GetNodes 获取节点详情
+// @Summary 获取节点列表
+// @Description 获取 Neo4j 中的节点详情
+// @Tags Neo4j
+// @Accept json
+// @Produce json
+// @Param request body model.Neo4jNodeRequest true "节点查询请求"
+// @Success 200 {object} map[string]interface{}
+// @Failure 400 {object} map[string]string
+// @Failure 500 {object} map[string]string
+// @Router /neo4j/nodes [post]
 func (h *Neo4jHandler) GetNodes(c *gin.Context) {
 	var req model.Neo4jNodeRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
@@ -68,7 +95,16 @@ func (h *Neo4jHandler) GetNodes(c *gin.Context) {
 	c.JSON(http.StatusOK, result)
 }
 
-// GetRelationships 获取关系详情
+// @Summary 获取关系列表
+// @Description 获取 Neo4j 中的关系详情
+// @Tags Neo4j
+// @Accept json
+// @Produce json
+// @Param request body model.Neo4jRelRequest true "关系查询请求"
+// @Success 200 {object} map[string]interface{}
+// @Failure 400 {object} map[string]string
+// @Failure 500 {object} map[string]string
+// @Router /neo4j/relationships [post]
 func (h *Neo4jHandler) GetRelationships(c *gin.Context) {
 	var req model.Neo4jRelRequest
 	if err := c.ShouldBindJSON(&req); err != nil {

server/internal/handler/sub_table_handler.go

@@ -17,7 +17,16 @@ func NewSubTableHandler(svc *service.SubTableService) *SubTableHandler {
 	return &SubTableHandler{service: svc}
 }
 
-// Create 创建子表信息
+// @Summary 创建子表映射
+// @Description 添加数据库的子表映射关系
+// @Tags 子表管理
+// @Accept json
+// @Produce json
+// @Param request body model.CreateSubTableRequest true "子表信息"
+// @Success 201 {object} model.SubTableInfo
+// @Failure 400 {object} map[string]string
+// @Failure 500 {object} map[string]string
+// @Router /sub-table/add [post]
 func (h *SubTableHandler) Create(c *gin.Context) {
 	var req model.CreateSubTableRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
@@ -34,7 +43,15 @@ func (h *SubTableHandler) Create(c *gin.Context) {
 	c.JSON(http.StatusCreated, info)
 }
 
-// GetByID 获取详情
+// @Summary 获取子表详情
+// @Description 根据ID获取子表映射详情
+// @Tags 子表管理
+// @Accept json
+// @Produce json
+// @Param id path string true "子表ID"
+// @Success 200 {object} model.SubTableInfo
+// @Failure 404 {object} map[string]string
+// @Router /sub-table/{id} [get]
 func (h *SubTableHandler) GetByID(c *gin.Context) {
 	id := c.Param("id")
 
@@ -47,7 +64,15 @@ func (h *SubTableHandler) GetByID(c *gin.Context) {
 	c.JSON(http.StatusOK, info)
 }
 
-// ListByDatabase 获取数据库下所有子表
+// @Summary 获取数据库下所有子表
+// @Description 获取指定数据库的所有子表映射列表
+// @Tags 子表管理
+// @Accept json
+// @Produce json
+// @Param database_id path string true "数据库ID"
+// @Success 200 {object} map[string]interface{}
+// @Failure 500 {object} map[string]string
+// @Router /sub-table/database/{database_id} [get]
 func (h *SubTableHandler) ListByDatabase(c *gin.Context) {
 	databaseID := c.Param("database_id")
 
@@ -64,7 +89,15 @@ func (h *SubTableHandler) ListByDatabase(c *gin.Context) {
 	c.JSON(http.StatusOK, gin.H{"list": list})
 }
 
-// GetMappingFromFile 从文件获取映射
+// @Summary 从文件获取映射
+// @Description 从文件中读取子表映射关系
+// @Tags 子表管理
+// @Accept json
+// @Produce json
+// @Param database_id path string true "数据库ID"
+// @Success 200 {object} map[string]interface{}
+// @Failure 500 {object} map[string]string
+// @Router /sub-table/mapping/{database_id} [get]
 func (h *SubTableHandler) GetMappingFromFile(c *gin.Context) {
 	databaseID := c.Param("database_id")
 
@@ -82,7 +115,17 @@ func (h *SubTableHandler) GetMappingFromFile(c *gin.Context) {
 	c.JSON(http.StatusOK, gin.H{"mapping": mapping})
 }
 
-// Update 更新
+// @Summary 更新子表映射
+// @Description 更新子表映射信息
+// @Tags 子表管理
+// @Accept json
+// @Produce json
+// @Param id path string true "子表ID"
+// @Param request body model.UpdateSubTableRequest true "更新信息"
+// @Success 200 {object} model.SubTableInfo
+// @Failure 400 {object} map[string]string
+// @Failure 404 {object} map[string]string
+// @Router /sub-table/{id} [put]
 func (h *SubTableHandler) Update(c *gin.Context) {
 	id := c.Param("id")
 
@@ -101,7 +144,15 @@ func (h *SubTableHandler) Update(c *gin.Context) {
 	c.JSON(http.StatusOK, info)
 }
 
-// Delete 删除
+// @Summary 删除子表映射
+// @Description 删除指定的子表映射
+// @Tags 子表管理
+// @Accept json
+// @Produce json
+// @Param id path string true "子表ID"
+// @Success 200 {object} map[string]string
+// @Failure 404 {object} map[string]string
+// @Router /sub-table/{id} [delete]
 func (h *SubTableHandler) Delete(c *gin.Context) {
 	id := c.Param("id")
 
@@ -114,7 +165,15 @@ func (h *SubTableHandler) Delete(c *gin.Context) {
 	c.JSON(http.StatusOK, gin.H{"message": "deleted"})
 }
 
-// GetTablesDDL 获取数据库下所有表及DDL
+// @Summary 获取表结构DDL
+// @Description 获取数据库下所有表的DDL语句
+// @Tags 子表管理
+// @Accept json
+// @Produce json
+// @Param database_id path string true "数据库ID"
+// @Success 200 {object} map[string]interface{}
+// @Failure 500 {object} map[string]string
+// @Router /sub-table/ddl/{database_id} [get]
 func (h *SubTableHandler) GetTablesDDL(c *gin.Context) {
 	databaseID := c.Param("database_id")
 

server/internal/handler/system_handler.go

@@ -14,7 +14,14 @@ func NewSystemHandler() *SystemHandler {
 	return &SystemHandler{}
 }
 
-// GetSystemInfo 获取系统信息
+// @Summary 获取系统信息
+// @Description 获取服务器系统信息（CPU、内存等）
+// @Tags 系统
+// @Accept json
+// @Produce json
+// @Success 200 {object} model.SystemInfo
+// @Failure 500 {object} map[string]string
+// @Router /system/info [get]
 func (h *SystemHandler) GetSystemInfo(c *gin.Context) {
 	info, err := getSystemInfo()
 	if err != nil {

server/internal/handler/upload_handler.go

@@ -20,7 +20,16 @@ func NewUploadHandler(uploadService *service.UploadService, knowledgeRepo *repos
 	return &UploadHandler{uploadService: uploadService, knowledgeRepo: knowledgeRepo}
 }
 
-// Upload 上传文件
+// @Summary 上传文件
+// @Description 上传文件到服务器（本地存储或MinIO）
+// @Tags 文件上传
+// @Accept multipart/form-data
+// @Produce json
+// @Param file formData file true "要上传的文件"
+// @Success 200 {object} map[string]interface{}
+// @Failure 400 {object} map[string]string
+// @Failure 500 {object} map[string]string
+// @Router /api/file_upload [post]
 func (h *UploadHandler) Upload(c *gin.Context) {
 	file, err := c.FormFile("file")
 	if err != nil {
@@ -48,7 +57,16 @@ func (h *UploadHandler) Upload(c *gin.Context) {
 	c.JSON(http.StatusOK, result)
 }
 
-// Delete 删除文件
+// @Summary 删除文件
+// @Description 删除指定文件
+// @Tags 文件上传
+// @Accept json
+// @Produce json
+// @Param filename path string true "文件名"
+// @Success 200 {object} map[string]interface{}
+// @Failure 400 {object} map[string]string
+// @Failure 500 {object} map[string]string
+// @Router /api/file_upload/{filename} [delete]
 func (h *UploadHandler) Delete(c *gin.Context) {
 	filename := c.Param("filename")
 	if filename == "" {
@@ -64,7 +82,17 @@ func (h *UploadHandler) Delete(c *gin.Context) {
 	c.JSON(http.StatusOK, gin.H{"success": true, "message": "File deleted"})
 }
 
-// ProxyFile 代理文件访问（解决 MinIO 内网地址和 HTTPS 问题）
+// @Summary 代理文件访问
+// @Description 代理访问文件，解决 MinIO 内网和 HTTPS 问题
+// @Tags 文件上传
+// @Accept json
+// @Produce octet-stream
+// @Param key query string true "文件Key"
+// @Param kb_id query string false "知识库ID"
+// @Success 200 {file} binary
+// @Failure 400 {object} map[string]string
+// @Failure 500 {object} map[string]string
+// @Router /api/file_proxy [get]
 func (h *UploadHandler) ProxyFile(c *gin.Context) {
 	fileKey := c.Query("key")
 	kbID := c.Query("kb_id")