fix: rank the Berlin Group v1.3 alias by identity, not by its configured name

standardPrecedence ranked a version by its apiStandard string, and the alias
takes that string from the first segment of berlin_group_v1_3_alias_path. A
deployment may point it at a name an existing standard already uses:
configured as "BG/v9" the alias reports ScannedApiVersion("BG", "BG", "v9"),
ranks alongside Berlin Group, and -- sorting after "v2" on the tie-breaker --
comes last, so its re-stamped copies won getBalances, getAccountList and
getAccountBalances away from the canonical docs it had copied. Metrics,
top-apis and popular-apis would then report BGv9-getBalances instead of
BGv1.3-getBalances. The comment on standardPrecedence claimed the opposite,
that the alias "can never override a first-class standard no matter how a
deployment configures it".

Match the alias by identity instead and rank it below every listed standard,
which makes that claim true for any configuration. sortKey takes the derived
alias version as a curried parameter and is package-private so the guarantee
can be tested against a synthetic alias, rather than only under whichever
berlin_group_v1_3_alias_path the JVM happens to have booted with.

Verified both directions with the new scenario: reverting to the string-based
rank fails it with "(1,BG,v9) was not less than (1,BG,v2)" -- the mechanism
itself -- and it passes with the fix. Full local suite 3576/0.

Author: hongwei1

obp-api/src/main/scala/code/api/util/ResourceDocRegistry.scala

@@ -73,7 +73,7 @@ object ResourceDocRegistry {
       ScannedApis.versionMapScannedApis.toSeq
         .collect { case (version: ScannedApiVersion, apis) if !explicit.contains(version) =>
           version -> (() => apis.allResourceDocs.toSeq) }
-        .sortBy(entry => sortKey(entry._1))
+        .sortBy(entry => sortKey(code.api.berlin.group.v1_3.OBP_BERLIN_GROUP_1_3_Alias.apiVersion)(entry._1))
         .foldLeft(ListMap.empty[ApiVersion, () => Seq[ResourceDoc]])(_ + _)
     explicit ++ scanned
   }
@@ -82,27 +82,43 @@ object ResourceDocRegistry {
    * Standards in ASCENDING precedence: a standard later in this list wins a partialFunctionName it
    * shares with an earlier one, because the `.toMap` consumers keep the last entry. This
    * reproduces the order of the hand-written union that preceded this registry (UK Open Banking,
-   * then Berlin Group).
-   *
-   * A standard that is not listed ranks below all of them -- including the Berlin Group v1.3 alias,
-   * whose apiStandard is whatever `berlin_group_v1_3_alias_path` names, so it can never override a
-   * first-class standard no matter how a deployment configures it.
+   * then Berlin Group). A standard that is not listed ranks below all of them.
    */
   private val standardPrecedence: List[String] =
     List(ApiVersion.ukOpenBankingV20.apiStandard, ConstantsBG.berlinGroupVersion1.apiStandard)
 
+  /** Below every entry of standardPrecedence, whose lowest index is -1 for an unlisted standard. */
+  private val derivedStandardRank: Int = -2
+
   /**
    * Total order over registry keys: precedence first, then the version's own identity.
    *
+   * `derivedAliasVersion` is the version of a standard that merely re-publishes another standard's
+   * docs -- today only the Berlin Group v1.3 alias. It is matched by identity, NOT by its
+   * apiStandard, because that string is the first segment of `berlin_group_v1_3_alias_path` and a
+   * deployment may legitimately choose one that an existing standard already uses: configured as
+   * "BG/v9" the alias would otherwise rank alongside Berlin Group and, sorting after "v2", let its
+   * re-stamped copies win getBalances, getAccountList and getAccountBalances away from the
+   * canonical docs it copied. Ranking it derivedStandardRank keeps that impossible for any
+   * configuration.
+   *
    * The tie-breaker is (apiStandard, apiShortVersion) rather than fullyQualifiedVersion because
    * that pair is exactly ScannedApiVersion's equals/hashCode key, so two distinct keys of a Map
    * keyed by version always differ in it and sortBy never has to fall back to the unordered input.
    * fullyQualifiedVersion concatenates the two (apiStandard.toUpperCase + apiShortVersion) and can
    * therefore collide across distinct keys -- ("BG", "v1.3") and ("BGV", "1.3") both render
    * "BGV1.3" -- which a deployment could reach through berlin_group_v1_3_alias_path.
+   *
+   * Curried and package-private so a test can rank against a synthetic alias without having to
+   * restart the JVM under a different berlin_group_v1_3_alias_path.
    */
