feat: add tenant admin direct operations endpoints

2026-07-26 18:53:01 +08:00
parent 89e1f2a4df
commit f671a7f07a
8 changed files with 1822 additions and 0 deletions
--- a/Tiku.Api/Contracts/TenantAdminDirectDtos.cs
+++ b/Tiku.Api/Contracts/TenantAdminDirectDtos.cs
@@ -0,0 +1,217 @@
+using System.ComponentModel.DataAnnotations;
+using System.Text.Json;
+using Tiku.Application.TenantAdmin;
+using Tiku.Domain.Common;
+
+namespace Tiku.Api.Contracts;
+
+public sealed class TenantAdminClassQueryDto
+{
+    public Guid? RegionId { get; set; }
+    public string? Status { get; set; }
+    public string? Keyword { get; set; }
+
+    [Range(1, 500)]
+    public int? Limit { get; set; }
+
+    public TenantAdminClassFilter ToFilter()
+    {
+        return new TenantAdminClassFilter(RegionId, Status, Keyword, Limit);
+    }
+}
+
+public sealed class TenantAdminClassMemberQueryDto
+{
+    [Required]
+    public Guid ClassId { get; set; }
+
+    public string? MemberType { get; set; }
+    public string? Status { get; set; }
+
+    [Range(1, 500)]
+    public int? Limit { get; set; }
+
+    public TenantAdminClassMemberFilter ToFilter()
+    {
+        return new TenantAdminClassMemberFilter(ClassId, MemberType, Status, Limit);
+    }
+}
+
+public sealed class TenantAdminStudentQueryDto
+{
+    public Guid? RegionId { get; set; }
+    public Guid? ClassId { get; set; }
+    public string? Status { get; set; }
+    public string? Keyword { get; set; }
+
+    [Range(1, 500)]
+    public int? Limit { get; set; }
+
+    public TenantAdminStudentFilter ToFilter()
+    {
+        return new TenantAdminStudentFilter(RegionId, ClassId, Status, Keyword, Limit);
+    }
+}
+
+public sealed class TenantAdminStudentActivityQueryDto
+{
+    public Guid? StudentUserId { get; set; }
+    public string? Status { get; set; }
+
+    [Range(1, 500)]
+    public int? Limit { get; set; }
+
+    public TenantAdminStudentActivityFilter ToFilter()
+    {
+        return new TenantAdminStudentActivityFilter(StudentUserId, Status, Limit);
+    }
+}
+
+public sealed class UpsertTenantAdminClassDto
+{
+    public Guid? Id { get; set; }
+    public Guid? RegionId { get; set; }
+    public string? LegacyId { get; set; }
+    public string? Code { get; set; }
+    public required string Name { get; set; }
+    public string? Description { get; set; }
+    public string? Status { get; set; }
+    public int? Order { get; set; }
+    public JsonElement Metadata { get; set; } = JsonDefaults.Object();
+
+    public UpsertTenantAdminClassCommand ToCommand()
+    {
+        return new UpsertTenantAdminClassCommand(Id, RegionId, LegacyId, Code, Name, Description, Status, Order, Metadata);
+    }
+}
+
+public sealed class TenantAdminUserLookupDto
+{
+    public Guid? UserId { get; set; }
+    public string? Username { get; set; }
+    public string? Email { get; set; }
+    public string? Phone { get; set; }
+    public string? Name { get; set; }
+    public string? AvatarUrl { get; set; }
+
+    public UserLookupCommand ToCommand()
+    {
+        return new UserLookupCommand(UserId, Username, Email, Phone, Name, AvatarUrl);
+    }
+}
+
+public sealed class UpsertTenantAdminClassMemberDto
+{
+    [Required]
+    public Guid ClassId { get; set; }
+
+    public TenantAdminUserLookupDto User { get; set; } = new();
+    public string? MemberType { get; set; }
+    public string? Status { get; set; }
+    public JsonElement Metadata { get; set; } = JsonDefaults.Object();
+
+    public UpsertTenantAdminClassMemberCommand ToCommand()
+    {
+        return new UpsertTenantAdminClassMemberCommand(ClassId, User.ToCommand(), MemberType, Status, Metadata);
+    }
+}
+
+public sealed class RemoveTenantAdminClassMemberDto
+{
+    [Required]
+    public Guid ClassMemberId { get; set; }
+}
+
+public sealed class UpsertTenantAdminStudentDto
+{
+    public TenantAdminUserLookupDto User { get; set; } = new();
+    public Guid? RegionId { get; set; }
+    public Guid? SelectedSchoolId { get; set; }
+    public Guid? SelectedMajorId { get; set; }
+    public string? AvatarPreset { get; set; }
+    public JsonElement Stats { get; set; } = JsonDefaults.Object();
+    public JsonElement Progress { get; set; } = JsonDefaults.Object();
+    public JsonElement ModuleSelections { get; set; } = JsonDefaults.Object();
+    public JsonElement RawProfile { get; set; } = JsonDefaults.Object();
+
+    public UpsertTenantAdminStudentCommand ToCommand()
+    {
+        return new UpsertTenantAdminStudentCommand(
+            User.ToCommand(),
+            RegionId,
+            SelectedSchoolId,
+            SelectedMajorId,
+            AvatarPreset,
+            Stats,
+            Progress,
+            ModuleSelections,
+            RawProfile);
+    }
+}
+
+public sealed class UpdateTenantAdminStudentStatusDto
+{
+    [Required]
+    public Guid UserId { get; set; }
+
+    public string? Status { get; set; }
+    public string? Reason { get; set; }
+
+    public UpdateTenantAdminStudentStatusCommand ToCommand()
+    {
+        return new UpdateTenantAdminStudentStatusCommand(UserId, Status, Reason);
+    }
+}
+
+public sealed class UpsertTenantAdminStudentNoteDto
+{
+    public Guid? Id { get; set; }
+
+    [Required]
+    public Guid StudentUserId { get; set; }
+
+    public string? NoteType { get; set; }
+    public required string Content { get; set; }
+    public string? Visibility { get; set; }
+    public bool? IsPinned { get; set; }
+    public JsonElement Metadata { get; set; } = JsonDefaults.Object();
+
+    public UpsertTenantAdminStudentNoteCommand ToCommand()
+    {
+        return new UpsertTenantAdminStudentNoteCommand(Id, StudentUserId, NoteType, Content, Visibility, IsPinned, Metadata);
+    }
+}
+
+public sealed class UpsertTenantAdminStudentFollowupDto
+{
+    public Guid? Id { get; set; }
+
+    [Required]
+    public Guid StudentUserId { get; set; }
+
+    public Guid? AssignedToUserId { get; set; }
+    public Guid? ClassId { get; set; }
+    public required string Title { get; set; }
+    public string? Description { get; set; }
+    public string? FollowupType { get; set; }
+    public string? Priority { get; set; }
+    public string? Status { get; set; }
+    public DateTimeOffset? DueAt { get; set; }
+    public JsonElement Metadata { get; set; } = JsonDefaults.Object();
+
+    public UpsertTenantAdminStudentFollowupCommand ToCommand()
+    {
+        return new UpsertTenantAdminStudentFollowupCommand(
+            Id,
+            StudentUserId,
+            AssignedToUserId,
+            ClassId,
+            Title,
+            Description,
+            FollowupType,
+            Priority,
+            Status,
+            DueAt,
+            Metadata);
+    }
+}
--- a/Tiku.Api/Controllers/TenantAdminDirectController.cs
+++ b/Tiku.Api/Controllers/TenantAdminDirectController.cs
@@ -0,0 +1,159 @@
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+using Tiku.Api.Contracts;
+using Tiku.Application.Catalog;
+using Tiku.Application.Content;
+using Tiku.Application.Security;
+using Tiku.Application.TenantAdmin;
+
+namespace Tiku.Api.Controllers;
+
+[ApiController]
+[Authorize(Policy = TikuPolicies.TenantAdmin)]
+[Produces("application/json")]
+[Route("api/tenant-admin")]
+public sealed class TenantAdminDirectController(
+    ITenantAdminDirectService tenantAdminService,
+    ICurrentUser currentUser,
+    ICurrentTenant currentTenant) : ControllerBase
+{
+    [HttpGet("classes")]
+    [EndpointSummary("查询租户班级")]
+    [ProducesResponseType<TenantAdminClassList>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<TenantAdminClassList>> GetClasses(
+        [FromQuery] TenantAdminClassQueryDto query,
+        CancellationToken cancellationToken)
+    {
+        return Ok(await tenantAdminService.GetClassesAsync(ResolveActor(), query.ToFilter(), cancellationToken));
+    }
+
+    [HttpPut("classes")]
+    [EndpointSummary("新增或更新租户班级")]
+    [ProducesResponseType<ContentManagementResult<TenantAdminClassItem>>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<ContentManagementResult<TenantAdminClassItem>>> UpsertClass(
+        UpsertTenantAdminClassDto request,
+        CancellationToken cancellationToken)
+    {
+        return Ok(await tenantAdminService.UpsertClassAsync(ResolveActor(), request.ToCommand(), cancellationToken));
+    }
+
+    [HttpPost("classes/disable")]
+    [EndpointSummary("停用租户班级")]
+    [ProducesResponseType<ContentManagementResult<TenantAdminClassItem>>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<ContentManagementResult<TenantAdminClassItem>>> DisableClass(
+        [FromBody] Guid classId,
+        CancellationToken cancellationToken)
+    {
+        return Ok(await tenantAdminService.DisableClassAsync(ResolveActor(), classId, cancellationToken));
+    }
+
+    [HttpGet("classes/members")]
+    [EndpointSummary("查询班级成员")]
+    [ProducesResponseType<CatalogList<TenantAdminClassMemberItem>>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<CatalogList<TenantAdminClassMemberItem>>> GetClassMembers(
+        [FromQuery] TenantAdminClassMemberQueryDto query,
+        CancellationToken cancellationToken)
+    {
+        return Ok(await tenantAdminService.GetClassMembersAsync(ResolveActor(), query.ToFilter(), cancellationToken));
+    }
+
+    [HttpPut("classes/members")]
+    [EndpointSummary("新增或更新班级成员")]
+    [ProducesResponseType<ContentManagementResult<TenantAdminClassMemberItem>>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<ContentManagementResult<TenantAdminClassMemberItem>>> UpsertClassMember(
+        UpsertTenantAdminClassMemberDto request,
+        CancellationToken cancellationToken)
+    {
+        return Ok(await tenantAdminService.UpsertClassMemberAsync(ResolveActor(), request.ToCommand(), cancellationToken));
+    }
+
+    [HttpPost("classes/members/remove")]
+    [EndpointSummary("移除班级成员")]
+    [ProducesResponseType<ContentManagementResult<TenantAdminClassMemberItem>>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<ContentManagementResult<TenantAdminClassMemberItem>>> RemoveClassMember(
+        RemoveTenantAdminClassMemberDto request,
+        CancellationToken cancellationToken)
+    {
+        return Ok(await tenantAdminService.RemoveClassMemberAsync(ResolveActor(), request.ClassMemberId, cancellationToken));
+    }
+
+    [HttpGet("students")]
+    [EndpointSummary("查询租户学生")]
+    [ProducesResponseType<TenantAdminStudentList>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<TenantAdminStudentList>> GetStudents(
+        [FromQuery] TenantAdminStudentQueryDto query,
+        CancellationToken cancellationToken)
+    {
+        return Ok(await tenantAdminService.GetStudentsAsync(ResolveActor(), query.ToFilter(), cancellationToken));
+    }
+
+    [HttpPut("students")]
+    [EndpointSummary("新增或更新租户学生档案")]
+    [ProducesResponseType<ContentManagementResult<TenantAdminStudentItem>>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<ContentManagementResult<TenantAdminStudentItem>>> UpsertStudent(
+        UpsertTenantAdminStudentDto request,
+        CancellationToken cancellationToken)
+    {
+        return Ok(await tenantAdminService.UpsertStudentAsync(ResolveActor(), request.ToCommand(), cancellationToken));
+    }
+
+    [HttpPost("students/status")]
+    [EndpointSummary("更新租户学生状态")]
+    [ProducesResponseType<ContentManagementResult<TenantAdminStudentStatusItem>>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<ContentManagementResult<TenantAdminStudentStatusItem>>> UpdateStudentStatus(
+        UpdateTenantAdminStudentStatusDto request,
+        CancellationToken cancellationToken)
+    {
+        return Ok(await tenantAdminService.UpdateStudentStatusAsync(ResolveActor(), request.ToCommand(), cancellationToken));
+    }
+
+    [HttpGet("student-notes")]
+    [EndpointSummary("查询学生备注")]
+    [ProducesResponseType<CatalogList<TenantAdminStudentNoteItem>>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<CatalogList<TenantAdminStudentNoteItem>>> GetStudentNotes(
+        [FromQuery] TenantAdminStudentActivityQueryDto query,
+        CancellationToken cancellationToken)
+    {
+        return Ok(await tenantAdminService.GetStudentNotesAsync(ResolveActor(), query.ToFilter(), cancellationToken));
+    }
+
+    [HttpPut("student-notes")]
+    [EndpointSummary("新增或更新学生备注")]
+    [ProducesResponseType<ContentManagementResult<TenantAdminStudentNoteItem>>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<ContentManagementResult<TenantAdminStudentNoteItem>>> UpsertStudentNote(
+        UpsertTenantAdminStudentNoteDto request,
+        CancellationToken cancellationToken)
+    {
+        return Ok(await tenantAdminService.UpsertStudentNoteAsync(ResolveActor(), request.ToCommand(), cancellationToken));
+    }
+
+    [HttpGet("student-followups")]
+    [EndpointSummary("查询学生跟进")]
+    [ProducesResponseType<CatalogList<TenantAdminStudentFollowupItem>>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<CatalogList<TenantAdminStudentFollowupItem>>> GetStudentFollowups(
+        [FromQuery] TenantAdminStudentActivityQueryDto query,
+        CancellationToken cancellationToken)
+    {
+        return Ok(await tenantAdminService.GetStudentFollowupsAsync(ResolveActor(), query.ToFilter(), cancellationToken));
+    }
+
+    [HttpPut("student-followups")]
+    [EndpointSummary("新增或更新学生跟进")]
+    [ProducesResponseType<ContentManagementResult<TenantAdminStudentFollowupItem>>(StatusCodes.Status200OK)]
+    public async Task<ActionResult<ContentManagementResult<TenantAdminStudentFollowupItem>>> UpsertStudentFollowup(
+        UpsertTenantAdminStudentFollowupDto request,
+        CancellationToken cancellationToken)
+    {
+        return Ok(await tenantAdminService.UpsertStudentFollowupAsync(ResolveActor(), request.ToCommand(), cancellationToken));
+    }
+
+    private TenantAdminActor ResolveActor()
+    {
+        if (currentTenant.TenantId is null || currentUser.UserId is null)
+        {
+            throw new TenantAdminDirectException("Tenant admin actor was not resolved.", "tenant_admin_access_denied");
+        }
+
+        return new TenantAdminActor(currentTenant.TenantId.Value, currentUser.UserId.Value);
+    }
+}
--- a/Tiku.Api/Middleware/ExceptionHandlingMiddleware.cs
+++ b/Tiku.Api/Middleware/ExceptionHandlingMiddleware.cs
@@ -9,6 +9,7 @@ using Tiku.Infrastructure.Learning;
 using Tiku.Infrastructure.Profile;
 using Tiku.Infrastructure.QuestionBanks;
 using Tiku.Infrastructure.Scoreline;
+using Tiku.Application.TenantAdmin;

 namespace Tiku.Api.Middleware;

@@ -161,6 +162,16 @@ public sealed class ExceptionHandlingMiddleware(
                return;
            }

+            if (exception is TenantAdminDirectException tenantAdminDirectException)
+            {
+                await WriteProblemAsync(
+                    context,
+                    tenantAdminDirectException.Message,
+                    TenantAdminDirectStatusCode(tenantAdminDirectException.Code),
+                    tenantAdminDirectException.Code);
+                return;
+            }
+
            if (exception is ObjectStorageException storageException)
            {
                await WriteProblemAsync(
@@ -285,4 +296,16 @@ public sealed class ExceptionHandlingMiddleware(
            _ => StatusCodes.Status400BadRequest
        };
    }
+
+    private static int TenantAdminDirectStatusCode(string code)
+    {
+        return code switch
+        {
+            "tenant_admin_access_denied" => StatusCodes.Status403Forbidden,
+            "class_not_found" or "class_member_not_found" or "student_not_found" or "user_not_found" => StatusCodes.Status404NotFound,
+            "tenant_member_not_found" => StatusCodes.Status400BadRequest,
+            _ when code.EndsWith("_not_found", StringComparison.Ordinal) => StatusCodes.Status400BadRequest,
+            _ => StatusCodes.Status400BadRequest
+        };
+    }
 }