feat: add referral management endpoints

Tiku.Api/Controllers/ReferralController.cs

@@ -92,6 +92,104 @@ public sealed class ReferralController(
             cancellationToken));
     }
 
+    [HttpGet("stats")]
+    [Authorize(Policy = TikuPolicies.TenantAdmin)]
+    [EndpointSummary("查询推荐人个人统计")]
+    [ProducesResponseType<ReferralStatsItem>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<ReferralStatsItem>> Stats(
+        [FromQuery] ReferralStatsQueryDto query,
+        CancellationToken cancellationToken)
+    {
+        return Ok(await referralService.GetStatsAsync(
+            ResolveAdminActor(),
+            query.ToQuery(),
+            cancellationToken));
+    }
+
+    [HttpGet("sales-stats")]
+    [Authorize(Policy = TikuPolicies.TenantAdmin)]
+    [EndpointSummary("查询销售推荐统计排行")]
+    [ProducesResponseType<ReferralList<ReferralStatsItem>>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<ReferralList<ReferralStatsItem>>> SalesStats(
+        [FromQuery] ReferralStatsQueryDto query,
+        CancellationToken cancellationToken)
+    {
+        return Ok(await referralService.GetSalesStatsAsync(
+            ResolveAdminActor(),
+            query.ToQuery(),
+            cancellationToken));
+    }
+
+    [HttpGet("conversion-report")]
+    [Authorize(Policy = TikuPolicies.TenantAdmin)]
+    [EndpointSummary("查询推荐转化报告")]
+    [ProducesResponseType<ReferralConversionReport>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<ReferralConversionReport>> ConversionReport(
+        [FromQuery] ReferralConversionQueryDto query,
+        CancellationToken cancellationToken)
+    {
+        return Ok(await referralService.GetConversionReportAsync(
+            ResolveAdminActor(),
+            query.ToQuery(),
+            cancellationToken));
+    }
+
+    [HttpGet("sales-clients")]
+    [Authorize(Policy = TikuPolicies.TenantAdmin)]
+    [EndpointSummary("查询推荐人名下客户")]
+    [ProducesResponseType<ReferralList<ReferralLeadItem>>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<ReferralList<ReferralLeadItem>>> SalesClients(
+        [FromQuery] ReferralStatsQueryDto query,
+        CancellationToken cancellationToken)
+    {
+        return Ok(await referralService.GetClientsAsync(
+            ResolveAdminActor(),
+            query.ToQuery(),
+            cancellationToken));
+    }
+
+    [HttpPost("manual-bind")]
+    [Authorize(Policy = TikuPolicies.TenantAdmin)]
+    [EndpointSummary("人工调整学生推荐归属")]
+    [ProducesResponseType<ReferralBindResult>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<ReferralBindResult>> ManualBind(
+        ManualBindReferralDto request,
+        CancellationToken cancellationToken)
+    {
+        return Ok(await referralService.ManualBindAsync(
+            ResolveAdminActor(),
+            request.ToCommand(),
+            cancellationToken));
+    }
+
+    [HttpGet("team")]
+    [Authorize(Policy = TikuPolicies.TenantAdmin)]
+    [EndpointSummary("查询推荐团队成员")]
+    [ProducesResponseType<ReferralList<ReferralTeamItem>>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<ReferralList<ReferralTeamItem>>> Team(
+        [FromQuery] ReferralTeamQueryDto query,
+        CancellationToken cancellationToken)
+    {
+        return Ok(await referralService.GetTeamAsync(
+            ResolveAdminActor(),
+            query.ToQuery(),
+            cancellationToken));
+    }
+
+    [HttpPut("team")]
+    [Authorize(Policy = TikuPolicies.TenantAdmin)]
+    [EndpointSummary("新增或更新推荐团队关系")]
+    [ProducesResponseType<ReferralTeamItem>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<ReferralTeamItem>> UpsertTeam(
+        UpsertReferralTeamDto request,
+        CancellationToken cancellationToken)
+    {
+        return Ok(await referralService.UpsertTeamAsync(
+            ResolveAdminActor(),
+            request.ToCommand(),
+            cancellationToken));
+    }
+
     private ReferralActor ResolveUserActor()
     {
         if (currentTenant.TenantId is null || currentUser.UserId is null)
@@ -102,6 +200,16 @@ public sealed class ReferralController(
         return new ReferralActor(currentTenant.TenantId.Value, currentUser.UserId.Value);
     }
 
+    private ReferralAdminActor ResolveAdminActor()
+    {
+        if (currentTenant.TenantId is null || currentUser.UserId is null)
+        {
+            throw new ReferralException("Referral admin actor was not resolved.", "referral_access_denied");
+        }
+
+        return new ReferralAdminActor(currentTenant.TenantId.Value, currentUser.UserId.Value);
+    }
+
     private async Task<Guid> ResolveTenantIdAsync(string? tenantCode, CancellationToken cancellationToken)
     {
         if (currentTenant.TenantId.HasValue)