mi-assessment/server/MiAssessment/src/MiAssessment.Api/Controllers/HomeController.cs

using MiAssessment.Core.Interfaces;
using MiAssessment.Model.Base;
using MiAssessment.Model.Models.Home;
using Microsoft.AspNetCore.Mvc;

namespace MiAssessment.Api.Controllers;

/// <summary>
/// 首页控制器 - 处理首页相关功能
/// </summary>
/// <remarks>
/// 提供Banner列表、测评入口列表、宣传图列表等首页内容
/// 所有接口不需要用户登录认证
/// Requirements: 1.1, 1.2, 1.3, 1.4
/// </remarks>
[ApiController]
[Route("api/home")]
public class HomeController : ControllerBase
{
    private readonly IHomeService _homeService;
    private readonly ILogger<HomeController> _logger;

    /// <summary>
    /// 构造函数
    /// </summary>
    /// <param name="homeService">首页服务</param>
    /// <param name="logger">日志记录器</param>
    public HomeController(IHomeService homeService, ILogger<HomeController> logger)
    {
        _homeService = homeService;
        _logger = logger;
    }

    /// <summary>
    /// 获取Banner列表
    /// </summary>
    /// <remarks>
    /// GET /api/home/getBannerList
    /// 
    /// 返回所有启用状态的Banner记录，按Sort降序排列
    /// 不需要用户登录认证
    /// Requirements: 1.1
    /// </remarks>
    /// <returns>Banner列表</returns>
    [HttpGet("getBannerList")]
    [ProducesResponseType(typeof(ApiResponse<List<BannerDto>>), StatusCodes.Status200OK)]
    public async Task<ApiResponse<List<BannerDto>>> GetBannerList()
    {
        try
        {
            var banners = await _homeService.GetBannerListAsync();
            return ApiResponse<List<BannerDto>>.Success(banners);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Failed to get banner list");
            return ApiResponse<List<BannerDto>>.Fail("获取Banner列表失败");
        }
    }

    /// <summary>
    /// 获取测评入口列表
    /// </summary>
    /// <remarks>
    /// GET /api/home/getAssessmentList
    /// 
    /// 返回所有未删除的测评类型，包含状态信息（已上线/即将上线）
    /// 不需要用户登录认证
    /// Requirements: 1.2
    /// </remarks>
    /// <returns>测评类型列表</returns>
    [HttpGet("getAssessmentList")]
    [ProducesResponseType(typeof(ApiResponse<List<AssessmentTypeDto>>), StatusCodes.Status200OK)]
    public async Task<ApiResponse<List<AssessmentTypeDto>>> GetAssessmentList()
    {
        try
        {
            var assessmentTypes = await _homeService.GetAssessmentListAsync();
            return ApiResponse<List<AssessmentTypeDto>>.Success(assessmentTypes);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Failed to get assessment list");
            return ApiResponse<List<AssessmentTypeDto>>.Fail("获取测评列表失败");
        }
    }

    /// <summary>
    /// 获取首页导航入口列表
    /// </summary>
    /// <remarks>
    /// GET /api/home/getNavigationList?position=1
    /// 
    /// 返回启用状态的首页导航入口，按Sort降序排列
    /// 支持按 position 筛选区域（1=专业测评，2=更多），不传返回全部
    /// 不需要用户登录认证
    /// Requirements: 2.1, 2.2
    /// </remarks>
    /// <param name="position">区域标识（可选）：1=专业测评区域，2=更多区域</param>
    /// <returns>导航入口列表</returns>
    [HttpGet("getNavigationList")]
    [ProducesResponseType(typeof(ApiResponse<List<HomeNavigationDto>>), StatusCodes.Status200OK)]
    public async Task<ApiResponse<List<HomeNavigationDto>>> GetNavigationList([FromQuery] int? position)
    {
        try
        {
            var navigations = await _homeService.GetNavigationListAsync(position);
            return ApiResponse<List<HomeNavigationDto>>.Success(navigations);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Failed to get navigation list");
            return ApiResponse<List<HomeNavigationDto>>.Fail("获取导航入口列表失败");
        }
    }

    /// <summary>
    /// 获取宣传图列表
    /// </summary>
    /// <remarks>
    /// GET /api/home/getPromotionList
    /// 
    /// 返回首页位置（Position=1）且启用状态的宣传图
    /// 不需要用户登录认证
    /// Requirements: 1.3
    /// </remarks>
    /// <returns>宣传图列表</returns>
    [HttpGet("getPromotionList")]
    [ProducesResponseType(typeof(ApiResponse<List<PromotionDto>>), StatusCodes.Status200OK)]
    public async Task<ApiResponse<List<PromotionDto>>> GetPromotionList()
    {
        try
        {
            var promotions = await _homeService.GetPromotionListAsync();
            return ApiResponse<List<PromotionDto>>.Success(promotions);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Failed to get promotion list");
            return ApiResponse<List<PromotionDto>>.Fail("获取宣传图列表失败");
        }
    }
}