M8-T12: scope energy contracts

openapi/openapi.json

@@ -1126,8 +1126,20 @@
           "api-energy-contracts"
         ],
         "summary": "List Energy Contracts",
-        "description": "List all energy contracts with their active status.\n\nReturns a flat list (no embedded version history); use\nGET /api/energy/contracts/{id} to fetch the full version history for a\nspecific contract.",
+        "description": "List all energy contracts with their active status.\n\nScope defaults to ``electricity`` for old clients. Returns a flat list (no embedded version history); use\nGET /api/energy/contracts/{id} to fetch the full version history for a\nspecific 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",
@@ -1138,6 +1150,16 @@
                 }
               }
             }
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            }
           }
         }
       },
@@ -1247,7 +1269,7 @@
           "api-energy-contracts"
         ],
         "summary": "Patch Energy Contract",
-        "description": "Partially update a contract: rename or change activation status.\n\n- ``name``: updates the human-readable label.\n- ``active=true``: activates this contract (all others are deactivated).\n- ``active=false``: deactivates this contract (no effect on others).\n\nAt most one contract may be active at any time; the service layer enforces\nmutual exclusion.",
+        "description": "Partially update a contract: rename or change activation status.\n\n- ``name``: updates the human-readable label.\n- ``active=true``: activates this contract (same-scope contracts are deactivated).\n- ``active=false``: deactivates this contract (no effect on others).\n\nAt most one contract may be active per scope; the service layer enforces\nscope-local mutual exclusion.",
         "operationId": "patch_energy_contract_api_energy_contracts__contract_id__patch",
         "parameters": [
           {
@@ -3705,6 +3727,19 @@
             "minLength": 1,
             "title": "Kind"
           },
+          "scope": {
+            "anyOf": [
+              {
+                "type": "string",
+                "maxLength": 32,
+                "minLength": 1
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Scope"
+          },
           "currency": {
             "type": "string",
             "maxLength": 8,
@@ -3754,6 +3789,10 @@
             "type": "string",
             "title": "Kind"
           },
+          "scope": {
+            "type": "string",
+            "title": "Scope"
+          },
           "active": {
             "type": "boolean",
             "title": "Active"
@@ -3785,6 +3824,7 @@
           "id",
           "name",
           "kind",
+          "scope",
           "active",
           "currency",
           "created_at",
@@ -3861,6 +3901,10 @@
             "type": "string",
             "title": "Kind"
           },
+          "scope": {
+            "type": "string",
+            "title": "Scope"
+          },
           "active": {
             "type": "boolean",
             "title": "Active"
@@ -3885,6 +3929,7 @@
           "id",
           "name",
           "kind",
+          "scope",
           "active",
           "currency",
           "created_at",

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