================================================================================
 BrightAgreementsController - Summary & Response Structures
 File: SonWinCommonAPI/Controllers/BrightAgreementsController.cs
================================================================================

--------------------------------------------------------------------------------
 WHAT THE CONTROLLER DOES
--------------------------------------------------------------------------------

BrightAgreementsController exposes the active agreements / contracts
("kontrakter") tied to a single customer and a single service in the
SonWin/Sonlinc system, shaped into the "Bright" agreement contract. It requires
authorization ([Authorize]) and, on any thrown exception, goes through
CustomBase.HandleError which logs the error and returns HTTP 500 with the
exception message in the body.

IMPORTANT - serviceId MUST be the EAN/MeteringPointId:
The controller's remark states "The serviceId have to be the
edielnumber(MeteringPointId) for this method to return the correct data."
The query filters kontr.EANNR = @EanNumber, so passing anything other than the
metering point id / EAN number (the 18-digit ediel number) returns no rows.

--------------------------------------------------------------------------------
 METHODS
--------------------------------------------------------------------------------

1) GetAgreements
   Route:    

  • GET /bright/agreements

Params:  

  • customerId (required)
  • serviceId (required)   serviceId MUST be the EAN / MeteringPointId (ediel number).
  • (+ CancellationToken)
                 

Returns

  • 200 OK -> IEnumerable<BrightAgreement>
  • 400 BadRequest    (declared; see note below)
  • 401 Unauthorized


What it does:
     Returns the list of active agreements for the given customer + service.
     It first validates the customer exists and validates input (customerId required; serviceId required and digits
     only).

Validation that affects the result (all surface as HTTP 500 with a message):

  • Customer does not exist        -> commonValidator.ValidateCustomer throws
  • Missing customerId             -> "Missing parameter 'CustomerId'."
  • Missing serviceId              -> "Missing parameter 'ServiceId'."
  • serviceId not digits-only      -> "Parameter 'ServiceId' must contain digits only."
    Duplicate ContractName in out  -> "Duplicate ContractName(s) found: ..."  
  • Rows for >1 customer / wrong   -> "Agreements belong to multiple customer
  • Agreements belongs to wrong CustomerId. Expected id: {id}"

--------------------------------------------------------------------------------
 RESPONSE STRUCTURE (BrightAgreement)
--------------------------------------------------------------------------------

Returned as a JSON ARRAY (IEnumerable<BrightAgreement>), one element per
distinct active contract (by ContractName) found for the customer + service.
NOTE: every field below is currently HARDCODED in the service mapping; the
commented-out code shows the intended Data/Derived sources for the future.

Agreement response
[
  {
    "Id":            <value>      		// Hardcoded: set to the supplied serviceId (eanNumber), NOT the contract id. (Intended Data: AgreementId / grouping key.)
    "ServiceId":     <value>      		// Hardcoded: set to the supplied serviceId (eanNumber). (Intended Data: the service id from the row.)
    "DisplayName":   "Dit elprodukt" 	// Hardcoded: literal Danish string "Dit elprodukt". (Intended Data: contract name - BAKONTRAKT/AFORBKONTR.KONTRAKT.)
    "AgreementType": null         		// Hardcoded null: always null today.(Intended Data: BAKONTRAKT.TYP -> ContractType.)
    "StartDate":     null         		// Hardcoded null: always null today.(Intended Data: AFORBKONTR/BAKONTRAKT.FRADATO -> ContractActiveFrom.)
    "EndDate":       null         		// Hardcoded null: always null today.(Intended Data: AFORBKONTR/BAKONTRAKT.TILDATO -> ContractActiveTo.)
    "HasCapacityTariffs": null    		// Hardcoded null: always null today.(Intended Data: DbAgreement.HasCapacityTariffs - not populated by SQL.)
    "Info":          []           		// Hardcoded: always an empty array (new List<BrightAgreementInfo>()).(Intended Data: list of {Title, Key, Value} from InfoTitle/InfoKey/InfoValue rows - currently not populated.)
  }
]
Each Info entry
 {
    "Title": <value>             // Data (intended): DbAgreement.InfoTitle - not emitted today.
    "Key":   <value>             // Data (intended): DbAgreement.InfoKey   - not emitted today.
    "Value": <value>             // Data (intended): DbAgreement.InfoValue - not emitted today.
  }


  • No labels