ys_base 0.1.0__py3-none-any.whl

ys_base/__init__.py

@@ -0,0 +1,4 @@
+# -*- coding: utf-8 -*-
+"""YS 统一 SDK：契约模型 / auth 客户端与差量同步 / 应用服务骨架 / 交易网关。"""
+
+__version__ = "0.1.0"

ys_base/auth/__init__.py

@@ -0,0 +1,5 @@
+# -*- coding: utf-8 -*-
+from ys_base.auth.client import AppCredentials, AuthClient
+from ys_base.auth.delta import DeltaSync
+
+__all__ = ["AppCredentials", "AuthClient", "DeltaSync"]

ys_base/auth/client.py

@@ -0,0 +1,151 @@
+# -*- coding: utf-8 -*-
+"""AuthClient v2 —— 子系统连接 auth 平台的客户端。
+
+流程（架构方案 v5 §1 / v6 §1）：
+hello → register_app(HMAC 挑战应答) → sync(游标上报) → snapshot/delta 持续接收
+控制事件：user_revoked（踢用户）、app_status（可插拔状态机）、resync（授权变更重拉）。
+"""
+
+import hashlib
+import hmac
+import time
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any
+
+from loguru import logger
+
+from ys_base.auth.delta import DeltaSync
+from ys_base.ws.rpc_client import WsRpcClient, YsRejected
+
+RevokedCallback = Callable[[str, str], Awaitable[None]]  # (user_id, reason)
+StatusCallback = Callable[[str], Awaitable[None]]  # (app_status)
+
+
+@dataclass
+class AppCredentials:
+    app_name: str
+    secret: str
+
+    def sign(self, connection_id: str, ts: float) -> str:
+        message = f"{connection_id}:{ts}".encode()
+        return hmac.new(self.secret.encode(), message, hashlib.sha256).hexdigest()
+
+
+class AuthClient(WsRpcClient):
+    def __init__(
+        self,
+        uri: str,
+        credentials: AppCredentials,
+        *,
+        delta_sync: DeltaSync | None = None,
+        app_version: str = "",
+        **kwargs: Any,
+    ):
+        super().__init__(uri, **kwargs)
+        self.credentials = credentials
+        self.delta = delta_sync
+        self.app_version = app_version
+        self.registered = False
+        self.app_id: str = ""
+        self.server_contracts_version: str = ""
+        self._revoked_callbacks: list[RevokedCallback] = []
+        self._status_callbacks: list[StatusCallback] = []
+        if self.delta is not None:
+            self.delta.bind_resync(self._request_resync)
+
+    # ---------- 回调注册 ----------
+
+    def on_revoked(self, callback: RevokedCallback) -> None:
+        self._revoked_callbacks.append(callback)
+
+    def on_app_status(self, callback: StatusCallback) -> None:
+        self._status_callbacks.append(callback)
+
+    # ---------- 握手 ----------
+
+    async def _handle_hello(self, data: dict[str, Any]) -> None:
+        self.registered = False
+        self.server_contracts_version = str(data.get("contracts_version", ""))
+        ts = time.time()
+        try:
+            result = await self.call(
+                "register_app",
+                {
+                    "app_name": self.credentials.app_name,
+                    "signature": self.credentials.sign(self.connection_id, ts),
+                    "ts": ts,
+                    "sdk_version": self._sdk_version(),
+                    "app_version": self.app_version,
+                },
+            )
+        except YsRejected as e:
+            logger.error("应用注册被拒: {}（状态可能为 disabled，按降级策略处理）", e)
+            for callback in self._status_callbacks:
+                await callback("disabled")
+            return
+        self.app_id = str((result or {}).get("app_id", ""))
+        self.registered = True
+        logger.info("应用注册成功: {} (app_id={})", self.credentials.app_name, self.app_id)
+        if self.delta is not None:
+            await self.send_event("sync", {"cursors": await self.delta.build_cursors()})
+
+    @staticmethod
+    def _sdk_version() -> str:
+        from ys_base import __version__
+
+        return __version__
+
+    async def _request_resync(self, tables: list[str]) -> None:
+        cursors = {table: 0 for table in tables}
+        await self.send_event("sync", {"cursors": cursors})
+
+    # ---------- 事件分发 ----------
+
+    async def _dispatch_event(self, event: str, data: dict[str, Any]) -> None:
+        if event == "snapshot" and self.delta is not None:
+            await self.delta.handle_snapshot(data)
+            return
+        if event == "delta" and self.delta is not None:
+            await self.delta.handle_delta(data)
+            return
+        if event == "resync" and self.delta is not None:
+            await self.delta.handle_resync(data)
+            return
+        if event == "user_revoked":
+            user_id = str(data.get("user_id", ""))
+            reason = str(data.get("reason", ""))
+            for callback in self._revoked_callbacks:
+                try:
+                    await callback(user_id, reason)
+                except Exception:
+                    logger.exception("user_revoked 回调异常")
+            return
+        if event == "app_status":
+            status = str(data.get("status", ""))
+            for callback in self._status_callbacks:
+                try:
+                    await callback(status)
+                except Exception:
+                    logger.exception("app_status 回调异常")
+            return
+        await super()._dispatch_event(event, data)
+
+    # ---------- 业务接口 ----------
+
+    async def login(self, info: dict[str, Any]) -> dict[str, Any]:
+        """转发终端用户登录（返回用户信息 + token 对）。"""
+        return await self.call("login", info)
+
+    async def exchange_sso_code(self, code: str) -> dict[str, Any]:
+        """门户一次性 code 换 token（SSO）。"""
+        return await self.call("exchange_sso_code", {"code": code})
+
+    async def heartbeat(self, checks: dict[str, str] | None = None, uptime: float = 0) -> None:
+        cursors = await self.delta.build_cursors() if self.delta is not None else {}
+        await self.send_event(
+            "heartbeat",
+            {"cursors": cursors, "uptime": uptime, "healthy": all(
+                v == "ok" for v in (checks or {}).values()
+            ), "checks": checks or {}},
+        )

