xiaoxia-saas/packages/domain/system_setting.py

"""系统配置领域实体 — #2246.

承载 setting_type（bool/int/float/string/json）及 setting_value 的
序列化/反序列化规则；与 DB、框架无关。
"""

from __future__ import annotations

import json
from dataclasses import dataclass, field
from datetime import UTC, datetime
from typing import Any
from uuid import uuid4

SETTING_TYPE_BOOL = "bool"
SETTING_TYPE_INT = "int"
SETTING_TYPE_FLOAT = "float"
SETTING_TYPE_STRING = "string"
SETTING_TYPE_JSON = "json"

VALID_SETTING_TYPES = {
    SETTING_TYPE_BOOL,
    SETTING_TYPE_INT,
    SETTING_TYPE_FLOAT,
    SETTING_TYPE_STRING,
    SETTING_TYPE_JSON,
}


class SystemSettingError(ValueError):
    """系统配置类型或序列化错误."""


def infer_setting_type(value: Any) -> str:
    """根据 Python 值推断 setting_type（bool 必须先于 int 判断）."""
    if isinstance(value, bool):
        return SETTING_TYPE_BOOL
    if isinstance(value, int):
        return SETTING_TYPE_INT
    if isinstance(value, float):
        return SETTING_TYPE_FLOAT
    if isinstance(value, str):
        return SETTING_TYPE_STRING
    return SETTING_TYPE_JSON


def serialize_setting_value(value: Any, setting_type: str) -> str:
    """把 Python 值按 setting_type 序列化为可入库的字符串."""
    if setting_type == SETTING_TYPE_BOOL:
        if not isinstance(value, bool):
            raise SystemSettingError(f"bool 配置值必须是布尔类型，收到 {value!r}")
        return "true" if value else "false"
    if setting_type == SETTING_TYPE_INT:
        if isinstance(value, bool) or not isinstance(value, int):
            raise SystemSettingError(f"int 配置值必须是整数，收到 {value!r}")
        return str(value)
    if setting_type == SETTING_TYPE_FLOAT:
        if isinstance(value, bool):
            raise SystemSettingError(f"float 配置值不能是布尔类型，收到 {value!r}")
        try:
            return repr(float(value))
        except (TypeError, ValueError) as exc:
            raise SystemSettingError(f"float 配置值非法：{value!r}") from exc
    if setting_type == SETTING_TYPE_STRING:
        if not isinstance(value, str):
            raise SystemSettingError(f"string 配置值必须是字符串，收到 {value!r}")
        return value
    if setting_type == SETTING_TYPE_JSON:
        try:
            return json.dumps(value, ensure_ascii=False)
        except (TypeError, ValueError) as exc:
            raise SystemSettingError(f"json 配置值无法序列化：{value!r}") from exc
    raise SystemSettingError(f"未知 setting_type: {setting_type}")


def deserialize_setting_value(raw: str | None, setting_type: str) -> Any:
    """把入库字符串按 setting_type 反序列化为 Python 值."""
    if raw is None:
        return None
    if setting_type == SETTING_TYPE_BOOL:
        return str(raw).strip().lower() in {"1", "true", "yes", "on"}
    if setting_type == SETTING_TYPE_INT:
        try:
            return int(str(raw).strip())
        except ValueError as exc:
            raise SystemSettingError(f"int 配置值损坏：{raw!r}") from exc
    if setting_type == SETTING_TYPE_FLOAT:
        try:
            return float(str(raw).strip())
        except ValueError as exc:
            raise SystemSettingError(f"float 配置值损坏：{raw!r}") from exc
    if setting_type == SETTING_TYPE_STRING:
        return raw
    if setting_type == SETTING_TYPE_JSON:
        try:
            return json.loads(raw)
        except (TypeError, ValueError) as exc:
            raise SystemSettingError(f"json 配置值损坏：{raw!r}") from exc
    raise SystemSettingError(f"未知 setting_type: {setting_type}")


@dataclass(slots=True)
class SystemSetting:
    """系统配置领域实体."""

    setting_key: str
    setting_value: str | None = None
    setting_type: str = SETTING_TYPE_STRING
    description: str = ""
    is_public: bool = False
    category: str = "general"
    updated_by: str | None = None
    id: str = field(default_factory=lambda: uuid4().hex)
    created_at: datetime = field(default_factory=lambda: datetime.now(UTC))
    updated_at: datetime = field(default_factory=lambda: datetime.now(UTC))

    def get_typed_value(self) -> Any:
        return deserialize_setting_value(self.setting_value, self.setting_type)

    @classmethod
    def from_value(
        cls,
        setting_key: str,
        value: Any,
        setting_type: str | None = None,
        **kwargs: Any,
    ) -> "SystemSetting":
        st = setting_type or infer_setting_type(value)
        return cls(
            setting_key=setting_key,
            setting_value=serialize_setting_value(value, st),
            setting_type=st,
            **kwargs,
        )