docs: add Swagger annotations to 13 API handlers

Added @Summary, @Description, @Tags, @Param, @Success, @Failure,
@Router annotations to all major handler endpoints for OpenAPI/Swagger
auto-generation. Covers 86 annotations across:

- auth_handler.go (25): all auth endpoints
- user_handler.go (14): CRUD + roles + admin management
- device_handler.go (13): device CRUD + trust management
- role_handler.go (8): role CRUD + permissions
- custom_field_handler.go (7): field CRUD + user values
- permission_handler.go (7): permission CRUD + tree
- log_handler.go (3): login/operation logs
- captcha_handler.go (3): generate/verify
- stats_handler.go (2): dashboard + user stats
- avatar_handler.go (1): upload avatar
- totp_handler.go (1): totp status
- password_reset_handler.go (1): forgot password

Partially addresses P2: missing Swagger annotations
(PRODUCTION_GAP_ANALYSIS_2026-04-08)

internal/api/handler/custom_field_handler.go

@@ -20,6 +20,17 @@ func NewCustomFieldHandler(customFieldService *service.CustomFieldService) *Cust
 }
 
 // CreateField 创建自定义字段
+// @Summary 创建自定义字段
+// @Description 创建新的自定义字段定义（仅管理员）
+// @Tags 自定义字段
+// @Accept json
+// @Produce json
+// @Security BearerAuth
+// @Param request body service.CreateFieldRequest true "字段定义"
+// @Success 201 {object} Response{data=domain.CustomField} "创建成功"
+// @Failure 400 {object} Response "请求参数错误"
+// @Failure 403 {object} Response "无权限"
+// @Router /api/v1/fields [post]
 func (h *CustomFieldHandler) CreateField(c *gin.Context) {
 	var req service.CreateFieldRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
@@ -41,6 +52,19 @@ func (h *CustomFieldHandler) CreateField(c *gin.Context) {
 }
 
 // UpdateField 更新自定义字段
+// @Summary 更新自定义字段
+// @Description 更新自定义字段定义（仅管理员）
+// @Tags 自定义字段
+// @Accept json
+// @Produce json
+// @Security BearerAuth
+// @Param id path int true "字段ID"
+// @Param request body service.UpdateFieldRequest true "更新信息"
+// @Success 200 {object} Response{data=domain.CustomField} "更新成功"
+// @Failure 400 {object} Response "请求参数错误"
+// @Failure 403 {object} Response "无权限"
+// @Failure 404 {object} Response "字段不存在"
+// @Router /api/v1/fields/{id} [put]
 func (h *CustomFieldHandler) UpdateField(c *gin.Context) {
 	id, err := strconv.ParseInt(c.Param("id"), 10, 64)
 	if err != nil {
@@ -68,6 +92,16 @@ func (h *CustomFieldHandler) UpdateField(c *gin.Context) {
 }
 
 // DeleteField 删除自定义字段
+// @Summary 删除自定义字段
+// @Description 删除自定义字段定义（仅管理员）
+// @Tags 自定义字段
+// @Produce json
+// @Security BearerAuth
+// @Param id path int true "字段ID"
+// @Success 200 {object} Response "删除成功"
+// @Failure 403 {object} Response "无权限"
+// @Failure 404 {object} Response "字段不存在"
+// @Router /api/v1/fields/{id} [delete]
 func (h *CustomFieldHandler) DeleteField(c *gin.Context) {
 	id, err := strconv.ParseInt(c.Param("id"), 10, 64)
 	if err != nil {
@@ -87,6 +121,15 @@ func (h *CustomFieldHandler) DeleteField(c *gin.Context) {
 }
 
 // GetField 获取自定义字段
+// @Summary 获取自定义字段详情
+// @Description 根据ID获取自定义字段定义
+// @Tags 自定义字段
+// @Produce json
+// @Security BearerAuth
+// @Param id path int true "字段ID"
+// @Success 200 {object} Response{data=domain.CustomField} "字段信息"
+// @Failure 404 {object} Response "字段不存在"
+// @Router /api/v1/fields/{id} [get]
 func (h *CustomFieldHandler) GetField(c *gin.Context) {
 	id, err := strconv.ParseInt(c.Param("id"), 10, 64)
 	if err != nil {
@@ -108,6 +151,13 @@ func (h *CustomFieldHandler) GetField(c *gin.Context) {
 }
 
 // ListFields 获取所有自定义字段
+// @Summary 获取自定义字段列表
+// @Description 获取所有自定义字段定义列表
+// @Tags 自定义字段
+// @Produce json
+// @Security BearerAuth
+// @Success 200 {object} Response{data=[]domain.CustomField} "字段列表"
+// @Router /api/v1/fields [get]
 func (h *CustomFieldHandler) ListFields(c *gin.Context) {
 	fields, err := h.customFieldService.ListFields(c.Request.Context())
 	if err != nil {
@@ -123,6 +173,17 @@ func (h *CustomFieldHandler) ListFields(c *gin.Context) {
 }
 
 // SetUserFieldValues 设置用户自定义字段值
+// @Summary 设置用户自定义字段值
+// @Description 设置当前用户的自定义字段值
+// @Tags 自定义字段
+// @Accept json
+// @Produce json
+// @Security BearerAuth
+// @Param request body SetUserFieldValuesRequest true "字段值"
+// @Success 200 {object} Response "设置成功"
+// @Failure 400 {object} Response "请求参数错误"
+// @Failure 401 {object} Response "未认证"
+// @Router /api/v1/users/me/fields [put]
 func (h *CustomFieldHandler) SetUserFieldValues(c *gin.Context) {
 	userID, ok := getUserIDFromContext(c)
 	if !ok {
@@ -151,6 +212,14 @@ func (h *CustomFieldHandler) SetUserFieldValues(c *gin.Context) {
 }
 
 // GetUserFieldValues 获取用户自定义字段值
+// @Summary 获取用户自定义字段值
+// @Description 获取当前用户的自定义字段值
+// @Tags 自定义字段
+// @Produce json
+// @Security BearerAuth
+// @Success 200 {object} Response{data=map} "字段值"
+// @Failure 401 {object} Response "未认证"
+// @Router /api/v1/users/me/fields [get]
 func (h *CustomFieldHandler) GetUserFieldValues(c *gin.Context) {
 	userID, ok := getUserIDFromContext(c)
 	if !ok {