ys_base/auth/delta.py

@@ -0,0 +1,95 @@
+# -*- coding: utf-8 -*-
+"""DeltaSync —— 差量同步引擎（客户端侧）。
+
+职责：
+- 维护各表游标，生成 sync 上报；
+- 应用 snapshot（分批聚合）与 delta（幂等）；
+- seq 空洞检测 → 请求重新同步该表；
+- 表级回调通知业务层。
+"""
+
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from loguru import logger
+
+from ys_base.store.base import LocalStore
+
+TableCallback = Callable[[str, list[dict[str, Any]]], Awaitable[None]]
+ResyncRequest = Callable[[list[str]], Awaitable[None]]
+
+
+class DeltaSync:
+    def __init__(self, store: LocalStore, tables: list[str]):
+        self.store = store
+        self.tables = list(tables)
+        self._snapshot_buffer: dict[str, list[dict[str, Any]]] = {}
+        self._callbacks: dict[str, list[TableCallback]] = {}
+        self._request_resync: ResyncRequest | None = None
+
+    def on_table(self, table: str, callback: TableCallback) -> None:
+        """注册表变更回调（收到差量/快照落库后触发，参数为本批文档）。"""
+        self._callbacks.setdefault(table, []).append(callback)
+
+    def bind_resync(self, request_resync: ResyncRequest) -> None:
+        self._request_resync = request_resync
+
+    async def build_cursors(self) -> dict[str, int]:
+        return {table: await self.store.get_cursor(table) for table in self.tables}
+
+    # ---------- 事件入口（由 AuthClient 调用） ----------
+
+    async def handle_snapshot(self, data: dict[str, Any]) -> None:
+        table = data["table"]
+        batch, total = int(data.get("batch", 1)), int(data.get("total", 1))
+        docs = data.get("docs", [])
+        buffer = self._snapshot_buffer.setdefault(table, [])
+        buffer.extend(docs)
+        if batch < total:
+            return
+        collected = self._snapshot_buffer.pop(table, [])
+        last_seq = int(data.get("last_seq", 0))
+        await self.store.replace_table(table, collected, last_seq)
+        logger.info("快照落地: {} 共 {} 条 (seq={})", table, len(collected), last_seq)
+        await self._notify(table, collected)
+
+    async def handle_delta(self, data: dict[str, Any]) -> None:
+        table = data["table"]
+        changes: list[dict[str, Any]] = data.get("changes", [])
+        last_seq = int(data.get("last_seq", 0))
+        if not changes:
+            return
+        cursor = await self.store.get_cursor(table)
+        first_seq = int(changes[0].get("seq", 0))
+        if first_seq > cursor + 1:
+            logger.warning("检测到 seq 空洞: {} cursor={} first={}，请求重新同步", table, cursor, first_seq)
+            await self._resync([table])
+            return
+        effective = [c for c in changes if int(c.get("seq", 0)) > cursor]
+        if not effective:
+            return
+        await self.store.apply_changes(table, effective, last_seq)
+        await self._notify(table, [c.get("doc", {}) for c in effective])
+
+    async def handle_resync(self, data: dict[str, Any]) -> None:
+        """服务端要求重拉（授权变更等）。"""
+        tables = data.get("tables") or self.tables
+        for table in tables:
+            self._snapshot_buffer.pop(table, None)
+            await self.store.replace_table(table, [], 0)
+        await self._resync(list(tables))
+
+    # ---------- 内部 ----------
+
+    async def _resync(self, tables: list[str]) -> None:
+        if self._request_resync is None:
+            logger.error("未绑定 resync 请求通道，无法补差: {}", tables)
+            return
+        await self._request_resync(tables)
+
+    async def _notify(self, table: str, docs: list[dict[str, Any]]) -> None:
+        for callback in self._callbacks.get(table, []):
+            try:
+                await callback(table, docs)
+            except Exception:
+                logger.exception("表回调异常: {}", table)

ys_base/contracts/__init__.py

@@ -0,0 +1,123 @@
+# -*- coding: utf-8 -*-
+"""ys_base.contracts —— 全平台跨系统契约（唯一事实来源）。
+
+TABLES 注册表：表名 ↔ 模型 ↔ 订阅授权枚举，供 DeltaSync / 服务端下发管道 / codegen 使用。
+"""
+
+from pydantic import BaseModel
+
+from ys_base.contracts.base import (
+    SField,
+    YsModel,
+    field_sensitivity,
+    fields_for_grant,
+    project_doc,
+)
+from ys_base.contracts.enums import *  # noqa: F401,F403
+from ys_base.contracts.enums import AccessTable, export_enum_meta
+from ys_base.contracts.master import (
+    Account,
+    BankCard,
+    Broker,
+    CounterSupplier,
+    Custodian,
+    ExchangeAccount,
+    MountExchangeAccount,
+    Owner,
+    Project,
+    Server,
+    ServerRef,
+    ServerRoom,
+    Strategy,
+    Team,
+    TradingPlatform,
+    User,
+)
+from ys_base.contracts.platform import (
+    App,
+    AppConfig,
+    ChangelogEntry,
+    FileMeta,
+    RefreshToken,
+    RowFilter,
+)
+from ys_base.contracts.relations import (
+    AccountApp,
+    AccountStrategy,
+    FOREIGN_KEYS,
+    ForeignKey,
+    OwnerApp,
+    OwnerStrategy,
+    ProjectOwner,
+    UserApp,
+    foreign_keys_to,
+)
+
+#: 表名(=Mongo 集合名/SQLite 表名) → 模型
+TABLES: dict[str, type[YsModel]] = {
+    "teams": Team,
+    "owners": Owner,
+    "accounts": Account,
+    "exchange_accounts": ExchangeAccount,
+    "mount_exchange_accounts": MountExchangeAccount,
+    "users": User,
+    "bank_cards": BankCard,
+    "custodians": Custodian,
+    "strategies": Strategy,
+    "projects": Project,
+    "brokers": Broker,
+    "servers": Server,
+    "trading_platforms": TradingPlatform,
+    "counter_suppliers": CounterSupplier,
+    "server_rooms": ServerRoom,
+    "user_app": UserApp,
+    "account_app": AccountApp,
+    "owner_app": OwnerApp,
+    "account_strategy": AccountStrategy,
+    "owner_strategy": OwnerStrategy,
+    "project_owner": ProjectOwner,
+    "apps": App,
+    "app_configs": AppConfig,
+    "file_metas": FileMeta,
+}
+
+#: 订阅授权枚举 → 该授权可订阅的表集合（闭包：授权 OWNER 即含其关联台账等）
+ACCESS_TABLES: dict[AccessTable, tuple[str, ...]] = {
+    AccessTable.USER: ("users", "user_app"),
+    AccessTable.TEAM: ("teams",),
+    AccessTable.OWNER: (
+        "owners",
+        "owner_app",
+        "owner_strategy",
+        "exchange_accounts",
+        "bank_cards",
+    ),
+    AccessTable.ACCOUNT: (
+        "accounts",
+        "account_app",
+        "account_strategy",
+        "mount_exchange_accounts",
+        "brokers",
+        "servers",
+    ),
+    AccessTable.CUSTODIAN: ("custodians",),
+    AccessTable.PROJECT: ("projects", "project_owner", "strategies"),
+    AccessTable.APP_CONFIG: ("app_configs",),
+}
+
+__all__ = [  # noqa: RUF022
+    "YsModel", "SField", "project_doc", "fields_for_grant", "field_sensitivity",
+    "export_enum_meta", "TABLES", "ACCESS_TABLES", "ForeignKey", "FOREIGN_KEYS",
+    "foreign_keys_to",
+    "Team", "Owner", "Account", "ExchangeAccount", "MountExchangeAccount", "User",
+    "BankCard", "Custodian", "Strategy", "Project", "Broker", "Server", "ServerRef",
+    "TradingPlatform", "CounterSupplier", "ServerRoom",
+    "UserApp", "AccountApp", "OwnerApp", "AccountStrategy", "OwnerStrategy", "ProjectOwner",
+    "App", "AppConfig", "RowFilter", "ChangelogEntry", "RefreshToken", "FileMeta",
+]
+
+
+def model_for_table(table: str) -> type[BaseModel]:
+    if table not in TABLES:
+        raise KeyError(f"未注册的契约表: {table}")
+    return TABLES[table]

ys_base/contracts/base.py

@@ -0,0 +1,77 @@
+# -*- coding: utf-8 -*-
+"""契约基类与字段级投影工具。
+
+约定（架构方案 v6）：
+- 主键 `_id` = ObjectId hex 字符串，模型内属性名 `id`；
+- created_at/updated_at/deleted_at 为 epoch 秒；deleted_at 非空即软删除；
+- 字段敏感级经 Field 的 json_schema_extra["sensitivity"] 标注，
+  下发管道按 App 的 FieldGrant 用 project_doc() 投影裁剪（剔除字段而非置空）。
+"""
+
+import time
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ys_base.contracts.enums import GRANT_ALLOWS, FieldGrant, Sensitivity
+
+
+def SField(
+    default: Any = ...,
+    *,
+    sensitivity: Sensitivity,
+    title: str | None = None,
+    **kwargs: Any,
+) -> Any:
+    """带敏感级标注的 Field。"""
+    extra = kwargs.pop("json_schema_extra", {}) or {}
+    extra["sensitivity"] = sensitivity.value
+    return Field(default, title=title, json_schema_extra=extra, **kwargs)
+
+
+class YsModel(BaseModel):
+    """全实体公共基类。"""
+
+    model_config = ConfigDict(populate_by_name=True, use_enum_values=False, extra="ignore")
+
+    id: str = Field(default="", alias="_id", title="主键")
+    created_at: float = Field(default_factory=time.time, title="创建时间")
+    updated_at: float = Field(default_factory=time.time, title="更新时间")
+    deleted_at: float | None = Field(default=None, title="软删除时间")
+
+    def to_doc(self) -> dict[str, Any]:
+        """导出为存储/传输文档（含 _id 别名，枚举转值）。"""
+        return self.model_dump(by_alias=True, mode="json")
+
+
+def field_sensitivity(model_cls: type[BaseModel], field_name: str) -> Sensitivity:
+    info = model_cls.model_fields.get(field_name)
+    if info is None:
+        return Sensitivity.public
+    extra = info.json_schema_extra
+    if isinstance(extra, dict):
+        value = extra.get("sensitivity")
+        if value:
+            return Sensitivity(value)
+    return Sensitivity.public
+
+
+def fields_for_grant(model_cls: type[BaseModel], grant: FieldGrant) -> set[str]:
+    """该授权等级下可见的字段名集合（含 _id 别名对应的 id）。"""
+    allowed = GRANT_ALLOWS[grant]
+    return {name for name in model_cls.model_fields if field_sensitivity(model_cls, name) in allowed}
+
+
+def project_doc(model_cls: type[BaseModel], doc: dict[str, Any], grant: FieldGrant) -> dict[str, Any]:
+    """按授权等级裁剪文档：高于授权的字段整体剔除（而非置空）。
+
+    doc 以存储形态（_id 别名）传入/返回；未在契约中的键一律剔除。
+    """
+    visible = fields_for_grant(model_cls, grant)
+    out: dict[str, Any] = {}
+    for name in visible:
+        info = model_cls.model_fields[name]
+        key = info.alias or name
+        if key in doc:
+            out[key] = doc[key]
+    return out

