aury-boot 0.0.28__py3-none-any.whl → 0.0.29__py3-none-any.whl

aury/boot/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.0.28'
-__version_tuple__ = version_tuple = (0, 0, 28)
+__version__ = version = '0.0.29'
+__version_tuple__ = version_tuple = (0, 0, 29)
 
 __commit_id__ = commit_id = None

aury/boot/commands/templates/project/AGENTS.md.tpl

@@ -164,15 +164,25 @@ class User(Base): ...
 - 写操作**必须**使用 `@transactional` 装饰器
 - 只读操作可以不加事务装饰器
 - 跨 Service 调用通过共享 session 实现事务共享
+- **后台任务必须**使用 `@isolated_task` 装饰器
 
 ```python
-from aury.boot.domain.transaction import transactional
+from aury.boot.domain.transaction import transactional, isolated_task
 
 class UserService(BaseService):
     @transactional
     async def create(self, data: UserCreate) -> User:
         # 自动事务管理
         return await self.repo.create(data.model_dump())
+
+
+# 后台任务必须加 @isolated_task，否则事务不会提交
+@isolated_task
+async def background_upload(space_id: int, url: str):
+    async with db.session() as session:
+        async with transactional_context(session):
+            repo = SpaceRepository(session, Space)
+            await repo.update(...)
 ```
 
 ### Manager API 规范

aury/boot/commands/templates/project/aury_docs/03-service.md.tpl

@@ -396,3 +396,63 @@ DATABASE_ISOLATION_LEVEL=REPEATABLE READ
 - 大多数场景：`READ COMMITTED`（平衡性能和一致性）
 - 报表/统计查询：`REPEATABLE READ`（保证读取一致性）
 - 金融交易：`SERIALIZABLE`（最强一致性，性能较低）
+
+### 3.12 后台任务事务隔离（重要）
+
+在 `@transactional` 装饰的 Service 方法中 spawn 后台任务时，**必须**使用 `@isolated_task` 或 `isolated_context`，否则事务不会提交。
+
+**问题背景**：
+`asyncio.create_task()` 会继承父协程的 `contextvars`。如果父协程在 `@transactional` 中，子任务会继承事务深度标记，导致：
+- `auto_commit` 失效
+- `transactional_context` 也不会提交
+- session 关闭时数据被 rollback
+
+**解决方案 1：装饰器（推荐）**
+
+```python
+import asyncio
+from aury.boot.domain.transaction import isolated_task, transactional_context
+from aury.boot.infrastructure.database import DatabaseManager
+
+db = DatabaseManager.get_instance()
+
+
+@isolated_task
+async def upload_cover(space_id: int, cover_url: str):
+    """后台任务：上传封面。"""
+    async with db.session() as session:
+        async with transactional_context(session):
+            repo = SpaceRepository(session, Space)
+            space = await repo.get(space_id)
+            if space:
+                await repo.update(space, {{"cover": cover_url}})
+        # 现在会正常 commit
+
+
+class SpaceService(BaseService):
+    @transactional
+    async def create(self, data: SpaceCreate) -> Space:
+        space = await self.repo.create(data.model_dump())
+        
+        # spawn 后台任务
+        asyncio.create_task(upload_cover(space.id, data.cover_url))
+        
+        return space
+```
+
+**解决方案 2：上下文管理器**
+
+```python
+from aury.boot.domain.transaction import isolated_context
+
+async def background_job():
+    async with isolated_context():
+        async with db.session() as session:
+            async with transactional_context(session):
+                # 正常的事务处理
+                ...
+```
+
+**注意事项**：
+- 后台任务必须新开 session（`db.session()`），不能复用主请求的 `self.session`
+- 后台任务的事务与主请求独立，主请求回滚不影响后台任务

aury/boot/domain/transaction/__init__.py

@@ -390,11 +390,68 @@ def requires_transaction(func: Callable) -> Callable:
     return wrapper
 
 
