仓库自包含化：Docker/CI/文档/规范入库，路由分组拆分

internal/api/task.go

@@ -29,6 +29,12 @@ type updateTaskRequest struct {
 	Status   *string         `json:"status"`
 }
 
+// @Summary  创建任务
+// @Tags     任务与日志回传
+// @Param    body body createTaskRequest true "任务定义(类型/cron/payload)"
+// @Success  201 {object} map[string]any
+// @Security BearerAuth
+// @Router   /api/v1/tasks [post]
 func (h *taskHandler) create(c *gin.Context) {
 	var req createTaskRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
@@ -48,6 +54,11 @@ func (h *taskHandler) create(c *gin.Context) {
 	c.JSON(http.StatusCreated, task)
 }
 
+// @Summary  任务列表
+// @Tags     任务与日志回传
+// @Success  200 {array} map[string]any
+// @Security BearerAuth
+// @Router   /api/v1/tasks [get]
 func (h *taskHandler) list(c *gin.Context) {
 	tasks, err := h.svc.ListTasks(c.Request.Context())
 	if err != nil {
@@ -57,6 +68,12 @@ func (h *taskHandler) list(c *gin.Context) {
 	c.JSON(http.StatusOK, tasks)
 }
 
+// @Summary  任务详情
+// @Tags     任务与日志回传
+// @Param    id path int true "任务 ID"
+// @Success  200 {object} map[string]any
+// @Security BearerAuth
+// @Router   /api/v1/tasks/{id} [get]
 func (h *taskHandler) get(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
@@ -70,6 +87,13 @@ func (h *taskHandler) get(c *gin.Context) {
 	c.JSON(http.StatusOK, task)
 }
 
+// @Summary  更新任务
+// @Tags     任务与日志回传
+// @Param    id path int true "任务 ID"
+// @Param    body body updateTaskRequest true "可更新字段"
+// @Success  200 {object} map[string]any
+// @Security BearerAuth
+// @Router   /api/v1/tasks/{id} [put]
 func (h *taskHandler) update(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
@@ -93,6 +117,12 @@ func (h *taskHandler) update(c *gin.Context) {
 	c.JSON(http.StatusOK, task)
 }
 
+// @Summary  删除任务
+// @Tags     任务与日志回传
+// @Param    id path int true "任务 ID"
+// @Success  204 "无内容"
+// @Security BearerAuth
+// @Router   /api/v1/tasks/{id} [delete]
 func (h *taskHandler) remove(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
@@ -105,6 +135,12 @@ func (h *taskHandler) remove(c *gin.Context) {
 	c.Status(http.StatusNoContent)
 }
 
+// @Summary  任务执行日志
+// @Tags     任务与日志回传
+// @Param    id path int true "配置 ID"
+// @Success  200 {object} map[string]any
+// @Security BearerAuth
+// @Router   /api/v1/tasks/{id}/logs [get]
 func (h *taskHandler) logs(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
@@ -119,6 +155,12 @@ func (h *taskHandler) logs(c *gin.Context) {
 	c.JSON(http.StatusOK, logs)
 }
 
+// @Summary  立即执行任务
+// @Tags     任务与日志回传
+// @Param    id path int true "配置 ID"
+// @Success  200 {object} map[string]any
+// @Security BearerAuth
+// @Router   /api/v1/tasks/{id}/run [post]
 func (h *taskHandler) run(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {