feat: add phase five operations foundation

Tiku.Api/ApiProgramMarker.cs

@@ -0,0 +1,3 @@
+namespace Tiku.Api;
+
+public sealed class ApiProgramMarker;

Tiku.Api/Contracts/BackgroundJobDtos.cs

@@ -0,0 +1,22 @@
+using System.Text.Json;
+using Tiku.Application.Jobs;
+
+namespace Tiku.Api.Contracts;
+
+public sealed class CreateBackgroundJobDto
+{
+    public string JobType { get; set; } = string.Empty;
+    public JsonElement Payload { get; set; }
+    public DateTimeOffset? RunAfter { get; set; }
+    public int MaxRetries { get; set; } = 3;
+
+    public CreateBackgroundJobCommand ToCommand(Guid tenantId)
+    {
+        return new CreateBackgroundJobCommand(
+            tenantId,
+            JobType,
+            Payload.ValueKind == JsonValueKind.Undefined ? JsonSerializer.SerializeToElement(new { }) : Payload,
+            RunAfter,
+            MaxRetries);
+    }
+}

Tiku.Api/Contracts/BackofficeDtos.cs

@@ -0,0 +1,41 @@
+using System.Text.Json;
+using Tiku.Application.Backoffice;
+using Tiku.Domain.Operations;
+
+namespace Tiku.Api.Contracts;
+
+public sealed class UpsertBackofficeRoleDto
+{
+    public Guid? Id { get; set; }
+    public string Code { get; set; } = string.Empty;
+    public string Name { get; set; } = string.Empty;
+    public BackendRoleStatus Status { get; set; } = BackendRoleStatus.Active;
+    public string? Description { get; set; }
+    public JsonElement? DataScope { get; set; }
+
+    public UpsertBackofficeRoleCommand ToCommand()
+    {
+        return new UpsertBackofficeRoleCommand(Id, Code, Name, Status, Description, DataScope);
+    }
+}
+
+public sealed class ReplaceRoleBindingsDto
+{
+    public IReadOnlyCollection<string> PermissionCodes { get; set; } = [];
+    public IReadOnlyCollection<string> MenuCodes { get; set; } = [];
+
+    public ReplaceRoleBindingsCommand ToCommand(Guid roleId)
+    {
+        return new ReplaceRoleBindingsCommand(roleId, PermissionCodes, MenuCodes);
+    }
+}
+
+public sealed class ReplaceUserRolesDto
+{
+    public IReadOnlyCollection<Guid> RoleIds { get; set; } = [];
+
+    public ReplaceUserRolesCommand ToCommand(Guid userId)
+    {
+        return new ReplaceUserRolesCommand(userId, RoleIds);
+    }
+}

Tiku.Api/Contracts/TenantCommerceDtos.cs

@@ -249,6 +249,91 @@ public sealed class UpsertPointExchangeItemDto
     }
 }
 
+public sealed class CreateRefundRequestDto
+{
+    [Required]
+    public Guid OrderId { get; set; }
+
+    public Guid? PaymentId { get; set; }
+
+    [Range(1, int.MaxValue)]
+    public int AmountCents { get; set; }
+
+    [StringLength(1000)]
+    public string? Reason { get; set; }
+
+    public RefundEntitlementAction EntitlementAction { get; set; } = RefundEntitlementAction.RevokeOnSuccess;
+    public JsonElement Metadata { get; set; } = JsonDefaults.Object();
+
+    public CreateRefundRequestCommand ToCommand()
+    {
+        return new CreateRefundRequestCommand(OrderId, PaymentId, AmountCents, Reason, EntitlementAction, Metadata);
+    }
+}
+
+public sealed class UpdateRefundStatusDto
+{
+    [Required]
+    public Guid RefundRequestId { get; set; }
+
+    public CommerceRefundStatus Status { get; set; }
+
+    [StringLength(1000)]
+    public string? Reason { get; set; }
+
+    [StringLength(200)]
+    public string? ProviderRefundNo { get; set; }
+
+    public UpdateRefundStatusCommand ToCommand()
+    {
+        return new UpdateRefundStatusCommand(RefundRequestId, Status, Reason, ProviderRefundNo);
+    }
+}
+
+public sealed class CreateReconciliationBatchDto
+{
+    [Required]
+    [StringLength(50)]
+    public string Provider { get; set; } = string.Empty;
+
+    public DateOnly BillDate { get; set; }
+    public ReconciliationBillType BillType { get; set; } = ReconciliationBillType.Combined;
+    public ReconciliationSource Source { get; set; } = ReconciliationSource.ManualUpload;
+
+    [StringLength(200)]
+    public string? SourceName { get; set; }
+
+    [Required]
+    [StringLength(200)]
+    public string SourceHash { get; set; } = string.Empty;
+
+    public JsonElement Metadata { get; set; } = JsonDefaults.Object();
+
+    public CreateReconciliationBatchCommand ToCommand()
+    {
+        return new CreateReconciliationBatchCommand(Provider, BillDate, BillType, Source, SourceName, SourceHash, Metadata);
+    }
+}
+
+public sealed class UpdateReconciliationIssueDto
+{
+    [Required]
+    public Guid IssueId { get; set; }
+
+    public ReconciliationIssueStatus Status { get; set; } = ReconciliationIssueStatus.Investigating;
+    public ReconciliationResolutionType ResolutionType { get; set; } = ReconciliationResolutionType.None;
+
+    [StringLength(1000)]
+    public string? Note { get; set; }
+
+    public Guid? AssignedTo { get; set; }
+
+    public UpdateReconciliationIssueCommand ToCommand()
+    {
+        return new UpdateReconciliationIssueCommand(IssueId, Status, ResolutionType, Note, AssignedTo);
+    }
+}
+
 public sealed class UpdatePointExchangeOrderStatusDto
 {
     [Required]

Tiku.Api/Controllers/BackgroundJobsController.cs

@@ -0,0 +1,41 @@
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+using Tiku.Api.Contracts;
+using Tiku.Application.Jobs;
+using Tiku.Application.Security;
+
+namespace Tiku.Api.Controllers;
+
+[ApiController]
+[Route("api/backoffice/tenant/jobs")]
+[Authorize(Policy = TikuPolicies.TenantAdmin)]
+public sealed class BackgroundJobsController(
+    IBackgroundJobService backgroundJobService,
+    ITenantContext tenantContext) : ControllerBase
+{
+    [HttpGet]
+    [ProducesResponseType<IReadOnlyCollection<BackgroundJobItem>>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<IReadOnlyCollection<BackgroundJobItem>>> List(
+        [FromQuery] string? jobType,
+        [FromQuery] int? limit,
+        CancellationToken cancellationToken)
+    {
+        var tenantId = ResolveTenantId();
+        return Ok(await backgroundJobService.ListAsync(tenantId, jobType, limit ?? 50, cancellationToken));
+    }
+
+    [HttpPost]
+    [ProducesResponseType<BackgroundJobItem>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<BackgroundJobItem>> Create(
+        CreateBackgroundJobDto request,
+        CancellationToken cancellationToken)
+    {
+        var tenantId = ResolveTenantId();
+        return Ok(await backgroundJobService.EnqueueAsync(request.ToCommand(tenantId), cancellationToken));
+    }
+
+    private Guid ResolveTenantId()
+    {
+        return tenantContext.TenantId ?? throw new InvalidOperationException("Tenant context was not resolved.");
+    }
+}

Tiku.Api/Controllers/BackofficeController.cs

@@ -0,0 +1,122 @@
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+using Tiku.Api.Contracts;
+using Tiku.Application.Backoffice;
+using Tiku.Application.Security;
+
+namespace Tiku.Api.Controllers;
+
+[ApiController]
+[Route("api/backoffice")]
+public sealed class BackofficeController(
+    IBackofficeService backofficeService,
+    ICurrentUser currentUser,
+    ITenantContext tenantContext) : ControllerBase
+{
+    [HttpGet("tenant/bootstrap")]
+    [Authorize(Policy = TikuPolicies.TenantAdmin)]
+    [ProducesResponseType<BackofficeBootstrap>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<BackofficeBootstrap>> GetTenantBootstrap(CancellationToken cancellationToken)
+    {
+        return Ok(await backofficeService.GetTenantBootstrapAsync(ResolveTenantActor(), cancellationToken));
+    }
+
+    [HttpPost("tenant/roles")]
+    [Authorize(Policy = TikuPolicies.TenantAdmin)]
+    [ProducesResponseType<BackofficeRoleItem>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<BackofficeRoleItem>> UpsertTenantRole(
+        UpsertBackofficeRoleDto request,
+        CancellationToken cancellationToken)
+    {
+        return Ok(await backofficeService.UpsertTenantRoleAsync(ResolveTenantActor(), request.ToCommand(), cancellationToken));
+    }
+
+    [HttpPut("tenant/roles/{roleId:guid}/bindings")]
+    [Authorize(Policy = TikuPolicies.TenantAdmin)]
+    [ProducesResponseType<BackofficeRoleItem>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<BackofficeRoleItem>> ReplaceTenantRoleBindings(
+        Guid roleId,
+        ReplaceRoleBindingsDto request,
+        CancellationToken cancellationToken)
+    {
+        return Ok(await backofficeService.ReplaceTenantRoleBindingsAsync(ResolveTenantActor(), request.ToCommand(roleId), cancellationToken));
+    }
+
+    [HttpPut("tenant/users/{userId:guid}/roles")]
+    [Authorize(Policy = TikuPolicies.TenantAdmin)]
+    [ProducesResponseType(StatusCodes.Status204NoContent)]
+    public async Task<IActionResult> ReplaceTenantUserRoles(
+        Guid userId,
+        ReplaceUserRolesDto request,
+        CancellationToken cancellationToken)
+    {
+        await backofficeService.ReplaceTenantUserRolesAsync(ResolveTenantActor(), request.ToCommand(userId), cancellationToken);
+        return NoContent();
+    }
+
+    [HttpGet("platform/bootstrap")]
+    [Authorize(Policy = TikuPolicies.TenantAdmin)]
+    [ProducesResponseType<BackofficeBootstrap>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<BackofficeBootstrap>> GetPlatformBootstrap(CancellationToken cancellationToken)
+    {
+        return Ok(await backofficeService.GetPlatformBootstrapAsync(ResolvePlatformActor(), cancellationToken));
+    }
+
+    [HttpPost("platform/roles")]
+    [Authorize(Policy = TikuPolicies.TenantAdmin)]
+    [ProducesResponseType<BackofficeRoleItem>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<BackofficeRoleItem>> UpsertPlatformRole(
+        UpsertBackofficeRoleDto request,
+        CancellationToken cancellationToken)
+    {
+        return Ok(await backofficeService.UpsertPlatformRoleAsync(ResolvePlatformActor(), request.ToCommand(), cancellationToken));
+    }
+
+    [HttpPut("platform/roles/{roleId:guid}/bindings")]
+    [Authorize(Policy = TikuPolicies.TenantAdmin)]
+    [ProducesResponseType<BackofficeRoleItem>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<BackofficeRoleItem>> ReplacePlatformRoleBindings(
+        Guid roleId,
+        ReplaceRoleBindingsDto request,
+        CancellationToken cancellationToken)
+    {
+        return Ok(await backofficeService.ReplacePlatformRoleBindingsAsync(ResolvePlatformActor(), request.ToCommand(roleId), cancellationToken));
+    }
+
+    [HttpPut("platform/users/{userId:guid}/roles")]
+    [Authorize(Policy = TikuPolicies.TenantAdmin)]
+    [ProducesResponseType(StatusCodes.Status204NoContent)]
+    public async Task<IActionResult> ReplacePlatformUserRoles(
+        Guid userId,
+        ReplaceUserRolesDto request,
+        CancellationToken cancellationToken)
+    {
+        await backofficeService.ReplacePlatformUserRolesAsync(ResolvePlatformActor(), request.ToCommand(userId), cancellationToken);
+        return NoContent();
+    }
+
+    private BackofficeActor ResolveTenantActor()
+    {
+        if (currentUser.UserId is not { } userId || tenantContext.TenantId is not { } tenantId)
+        {
+            throw new InvalidOperationException("Tenant backoffice actor was not resolved.");
+        }
+
+        return new BackofficeActor(userId, tenantId, IsPlatformAdmin());
+    }
+
+    private BackofficeActor ResolvePlatformActor()
+    {
+        if (currentUser.UserId is not { } userId)
+        {
+            throw new InvalidOperationException("Platform backoffice actor was not resolved.");
+        }
+
+        return new BackofficeActor(userId, tenantContext.TenantId, IsPlatformAdmin());
+    }
+
+    private bool IsPlatformAdmin()
+    {
+        return string.Equals(currentUser.TenantRole, "PlatformAdmin", StringComparison.OrdinalIgnoreCase);
+    }
+}

Tiku.Api/Controllers/TenantCommerceController.cs

@@ -3,6 +3,7 @@ using Microsoft.AspNetCore.Mvc;
 using Tiku.Api.Contracts;
 using Tiku.Application.Commerce;
 using Tiku.Application.Security;
+using Tiku.Domain.Commerce;
 
 namespace Tiku.Api.Controllers;
 
@@ -262,6 +263,110 @@ public sealed class TenantCommerceController(
             cancellationToken));
     }
 
+    [HttpGet("refunds")]
+    [EndpointSummary("查询退款申请")]
+    [ProducesResponseType<TenantRefundList>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<TenantRefundList>> Refunds(
+        [FromQuery] TenantCommerceQueryDto query,
+        CancellationToken cancellationToken)
+    {
+        return Ok(await commerceAdminService.GetRefundsAsync(
+            ResolveActor(),
+            ToQuery(query),
+            cancellationToken));
+    }
+
+    [HttpPost("refunds")]
+    [EndpointSummary("创建退款申请")]
+    [ProducesResponseType<CommerceRefundRequest>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<CommerceRefundRequest>> CreateRefund(
+        CreateRefundRequestDto request,
+        CancellationToken cancellationToken)
+    {
+        return Ok(await commerceAdminService.CreateRefundRequestAsync(
+            ResolveActor(),
+            request.ToCommand(),
+            cancellationToken));
+    }
+
+    [HttpPost("refunds/status")]
+    [EndpointSummary("更新退款状态")]
+    [ProducesResponseType<CommerceRefundRequest>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<CommerceRefundRequest>> UpdateRefundStatus(
+        UpdateRefundStatusDto request,
+        CancellationToken cancellationToken)
+    {
+        return Ok(await commerceAdminService.UpdateRefundStatusAsync(
+            ResolveActor(),
+            request.ToCommand(),
+            cancellationToken));
+    }
+
+    [HttpGet("refunds/{refundRequestId:guid}/events")]
+    [EndpointSummary("查询退款事件")]
+    [ProducesResponseType<TenantRefundEventList>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<TenantRefundEventList>> RefundEvents(
+        Guid refundRequestId,
+        CancellationToken cancellationToken)
+    {
+        return Ok(await commerceAdminService.GetRefundEventsAsync(
+            ResolveActor(),
+            refundRequestId,
+            cancellationToken));
+    }
+
+    [HttpGet("reconciliation/batches")]
+    [EndpointSummary("查询对账批次")]
+    [ProducesResponseType<TenantReconciliationBatchList>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<TenantReconciliationBatchList>> ReconciliationBatches(
+        [FromQuery] TenantCommerceQueryDto query,
+        CancellationToken cancellationToken)
+    {
+        return Ok(await commerceAdminService.GetReconciliationBatchesAsync(
+            ResolveActor(),
+            ToQuery(query),
+            cancellationToken));
+    }
+
+    [HttpPost("reconciliation/batches")]
+    [EndpointSummary("创建对账批次")]
+    [ProducesResponseType<CommerceReconciliationBatch>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<CommerceReconciliationBatch>> CreateReconciliationBatch(
+        CreateReconciliationBatchDto request,
+        CancellationToken cancellationToken)
+    {
+        return Ok(await commerceAdminService.CreateReconciliationBatchAsync(
+            ResolveActor(),
+            request.ToCommand(),
+            cancellationToken));
+    }
+
+    [HttpGet("reconciliation/issues")]
+    [EndpointSummary("查询对账异常")]
+    [ProducesResponseType<TenantReconciliationIssueList>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<TenantReconciliationIssueList>> ReconciliationIssues(
+        [FromQuery] TenantCommerceQueryDto query,
+        CancellationToken cancellationToken)
+    {
+        return Ok(await commerceAdminService.GetReconciliationIssuesAsync(
+            ResolveActor(),
+            ToQuery(query),
+            cancellationToken));
+    }
+
+    [HttpPost("reconciliation/issues/status")]
+    [EndpointSummary("更新对账异常状态")]
+    [ProducesResponseType<CommerceReconciliationIssue>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<CommerceReconciliationIssue>> UpdateReconciliationIssue(
+        UpdateReconciliationIssueDto request,
+        CancellationToken cancellationToken)
+    {
+        return Ok(await commerceAdminService.UpdateReconciliationIssueAsync(
+            ResolveActor(),
+            request.ToCommand(),
+            cancellationToken));
+    }
+
     private CommerceAdminActor ResolveActor()
     {
         if (currentTenant.TenantId is null || currentUser.UserId is null)