Разрабатываешь ли административный функционал

Работа с административным функционалом

Да, я регулярно разрабатываю административные интерфейсы и backend для админ-панелей. Это важная часть production-систем, и я хочу поделиться практическим опытом.

Что я понимаю под администативным функционалом

Админ-панель — это интерфейс для управления данными в системе:

• Управление пользователями (создание, редактирование, удаление, блокировка)
• Модерация контента (посты, комментарии, отзывы)
• Управление заказами (отслеживание, отмена, возврат)
• Настройка системы (параметры, интеграции, уведомления)
• Аналитика и отчёты
• Логирование действий и безопасность

Примеры из моего опыта

1. REST API для админ-операций

@RestController
@RequestMapping("/api/v1/admin/users")
@PreAuthorize("hasRole('ADMIN')")
public class AdminUserController {
    private final AdminUserService adminUserService;
    private final AuditLogger auditLogger;
    
    // Получение списка пользователей с фильтрацией
    @GetMapping
    public Page<AdminUserDTO> listUsers(
        @RequestParam(defaultValue = "0") int page,
        @RequestParam(defaultValue = "20") int pageSize,
        @RequestParam(required = false) String status,
        @RequestParam(required = false) String email
    ) {
        return adminUserService.searchUsers(
            PageRequest.of(page, pageSize),
            status,
            email
        );
    }
    
    // Редактирование пользователя
    @PutMapping("/{userId}")
    @PreAuthorize("hasRole('ADMIN')")
    public ResponseEntity<AdminUserDTO> updateUser(
        @PathVariable String userId,
        @Valid @RequestBody UpdateUserRequest request,
        HttpServletRequest httpRequest
    ) {
        AdminUserDTO result = adminUserService.updateUser(userId, request);
        
        // Логируем административное действие
        auditLogger.logAdminAction(
            userId,
            "USER_UPDATE",
            request,
            httpRequest.getRemoteAddr()
        );
        
        return ResponseEntity.ok(result);
    }
    
    // Блокировка пользователя
    @PostMapping("/{userId}/block")
    public ResponseEntity<Void> blockUser(
        @PathVariable String userId,
        @RequestBody BlockUserRequest request
    ) {
        adminUserService.blockUser(userId, request.getReason());
        
        // Отправляем уведомление пользователю
        notificationService.notifyUserBlocked(userId, request.getReason());
        
        return ResponseEntity.ok().build();
    }
    
    // Удаление пользователя (с каскадным удалением)
    @DeleteMapping("/{userId}")
    public ResponseEntity<Void> deleteUser(@PathVariable String userId) {
        adminUserService.deleteUser(userId);
        return ResponseEntity.noContent().build();
    }
}

2. Сервис с бизнес-логикой

@Service
@Transactional
public class AdminUserService {
    private final UserRepository userRepository;
    private final AuditRepository auditRepository;
    private final UserMapper userMapper;
    
    public Page<AdminUserDTO> searchUsers(
        Pageable pageable,
        String status,
        String email
    ) {
        // Динамическое построение запроса
        Specification<User> spec = Specification
            .where(User_.status.eq(status != null ? status : null))
            .and(User_.email.like(email != null ? "%" + email + "%" : null));
        
        return userRepository.findAll(spec, pageable)
            .map(userMapper::toAdminDTO);
    }
    
    public AdminUserDTO updateUser(String userId, UpdateUserRequest request) {
        User user = userRepository.findById(userId)
            .orElseThrow(() -> new NotFoundException("User not found"));
        
        // Сохраняем старые значения для аудита
        String oldStatus = user.getStatus();
        String oldEmail = user.getEmail();
        
        // Обновляем данные
        if (request.getEmail() != null) {
            user.setEmail(request.getEmail());
        }
        if (request.getStatus() != null) {
            user.setStatus(request.getStatus());
        }
        if (request.getFullName() != null) {
            user.setFullName(request.getFullName());
        }
        
        user.setUpdatedAt(LocalDateTime.now());
        userRepository.save(user);
        
        // Логируем изменения
        auditRepository.save(AuditLog.builder()
            .action("USER_UPDATE")
            .userId(userId)
            .changes(Map.of(
                "email", Map.of("old", oldEmail, "new", user.getEmail()),
                "status", Map.of("old", oldStatus, "new", user.getStatus())
            ))
            .timestamp(LocalDateTime.now())
            .build()
        );
        
        return userMapper.toAdminDTO(user);
    }
    
    public void blockUser(String userId, String reason) {
        User user = userRepository.findById(userId)
            .orElseThrow(() -> new NotFoundException("User not found"));
        
        user.setStatus("BLOCKED");
        user.setBlockedAt(LocalDateTime.now());
        user.setBlockReason(reason);
        userRepository.save(user);
    }
    
    public void deleteUser(String userId) {
        // Проверяем, есть ли связанные данные
        if (userRepository.hasActiveOrders(userId)) {
            throw new BusinessException(
                "Невозможно удалить пользователя с активными заказами"
            );
        }
        
        // Удаляем каскадно
        userRepository.deleteById(userId);
    }
}

3. Модерация контента

