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

internal/api/auth.go

@@ -24,6 +24,17 @@ type loginRequest struct {
 	TotpCode string `json:"totpCode"`
 }
 
+// login 校验用户名密码(与可选 TOTP)后签发 JWT。
+//
+// @Summary  登录
+// @Tags     认证
+// @Accept   json
+// @Produce  json
+// @Param    body body loginRequest true "登录凭据"
+// @Success  200 {object} map[string]any "token 与 expiresAt"
+// @Failure  401 {object} map[string]string "凭据错误"
+// @Failure  428 {object} map[string]any "需要两步验证码(totpRequired=true)"
+// @Router   /api/v1/auth/login [post]
 func (h *authHandler) login(c *gin.Context) {
 	var req loginRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
@@ -61,6 +72,12 @@ func (h *authHandler) login(c *gin.Context) {
 }
 
 // logout 把当前令牌拉黑至自然过期(secured 组内,写请求由系统日志中间件留痕)。
+//
+// @Summary  登出
+// @Tags     认证
+// @Success  204 "令牌已吊销"
+// @Security BearerAuth
+// @Router   /api/v1/auth/logout [post]
 func (h *authHandler) logout(c *gin.Context) {
 	token, ok := strings.CutPrefix(c.GetHeader("Authorization"), "Bearer ")
 	if ok && token != "" {