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

internal/api/ociconfig.go

@@ -33,6 +33,12 @@ type importRequest struct {
 	ProxyID          *uint  `json:"proxyId"`          // 关联出站代理,null 直连
 }
 
+// @Summary  导入租户配置
+// @Tags     租户配置
+// @Param    body body importRequest true "API Key 配置(私钥密文落库)"
+// @Success  201 {object} map[string]any
+// @Security BearerAuth
+// @Router   /api/v1/oci-configs [post]
 func (h *ociConfigHandler) create(c *gin.Context) {
 	var req importRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
@@ -60,6 +66,11 @@ func (h *ociConfigHandler) create(c *gin.Context) {
 	c.JSON(http.StatusCreated, cfg)
 }
 
+// @Summary  租户配置列表
+// @Tags     租户配置
+// @Success  200 {object} map[string]any "items"
+// @Security BearerAuth
+// @Router   /api/v1/oci-configs [get]
 func (h *ociConfigHandler) list(c *gin.Context) {
 	items, err := h.svc.List(c.Request.Context())
 	if err != nil {
@@ -69,6 +80,12 @@ func (h *ociConfigHandler) list(c *gin.Context) {
 	c.JSON(http.StatusOK, items)
 }
 
+// @Summary  租户配置详情
+// @Tags     租户配置
+// @Param    id path int true "配置 ID"
+// @Success  200 {object} map[string]any
+// @Security BearerAuth
+// @Router   /api/v1/oci-configs/{id} [get]
 func (h *ociConfigHandler) get(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
@@ -82,6 +99,12 @@ func (h *ociConfigHandler) get(c *gin.Context) {
 	c.JSON(http.StatusOK, cfg)
 }
 
+// @Summary  验证配置连通性并刷新画像
+// @Tags     租户配置
+// @Param    id path int true "配置 ID"
+// @Success  200 {object} map[string]any
+// @Security BearerAuth
+// @Router   /api/v1/oci-configs/{id}/verify [post]
 func (h *ociConfigHandler) verify(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
@@ -109,6 +132,13 @@ type updateConfigRequest struct {
 	ProxyID          *uint   `json:"proxyId"`          // 非 null 切换代理:0 解除,>0 关联
 }
 
+// @Summary  更新租户配置
+// @Tags     租户配置
+// @Param    id path int true "配置 ID"
+// @Param    body body object true "可更新字段(别名/分组/代理/多区域开关等)"
+// @Success  200 {object} map[string]any
+// @Security BearerAuth
+// @Router   /api/v1/oci-configs/{id} [put]
 func (h *ociConfigHandler) update(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
@@ -137,6 +167,12 @@ func (h *ociConfigHandler) update(c *gin.Context) {
 	c.JSON(http.StatusOK, gin.H{"config": cfg, "changes": changes})
 }
 
+// @Summary  删除租户配置
+// @Tags     租户配置
+// @Param    id path int true "配置 ID"
+// @Success  204 "无内容"
+// @Security BearerAuth
+// @Router   /api/v1/oci-configs/{id} [delete]
 func (h *ociConfigHandler) remove(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
@@ -150,6 +186,13 @@ func (h *ociConfigHandler) remove(c *gin.Context) {
 }
 
 // compartments 列出租户下全部 ACTIVE compartment（不含租户根）。
+//
+// @Summary  列出租户下全部 ACTIVE compartment
+// @Tags     租户配置
+// @Param    id path int true "配置 ID"
+// @Success  200 {object} map[string]any
+// @Security BearerAuth
+// @Router   /api/v1/oci-configs/{id}/compartments [get]
 func (h *ociConfigHandler) compartments(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
@@ -165,6 +208,13 @@ func (h *ociConfigHandler) compartments(c *gin.Context) {
 
 // cachedRegions 返回筛选器用区域列表：未开多区域支持只含默认区域；
 // 缓存存在非 READY 时实时刷新。
+//
+// @Summary  返回筛选器用区域列表：未开多区域支持只含默认区域
+// @Tags     租户配置
+// @Param    id path int true "配置 ID"
+// @Success  200 {object} map[string]any
+// @Security BearerAuth
+// @Router   /api/v1/oci-configs/{id}/cached-regions [get]
 func (h *ociConfigHandler) cachedRegions(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
@@ -179,6 +229,13 @@ func (h *ociConfigHandler) cachedRegions(c *gin.Context) {
 }
 
 // cachedCompartments 返回筛选器用区间列表：未开多区间支持返回空数组。
+//
+// @Summary  返回筛选器用区间列表：未开多区间支持返回空数组
+// @Tags     租户配置
+// @Param    id path int true "配置 ID"
+// @Success  200 {object} map[string]any
+// @Security BearerAuth
+// @Router   /api/v1/oci-configs/{id}/cached-compartments [get]
 func (h *ociConfigHandler) cachedCompartments(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {