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

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application/interceptors/order_timing_interceptor.py.jinja

@@ -0,0 +1,17 @@
+"""Record invocation timing through the framework's interceptor extension."""
+
+import logging
+from time import monotonic
+
+from python_ddd_framework import Interceptor, MethodInvocation
+
+
+class OrderTimingInterceptor(Interceptor):
+    async def intercept(self, invocation: MethodInvocation) -> object:
+        started = monotonic()
+        try:
+            return await invocation.proceed()
+        finally:
+            logging.getLogger(__name__).info(
+                "Order invocation completed in %.4fs", monotonic() - started
+            )

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

@@ -1,20 +1,115 @@
 """模块贡献自己的服务与任务；provider 选择留给 Host。"""
 
-from python_ddd_framework import AppModule, ConfigureContext
+from dishka import Scope
+from modules.{{ cookiecutter.module_name }}.application.background_workers.order_maintenance_worker import (
+    OrderMaintenanceWorker,
+)
+from modules.{{ cookiecutter.module_name }}.application.background_workers.order_statistics_worker import (
+    OrderStatisticsWorker,
+)
+from modules.{{ cookiecutter.module_name }}.application.interceptors.order_timing_interceptor import (
+    OrderTimingInterceptor,
+)
+from modules.{{ cookiecutter.module_name }}.application.options.order_options import {{ cookiecutter.class_prefix }}Options
+from modules.{{ cookiecutter.module_name }}.application.setting_handlers.approval_setting_observer import (
+    ApprovalSettingObserver,
+)
+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 }}.domain.module import {{ cookiecutter.class_prefix }}DomainModule
+from modules.{{ cookiecutter.module_name }}.domain.settings.approval_settings import APPROVAL_ENABLED
+from modules.{{ cookiecutter.module_name }}.domain_shared.constants.order_constants import MODULE_NAME
 
-from ..application_contracts.module import {{ cookiecutter.class_prefix }}ApplicationContractsModule
-from ..domain.module import {{ cookiecutter.class_prefix }}DomainModule
-from ..domain_shared.definitions import MODULE_NAME
-from .cache import ORDER_CACHE
-from .options import {{ cookiecutter.class_prefix }}Options
-from .tasks import OrderMaintenanceWorker, OrderStatisticsWorker
+from python_ddd_framework import (
+    BackgroundExecutionModule,
+    BackgroundWorkers,
+    BackgroundSchedules,
+    HostedServices,
+    LocalEventsModule,
+    SettingHandlers,
+    add_interceptor,
+    AppModule,
+    ConfigureContext,
+    InitializeContext,
+    InterceptionStage,
+    PostConfigureContext,
+    PostInitializeContext,
+    PreConfigureContext,
+    PreInitializeContext,
+    ShutdownContext,
+)
+from python_ddd_framework.caching.module import CachingModule
+from python_ddd_framework.settings import SettingHandlerDefinition
 
 
 class {{ cookiecutter.class_prefix }}ApplicationModule(AppModule):
-    dependencies = ({{ cookiecutter.class_prefix }}DomainModule, {{ cookiecutter.class_prefix }}ApplicationContractsModule)
+    dependencies = (
+        {{ cookiecutter.class_prefix }}DomainModule,
+        {{ cookiecutter.class_prefix }}ApplicationContractsModule,
+        CachingModule,
+        BackgroundExecutionModule,
+        LocalEventsModule,
+    )
     scan_packages = (__package__,)
-    cache_definitions = (ORDER_CACHE,)
-    background_workers = (OrderStatisticsWorker, OrderMaintenanceWorker)
+    background_workers = BackgroundWorkers((OrderStatisticsWorker, OrderMaintenanceWorker))
+
+    # 显式启用时导入 hosted_services.order_integration_service.OrderIntegrationService 并加入元组。
+    hosted_services = HostedServices(())
+    # 可选消息示例见项目 docs/development.md：选择 MessagingModule、声明 OrderObservation
+    # 通道并注册 hosted_services.order_observation_handler；不会自动替换线程 callback。
+    # 显式启用时导入 background_jobs.order_statistics.schedule.STATISTICS_SCHEDULE 并加入元组。
+    background_job_schedules = BackgroundSchedules(())
+    setting_handler_definitions = SettingHandlers((
+        SettingHandlerDefinition(APPROVAL_ENABLED, ApprovalSettingObserver),
+    ))
+
+    def pre_configure(self, context: PreConfigureContext) -> None:
+        # 贡献影响后续注册的 PreOptions；此阶段不启动资源。
+        pass
 
     def configure(self, context: ConfigureContext) -> None:
+        # 组装扩展：在这里声明本模块的启动 Options 和必要服务注册；业务执行代码放在应用服务中。
         context.configure({{ cookiecutter.class_prefix }}Options, section=MODULE_NAME)
+        context.services.add_scoped(OrderTimingInterceptor, scope=Scope.REQUEST)
+        add_interceptor(context,
+            OrderTimingInterceptor,
+            match=lambda method: (
+                method.service
+                in (
+                    {{ cookiecutter.class_prefix }}QueryApplicationService,
+                    {{ cookiecutter.class_prefix }}ManagementApplicationService,
+                    {{ cookiecutter.class_prefix }}ApprovalApplicationService,
+                )
+            ),
+            before=InterceptionStage.METHOD,
+        )
+
+    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}}/application/options/__init__.py.jinja

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

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application/{options.py.jinja → options/order_options.py.jinja}

@@ -1,4 +1,4 @@
-"""typed 业务配置；从本模块 YAML 节读取，非法值在 build 失败。"""
+"""Typed startup options bound to the module's configuration section."""
 
 from python_ddd_framework import BaseOptions
 

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application/services/__init__.py.jinja

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

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

@@ -0,0 +1,65 @@
+import logging
+from uuid import UUID
+
+from modules.{{ cookiecutter.module_name }}.application.background_jobs.order_approval.handler import (
+    ApprovalJob,
+)
+from modules.{{ cookiecutter.module_name }}.application.background_jobs.order_approval.payload import (
+    ApprovalPayload,
+)
+from modules.{{ cookiecutter.module_name }}.application_contracts.inputs.approve_order import ApproveOrder
+from modules.{{ cookiecutter.module_name }}.application_contracts.services.order_approval_service import (
+    {{ cookiecutter.class_prefix }}ApprovalApplicationService,
+)
+from modules.{{ cookiecutter.module_name }}.application_contracts.views.order_view import OrderView
+from modules.{{ cookiecutter.module_name }}.domain.repositories.order_repository import OrderRepository
+from modules.{{ cookiecutter.module_name }}.domain.services.order_approval_service import OrderApprovalService
+from modules.{{ cookiecutter.module_name }}.domain_shared.permissions.order_permissions import ORDERS_WRITE
+
+from python_ddd_framework import ApplicationService, CurrentUser
+from python_ddd_framework.authorization import authorize
+from python_ddd_framework.background_jobs import BackgroundJobEnqueuer
+from python_ddd_framework.errors.base import ResourceConflictError, ResourceNotFoundError
+from python_ddd_framework.fastapi import http
+
+logger = logging.getLogger(__name__)
+
+
+class _{{ cookiecutter.class_prefix }}ApprovalApplicationService(
+    ApplicationService, {{ cookiecutter.class_prefix }}ApprovalApplicationService
+):
+    def __init__(
+        self,
+        repository: OrderRepository,
+        user: CurrentUser,
+        jobs: BackgroundJobEnqueuer,
+        approval: OrderApprovalService,
+    ) -> None:
+        self._repository = repository
+        self._user = user
+        self._jobs = jobs
+        self._approval = approval
+
+    @authorize(ORDERS_WRITE)
+    async def approve(self, id: UUID, command: ApproveOrder) -> OrderView:
+        # 业务扩展：这里编排“读取聚合 → 核对版本 → 领域服务检查策略并执行动作 → 保存”。
+        # 审批只是动作示例；替换为入库等用例时保留权限/并发边界，把状态规则放进领域方法。
+        order = await self._repository.find(id)
+        if order is None:
+            raise ResourceNotFoundError("Order not found")
+        if order.version != command.expected_version:
+            raise ResourceConflictError("Order version changed")
+        await self._approval.approve(order, user_id=self._user.user_id)
+        await self._repository.save(order)
+        logger.info("Order approved")
+        return OrderView.model_validate(order)
+
+    @authorize(ORDERS_WRITE)
+    @http.post(status_code=202)
+    async def queue_approval(self, id: UUID) -> str:
+        # 业务扩展：这里校验入队条件并构造自己的任务载荷；实际后台业务写在对应 Job.execute。
+        # Job 和载荷类型一起替换，通过注入的入队服务调用，不自行创建消费者或数据库连接。
+        if await self._repository.find(id) is None:
+            raise ResourceNotFoundError("Order not found")
+        # 入队参与本方法原生事务；失败时订单业务与队列写入一起回滚。
+        return await self._jobs.enqueue(ApprovalJob, ApprovalPayload(order_id=id))

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application/services/order_management_service.py.jinja

@@ -0,0 +1,35 @@
+import logging
+from uuid import uuid4
+
+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.views.order_view import OrderView
+from modules.{{ cookiecutter.module_name }}.domain.entities.order import Order
+from modules.{{ cookiecutter.module_name }}.domain.repositories.order_repository import OrderRepository
+from modules.{{ cookiecutter.module_name }}.domain.value_objects.order_title import OrderTitle
+from modules.{{ cookiecutter.module_name }}.domain_shared.permissions.order_permissions import ORDERS_WRITE
+
+from python_ddd_framework import ApplicationService
+from python_ddd_framework.authorization import authorize
+from python_ddd_framework.fastapi import http
+
+logger = logging.getLogger(__name__)
+
+
+class _{{ cookiecutter.class_prefix }}ManagementApplicationService(
+    ApplicationService, {{ cookiecutter.class_prefix }}ManagementApplicationService
+):
+    def __init__(self, repository: OrderRepository) -> None:
+        self._repository = repository
+
+    @authorize(ORDERS_WRITE)
+    @http.post(status_code=201)
+    async def create(self, command: CreateOrder) -> OrderView:
+        # 业务扩展：这里编排创建用例，把输入 DTO 转成领域对象，调用领域方法，再交给仓储保存。
+        # 将 Order/OrderTitle 换成自己的聚合和值对象；领域规则写进聚合，事务由正式调用管线完成。
+        order = Order.create(uuid4(), OrderTitle(value=command.title))
+        await self._repository.save(order)
+        logger.info("Order created")
+        return OrderView.model_validate(order)

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application/services/order_query_service.py.jinja

@@ -0,0 +1,41 @@
+import logging
+from uuid import UUID
+
+from modules.{{ cookiecutter.module_name }}.application.caching.order_cache import OrderCacheItem
+from modules.{{ cookiecutter.module_name }}.application_contracts.services.order_query_service import (
+    {{ cookiecutter.class_prefix }}QueryApplicationService,
+)
+from modules.{{ cookiecutter.module_name }}.application_contracts.views.order_view import OrderView
+from modules.{{ cookiecutter.module_name }}.domain.repositories.order_repository import OrderRepository
+from modules.{{ cookiecutter.module_name }}.domain_shared.permissions.order_permissions import ORDERS_READ
+
+from python_ddd_framework import ApplicationService
+from python_ddd_framework.authorization import authorize
+from python_ddd_framework.caching import DistributedCache
+from python_ddd_framework.errors.base import ResourceNotFoundError
+
+logger = logging.getLogger(__name__)
+
+
+class _{{ cookiecutter.class_prefix }}QueryApplicationService(ApplicationService, {{ cookiecutter.class_prefix }}QueryApplicationService):
+    def __init__(self, repository: OrderRepository, cache: DistributedCache[OrderCacheItem]) -> None:
+        self._repository = repository
+        self._cache = cache
+
+    @authorize(ORDERS_READ)
+    async def get(self, id: UUID) -> OrderView:
+        # 业务扩展：这里组织单条查询及 DTO 返回；保留缓存时，定义和变更后的失效逻辑要一起调整。
+        cached = await self._cache.get(str(id))
+        if cached is not None:
+            return cached
+        order = await self._repository.find(id)
+        if order is None:
+            raise ResourceNotFoundError("Order not found")
+        view = OrderCacheItem.model_validate(order)
+        await self._cache.set(str(id), view)
+        return view
+
+    @authorize(ORDERS_READ)
+    async def get_list(self) -> tuple[OrderView, ...]:
+        # 业务扩展：这里接收实际业务的查询条件；需要筛选/分页时同步扩展 DTO 和仓储查询契约。
+        return tuple(OrderView.model_validate(order) for order in await self._repository.get_list())

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application/setting_handlers/__init__.py.jinja

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

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application/setting_handlers/approval_setting_observer.py.jinja

@@ -0,0 +1,17 @@
+"""Application-owned setting snapshot refreshed by the framework."""
+
+import logging
+import os
+
+from python_ddd_framework.settings import SettingSnapshot
+
+
+class ApprovalSettingObserver:
+    def __init__(self) -> None:
+        self.snapshot: SettingSnapshot[bool] | None = None
+
+    async def apply(self, snapshot: SettingSnapshot[bool]) -> None:
+        self.snapshot = snapshot
+        logging.getLogger(__name__).info(
+            "Approval setting applied: %s pid=%s", snapshot.value, os.getpid()
+        )

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application_contracts/inputs/__init__.py.jinja

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

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application_contracts/inputs/approve_order.py.jinja

@@ -0,0 +1,6 @@
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ApproveOrder(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+    expected_version: int = Field(ge=1)

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application_contracts/inputs/create_order.py.jinja

@@ -0,0 +1,7 @@
+from modules.{{ cookiecutter.module_name }}.domain_shared.constants.order_constants import TITLE_MAX_LENGTH
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class CreateOrder(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+    title: str = Field(min_length=1, max_length=TITLE_MAX_LENGTH)

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application_contracts/integration_services/__init__.py.jinja

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

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application_contracts/integration_services/order_reporting_service.py.jinja

@@ -0,0 +1,7 @@
+from typing import Protocol
+
+from python_ddd_framework import ApplicationServiceContract
+
+
+class OrderReportingService(ApplicationServiceContract, Protocol):
+    async def get_count(self) -> int: ...

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

@@ -1,10 +1,47 @@
 """契约层不反向依赖应用实现或 provider。"""
 
-from python_ddd_framework import AppModule
+from modules.{{ cookiecutter.module_name }}.domain_shared.module import {{ cookiecutter.class_prefix }}DomainSharedModule
 
-from ..domain_shared.module import {{ cookiecutter.class_prefix }}DomainSharedModule
+from python_ddd_framework import (
+    AppModule,
+    ConfigureContext,
+    InitializeContext,
+    PostConfigureContext,
+    PostInitializeContext,
+    PreConfigureContext,
+    PreInitializeContext,
+    ShutdownContext,
+)
 
 
 class {{ cookiecutter.class_prefix }}ApplicationContractsModule(AppModule):
     dependencies = ({{ cookiecutter.class_prefix }}DomainSharedModule,)
     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}}/application_contracts/services/__init__.py.jinja

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

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

@@ -0,0 +1,13 @@
+from typing import Protocol
+from uuid import UUID
+
+from modules.{{ cookiecutter.module_name }}.application_contracts.inputs.approve_order import ApproveOrder
+from modules.{{ cookiecutter.module_name }}.application_contracts.views.order_view import OrderView
+
+from python_ddd_framework import ApplicationServiceContract
+
+
+class {{ cookiecutter.class_prefix }}ApprovalApplicationService(ApplicationServiceContract, Protocol):
+    async def approve(self, id: UUID, command: ApproveOrder) -> OrderView: ...
+
+    async def queue_approval(self, id: UUID) -> str: ...

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application_contracts/services/order_management_service.py.jinja

@@ -0,0 +1,10 @@
+from typing import Protocol
+
+from modules.{{ cookiecutter.module_name }}.application_contracts.inputs.create_order import CreateOrder
+from modules.{{ cookiecutter.module_name }}.application_contracts.views.order_view import OrderView
+
+from python_ddd_framework import ApplicationServiceContract
+
+
+class {{ cookiecutter.class_prefix }}ManagementApplicationService(ApplicationServiceContract, Protocol):
+    async def create(self, command: CreateOrder) -> OrderView: ...

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application_contracts/services/order_query_service.py.jinja

@@ -0,0 +1,12 @@
+from typing import Protocol
+from uuid import UUID
+
+from modules.{{ cookiecutter.module_name }}.application_contracts.views.order_view import OrderView
+
+from python_ddd_framework import ApplicationServiceContract
+
+
+class {{ cookiecutter.class_prefix }}QueryApplicationService(ApplicationServiceContract, Protocol):
+    async def get(self, id: UUID) -> OrderView: ...
+
+    async def get_list(self) -> tuple[OrderView, ...]: ...

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application_contracts/views/__init__.py.jinja

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

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application_contracts/views/order_statistics_snapshot.py.jinja

@@ -0,0 +1,9 @@
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class OrderStatisticsSnapshot(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    count: int = Field(ge=0)
+    captured_at: datetime

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application_contracts/views/order_view.py.jinja

@@ -0,0 +1,12 @@
+from uuid import UUID
+
+from modules.{{ cookiecutter.module_name }}.domain_shared.enums.order_status import OrderStatus
+from pydantic import BaseModel, ConfigDict
+
+
+class OrderView(BaseModel):
+    model_config = ConfigDict(frozen=True, from_attributes=True)
+    id: UUID
+    title: str
+    status: OrderStatus
+    version: int

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

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

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/domain/{orders.py.jinja → entities/order.py.jinja}

@@ -1,26 +1,14 @@
-"""聚合拥有审批规则、版本及事件；持久化实现只负责映射。"""
-
 from __future__ import annotations
 
-from dataclasses import dataclass
 from uuid import UUID
 
-from pydantic import Field
-from python_ddd_framework import AggregateRoot, ValueObject
-from python_ddd_framework.errors import BusinessError
-
-from ..domain_shared.definitions import ALREADY_APPROVED, TITLE_MAX_LENGTH, OrderStatus
-
+from modules.{{ cookiecutter.module_name }}.domain.events.order_changed import OrderChanged
+from modules.{{ cookiecutter.module_name }}.domain.value_objects.order_title import OrderTitle
+from modules.{{ cookiecutter.module_name }}.domain_shared.enums.order_status import OrderStatus
+from modules.{{ cookiecutter.module_name }}.domain_shared.errors.order_errors import ALREADY_APPROVED
 
-class OrderTitle(ValueObject):
-    value: str = Field(min_length=1, max_length=TITLE_MAX_LENGTH)
-
-
-@dataclass(frozen=True)
-class OrderChanged:
-    order_id: UUID
-    status: OrderStatus
-    user_id: UUID | None = None
+from python_ddd_framework import AggregateRoot
+from python_ddd_framework.errors import BusinessError
 
 
 class Order(AggregateRoot[UUID]):
@@ -45,11 +33,15 @@ class Order(AggregateRoot[UUID]):
 
     @classmethod
     def create(cls, id: UUID, title: OrderTitle) -> Order:
+        # 业务扩展：在这里校验新聚合的创建条件、初始化实体和值对象；替换订单示例时一起调整参数。
+        # 领域方法只维护业务状态和事件，持久化由应用服务调用仓储完成。
         order = cls(id, title)
         order.raise_local_event(OrderChanged(id, order.status))
         return order
 
     def approve(self, *, user_id: UUID | None = None) -> None:
+        # 业务扩展：在这里实现自己的状态转换条件，例如库存是否足够、单据是否允许提交。
+        # 校验通过后再修改状态并记录对应事件；HTTP 参数绑定和调用者授权留在外层。
         if self.status is OrderStatus.APPROVED:
             raise BusinessError(ALREADY_APPROVED)
         self._status = OrderStatus.APPROVED

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

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

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/domain/events/order_changed.py.jinja

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from uuid import UUID
+
+from modules.{{ cookiecutter.module_name }}.domain_shared.enums.order_status import OrderStatus
+
+
+@dataclass(frozen=True)
+class OrderChanged:
+    order_id: UUID
+    status: OrderStatus
+    user_id: UUID | None = None

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

@@ -1,10 +1,49 @@
 """扫描仅包含实际业务声明，模块 tests 不参与服务发现。"""
 
-from python_ddd_framework import AppModule
+from modules.{{ cookiecutter.module_name }}.domain_shared.module import {{ cookiecutter.class_prefix }}DomainSharedModule
 
-from ..domain_shared.module import {{ cookiecutter.class_prefix }}DomainSharedModule
+from python_ddd_framework import (
+    AppModule,
+    SettingsModule,
+    DataSeedingModule,
+    ConfigureContext,
+    InitializeContext,
+    PostConfigureContext,
+    PostInitializeContext,
+    PreConfigureContext,
+    PreInitializeContext,
+    ShutdownContext,
+)
 
 
 class {{ cookiecutter.class_prefix }}DomainModule(AppModule):
-    dependencies = ({{ cookiecutter.class_prefix }}DomainSharedModule,)
+    dependencies = ({{ cookiecutter.class_prefix }}DomainSharedModule, SettingsModule, DataSeedingModule)
     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/repositories/__init__.py.jinja

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

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/domain/repositories/order_repository.py.jinja

@@ -0,0 +1,17 @@
+"""领域需要的业务仓储边界；不暴露 Session 或容器。"""
+
+from typing import Protocol
+from uuid import UUID
+
+from modules.{{ cookiecutter.module_name }}.domain.entities.order import Order
+
+from python_ddd_framework import RepositoryContract
+
+
+class OrderRepository(RepositoryContract, Protocol):
+    async def find(self, id: UUID, include_details: bool = True) -> Order | None: ...
+    async def get(self, id: UUID, include_details: bool = True) -> Order: ...
+    async def get_count(self) -> int: ...
+    async def get_paged_list(self, skip_count: int, max_result_count: int, sorting: str | None = None, include_details: bool = False) -> list[Order]: ...
+    async def get_list(self, include_details: bool = False) -> list[Order]: ...
+    async def save(self, order: Order) -> None: ...

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

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