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

python_ddd_framework/developer_kit/templates/basic/cookiecutter.json

@@ -0,0 +1,4 @@
+{
+  "module_name": "conversions",
+  "class_prefix": "Conversions"
+}

python_ddd_framework/developer_kit/templates/basic/{{cookiecutter.module_name}}/README.md

@@ -0,0 +1,45 @@
+# {{ cookiecutter.class_prefix }}
+
+This basic module demonstrates an ordinary in-process DI service. Text conversion is an example to replace with your own capability, not a required business model.
+
+| File | Owner |
+| --- | --- |
+| `module.py` | `{{ cookiecutter.class_prefix }}Module`: dependencies, scanning, and lifecycle |
+| `contracts/conversion_service.py` | The public `ConversionService` Protocol |
+| `services/default_conversion_service.py` | The transient default implementation |
+| `__init__.py` files | Package markers only |
+
+The CLI adds `{{ cookiecutter.class_prefix }}Module` to the Host dependencies and publishes the `{{ cookiecutter.module_name }}` alias through the project's standard module entry points. This template does not require database or Redis providers. Other modules selected by your Host may require them.
+
+## Consume the interface
+
+Declare a dependency on `{{ cookiecutter.class_prefix }}Module` in the consuming Module and inject `ConversionService` through a constructor. Keep the consuming service in that Module's `scan_packages`:
+
+```python
+from python_ddd_framework import AppModule, TransientDependency
+from modules.{{ cookiecutter.module_name }}.module import {{ cookiecutter.class_prefix }}Module
+from modules.{{ cookiecutter.module_name }}.contracts.conversion_service import ConversionService
+
+class LabelService(TransientDependency):
+    def __init__(self, conversions: ConversionService) -> None:
+        self.conversions = conversions
+
+    def label(self, text: str) -> str:
+        return self.conversions.to_upper(text)
+
+class LabelsModule(AppModule):
+    dependencies = ({{ cookiecutter.class_prefix }}Module,)
+    scan_packages = (__package__,)
+```
+
+Add `LabelsModule` to the Host dependencies. Each resolution inside a REQUEST creates a fresh transient instance; dependencies still obey their own scope constraints. No custom Provider, factory, or service locator is required.
+
+## Lifecycle and replacement
+
+All seven lifecycle hooks are explicit. Empty hooks use `pass`; composition is synchronous and does not start I/O, while initialization and shutdown are asynchronous. Resources belong to the Module that creates them and must be released before shutdown returns.
+
+To replace the example, subclass `DefaultConversionService` in a consuming Module that directly depends on `{{ cookiecutter.class_prefix }}Module`. In its `post_configure`, use the framework's `context.services.add_transient(ConversionService, YourConversionService, override=True, reason="...")`. The default is transient and the replacement should preserve that contract. Do not register a parallel lookup path or modify the original contract to point at the replacement.
+
+The synchronous `to_upper` method is unmarked and returns `text.upper()`. It is not an ApplicationService, has no interception or HTTP exposure, and does not open a transaction. To use authorization, validation, or UoW interception later, adopt the supported asynchronous instance-method contract and explicitly declare its capability dependencies and policies.
+
+This template generates no Domain, persistence, migration, seed, HTTP, background task, or empty layer. Use `pddd add module <name> --template ddd` for the complete six-layer example instead. Project commands can run from the application root or any child directory; Python files and metadata belong under `backend/`.

python_ddd_framework/developer_kit/templates/basic/{{cookiecutter.module_name}}/contracts/conversion_service.py.jinja

@@ -0,0 +1,7 @@
+"""Public in-process service contract; independent of Host and implementation."""
+
+from typing import Protocol
+
+
+class ConversionService(Protocol):
+    def to_upper(self, text: str) -> str: ...

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

