"""Instance management pydantic request / response models.

Maps to the OpenAPI schemas (registry_openapi.yaml §/api/instances):
- ``RegisterInstanceRequest``: gateway registers an instance after
  launching it (三方 / 九问 unified flow).
- ``UpdateInstanceRequest``: gateway updates node/address/instance_id on
  migration, or sets ``status`` (运行 / 停止 / 异常) from the 元戎 List.
- ``InstanceEntry``: full entry with ``status`` (运行 / 停止 / 异常).
- ``InstanceDeleteResponse``: deregister result with ``deleted`` flag.

``status`` is persisted inside the ``data`` JSON (default 运行 on
register, written by the gateway via PATCH); when the node heartbeat
marks a node UNHEALTHY the derived status shown is 异常 (see
InstanceService._derive_status). ``instance_id`` is the 元戎 instance
ID backfilled by the gateway — optional (empty when not launched via
元戎) and never a primary key.
"""

from __future__ import annotations

from typing import Any, Dict, List, Optional

from pydantic import BaseModel, Field


class RegisterInstanceRequest(BaseModel):
    """``POST /api/instances`` request body(模式 A:仅登记,向前兼容).

    All fields except ``instance_id`` / ``image_name`` are provided by the
    gateway; ``service_id`` is derived from (user, framework) by the gateway
    for idempotent upsert. ``instance_id`` is the 元戎 instance ID —
    optional (empty when the instance was not launched via 元戎).
    ``image_name`` is the image primary-key reference used by the image
    in-use check (optional; legacy rows fall back to framework matching).
    """

    service_id: str = Field(..., description="user+framework 派生(幂等)")
    kind: str = Field(..., description="实例种类:三方 / 九问")
    framework: str = Field(..., description="框架名")
    framework_version: str = Field(..., description="框架版本")
    image_name: Optional[str] = Field(
        None, description="镜像主键 name(可选;空则镜像在用校验退回 framework 匹配)"
    )
    node: str = Field("", description="元戎落点 nodeIP(可空,后续 PATCH 补写)")
    instance_id: Optional[str] = Field(
        None, description="元戎实例 ID(gateway 拉起后回填;非元戎拉起可空、不做主键)"
    )
    address: str = Field("", description="实例访问地址 (IP:port)(可空,后续 PATCH 补写)")
    user: str = Field(..., description="创建 / 所属用户")


class CreateInstanceRuntimeRequest(BaseModel):
    """``POST /api/instances`` request body(模式 B:registry 调元戎创建).

    = 元戎 create payload + version。``service_id = name``(首个 ``+`` 拆
    user/framework)、``kind`` 由 framework 判、``node``/``address``/
    ``instance_id`` 元戎回填。**有无 runtime_spec 是与模式 A 的判据**。
    实例行冗余存 ``image_name``(镜像主键引用),供镜像注销在用校验按主键关联。
    """

    name: str = Field(..., description="实例主键 = user+framework(= 元戎 name)")
    workspace: str = Field(..., description="绝对路径")
    version: str = Field(..., description="镜像版本(注册中心专属,注销校验用)")
    image_name: Optional[str] = Field(
        None, description="镜像主键 name(在用校验按主键关联的引用键)"
    )
    namespace: Optional[str] = Field(
        None, description="元戎命名空间(可选;registry 配置优先,入参被忽略)"
    )
    runtime_spec: Dict[str, Any] = Field(
        ..., description="元戎沙箱运行规格(runtime / rootfs.imageurl / cpu / memory…),原样转发"
    )
    env_vars: Optional[Dict[str, str]] = Field(None, description="环境变量")
    mounts: Optional[List[Dict[str, Any]]] = Field(None, description="挂载列表")


class UpdateInstanceRequest(BaseModel):
    """``PATCH /api/instances/{service_id}`` request body.

    At least one of node/address/instance_id/status must be provided.
    ``service_id`` is immutable (passed via the path).
    """

    node: Optional[str] = Field(None, description="新落点 nodeIP")
    address: Optional[str] = Field(None, description="新访问地址")
    instance_id: Optional[str] = Field(
        None, description="元戎实例 ID(元戎迁移后变化时回填)"
    )
    status: Optional[str] = Field(
        None, description="存活状态(gateway 据元戎 List 写入):运行 / 停止 / 异常"
    )


class InstanceEntry(BaseModel):
    """实例注册条目(含落库 status 与元戎 instance_id)。"""

    service_id: str
    kind: str
    framework: str
    framework_version: str
    node: str
    address: str
    instance_id: str = ""
    image_name: str = ""
    user: str
    created_at: str
    last_active_at: str
    status: str  # 运行 | 停止 | 异常


class InstanceDeleteResponse(BaseModel):
    """注销实例回执。``deleted=False`` 表示条目本就不存在(幂等)。

    ``runtime_deleted`` 仅 ``with_runtime=true``(模式 B)时返回:
    元戎实例已删(含元戎本就不存在的幂等情形)为 True;条目无
    instance_id 仅删条目为 False;模式 A 缺省。
    """

    service_id: str
    deleted: bool
    runtime_deleted: Optional[bool] = None


class BatchDeleteResultItem(BaseModel):
    """ALL / 批量删除的单条结果(部分失败不回滚)。"""

    service_id: str
    deleted: bool
    error: Optional[str] = Field(
        None, description='该条失败原因(如 "in_progress" / 元戎失败信息);成功时缺省'
    )


class BatchDeleteResponse(BaseModel):
    """DELETE /api/instances/ALL 的批量回执。"""

    total: int
    deleted: int
    results: List[BatchDeleteResultItem]