@RestController
@RequestMapping("/api/v1/admin/content")
@PreAuthorize("hasRole('MODERATOR') or hasRole('ADMIN')")
public class ContentModerationController {
    private final ContentModerationService moderationService;
    
    // Получение контента на проверку
    @GetMapping("/pending-review")
    public List<PendingContentDTO> getPendingContent(
        @RequestParam(defaultValue = "0") int page,
        @RequestParam(defaultValue = "50") int pageSize
    ) {
        return moderationService.getPendingReview(page, pageSize);
    }
    
    // Одобрение контента
    @PostMapping("/{contentId}/approve")
    public ResponseEntity<Void> approveContent(
        @PathVariable String contentId,
        @RequestParam(required = false) String notes
    ) {
        moderationService.approveContent(contentId, notes);
        return ResponseEntity.ok().build();
    }
    
    // Отклонение контента
    @PostMapping("/{contentId}/reject")
    public ResponseEntity<Void> rejectContent(
        @PathVariable String contentId,
        @Valid @RequestBody RejectContentRequest request
    ) {
        moderationService.rejectContent(
            contentId,
            request.getReason(),
            request.getMessage()  // Сообщение автору
        );
        return ResponseEntity.ok().build();
    }
}

4. Управление заказами

@RestController
@RequestMapping("/api/v1/admin/orders")
@PreAuthorize("hasRole('ADMIN')")
public class AdminOrderController {
    private final AdminOrderService orderService;
    
    @PutMapping("/{orderId}/status")
    public ResponseEntity<AdminOrderDTO> updateOrderStatus(
        @PathVariable String orderId,
        @Valid @RequestBody UpdateOrderStatusRequest request
    ) {
        AdminOrderDTO order = orderService.updateStatus(
            orderId,
            request.getNewStatus(),
            request.getNotes()
        );
        
        // Отправляем уведомление клиенту
        if (shouldNotifyCustomer(request.getNewStatus())) {
            notificationService.notifyOrderStatusChanged(
                order.getCustomerId(),
                orderId,
                request.getNewStatus()
            );
        }
        
        return ResponseEntity.ok(order);
    }
    
    @PostMapping("/{orderId}/refund")
    public ResponseEntity<Void> refundOrder(
        @PathVariable String orderId,
        @Valid @RequestBody RefundRequest request
    ) {
        orderService.refundOrder(orderId, request.getReason());
        return ResponseEntity.ok().build();
    }
}

5. Безопасность admin-панели

@Configuration
public class AdminSecurityConfig {
    
    @Bean
    public SecurityFilterChain adminSecurityFilterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                // Админ-панель требует роли ADMIN
                .requestMatchers("/api/v1/admin/**")
                    .hasRole("ADMIN")
                // Модерация требует MODERATOR или ADMIN
                .requestMatchers("/api/v1/admin/content/**")
                    .hasAnyRole("MODERATOR", "ADMIN")
                // Всё остальное требует авторизации
                .anyRequest().authenticated()
            )
            // Дополнительная защита
            .sessionManagement(session -> session
                .sessionFixationProtection(SessionFixationProtectionStrategy.MIGRATEESSION)
                .sessionConcurrency(concurrency -> concurrency
                    .maximumSessions(1)  // Одна сессия на админа
                )
            )
            // CSRF защита для админ-операций
            .csrf(csrf -> csrf
                .csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse())
            );
        
        return http.build();
    }
}

6. Аудит и логирование

@Component
public class AdminAuditLogger {
    private final AuditRepository auditRepository;
    
    @Around("@annotation(AdminAction)")
    public Object logAdminAction(
        ProceedingJoinPoint joinPoint,
        AdminAction annotation
    ) throws Throwable {
        String adminId = SecurityContextHolder.getContext()
            .getAuthentication().getName();
        String action = annotation.value();
        long startTime = System.currentTimeMillis();
        
        try {
            Object result = joinPoint.proceed();
            
            // Логируем успешное действие
            auditRepository.save(AuditLog.builder()
                .adminId(adminId)
                .action(action)
                .status("SUCCESS")
                .duration(System.currentTimeMillis() - startTime)
                .timestamp(LocalDateTime.now())
                .build()
            );
            
            return result;
        } catch (Exception e) {
            // Логируем ошибку
            auditRepository.save(AuditLog.builder()
                .adminId(adminId)
                .action(action)
                .status("FAILED")
                .error(e.getMessage())
                .duration(System.currentTimeMillis() - startTime)
                .timestamp(LocalDateTime.now())
                .build()
            );
            throw e;
        }
    }
}

Важные принципы

1. Разделение ролей:

• ADMIN — полный доступ
• MODERATOR — модерация контента
• SUPPORT — работа с заказами и клиентами

2. Аудит всех действий:

• Кто сделал
• Что сделал
• Когда сделал
• С какого IP
• Результат

3. Защита:

• Двухфакторная аутентификация
• Rate limiting для admin API
• Логирование всех доступов
• Ограничение IP адресов (белый список)

4. Удобство:

• Пагинация и фильтрация
• Быстрый поиск
• Bulk операции (удалить N пользователей)
• Экспорт в CSV/Excel

Административный функционал — это не просто CRUD, это критическая часть безопасности и управления системой.