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/PeopleModels.cs

@@ -0,0 +1,171 @@
+using HSchool.Content;
+using HSchool.People;
+
+namespace HSchool.Server.Api;
+
+internal enum PersonLookupError
+{
+    None,
+    UnknownSchool,
+    UnknownPerson,
+}
+
+internal sealed record PersonCardResult(PersonCardResponse? Card, PersonLookupError Error);
+
+internal sealed record PeopleListResponse(
+    int Total,
+    int Page,
+    int PageSize,
+    IReadOnlyList<PersonListItemResponse> People,
+    PeopleFilterOptionsResponse Filters);
+
+internal sealed record PeopleFilterOptionsResponse(
+    IReadOnlyList<int> Years,
+    IReadOnlyList<string> Letters,
+    IReadOnlyList<DefLabelResponse> Positions);
+
+internal sealed record DefLabelResponse(string DefName, string Label);
+
+internal sealed record PersonListItemResponse(
+    string Id,
+    string FullName,
+    string Surname,
+    string Given,
+    string Patronymic,
+    bool Female,
+    int Age,
+    IReadOnlyList<string> Roles,
+    int? ClassYear,
+    string? ClassLetter,
+    string? Position,
+    string? PositionLabel);
+
+internal sealed record PersonCardResponse(
+    string Id,
+    string FullName,
+    string Surname,
+    string Given,
+    string Patronymic,
+    bool Female,
+    int Age,
+    DateTime BirthDate,
+    IReadOnlyList<string> Roles,
+    int? ClassYear,
+    string? ClassLetter,
+    string? Position,
+    string? PositionLabel,
+    IReadOnlyList<LabeledStatResponse> Body,
+    IReadOnlyList<LabeledStatResponse> Skills,
+    IReadOnlyList<DefLabelResponse> Traits,
+    IReadOnlyList<NeedStatResponse> Needs,
+    PersonFamilyResponse Family);
+
+internal sealed record LabeledStatResponse(string Id, string Label, string Value);
+
+internal sealed record NeedStatResponse(string Id, string Label, float Value);
+
+internal sealed record PersonFamilyResponse(
+    IReadOnlyList<PersonRelResponse> Parents,
+    IReadOnlyList<PersonRelResponse> Children,
+    IReadOnlyList<PersonRelResponse> Siblings,
+    IReadOnlyList<PersonRelResponse> Partners);
+
+internal sealed record PersonRelResponse(string Id, string FullName, bool Female);
+
+internal static class PeopleListMapper
+{
+    public static PeopleListResponse From(
+        Roster roster,
+        RosterPage page,
+        DateTime asOf,
+        DefCatalog? catalog,
+        string locale,
+        RosterQuery query)
+    {
+        var classes = roster.Classes.ToDictionary(schoolClass => schoolClass.Id, StringComparer.Ordinal);
+        var people = page.People
+            .Select(person => Item(person, classes, asOf, catalog, locale))
+            .ToArray();
+        return new PeopleListResponse(page.Total, query.Page, query.PageSize, people, FilterOptions(roster, catalog, locale));
+    }
+
+    private static PersonListItemResponse Item(
+        Person person,
+        IReadOnlyDictionary<string, SchoolClass> classes,
+        DateTime asOf,
+        DefCatalog? catalog,
+        string locale)
+    {
+        int? year = null;
+        string? letter = null;
+        if (person.ClassId is { } classId && classes.TryGetValue(classId, out var schoolClass))
+        {
+            year = schoolClass.Year;
+            letter = schoolClass.Letter;
+        }
+
+        return new PersonListItemResponse(
+            person.Id,
+            person.Name.Full,
+            person.Name.Surname,
+            person.Name.Given,
+            person.Name.Patronymic,
+            person.Female,
+            person.AgeOn(asOf),
+            RolesOf(person),
+            year,
+            letter,
+            person.Position,
+            PositionLabel(catalog, locale, person.Position));
+    }
+
+    internal static string[] RolesOf(Person person)
+    {
+        var roles = new List<string>(3);
+        if (person.IsStudent)
+        {
+            roles.Add(PersonRoles.Student);
+        }
+
+        if (person.IsStaff)
+        {
+            roles.Add(PersonRoles.Staff);
+        }
+
+        if (person.IsParent)
+        {
+            roles.Add(PersonRoles.Parent);
+        }
+
+        return [.. roles];
+    }
+
+    internal static string? PositionLabel(DefCatalog? catalog, string locale, string? position)
+    {
+        if (position is null)
+        {
+            return null;
+        }
+
+        if (catalog is not null && catalog.Positions.TryGetValue(position, out var def))
+        {
+            return catalog.Label(locale, def);
+        }
+
+        return position;
+    }
+
+    private static PeopleFilterOptionsResponse FilterOptions(Roster roster, DefCatalog? catalog, string locale)
+    {
+        var years = roster.Classes.Select(schoolClass => schoolClass.Year).Distinct().OrderBy(year => year).ToArray();
+        var letters = roster.Classes.Select(schoolClass => schoolClass.Letter).Distinct().OrderBy(letter => letter, StringComparer.Ordinal).ToArray();
+        var positions = roster.People
+            .Select(person => person.Position)
+            .Where(position => position is not null)
+            .Distinct(StringComparer.Ordinal)
+            .OrderBy(position => PositionLabel(catalog, locale, position) ?? position, StringComparer.Ordinal)
+            .Select(position => new DefLabelResponse(position!, PositionLabel(catalog, locale, position) ?? position!))
+            .ToArray();
+        return new PeopleFilterOptionsResponse(years, letters, positions);
+    }
+}