M8-T12: scope energy contracts

openapi/openapi.yaml

@@ -877,12 +877,21 @@ paths:
       description: 'List all energy contracts with their active status.
 
 
-        Returns a flat list (no embedded version history); use
+        Scope defaults to ``electricity`` for old clients. Returns a flat list (no
+        embedded version history); use
 
         GET /api/energy/contracts/{id} to fetch the full version history for a
 
         specific contract.'
       operationId: list_energy_contracts_api_energy_contracts_get
+      parameters:
+      - name: scope
+        in: query
+        required: false
+        schema:
+          type: string
+          default: electricity
+          title: Scope
       responses:
         '200':
           description: Successful Response
@@ -890,6 +899,12 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ContractListResponse'
+        '422':
+          description: Validation Error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HTTPValidationError'
     post:
       tags:
       - api-energy-contracts
@@ -974,14 +989,14 @@ paths:
 
         - ``name``: updates the human-readable label.
 
-        - ``active=true``: activates this contract (all others are deactivated).
+        - ``active=true``: activates this contract (same-scope contracts are deactivated).
 
         - ``active=false``: deactivates this contract (no effect on others).
 
 
-        At most one contract may be active at any time; the service layer enforces
+        At most one contract may be active per scope; the service layer enforces
 
-        mutual exclusion.'
+        scope-local mutual exclusion.'
       operationId: patch_energy_contract_api_energy_contracts__contract_id__patch
       parameters:
       - name: contract_id
@@ -2768,6 +2783,13 @@ components:
           maxLength: 32
           minLength: 1
           title: Kind
+        scope:
+          anyOf:
+          - type: string
+            maxLength: 32
+            minLength: 1
+          - type: 'null'
+          title: Scope
         currency:
           type: string
           maxLength: 8
@@ -2813,6 +2835,9 @@ components:
         kind:
           type: string
           title: Kind
+        scope:
+          type: string
+          title: Scope
         active:
           type: boolean
           title: Active
@@ -2837,6 +2862,7 @@ components:
       - id
       - name
       - kind
+      - scope
       - active
       - currency
       - created_at
@@ -2901,6 +2927,9 @@ components:
         kind:
           type: string
           title: Kind
+        scope:
+          type: string
+          title: Scope
         active:
           type: boolean
           title: Active
@@ -2920,6 +2949,7 @@ components:
       - id
       - name
       - kind
+      - scope
       - active
       - currency
       - created_at