Introduce the concept of sort keys.

Progress towards #2525.

The basic idea is to replace a lot of scattered scoring logic (which
might become more complex when we introduce more scoring options such as
optimization problems) by encoding sufficient information within the
existing rank cache.

The information is encoded into a sort key that is designed to be sorted
descendingly. The sort key is a tuple (serialized as string into the
database) of fixed precision decimals. Each tuple uses 9 decimals and is
left padded with `0`s, enabling sorting via standard database query
operations. For ascendingly sorted tuple entries (e.g. penalty time),
values are subtracted from a very large constant - this ensures that
that the key can be sorted as a whole.

For example, with ICPC scoring, the top 3 teams from NWERC 2024 receive
these sort keys:
```
00000000000000000000013.000000000,99999999999999999998725.000000000,99999999999999999999711.000000000
00000000000000000000011.000000000,99999999999999999998918.000000000,99999999999999999999701.000000000
00000000000000000000011.000000000,99999999999999999998916.000000000,99999999999999999999706.000000000
```

This mechanism should facilitate the implementation of other planned
scoring methods, particularly partial scoring and optimization problems,
with reasonable complexity in the business logic.

We do use `bcmath` with fixed precision to avoid numerical precision
issues caused by the order of floating point operations.  While not
critical currently, this will be essential when handling non-integers,
such as those in optimization problems.

The new mechanism also caches some computations and thus improves
scoreboard computation efficiency.

Author: meisterT

doc/manual/install-domserver.rst

@@ -37,14 +37,14 @@ GNU/Linux, or one of its derivative distributions like Ubuntu::
 
   sudo apt install libcgroup-dev make acl zip unzip pv mariadb-server apache2 \
         php php-fpm php-gd php-cli php-intl php-mbstring php-mysql \
-        php-curl php-json php-xml php-zip composer ntp python3-yaml
+        php-curl php-json php-xml php-zip composer ntp python3-yaml php-bcmath
 
 The following command can be used on Fedora, and related distributions like
 Red Hat Enterprise Linux and Rocky Linux (before V9)::
 
   sudo dnf install libcgroup-devel make acl zip unzip pv mariadb-server httpd \
         php-gd php-cli php-intl php-mbstring php-mysqlnd php-fpm \
-        php-xml php-zip composer chronyd python3-pyyaml
+        php-xml php-zip composer chronyd python3-pyyaml php-bcmath
 
 `nginx` can be used as an alternate web server.
 

webapp/composer.json

@@ -40,6 +40,7 @@
 	],
 	"require": {
 		"php": "^8.1.0",
+		"ext-bcmath": "*",
 		"ext-ctype": "*",
 		"ext-curl": "*",
 		"ext-fileinfo": "*",

webapp/composer.lock

@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DoctrineMigrations;
+
+use Doctrine\DBAL\Schema\Schema;
+use Doctrine\Migrations\AbstractMigration;
+
+/**
+ * Auto-generated Migration: Please modify to your needs!
+ */
+final class Version20250309122806 extends AbstractMigration
+{
+    public function getDescription(): string
+    {
+        return 'Add sort keys to rankcache, allowing us to support different scoring functions efficiently and elegantly';
+    }
+
+    public function up(Schema $schema): void
+    {
+        // this up() migration is auto-generated, please modify it to your needs
+        $this->addSql('ALTER TABLE rankcache ADD sort_key_public TEXT DEFAULT \'\' NOT NULL COMMENT \'Opaque sort key for public audience.\', ADD sort_key_restricted TEXT DEFAULT \'\' NOT NULL COMMENT \'Opaque sort key for restricted audience.\'');
+        $this->addSql('CREATE INDEX sortKeyPublic ON rankcache (sort_key_public)');
+        $this->addSql('CREATE INDEX sortKeyRestricted ON rankcache (sort_key_restricted)');
+    }
+
+    public function down(Schema $schema): void
+    {
+        // this down() migration is auto-generated, please modify it to your needs
+        $this->addSql('DROP INDEX sortKeyPublic ON rankcache');
+        $this->addSql('DROP INDEX sortKeyRestricted ON rankcache');
+        $this->addSql('ALTER TABLE rankcache DROP sort_key_public, DROP sort_key_restricted');
+    }
+
+    public function isTransactional(): bool
+    {
+        return false;
+    }
+}

webapp/migrations/Version20250309122806.php

@@ -412,7 +412,7 @@ protected function getResultsHtml(
         $filter           = new Filter();
         $filter->categories = $categoryIds;
         $scoreboard = $this->scoreboardService->getScoreboard($contest, true, $filter);
-        $teams      = $scoreboard->getTeams();
+        $teams      = $scoreboard->getTeamsInDescendingOrder();
 
         $teamNames = [];
         foreach ($teams as $team) {

webapp/src/Controller/Jury/ImportExportController.php

@@ -1,6 +1,7 @@
 <?php declare(strict_types=1);
 namespace App\Entity;
 
+use Doctrine\DBAL\Platforms\AbstractMySQLPlatform;
 use Doctrine\ORM\Mapping as ORM;
 
 /**
@@ -18,6 +19,8 @@
 #[ORM\Index(columns: ['cid', 'points_public', 'totaltime_public', 'totalruntime_public'], name: 'order_public')]
 #[ORM\Index(columns: ['cid'], name: 'cid')]
 #[ORM\Index(columns: ['teamid'], name: 'teamid')]
+#[ORM\Index(columns: ['sort_key_public'], name: 'sortKeyPublic')]
+#[ORM\Index(columns: ['sort_key_restricted'], name: 'sortKeyRestricted')]
 class RankCache
 {
     #[ORM\Column(options: [
@@ -62,6 +65,20 @@ class RankCache
     #[ORM\JoinColumn(name: 'teamid', referencedColumnName: 'teamid', onDelete: 'CASCADE')]
     private Team $team;
 
+    #[ORM\Column(
+        type: 'text',
+        length: AbstractMySQLPlatform::LENGTH_LIMIT_TEXT,
+        options: ['comment' => 'Opaque sort key for public audience.', 'default' => '']
+    )]
+    private string $sortKeyPublic = '';
+
+    #[ORM\Column(
+        type: 'text',
+        length: AbstractMySQLPlatform::LENGTH_LIMIT_TEXT,
+        options: ['comment' => 'Opaque sort key for restricted audience.', 'default' => '']
+    )]
+    private string $sortKeyRestricted = '';
+
     public function setPointsRestricted(int $pointsRestricted): RankCache
     {
         $this->points_restricted = $pointsRestricted;
@@ -149,4 +166,26 @@ public function getTeam(): Team
     {
         return $this->team;
     }
+
+    public function setSortKeyPublic(string $sortKeyPublic): RankCache
+    {
+        $this->sortKeyPublic = $sortKeyPublic;
+        return $this;
+    }
+
+    public function getSortKeyPublic(): string
+    {
+        return $this->sortKeyPublic;
+    }
+
+    public function setSortKeyRestricted(string $sortKeyRestricted): RankCache
+    {
+        $this->sortKeyRestricted = $sortKeyRestricted;
+        return $this;
+    }
+
+    public function getSortKeyRestricted(): string
+    {
+        return $this->sortKeyRestricted;
+    }
 }

webapp/src/Entity/RankCache.php

@@ -16,7 +16,7 @@ protected function loadAwards(Contest $contest, Scoreboard $scoreboard): void
     {
         $group_winners = $problem_winners = $problem_shortname = [];
         $groups = [];
-        foreach ($scoreboard->getTeams() as $team) {
+        foreach ($scoreboard->getTeamsInDescendingOrder() as $team) {
             $teamid = $team->getExternalid();
             if ($scoreboard->isBestInCategory($team)) {
                 $catId = $team->getCategory()->getExternalid();