-  private def sortKey(version: ScannedApiVersion): (Int, String, String) =
-    (standardPrecedence.indexOf(version.apiStandard), version.apiStandard, version.apiShortVersion)
+  private[util] def sortKey(derivedAliasVersion: ScannedApiVersion)
+                           (version: ScannedApiVersion): (Int, String, String) = {
+    val rank =
+      if (version == derivedAliasVersion) derivedStandardRank
+      else standardPrecedence.indexOf(version.apiStandard)
+    (rank, version.apiStandard, version.apiShortVersion)
+  }
 
   /** What the per-version resource-docs dispatcher serves for this version (empty if unknown). */
   def docsFor(version: ApiVersion): Seq[ResourceDoc] = registry.get(version).map(_ ()).getOrElse(Nil)

obp-api/src/test/scala/code/api/util/ResourceDocRegistryParityTest.scala

@@ -1,5 +1,6 @@
 package code.api.util
 
+import code.api.berlin.group.ConstantsBG
 import code.api.berlin.group.v1_3.Http4sBGv13Alias
 import code.setup.ServerSetup
 import com.openbankproject.commons.util.{ApiStandards, ApiVersion, ScannedApiVersion}
@@ -117,6 +118,27 @@ class ResourceDocRegistryParityTest extends ServerSetup {
       resolved.get("getAccountBalances") shouldBe Some("BGv2-getAccountBalances")
     }
 
+    // The Berlin Group v1.3 alias only re-publishes the canonical BG v1.3 docs, so it must never
+    // win a partialFunctionName away from the standard it copied. Its apiStandard is the first
+    // segment of berlin_group_v1_3_alias_path, so a deployment can point it at a name an existing
+    // standard already uses ("BG/v9"); ranking by that string alone put the alias alongside Berlin
+    // Group and, sorting after "v2", ahead of it. Ranking is by identity instead, and the synthetic
+    // alias below exercises the colliding configuration without needing a JVM under that prop.
+    scenario("a derived alias never outranks the standard it re-publishes", RegistryParityTag) {
+      val syntheticAlias = ScannedApiVersion("BG", "BG", "v9")
+      val rankOf = ResourceDocRegistry.sortKey(syntheticAlias) _
+      withClue("the alias must sort before Berlin Group, i.e. lose the `.toMap` last-wins race ") {
+        rankOf(syntheticAlias) should be < rankOf(ConstantsBG.berlinGroupVersion2)
+        rankOf(syntheticAlias) should be < rankOf(ConstantsBG.berlinGroupVersion1)
+      }
+      withClue("the alias must also sort before UK Open Banking ") {
+        rankOf(syntheticAlias) should be < rankOf(ApiVersion.ukOpenBankingV401)
+      }
+      withClue("UK must still sort before Berlin Group, so BG keeps the names they share ") {
+        rankOf(ApiVersion.ukOpenBankingV401) should be < rankOf(ConstantsBG.berlinGroupVersion2)
+      }
+    }
+
     // An unconfigured configuration-gated standard reports ScannedApiVersion("", "", ""), whose
     // fullyQualifiedVersion is "" as well. While ScannedApis kept it, ApiVersionUtils.valueOf("")
     // resolved successfully and GET /obp/v7.0.0/resource-docs//obp answered 200 with an empty