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

internal/api/logevent.go

@@ -16,6 +16,13 @@ type logEventHandler struct {
 }
 
 // getWebhook 查询配置的回调地址;未生成时 exists 为 false 且不含 secret。
+//
+// @Summary  查询配置的回调地址
+// @Tags     任务与日志回传
+// @Param    id path int true "配置 ID"
+// @Success  200 {object} map[string]any
+// @Security BearerAuth
+// @Router   /api/v1/oci-configs/{id}/log-webhook [get]
 func (h *logEventHandler) getWebhook(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
@@ -34,6 +41,13 @@ func (h *logEventHandler) getWebhook(c *gin.Context) {
 }
 
 // ensureWebhook 生成(或幂等返回)配置的回传 secret 与回调路径。
+//
+// @Summary  生成
+// @Tags     任务与日志回传
+// @Param    id path int true "配置 ID"
+// @Success  200 {object} map[string]any
+// @Security BearerAuth
+// @Router   /api/v1/oci-configs/{id}/log-webhook [post]
 func (h *logEventHandler) ensureWebhook(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
@@ -48,6 +62,13 @@ func (h *logEventHandler) ensureWebhook(c *gin.Context) {
 }
 
 // revokeWebhook 撤销配置的回传 secret,旧回调地址随即失效。
+//
+// @Summary  撤销配置的回传 secret,旧回调地址随即失效
+// @Tags     任务与日志回传
+// @Param    id path int true "配置 ID"
+// @Success  204 "无内容"
+// @Security BearerAuth
+// @Router   /api/v1/oci-configs/{id}/log-webhook [delete]
 func (h *logEventHandler) revokeWebhook(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
@@ -61,6 +82,14 @@ func (h *logEventHandler) revokeWebhook(c *gin.Context) {
 }
 
 // list 分页查询回传事件;cfgId 缺省为全部租户。
+//
+// @Summary  回传日志事件列表
+// @Tags     任务与日志回传
+// @Param    configId query int false "按配置过滤"
+// @Param    q query string false "关键字"
+// @Success  200 {object} map[string]any "items 与 total"
+// @Security BearerAuth
+// @Router   /api/v1/log-events [get]
 func (h *logEventHandler) list(c *gin.Context) {
 	cfgID, _ := strconv.ParseUint(c.Query("cfgId"), 10, 64)
 	page, _ := strconv.Atoi(c.Query("page"))
@@ -78,6 +107,13 @@ func (h *logEventHandler) list(c *gin.Context) {
 }
 
 // getRelay 查询 OCI 侧链路状态与关键事件清单。
+//
+// @Summary  查询 OCI 侧链路状态与关键事件清单
+// @Tags     任务与日志回传
+// @Param    id path int true "配置 ID"
+// @Success  200 {object} map[string]any
+// @Security BearerAuth
+// @Router   /api/v1/oci-configs/{id}/log-relay [get]
 func (h *logEventHandler) getRelay(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
@@ -92,6 +128,13 @@ func (h *logEventHandler) getRelay(c *gin.Context) {
 }
 
 // setupRelay 一键建立回传链路(P1 引导创建);同步执行,前端以长超时等待。
+//
+// @Summary  一键建立回传链路
+// @Tags     任务与日志回传
+// @Param    id path int true "配置 ID"
+// @Success  200 {object} map[string]any
+// @Security BearerAuth
+// @Router   /api/v1/oci-configs/{id}/log-relay [post]
 func (h *logEventHandler) setupRelay(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
@@ -106,6 +149,13 @@ func (h *logEventHandler) setupRelay(c *gin.Context) {
 }
 
 // teardownRelay 逆序销毁链路并撤销 secret。
+//
+// @Summary  逆序销毁链路并撤销 secret
+// @Tags     任务与日志回传
+// @Param    id path int true "配置 ID"
+// @Success  204 "无内容"
+// @Security BearerAuth
+// @Router   /api/v1/oci-configs/{id}/log-relay [delete]
 func (h *logEventHandler) teardownRelay(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {