crypto_okx/lib/env/env_ui_manifest.py

"""env 配置页 UI 白名单:中文标签,按交易所过滤."""
from __future__ import annotations

import os
from typing import Any, Optional

from lib.env.env_file_lib import env_get_all, read_env_lines
from lib.env.env_schema import (
    _field_type,
    _hot_reload,
    _is_sensitive,
    _mask_value,
    _restart_required,
    normalize_select_value,
    parse_env_example_schema,
    select_options_for,
)

# 各所「交易所与实盘」字段(顺序即页面顺序)
# 合约计仓/杠杆/自动单等已从 env UI 移除;永续划转等见系统设置开关(默认关)
_EXCHANGE_LIVE_FIELDS: dict[str, list[tuple[str, str, str]]] = {
    "okx": [
        ("LIVE_TRADING_ENABLED", "开启实盘下单", "关闭时仅走本地流程,不向交易所发单(期权/对冲共用)"),
        ("OKX_API_KEY", "API Key", "账户 API(永续腿+期权共用)"),
        ("OKX_API_SECRET", "API Secret", "账户 API(永续腿+期权共用)"),
        ("OKX_API_PASSPHRASE", "API Passphrase", "OKX 必填"),
        ("OKX_ACCOUNT_LABEL", "账户备注", "企业微信推送中显示"),
        (
            "OKX_SHOW_PERP_FUNDS",
            "显示永续资金",
            "默认关闭;开启后顶栏显示 USDT 资金/交易账户。币本位期权仍会显示交易账户以便买币",
        ),
    ],
    "binance": [
        ("LIVE_TRADING_ENABLED", "开启实盘下单", "关闭时仅走本地流程,不向交易所发单"),
        ("BINANCE_API_KEY", "API Key", "永续子账户"),
        ("BINANCE_API_SECRET", "API Secret", "永续子账户"),
        ("BINANCE_MARGIN_MODE", "保证金模式", ""),
        ("BINANCE_POSITION_MODE", "持仓模式", ""),
        ("BINANCE_ACCOUNT_LABEL", "账户备注", "企业微信推送中显示"),
    ],
    "gate": [
        ("LIVE_TRADING_ENABLED", "开启实盘下单", "关闭时仅走本地流程,不向交易所发单"),
        ("GATE_API_KEY", "API Key", "永续子账户"),
        ("GATE_API_SECRET", "API Secret", "永续子账户"),
        ("GATE_TD_MODE", "保证金模式", ""),
        ("GATE_POS_MODE", "持仓模式", ""),
        ("GATE_ACCOUNT_LABEL", "账户备注", "企业微信推送中显示"),
    ],
}

# 仅保留与期权/对冲产品相关的共享区块(永续执行/风控/冷静期/划转/当日资金已从 UI 移除)
_SHARED_SECTIONS: list[dict[str, Any]] = [
    {
        "title": "企业微信",
        "fields": [
            ("WECHAT_WEBHOOK", "机器人 Webhook", "行情与风控推送地址"),
            ("WECHAT_TIMEOUT_SECONDS", "推送超时(秒)", "默认 10"),
        ],
    },
]

_MODE_SECTION: dict[str, Any] = {
    "title": "期权/对冲模式",
    "exchanges": frozenset({"okx"}),
    "fields": [
        (
            "OKX_TRADE_MODE",
            "交易模式",
            "二选一:单独期权 / 期期对冲。选单独期权时隐藏对冲导航与对冲配置;选期期对冲时不可单独开期权。永期对冲(含合约腿)已从配置页移除",
        ),
    ],
}

_OPTIONS_SECTION: dict[str, Any] = {
    "title": "期权账户",
    "exchanges": frozenset({"okx"}),
    "fields": [
        ("OKX_OPTIONS_ENABLED", "启用期权模块", "与永续共用上方 OKX_API_*;不再单独配置期权密钥"),
        ("OKX_OPTIONS_ACCOUNT_LABEL", "期权账户备注", ""),
        (
            "OKX_OPTIONS_MARGIN_MODE",
            "单笔期权本位",
            "usdc=USDⓈ权利金;coin=币本位+USDT买币桥(默认)。有持仓/半成品桥时勿切换;改后需重启",
        ),
        (
            "OKX_OPTIONS_TRADE_BUDGET_USDC",
            "单笔预算(USDC)",
            "仅 USDC 模式且全仓复利关闭时显示/生效;用于「按可用余额打满」及张数/币数上限",
        ),
        ("OKX_OPTIONS_BUDGET_BUFFER", "预算缓冲比例", "如 0.95;USDC 打满/全仓复利与币本位复利共用"),
        (
            "OKX_OPTIONS_COIN_COMPOUND",
            "币本位按交易户USDT复利",
            "默认 true;预算=交易账户USDT×缓冲;关闭则用下方固定 USDT 预算×缓冲",
        ),
        (
            "OKX_OPTIONS_COIN_BUDGET_USDT",
            "币本位固定预算(USDT)",
            "仅币本位且复利关闭时生效",
        ),
        (
            "OKX_OPTIONS_COIN_MAX_USDT_ENABLED",
            "币本位单笔上限开关",
            "默认 false=靠人工转走控规模;true 时预算不超过下方 N U",
        ),
        (
            "OKX_OPTIONS_COIN_MAX_USDT",
            "币本位单笔上限(USDT)",
            "仅上限开关开启时生效",
        ),
        (
            "OKX_OPTIONS_COIN_SPOT_BUY_BUFFER",
            "币本位现货买入缓冲",
            "相对权利金倍数,默认 1.10(=多买10%);也可写 0.10 表示+10%。按最大可开张数×卖一权利金×本缓冲买币,不全额兑换",
        ),
        (
            "OKX_OPTIONS_COMPOUND_FULL_ENABLED",
            "全仓复利开关",
            "默认 true;仅 USDC 模式。开启时隐藏单笔预算且不可用打满预算,下单以全仓复利为主;关闭则恢复单笔预算并隐藏全仓复利",
        ),
        (
            "OKX_OPTIONS_COMPOUND_FULL_CAP_ENABLED",
            "全仓复利上限开关",
            "仅全仓复利开启时有意义;默认 false=不设上限用期权户全部可用;true 时按下方上限封顶",
        ),
        (
            "OKX_OPTIONS_COMPOUND_FULL_CAP_USDC",
            "全仓复利上限(USDC)",
            "仅「全仓复利」且「上限开关」都开启时生效;例如 300",
        ),
        (
            "OKX_OPTIONS_MAX_ACTIVE_POSITIONS",
            "期权持仓上限(笔)",
            "仅「单独期权」模式生效;默认 0=不限制;按交易所期权合约笔数计数,同合约加仓不占新笔数",
        ),
        ("OKX_OPTIONS_DEFAULT_UNDERLY", "默认标的", "如 ETH"),
        (
            "OKX_OPTIONS_CHAIN_MAX_DTE_DAYS",
            "期权链展示天数",
            "默认 14;下拉到期日只出现该天数内的合约(含明天)",
        ),
        (
            "OKX_OPTIONS_MAX_DTE_DAYS",
            "开仓最大剩余天数",
            "默认 2;单独开期权时拒绝更远到期(与链展示天数独立)",
        ),
        (
            "OKX_OPTIONS_CHAIN_ASK_LIQ_FILTER_ENABLED",
            "链上仅显示有卖一",
            "默认 true;开启后隐藏无卖一深度或深度不足1张的合约(含标记价估算行)",
        ),
        (
            "OKX_OPTIONS_CLOSE_GATE_MODE",
            "目标平仓门控模式",
            "premium=可回收≥权利金×倍数(币本位默认×1.05);net_pnl=净盈亏折USDT≥阈值",
        ),
        (
            "OKX_OPTIONS_CLOSE_RECYCLE_MULT",
            "门控权利金倍数(USDC)",
            "仅 premium 模式;USDC 权利金仓默认 2",
        ),
        (
            "OKX_OPTIONS_CLOSE_RECYCLE_MULT_COIN",
            "门控权利金倍数(币本位)",
            "仅 premium 模式;ETH/BTC 权利金仓默认 1.05",
        ),
        (
            "OKX_OPTIONS_CLOSE_NET_PNL_MIN_USDT",
            "门控净盈亏下限(U)",
            "仅 net_pnl 模式;买一可回收−权利金折 USDT 后需≥此值;0 或 1 等",
        ),
        (
            "OKX_OPTIONS_CLOSE_HOLD_SECONDS",
            "门控持续秒数",
            "条件达标后需持续满足的秒数,默认 120",
        ),
    ],
}

# 对冲公共字段(不含已由 OKX_TRADE_MODE 取代的 ENABLED/SHOW/MUTUAL)
_HEDGE_COMMON_FIELDS: list[tuple[str, str, str]] = [
    ("HEDGE_PLAN_LIVE_ORDER", "允许对冲真实下单", "再与实盘 LIVE_TRADING_ENABLED 同开才可启动"),
    (
        "MAX_ACTIVE_HEDGE_PLANS",
        "对冲组数上限",
        "默认 1;同时进行中的对冲计划组数(opening/active/partial),可改",
    ),
    ("HEDGE_PLAN_MONITOR_POLL_SECONDS", "对冲监控轮询(秒)", "默认 15"),
    (
        "HEDGE_PLAN_BUDGET_BUFFER",
        "对冲预算缓冲比例",
        "默认 0.95;仅对冲计划;与期权页 OKX_OPTIONS_BUDGET_BUFFER 独立",
    ),
    (
        "HEDGE_PLAN_MANUAL_COMPLETE_ON_PARTIAL",
        "半腿失败改手动补开",
        "默认 true;开启时半腿失败不自动平,计划挂 partial,页面可补开;并强制关闭下方自动平",
    ),
    (
        "HEDGE_PLAN_PARTIAL_AUTO_CLOSE_OPTION",
        "半腿失败时自动平期权",
        "默认 true;若上方「半腿失败改手动补开」开启则本项强制无效",
    ),
]

_HEDGE_PO_FIELDS: list[tuple[str, str, str]] = [
    (
        "HEDGE_PLAN_OPTION_PRIMARY",
        "永期模式(以期权为主/保险)",
        "默认 true=以期权为主;false=保险模式;页面标题前显示标识,不可在页内切换",
    ),
    ("HEDGE_PLAN_OPEN_ORDER", "永期开仓顺序", "options_first 或 perp_first"),
    ("HEDGE_PLAN_ON_PERP_SL_CLOSE_OPTIONS", "永期止损后强制平期权", "保护机制,建议保持 true"),
    ("HEDGE_PLAN_ON_PERP_TP_CLOSE_OPTIONS", "永期止盈后强制平期权", "默认 false,保险腿不平"),
    (
        "HEDGE_PLAN_ITM_MAX_DIST_USD",
        "永期实值最大深度(U)",
        "默认空=沿用 OKX_OPTIONS_ITM_MAX_DIST_USD(常 30);0=不限制",
    ),
    (
        "HEDGE_PLAN_MIN_OPTION_HOURS",
        "对冲期权最低剩余小时",
        "默认 8;测算/启动时若传 hours_to_expiry 则校验",
    ),
    (
        "HEDGE_PLAN_MIN_OPTION_LEVERAGE",
        "对冲期权最低杠杆(S/ask)",
        "默认 0=不启用;>0 时拒绝杠杆过低的保险腿",
    ),
]

_HEDGE_OO_FIELDS: list[tuple[str, str, str]] = [
    ("HEDGE_PLAN_OO_CLOSE_WINNER_ONLY", "期期只平盈利腿", "达目标价只平盈利方"),
    (
        "HEDGE_PLAN_OO_CLOSE_MODE_ENABLED",
        "期期平仓模式(方案C)",
        "默认 true;开启后页面可选「到期平/全平」;关闭则固定到期平",
    ),
    (
        "HEDGE_PLAN_OO_BIAS_SPLIT_BY",
        "期期做多做空拆分口径",
        "默认预算金额;budget=按权利金预算分两腿;sheets=先算同张数再按比例拆",
    ),
    (
        "HEDGE_PLAN_OO_BIAS_RATIO",
        "期期做多做空主腿占比",
        "默认 0.7(即 7:3);做多主腿=Call,做空主腿=Put;须在 0~1 之间",
    ),
]

# 兼容旧测试/全量字段列表(写 env 时仍允许这些键,但 UI 按模式过滤)
_HEDGE_PLAN_SECTION: dict[str, Any] = {
    "title": "对冲计划",
    "exchanges": frozenset({"okx"}),
    "fields": [
        ("HEDGE_PLAN_ENABLED", "启用对冲计划", "已由「交易模式」取代,一般无需再改"),
        ("HEDGE_PLAN_SHOW_PERP_OPTIONS", "显示永期对冲", "已由「交易模式」取代"),
        ("HEDGE_PLAN_SHOW_OPTIONS_OPTIONS", "显示期期对冲", "已由「交易模式」取代"),
        ("HEDGE_PLAN_OPTIONS_MUTUAL_EXCLUSIVE", "对冲与期权互斥门控", "已由「交易模式」三选一取代"),
        *_HEDGE_COMMON_FIELDS,
        *_HEDGE_PO_FIELDS,
        *_HEDGE_OO_FIELDS,
    ],
}


# 与运行时 os.getenv 默认一致;.env 未写明时展示实际生效值(同风控说明页)
_RUNTIME_ENV_DEFAULTS: dict[str, str] = {
    "RISK_CONTROL_ENABLED": "true",
    "RISK_COOLING_HOURS_MANUAL": "4",
    "RISK_COOLING_HOURS_MANUAL_JOURNAL": "1",
    "RISK_MANUAL_CLOSE_DAILY_LIMIT": "2",
    "RISK_DAILY_LOSS_LIMIT": "2",
    "RISK_MOOD_ISSUES_DAILY_FREEZE": "true",
    "AUTO_TRANSFER_FROM": "funding",
    "AUTO_TRANSFER_TO": "swap",
    "TRANSFER_CCY": "USDT",
    "HEDGE_PLAN_SHOW_PERP_OPTIONS": "false",
    "HEDGE_PLAN_SHOW_OPTIONS_OPTIONS": "false",
    "OKX_SHOW_PERP_FUNDS": "false",
    "OKX_OPTIONS_CHAIN_ASK_LIQ_FILTER_ENABLED": "true",
    "OKX_OPTIONS_CHAIN_MAX_DTE_DAYS": "14",
    "OKX_OPTIONS_MAX_DTE_DAYS": "2",
    "OKX_OPTIONS_MAX_ACTIVE_POSITIONS": "0",
    "OKX_OPTIONS_MARGIN_MODE": "coin",
    "OKX_OPTIONS_CLOSE_GATE_MODE": "premium",
    "OKX_OPTIONS_CLOSE_RECYCLE_MULT": "2",
    "OKX_OPTIONS_CLOSE_RECYCLE_MULT_COIN": "1.05",
    "OKX_OPTIONS_CLOSE_NET_PNL_MIN_USDT": "0",
    "OKX_OPTIONS_CLOSE_HOLD_SECONDS": "120",
    "OKX_TRADE_MODE": "options",
    "HEDGE_PLAN_ENABLED": "false",
    "MAX_ACTIVE_HEDGE_PLANS": "1",
    "HEDGE_PLAN_OO_CLOSE_MODE_ENABLED": "true",
    "HEDGE_PLAN_OO_BIAS_SPLIT_BY": "budget",
    "HEDGE_PLAN_OO_BIAS_RATIO": "0.7",
    "HEDGE_PLAN_BUDGET_BUFFER": "0.95",
    "HEDGE_PLAN_OPTION_PRIMARY": "true",
    "HEDGE_PLAN_OPTIONS_MUTUAL_EXCLUSIVE": "true",
    "HEDGE_PLAN_MANUAL_COMPLETE_ON_PARTIAL": "true",
}


def _effective_env_value(key: str, file_values: dict[str, str], schema_default: str = "") -> str:
    if key == "OKX_TRADE_MODE":
        # 展示值必须与运行时 get_okx_trade_mode() 一致,避免未写入时默认 options 静默改模式
        file_val = str(file_values.get(key) or "").strip() if key in file_values else ""
        if file_val:
            from lib.hedge_plan.okx_trade_mode_lib import normalize_okx_trade_mode

            return normalize_okx_trade_mode(file_val) or file_val
        try:
            from lib.hedge_plan.okx_trade_mode_lib import get_okx_trade_mode

            return get_okx_trade_mode()
        except Exception:
            pass
    if key in file_values:
        file_val = str(file_values.get(key) or "").strip()
        if file_val:
            return file_val
    runtime = os.getenv(key)
    if runtime is not None and str(runtime).strip() != "":
        return str(runtime).strip()
    if schema_default:
        return schema_default
    return _RUNTIME_ENV_DEFAULTS.get(key, "")


def _env_truthy(raw: str) -> bool:
    return str(raw or "").strip().lower() in ("1", "true", "yes", "on")


def _schema_field_map(example_path: str) -> dict[str, dict[str, Any]]:
    out: dict[str, dict[str, Any]] = {}
    for group in parse_env_example_schema(example_path):
        for field in group.get("fields") or []:
            out[field["key"]] = dict(field)
    return out


def _build_field(
    key: str,
    label: str,
    note: str,
    schema: dict[str, dict[str, Any]],
    values: dict[str, str],
) -> dict[str, Any]:
    meta = schema.get(key) or {}
    schema_default = meta.get("default") or ""
    val = _effective_env_value(key, values, schema_default)
    # 与运行时一致:手动补开开启时,「自动平期权」展示为关闭(实际也不会执行)
    if key == "HEDGE_PLAN_PARTIAL_AUTO_CLOSE_OPTION":
        manual = _effective_env_value(
            "HEDGE_PLAN_MANUAL_COMPLETE_ON_PARTIAL", values, "true"
        )
        if _env_truthy(manual):
            val = "false"
    masked = _mask_value(key, val)
    ftype = meta.get("type") or _field_type(key, val or schema_default)
    options = select_options_for(key)
    if options:
        ftype = "select"
        val = normalize_select_value(key, val) or val
        masked = _mask_value(key, val)
    out: dict[str, Any] = {
        "key": key,
        "label": label,
        "note": note or meta.get("note") or "",
        "default": val,
        "type": ftype,
        "sensitive": meta.get("sensitive", _is_sensitive(key)),
        "restart_required": meta.get("restart_required", _restart_required(key)),
        "hot_reload": meta.get("hot_reload", _hot_reload(key)),
        "current": masked["value"] if not _is_sensitive(key) else "",
        "masked": masked["masked"],
        "tail": masked.get("tail") or "",
        "has_value": masked["has_value"],
    }
    if options:
        cur = (out["current"] or out["default"] or "").strip()
        opt_vals = {o["value"] for o in options}
        # 永期对冲不再作为可选模式;已选历史值也不塞回下拉,避免继续强化合约 UI
        if key == "OKX_TRADE_MODE" and cur == "perp_options":
            cur = ""
            out["current"] = "options"
            out["default"] = "options"
            out["note"] = (
                (out.get("note") or "")
                + "（当前 .env 仍为永期对冲:请改选「单独期权」或「期期对冲」后保存并重启）"
            ).strip()
        if cur and cur not in opt_vals:
            options = [{"value": cur, "label": cur}] + options
        out["options"] = options
    return out


def _okx_mode_for_env_ui() -> str:
    try:
        from lib.hedge_plan.okx_trade_mode_lib import get_okx_trade_mode

        return get_okx_trade_mode()
    except Exception:
        return "options"


def _options_fields_for_mode(mode: str) -> list[tuple[str, str, str]]:
    fields = list(_OPTIONS_SECTION["fields"])
    if mode != "options":
        fields = [f for f in fields if f[0] != "OKX_OPTIONS_MAX_ACTIVE_POSITIONS"]
    return fields


def _hedge_fields_for_mode(mode: str) -> list[tuple[str, str, str]]:
    if mode == "perp_options":
        return [*_HEDGE_COMMON_FIELDS, *_HEDGE_PO_FIELDS]
    if mode == "options_options":
        return [*_HEDGE_COMMON_FIELDS, *_HEDGE_OO_FIELDS]
    return []


def ui_sections_for_exchange(
    exchange_key: str,
    *,
    mode: str | None = None,
) -> list[dict[str, Any]]:
    ex = (exchange_key or "").strip().lower()
    sections: list[dict[str, Any]] = []
    live_fields = _EXCHANGE_LIVE_FIELDS.get(ex, _EXCHANGE_LIVE_FIELDS["okx"])
    sections.append({"title": "交易所与实盘", "fields": live_fields})
    sections.extend(_SHARED_SECTIONS)
    if ex in _MODE_SECTION.get("exchanges", frozenset()):
        from lib.hedge_plan.okx_trade_mode_lib import normalize_okx_trade_mode

        m = normalize_okx_trade_mode(mode) if mode else ""
        if not m:
            m = _okx_mode_for_env_ui()
        sections.append(_MODE_SECTION)
        sections.append({"title": "期权账户", "fields": _options_fields_for_mode(m)})
        # 永期对冲配置块不再展示(含合约腿);期期仍展示
        if m != "perp_options":
            hedge_fields = _hedge_fields_for_mode(m)
            if hedge_fields:
                title = "对冲计划·期期"
                sections.append({"title": title, "fields": hedge_fields})
    return sections


def ui_allowed_keys(exchange_key: str) -> frozenset[str]:
    """可写键=当前模式可见字段 + 模式切换键 + 遗留对冲开关(兼容旧脚本写入)."""
    keys: set[str] = set()
    for sec in ui_sections_for_exchange(exchange_key):
        for item in sec["fields"]:
            keys.add(item[0])
    ex = (exchange_key or "").strip().lower()
    if ex == "okx":
        keys.add("OKX_TRADE_MODE")
        # 允许写入遗留键,避免旧自动化/手改失败;页面不再展示
        for item in _HEDGE_PLAN_SECTION["fields"]:
            keys.add(item[0])
        for item in _OPTIONS_SECTION["fields"]:
            keys.add(item[0])
    return frozenset(keys)


def build_env_ui_payload(
    exchange_key: str,
    example_path: str,
    env_path: str,
) -> list[dict[str, Any]]:
    schema = _schema_field_map(example_path)
    env_lines = read_env_lines(env_path)
    values = env_get_all(env_lines)
    groups: list[dict[str, Any]] = []
    for sec in ui_sections_for_exchange(
        exchange_key, mode=values.get("OKX_TRADE_MODE") or ""
    ):
        fields = [
            _build_field(key, label, note, schema, values)
            for key, label, note in sec["fields"]
        ]
        fields = _mark_options_section_hidden(fields)
        groups.append({
            "title": sec["title"],
            "fields": fields,
            "has_restart": any(f.get("restart_required") for f in fields),
        })
    return groups


# 币本位专属 / USDC 专属(配置页互斥隐藏)
_COIN_ONLY_ENV_KEYS = frozenset({
    "OKX_OPTIONS_COIN_COMPOUND",
    "OKX_OPTIONS_COIN_BUDGET_USDT",
    "OKX_OPTIONS_COIN_MAX_USDT_ENABLED",
    "OKX_OPTIONS_COIN_MAX_USDT",
    "OKX_OPTIONS_COIN_SPOT_BUY_BUFFER",
    "OKX_OPTIONS_CLOSE_RECYCLE_MULT_COIN",
})
_USDC_ONLY_ENV_KEYS = frozenset({
    "OKX_OPTIONS_TRADE_BUDGET_USDC",
    "OKX_OPTIONS_COMPOUND_FULL_ENABLED",
    "OKX_OPTIONS_COMPOUND_FULL_CAP_ENABLED",
    "OKX_OPTIONS_COMPOUND_FULL_CAP_USDC",
    "OKX_OPTIONS_CLOSE_RECYCLE_MULT",
})


def _field_current(fields: list[dict[str, Any]], key: str, default: str = "") -> str:
    for f in fields:
        if f.get("key") == key:
            return str(f.get("current") or f.get("default") or default).strip()
    return default


