feat: add referral crm queue endpoints

Tiku.Api/Contracts/CrmDtos.cs

@@ -0,0 +1,104 @@
+using System.ComponentModel.DataAnnotations;
+using System.Text.Json;
+using Tiku.Application.Growth;
+
+namespace Tiku.Api.Contracts;
+
+public sealed class UpsertCrmConfigDto
+{
+    public bool Enabled { get; set; }
+
+    [StringLength(2048)]
+    public string? Url { get; set; }
+
+    [StringLength(300)]
+    public string? SecretRef { get; set; }
+
+    public string? Secret { get; set; }
+
+    [StringLength(200)]
+    public string? FormName { get; set; }
+
+    [StringLength(100)]
+    public string? ExamType { get; set; }
+
+    [Range(1, 120)]
+    public int? TimeoutSeconds { get; set; }
+
+    [Range(0, 86400)]
+    public int? DelaySeconds { get; set; }
+
+    [StringLength(50)]
+    public string? AssignmentMode { get; set; }
+
+    public JsonElement? AssignmentPool { get; set; }
+
+    public JsonElement? AssignmentConfig { get; set; }
+
+    public UpsertCrmConfigCommand ToCommand()
+    {
+        return new UpsertCrmConfigCommand(
+            Enabled,
+            Url,
+            SecretRef,
+            Secret,
+            FormName,
+            ExamType,
+            TimeoutSeconds,
+            DelaySeconds,
+            AssignmentMode,
+            AssignmentPool,
+            AssignmentConfig);
+    }
+}
+
+public sealed class CrmQueueQueryDto
+{
+    [StringLength(50)]
+    public string? Status { get; set; }
+
+    public Guid? QueueId { get; set; }
+
+    [StringLength(200)]
+    public string? Source { get; set; }
+
+    [Range(1, 500)]
+    public int? Limit { get; set; }
+
+    public CrmQueueQuery ToQuery()
+    {
+        return new CrmQueueQuery(Status, QueueId, Source, Limit);
+    }
+}
+
+public sealed class CrmQueueLogQueryDto
+{
+    public Guid? QueueId { get; set; }
+
+    [Range(1, 200)]
+    public int? Limit { get; set; }
+
+    public CrmQueueLogQuery ToQuery()
+    {
+        return new CrmQueueLogQuery(QueueId, Limit);
+    }
+}
+
+public sealed class CrmQueueActionDto
+{
+    [Required]
+    public Guid QueueId { get; set; }
+
+    [StringLength(50)]
+    public string? Action { get; set; }
+
+    [StringLength(500)]
+    public string? Note { get; set; }
+
+    public JsonElement? Metadata { get; set; }
+
+    public CrmQueueActionCommand ToCommand()
+    {
+        return new CrmQueueActionCommand(QueueId, Action, Note, Metadata);
+    }
+}

Tiku.Api/Controllers/CrmController.cs

@@ -0,0 +1,85 @@
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+using Tiku.Api.Contracts;
+using Tiku.Application.Growth;
+using Tiku.Application.Security;
+
+namespace Tiku.Api.Controllers;
+
+[ApiController]
+[Authorize(Policy = TikuPolicies.TenantAdmin)]
+[Produces("application/json")]
+[Route("api/crm")]
+public sealed class CrmController(
+    ICrmService crmService,
+    ICurrentUser currentUser,
+    ICurrentTenant currentTenant) : ControllerBase
+{
+    [HttpGet("config")]
+    [EndpointSummary("查询 CRM 推送配置")]
+    [ProducesResponseType<CrmConfigItem>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<CrmConfigItem>> Config(CancellationToken cancellationToken)
+    {
+        return Ok(await crmService.GetConfigAsync(ResolveActor(), cancellationToken));
+    }
+
+    [HttpPut("config")]
+    [EndpointSummary("保存 CRM 推送配置")]
+    [ProducesResponseType<CrmConfigItem>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<CrmConfigItem>> UpsertConfig(
+        UpsertCrmConfigDto request,
+        CancellationToken cancellationToken)
+    {
+        return Ok(await crmService.UpsertConfigAsync(ResolveActor(), request.ToCommand(), cancellationToken));
+    }
+
+    [HttpGet("queue")]
+    [EndpointSummary("查询 CRM webhook 队列")]
+    [ProducesResponseType<CrmList<CrmQueueItem>>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<CrmList<CrmQueueItem>>> Queue(
+        [FromQuery] CrmQueueQueryDto query,
+        CancellationToken cancellationToken)
+    {
+        return Ok(await crmService.GetQueueAsync(ResolveActor(), query.ToQuery(), cancellationToken));
+    }
+
+    [HttpGet("dead-letters")]
+    [EndpointSummary("查询 CRM 死信任务与汇总")]
+    [ProducesResponseType<CrmDeadLetterResult>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<CrmDeadLetterResult>> DeadLetters(
+        [FromQuery] CrmQueueQueryDto query,
+        CancellationToken cancellationToken)
+    {
+        return Ok(await crmService.GetDeadLettersAsync(ResolveActor(), query.ToQuery(), cancellationToken));
+    }
+
+    [HttpGet("queue/logs")]
+    [EndpointSummary("查询 CRM 队列执行日志")]
+    [ProducesResponseType<CrmList<CrmQueueLogItem>>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<CrmList<CrmQueueLogItem>>> Logs(
+        [FromQuery] CrmQueueLogQueryDto query,
+        CancellationToken cancellationToken)
+    {
+        return Ok(await crmService.GetLogsAsync(ResolveActor(), query.ToQuery(), cancellationToken));
+    }
+
+    [HttpPost("queue/action")]
+    [EndpointSummary("重试或忽略 CRM 死信任务")]
+    [ProducesResponseType<CrmQueueItem>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<CrmQueueItem>> Action(
+        CrmQueueActionDto request,
+        CancellationToken cancellationToken)
+    {
+        return Ok(await crmService.ApplyQueueActionAsync(ResolveActor(), request.ToCommand(), cancellationToken));
+    }
+
+    private CrmAdminActor ResolveActor()
+    {
+        if (currentTenant.TenantId is null || currentUser.UserId is null)
+        {
+            throw new CrmException("CRM admin actor was not resolved.", "crm_access_denied");
+        }
+
+        return new CrmAdminActor(currentTenant.TenantId.Value, currentUser.UserId.Value);
+    }
+}

Tiku.Api/Middleware/ExceptionHandlingMiddleware.cs

@@ -205,6 +205,16 @@ public sealed class ExceptionHandlingMiddleware(
                 return;
             }
 
+            if (exception is CrmException crmException)
+            {
+                await WriteProblemAsync(
+                    context,
+                    crmException.Message,
+                    CrmStatusCode(crmException.Code),
+                    crmException.Code);
+                return;
+            }
+
             if (exception is PaymentProviderException paymentProviderException)
             {
                 await WriteProblemAsync(
@@ -389,4 +399,15 @@ public sealed class ExceptionHandlingMiddleware(
             _ => StatusCodes.Status400BadRequest
         };
     }
+
+    private static int CrmStatusCode(string code)
+    {
+        return code switch
+        {
+            "crm_access_denied" => StatusCodes.Status403Forbidden,
+            "crm_queue_not_found" => StatusCodes.Status404NotFound,
+            "crm_queue_status_invalid" => StatusCodes.Status409Conflict,
+            _ => StatusCodes.Status400BadRequest
+        };
+    }
 }