Resolve issue 55 (#58)

* fix: ActionResult

* feat: Exception

* feat: 添加冻结机制

* docs: 完善文档

Author: JohnRichard4096

README.md

@@ -36,7 +36,7 @@
 - 🔐 安全控制:  支持负余额限制
 - 📝 批量操作:  支持批量修改用户的货币数据
 - 🔍 时间范围审计日志:  从时间范围获取交易记录
-- 🚀 导出数据: 支持从Json文件导入，导出到Json文件
+- 🚀 导出数据: 支持从Json文件导入/导出到Json文件
 - 🔧 依赖注入: 支持依赖注入模式调用
 
 ### 快速开始

docs/apis/advanced.md

@@ -148,6 +148,44 @@ async def get_or_create_account(
     ...
 ```
 
+### `~~.set_frozen`
+
+```python
+async def set_frozen(
+    account_id: str,
+    frozen: bool,
+    currency_id: str | None = None,
+    session: AsyncSession | None = None,
+) -> None:
+    """设置账户特定货币的冻结状态
+
+    Args:
+        account_id (str): 账户ID
+        frozen (bool): 是否冻结
+        currency_id (str | None, optional): 货币ID. Defaults to None.
+        session (AsyncSession | None, optional): 异步Session. Defaults to None.
+    """
+    ...
+```
+
+### `set_frozen_all`
+
+```python
+async def set_frozen_all(
+    account_id: str,
+    frozen: bool,
+    session: AsyncSession | None = None,
+):
+    """冻结这个账户ID下的所有货币储备
+
+    Args:
+        account_id (str): 账户ID
+        frozen (bool): 是否冻结
+        session (AsyncSession | None, optional): 异步Session. Defaults to None.
+    """
+    ...
+```
+
 ### `~~.del_account`
 
 ```python

docs/apis/kernel.md

@@ -66,10 +66,27 @@ class AccountRepository:
         """获取或创建用户账户"""
         ...
 
+    async def set_account_frozen(
+        self,
+        account_id: str,
+        currency_id: str,
+        frozen: bool,
+    ) -> None:
+        """设置账户冻结状态"""
+        ...
+
+    async def is_account_frozen(
+        self,
+        account_id: str,
+        currency_id: str,
+    ) -> bool:
+        """判断账户是否冻结"""
+        ...
+
     async def get_balance(self, account_id: str) -> float | None:
         """获取账户余额"""
         ...
-
+    
     async def update_balance(
         self, account_id: str, amount: float, currency_id: str
     ) -> tuple[float, float]:

docs/apis/standard.md

@@ -21,6 +21,34 @@ async def list_accounts(currency_id: str | None = None) -> list[UserAccountData]
     ...
 ```
 
+### `~~.set_frozen`
+
+```python
+async def set_frozen(account_id: str, currency_id: str, frozen: bool) -> None:
+    """设置账户特定货币冻结状态
+
+    Args:
+        account_id (str): 用户ID
+        currency_id (str): 货币ID
+        frozen (bool): 是否冻结
+    """
+    ...
+```
+
+### `~~.set_frozen_all`
+
+```python
+async def set_frozen_all(account_id: str, frozen: bool) -> None:
+    """冻结账户的所有货币资产
+
+    Args:
+        account_id (str): 账户ID
+        frozen (bool): 是否冻结
+    """
+    ...
+```
+
+
 ### `~~.get_or_create_account`
 
 ```python

nonebot_plugin_value/api/api_balance.py

@@ -8,10 +8,35 @@
 from ..services.balance import del_balance as _d_balance
 from ..services.balance import get_or_create_account as _go_account
 from ..services.balance import list_accounts as _list_accounts
+from ..services.balance import set_frozen as _set_frozen
+from ..services.balance import set_frozen_all as _set_frozen_all
 from ..services.balance import transfer_funds as _transfer
 from .api_currency import get_default_currency as _get_default
 
 
+async def set_frozen_all(account_id: str, frozen: bool) -> None:
+    """冻结账户的所有货币资产
+
+    Args:
+        account_id (str): 账户ID
+        frozen (bool): 是否冻结
+    """
+    async with get_session() as session:
+        await _set_frozen_all(account_id, frozen, session)
+
+
+async def set_frozen(account_id: str, currency_id: str, frozen: bool) -> None:
+    """设置账户特定货币冻结状态
+
+    Args:
+        account_id (str): 用户ID
+        currency_id (str): 货币ID
+        frozen (bool): 是否冻结
+    """
+    async with get_session() as session:
+        await _set_frozen(account_id, frozen, currency_id, session)
+
+
 async def list_accounts(currency_id: str | None = None) -> list[UserAccountData]:
     """获取指定货币（或默认）的账户列表
 

nonebot_plugin_value/api/depends/data_classes.py

@@ -24,8 +24,8 @@ async def __call__(self, event: Event) -> list[TransactionData]:
             )
         start_time, end_time = self.timerange
         return await get_transaction_history_by_time_range(
-                to_uuid(event.get_user_id()), start_time, end_time, self.limit
-            )
+            to_uuid(event.get_user_id()), start_time, end_time, self.limit
+        )
 
 
 @dataclass

nonebot_plugin_value/dump_tools.py

@@ -41,7 +41,7 @@ async def dump_data() -> MigrationData:
     for currency in currencies:
         accounts = await list_accounts(currency_id=currency.id)
         for account in accounts:
-            transactions = await get_transaction_history(account.id)
+            transactions = await get_transaction_history(account.id, 100)
             data.accounts.append(
                 AccountMigrationData(
                     account_data=account,

nonebot_plugin_value/exception.py

@@ -0,0 +1,66 @@
+class BaseFailed(Exception):
+    """
+    Base failed exception for all exceptions
+    """
+
+
+# start of basic exceptions
+
+
+class AccountException(BaseFailed):
+    """
+    Account exception
+    """
+
+
+class CurrencyException(BaseFailed):
+    """
+    Currency exception
+    """
+
+
+class TransactionException(BaseFailed):
+    """
+    Transaction exception
+    """
+
+
+# end of basic exceptions
+
+
+# start of not found exceptions
+
+
+class NotFoundException(BaseFailed):
+    """
+    Not found exception
+    """
+
+
+class AccountNotFound(NotFoundException, AccountException):
+    """
+    Account not found exception
+    """
+
+
+class CurrencyNotFound(NotFoundException, CurrencyException):
+    """
+    Currency not found exception
+    """
+
+
+class TransactionNotFound(NotFoundException, TransactionException):
+    """
+    Transaction not found exception
+    """
+
+
+# end of not found exceptions
+
+# start of other exceptions
+
+
+class AccountFrozen(AccountException):
+    """
+    Account frozen exception (will be raised when trying to perform an action on a frozen account)
+    """

…ebot_plugin_value/migrations/__init__,py …ebot_plugin_value/migrations/__init__.pynonebot_plugin_value/migrations/__init__,py renamed to nonebot_plugin_value/migrations/__init__.py nonebot_plugin_value/migrations/__init__,py renamed to nonebot_plugin_value/migrations/__init__.py

@@ -6,6 +6,13 @@
 from nonebot_plugin_orm import AsyncSession
 from sqlalchemy import insert, select, update
 
+from .exception import (
+    AccountFrozen,
+    AccountNotFound,
+    CurrencyNotFound,
+    TransactionException,
+    TransactionNotFound,
+)
 from .models.balance import Transaction, UserAccount
 from .models.currency import CurrencyMeta
 from .pyd_models.currency_pyd import CurrencyData
@@ -96,7 +103,7 @@ async def remove_currency(self, currency_id: str):
                 )
             ).scalar_one_or_none()
             if not currency:
-                raise ValueError("Currency not found")
+                raise CurrencyNotFound(f"Currency {currency_id} not found")
             await session.delete(currency)
             users = await session.execute(
                 select(UserAccount)
@@ -124,7 +131,7 @@ async def get_or_create_account(
             result = await session.execute(stmt)
             currency = result.scalar_one_or_none()
             if currency is None:
-                raise ValueError(f"Currency {currency_id} not found")
+                raise CurrencyNotFound(f"Currency {currency_id} not found")
 
             # 检查账户是否存在
             stmt = (
@@ -158,6 +165,39 @@ async def get_or_create_account(
             session.add(account)
             return account
 
+    async def set_account_frozen(
+        self,
+        account_id: str,
+        currency_id: str,
+        frozen: bool,
+    ) -> None:
+        """设置账户冻结状态"""
+        async with self.session as session:
+            account = await self.get_or_create_account(account_id, currency_id)
+            session.add(account)
+            account.frozen = frozen
+            await session.commit()
+
+    async def set_frozen_all(self, account_id: str, frozen: bool):
+        async with self.session as session:
+            result = await session.execute(
+                select(UserAccount).where(UserAccount.id == account_id)
+            )
+            accounts = result.scalars().all()
+            session.add_all(accounts)
+            for account in accounts:
+                account.frozen = frozen
+            await session.commit()
+
+    async def is_account_frozen(
+        self,
+        account_id: str,
+        currency_id: str,
+    ) -> bool:
+        """判断账户是否冻结"""
+        async with self.session:
+            return (await self.get_or_create_account(account_id, currency_id)).frozen
+
     async def get_balance(self, account_id: str, currency_id: str) -> float | None:
         """获取账户余额"""
         uni_id = get_uni_id(account_id, currency_id)
@@ -180,16 +220,21 @@ async def update_balance(
             ).scalar_one_or_none()
 
             if account is None:
-                raise ValueError("Account not found")
+                raise AccountNotFound("Account not found")
             session.add(account)
 
+            if account.frozen:
+                raise AccountFrozen(
+                    f"Account {account_id} on currency {currency_id} is frozen"
+                )
+
             # 获取货币规则
             currency = await session.get(CurrencyMeta, account.currency_id)
             session.add(currency)
 
             # 负余额检查
             if amount < 0 and not getattr(currency, "allow_negative", False):
-                raise ValueError("Insufficient funds")
+                raise TransactionException("Insufficient funds")
 
             # 记录原始余额
             old_balance = account.balance
@@ -235,7 +280,7 @@ async def remove_account(self, account_id: str, currency_id: str | None = None):
                 )
             accounts = (await session.execute(stmt)).scalars().all()
             if not accounts:
-                raise ValueError("Account not found")
+                raise AccountNotFound("Account not found")
             for account in accounts:
                 await session.delete(account)
             await session.commit()
@@ -337,6 +382,6 @@ async def remove_transaction(self, transaction_id: str) -> None:
                 )
             ).scalar_one_or_none()
             if not transaction:
-                raise ValueError("Transaction not found")
+                raise TransactionNotFound("Transaction not found")
             await session.delete(transaction)
             await session.commit()