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

internal/api/aiadmin.go

@@ -16,6 +16,11 @@ type aiAdminHandler struct {
 
 // ---- 密钥 ----
 
+// @Summary  ---- 密钥 ----
+// @Tags     AI 管理
+// @Success  200 {object} map[string]any
+// @Security BearerAuth
+// @Router   /api/v1/ai-keys [get]
 func (h *aiAdminHandler) listKeys(c *gin.Context) {
 	keys, err := h.gw.Keys(c.Request.Context())
 	if err != nil {
@@ -26,6 +31,13 @@ func (h *aiAdminHandler) listKeys(c *gin.Context) {
 }
 
 // createKey 生成密钥;明文仅在本响应返回一次。
+//
+// @Summary  生成密钥
+// @Tags     AI 管理
+// @Param    body body object true "请求体(见接口说明)"
+// @Success  201 {object} map[string]any
+// @Security BearerAuth
+// @Router   /api/v1/ai-keys [post]
 func (h *aiAdminHandler) createKey(c *gin.Context) {
 	var req struct {
 		Name  string `json:"name" binding:"required"`
@@ -44,6 +56,13 @@ func (h *aiAdminHandler) createKey(c *gin.Context) {
 	c.JSON(http.StatusCreated, gin.H{"key": plaintext, "item": key})
 }
 
+// @Summary  更新 AI 网关密钥
+// @Tags     AI 管理
+// @Param    id path int true "配置 ID"
+// @Param    body body object true "请求体(见接口说明)"
+// @Success  204 "无内容"
+// @Security BearerAuth
+// @Router   /api/v1/ai-keys/{id} [put]
 func (h *aiAdminHandler) updateKey(c *gin.Context) {
 	id, ok := aiPathID(c)
 	if !ok {
@@ -65,6 +84,12 @@ func (h *aiAdminHandler) updateKey(c *gin.Context) {
 	c.Status(http.StatusNoContent)
 }
 
+// @Summary  删除 AI 网关密钥
+// @Tags     AI 管理
+// @Param    id path int true "配置 ID"
+// @Success  204 "无内容"
+// @Security BearerAuth
+// @Router   /api/v1/ai-keys/{id} [delete]
 func (h *aiAdminHandler) deleteKey(c *gin.Context) {
 	id, ok := aiPathID(c)
 	if !ok {
@@ -78,6 +103,14 @@ func (h *aiAdminHandler) deleteKey(c *gin.Context) {
 }
 
 // updateKeyContentLog 设置密钥内容日志窗口(红线例外:显式限时开启,0 关闭)。
+//
+// @Summary  设置密钥内容日志窗口
+// @Tags     AI 管理
+// @Param    id path int true "配置 ID"
+// @Param    body body object true "请求体(见接口说明)"
+// @Success  200 {object} map[string]any
+// @Security BearerAuth
+// @Router   /api/v1/ai-keys/{id}/content-log [put]
 func (h *aiAdminHandler) updateKeyContentLog(c *gin.Context) {
 	id, ok := aiPathID(c)
 	if !ok {
@@ -99,6 +132,12 @@ func (h *aiAdminHandler) updateKeyContentLog(c *gin.Context) {
 }
 
 // listContentLogs 分页查询内容日志(可选 keyId / callLogId 过滤)。
+//
+// @Summary  分页查询内容日志
+// @Tags     AI 管理
+// @Success  200 {object} map[string]any
+// @Security BearerAuth
+// @Router   /api/v1/ai-content-logs [get]
 func (h *aiAdminHandler) listContentLogs(c *gin.Context) {
 	page, _ := strconv.Atoi(c.DefaultQuery("page", "1"))
 	size, _ := strconv.Atoi(c.DefaultQuery("size", "20"))
@@ -114,6 +153,11 @@ func (h *aiAdminHandler) listContentLogs(c *gin.Context) {
 
 // ---- 渠道 ----
 
+// @Summary  ---- 渠道 ----
+// @Tags     AI 管理
+// @Success  200 {object} map[string]any
+// @Security BearerAuth
+// @Router   /api/v1/ai-channels [get]
 func (h *aiAdminHandler) listChannels(c *gin.Context) {
 	chs, err := h.gw.Channels(c.Request.Context())
 	if err != nil {
@@ -123,6 +167,12 @@ func (h *aiAdminHandler) listChannels(c *gin.Context) {
 	c.JSON(http.StatusOK, gin.H{"items": chs})
 }
 
+// @Summary  创建 AI 渠道
+// @Tags     AI 管理
+// @Param    body body service.ChannelInput true "请求体"
+// @Success  201 {object} map[string]any
+// @Security BearerAuth
+// @Router   /api/v1/ai-channels [post]
 func (h *aiAdminHandler) createChannel(c *gin.Context) {
 	var req service.ChannelInput
 	if err := c.ShouldBindJSON(&req); err != nil {
@@ -137,6 +187,13 @@ func (h *aiAdminHandler) createChannel(c *gin.Context) {
 	c.JSON(http.StatusCreated, ch)
 }
 
+// @Summary  更新 AI 渠道
+// @Tags     AI 管理
+// @Param    id path int true "配置 ID"
+// @Param    body body service.ChannelInput true "请求体"
+// @Success  204 "无内容"
+// @Security BearerAuth
+// @Router   /api/v1/ai-channels/{id} [put]
 func (h *aiAdminHandler) updateChannel(c *gin.Context) {
 	id, ok := aiPathID(c)
 	if !ok {
@@ -154,6 +211,12 @@ func (h *aiAdminHandler) updateChannel(c *gin.Context) {
 	c.Status(http.StatusNoContent)
 }
 
+// @Summary  删除 AI 渠道
+// @Tags     AI 管理
+// @Param    id path int true "配置 ID"
+// @Success  204 "无内容"
+// @Security BearerAuth
+// @Router   /api/v1/ai-channels/{id} [delete]
 func (h *aiAdminHandler) deleteChannel(c *gin.Context) {
 	id, ok := aiPathID(c)
 	if !ok {
@@ -167,6 +230,13 @@ func (h *aiAdminHandler) deleteChannel(c *gin.Context) {
 }
 
 // probeChannel 触发探测:服务可见性 + 模型同步 + 配额试调,返回更新后的渠道。
+//
+// @Summary  触发探测:服务可见性 + 模型同步 + 配额试调,返回更新后的渠道
+// @Tags     AI 管理
+// @Param    id path int true "配置 ID"
+// @Success  200 {object} map[string]any
+// @Security BearerAuth
+// @Router   /api/v1/ai-channels/{id}/probe [post]
 func (h *aiAdminHandler) probeChannel(c *gin.Context) {
 	id, ok := aiPathID(c)
 	if !ok {
@@ -180,6 +250,12 @@ func (h *aiAdminHandler) probeChannel(c *gin.Context) {
 	c.JSON(http.StatusOK, ch)
 }
 
+// @Summary  同步渠道模型缓存
+// @Tags     AI 管理
+// @Param    id path int true "配置 ID"
+// @Success  200 {object} map[string]any
+// @Security BearerAuth
+// @Router   /api/v1/ai-channels/{id}/sync-models [post]
 func (h *aiAdminHandler) syncChannelModels(c *gin.Context) {
 	id, ok := aiPathID(c)
 	if !ok {
@@ -195,6 +271,11 @@ func (h *aiAdminHandler) syncChannelModels(c *gin.Context) {
 
 // ---- 聚合模型与调用日志 ----
 
+// @Summary  ---- 聚合模型与调用日志 ----
+// @Tags     AI 管理
+// @Success  200 {object} map[string]any
+// @Security BearerAuth
+// @Router   /api/v1/ai-models [get]
 func (h *aiAdminHandler) gatewayModels(c *gin.Context) {
 	list, err := h.gw.GatewayModels(c.Request.Context(), "")
 	if err != nil {
@@ -204,6 +285,11 @@ func (h *aiAdminHandler) gatewayModels(c *gin.Context) {
 	c.JSON(http.StatusOK, gin.H{"items": list.Data})
 }
 
+// @Summary  AI 调用日志列表
+// @Tags     AI 管理
+// @Success  200 {object} map[string]any
+// @Security BearerAuth
+// @Router   /api/v1/ai-logs [get]
 func (h *aiAdminHandler) listLogs(c *gin.Context) {
 	page, _ := strconv.Atoi(c.DefaultQuery("page", "1"))
 	size, _ := strconv.Atoi(c.DefaultQuery("size", "50"))