Swagger 文档改为按权限分组

- @Tags 由功能维度改为 public/user/admin 权限维度
- main.go 增加全局 tag 声明与权限说明（需放在 @securitydefinitions 之前，否则会被解析器吞掉）
- 重新生成 docs/，公开 4 个、需登录 7 个、管理员 11 个接口

internal/api/api.go

@@ -88,7 +88,7 @@ type HealthResponse struct {
 
 // @Summary      Health check
 // @Description  Check service and database connectivity; returns 503 when the database is unavailable.
-// @Tags         system
+// @Tags         public
 // @Produce      json
 // @Success      200  {object}  api.HealthResponse
 // @Failure      503  {object}  api.HealthResponse

internal/auth/auth.go

@@ -55,7 +55,7 @@ type LoginResponse struct {
 
 // @Summary      Register
 // @Description  Public registration. Creates a regular user in the default user group (id 1). username is 3-50 chars and unique; email is unique; password is 6-72 chars.
-// @Tags         auth
+// @Tags         public
 // @Accept       json
 // @Produce      json
 // @Param        user  body      auth.RegisterRequest  true  "Registration payload"
@@ -108,7 +108,7 @@ func Register(db *gorm.DB) gin.HandlerFunc {
 
 // @Summary      Login
 // @Description  Login with username or email; returns a JWT (TTL from auth.token_ttl) and the user.
-// @Tags         auth
+// @Tags         public
 // @Accept       json
 // @Produce      json
 // @Param        credentials  body      auth.LoginRequest  true  "Login credentials"

internal/auth/profile.go

@@ -19,7 +19,7 @@ type UpdateProfileRequest struct {
 
 // @Summary      Get current user profile
 // @Description  Return the authenticated user's profile, including groups.
-// @Tags         profile
+// @Tags         user
 // @Produce      json
 // @Success      200  {object}  model.User
 // @Security     BearerAuth
@@ -39,7 +39,7 @@ func Me() gin.HandlerFunc {
 
 // @Summary      Update current user profile
 // @Description  Update the authenticated user's nickname, gender, and birthday. birthday accepts YYYY-MM-DD, an empty string clears it, and omitting it keeps the current value.
-// @Tags         profile
+// @Tags         user
 // @Accept       json
 // @Produce      json
 // @Param        profile  body      auth.UpdateProfileRequest  true  "Fields to update"

internal/note/note.go

@@ -27,7 +27,7 @@ type ListResponse struct {
 
 // @Summary      List notes
 // @Description  List notes ordered by id DESC. page starts at 1; page_size is 1-100, default 20.
-// @Tags         notes
+// @Tags         user
 // @Produce      json
 // @Param        page       query     int  false  "Page number, default 1"                example(1)
 // @Param        page_size  query     int  false  "Page size, default 20, max 100"  example(20)
@@ -69,7 +69,7 @@ func List(db *gorm.DB) gin.HandlerFunc {
 
 // @Summary      Create a note
 // @Description  Create a note. title is required (max 200 chars); content is optional.
-// @Tags         notes
+// @Tags         user
 // @Accept       json
 // @Produce      json
 // @Param        note  body      note.Request  true  "Note payload"
@@ -99,7 +99,7 @@ func Create(db *gorm.DB) gin.HandlerFunc {
 
 // @Summary      Get a note
 // @Description  Get a note by id.
-// @Tags         notes
+// @Tags         user
 // @Produce      json
 // @Param        id   path      int  true  "Note ID"  example(1)
 // @Success      200  {object}  model.Note
@@ -128,7 +128,7 @@ func Get(db *gorm.DB) gin.HandlerFunc {
 
 // @Summary      Update a note
 // @Description  Update title and content; validation is the same as create.
-// @Tags         notes
+// @Tags         user
 // @Accept       json
 // @Produce      json
 // @Param        id    path      int           true  "Note ID"  example(1)
@@ -173,7 +173,7 @@ func Update(db *gorm.DB) gin.HandlerFunc {
 
 // @Summary      Delete a note
 // @Description  Delete a note by id; returns 204 with no body on success.
-// @Tags         notes
+// @Tags         user
 // @Produce      json
 // @Param        id   path  int  true  "Note ID"  example(1)
 // @Success      204  "Deleted"

internal/site/site.go

@@ -22,7 +22,7 @@ type UpdateRequest struct {
 
 // @Summary      Get site settings
 // @Description  Public site settings: site name, logo URL, and footer text. Returns built-in defaults when the settings row is missing.
-// @Tags         site
+// @Tags         public
 // @Produce      json
 // @Success      200  {object}  model.SiteSetting
 // @Failure      500  {object}  httpx.ErrorResponse
@@ -45,7 +45,7 @@ func Get(db *gorm.DB) gin.HandlerFunc {
 
 // @Summary      Update site settings
 // @Description  Admin only. Update the site name, logo URL, and footer text; returns the updated settings.
-// @Tags         site
+// @Tags         admin
 // @Accept       json
 // @Produce      json
 // @Param        site  body      site.UpdateRequest  true  "Site settings"

internal/user/user.go

@@ -54,7 +54,7 @@ type ListResponse struct {
 
 // @Summary      List users
 // @Description  List users with their groups, ordered by id DESC. page starts at 1; page_size is 1-100, default 20.
-// @Tags         users
+// @Tags         admin
 // @Produce      json
 // @Param        page       query     int  false  "Page number, default 1"                example(1)
 // @Param        page_size  query     int  false  "Page size, default 20, max 100"  example(20)
@@ -100,7 +100,7 @@ func List(db *gorm.DB) gin.HandlerFunc {
 
 // @Summary      Create a user
 // @Description  Create a user and assign groups. username and email are unique; password is 6-72 chars; gender is male/female/other; birthday is YYYY-MM-DD and cannot be in the future; defaults to the regular user group (id 1) when group_ids is omitted.
-// @Tags         users
+// @Tags         admin
 // @Accept       json
 // @Produce      json
 // @Param        user  body      user.CreateRequest  true  "User payload"
@@ -178,7 +178,7 @@ func Create(db *gorm.DB) gin.HandlerFunc {
 
 // @Summary      Get a user
 // @Description  Get a user by id, including groups.
-// @Tags         users
+// @Tags         admin
 // @Produce      json
 // @Param        id   path      int  true  "User ID"  example(1)
 // @Success      200  {object}  model.User
@@ -215,7 +215,7 @@ func Get(db *gorm.DB) gin.HandlerFunc {
 
 // @Summary      Update a user
 // @Description  Update user fields. group_ids replaces all groups; a non-empty password resets the password; birthday accepts YYYY-MM-DD, an empty string clears it, and omitting it keeps the current value.
-// @Tags         users
+// @Tags         admin
 // @Accept       json
 // @Produce      json
 // @Param        id    path      int                 true  "User ID"  example(1)
@@ -326,7 +326,7 @@ func Update(db *gorm.DB) gin.HandlerFunc {
 
 // @Summary      Delete a user
 // @Description  Delete a user and their group memberships; returns 204 with no body on success.
-// @Tags         users
+// @Tags         admin
 // @Produce      json
 // @Param        id   path  int  true  "User ID"  example(1)
 // @Success      204  "Deleted"

internal/usergroup/user_group.go

@@ -28,7 +28,7 @@ type ListResponse struct {
 
 // @Summary      List user groups
 // @Description  List user groups ordered by id ASC. page starts at 1; page_size is 1-100, default 20.
-// @Tags         user-groups
+// @Tags         admin
 // @Produce      json
 // @Param        page       query     int  false  "Page number, default 1"                example(1)
 // @Param        page_size  query     int  false  "Page size, default 20, max 100"  example(20)
@@ -70,7 +70,7 @@ func List(db *gorm.DB) gin.HandlerFunc {
 
 // @Summary      Create a user group
 // @Description  Create a user group. name is required and unique (max 50 chars); description is optional (max 255 chars); id is assigned by the server.
-// @Tags         user-groups
+// @Tags         admin
 // @Accept       json
 // @Produce      json
 // @Param        group  body      usergroup.Request  true  "User group payload"
@@ -114,7 +114,7 @@ func Create(db *gorm.DB) gin.HandlerFunc {
 
 // @Summary      Get a user group
 // @Description  Get a user group by id; id 0 is the built-in admin group.
-// @Tags         user-groups
+// @Tags         admin
 // @Produce      json
 // @Param        id   path      int  true  "User group ID"  example(1)
 // @Success      200  {object}  model.UserGroup
@@ -143,7 +143,7 @@ func Get(db *gorm.DB) gin.HandlerFunc {
 
 // @Summary      Update a user group
 // @Description  Update a user group's name and description; name is required and unique.
-// @Tags         user-groups
+// @Tags         admin
 // @Accept       json
 // @Produce      json
 // @Param        id     path      int                true  "User group ID"  example(1)
@@ -189,7 +189,7 @@ func Update(db *gorm.DB) gin.HandlerFunc {
 
 // @Summary      Delete a user group
 // @Description  Delete a user group by id; returns 204 with no body on success. Returns 409 for system groups or when the group still has members.
-// @Tags         user-groups
+// @Tags         admin
 // @Produce      json
 // @Param        id   path  int  true  "User group ID"  example(2)
 // @Success      204  "Deleted"