@@ -0,0 +1,38 @@
+"""Declare this capability and its scan boundary; service logic belongs in services."""
+
+from python_ddd_framework import (
+    AppModule,
+    ConfigureContext,
+    InitializeContext,
+    PostConfigureContext,
+    PostInitializeContext,
+    PreConfigureContext,
+    PreInitializeContext,
+    ShutdownContext,
+)
+
+
+class {{ cookiecutter.class_prefix }}Module(AppModule):
+    dependencies = ()
+    scan_packages = (__package__,)
+
+    def pre_configure(self, context: PreConfigureContext) -> None:
+        pass
+
+    def configure(self, context: ConfigureContext) -> None:
+        pass
+
+    def post_configure(self, context: PostConfigureContext) -> None:
+        pass
+
+    async def pre_initialize(self, context: PreInitializeContext) -> None:
+        pass
+
+    async def initialize(self, context: InitializeContext) -> None:
+        pass
+
+    async def post_initialize(self, context: PostInitializeContext) -> None:
+        pass
+
+    async def shutdown(self, context: ShutdownContext) -> None:
+        pass

python_ddd_framework/developer_kit/templates/basic/{{cookiecutter.module_name}}/services/default_conversion_service.py.jinja

@@ -0,0 +1,10 @@
+"""A minimal synchronous service discovered through the normal DI conventions."""
+
+from python_ddd_framework import TransientDependency
+
+from ..contracts.conversion_service import ConversionService
+
+
+class DefaultConversionService(ConversionService, TransientDependency):
+    def to_upper(self, text: str) -> str:
+        return text.upper()

python_ddd_framework/developer_kit/templates/module/cookiecutter.json

@@ -1 +1 @@
-{"module_name": "orders", "class_prefix": "Orders"}
+{"module_name": "orders", "class_prefix": "Orders", "http_service_path": "/orders", "http_operation_prefix": "orders_"}

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/README.md

@@ -1,70 +1,62 @@
-# {{ cookiecutter.module_name }} module
+# {{ cookiecutter.class_prefix }} module
 
-This module was generated by `pddd add module`. It contains an order-management example to demonstrate the framework's boundaries. The module name does not establish business requirements: replace the example with the application's confirmed domain and keep this document current.
+This module owns the generated order example. Adapt its business rules from confirmed requirements. The Host explicitly selects its Application, SQLAlchemy, and HttpApi Modules and infrastructure providers.
 