+def isolated_task[T](func: Callable[..., T]) -> Callable[..., T]:
+    """后台任务隔离装饰器。
+    
+    重置事务上下文，避免从父协程继承 _transaction_depth 导致 auto_commit 失效。
+    
+    问题背景：
+        asyncio.create_task() 会继承父协程的 contextvars。如果父协程在 @transactional 中，
+        _transaction_depth > 0，子任务的 auto_commit 和 transactional_context 都会认为
+        "在事务中" 而跳过 commit，导致 session 关闭时 rollback。
+    
+    用法：
+        @isolated_task
+        async def upload_cover(space_id: int, cover_url: str):
+            async with db.session() as session:
+                async with transactional_context(session):
+                    repo = SpaceRepository(session, Space)
+                    space = await repo.get(space_id)
+                    await repo.update(space, {"cover": cover_url})
+                # 现在会正常 commit
+        
+        # 在 Service 中 spawn
+        asyncio.create_task(upload_cover(space.id, url))
+    """
+    @wraps(func)
+    async def wrapper(*args, **kwargs):
+        # 重置事务深度，让当前任务成为独立的事务上下文
+        token = _transaction_depth.set(0)
+        try:
+            return await func(*args, **kwargs)
+        finally:
+            _transaction_depth.reset(token)
+    
+    return wrapper
+
+
+@asynccontextmanager
+async def isolated_context() -> AsyncGenerator[None]:
+    """后台任务隔离上下文管理器。
+    
+    与 @isolated_task 作用相同，但用于上下文管理器形式。
+    
+    用法：
+        async def background_job():
+            async with isolated_context():
+                async with db.session() as session:
+                    async with transactional_context(session):
+                        ...
+    """
+    token = _transaction_depth.set(0)
+    try:
+        yield
+    finally:
+        _transaction_depth.reset(token)
+
+
 __all__ = [
     "TransactionManager",
     "TransactionRequiredError",
     "_transaction_depth",  # 内部使用，不对外文档化
     "ensure_transaction",
+    "isolated_context",
+    "isolated_task",
     "on_commit",
     "requires_transaction",
     "transactional",

{aury_boot-0.0.28.dist-info → aury_boot-0.0.29.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aury-boot
-Version: 0.0.28
+Version: 0.0.29
 Summary: Aury Boot - 基于 FastAPI 生态的企业级 API 开发框架
 Requires-Python: >=3.13
 Requires-Dist: alembic>=1.17.2

{aury_boot-0.0.28.dist-info → aury_boot-0.0.29.dist-info}/RECORD

@@ -1,5 +1,5 @@
 aury/boot/__init__.py,sha256=pCno-EInnpIBa1OtxNYF-JWf9j95Cd2h6vmu0xqa_-4,1791
-aury/boot/_version.py,sha256=rsZxmANBVfE-nN63y-ZZ_71Lkm6YP4u4TgVEBJV3mNM,706
+aury/boot/_version.py,sha256=p4kcB0BmpcnphBIseH7188jNCCOqFZSly7Pka9LrUDM,706
 aury/boot/application/__init__.py,sha256=0o_XmiwFCeAu06VHggS8I1e7_nSMoRq0Hcm0fYfCywU,3071
 aury/boot/application/adapter/__init__.py,sha256=e1bcSb1bxUMfofTwiCuHBZJk5-STkMCWPF2EJXHQ7UU,3976
 aury/boot/application/adapter/base.py,sha256=Ar_66fiHPDEmV-1DKnqXKwc53p3pozG31bgTJTEUriY,15763
@@ -61,7 +61,7 @@ aury/boot/commands/templates/generate/model.py.tpl,sha256=knFwMyGZ7wMpzH4_bQD_V1
 aury/boot/commands/templates/generate/repository.py.tpl,sha256=xoEg6lPAaLIRDeFy4I0FBsPPVLSy91h6xosAlaCL_mM,590
 aury/boot/commands/templates/generate/schema.py.tpl,sha256=HIaY5B0UG_S188nQLrZDEJ0q73WPdb7BmCdc0tseZA4,545
 aury/boot/commands/templates/generate/service.py.tpl,sha256=2hwQ8e4a5d_bIMx_jGDobdmKPMFLBlfQrQVQH4Ym5k4,1842
-aury/boot/commands/templates/project/AGENTS.md.tpl,sha256=-KrVhPqwVaf1IWRIl4L9Yb0LSRihq69ZaZ-ynnGM4W8,7882
+aury/boot/commands/templates/project/AGENTS.md.tpl,sha256=SpqoXZXCyWmitBV6Mt0VvXWdPZAZXsLoU-vDEyJyQDc,8269
 aury/boot/commands/templates/project/README.md.tpl,sha256=oCeBiukk6Pa3hrCKybkfM2sIRHsPZ15nlwuFTUSFDwY,2459
 aury/boot/commands/templates/project/admin_console_init.py.tpl,sha256=K81L14thyEhRA8lFCQJVZL_NU22-sBz0xS68MJPeoCo,1541
 aury/boot/commands/templates/project/config.py.tpl,sha256=H_B05FypBJxTjb7qIL91zC1C9e37Pk7C9gO0-b3CqNs,1009
@@ -71,7 +71,7 @@ aury/boot/commands/templates/project/main.py.tpl,sha256=Q61ve3o1VkNPv8wcQK7lUosn
 aury/boot/commands/templates/project/aury_docs/00-overview.md.tpl,sha256=8Aept3yEAe9cVdRvkddr_oEF-lr2riPXYRzBuw_6DBA,2138
 aury/boot/commands/templates/project/aury_docs/01-model.md.tpl,sha256=1mQ3hGDxqEZjev4CD5-3dzYRFVonPNcAaStI1UBEUyM,6811
 aury/boot/commands/templates/project/aury_docs/02-repository.md.tpl,sha256=JfUVdrIgW7_J6JGCcB-_uP_x-gCtjKiewwGv4Xr44QI,7803
-aury/boot/commands/templates/project/aury_docs/03-service.md.tpl,sha256=Dg_8RGSeRmmyQrhhpppEoxl-6C5pNe9M2OzVOl1kjSk,13102
+aury/boot/commands/templates/project/aury_docs/03-service.md.tpl,sha256=SgfPAgLVi_RbMjSAe-m49jQOIr6vfUT8VF2V1E-qa3w,15098
 aury/boot/commands/templates/project/aury_docs/04-schema.md.tpl,sha256=ZwwKhUbLI--PEEmwnuo2fIZrhCEZagBN6fRNDTFCnNk,2891
 aury/boot/commands/templates/project/aury_docs/05-api.md.tpl,sha256=oPzda3V6ZPDDEW-5MwyzmsMRuu5mXrsRGEq3lj0M-58,2997
 aury/boot/commands/templates/project/aury_docs/06-exception.md.tpl,sha256=Tv_Q5lsScHzvtcaFWmuQzN4YqvpcWZIdXS8jw99K29E,3340
@@ -130,7 +130,7 @@ aury/boot/domain/repository/interface.py,sha256=CmkiqVhhHPx_xcpuBCz11Vr26-govwYB
 aury/boot/domain/repository/query_builder.py,sha256=pFErMzsBql-T6gBX0S4FxIheCkNaGjpSewzcJ2DxrUU,10890
 aury/boot/domain/service/__init__.py,sha256=ZRotaBlqJXn7ebPTQjjoHtorpQREk8AgTD69UCcRd1k,118
 aury/boot/domain/service/base.py,sha256=6sN0nf8r5yUZsE6AcZOiOXFCqzb61oCxTfrWlqjIo9I,2035
-aury/boot/domain/transaction/__init__.py,sha256=Mk-J-5VOuuQ7NDW1DQmU-skCvcUOuEENfP_Ej3iZuJ8,13497
+aury/boot/domain/transaction/__init__.py,sha256=EKnjJ235SYjMCvGIuLVlTdYRzU35RxNMejRGUExYqqE,15488
 aury/boot/infrastructure/__init__.py,sha256=ppP1-suaDICMNvBSXj_4DVSH3h0D8e0qZhtENCr16m8,3007
 aury/boot/infrastructure/cache/__init__.py,sha256=G40uCkpJ1jSs2fc_CBDem73iQQzCcp-4GG1WpDJzwaA,658
 aury/boot/infrastructure/cache/backends.py,sha256=9QMQ8G9DtZgzVXZ_Ng7n1gXRu-_OQZgw4FHPOfr1qco,13585
@@ -192,7 +192,7 @@ aury/boot/testing/client.py,sha256=KOg1EemuIVsBG68G5y0DjSxZGcIQVdWQ4ASaHE3o1R0,4
 aury/boot/testing/factory.py,sha256=8GvwX9qIDu0L65gzJMlrWB0xbmJ-7zPHuwk3eECULcg,5185
 aury/boot/toolkit/__init__.py,sha256=AcyVb9fDf3CaEmJPNkWC4iGv32qCPyk4BuFKSuNiJRQ,334
 aury/boot/toolkit/http/__init__.py,sha256=zIPmpIZ9Qbqe25VmEr7jixoY2fkRbLm7NkCB9vKpg6I,11039
-aury_boot-0.0.28.dist-info/METADATA,sha256=7fabDsArEBQ_L5MoamQPJa9xmdi19-CLTSGG5YgPQPw,7695
-aury_boot-0.0.28.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-aury_boot-0.0.28.dist-info/entry_points.txt,sha256=f9KXEkDIGc0BGkgBvsNx_HMz9VhDjNxu26q00jUpDwQ,49
-aury_boot-0.0.28.dist-info/RECORD,,
+aury_boot-0.0.29.dist-info/METADATA,sha256=EaL1z6pE7pRmQ6YSAytT91uPj34ejAyuzeTpWWpAI-g,7695
+aury_boot-0.0.29.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+aury_boot-0.0.29.dist-info/entry_points.txt,sha256=f9KXEkDIGc0BGkgBvsNx_HMz9VhDjNxu26q00jUpDwQ,49
+aury_boot-0.0.29.dist-info/RECORD,,