"""长任务轮询响应 schema（C3 / ARCH §7.4）。

snake_case；前端经 OpenAPI→TS 客户端消费——改字段须 `pnpm gen:api` 重生成。
此前 `GET /jobs/{id}` 返回裸 `dict`，TS 端拿到弱类型；改为具体 Pydantic 模型提升类型。
"""

from __future__ import annotations

import uuid
from typing import Any

from pydantic import BaseModel


class JobResponse(BaseModel):
    """长任务状态（`GET /jobs/{id}`）：状态 + 进度 + 结果/错误。

    `result` 是任务成功后的非密摘要（如 `{"connected": true, ...}`）；`error` 是失败后的
    面向用户文案（已脱敏，绝不含 `str(exc)`，见 `services/job_runner._classify_job_error`）。
    """

    id: uuid.UUID
    kind: str
    status: str
    progress: int = 0
    result: dict[str, Any] | None = None
    error: str | None = None