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

internal/api/proxy.go

@@ -15,6 +15,12 @@ type proxyHandler struct {
 }
 
 // list 返回全部代理(脱敏视图,含引用计数)。
+//
+// @Summary  代理列表
+// @Tags     设置
+// @Success  200 {object} map[string]any "items"
+// @Security BearerAuth
+// @Router   /api/v1/proxies [get]
 func (h *proxyHandler) list(c *gin.Context) {
 	items, err := h.svc.List(c.Request.Context())
 	if err != nil {
@@ -25,6 +31,13 @@ func (h *proxyHandler) list(c *gin.Context) {
 }
 
 // create 新建代理。
+//
+// @Summary  创建代理
+// @Tags     设置
+// @Param    body body service.ProxyInput true "代理配置(密码只写不回)"
+// @Success  201 {object} map[string]any
+// @Security BearerAuth
+// @Router   /api/v1/proxies [post]
 func (h *proxyHandler) create(c *gin.Context) {
 	var req service.ProxyInput
 	if err := c.ShouldBindJSON(&req); err != nil {
@@ -40,6 +53,14 @@ func (h *proxyHandler) create(c *gin.Context) {
 }
 
 // update 更新代理;密码缺省沿用、空串清除。
+//
+// @Summary  更新代理
+// @Tags     设置
+// @Param    id path int true "代理 ID"
+// @Param    body body service.ProxyInput true "代理配置(密码缺省沿用)"
+// @Success  200 {object} map[string]any
+// @Security BearerAuth
+// @Router   /api/v1/proxies/{id} [put]
 func (h *proxyHandler) update(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
@@ -59,6 +80,13 @@ func (h *proxyHandler) update(c *gin.Context) {
 }
 
 // remove 删除代理;仍被租户引用时返回 409。
+//
+// @Summary  删除代理
+// @Tags     设置
+// @Param    id path int true "代理 ID"
+// @Success  204 "无内容"
+// @Security BearerAuth
+// @Router   /api/v1/proxies/{id} [delete]
 func (h *proxyHandler) remove(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {
@@ -72,6 +100,13 @@ func (h *proxyHandler) remove(c *gin.Context) {
 }
 
 // importBatch 批量导入代理;逐行解析,返回成功与脱敏后的失败明细。
+//
+// @Summary  批量导入代理
+// @Tags     设置
+// @Param    body body object true "请求体(见接口说明)"
+// @Success  200 {object} map[string]any
+// @Security BearerAuth
+// @Router   /api/v1/proxies/import [post]
 func (h *proxyHandler) importBatch(c *gin.Context) {
 	var req struct {
 		Text string `json:"text" binding:"required"`
@@ -89,6 +124,13 @@ func (h *proxyHandler) importBatch(c *gin.Context) {
 }
 
 // probe 手动重测代理出口地区,同步返回最新视图。
+//
+// @Summary  手动重测代理出口地区,同步返回最新视图
+// @Tags     设置
+// @Param    id path int true "配置 ID"
+// @Success  200 {object} map[string]any
+// @Security BearerAuth
+// @Router   /api/v1/proxies/{id}/probe [post]
 func (h *proxyHandler) probe(c *gin.Context) {
 	id, ok := pathID(c)
 	if !ok {