Implement people management features by adding API endpoints for retrieving school rosters and individual person cards. Enhance the UI to support a people browser with filtering and pagination capabilities. Update localization strings for improved user experience and ensure robust handling of person data. Revise documentation to reflect new API functionalities and update tests to validate the new features.

src/HSchool.Server/Api/SchoolEndpoints.cs

@@ -1,12 +1,13 @@
 using HSchool.Content;
+using HSchool.People;
 using HSchool.Server.Game;
 using HSchool.Simulation;
 
 namespace HSchool.Server.Api;
 
 /// <summary>
-/// The main menu talks to these: list, create, delete. Everything that mutates state is handed to
-/// the supervisor as a command and awaited, so each school stays on its own worker thread.
+/// The main menu talks to these: list, create, delete. The people list reads a published roster
+/// snapshot; the person card goes through the school's mailbox because needs are live.
 /// </summary>
 internal static class SchoolEndpoints
 {
@@ -91,6 +92,70 @@ internal static class SchoolEndpoints
             return deleted ? Results.NoContent() : Results.NotFound();
         })
         .WithName("DeleteSchool");
+
+        schools.MapGet("/{id:int}/people", (
+            int id,
+            string? role,
+            int? year,
+            string? letter,
+            string? position,
+            string? sex,
+            int? ageMin,
+            int? ageMax,
+            string? sort,
+            string? dir,
+            int? page,
+            int? pageSize,
+            string? lang,
+            GameLoopService loop) =>
+        {
+            var published = loop.FindPeople(id);
+            if (published is null)
+            {
+                return Problem(StatusCodes.Status404NotFound, "unknown-school", "That school does not exist.");
+            }
+
+            if (!TryParsePeopleQuery(role, year, letter, position, sex, ageMin, ageMax, sort, dir, page, pageSize, out var query, out var error))
+            {
+                return Problem(StatusCodes.Status400BadRequest, "invalid-query", error);
+            }
+
+            var roster = published.Roster;
+            if (roster is null)
+            {
+                return Results.Ok(new PeopleListResponse(0, query.Page, query.PageSize, [], new PeopleFilterOptionsResponse([], [], [])));
+            }
+
+            var locale = ParseLocale(lang);
+            var slice = RosterBrowser.Apply(roster, published.School.GameTime, query);
+            return Results.Ok(PeopleListMapper.From(roster, slice, published.School.GameTime, published.Catalog, locale, query));
+        })
+        .WithName("GetSchoolPeople");
+
+        schools.MapGet("/{id:int}/people/{personId}", async (
+            int id,
+            string personId,
+            string? lang,
+            GameCommandQueue commands,
+            CancellationToken cancellationToken) =>
+        {
+            if (string.IsNullOrWhiteSpace(personId) || personId.Length > 64)
+            {
+                return Problem(StatusCodes.Status400BadRequest, "invalid-query", "The person id is not valid.");
+            }
+
+            var command = new GameCommand.GetPerson(id, personId, ParseLocale(lang), NewCompletion<PersonCardResult>());
+            commands.Enqueue(command);
+
+            var outcome = await command.Result.Task.WaitAsync(CommandTimeout, cancellationToken);
+            return outcome.Error switch
+            {
+                PersonLookupError.None when outcome.Card is not null => Results.Ok(outcome.Card),
+                PersonLookupError.UnknownPerson => Problem(StatusCodes.Status404NotFound, "unknown-person", "That person is not in the school."),
+                _ => Problem(StatusCodes.Status404NotFound, "unknown-school", "That school does not exist."),
+            };
+        })
+        .WithName("GetSchoolPerson");
     }
 
     /// <summary>The supervisor must never be blocked by a continuation of a waiting request.</summary>
@@ -102,6 +167,118 @@ internal static class SchoolEndpoints
             ? SchoolNameLanguage.English
             : SchoolNameLanguage.Russian;
 
+    private static string ParseLocale(string? lang) =>
+        string.Equals(lang, "en", StringComparison.OrdinalIgnoreCase) ? "en" : "ru";
+
+    private static bool TryParsePeopleQuery(
+        string? role,
+        int? year,
+        string? letter,
+        string? position,
+        string? sex,
+        int? ageMin,
+        int? ageMax,
+        string? sort,
+        string? dir,
+        int? page,
+        int? pageSize,
+        out RosterQuery query,
+        out string error)
+    {
+        query = default;
+        error = string.Empty;
+
+        if (!string.IsNullOrWhiteSpace(role) && !HSchool.Content.PersonRoles.IsKnown(role))
+        {
+            error = "role must be student, staff or parent.";
+            return false;
+        }
+
+        if (year is < 1)
+        {
+            error = "year must be a positive integer.";
+            return false;
+        }
+
+        bool? female = null;
+        if (!string.IsNullOrWhiteSpace(sex))
+        {
+            if (sex.Equals("female", StringComparison.OrdinalIgnoreCase))
+            {
+                female = true;
+            }
+            else if (sex.Equals("male", StringComparison.OrdinalIgnoreCase))
+            {
+                female = false;
+            }
+            else
+            {
+                error = "sex must be male or female.";
+                return false;
+            }
+        }
+
+        if (ageMin is < 0 || ageMax is < 0)
+        {
+            error = "ageMin and ageMax must be zero or greater.";
+            return false;
+        }
+
+        if (ageMin is int min && ageMax is int max && min > max)
+        {
+            error = "ageMin cannot be greater than ageMax.";
+            return false;
+        }
+
+        if (!RosterBrowser.TryParseSort(sort, out var parsedSort))
+        {
+            error = "sort must be surname, age, year or position.";
+            return false;
+        }
+
+        var descending = false;
+        if (!string.IsNullOrWhiteSpace(dir))
+        {
+            if (dir.Equals("desc", StringComparison.OrdinalIgnoreCase))
+            {
+                descending = true;
+            }
+            else if (!dir.Equals("asc", StringComparison.OrdinalIgnoreCase))
+            {
+                error = "dir must be asc or desc.";
+                return false;
+            }
+        }
+
+        var parsedPage = page ?? 1;
+        if (parsedPage < 1)
+        {
+            error = "page must be 1 or greater.";
+            return false;
+        }
+
+        var parsedPageSize = pageSize ?? RosterBrowser.DefaultPageSize;
+        if (parsedPageSize < 1 || parsedPageSize > RosterBrowser.MaxPageSize)
+        {
+            error = $"pageSize must be between 1 and {RosterBrowser.MaxPageSize}.";
+            return false;
+        }
+
+        query = new RosterQuery(
+            string.IsNullOrWhiteSpace(role) ? null : role,
+            year,
+            string.IsNullOrWhiteSpace(letter) ? null : letter,
+            string.IsNullOrWhiteSpace(position) ? null : position,
+            female,
+            ageMin,
+            ageMax,
+            parsedSort,
+            descending,
+            parsedPage,
+            parsedPageSize);
+        return true;
+    }
+
     private static IResult Problem(int statusCode, string code, string detail) =>
         Results.Problem(detail: detail, statusCode: statusCode, title: code, extensions: new Dictionary<string, object?>
         {