python-ddd-framework 0.3.2__py3-none-any.whl → 0.4.0__py3-none-any.whl

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/domain/services/order_approval_service.py.jinja

@@ -0,0 +1,23 @@
+"""审批设置属于跨对象的领域策略；订单自身仍拥有状态转换规则。"""
+
+from uuid import UUID
+
+from modules.{{ cookiecutter.module_name }}.domain.entities.order import Order
+from modules.{{ cookiecutter.module_name }}.domain.settings.approval_settings import APPROVAL_ENABLED
+from modules.{{ cookiecutter.module_name }}.domain_shared.errors.order_errors import APPROVAL_DISABLED
+
+from python_ddd_framework import DomainService, ValidationEnabled
+from python_ddd_framework.errors import BusinessError
+from python_ddd_framework.settings import SettingProvider
+
+
+class OrderApprovalService(DomainService, ValidationEnabled):
+    def __init__(self, settings: SettingProvider) -> None:
+        self._settings = settings
+
+    async def approve(self, order: Order, *, user_id: UUID | None = None) -> None:
+        # 业务扩展：依赖设置、仓储或多个聚合的规则写在领域服务；不接收 HTTP DTO。
+        # 聚合仍保证不能重复审批；保存和提交由调用方完成，失败才能整体回滚。
+        if not await self._settings.get(APPROVAL_ENABLED):
+            raise BusinessError(APPROVAL_DISABLED)
+        order.approve(user_id=user_id)

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/domain/settings/__init__.py.jinja

@@ -0,0 +1 @@
+"""所属能力的实现或契约。"""

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/domain/{settings.py.jinja → settings/approval_settings.py.jinja}

@@ -1,16 +1,17 @@
 """设置默认值属于领域，业务通过 SettingProvider 获取冻结读取视图。"""
 
+from modules.{{ cookiecutter.module_name }}.domain_shared.constants.order_constants import MODULE_NAME
+
 from python_ddd_framework.settings import (
     SettingDefinition,
     SettingDefinitionContext,
     SettingDefinitionProvider,
 )
 
-from ..domain_shared.definitions import MODULE_NAME
-
 APPROVAL_ENABLED = SettingDefinition(f"{MODULE_NAME}.approval_enabled", bool, default=True)
 
 
 class {{ cookiecutter.class_prefix }}SettingDefinitionProvider(SettingDefinitionProvider):
     def define(self, context: SettingDefinitionContext) -> None:
+        # 定义扩展：在这里发布本模块的动态业务设置；类型/默认值归 SettingDefinition，读取走 SettingProvider。
         context.add(APPROVAL_ENABLED)

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/domain/value_objects/__init__.py.jinja

@@ -0,0 +1 @@
+"""所属能力的实现或契约。"""

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/domain/value_objects/order_title.py.jinja

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from modules.{{ cookiecutter.module_name }}.domain_shared.constants.order_constants import TITLE_MAX_LENGTH
+from pydantic import Field
+
+from python_ddd_framework import ValueObject
+
+
+class OrderTitle(ValueObject):
+    value: str = Field(min_length=1, max_length=TITLE_MAX_LENGTH)

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/domain_shared/constants/__init__.py.jinja

@@ -0,0 +1 @@
+"""所属能力的实现或契约。"""

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/domain_shared/constants/order_constants.py.jinja

@@ -0,0 +1,3 @@
+MODULE_NAME = "{{ cookiecutter.module_name }}"
+
+TITLE_MAX_LENGTH = 120

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/domain_shared/enums/__init__.py.jinja

@@ -0,0 +1 @@
+"""所属能力的实现或契约。"""

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/domain_shared/enums/order_status.py.jinja

@@ -0,0 +1,6 @@
+from enum import Enum
+
+
+class OrderStatus(str, Enum):
+    PENDING = "pending"
+    APPROVED = "approved"

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/domain_shared/errors/__init__.py.jinja

@@ -0,0 +1 @@
+"""所属能力的实现或契约。"""

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/domain_shared/errors/order_errors.py.jinja

@@ -0,0 +1,11 @@
+from modules.{{ cookiecutter.module_name }}.domain_shared.constants.order_constants import MODULE_NAME
+
+from python_ddd_framework.errors import BusinessErrorDefinition
+
+ALREADY_APPROVED = BusinessErrorDefinition(
+    f"{MODULE_NAME}.already_approved", "Order is already approved"
+)
+
+APPROVAL_DISABLED = BusinessErrorDefinition(
+    f"{MODULE_NAME}.approval_disabled", "Order approval is disabled"
+)

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/domain_shared/messages/__init__.py.jinja

@@ -0,0 +1 @@
+"""所属能力的实现或契约。"""

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/domain_shared/messages/order_messages.py.jinja

@@ -0,0 +1,26 @@
+from uuid import UUID
+
+from modules.{{ cookiecutter.module_name }}.domain_shared.constants.order_constants import MODULE_NAME
+from modules.{{ cookiecutter.module_name }}.domain_shared.enums.order_status import OrderStatus
+from pydantic import BaseModel, ConfigDict
+
+from python_ddd_framework.realtime import RealtimeMessage
+
+
+class OrderChangedMessage(RealtimeMessage):
+    message_type = f"{MODULE_NAME}.changed.v1"
+    id: UUID
+    status: OrderStatus
+
+
+class OrderSnapshotItem(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    id: UUID
+    title: str
+    status: OrderStatus
+    version: int
+
+
+class OrderSnapshotMessage(RealtimeMessage):
+    message_type = f"{MODULE_NAME}.snapshot.v1"
+    orders: tuple[OrderSnapshotItem, ...]

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/domain_shared/messages/order_observation.py.jinja

@@ -0,0 +1,13 @@
+"""外部集成的可覆盖快照；不承载命令、结果或领域事件。"""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class OrderObservation:
+    source: str
+    count: int
+
+
+def observation_identity(message: OrderObservation) -> str:
+    return message.source

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/domain_shared/module.py.jinja

@@ -1,7 +1,46 @@
 """共享层只发布业务常量与权限，不引用基础设施。"""
 
-from python_ddd_framework import AppModule
+from python_ddd_framework import (
+    AppModule,
+    AuthorizationModule,
+    ConfigureContext,
+    InitializeContext,
+    PostConfigureContext,
+    PostInitializeContext,
+    PreConfigureContext,
+    PreInitializeContext,
+    ShutdownContext,
+)
 
 
 class {{ cookiecutter.class_prefix }}DomainSharedModule(AppModule):
+    dependencies = (AuthorizationModule,)
     scan_packages = (__package__,)
+
+    def pre_configure(self, context: PreConfigureContext) -> None:
+        # 贡献影响后续注册的 PreOptions；此阶段不启动资源。
+        pass
+
+    def configure(self, context: ConfigureContext) -> None:
+        # 注册服务和普通 Options；业务执行留在所属能力。
+        pass
+
+    def post_configure(self, context: PostConfigureContext) -> None:
+        # 读取已冻结 PreOptions，补充 Options 或覆盖已有服务注册。
+        pass
+
+    async def pre_initialize(self, context: PreInitializeContext) -> None:
+        # 异步初始化前置条件；依赖模块在同一阶段先完成。
+        pass
+
+    async def initialize(self, context: InitializeContext) -> None:
+        # 初始化本模块资源；不手工启动框架管理的 Worker 或 HostedService。
+        pass
+
+    async def post_initialize(self, context: PostInitializeContext) -> None:
+        # 完成初始化收尾；应用此时尚未对外就绪。
+        pass
+
+    async def shutdown(self, context: ShutdownContext) -> None:
+        # 逆依赖关闭本模块拥有的资源；返回前等待清理结束。
+        pass

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/domain_shared/permissions/__init__.py.jinja

@@ -0,0 +1 @@
+"""所属能力的实现或契约。"""

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/domain_shared/{permissions.py.jinja → permissions/order_permission_provider.py.jinja}

@@ -1,15 +1,19 @@
 """权限名称由共享定义拥有；Provider 仅发布定义。"""
 
+from modules.{{ cookiecutter.module_name }}.domain_shared.permissions.order_permissions import (
+    ORDERS_READ,
+    ORDERS_WRITE,
+)
+
 from python_ddd_framework import (
     PermissionDefinition,
     PermissionDefinitionContext,
     PermissionDefinitionProvider,
 )
 
-from .definitions import ORDERS_READ, ORDERS_WRITE
-
 
 class {{ cookiecutter.class_prefix }}PermissionDefinitionProvider(PermissionDefinitionProvider):
     def define(self, context: PermissionDefinitionContext) -> None:
+        # 定义扩展：在这里发布自己的业务权限，名称统一放在共享定义；实际授权检查声明在服务/端点上。
         context.add(PermissionDefinition(ORDERS_READ, "Read orders"))
         context.add(PermissionDefinition(ORDERS_WRITE, "Create and approve orders"))

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/domain_shared/permissions/order_permissions.py.jinja

@@ -0,0 +1,7 @@
+from modules.{{ cookiecutter.module_name }}.domain_shared.constants.order_constants import MODULE_NAME
+
+from python_ddd_framework import PermissionName
+
+ORDERS_READ = PermissionName(f"{MODULE_NAME}.read")
+
+ORDERS_WRITE = PermissionName(f"{MODULE_NAME}.write")

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/domain_shared/value_objects/__init__.py.jinja

@@ -0,0 +1 @@
+"""跨层共享的不可变领域值；不依赖 Domain 实现或 DTO。"""

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/domain_shared/value_objects/money.py.jinja

@@ -0,0 +1,18 @@
+"""Shared immutable monetary value for domain objects and public DTOs."""
+
+from decimal import Decimal
+
+from pydantic import Field, field_validator
+
+from python_ddd_framework import ValueObject
+
+
+class Money(ValueObject):
+    amount: Decimal = Field(ge=0, max_digits=12, decimal_places=2)
+    currency: str = Field(default="CNY", pattern=r"^[A-Z]{3}$")
+
+    @field_validator("amount")
+    @classmethod
+    def normalize_amount(cls, value: Decimal) -> Decimal:
+        # 与两位小数的持久价格一致，避免写入前后公开 DTO 表达不同。
+        return value.quantize(Decimal("0.01"))

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/http_api/filters/__init__.py.jinja

@@ -0,0 +1 @@
+"""所属能力的实现或契约。"""

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/http_api/filters/export_filter.py.jinja

@@ -0,0 +1,15 @@
+import logging
+from collections.abc import Awaitable, Callable
+
+from python_ddd_framework.fastapi import ActionFilterContext
+
+
+class ExportFilter:
+    async def invoke(
+        self, context: ActionFilterContext, next_action: Callable[[], Awaitable[object]]
+    ) -> object:
+        # 管线扩展：在这里添加端点执行前/后的 HTTP 处理；领域规则仍由调用的应用服务/聚合负责。
+        # Filter 的作用域只覆盖已绑定参数到响应准备；不假定流传输已经结束。
+        result = await next_action()
+        logging.getLogger(__name__).info("File response prepared")
+        return result

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/http_api/models/__init__.py.jinja

@@ -0,0 +1 @@
+"""所属能力的实现或契约。"""

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/http_api/models/refresh_orders.py.jinja

@@ -0,0 +1,5 @@
+from pydantic import BaseModel, ConfigDict
+
+
+class RefreshOrders(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/http_api/module.py.jinja

@@ -1,25 +1,103 @@
 """自动服务暴露与手写路由共用正式认证／REQUEST 管线。"""
 
 from dishka import Scope
-from python_ddd_framework import AppModule, ConfigureContext
+from modules.{{ cookiecutter.module_name }}.application_contracts.module import (
+    {{ cookiecutter.class_prefix }}ApplicationContractsModule,
+)
+from modules.{{ cookiecutter.module_name }}.application_contracts.services.order_approval_service import (
+    {{ cookiecutter.class_prefix }}ApprovalApplicationService,
+)
+from modules.{{ cookiecutter.module_name }}.application_contracts.services.order_management_service import (
+    {{ cookiecutter.class_prefix }}ManagementApplicationService,
+)
+from modules.{{ cookiecutter.module_name }}.application_contracts.services.order_query_service import (
+    {{ cookiecutter.class_prefix }}QueryApplicationService,
+)
+from modules.{{ cookiecutter.module_name }}.http_api.filters.export_filter import ExportFilter
+from modules.{{ cookiecutter.module_name }}.http_api.routers.order_files import router as files_router
+from modules.{{ cookiecutter.module_name }}.http_api.websockets.order_socket import router as realtime_router
+
+from python_ddd_framework import (
+    AppModule,
+    ConfigureContext,
+    InitializeContext,
+    PostConfigureContext,
+    PostInitializeContext,
+    PreConfigureContext,
+    PreInitializeContext,
+    ShutdownContext,
+)
 from python_ddd_framework.fastapi import (
+    ApplicationServiceRouteOverride,
     FastApiRealtimeModule,
     contributes_routers,
     exposes_application_services,
 )
 
-from ..application_contracts.module import {{ cookiecutter.class_prefix }}ApplicationContractsModule
-from .files import ExportFilter
-from .files import router as files_router
-from .realtime import router as realtime_router
-
 
 @contributes_routers(files_router, realtime_router)
 @exposes_application_services(
     {{ cookiecutter.class_prefix }}ApplicationContractsModule,
+    overrides=(
+        ApplicationServiceRouteOverride(
+            service={{ cookiecutter.class_prefix }}QueryApplicationService,
+            method={{ cookiecutter.class_prefix }}QueryApplicationService.get,
+            path="{{ cookiecutter.http_service_path }}/{id}",
+            operation_id="{{ cookiecutter.http_operation_prefix }}get",
+        ),
+        ApplicationServiceRouteOverride(
+            service={{ cookiecutter.class_prefix }}QueryApplicationService,
+            method={{ cookiecutter.class_prefix }}QueryApplicationService.get_list,
+            path="{{ cookiecutter.http_service_path }}",
+            operation_id="{{ cookiecutter.http_operation_prefix }}get_list",
+        ),
+        ApplicationServiceRouteOverride(
+            service={{ cookiecutter.class_prefix }}ManagementApplicationService,
+            method={{ cookiecutter.class_prefix }}ManagementApplicationService.create,
+            path="{{ cookiecutter.http_service_path }}",
+            operation_id="{{ cookiecutter.http_operation_prefix }}create",
+        ),
+        ApplicationServiceRouteOverride(
+            service={{ cookiecutter.class_prefix }}ApprovalApplicationService,
+            method={{ cookiecutter.class_prefix }}ApprovalApplicationService.approve,
+            path="{{ cookiecutter.http_service_path }}/{id}/approve",
+            operation_id="{{ cookiecutter.http_operation_prefix }}approve",
+        ),
+        ApplicationServiceRouteOverride(
+            service={{ cookiecutter.class_prefix }}ApprovalApplicationService,
+            method={{ cookiecutter.class_prefix }}ApprovalApplicationService.queue_approval,
+            path="{{ cookiecutter.http_service_path }}/{id}/queue-approval",
+            operation_id="{{ cookiecutter.http_operation_prefix }}queue_approval",
+        ),
+    ),
 )
 class {{ cookiecutter.class_prefix }}HttpApiModule(AppModule):
-    dependencies = ({{ cookiecutter.class_prefix }}ApplicationContractsModule, FastApiRealtimeModule)
+    dependencies = (FastApiRealtimeModule,)
+
+    def pre_configure(self, context: PreConfigureContext) -> None:
+        # 贡献影响后续注册的 PreOptions；此阶段不启动资源。
+        pass
 
     def configure(self, context: ConfigureContext) -> None:
+        # 组装扩展：在这里注册 HTTP 层自己的 Filter 等依赖；新路由通过上方 Module 声明接入。
         context.services.add_scoped(ExportFilter, scope=Scope.REQUEST)
+
+    def post_configure(self, context: PostConfigureContext) -> None:
+        # 读取已冻结 PreOptions，补充 Options 或覆盖已有服务注册。
+        pass
+
+    async def pre_initialize(self, context: PreInitializeContext) -> None:
+        # 异步初始化前置条件；依赖模块在同一阶段先完成。
+        pass
+
+    async def initialize(self, context: InitializeContext) -> None:
+        # 初始化本模块资源；不手工启动框架管理的 Worker 或 HostedService。
+        pass
+
+    async def post_initialize(self, context: PostInitializeContext) -> None:
+        # 完成初始化收尾；应用此时尚未对外就绪。
+        pass
+
+    async def shutdown(self, context: ShutdownContext) -> None:
+        # 逆依赖关闭本模块拥有的资源；返回前等待清理结束。
+        pass

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/http_api/routers/__init__.py.jinja

@@ -0,0 +1 @@
+"""所属能力的实现或契约。"""

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/http_api/{files.py.jinja → routers/order_files.py.jinja}

@@ -1,40 +1,40 @@
-"""原生上传与流响应；业务查询在返回响应前完成，不跨网络发送持有事务。"""
-
 import asyncio
 import hashlib
 import logging
-from collections.abc import AsyncIterator, Awaitable, Callable
+from collections.abc import AsyncIterator
 from typing import Annotated
 from uuid import UUID
 
 from fastapi import File, Form, UploadFile
-from python_ddd_framework.authorization import authorize
-from python_ddd_framework.fastapi import ActionFilterContext, HttpRouter, service_filter
+from modules.{{ cookiecutter.module_name }}.application_contracts.inputs.create_order import CreateOrder
+from modules.{{ cookiecutter.module_name }}.application_contracts.services.order_management_service import (
+    {{ cookiecutter.class_prefix }}ManagementApplicationService,
+)
+from modules.{{ cookiecutter.module_name }}.application_contracts.services.order_query_service import (
+    {{ cookiecutter.class_prefix }}QueryApplicationService,
+)
+from modules.{{ cookiecutter.module_name }}.domain_shared.constants.order_constants import MODULE_NAME
+from modules.{{ cookiecutter.module_name }}.domain_shared.permissions.order_permissions import (
+    ORDERS_READ,
+    ORDERS_WRITE,
+)
+from modules.{{ cookiecutter.module_name }}.http_api.filters.export_filter import ExportFilter
 from starlette.responses import Response, StreamingResponse
 
-from ..application_contracts.orders import CreateOrder, {{ cookiecutter.class_prefix }}ApplicationService
-from ..domain_shared.definitions import MODULE_NAME, ORDERS_READ, ORDERS_WRITE
+from python_ddd_framework.authorization import authorize
+from python_ddd_framework.fastapi import HttpRouter, service_filter
 
 router = HttpRouter(use_api_prefix=True, prefix=f"/{MODULE_NAME}/files", permissions=(ORDERS_READ,))
 
 
-class ExportFilter:
-    async def invoke(
-        self, context: ActionFilterContext, next_action: Callable[[], Awaitable[object]]
-    ) -> object:
-        # Filter 的作用域只覆盖已绑定参数到响应准备；不假定流传输已经结束。
-        result = await next_action()
-        logging.getLogger(__name__).info("File response prepared")
-        return result
-
-
 @router.post("/upload", status_code=201)
 @authorize(ORDERS_WRITE)
 async def upload(
-    service: {{ cookiecutter.class_prefix }}ApplicationService,
+    service: {{ cookiecutter.class_prefix }}ManagementApplicationService,
     title: Annotated[str, Form()],
     file: Annotated[UploadFile, File()],
 ) -> dict[str, object]:
+    # 接口扩展：在这里解析上传内容并组装业务命令，交给应用服务处理；当前只演示创建订单及计算摘要。
     # File/Form 使用框架读取期限额及原生 parser；UploadFile 资源由 REQUEST 关闭。
     content = await file.read()
     order = await service.create(CreateOrder(title=title))
@@ -47,7 +47,8 @@ async def upload(
 
 @router.get("/{id}/download")
 @service_filter(ExportFilter)
-async def download(id: UUID, service: {{ cookiecutter.class_prefix }}ApplicationService) -> Response:
+async def download(id: UUID, service: {{ cookiecutter.class_prefix }}QueryApplicationService) -> Response:
+    # 接口扩展：通过服务查询已授权的数据后，在这里转换为实际下载格式、文件名和媒体类型。
     order = await service.get(id)
     return Response(
         order.model_dump_json(),
@@ -58,10 +59,12 @@ async def download(id: UUID, service: {{ cookiecutter.class_prefix }}Application
 
 @router.get("/export/stream")
 @service_filter(ExportFilter)
-async def export(service: {{ cookiecutter.class_prefix }}ApplicationService) -> StreamingResponse:
+async def export(service: {{ cookiecutter.class_prefix }}QueryApplicationService) -> StreamingResponse:
+    # 接口扩展：这里准备导出数据，下面的 producer 负责编码输出；不要让业务事务跨越网络发送。
     orders = await service.get_list()
 
     async def produce() -> AsyncIterator[bytes]:
+        # 输出扩展：将 JSON 行替换为实际流格式；大数据分批读取须各自完成短 UoW 后再 yield。
         try:
             for order in orders:
                 yield (order.model_dump_json() + "\n").encode()

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/http_api/websockets/__init__.py.jinja

@@ -0,0 +1 @@
+"""所属能力的实现或契约。"""

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/http_api/websockets/order_socket.py.jinja

@@ -0,0 +1,44 @@
+from typing import Annotated
+
+from fastapi import APIRouter, Depends
+from modules.{{ cookiecutter.module_name }}.application_contracts.services.order_query_service import (
+    {{ cookiecutter.class_prefix }}QueryApplicationService,
+)
+from modules.{{ cookiecutter.module_name }}.domain_shared.constants.order_constants import MODULE_NAME
+from modules.{{ cookiecutter.module_name }}.domain_shared.messages.order_messages import (
+    OrderSnapshotItem,
+    OrderSnapshotMessage,
+)
+from modules.{{ cookiecutter.module_name }}.http_api.models.refresh_orders import RefreshOrders
+from starlette.websockets import WebSocketDisconnect
+
+from python_ddd_framework import FrameworkError
+from python_ddd_framework.fastapi import WebSocketConnection, websocket_connection
+
+router = APIRouter()
+
+
+@router.websocket(f"/ws/{MODULE_NAME}")
+async def orders_socket(
+    connection: Annotated[WebSocketConnection, Depends(websocket_connection)],
+) -> None:
+    # 接口扩展：这里定义“查询快照 → 发送消息 → 接收下一条命令”的交互，替换消息 DTO 和业务调用。
+    # 每次业务操作仍经 connection.invoke 进入授权/事务管线，不在连接期间保留 Session 或聚合实例。
+    try:
+        while True:
+            orders = await connection.invoke({{ cookiecutter.class_prefix }}QueryApplicationService.get_list)
+            await connection.send(
+                OrderSnapshotMessage(
+                    orders=tuple(
+                        OrderSnapshotItem(
+                            id=item.id, title=item.title, status=item.status, version=item.version
+                        )
+                        for item in orders
+                    )
+                ),
+            )
+            await connection.receive(RefreshOrders)
+    except WebSocketDisconnect:
+        return
+    except FrameworkError as error:
+        await connection.send_problem(error)

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/sqlalchemy/migrations/__init__.py.jinja

@@ -1 +1 @@
-"""初始无业务 revision；执行 pddd db revision --module {{ cookiecutter.module_name }} 后人工审查。"""
+"""初始无业务 revision；执行 pddd db revision --module orders 后人工审查。"""

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/sqlalchemy/models/__init__.py.jinja

@@ -1,7 +1 @@
-"""本模块模型的原生 MetaData owner；具体模型由 Module 的包声明加载。"""
-
-from sqlalchemy.orm import DeclarativeBase
-
-
-class {{ cookiecutter.class_prefix }}Base(DeclarativeBase):
-    pass
+"""ORM 模型包；metadata owner 位于 base。"""

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/sqlalchemy/models/base.py.jinja

@@ -0,0 +1,7 @@
+"""Native metadata owner for models discovered by this module."""
+
+from sqlalchemy.orm import DeclarativeBase
+
+
+class {{ cookiecutter.class_prefix }}Base(DeclarativeBase):
+    pass

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/sqlalchemy/models/{orders.py.jinja → order_model.py.jinja}

@@ -2,12 +2,16 @@
 
 from uuid import UUID
 
-from python_ddd_framework.sqlalchemy import AuditedEntityMixin
+from modules.{{ cookiecutter.module_name }}.domain_shared.constants.order_constants import (
+    MODULE_NAME,
+    TITLE_MAX_LENGTH,
+)
+from modules.{{ cookiecutter.module_name }}.domain_shared.enums.order_status import OrderStatus
+from modules.{{ cookiecutter.module_name }}.sqlalchemy.models.base import {{ cookiecutter.class_prefix }}Base
 from sqlalchemy import Integer, String, Uuid
 from sqlalchemy.orm import Mapped, mapped_column
 
-from ...domain_shared.definitions import MODULE_NAME, TITLE_MAX_LENGTH, OrderStatus
-from . import {{ cookiecutter.class_prefix }}Base
+from python_ddd_framework.sqlalchemy import AuditedEntityMixin
 
 
 class OrderRow(AuditedEntityMixin, {{ cookiecutter.class_prefix }}Base):

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/sqlalchemy/module.py.jinja

@@ -1,16 +1,25 @@
 """provider 依赖领域契约；Host 显式选择此实现。"""
 
-from python_ddd_framework import AppModule
+from modules.{{ cookiecutter.module_name }}.domain.module import {{ cookiecutter.class_prefix }}DomainModule
+from modules.{{ cookiecutter.module_name }}.domain_shared.constants.order_constants import MODULE_NAME
+from modules.{{ cookiecutter.module_name }}.sqlalchemy.models.base import {{ cookiecutter.class_prefix }}Base
+
+from python_ddd_framework import (
+    AppModule,
+    ConfigureContext,
+    InitializeContext,
+    PostConfigureContext,
+    PostInitializeContext,
+    PreConfigureContext,
+    PreInitializeContext,
+    ShutdownContext,
+)
 from python_ddd_framework.sqlalchemy import (
     SqlAlchemyModelRegistration,
     SqlAlchemyPersistenceModule,
     contributes_sqlalchemy_models,
 )
 
-from ..domain.module import {{ cookiecutter.class_prefix }}DomainModule
-from ..domain_shared.definitions import MODULE_NAME
-from .models import {{ cookiecutter.class_prefix }}Base
-
 
 @contributes_sqlalchemy_models(
     SqlAlchemyModelRegistration.from_package(
@@ -24,3 +33,31 @@ class {{ cookiecutter.class_prefix }}SqlAlchemyModule(AppModule):
     dependencies = ({{ cookiecutter.class_prefix }}DomainModule, SqlAlchemyPersistenceModule)
 
     scan_packages = (__package__ + ".repositories",)
+
+    def pre_configure(self, context: PreConfigureContext) -> None:
+        # 贡献影响后续注册的 PreOptions；此阶段不启动资源。
+        pass
+
+    def configure(self, context: ConfigureContext) -> None:
+        # 注册服务和普通 Options；业务执行留在所属能力。
+        pass
+
+    def post_configure(self, context: PostConfigureContext) -> None:
+        # 读取已冻结 PreOptions，补充 Options 或覆盖已有服务注册。
+        pass
+
+    async def pre_initialize(self, context: PreInitializeContext) -> None:
+        # 异步初始化前置条件；依赖模块在同一阶段先完成。
+        pass
+
+    async def initialize(self, context: InitializeContext) -> None:
+        # 初始化本模块资源；不手工启动框架管理的 Worker 或 HostedService。
+        pass
+
+    async def post_initialize(self, context: PostInitializeContext) -> None:
+        # 完成初始化收尾；应用此时尚未对外就绪。
+        pass
+
+    async def shutdown(self, context: ShutdownContext) -> None:
+        # 逆依赖关闭本模块拥有的资源；返回前等待清理结束。
+        pass