Implement UC-FM-05: answer inbound device-location queries from SRM

Sergio Gimenezrequested to merge
feat/uc-fm-05-inbound-queries into develop

Delivers UC-FM-05 (Inbound Federated Synchronous Query) for Device Location, and the APIForwarding half of Outbound Federation #3 (closed) in the delivery plan.

A partner operator asks us where one of our subscribers is:

POST /operatorplatform/federation/v1/{federationContextId}/apiservice/DeviceLocation
Authorization: Bearer <fed-mgmt token>

{ "apiServiceId": "DeviceLocation",
  "customerID": "...", "customerInfo": "ACME Corp", "txnIdentifier": "partner-txn-1",
  "ServiceAPIBody": { "mediaType": "application/json",
                      "APIContent": { "device": { "phoneNumber": "+34612345678" }, "maxAge": 60 } } }

FM authenticates the partner, resolves their federation_contexts row, checks the agreement permits the device-location family and which local service_specification_id it maps to, calls SRM POST /internal/network-queries/location, and returns SRM's answer inside the OPG.04 serviceAPIResponse wrapper (apiResponse.responseContent).

This is the inbound mirror of the outbound hand-off already on develop: same wrapper, opposite direction.

Verification

Seven unit tests, plus an end-to-end run against SRM from origin/feat/location-retrieval-api, with real Keycloak tokens:

{"type":"urn:oop:ewbi:error:service-not-applicable","title":"Service Not Applicable","status":422,
 "detail":"No local capability can serve the requested target.",
 "instance":"/operatorplatform/federation/v1/fed-ctx-q/apiservice/DeviceLocation"}

with the matching audit row:

api_type        | device-location
direction       | inbound
status          | failed
external_txn_id | txn-uc05
operation_id    |

149 tests pass; ruff and mypy clean.

Known Limits

  • DeviceStatus is not implemented. SRM exposes only the location query, so any other serviceAPINameVal returns 404 service-api-unsupported rather than pretending to support it. UC-FM-05 is therefore half delivered by design; the remaining half is blocked on SRM.
  • A successful location answer has never been observed. That needs a TF-SDK control path configured in SRM, which this repository does not own. Every hop up to and including SRM's decision is exercised.

Merge request reports