ys_base/contracts/enums.py

@@ -0,0 +1,201 @@
+# -*- coding: utf-8 -*-
+"""契约枚举。代码值为 str；中文名/排序等展示元数据集中在 ENUM_META，经 export_enum_meta() 下发前端。"""
+
+from enum import StrEnum
+from typing import Any
+
+
+class UserRole(StrEnum):
+    Observer = "Observer"
+    User = "User"
+    Operator = "Operator"
+    Manager = "Manager"
+    Root = "Root"
+
+
+class TeamType(StrEnum):
+    Manager = "Manager"
+    Commoner = "Commoner"
+
+
+class OwnerType(StrEnum):
+    Product = "Product"
+    LegalPerson = "LegalPerson"
+    NaturalPerson = "NaturalPerson"
+
+
+class ExchangeType(StrEnum):
+    SH = "SH"
+    SZ = "SZ"
+    SHFE = "SHFE"
+    CFFEX = "CFFEX"
+    CZCE = "CZCE"
+    DCE = "DCE"
+    GFEX = "GFEX"
+    INE = "INE"
+    SGE = "SGE"
+    UNKNOWN = "UNKNOWN"
+
+
+class AccountType(StrEnum):
+    STOCK = "STOCK"
+    FUTURES = "FUTURES"
+    CREDIT = "CREDIT"
+    STOCK_OPTION = "STOCK_OPTION"
+    GOLD = "GOLD"
+    INCOME_SWAP = "INCOME_SWAP"
+    FUTURES_OPTION = "FUTURES_OPTION"
+    HUGANGTONG = "HUGANGTONG"
+    NEW3BOARD = "NEW3BOARD"
+    SHENGANGTONG = "SHENGANGTONG"
+
+
+class TradeEnvType(StrEnum):
+    LIVE = "LIVE"
+    TEST = "TEST"
+
+
+class AccessTable(StrEnum):
+    """表级订阅授权。"""
+
+    USER = "USER"
+    TEAM = "TEAM"
+    OWNER = "OWNER"
+    ACCOUNT = "ACCOUNT"
+    CUSTODIAN = "CUSTODIAN"
+    PROJECT = "PROJECT"
+    APP_CONFIG = "APP_CONFIG"
+
+
+class GatewayMode(StrEnum):
+    db = "db"
+    flow = "flow"
+
+
+class ServerType(StrEnum):
+    td = "td"
+    md = "md"
+
+
+class AppKind(StrEnum):
+    service = "service"  # 连 auth 订阅数据的子系统
+    link = "link"  # 纯门户外链
+
+
+class AppStatus(StrEnum):
+    enabled = "enabled"
+    disabled = "disabled"
+    maintenance = "maintenance"
+
+
+class FieldGrant(StrEnum):
+    """字段级授权（层级递进：credential ⊃ restricted ⊃ public）。"""
+
+    public = "public"
+    restricted = "restricted"
+    credential = "credential"
+
+
+class Sensitivity(StrEnum):
+    """契约字段敏感级标注。"""
+
+    public = "public"
+    restricted = "restricted"  # 生产基础设施信息
+    credential = "credential"  # 凭据
+
+
+class ChangeOp(StrEnum):
+    upsert = "upsert"
+    delete = "delete"
+
+
+#: 层级：grant 允许看到的 sensitivity 集合
+GRANT_ALLOWS: dict[FieldGrant, frozenset[Sensitivity]] = {
+    FieldGrant.public: frozenset({Sensitivity.public}),
+    FieldGrant.restricted: frozenset({Sensitivity.public, Sensitivity.restricted}),
+    FieldGrant.credential: frozenset({Sensitivity.public, Sensitivity.restricted, Sensitivity.credential}),
+}
+
+#: 展示元数据（前端经 export_enum_meta() 获取，替代旧 dict-value 枚举）
+ENUM_META: dict[str, dict[str, dict[str, Any]]] = {
+    "UserRole": {
+        "Observer": {"name": "观察员", "sort": 0},
+        "User": {"name": "普通用户", "sort": 1},
+        "Operator": {"name": "运维员", "sort": 2},
+        "Manager": {"name": "管理员", "sort": 3},
+        "Root": {"name": "超级管理员", "sort": 4},
+    },
+    "TeamType": {
+        "Manager": {"name": "管理人", "sort": 0},
+        "Commoner": {"name": "非管理人", "sort": 1},
+    },
+    "OwnerType": {
+        "Product": {"name": "产品", "team_type": "Manager", "sort": 0},
+        "LegalPerson": {"name": "法人", "team_type": "Commoner", "sort": 1},
+        "NaturalPerson": {"name": "自然人", "team_type": "Commoner", "sort": 2},
+    },
+    "ExchangeType": {
+        "SH": {"name": "上交所", "market": "STOCK"},
+        "SZ": {"name": "深交所", "market": "STOCK"},
+        "SHFE": {"name": "上期所", "market": "FUTURES"},
+        "CFFEX": {"name": "中金所", "market": "FUTURES"},
+        "CZCE": {"name": "郑商所", "market": "FUTURES"},
+        "DCE": {"name": "大商所", "market": "FUTURES"},
+        "GFEX": {"name": "广期所", "market": "FUTURES"},
+        "INE": {"name": "上能所", "market": "FUTURES"},
+        "SGE": {"name": "金交所", "market": "FUTURES"},
+        "UNKNOWN": {"name": "其他", "market": "UNKNOWN"},
+    },
+    "AccountType": {
+        "STOCK": {"name": "股票账户", "agent": ["STOCK", "FUTURES"]},
+        "FUTURES": {"name": "期货账户", "agent": ["FUTURES"]},
+        "CREDIT": {"name": "信用账户", "agent": ["STOCK"]},
+        "STOCK_OPTION": {"name": "股票期权", "agent": ["STOCK", "FUTURES"]},
+        "GOLD": {"name": "贵金属账户", "agent": ["STOCK", "FUTURES"]},
+        "INCOME_SWAP": {"name": "收益互换账户", "agent": ["STOCK"]},
+        "FUTURES_OPTION": {"name": "期货期权", "agent": ["FUTURES"]},
+        "HUGANGTONG": {"name": "沪港通账户", "agent": ["STOCK"]},
+        "NEW3BOARD": {"name": "全国股转账户", "agent": ["STOCK"]},
+        "SHENGANGTONG": {"name": "深港通账户", "agent": ["STOCK"]},
+    },
+    "TradeEnvType": {
+        "LIVE": {"name": "实盘", "sort": 0},
+        "TEST": {"name": "测试", "sort": 1},
+    },
+    "AccessTable": {
+        "USER": {"name": "用户表", "sort": 0},
+        "TEAM": {"name": "团队表", "sort": 1},
+        "OWNER": {"name": "产品表", "sort": 2},
+        "ACCOUNT": {"name": "账户表", "sort": 3},
+        "CUSTODIAN": {"name": "托管表", "sort": 4},
+        "PROJECT": {"name": "项目表", "sort": 5},
+        "APP_CONFIG": {"name": "应用配置", "sort": 6},
+    },
+    "GatewayMode": {"db": {"name": "数据库"}, "flow": {"name": "流"}},
+    "ServerType": {"td": {"name": "交易"}, "md": {"name": "行情"}},
+    "AppKind": {"service": {"name": "业务子系统"}, "link": {"name": "门户外链"}},
+    "AppStatus": {
+        "enabled": {"name": "运行中"},
+        "disabled": {"name": "已停用"},
+        "maintenance": {"name": "维护中"},
+    },
+    "FieldGrant": {
+        "public": {"name": "常规"},
+        "restricted": {"name": "含生产信息"},
+        "credential": {"name": "含凭据"},
+    },
+}
+
+
+def export_enum_meta() -> dict[str, Any]:
+    """导出枚举元数据（成员顺序 + 展示信息），供前端与 codegen 使用。"""
+    import ys_base.contracts.enums as _self
+
+    result: dict[str, Any] = {}
+    for enum_name, meta in ENUM_META.items():
+        enum_cls = getattr(_self, enum_name)
+        result[enum_name] = {
+            "members": [m.value for m in enum_cls],
+            "meta": meta,
+        }
+    return result