feat(workbench): persist operational workflows and events

2026-09-24 04:19:02 +08:00
parent baff7dfe9e
commit 9335bdc1ea
66 changed files with 16580 additions and 238 deletions
@@ -0,0 +1,218 @@
+"""Typed external action adapters. Credentials are request-scoped, never persisted."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Literal, Protocol
+from uuid import UUID
+
+import httpx
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from app.auth.project_dependencies import ProjectContext
+from app.domain.schemas.operational_task import (
+    ActionReceipt, CreateWorkOrderPayload, HumanApprovalAction,
+    IssueCommandPayload, OperationalTaskDetail,
+)
+
+
+@dataclass(frozen=True)
+class ActionDispatchOutcome:
+    status: Literal["submitted", "succeeded", "failed", "unsupported", "unknown"]
+    detail: str
+    receipt: ActionReceipt | None = None
+
+
+class OperationalActionDispatcher(Protocol):
+    async def dispatch(
+        self, *, context: ProjectContext, task: OperationalTaskDetail,
+        action: HumanApprovalAction, credential: str | None,
+    ) -> ActionDispatchOutcome: ...
+
+    async def reconcile(
+        self, *, context: ProjectContext, task: OperationalTaskDetail,
+        action: HumanApprovalAction, credential: str | None,
+    ) -> ActionDispatchOutcome: ...
+
+
+class OperationalActionSettings(BaseSettings):
+    peripheral_url: str = ""
+    command_gateway_url: str = ""
+    timeout_seconds: float = Field(default=10, ge=1, le=60)
+    model_config = SettingsConfigDict(
+        env_prefix="OPERATIONAL_ACTION_", extra="ignore",
+        env_file=Path(__file__).resolve().parents[3] / ".env",
+    )
+
+
+class SampleWorkOrderReceipt(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+    work_order_id: UUID
+    project_id: UUID
+    created_at: datetime
+    origin: Literal["synthetic"]
+    status: Literal[
+        "draft", "open", "in_progress", "awaiting_reply", "completed", "cancelled"
+    ]
+
+
+class CommandGatewayReceipt(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    request_id: UUID
+    project_id: UUID
+    receipt_id: str = Field(min_length=1)
+    status: Literal["accepted", "running", "completed", "failed"]
+    submitted_at: datetime
+    completed_at: datetime | None = None
+    detail: str = Field(min_length=1)
+
+
+class HttpOperationalActionDispatcher:
+    def __init__(
+        self, settings: OperationalActionSettings | None = None,
+        *, transport: httpx.AsyncBaseTransport | None = None,
+    ):
+        self.settings = settings or OperationalActionSettings()
+        self.transport = transport
+
+    async def dispatch(
+        self, *, context: ProjectContext, task: OperationalTaskDetail,
+        action: HumanApprovalAction, credential: str | None,
+    ) -> ActionDispatchOutcome:
+        base = (self.settings.peripheral_url if action.kind == "create_work_order"
+                else self.settings.command_gateway_url)
+        if not base:
+            return ActionDispatchOutcome("unsupported", "尚未配置该动作的外部执行适配器")
+        if not credential or not credential.lower().startswith("bearer "):
+            return ActionDispatchOutcome("failed", "缺少当前用户的产品身份，未提交外部动作")
+        if action.task_id != task.task_id or task.project_id != context.project_id:
+            return ActionDispatchOutcome("failed", "动作与当前项目任务不匹配，未提交")
+        if action.approval_status != "approved":
+            return ActionDispatchOutcome("failed", "动作尚未通过人工确认，未提交")
+        request_id = action.execution_request_id
+        if request_id is None:
+            return ActionDispatchOutcome("failed", "缺少持久化执行编号，未提交")
+        headers = {"Authorization": credential, "X-Project-Id": str(context.project_id)}
+        try:
+            if action.kind == "create_work_order":
+                payload = CreateWorkOrderPayload.model_validate(action.payload)
+                body = {
+                    "request_id": str(request_id), "title": payload.title,
+                    "summary": payload.description, "status": "open",
+                    "priority": payload.priority, "assignee": payload.assignee,
+                    "scheduled_at": payload.scheduled_at.isoformat() if payload.scheduled_at else None,
+                    "location": payload.location,
+                    # An approved action creates a child execution order, not a
+                    # new inbound complaint/burst event for the sync loop.
+                    "work_order_type": "general",
+                }
+                path = "/api/sample/v1/work-orders"
+                recovery_path = f"/api/sample/v1/requests/{request_id}"
+            else:
+                payload = IssueCommandPayload.model_validate(action.payload)
+                if payload.expires_at <= datetime.now(timezone.utc):
+                    return ActionDispatchOutcome("failed", "命令确认窗口已过期，未提交")
+                body = {
+                    "request_id": str(request_id), "project_id": str(context.project_id),
+                    "task_id": str(task.task_id), "action_id": str(action.action_id),
+                    "action_version": action.version,
+                    "approved_by": action.decided_by,
+                    "approved_at": action.decided_at.isoformat() if action.decided_at else None,
+                    "command": payload.model_dump(mode="json"),
+                }
+                path = "/api/v1/commands"
+                recovery_path = f"/api/v1/commands/requests/{request_id}"
+        except (ValidationError, TypeError, ValueError):
+            return ActionDispatchOutcome("failed", "动作参数不符合执行契约，未提交")
+
+        async with httpx.AsyncClient(
+            base_url=base.rstrip("/"), headers=headers, timeout=self.settings.timeout_seconds,
+            follow_redirects=False, trust_env=False, transport=self.transport,
+        ) as client:
+            try:
+                response = await client.post(path, json=body)
+                if response.status_code in {400, 401, 403, 404, 409, 422}:
+                    # Sample responses explicitly state whether any write occurred.
+                    # An untyped rejection is not proof that no effect took place.
+                    error = response.json()
+                    if isinstance(error, dict) and error.get("effect") == "none":
+                        return ActionDispatchOutcome("failed", "外部系统拒绝了动作，未生效")
+                response.raise_for_status()
+                return self._receipt(action.kind, response.json(), request_id, context.project_id)
+            except (httpx.HTTPError, ValueError, KeyError, ValidationError):
+                # A lost response can follow a successful write. Recover using the
+                # same idempotency key, never manufacture success or blindly retry.
+                try:
+                    recovered = await client.get(recovery_path)
+                    recovered.raise_for_status()
+                    value = recovered.json()
+                    if action.kind == "create_work_order":
+                        if not isinstance(value, dict) or value.get("request_id") != str(request_id):
+                            raise ValueError("request receipt mismatch")
+                        value = value["result"]
+                    return self._receipt(action.kind, value, request_id, context.project_id)
+                except (httpx.HTTPError, ValueError, KeyError, ValidationError):
+                    return ActionDispatchOutcome("unknown", "外部执行结果待核实，请通过回执核对，勿重复下发")
+
+    async def reconcile(
+        self, *, context: ProjectContext, task: OperationalTaskDetail,
+        action: HumanApprovalAction, credential: str | None,
+    ) -> ActionDispatchOutcome:
+        request_id = action.execution_request_id
+        if not credential or request_id is None or action.task_id != task.task_id or task.project_id != context.project_id:
+            return ActionDispatchOutcome("unknown", "无法核实当前动作的身份或执行编号")
+        base = self.settings.peripheral_url if action.kind == "create_work_order" else self.settings.command_gateway_url
+        if not base:
+            return ActionDispatchOutcome("unknown", "回执查询服务尚未配置")
+        path = (f"/api/sample/v1/requests/{request_id}" if action.kind == "create_work_order"
+                else f"/api/v1/commands/requests/{request_id}")
+        try:
+            async with httpx.AsyncClient(
+                base_url=base.rstrip("/"), timeout=self.settings.timeout_seconds,
+                follow_redirects=False, trust_env=False, transport=self.transport,
+            ) as client:
+                response = await client.get(path, headers={
+                    "Authorization": credential, "X-Project-Id": str(context.project_id),
+                })
+                response.raise_for_status()
+                value = response.json()
+                if action.kind == "create_work_order":
+                    if not isinstance(value, dict) or value.get("request_id") != str(request_id):
+                        raise ValueError("request receipt mismatch")
+                    value = value["result"]
+                return self._receipt(action.kind, value, request_id, context.project_id)
+        except (httpx.HTTPError, ValueError, KeyError, ValidationError):
+            return ActionDispatchOutcome("unknown", "尚未取得可核实的执行回执")
+
+    @staticmethod
+    def _receipt(kind: str, value: object, request_id: UUID, project_id: UUID) -> ActionDispatchOutcome:
+        if kind == "create_work_order":
+            order = SampleWorkOrderReceipt.model_validate(value)
+            if order.project_id != project_id or order.created_at.tzinfo is None:
+                raise ValueError("invalid external project or timestamp")
+            receipt = ActionReceipt(
+                adapter="peripheral_sample", receipt_id=str(order.work_order_id),
+                submitted_at=order.created_at, completed_at=order.created_at,
+                external_status=order.status, detail="合成外围工单已创建，现场工作进度由外围系统继续同步",
+            )
+            return ActionDispatchOutcome("succeeded", receipt.detail, receipt)
+        result = CommandGatewayReceipt.model_validate(value)
+        if result.project_id != project_id or result.request_id != request_id:
+            raise ValueError("command receipt does not match submission")
+        if result.submitted_at.tzinfo is None or (result.completed_at and result.completed_at.tzinfo is None):
+            raise ValueError("command receipt timestamps must include timezone")
+        if result.status == "completed" and result.completed_at is None:
+            raise ValueError("command has no completion receipt")
+        receipt = ActionReceipt(
+            adapter="command_gateway", receipt_id=result.receipt_id,
+            submitted_at=result.submitted_at, completed_at=result.completed_at,
+            external_status=result.status, detail=result.detail,
+        )
+        status = "succeeded" if result.status == "completed" else "failed" if result.status == "failed" else "submitted"
+        return ActionDispatchOutcome(status, result.detail, receipt)
+
+
+def get_operational_action_dispatcher() -> OperationalActionDispatcher:
+    return HttpOperationalActionDispatcher()
@@ -0,0 +1,177 @@
+"""Read-only source adapters with bounded queries and explicit provenance."""
+from __future__ import annotations
+
+import hashlib
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+import httpx
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from app.auth.permissions import SCADA_VIEW, SIMULATION_VIEW, permissions_for_context
+from app.auth.project_dependencies import ProjectContext
+from app.domain.schemas.operational_data import TaskDataQuery, TaskDataSnapshot
+
+
+class TaskDataSettings(BaseSettings):
+    server_url: str = "http://127.0.0.1:8000"
+    peripheral_url: str = ""
+    timeout_seconds: float = Field(default=15, ge=1, le=60)
+    model_config = SettingsConfigDict(
+        env_prefix="OPERATIONAL_DATA_", extra="ignore",
+        env_file=Path(__file__).resolve().parents[3] / ".env",
+    )
+
+
+class TaskDataError(Exception):
+    def __init__(self, status: int, detail: str):
+        super().__init__(detail)
+        self.status = status
+        self.detail = detail
+
+
+def _matches_project(value: object, project_id: str) -> bool:
+    if isinstance(value, list):
+        return all(_matches_project(item, project_id) for item in value)
+    if isinstance(value, dict):
+        if "project_id" in value and value["project_id"] != project_id:
+            return False
+        return all(_matches_project(item, project_id) for item in value.values())
+    return True
+
+
+def _select_demo_observations(
+    payload: object, query: TaskDataQuery, project_id: str,
+) -> dict[str, object]:
+    """Project a bounded DEMO-* observation query from the stored demo dataset."""
+    if not isinstance(payload, dict) or not _matches_project(payload, project_id):
+        raise TaskDataError(502, "数据源返回了其他项目的数据")
+    points = payload.get("points")
+    observations = payload.get("observations")
+    if not isinstance(points, list) or not isinstance(observations, list):
+        raise TaskDataError(502, "外围合成样本格式无效")
+    if not any(isinstance(point, dict) and point.get("point_id") == query.point_id for point in points):
+        raise TaskDataError(404, "合成样本测点不存在")
+    assert query.start is not None and query.end is not None
+    items: list[object] = []
+    try:
+        for item in observations:
+            if not isinstance(item, dict) or item.get("point_id") != query.point_id:
+                continue
+            observed_at = datetime.fromisoformat(str(item.get("observed_at")))
+            if query.start <= observed_at < query.end:
+                items.append(item)
+    except (TypeError, ValueError) as exc:
+        raise TaskDataError(502, "外围合成样本格式无效") from exc
+    return {
+        "origin": "synthetic",
+        "source_id": payload.get("source_id"),
+        "source_revision": payload.get("source_revision"),
+        "point_id": query.point_id,
+        "window": {
+            "start": query.start.isoformat(),
+            "end": query.end.isoformat(),
+        },
+        "items": items,
+        "truncated": False,
+    }
+
+
+async def read_task_data(
+    *, context: ProjectContext, query: TaskDataQuery, credential: str | None,
+    settings: TaskDataSettings | None = None,
+    transport: httpx.AsyncBaseTransport | None = None,
+) -> TaskDataSnapshot:
+    config = settings or TaskDataSettings()
+    permission = SCADA_VIEW if query.source.startswith("scada_") else SIMULATION_VIEW
+    if permission not in permissions_for_context(context):
+        raise TaskDataError(403, "当前身份没有该数据源的读取权限")
+    if not credential or not credential.lower().startswith("bearer "):
+        raise TaskDataError(401, "数据查询需要当前产品身份")
+    peripheral = query.source.startswith("peripheral_")
+    base = config.peripheral_url if peripheral else config.server_url
+    if not base:
+        raise TaskDataError(503, "调查数据源尚未配置")
+    paths = {
+        "workbench_runtime": "/api/v1/workbench/runtime",
+        "scada_devices": "/api/v1/scada-devices",
+        "scada_readings": "/api/v1/timeseries/scada-readings",
+        "peripheral_points": "/api/sample/v1/monitoring/points",
+        "peripheral_work_orders": "/api/sample/v1/work-orders",
+        "peripheral_observations": "/api/sample/v1/monitoring/observations",
+        "peripheral_test_data": "/api/sample/v1/test-data",
+    }
+    demo_observations = (
+        query.source == "peripheral_observations"
+        and query.point_id is not None
+        and query.point_id.startswith("DEMO-")
+    )
+    path = "/api/sample/v1/demo-data" if demo_observations else paths[query.source]
+    params: dict[str, str | int] = {"limit": 100}
+    if query.source == "scada_readings":
+        params.update(device_ids=",".join(query.device_ids), start_time=query.start.isoformat(), end_time=query.end.isoformat())
+    elif query.source == "peripheral_observations" and not demo_observations:
+        params = {"point_id": query.point_id, "start": query.start.isoformat(), "end": query.end.isoformat()}
+    elif demo_observations:
+        params = {}
+    try:
+        async with httpx.AsyncClient(
+            base_url=base.rstrip("/"), timeout=config.timeout_seconds, follow_redirects=False,
+            trust_env=False, transport=transport,
+        ) as client:
+            async with client.stream("GET", path, params=params, headers={
+                "Authorization": credential, "X-Project-Id": str(context.project_id),
+            }) as response:
+                if response.status_code in {401, 403}:
+                    raise TaskDataError(response.status_code, "数据源拒绝当前身份或项目权限")
+                response.raise_for_status()
+                body = bytearray()
+                async for chunk in response.aiter_bytes():
+                    body.extend(chunk)
+                    if len(body) > 2_000_000:
+                        raise TaskDataError(422, "查询结果过大，请缩短时间范围或减少设备数量")
+        data = json.loads(body)
+    except (httpx.HTTPError, ValueError) as exc:
+        raise TaskDataError(502, "调查数据查询失败，不能据此形成已核实结论") from exc
+    if demo_observations:
+        data = _select_demo_observations(data, query, str(context.project_id))
+    elif not _matches_project(data, str(context.project_id)):
+        raise TaskDataError(502, "数据源返回了其他项目的数据")
+    origin = "synthetic" if peripheral else "system_data"
+    historical_replay = False
+    if query.source in {"peripheral_points", "peripheral_observations"}:
+        source_origin = data.get("origin") if isinstance(data, dict) else None
+        if source_origin not in {"historical_replay", "synthetic"}:
+            raise TaskDataError(502, "监测数据缺少明确来源，不能作为已核实证据")
+        historical_replay = source_origin == "historical_replay"
+        origin = "system_data" if historical_replay else "synthetic"
+    truncated = isinstance(data, dict) and bool(data.get("truncated") or data.get("next_cursor") or data.get("next_offset"))
+    if isinstance(data, list) and len(data) > 1000:
+        data, truncated = data[:1000], True
+    if isinstance(data, dict) and isinstance(data.get("items"), list):
+        if len(data["items"]) > 1000:
+            data = {**data, "items": data["items"][:1000]}
+            truncated = True
+        if isinstance(data.get("total"), int) and data["total"] > len(data["items"]):
+            truncated = True
+    # The digest identifies the returned snapshot, not merely a mutable URL.
+    digest = hashlib.sha256(json.dumps(data, ensure_ascii=False, sort_keys=True).encode()).hexdigest()
+    if demo_observations:
+        assert query.start is not None and query.end is not None
+        source_ref = (
+            f"peripheral_demo_data:{query.point_id}:"
+            f"{query.start.isoformat()}:{query.end.isoformat()}:sha256:{digest}"
+        )
+    elif historical_replay:
+        # Use a distinct identity: old snapshots may have incorrectly labeled
+        # this same historical response synthetic. Immutable evidence stays intact.
+        source_ref = f"peripheral_historical_replay:{query.source}:sha256:{digest}"
+    else:
+        source_ref = f"{query.source}:sha256:{digest}"
+    return TaskDataSnapshot(
+        source=query.source, source_ref=source_ref,
+        queried_at=datetime.now(timezone.utc), origin=origin,
+        data=data, truncated=truncated,
+    )