"""Gateway 进程的本机绑定配置。

目前唯一字段是 ``port``——Gateway FastAPI 的监听端口。圆桌三路由
(intent / recommend / multi_agent) 内部用 loopback 调本机的其它 endpoint
(``/api/threads``、``/api/agents`` 等),需要知道这个端口才能拼出 base URL。

为什么放在配置里而不是写死
--------------------------
- 部署方常常会改 Gateway 监听端口(端口被占用、合规要求、容器化端口映射),
  写死代码意味着每次改端口都得改源码 + 重新构建/分发,**改 config 不需要重启二进制**
- ``DEER_FLOW_GATEWAY_PORT`` 环境变量仍然是更高优先级的紧急覆盖通道,适合
  临时调试或者 docker-compose / k8s 注入

修改方式(部署侧)
------------------
在 ``config.yaml`` 顶层加:

.. code-block:: yaml

    gateway:
      port: 9999        # 默认 8001;部署机改了 gateway 端口时改这里

只想临时改一次(不动 yaml)→ 设环境变量:

.. code-block:: bash

    export DEER_FLOW_GATEWAY_PORT=9999
"""

from __future__ import annotations

from pydantic import BaseModel, Field


class GatewayConfig(BaseModel):
    """Gateway 本机 loopback 端口配置。"""

    port: int = Field(
        default=8001,
        ge=1,
        le=65535,
        description=(
            "Gateway FastAPI 监听端口。圆桌内部 loopback 调用会拼到 "
            "``http://127.0.0.1:<port>``。默认 8001(与 Makefile/scripts/start-all.sh 对齐)。"
        ),
    )