-[Application setup](../../../README.md) · [Architecture](../../../docs/architecture.md) · [Development guide](../../../docs/development.md) · [Working rules](../../../AGENTS.md)
+[Project setup](../../../../README.md) · [Working rules](../../../../AGENTS.md) · [Architecture](../../../../docs/architecture.md) · [Directory and coding rules](../../../../docs/development.md#module-layout-and-coding-rules)
 
-## Ownership and entry points
+## Owners and entry points
 
-| Concern | Source |
+| Capability | Entry |
 | --- | --- |
-| Shared names, errors, permissions, and message types | [Shared definitions](domain_shared/definitions.py) and [permission definitions](domain_shared/permissions.py) |
-| Aggregate rules and events | [Order aggregate](domain/orders.py) |
-| Repository contract and runtime setting | [Repository](domain/repository.py) and [settings](domain/settings.py) |
-| DTOs and public service contract | [Application contracts](application_contracts/orders.py) |
-| Use cases and policies | [Application service](application/orders.py) |
-| Events, jobs, workers, and hosted integration example | [Event handlers](application/events.py), [tasks](application/tasks.py), and [integration](application/integration.py) |
-| ORM, repositories, and migration registration | [Models](sqlalchemy/models/orders.py), [repository implementation](sqlalchemy/repositories/orders.py), and [persistence module](sqlalchemy/module.py) |
-| HTTP exposure, file transfer, and WebSocket | [HTTP module](http_api/module.py), [files](http_api/files.py), and [real-time endpoint](http_api/realtime.py) |
+| Shared constraints, permissions, errors, messages | [Shared layer](domain_shared/module.py), [constants](domain_shared/constants/order_constants.py), [permissions](domain_shared/permissions/order_permission_provider.py) |
+| Aggregate, value, domain policy | [Order](domain/entities/order.py), [title](domain/value_objects/order_title.py), [approval policy](domain/services/order_approval_service.py) |
+| Shared immutable value example | [Money](domain_shared/value_objects/money.py), reusable by Domain and public DTOs; no new sample HTTP fields |
+| Repository contract and settings | [Repository](domain/repositories/order_repository.py), [approval setting](domain/settings/approval_settings.py) |
+| User contracts and use cases | [Query contract](application_contracts/services/order_query_service.py), [management](application/services/order_management_service.py), [approval](application/services/order_approval_service.py) |
+| Internal reporting | [Contract](application_contracts/integration_services/order_reporting_service.py), [implementation](application/integration_services/order_reporting_service.py) |
+| Background and lifecycle | [Approval Job](application/background_jobs/order_approval/handler.py), [statistics schedule](application/background_jobs/order_statistics/schedule.py), [maintenance Worker](application/background_workers/order_maintenance_worker.py), [HostedService](application/hosted_services/order_integration_service.py) |
+| Events, interception, settings refresh | [After-commit handler](application/event_handlers/order_changed_handler.py), [interceptor](application/interceptors/order_timing_interceptor.py), [observer](application/setting_handlers/approval_setting_observer.py) |
+| Persistence | [Model](sqlalchemy/models/order_model.py), [repository](sqlalchemy/repositories/order_repository.py), [registration](sqlalchemy/module.py) |
+| Transport | [HTTP exposure](http_api/module.py), [file router](http_api/routers/order_files.py), [WebSocket](http_api/websockets/order_socket.py) |
 
-The Host selects this module's application, SQLAlchemy, and HTTP modules. Other modules consume its public contract with an explicit dependency; they do not import its concrete repository or query its tables. Source declarations own the actual Module graph, table names, permission names, and routes.
+## Behavior and enablement
 
-## Current example behavior
+- Query, management, and approval use separate `{{ cookiecutter.class_prefix }}QueryApplicationService`, `{{ cookiecutter.class_prefix }}ManagementApplicationService`, and `{{ cookiecutter.class_prefix }}ApprovalApplicationService` contracts. The exposure decorator contributes the ContractsModule dependency; overrides retain the sample's deliberate paths and operation IDs. Other conventional methods are automatic, with plain GET Pydantic DTOs bound as query parameters unless explicitly declared otherwise. Reporting uses `OrderReportingService` internally without end-user permissions or HTTP exposure.
+- The aggregate owns pending-to-approved transitions. The domain service reads the approval setting; the caller owns version checks, transaction, and save. Repository writes collect events; AFTER_COMMIT removes the cache before online notification. Notification failure cannot undo a committed write.
+- The approval Job participates in transactional enqueue and ignores missing/already-approved orders. The statistics schedule refers to its Job type and typed payload; the Job definition owns persisted name/version/schema. Generated Workers are code-disabled; HostedService and periodic schedule require explicit Module registration as described in the project development guide. The hosted owner waits for its thread to exit. Settings refresh and timing interception reuse framework extensions.
+- File upload/download/stream and `/ws/{{ cookiecutter.module_name }}` call public contracts. Typed messages in [order_messages](domain_shared/messages/order_messages.py) own their versioned names and payload schemas; handlers and the socket explicitly map business values. Sending reports local queue acceptance, with no offline replay, cross-process backplane or client acknowledgment.
 
-- An order has a validated title and moves from pending to approved. Repeated direct approval is rejected. Shared constraints and errors are declared in `domain_shared/definitions.py`.
-- The public `{{ cookiecutter.class_prefix }}ApplicationService` contract supports create, get, list, approve, and queued approval. Approval accepts an expected version; repository and database checks protect competing writes.
-- Read and write permissions are defined by the module. Approval also reads the module's runtime setting; queued approval additionally uses its startup Options. Keep these choices separate when changing policy.
-- Writes stage aggregate events through the repository. AFTER_COMMIT handlers invalidate the typed cache and send a notification to the initiating user when that identity is available. A notification failure does not undo the database commit.
-- `ApprovalJob` carries an `order_id` and safely ignores orders that are missing or already approved. Both periodic example workers are code-disabled by default. The hosted integration example is opt-in and is not registered initially.
-- The authenticated WebSocket at `/ws/{{ cookiecutter.module_name }}` sends a snapshot and accepts `{}` to refresh. Online notifications have no cross-process backplane or offline replay. File upload/download/stream examples share the public service boundary.
+Startup [Options](application/options/order_options.py) bind to the `{{ cookiecutter.module_name }}` YAML section; `allow_background_approval` defaults to true. Runtime approval settings and seed contributors belong to Domain. Its Module declares `SettingsModule` and `DataSeedingModule`; contributors are independent DI services, not ApplicationServices. The Domain [OrderApprovalService](domain/services/order_approval_service.py) opts into `ValidationEnabled` through the transitive InvocationModule dependency, retains its transient lifetime, and leaves saving and transaction completion to its caller. Capability dependencies and typed declarations are owned by each Module, while Host selects providers. Change declarations at their owners rather than copying names into another registry.
 
-Use the generated application's `/docs` for the current HTTP paths and payloads. Change business rules only from confirmed requirements; update their aggregate, service policy, persistence, and verification owners together.
+## Optional in-process observations
 
-## Database and configuration
+The external integration example includes a pure-value [snapshot](domain_shared/messages/order_observation.py)
+and a [Handler](application/hosted_services/order_observation_handler.py). It is not enabled by
+default and does not replace existing callbacks. Follow the project's development guide to add
+MessagingModule, declare the typed channel and register the ACTION Handler. Only pending
+snapshots may coalesce; acceptance, completion, commit and external acknowledgement differ.
 
-After initializing the framework providers as described in the application README, run these commands from the application root:
+## Persistence and verification
 
-```sh
-uv run pddd db revision --module {{ cookiecutter.module_name }}
-```
+This module's ordinary models do not automatically become extension targets. To publish a reusable extension point, declare `ExtensionPoints` with explicit DTO/entity targets and use `ExtensibleModel` for those DTOs. Customer modules contribute typed `ExtensionProperties`; SQL column mappings reference the same fields and belong to their persistence Module. The base module keeps table/Schema/core ownership, while customer extension revisions declare native Alembic `depends_on` and include only their declared columns/indexes. Effective DTO and mapper state belong to each Application.
 
-Review the generated revision before applying it, then run:
+From the application root, generate and review a revision, then apply and seed explicitly:
 
 ```sh
-uv run pddd db upgrade --module {{ cookiecutter.module_name }}
-uv run pddd db status --module {{ cookiecutter.module_name }}
-uv run pddd db seed --module {{ cookiecutter.module_name }}
-```
-
-The module owns its models and migration package. Keep applied revisions immutable and upgrade external prerequisites explicitly. Seeding this module does not seed identity or migrate the schema on its behalf.
-
-Startup options are declared in [application/options.py](application/options.py) and bound to the `{{ cookiecutter.module_name }}` YAML section. For example:
-
-```yaml
-{{ cookiecutter.module_name }}:
-  allow_background_approval: false
+pddd db revision --module {{ cookiecutter.module_name }}
+pddd db upgrade --module {{ cookiecutter.module_name }}
+pddd db status --module {{ cookiecutter.module_name }}
+pddd db seed --module {{ cookiecutter.module_name }}
+cd backend
+uv run pytest src/modules/{{ cookiecutter.module_name }}/tests
 ```
 
-Runtime setting definitions remain in `domain/settings.py`; query the current version token before a conditional update or reset. Do not copy permission, setting, queue, or database identities into a second registry.
-
-## Verification and maintenance
+Keep applied migrations immutable. The domain test covers repeat-approval rejection; it does not prove infrastructure, HTTP, background, or deployment behavior. Host tests cover generic health and identity. Update the owning contracts, implementation, documentation, and existing verification when adapting the example. Every Module supplies all seven lifecycle hooks; keep empty stages as `pass`.
 
-Run the existing domain test from the application root:
+## Data and events
 
-```sh
-uv run pytest src/modules/{{ cookiecutter.module_name }}/tests
-```
+`OrderRepository.find` returns an optional aggregate; `get` requires one. List/count/page methods keep explicit ORM mapping and stable ordering. Business `save` participates in the caller's UoW and records entity and aggregate events once. Nontransactional UoWs reject event-producing writes before staging. The framework repository's `auto_save` flushes without committing an outer UoW.
 
-This test covers the sample aggregate's approval behavior. It does not prove HTTP authorization, database concurrency, jobs, Redis, WebSocket delivery, or deployment behavior. Add focused coverage as the application implements those requirements; root Host tests cover the generic Host boundary.
+Inject `DistributedCache[OrderCacheItem]` (or the statistics item), using keys directly. Item classes in `application/caching/` own stable names. Global defaults and explicit entry options are complete alternatives. Use `consider_uow=True` for writes/deletions that should apply after a successful commit. `await events.publish(message)` dispatches immediately without a UoW and follows DOMAIN/AFTER_COMMIT stages inside a transaction; post-commit errors do not undo saved data.
 
-When changing this module, update the sections affected by its responsibilities, public contract, business invariants, persistence, background work, or validation scope. Add a more specific `AGENTS.md` only if the module needs distinct working rules; shared development instructions belong at the application root.
+This is the `ddd` template (the default), with all six layers and supported examples. Use `--template basic` for an ordinary in-process service. This module lives under `backend/src/modules/`; native uv/test/build commands run from `backend/`, while installed `pddd` project commands locate the owning backend from any application directory.

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

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

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

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

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

@@ -0,0 +1,45 @@
+from datetime import timedelta
+
+from modules.{{ cookiecutter.module_name }}.application.background_jobs.order_approval.payload import (
+    ApprovalPayload,
+)
+from modules.{{ cookiecutter.module_name }}.application.options.order_options import {{ cookiecutter.class_prefix }}Options
+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.constants.order_constants import MODULE_NAME
+from modules.{{ cookiecutter.module_name }}.domain_shared.enums.order_status import OrderStatus
+from modules.{{ cookiecutter.module_name }}.domain_shared.errors.order_errors import APPROVAL_DISABLED
+
+from python_ddd_framework import Options
+from python_ddd_framework.background_jobs import BackgroundJobContext, BackgroundJobHandler
+from python_ddd_framework.errors import BusinessError
+
+
+class ApprovalJob(BackgroundJobHandler[ApprovalPayload]):
+    name = f"{MODULE_NAME}.approve"
+    version = 1
+    current = True
+    timeout = timedelta(seconds=30)
+
+    def __init__(
+        self,
+        repository: OrderRepository,
+        approval: OrderApprovalService,
+        options: Options[{{ cookiecutter.class_prefix }}Options],
+    ) -> None:
+        self._repository, self._approval, self._options = repository, approval, options
+
+    async def execute(self, payload: ApprovalPayload, context: BackgroundJobContext) -> None:
+        # 业务扩展：这里执行可重试的后台用例；任务可能重复投递，先核对当前业务状态再产生副作用。
+        # 把审批替换为自己的业务，并同步调整载荷；不要删除幂等判断或吞掉应触发重试的异常。
+        if self._options.value.allow_background_approval:
+            order = await self._repository.find(payload.order_id)
+            if order is not None and order.status is OrderStatus.PENDING:
+                try:
+                    await self._approval.approve(order)
+                except BusinessError as error:
+                    # 保留后台业务的既有语义：设置禁止时跳过；其他失败仍交给任务重试。
+                    if error.definition == APPROVAL_DISABLED:
+                        return
+                    raise
+                await self._repository.save(order)

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

@@ -0,0 +1,8 @@
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict
+
+
+class ApprovalPayload(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+    order_id: UUID

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

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

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

@@ -0,0 +1,35 @@
+import logging
+from datetime import UTC, datetime, timedelta
+
+from modules.{{ cookiecutter.module_name }}.application.background_jobs.order_statistics.payload import (
+    StatisticsPayload,
+)
+from modules.{{ cookiecutter.module_name }}.application.caching.statistics_cache import OrderStatisticsCacheItem
+from modules.{{ cookiecutter.module_name }}.application_contracts.integration_services.order_reporting_service import (
+    OrderReportingService,
+)
+from modules.{{ cookiecutter.module_name }}.domain_shared.constants.order_constants import MODULE_NAME
+
+from python_ddd_framework.background_jobs import BackgroundJobContext, BackgroundJobHandler
+from python_ddd_framework.caching import DistributedCache
+
+
+class OrderStatisticsJob(BackgroundJobHandler[StatisticsPayload]):
+    name = f"{MODULE_NAME}.scheduled-statistics"
+    version = 1
+    current = True
+    timeout = timedelta(seconds=10)
+
+    def __init__(self, reporting: OrderReportingService, cache: DistributedCache[OrderStatisticsCacheItem]) -> None:
+        self._reporting, self._cache = reporting, cache
+
+    async def execute(self, payload: StatisticsPayload, context: BackgroundJobContext) -> None:
+        count = await self._reporting.get_count()
+        await self._cache.set(
+            "current",
+            OrderStatisticsCacheItem(
+                count=count,
+                captured_at=datetime.now(UTC),
+            ),
+        )
+        logging.getLogger(__name__).info("Scheduled order statistics: %s", count)

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

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

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

@@ -0,0 +1,15 @@
+"""周期入队声明；Module 显式引用后才启用，处理体由持久 Job 拥有。"""
+
+from modules.{{ cookiecutter.module_name }}.domain_shared.constants.order_constants import MODULE_NAME
+
+from python_ddd_framework.background_jobs import BackgroundJobSchedule
+
+from .handler import OrderStatisticsJob
+from .payload import StatisticsPayload
+
+STATISTICS_SCHEDULE = BackgroundJobSchedule(
+    name=f"{MODULE_NAME}.statistics.every-ten-seconds",
+    cron="* * * * * */10",
+    job=OrderStatisticsJob,
+    payload=StatisticsPayload(),
+)

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

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

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

@@ -0,0 +1,28 @@
+import logging
+from datetime import timedelta
+
+from modules.{{ cookiecutter.module_name }}.domain.repositories.order_repository import OrderRepository
+from modules.{{ cookiecutter.module_name }}.domain_shared.constants.order_constants import MODULE_NAME
+
+from python_ddd_framework import BackgroundWorker, BackgroundWorkerContext
+from python_ddd_framework.distributed_lock import DistributedLock
+
+logger = logging.getLogger(__name__)
+
+
+class OrderMaintenanceWorker(BackgroundWorker):
+    name = f"{MODULE_NAME}.maintenance"
+    enabled = False
+    interval = timedelta(seconds=30)
+    iteration_timeout = timedelta(seconds=10)
+
+    def __init__(self, repository: OrderRepository, lock: DistributedLock) -> None:
+        self._repository, self._lock = repository, lock
+
+    async def run_iteration(self, context: BackgroundWorkerContext) -> None:
+        # 租约失效由框架请求取消并等待本轮清理；业务不吞 CancelledError。
+        async with self._lock.acquire(f"{MODULE_NAME}:maintenance") as acquired:
+            if acquired:
+                # 业务扩展：需要互斥的维护逻辑写在成功持锁的分支内；当前读取并计数只是演示。
+                orders = await self._repository.get_list()
+                logger.info("Order maintenance completed: %s", len(orders))

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

@@ -0,0 +1,26 @@
+import logging
+from datetime import timedelta
+
+from modules.{{ cookiecutter.module_name }}.application_contracts.integration_services.order_reporting_service import (
+    OrderReportingService,
+)
+from modules.{{ cookiecutter.module_name }}.domain_shared.constants.order_constants import MODULE_NAME
+
+from python_ddd_framework import BackgroundWorker, BackgroundWorkerContext
+
+logger = logging.getLogger(__name__)
+
+
+class OrderStatisticsWorker(BackgroundWorker):
+    name = f"{MODULE_NAME}.statistics"
+    enabled = False
+    interval = timedelta(minutes=5)
+    iteration_timeout = timedelta(seconds=10)
+
+    def __init__(self, reporting: OrderReportingService) -> None:
+        self._reporting = reporting
+
+    async def run_iteration(self, context: BackgroundWorkerContext) -> None:
+        # 业务扩展：这里是一轮周期统计的处理体；替换统计/汇总逻辑，不自行启动 while 循环或线程。
+        # 启用这个默认关闭的示例 Worker 前，先确定自己的执行周期和失败处理要求。
+        logger.info("Order count: %s", await self._reporting.get_count())

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

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

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

@@ -0,0 +1,9 @@
+from modules.{{ cookiecutter.module_name }}.application_contracts.views.order_view import OrderView
+from modules.{{ cookiecutter.module_name }}.domain_shared.constants.order_constants import MODULE_NAME
+
+from python_ddd_framework.caching import cache_name
+
+
+@cache_name(f"{MODULE_NAME}.view")
+class OrderCacheItem(OrderView):
+    pass

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

@@ -0,0 +1,9 @@
+from modules.{{ cookiecutter.module_name }}.application_contracts.views.order_statistics_snapshot import OrderStatisticsSnapshot
+from modules.{{ cookiecutter.module_name }}.domain_shared.constants.order_constants import MODULE_NAME
+
+from python_ddd_framework.caching import cache_name
+
+
+@cache_name(f"{MODULE_NAME}.statistics")
+class OrderStatisticsCacheItem(OrderStatisticsSnapshot):
+    pass

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

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

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

@@ -0,0 +1,23 @@
+from modules.{{ cookiecutter.module_name }}.application.caching.order_cache import OrderCacheItem
+from modules.{{ cookiecutter.module_name }}.domain.events.order_changed import OrderChanged
+from modules.{{ cookiecutter.module_name }}.domain_shared.messages.order_messages import OrderChangedMessage
+
+from python_ddd_framework import LocalEventPhase, local_event_handler
+from python_ddd_framework.caching import DistributedCache
+from python_ddd_framework.realtime import RealtimePublisher
+
+
+@local_event_handler(phase=LocalEventPhase.AFTER_COMMIT)
+class OrderChangedHandler:
+    def __init__(self, cache: DistributedCache[OrderCacheItem], realtime: RealtimePublisher) -> None:
+        self._cache, self._realtime = cache, realtime
+
+    async def handle(self, event: OrderChanged) -> None:
+        # 业务扩展：这里处理提交后的缓存失效/在线通知，替换自己的事件、缓存定义和消息载荷。
+        # 必须随业务一起回滚的规则应放在聚合或 DOMAIN 阶段；这里失败不会撤销已经提交的数据。
+        await self._cache.remove(str(event.order_id))
+        if event.user_id is not None:
+            await self._realtime.send_to_user(
+                event.user_id,
+                OrderChangedMessage(id=event.order_id, status=event.status),
+            )

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

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

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application/{integration.py.jinja → hosted_services/order_integration_service.py.jinja}

@@ -4,6 +4,10 @@ import asyncio
 import logging
 from threading import Event, Thread
 
+from modules.{{ cookiecutter.module_name }}.application_contracts.integration_services.order_reporting_service import (
+    OrderReportingService,
+)
+
 from python_ddd_framework import (
     HostedService,
     HostedServiceContext,
@@ -12,8 +16,9 @@ from python_ddd_framework import (
 )
 
 
-async def observe_integration() -> None:
-    logging.getLogger(__name__).info("External integration callback received")
+async def observe_integration(reporting: OrderReportingService) -> None:
+    count = await reporting.get_count()
+    logging.getLogger(__name__).info("External integration callback observed %s orders", count)
 
 
 class OrderIntegrationService(HostedService):
@@ -39,3 +44,4 @@ class OrderIntegrationService(HostedService):
         if self._thread is not None:
             await asyncio.to_thread(self._thread.join)
             self._thread = None
+        logging.getLogger(__name__).info("External integration thread stopped")

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

@@ -0,0 +1,16 @@
+"""可选线程集成的快照消费者；通过消息能力进入一次受管理调用。"""
+
+import logging
+
+from modules.{{ cookiecutter.module_name }}.domain_shared.messages.order_observation import (
+    OrderObservation,
+)
+
+from python_ddd_framework import MessageHandler, unit_of_work
+
+
+class OrderObservationHandler(MessageHandler[OrderObservation]):
+    @unit_of_work(disabled=True)
+    async def handle(self, message: OrderObservation) -> None:
+        # 替换为快照应用逻辑；若需要保存数据，显式选择事务而非把接收等待放入 UoW。
+        logging.getLogger(__name__).info("Observed order count: %s", message.count)

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

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

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

@@ -0,0 +1,16 @@
+"""内部统计使用正式 IntegrationService 调用链，不开放 HTTP。"""
+
+from modules.{{ cookiecutter.module_name }}.application_contracts.integration_services.order_reporting_service import (
+    OrderReportingService,
+)
+from modules.{{ cookiecutter.module_name }}.domain.repositories.order_repository import OrderRepository
+
+from python_ddd_framework import IntegrationService
+
+
+class _OrderReportingService(IntegrationService, OrderReportingService):
+    def __init__(self, repository: OrderRepository) -> None:
+        self._repository = repository
+
+    async def get_count(self) -> int:
+        return await self._repository.get_count()

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

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

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
+            )