feat(api): add /v1/maintenance policies and run endpoints

OpenAPI, httpapi CRUD/run/dry-run, job maintenance_policy_run и audit с policy_id.

Co-authored-by: Cursor <[email protected]>

docs/openapi.yaml

@@ -51,6 +51,8 @@ tags:
     description: Сессия текущего API-ключа (tenant и роль).
   - name: Monitoring
     description: Наблюдаемость PostgreSQL и корреляция (instance-level, viewer+). Maintenance — operator.
+  - name: Maintenance
+    description: Политики обслуживания PostgreSQL (instance-scoped). CRUD и запуск — operator.
 
 security:
   - bearerAuth: []
@@ -966,10 +968,98 @@ components:
           default: false
         policy:
           type: string
-          description: job_audit_retention | asn_cache_retention
+          description: Deprecated; use maintenance policies API.
         limit:
           type: integer
 
+    MaintenancePolicy:
+      type: object
+      required: [name, table_name, schedule, vacuum_strategy]
+      properties:
+        id:
+          $ref: "#/components/schemas/ResourceId"
+        name:
+          type: string
+        table_name:
+          type: string
+        condition:
+          type: string
+          default: "true"
+        retention_period_sec:
+          type: integer
+          minimum: 1
+        max_rows:
+          type: integer
+          minimum: 1
+          maximum: 100000
+        vacuum_strategy:
+          type: string
+          enum: [none, vacuum, analyze, vacuum_analyze, reindex]
+        schedule:
+          type: string
+          description: Cron expression (5-field, UTC).
+        enabled:
+          type: boolean
+          default: true
+        dry_run_enabled:
+          type: boolean
+          default: false
+        last_run_at:
+          type: string
+          format: date-time
+        last_status:
+          type: string
+        last_error:
+          type: string
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+
+    MaintenancePolicyPatch:
+      type: object
+      properties:
+        name:
+          type: string
+        table_name:
+          type: string
+        condition:
+          type: string
+        retention_period_sec:
+          type: integer
+        max_rows:
+          type: integer
+        vacuum_strategy:
+          type: string
+          enum: [none, vacuum, analyze, vacuum_analyze, reindex]
+        schedule:
+          type: string
+        enabled:
+          type: boolean
+        dry_run_enabled:
+          type: boolean
+
+    MaintenanceRunBody:
+      type: object
+      required: [policy_id]
+      properties:
+        policy_id:
+          $ref: "#/components/schemas/ResourceId"
+
+    MaintenancePolicyList:
+      type: object
+      properties:
+        items:
+          type: array
+          items:
+            $ref: "#/components/schemas/MaintenancePolicy"
+        next_cursor:
+          type: string
+        has_more:
+          type: boolean
+
     BirdLocalStatus:
       type: object
       description: Статус локального BIRD на хосте API (GET /v1/bird/status).
@@ -3467,6 +3557,210 @@ paths:
         default:
           $ref: "#/components/responses/DefaultProblem"
 
+  /v1/maintenance/policies:
+    get:
+      tags: [Maintenance]
+      summary: List maintenance policies
+      operationId: listMaintenancePolicies
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+        - $ref: "#/components/parameters/Cursor"
+        - $ref: "#/components/parameters/Limit"
+      responses:
+        "200":
+          description: Успешно.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MaintenancePolicyList"
+        default:
+          $ref: "#/components/responses/DefaultProblem"
+    post:
+      tags: [Maintenance]
+      summary: Create maintenance policy
+      operationId: createMaintenancePolicy
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/MaintenancePolicy"
+      responses:
+        "201":
+          description: Создано.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MaintenancePolicy"
+        default:
+          $ref: "#/components/responses/DefaultProblem"
+
+  /v1/maintenance/policies/{id}:
+    get:
+      tags: [Maintenance]
+      summary: Get maintenance policy
+      operationId: getMaintenancePolicy
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+        - name: id
+          in: path
+          required: true
+          schema:
+            $ref: "#/components/schemas/ResourceId"
+      responses:
+        "200":
+          description: Успешно.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MaintenancePolicy"
+        default:
+          $ref: "#/components/responses/DefaultProblem"
+    patch:
+      tags: [Maintenance]
+      summary: Update maintenance policy
+      operationId: patchMaintenancePolicy
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+        - name: id
+          in: path
+          required: true
+          schema:
+            $ref: "#/components/schemas/ResourceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/MaintenancePolicyPatch"
+      responses:
+        "200":
+          description: Успешно.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MaintenancePolicy"
+        default:
+          $ref: "#/components/responses/DefaultProblem"
+    delete:
+      tags: [Maintenance]
+      summary: Delete maintenance policy
+      operationId: deleteMaintenancePolicy
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+        - name: id
+          in: path
+          required: true
+          schema:
+            $ref: "#/components/schemas/ResourceId"
+      responses:
+        "204":
+          description: Удалено.
+        default:
+          $ref: "#/components/responses/DefaultProblem"
+
+  /v1/maintenance/policies/{id}/hints:
+    get:
+      tags: [Maintenance]
+      summary: PostgreSQL hints for policy table
+      operationId: getMaintenancePolicyHints
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+        - name: id
+          in: path
+          required: true
+          schema:
+            $ref: "#/components/schemas/ResourceId"
+      responses:
+        "200":
+          description: Успешно.
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: true
+        default:
+          $ref: "#/components/responses/DefaultProblem"
+
+  /v1/maintenance/config-audit:
+    get:
+      tags: [Maintenance]
+      summary: Maintenance policy configuration audit log
+      operationId: listMaintenanceConfigAudit
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+        - $ref: "#/components/parameters/Cursor"
+        - $ref: "#/components/parameters/Limit"
+      responses:
+        "200":
+          description: Успешно.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  items:
+                    type: array
+                    items:
+                      type: object
+                      additionalProperties: true
+                  next_cursor:
+                    type: string
+                  has_more:
+                    type: boolean
+        default:
+          $ref: "#/components/responses/DefaultProblem"
+
+  /v1/maintenance/run:
+    post:
+      tags: [Maintenance]
+      summary: Run maintenance policy (async job)
+      operationId: postMaintenanceRun
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+        - $ref: "#/components/parameters/IdempotencyKey"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/MaintenanceRunBody"
+      responses:
+        "202":
+          description: Задача поставлена.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AsyncJobAccepted"
+        default:
+          $ref: "#/components/responses/DefaultProblem"
+
+  /v1/maintenance/dry-run:
+    post:
+      tags: [Maintenance]
+      summary: Dry-run maintenance policy (async job)
+      operationId: postMaintenanceDryRun
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+        - $ref: "#/components/parameters/IdempotencyKey"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/MaintenanceRunBody"
+      responses:
+        "202":
+          description: Задача поставлена.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AsyncJobAccepted"
+        default:
+          $ref: "#/components/responses/DefaultProblem"
+
   /v1/settings:
     get:
       tags: [Settings]