StoreWeb/Modules/Store.Users/Controllers/UserController.cs

using MediatR;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Store.Users.Commands;
using Store.Users.Contracts.Dtos;
using Store.Users.Dtos;
using Store.Users.Entities;
using Store.Users.Services;
using MAX.Framework.Dtos;
using MAX.Framework.Conventions;

namespace Store.Users.Controllers;

/// <summary>用户模块接口；所有管理操作均以当前 JWT 对应的数据库账户进行授权。</summary>
[ApiController]
[DefaultHttpPost]
[Authorize]
[Route("v{version:apiVersion}/user/[action]")]
public class UserController(UserManagementService users, UserFundsService funds, IMediator mediator) : ControllerBase
{
    /// <summary>获取本人或授权范围内的用户信息，响应不包含密码。</summary>
    [EndpointSummary("获取用户信息")]
    public Task<UserInfo> GetUser(string? userName, CancellationToken cancellationToken)
    {
        return users.GetUser(userName, cancellationToken);
    }

    /// <summary>管理员查询全部用户；普通主账号仅查询本人及直属子账号。</summary>
    [EndpointSummary("分页查询所有用户")]
    public Task<UserPage<UserInfo>> GetAllUser(UserSearchRequest request, CancellationToken cancellationToken)
    {
        return users.Search(request, false, cancellationToken);
    }

    /// <summary>管理员可查询所有账号的子账号，普通主账号只能查询自己的直属子账号。</summary>
    /// <param name="request">管理员可通过 ParentUserName 筛选指定父账号；普通主账号仅可指定自己。</param>
    /// <param name="cancellationToken">请求取消标记。</param>
    [EndpointSummary("分页查询子账号")]
    [EndpointDescription("管理员不传 ParentUserName 时查询全部子账号，传入时按指定父账号筛选；普通主账号只能查询自己的子账号。")]
    public Task<UserPage<UserInfo>> GetSubUser(UserSearchRequest request, CancellationToken cancellationToken)
    {
        return users.Search(request, true, cancellationToken);
    }

    /// <summary>管理员创建主账号。</summary>
    [EndpointSummary("创建主账号")]
    public Task<UserInfo> AddUser(UserCreateRequest request, CancellationToken cancellationToken)
    {
        return users.Create(request, false, cancellationToken);
    }

    /// <summary>管理员可为指定主账号创建子账号，普通主账号仅可为自己创建子账号。</summary>
    [EndpointSummary("创建直属子账号")]
    public Task<UserInfo> AddSubUser(UserCreateRequest request, CancellationToken cancellationToken)
    {
        return users.Create(request, true, cancellationToken);
    }

    /// <summary>管理员修改任意账户；普通主账号仅修改本人及直属子账号，用户名不可变更。</summary>
    [EndpointSummary("修改用户资料")]
    public Task<UserInfo> UpdateUser(UserUpdateRequest request, CancellationToken cancellationToken)
    {
        return users.Update(request, false, cancellationToken);
    }

    /// <summary>管理员修改任意子账号，普通主账号仅修改直属子账号。</summary>
    [EndpointSummary("修改直属子账号资料")]
    public Task<UserInfo> UpdateSubUser(UserUpdateRequest request, CancellationToken cancellationToken)
    {
        return users.Update(request, true, cancellationToken);
    }

    /// <summary>删除无资金和业务关联的账户。</summary>
    [EndpointSummary("删除用户")]
    public async Task<ApiResult> DelUser(int id, CancellationToken cancellationToken)
    {
        await users.Delete(id, cancellationToken);
        return ApiResult.Ok();
    }

    /// <summary>非管理员本人改密校验原密码；管理员可重置任意账户，主账号可重置直属子账号密码。</summary>
    [EndpointSummary("修改或重置用户密码")]
    public async Task<ApiResult> ChangePassword(ChangePasswordRequest request, CancellationToken cancellationToken)
    {
        await users.ChangePassword(request, cancellationToken);
        return ApiResult.Ok();
    }

    /// <summary>查询授权账户的积分流水。</summary>
    [EndpointSummary("查询用户积分流水")]
    public Task<UserPage<UserPointsRecordEntity>> GetUserPoints(UserRecordSearchRequest request, CancellationToken cancellationToken)
    {
        return users.Points(request.UserName, request, cancellationToken);
    }

    /// <summary>查询授权账户的余额流水。</summary>
    [EndpointSummary("查询用户余额流水")]
    public Task<UserPage<UserPaymentRecordEntity>> GetUserBalance(UserRecordSearchRequest request, CancellationToken cancellationToken)
    {
        return users.Balance(request.UserName, request, cancellationToken);
    }

    /// <summary>管理员充值积分，或主账号向直属子账号转移自己的积分。</summary>
    [EndpointSummary("充值或转移用户积分")]
    public Task<UserFundsResponse> UpdateUserPoints(UserFundsRequest request, CancellationToken cancellationToken)
    {
        return funds.Change(request, true, cancellationToken);
    }

    /// <summary>管理员充值或扣减余额，自动记录审计流水。</summary>
    [EndpointSummary("充值或扣减用户余额")]
    public Task<UserFundsResponse> UpdateUserBalance(UserFundsRequest request, CancellationToken cancellationToken)
    {
        return funds.Change(request, false, cancellationToken);
    }

    /// <summary>提交本人或管理范围内账户的充值备注。</summary>
    [EndpointSummary("提交充值备注")]
    public Task<long> AddUserTopUpMsg(UserTopUpMessageRequest request, CancellationToken cancellationToken)
    {
        return users.AddTopUpMessage(request, cancellationToken);
    }

    /// <summary>管理员可处理所有充值备注，普通主账号仅处理本人及直属子账号备注，不自动充值。</summary>
    [EndpointSummary("处理充值备注")]
    public async Task<ApiResult> UpdateUserTopUpMsg(UserTopUpResultRequest request, CancellationToken cancellationToken)
    {
        await users.UpdateTopUpMessage(request, cancellationToken);
        return ApiResult.Ok();
    }

    /// <summary>按管理员、主账号或子账号的授权范围分页查询充值备注。</summary>
    [EndpointSummary("分页查询充值备注")]
    public Task<UserPage<UserTopUpMessageEntity>> GetUserTopUpMsg(UserSearchRequest request, CancellationToken cancellationToken)
    {
        return users.TopUpMessages(request, cancellationToken);
    }

    /// <summary>管理员维护代理充值二维码。</summary>
    [EndpointSummary("维护代理充值二维码")]
    public async Task<ApiResult> UpdateTopUpQrcode(UserTopUpQrcodeRequest request, CancellationToken cancellationToken)
    {
        await users.UpdateTopUpQrcode(request, cancellationToken);
        return ApiResult.Ok();
    }

    /// <summary>获取代理充值二维码。</summary>
    [EndpointSummary("获取代理充值二维码")]
    public Task<string?> GetTopUpQrcode(string agentCode, CancellationToken cancellationToken)
    {
        return users.GetTopUpQrcode(agentCode, cancellationToken);
    }

    /// <summary>管理员或主账号为授权账户的商铺续费，扣除店铺所属账户积分并记录实际操作者。</summary>
    [EndpointSummary("使用积分为商铺续费")]
    public Task<ShopRenewResponse> ShopRenew(ShopRenewRequest request, CancellationToken cancellationToken)
    {
        // 操作者身份、目标账户归属和消费额度统一在命令管道中检查。
        return mediator.Send(new ShopRenewCommand(request), cancellationToken);
    }
}