def _mark_options_section_hidden(fields: list[dict[str, Any]]) -> list[dict[str, Any]]:
    """按本位/门控模式/全仓复利标记 hidden(供 SSR/前端;切换开关仍可再显示)."""
    margin = (_field_current(fields, "OKX_OPTIONS_MARGIN_MODE", "coin") or "coin").lower()
    is_coin = margin != "usdc"
    gate_mode = (_field_current(fields, "OKX_OPTIONS_CLOSE_GATE_MODE", "premium") or "premium").lower()
    compound_on = _env_truthy(_field_current(fields, "OKX_OPTIONS_COMPOUND_FULL_ENABLED", "true"))
    coin_compound_on = _env_truthy(_field_current(fields, "OKX_OPTIONS_COIN_COMPOUND", "true"))
    coin_max_on = _env_truthy(_field_current(fields, "OKX_OPTIONS_COIN_MAX_USDT_ENABLED", "false"))
    compound_cap_on = _env_truthy(
        _field_current(fields, "OKX_OPTIONS_COMPOUND_FULL_CAP_ENABLED", "false")
    )

    out: list[dict[str, Any]] = []
    for f in fields:
        key = str(f.get("key") or "")
        hide = False
        if is_coin and key in _USDC_ONLY_ENV_KEYS:
            hide = True
        elif (not is_coin) and key in _COIN_ONLY_ENV_KEYS:
            hide = True
        elif key == "OKX_OPTIONS_CLOSE_RECYCLE_MULT" and gate_mode != "premium":
            hide = True
        elif key == "OKX_OPTIONS_CLOSE_RECYCLE_MULT_COIN" and gate_mode != "premium":
            hide = True
        elif key == "OKX_OPTIONS_CLOSE_NET_PNL_MIN_USDT" and gate_mode != "net_pnl":
            hide = True
        elif key == "OKX_OPTIONS_TRADE_BUDGET_USDC" and compound_on:
            hide = True
        elif key == "OKX_OPTIONS_COMPOUND_FULL_CAP_ENABLED" and not compound_on:
            hide = True
        elif key == "OKX_OPTIONS_COMPOUND_FULL_CAP_USDC" and not (compound_on and compound_cap_on):
            hide = True
        elif key == "OKX_OPTIONS_COIN_BUDGET_USDT" and coin_compound_on:
            hide = True
        elif key == "OKX_OPTIONS_COIN_MAX_USDT" and not coin_max_on:
            hide = True
        if hide:
            item = dict(f)
            item["hidden"] = True
            out.append(item)
        else:
            out.append(f)
    return out


def _mark_compound_budget_hidden(fields: list[dict[str, Any]]) -> list[dict[str, Any]]:
    """兼容旧调用名."""
    return _mark_options_section_hidden(fields)


def filter_updates_for_ui(exchange_key: str, updates: dict[str, str]) -> dict[str, str]:
    allowed = ui_allowed_keys(exchange_key)
    return {k: v for k, v in (updates or {}).items() if k in allowed}


def validate_env_ui_updates(
    exchange_key: str,
    example_path: str,
    updates: dict[str, str],
) -> tuple[dict[str, str], list[str]]:
    from lib.env.env_schema import validate_env_updates

    schema = _schema_field_map(example_path)
    groups: list[dict[str, Any]] = []
    for sec in ui_sections_for_exchange(exchange_key):
        fields: list[dict[str, Any]] = []
        for key, _label, _note in sec["fields"]:
            if key in schema:
                field = dict(schema[key])
                opts = select_options_for(key)
                if opts:
                    field["type"] = "select"
                    field["options"] = opts
                fields.append(field)
            else:
                default = ""
                fields.append(
                    {
                        "key": key,
                        "type": _field_type(key, default),
                        "sensitive": _is_sensitive(key),
                        "restart_required": _restart_required(key),
                        "hot_reload": _hot_reload(key),
                        "options": select_options_for(key),
                    }
                )
        groups.append({"title": sec["title"], "fields": fields})
    return validate_env_updates(groups, updates)


def coerce_hedge_partial_close_with_manual(
    clean: dict[str, str],
    *,
    env_path: str = "",
) -> dict[str, str]:
    """手动补开为开启时,强制把自动平写成 false(与运行时一致)."""
    out = dict(clean or {})
    manual = out.get("HEDGE_PLAN_MANUAL_COMPLETE_ON_PARTIAL")
    if manual is None and env_path:
        try:
            from lib.env.env_file_lib import env_get_all, read_env_lines

            file_vals = env_get_all(read_env_lines(env_path))
            manual = _effective_env_value(
                "HEDGE_PLAN_MANUAL_COMPLETE_ON_PARTIAL", file_vals, "true"
            )
        except Exception:
            manual = "true"
    if _env_truthy(str(manual or "")):
        out["HEDGE_PLAN_PARTIAL_AUTO_CLOSE_OPTION"] = "false"
    return out