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

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

@@ -2,7 +2,43 @@
 
 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.
 
-[Project setup](../../../../README.md) · [Working rules](../../../../AGENTS.md) · [Architecture](../../../../docs/architecture.md) · [Directory and coding rules](../../../../docs/development.md#module-layout-and-coding-rules)
+[Project setup](../../../../README.md) · [Working rules](../../../../AGENTS.md) · [Architecture](../../../../docs/architecture.md) · [Business planning](../../../../docs/development.md#plan-a-business-change) · [Framework choices](../../../../docs/development.md#choose-a-framework-capability) · [Directory rules](../../../../docs/development.md#module-layout-and-coding-rules)
+
+## Business model record
+
+The following facts describe the generated example. When adapting it, replace them with confirmed business language, boundaries, and acceptance examples. Keep reasons for aggregate/consistency choices and unresolved questions here, with links to their code and checks. A proposed rule remains a proposal until the business requirement is established.
+
+| Concern | Current example |
+| --- | --- |
+| Owner and language | This capability owns an Order's title and approval state. The six layer Modules implement this capability under the Host. Decide actual business boundaries from the application's language and rules. |
+| Identity and values | `Order` has a UUID identity and a version; `OrderTitle` owns title validation and `OrderStatus` defines states. `Money` demonstrates a shared immutable value without becoming an Order field. |
+| Commands and invariants | Creation produces a pending order. Direct approval requires an existing order and the supplied expected version; the approval setting must allow it, and an approved order cannot be approved again. See the walkthrough below for each rule's owner. |
+| Consistency and collaboration | The repository stages one aggregate change in the caller's UoW, preserving optimistic concurrency. Commit precedes cache invalidation and optional online notification. Collaborating modules use public contracts with declared dependencies. |
+| Acceptance and open decisions | The generated domain test covers repeated approval. Real business rejection rules, aggregate relationships, and integration guarantees must come from the application's requirements and receive their own verification. See [verification](#persistence-and-verification) for the current coverage boundary. |
+
+### Invariants and rejection examples
+
+Maintain this record for each changed business invariant under the project's [mandatory DDD rules](../../../../docs/architecture.md#mandatory-ddd-rules). Add its source owner, operation, and concrete rejection case; distinguish implemented behavior from executed verification. The following rows describe the generated example, not additional requirements for another domain.
+
+| Rule | Owner and operation | Rejection example and evidence |
+| --- | --- | --- |
+| An approved order cannot be approved again. | [Order](domain/entities/order.py), `approve()`. | Calling `approve()` twice raises the domain error. The generated domain test covers this path; report its actual run result. |
+| Approval must be enabled. | [Domain approval policy](domain/services/order_approval_service.py), `approve()`. | A disabled approval setting rejects the operation before the aggregate changes. This rule needs its own evidence when adapting the domain; the repeated-approval test does not prove it. |
+| An interactive approval requires a current expected version. | [Application approval service](application/services/order_approval_service.py), `approve()`, plus repository/database concurrency enforcement. | A stale expected version is rejected; a competing database write must also be rejected at persistence. Domain-only tests do not prove the database race. |
+
+For child entities, record the root operation that protects their invariant. For cross-aggregate writes, extend the consistency row above with the participating owners, atomic writes, later effects, and failure/idempotency decisions before implementation. Keep unresolved decisions explicit; do not infer distributed delivery or retry guarantees from the sample's local events.
+
+## Approval walkthrough
+
+Follow one use case across its owners before changing a similar operation:
+
+1. The caller uses the [approval contract](application_contracts/services/order_approval_service.py) with [ApproveOrder](application_contracts/inputs/approve_order.py). The [application implementation](application/services/order_approval_service.py) applies the write permission, loads the order, and rejects a missing order or stale expected version.
+2. The [domain policy](domain/services/order_approval_service.py) reads the approval setting, then asks the [aggregate](domain/entities/order.py) to approve. The aggregate enforces the state transition and records a stable `OrderChanged` value; it does not save itself.
+3. The application calls the [repository](sqlalchemy/repositories/order_repository.py). It maps the aggregate, checks its persistence version, stages the next version, and lets `operation(..., aggregate=order)` collect events once. The managed UoW owns commit.
+4. After commit, the [event handler](application/event_handlers/order_changed_handler.py) removes the cached order and sends an online notification when a user ID is present. A failure here leaves the database commit intact; it does not justify blindly repeating the business write.
+5. For deferred approval, `queue_approval` returns a Job ID after transactional enqueue. [ApprovalPayload](application/background_jobs/order_approval/payload.py) carries the order ID; it does not carry the interactive expected version or user identity. The [Job](application/background_jobs/order_approval/handler.py) reads current state, skips missing/already-approved orders or disabled approval, and reuses the domain policy and repository. Queue acceptance and completed approval are separate outcomes.
+
+Use this trace to record the required behavior before adding an operation: which rule changes, who owns it, which framework capability executes it, and which check proves it. Keep the table above aligned with the resulting code.
 
 ## Owners and entry points
 
@@ -22,8 +58,9 @@ This module owns the generated order example. Adapt its business rules from conf
 ## Behavior and enablement
 
 - 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.
+- The [approval walkthrough](#approval-walkthrough) traces aggregate rules, domain policy, concurrency, transaction completion, and post-commit effects through their owners.
+- 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. Settings refresh and timing interception reuse framework extensions.
+- The hosted example uses `stopping` for an independent business call and an SDK thread callback with the temporary context, then `stop` joins the actual thread after accepted work drains. Startup contexts stay closed during shutdown. To keep message input during this phase, declare this service in the channel's `stopping_owners`, depend on its Module owner, and pass `stopping=context`; no channel opts in by default.
 - 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.
 
 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.
@@ -57,6 +94,8 @@ Keep applied migrations immutable. The domain test covers repeat-approval reject
 
 `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.
 
+`OrderChanged` captures UUIDs and an enum in a frozen dataclass. `raise_local_event` checks nested values before enqueueing: use native stable scalars, tuples/frozensets, or frozen records; avoid mutable containers, mapping views, entity references, cycles, and undeclared state. Pydantic event models must be frozen without extra/private/cached state. Dataclass subclasses must themselves declare `frozen=True`. Rejection raises TypeError and preserves already queued events; the framework keeps accepted event objects without copying. Repository entity-change notifications continue to carry entity references.
+
 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.
 
 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/hosted_services/order_integration_service.py.jinja

@@ -4,10 +4,6 @@ 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,
@@ -15,6 +11,10 @@ from python_ddd_framework import (
     ShutdownReason,
 )
 
+from modules.{{ cookiecutter.module_name }}.application_contracts.integration_services.order_reporting_service import (
+    OrderReportingService,
+)
+
 
 async def observe_integration(reporting: OrderReportingService) -> None:
     count = await reporting.get_count()
@@ -24,6 +24,10 @@ async def observe_integration(reporting: OrderReportingService) -> None:
 class OrderIntegrationService(HostedService):
     def __init__(self) -> None:
         self._stop = Event()
+        self._prepare = Event()
+        self._callback_done = Event()
+        self._stopping_context: HostedServiceContext | None = None
+        self._callback_error: BaseException | None = None
         self._thread: Thread | None = None
 
     async def start(self, context: HostedServiceContext) -> None:
@@ -34,13 +38,33 @@ class OrderIntegrationService(HostedService):
     def _receive(self, context: HostedServiceContext) -> None:
         # submit_call 只能来自外部线程；Future.result 等待同一正式 invocation 完成。
         try:
-            context.submit_call(observe_integration).result()
-        except HostedServiceInvocationRejectedError:
-            return  # Application 关闭已撤销调用许可。
+            try:
+                context.submit_call(observe_integration).result()
+            except HostedServiceInvocationRejectedError:
+                pass  # 普通准入可能已经关闭；收尾只使用 stopping 新提供的 context。
+            self._prepare.wait()
+            stopping = self._stopping_context
+            if stopping is not None:
+                stopping.submit_call(observe_integration).result()
+        except BaseException as error:  # noqa: BLE001 -- 线程故障转交 stopping 重新抛出。
+            self._callback_error = error
+        finally:
+            self._callback_done.set()
         self._stop.wait()
 
+    async def stopping(self, context: HostedServiceContext, reason: ShutdownReason) -> None:
+        # 独立业务调用完成后再等 SDK 回调，不跨线程传 scope，也不跨等待持有事务。
+        await context.call(observe_integration)
+        self._stopping_context = context
+        self._prepare.set()
+        await asyncio.to_thread(self._callback_done.wait)
+        if self._callback_error is not None:
+            raise RuntimeError("External integration callback failed") from self._callback_error
+
     async def stop(self, reason: ShutdownReason) -> None:
+        # start 部分失败时 stopping 不会执行；仍须唤醒并等待实际线程退出。
         self._stop.set()
+        self._prepare.set()
         if self._thread is not None:
             await asyncio.to_thread(self._thread.join)
             self._thread = None

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

@@ -2,12 +2,12 @@
 
 import logging
 
+from python_ddd_framework import MessageHandler, unit_of_work
+
 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)

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

@@ -74,6 +74,8 @@ class SqlAlchemyOrderRepository(OrderRepository):
 
 def _order(row: OrderRow) -> Order:
     # 映射扩展：在这里把数据库字段恢复成领域实体/值对象，不调用会再次产生创建事件的工厂。
+    # 驱动的 UUID 子类在边界恢复为原生 UUID，聚合事件只持有稳定领域值。
     return Order(
-        row.id, OrderTitle(value=row.title), status=OrderStatus(row.status), version=row.version
+        UUID(bytes=row.id.bytes), OrderTitle(value=row.title),
+        status=OrderStatus(row.status), version=row.version
     )

python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/AGENTS.md

@@ -6,11 +6,18 @@ These instructions apply to this application and its business modules. Follow th
 
 1. Check the branch, worktree, requested outcome, and existing changes before editing. Analysis and review requests are read-only unless implementation is requested.
 2. Use [README](README.md) for setup and commands, [architecture](docs/architecture.md) for ownership and dependencies, and the relevant section of [development](docs/development.md) for framework usage.
-3. First identify the layer and responsibility directory in the [module layout rules](docs/development.md#module-layout-and-coding-rules). Before changing a business module, read its `backend/src/modules/<name>/README.md`, then inspect the affected source and direct callers. Expand the investigation only when those facts reveal another affected boundary.
-4. Read versions and dependencies from `backend/pyproject.toml`, exact resolutions from `backend/uv.lock`, and commands from `pddd --help`. Verify behavior against the installed framework version when the application documentation is insufficient.
+3. Before changing a business module, read its `backend/src/modules/<name>/README.md`, then inspect the affected source and direct callers. Use the workflow below to choose the layer and responsibility directory. Expand the investigation only when those facts reveal another affected boundary.
+4. Read versions and dependencies from `backend/pyproject.toml` and exact resolutions from `backend/uv.lock`. Follow [installed framework lookup](docs/development.md#match-the-installed-framework) for the actual package, bundled examples, and CLI. Generated guidance records the template version; upgrades do not update it automatically.
 
 Python code, metadata, configuration, environment, and deployment files belong under `backend/`. Root `scripts/` contains consumer-owned scripts. Run installed `pddd` commands from any directory in the application; run native uv/build/test and Docker commands from `backend/`.
 
+## Work from business rules to framework code
+
+1. Describe the requested use case in business terms: caller, command or query, expected outcome, allowed state changes, and failure conditions. Reuse the module's recorded language and rules. The generated order example supplies implementation examples; actual business requirements come from the application.
+2. For a domain change, identify the rule owner, aggregate boundary, consistency needs, and collaboration with other modules using [business-change planning](docs/development.md#plan-a-business-change). Keep confirmed decisions in the owning module README. Ask about missing rules that affect correctness; label proposals and open questions instead of presenting assumptions as approved rules.
+3. Map each needed technical capability through the [framework selection table](docs/development.md#choose-a-framework-capability). Check the installed API, the owning Module's declarations, and an existing usage before adding infrastructure. Choose the existing `basic` or `ddd` layout for the capability; place each change using the [directory rules](docs/development.md#module-layout-and-coding-rules).
+4. Implement the authorized use case through its public contract, domain behavior, and existing persistence/invocation boundaries. Reuse existing validation and [verification commands](docs/development.md#verification); state which domain rules, composition paths, and infrastructure behavior the checks actually cover. Scale this process to the change: a local correction can reuse the existing model directly.
+
 ## Preserve ownership and contracts
 
 - The Host composes modules, selects providers, and supplies configuration. Keep business state and rules in their owning modules.
@@ -22,6 +29,10 @@ Python code, metadata, configuration, environment, and deployment files belong u
 
 Use the documented responsibility directories for every new capability. Propose a standards change before adding a responsibility category or changing dependency direction. The `ddd` template intentionally generates all supported example capabilities, even before use; this exception applies to DDD templates and generated projects, not speculative framework runtime layers. The `basic` template generates only package markers, `module.py`, `contracts/conversion_service.py`, `services/default_conversion_service.py`, and its README. It uses ordinary transient DI, without Domain, persistence, HTTP, interception, or empty layers. Keep `module.py` limited to dependencies, registration, and lifecycle hooks, and keep package `__init__.py` free of business code and compatibility exports.
 
+## Enforce DDD rules
+
+For a modeled domain capability, apply the [mandatory DDD rules](docs/architecture.md#mandatory-ddd-rules) during implementation and review. Reject application code that assigns aggregate business state directly, writes aggregate children outside the root's business operations, or leaks ORM/Session types through domain repository contracts. Before a cross-aggregate write, record its consistency, failure, and idempotency decisions. Keep each changed invariant's owner, operation, and rejection example in the module README and verify them with the [business-change checks](docs/development.md#check-a-domain-change). These rules do not require a `basic` service to acquire unused DDD layers.
+
 ## Use the framework safely
 
 - Extend only explicitly opened targets. Keep typed properties in application contracts, optional SQL mappings and local extension revisions in persistence, and reuse the same declaration for validation, OpenAPI, and storage. Never mutate shared DTO/ORM classes or duplicate the base table/Schema owner; extension migrations declare Alembic prerequisites explicitly.
@@ -29,7 +40,7 @@ Use the documented responsibility directories for every new capability. Propose
 - Invoke application services through their injected public contracts or the framework functions `invoke(application, ...)` / `call(application, ...)`. Manual construction and self-calls do not create a new managed invocation.
 - Ordinary DI services opt into interception with `@unit_of_work`, `@authorize`, or `ValidationEnabled`; declare the corresponding capability dependency on their owning Module. Keep marked methods async instance methods and preserve native scope/cache. These declarations do not add HTTP exposure or require ApplicationService inheritance.
 - Keep transactions short. Never carry a Session, unit of work, or request scope into an ordinary child task, external thread, network wait, or streamed response.
-- Keep aggregate rules and optimistic concurrency checks intact. Use repository operations to stage changes and collect events; do not publish the same aggregate events twice.
+- Keep aggregate rules and optimistic concurrency checks intact. Construct aggregate events from frozen records and stable nested values as described in [architecture](docs/architecture.md#calls-scopes-and-transactions). Use repository operations to stage changes and collect events; do not publish the same aggregate events twice.
 - Review generated migrations. Do not edit applied revisions, bypass migration guards, or treat Host startup as migration or seeding.
 - Keep background side effects idempotent. Local events and WebSocket messages do not provide durable distributed delivery; distributed locks do not replace database concurrency or idempotency.
 - Validate external inputs, propagate meaningful failures, and preserve cancellation and cleanup. Add defaults, retries, or fallbacks only for an identified requirement.
@@ -41,6 +52,13 @@ Business modules own message values and coalescing identities. Only replaceable
 coalesce. Acceptance, processing, commit and external acknowledgement are separate facts.
 Use the framework channel and hosted bridge; preserve capacity and actual cleanup guarantees.
 
+For SDK shutdown, initiate business cleanup in `HostedService.stopping(context, reason)` and
+release resources in `stop(reason)`. Pass the separate stopping context only to this phase's
+callbacks; startup contexts never gain shutdown permissions. Channels opt in with declared
+`stopping_owners` and `send/submit(..., stopping=context)`. Keep the channel Module dependent on
+the service owner, and drain accepted work before releasing resources. See the hosted-service
+and message examples in the project development guide.
+
 ## Verify and maintain
 
 - Preserve unrelated changes. Do not edit the installed framework, generated dependency files by hand, or another repository to make an application change pass.

python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/docs/architecture.md

@@ -55,6 +55,18 @@ The [development guide](development.md#module-layout-and-coding-rules) owns the
 
 Business Modules explicitly depend on the framework capabilities they use. Domain seed contributors depend on `DataSeedingModule`, permission definitions on `AuthorizationModule`, application services on `ApplicationServicesModule`, and HTTP declarations on `FastApiModule`. Host provider selection does not repair a missing business-module dependency. Capability definitions use typed module declarations; their catalogs and runtime state belong to each Application. Every Host and six-layer Module explicitly declares the seven framework hooks. Synchronous configuration phases only compose the application; asynchronous initialization phases follow dependency-first barriers, and shutdown closes resources in reverse dependency order. Empty hooks use `pass`. Generating a complete example does not enable its workers, hosted services, or schedules.
 
+## Mandatory DDD rules
+
+These constraints apply when a capability models aggregates. The module README owns its actual business language and invariants; generated order rules are examples to replace from confirmed requirements.
+
+| Boundary | Required behavior and review criterion |
+| --- | --- |
+| Application and aggregate | Application services authorize, load, coordinate, and save through existing contracts. State transitions and entity/value invariants must run through domain operations. Do not assign aggregate business fields or reproduce their transition rules in Application. Caller permissions and expected-version checks remain Application responsibilities. |
+| Aggregate root and children | Change an aggregate's internal entities and collections through the root's business operations so it can enforce the aggregate's invariants. Do not return mutable internals that let callers bypass those operations. Persistence may reconstitute stored state through the domain construction boundary; reconstitution must not manufacture new creation events or become a business-write shortcut. |
+| Domain repository and persistence | Design domain repository operations around the aggregate's identity and lifecycle, not one repository per table. Domain contracts use domain values and aggregates; keep ORM rows, Session, SQL expressions, and driver-specific values in persistence. Map database scalar subclasses to the native domain value at that boundary. Keep query projections in their declared read responsibility rather than weakening the aggregate contract. |
+| Cross-aggregate consistency | Before implementing a write spanning aggregates, identify the participating owners, what commits atomically, and any later effects. Record concurrency, failure-after-commit, duplicate/retry, and idempotency behavior. A local UoW may coordinate multiple aggregates when that is the confirmed requirement; do not impose one aggregate per transaction mechanically. Cross-module collaboration still uses public contracts, and local events do not promise durable distributed delivery. |
+| Business evidence | For each changed invariant, the module README must identify its rule owner, business operation, and a concrete rejection example, linking the relevant source and verification. Record unverified cases and open decisions explicitly. Directory placement, type checks, and passing unrelated tests do not by themselves prove a business rule. |
+
 ## Calls, scopes, and transactions
 
 A managed service call passes through authorization, validation, ACTION scope, unit-of-work handling, and the final implementation. HTTP and direct service invocation share this pipeline. Inject the public service contract; do not construct implementations to bypass it. A self-call is an ordinary Python call and does not re-enter the pipeline.
@@ -67,8 +79,12 @@ Repositories map aggregates and ORM models explicitly. Their `SqlAlchemySessionP
 
 Local transactional events run in this order: DOMAIN handlers, flush/version checks, database commit, then AFTER_COMMIT handlers. Outside a UoW, `await events.publish(message)` dispatches immediately and does not claim a transaction was committed. Nontransactional UoWs reject explicit and automatic events before repository writes. A post-commit failure does not roll back committed data. Local events provide neither distributed delivery nor crash recovery.
 
+`AggregateRoot.raise_local_event` validates actual field values before enqueueing. The root and nested records must be frozen dataclasses or frozen Pydantic models. Fields may contain native scalar values (`None`, bool, int, float, str, bytes, Decimal, UUID, date, datetime, time, timedelta), stable Enum values, tuples, frozensets, and NamedTuples without extra state. Datetime/time zones must be native timezone/ZoneInfo instances or None. Mutable containers and their subclasses, mapping views, entity references, unsupported custom objects, scalar subclasses, cycles, missing fields, and undeclared instance state are rejected. A mutable-container subclass remains rejected as a root or nested value even when decorated with `frozen=True`, because inherited container operations can still change its contents. Dataclass subclasses must themselves be decorated with `frozen=True`; records cannot declare cached properties or extra slots. Pydantic models cannot use `extra="allow"` or PrivateAttr. Shared immutable children are allowed. Invalid events raise TypeError without changing the queue; valid events are retained without copying. The publisher must respect normal frozen-value semantics. Direct event-bus publication and repository entity-change notifications keep their existing contracts, including entity references.
+
 Typed caches inject `DistributedCache[Item]` and take keys/values directly. The value type owns its cache name; the Host owns the Redis prefix and global defaults. Entry options replace the whole default object. `consider_uow=True` stages changes in the concrete UoW and applies them after successful completion; rollback discards them. Redis and PostgreSQL do not share an atomic commit.
 
+Batch cache I/O remains serial. The first unhidden Redis error, invalid payload, or cancellation can stop later commands; reads may refresh expiry or delete expired entries. After a database commit, ordinary cache errors allow other pending writes to run, while cancellation stops later commands. `hide_errors` only hides Redis errors.
+
 ## Extension ownership
 
 Identity owns core user/role fields, edit versions, and their base migrations. `concurrency_version` protects edits and relationship replacements; `permission_version` only tracks permission state. Password changes, deactivation, and deletion revoke sessions in the same transaction. Login and refresh coordinate through the user's transaction lock; refresh families retain their own lock-before-row mutation order. Consumer modules own only their declared extension columns/indexes and project-local revisions.
@@ -102,8 +118,9 @@ Module initialization precedes selected hosted services and background execution
 - Durable jobs use typed, versioned payloads and the PostgreSQL provider. Transactional enqueue must use the same configured connection as the surrounding unit of work. External side effects remain the job's idempotency responsibility.
 - Periodic workers are explicitly registered. Generated example workers are disabled in their class declarations; configuration cannot enable a code-disabled worker.
 - Execution modes are `host`, `shared`, and `exclusive`. Spawned processes compose their own Application; they do not inherit a live Session or container.
-- A `HostedService` owns long-lived SDKs or threads, their failures, recovery, and actual shutdown. It is opt-in; background-process instances need explicit selection. External threads use its supported submission methods.
+- A `HostedService` owns long-lived SDKs or threads, their failures, recovery, and actual shutdown. It is opt-in; background-process instances need explicit selection. Shutdown has global barriers: close ordinary admission, await `stopping`, close remaining admission, drain accepted work, then release resources in `stop` before Module/container cleanup. Only successfully started services prepare; all touched services clean up. External callbacks use the separate, temporary stopping context, never an upgraded startup context.
 - Redis business locks are leases. Preserve cancellation and cleanup when ownership is lost; a lease is not a transaction, fencing guarantee, or exactly-once guarantee.
+- In-process channels preserve SDK input during stopping only for declared `stopping_owners` and a current hook context passed to `send/submit`. The channel Module depends on the service owner. Admission permissions are Application-local and temporary; accepted work retains its reservation until execution or a reported non-execution outcome, with unchanged capacity and per-message scopes.
 - WebSocket delivery targets currently connected clients. The generated sample has no cross-process backplane, offline replay, or delivery acknowledgment. HTTP streaming must release business transactions before network transmission and clean up producers on disconnect.
 - Liveness and readiness report lifecycle state, not continuous infrastructure availability. Trace export is disabled in the generated development configuration until explicitly configured.
 

python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/docs/development.md

@@ -2,7 +2,68 @@
 
 Use this guide with the project's [architecture](architecture.md) and [working rules](../AGENTS.md). It describes the generated application's use of Python DDD Framework {{ cookiecutter.framework_version }}. Follow the installed version when adapting examples after an upgrade.
 
-[Add a module](#add-a-module) · [Services and permissions](#services-and-permissions) · [Options and settings](#options-and-settings) · [Persistence](#persistence-and-migrations) · [Events and background work](#events-and-background-work) · [Verification](#verification)
+[Plan a business change](#plan-a-business-change) · [Choose a capability](#choose-a-framework-capability) · [Installed version](#match-the-installed-framework) · [Add a module](#add-a-module) · [Services and permissions](#services-and-permissions) · [Options and settings](#options-and-settings) · [Persistence](#persistence-and-migrations) · [Events and background work](#events-and-background-work) · [Verification](#verification)
+
+## Plan a business change
+
+Start with the affected module README and confirmed requirements. For an existing behavior, reuse its model and record only the decisions that change. For a new domain use case, answer these questions before choosing files:
+
+| Decision | Questions to resolve |
+| --- | --- |
+| Language and use case | What do the business terms mean here? Who sends the command or query, and what outcome do they expect? Which facts distinguish success, rejection, and a pending operation? |
+| Business boundary | Which module owns each rule and fact? Where do terms or policies change meaning across contexts? Which public contract allows collaboration with another owner? |
+| Aggregate and values | Which entity controls the state change? Which related values must remain consistent together? Which rules belong on that aggregate, and which need a domain service because they depend on another input or policy? |
+| Consistency and failure | What must commit atomically? What happens with a stale version, duplicate request, cancellation, or a failure after commit? Which work may finish later, and does it need durable execution? |
+| Acceptance | Which concrete examples prove the rule and its failure paths? Which existing checks cover them, and which require approved new tests or real infrastructure? |
+
+Choose boundaries from business language, invariants, and consistency needs. A database table or a generated layer Module does not establish a bounded context or aggregate boundary. Keep entity transitions and value constraints in Domain, orchestration and caller policy in Application, and storage/transport in their existing owners. Use a domain service for a rule that needs collaborators; retain rules that an aggregate can enforce itself on the aggregate.
+
+An ordinary in-process service can use the [basic template](#add-a-module). A capability that needs the domain, persistence, and HTTP examples can use `ddd`; generated examples are enabled according to their Module declarations. Record the chosen model, reasons, and unresolved business questions in the module README. The generated DDD README contains an order model and an approval walkthrough to adapt; its sample rules are not requirements for a new business domain.
+
+### Check a domain change
+
+Use the [mandatory DDD rules](architecture.md#mandatory-ddd-rules) as the review boundary. Before considering the change complete:
+
+1. Trace the public command through Application to the aggregate's business operation. For example, approval calls `order.approve()` through the domain policy; an application assignment to `order._status` fails review. Retain permission and expected-version checks at their existing owners.
+2. If the aggregate has children, trace additions, removals, and edits through the root. A returned list that lets a caller append an invalid child fails the same check. Inspect repository reconstitution separately from business creation and mutation.
+3. Check repository signatures and imports: domain-facing inputs/results express the aggregate contract, while ORM and driver conversion stay in persistence. Do not infer a new repository boundary from a new table.
+4. For writes touching multiple aggregates or later side effects, compare the implementation with the module's recorded atomicity, concurrency, failure, and duplicate-handling decisions. A transaction, local event, or job enqueue alone does not prove all of these guarantees.
+5. Update the module's rule record with the owner, operation, rejection example, and the smallest relevant verification. Reuse existing checks where applicable; request approval for additional tests when the task requires it. Report missing evidence rather than marking the rule verified.
+
+These are review criteria, not a generated automated architecture-test suite. Use the actual checks listed under [verification](#verification).
+
+## Choose a framework capability
+
+Use this table to reach an existing implementation. Business Modules declare capability dependencies and typed contributions; the Host selects providers and supplies configuration. Read activation rules at those owners and use `pddd inspect` to check composition.
+
+| Task | Existing capability and boundary | Start here |
+| --- | --- | --- |
+| Implement a user operation or expose HTTP | Public ApplicationService contract, permission policy, and explicit HTTP exposure in the owning Application/HttpApi Modules | [Services and permissions](#services-and-permissions); module README's approval walkthrough |
+| Add login or user/role administration | Existing Identity authentication and management contracts, with the Host's provider and authorization configuration | [Identity management](#identity-management) |
+| Call an internal service | Inject its public contract through a declared Module dependency; ordinary DI services opt into interception only when required | [Services and permissions](#services-and-permissions); [basic module](#add-a-module) |
+| Save an aggregate in one business operation | Repository contract, SQLAlchemy implementation, and the managed UoW; keep commit at the invocation boundary | [Persistence](#persistence-and-migrations); module repository and SqlAlchemy Module |
+| Configure startup policy or change a runtime setting | `Options[T]` for bound startup configuration; `SettingProvider`/`SettingManager` for defined runtime values and conditional updates | [Options and settings](#options-and-settings); existing Options type and Domain setting provider |
+| React to a domain change | Aggregate events and `LocalEventPhase` handlers; choose transactional or AFTER_COMMIT semantics explicitly | [Events](#events-and-background-work); aggregate and event handler in the module README |
+| Run work durably or on a schedule | Typed Job and payload, `BackgroundJobEnqueuer`, and a registered schedule when needed; Host selects the queue provider | [Background work](#events-and-background-work); existing approval Job and Application Module |
+| Own a periodic loop or SDK lifetime | Background Worker or HostedService with explicit enablement and awaited cleanup | [Background work](#events-and-background-work); module HostedService example |
+| Cache a projection or notify connected clients | `DistributedCache[T]` and realtime APIs; preserve commit order and distinguish online notification from durable delivery | [Caching](#events-and-background-work); [HTTP and realtime](#http-files-and-real-time-communication) |
+| Extend a reusable module | Existing service override or explicitly declared DTO/model extension point | [Module extensions](#extend-reusable-modules) |
+
+Follow the linked minimal example, inspect its owner and direct callers, and verify composition before adding a parallel mechanism. If an existing API cannot meet a requirement, identify the exact missing behavior and the installed source checked; propose the smallest change within the task's authorization.
+
+## Match the installed framework
+
+After the project's normal dependency setup, run these read-only lookups from `backend/`. `--no-sync` inspects the current environment without updating it:
+
+```sh
+uv run --no-sync python -c "from importlib.metadata import version; from importlib.resources import files; p = files('python_ddd_framework'); print('Version:', version('python-ddd-framework')); print('Package:', p); print('Templates:', p.joinpath('developer_kit', 'templates'))"
+uv run --no-sync pddd --help
+uv run --no-sync pddd inspect --environment development
+```
+
+Compare the installed distribution with `backend/uv.lock` and the requested dependency/source in `backend/pyproject.toml`. A mismatch needs the project's documented environment setup before API conclusions are reliable. `inspect` composes a new Application and closes it without starting resources; it does not show a running process or verify database connectivity.
+
+The printed package path locates the implementation; its `developer_kit/templates/project` and `developer_kit/templates/module` directories contain this version's guidance and examples. Read the affected API and example together, and confirm that the application declares the needed Module/provider. Treat installed files as read-only references. After an upgrade, use the target release's migration notes and update affected application guidance deliberately; copying whole templates over business code or editing the installed package is not an upgrade procedure.
 
 ## Add a module
 
@@ -181,7 +242,7 @@ For shared databases, configure installation-specific Alembic version table loca
 
 ## Events and background work
 
-Raise domain events on the aggregate. Put typed handlers in a scanned package and select the required `LocalEventPhase` with `@local_event_handler`. Use DOMAIN for transactional rules and AFTER_COMMIT for work such as the sample's cache invalidation and online notifications. Post-commit failures cannot undo a committed order; local events are not a durable message bus.
+Raise domain events on the aggregate using frozen records and stable nested values. Capture the needed IDs and values at publication; use tuples/frozensets or frozen records for collections and follow the [event value rules](architecture.md#calls-scopes-and-transactions). Put typed handlers in a scanned package and select the required `LocalEventPhase` with `@local_event_handler`. Use DOMAIN for transactional rules and AFTER_COMMIT for work such as the sample's cache invalidation and online notifications. Post-commit failures cannot undo a committed order; local events are not a durable message bus.
 
 Inject `DistributedCache[OrderCacheItem]` and call `get`, `set`, `remove`, or their batch variants with keys directly. Cache item classes in `application/caching/` own stable `@cache_name` metadata. Omitted entry options use global defaults (20-minute sliding expiration); an explicit `DistributedCacheEntryOptions` replaces the entire object. `get_or_add` uses an async factory; cache access error hiding does not hide factory/type errors or cancellation. Development configuration explicitly disables `caching.hide_errors`. Use `consider_uow=True` when a cache mutation must wait for successful UoW completion; handle post-commit failure as committed database work.
 
@@ -207,7 +268,9 @@ Background execution Options use catalog names to select `host`, `shared`, or `e
 
 Use the existing `DistributedLock` provider for explicit business leases. `locks.acquire(key, wait_timeout=timedelta(0))` tries without waiting; omit the argument or pass `None` for configured waiting, or pass a positive timedelta for this acquisition only. If acquisition returns false, skip or report the operation as appropriate. Preserve cancellation and cleanup on lease loss. Use database concurrency and idempotency for their separate guarantees.
 
-A `HostedService` manages a long-lived SDK or thread through async `start`/`stop`, including actual thread termination. Register it with `hosted_services = HostedServices((ServiceType,))`; the generated integration example is not registered by default. External threads submit through the hosted-service context, and the component owns runtime failures and recovery.
+A `HostedService` starts its SDK/thread in `start(context)`, initiates business cleanup and waits for callbacks in optional `stopping(context, reason)`, then releases resources and joins threads in `stop(reason)`. Register it with `hosted_services = HostedServices((ServiceType,))`; the generated integration example is not registered by default. It demonstrates an independent `context.call` and a thread callback using `context.submit_call(...).result()`. Each call creates its own scope; never pass a Session or scope to the thread or hold a transaction while waiting for the SDK.
+
+The stopping context is separate from the startup context, which stays closed to new work. Its permission ends when the hook returns, fails, or receives a timeout cancellation request; accepted work still drains before resource stop. Only successfully started services receive `stopping`, while every touched service must tolerate `stop` after partial startup. Each hook uses `hosted_service.shutdown_timeout`, requests cancellation on expiry, and waits for actual cleanup; it is not a total shutdown deadline. HTTP/WebSocket use native transport shutdown.
 
 ## HTTP, files, and real-time communication
 
@@ -270,6 +333,14 @@ UoW, scope or concurrently mutable payloads between tasks/threads. Host configur
 resource exit and reports timeout. Restart requires a new Application. Commands, results and
 events requiring individual processing must not declare a coalescing key.
 
+To accept SDK messages during a hosted service's stopping hook, declare
+`MessageChannelDefinition(T, Handler, stopping_owners=(ServiceType,))` and make the channel
+Module depend on the service's owner Module. Send with `await channel.send(value, stopping=context)`
+or `channel.submit(value, stopping=context)` using that hook's current context. The default empty
+tuple keeps input closed. Ordinary, expired, undeclared-owner and foreign-Application contexts
+are rejected. Already accepted messages still drain before resource stop; the permission changes
+neither capacity nor handler validation, authorization, scope/UoW or receipt semantics.
+
 ## Verification
 
 Run native uv/test/build commands from `backend/`. Installed `pddd` commands locate the backend from the application root or any descendant, including nested foreign Python projects. Read fixtures first: Host tests use disposable PostgreSQL and Redis containers, so Docker must be available.

python_ddd_framework/diagnostics/source.py

@@ -1,12 +1,25 @@
-"""贡献诊断的调用位置；depth 由公开贡献入口指定。"""
+"""诊断源码定位；区分贡献入口的调用栈与被检查定义的位置。"""
 
 from __future__ import annotations
 
 import inspect
+from typing import Any
 
 from .model import SourceLocation
 
 
+def _source_file_line(target: Any) -> tuple[str | None, int | None]:
+    """动态对象边界交给 inspect；读不到行号时仍保留已经获得的文件名。"""
+    file_name: str | None = None
+    line: int | None = None
+    try:
+        file_name = inspect.getsourcefile(target)
+        _, line = inspect.getsourcelines(target)
+    except (OSError, TypeError):
+        pass
+    return file_name, line
+
+
 def caller_source(owner: str, *, depth: int) -> SourceLocation:
     frame = inspect.currentframe()
     try:

python_ddd_framework/domain/aggregates.py

@@ -2,13 +2,11 @@
 
 from __future__ import annotations
 
-from dataclasses import is_dataclass
 from typing import Generic, TypeVar
 
-from pydantic import BaseModel
-
 from .entities import Entity
 from .errors import OptimisticConcurrencyError
+from .event_values import _is_immutable_event
 
 _TId = TypeVar("_TId")
 
@@ -32,7 +30,10 @@ class AggregateRoot(Entity[_TId], Generic[_TId]):
 
     def raise_local_event(self, event: object) -> None:
         if not _is_immutable_event(event):
-            raise TypeError("aggregate local events must be immutable dataclass or Pydantic values")
+            raise TypeError(
+                "aggregate local events must be immutable dataclass or Pydantic values "
+                "with supported stable fields"
+            )
         self._local_events.append(event)
 
     def release_local_events(self) -> tuple[object, ...]:
@@ -54,11 +55,3 @@ class AggregateRoot(Entity[_TId], Generic[_TId]):
         self._version += 1
         self._version_staged = True
         return self._version
-
-
-def _is_immutable_event(event: object) -> bool:
-    event_type = type(event)
-    dataclass_parameters = getattr(event_type, "__dataclass_params__", None)
-    if is_dataclass(event) and bool(getattr(dataclass_parameters, "frozen", False)):
-        return True
-    return isinstance(event, BaseModel) and event.model_config.get("frozen") is True

python_ddd_framework/domain/event_values.py

@@ -0,0 +1,124 @@
+"""聚合业务事件的值边界；只检查发布方的值，不复制或转换事件。"""
+
+from __future__ import annotations
+
+from collections.abc import MutableMapping, MutableSequence, MutableSet
+from dataclasses import fields, is_dataclass
+from datetime import date, datetime, time, timedelta, timezone
+from decimal import Decimal
+from enum import Enum
+from functools import cached_property
+from types import MemberDescriptorType
+from uuid import UUID
+from zoneinfo import ZoneInfo
+
+from pydantic import BaseModel
+
+_SCALAR_TYPES = frozenset(
+    {type(None), bool, int, float, str, bytes, Decimal, UUID, date, timedelta}
+)
+_ENUM_STATE = frozenset({"_name_", "_value_", "_sort_order_", "__objclass__"})
+_MISSING = object()
+
+
+def _is_immutable_event(event: object) -> bool:
+    if isinstance(event, type) or not (is_dataclass(event) or isinstance(event, BaseModel)):
+        return False
+    # 路径上的重复对象是循环；已完成的共享子值可复用检查结果。显式栈不受递归深度限制。
+    pending: list[tuple[object, bool]] = [(event, False)]
+    active: set[int] = set()
+    checked: dict[int, object] = {}
+    while pending:
+        value, leaving = pending.pop()
+        identity = id(value)
+        if leaving:
+            active.remove(identity)
+            checked[identity] = value
+            continue
+        if identity in active:
+            return False
+        if identity in checked:
+            continue
+        children = _stable_children(value)
+        if children is None:
+            return False
+        active.add(identity)
+        pending.append((value, True))
+        pending.extend((child, False) for child in reversed(children))
+    return True
+
+
+def _stable_children(value: object) -> tuple[object, ...] | None:
+    value_type = type(value)
+    # 只接受原生标量；其子类可能带有可变实例状态。枚举在下面单独检查。
+    if value_type in _SCALAR_TYPES:
+        return ()
+    if value_type in (datetime, time) and isinstance(value, (datetime, time)):
+        return () if type(value.tzinfo) in (type(None), timezone, ZoneInfo) else None
+    # frozen 只拦截属性赋值；容器子类的内部存储不在 dataclass 字段中，必须先拒绝。
+    if isinstance(value, (MutableMapping, MutableSequence, MutableSet)):
+        return None
+    if isinstance(value, Enum):
+        return None if _has_extra_state(value, _ENUM_STATE) else (value.value,)
+    if type(value) in (tuple, frozenset) and isinstance(value, (tuple, frozenset)):
+        return tuple(value)
+    if isinstance(value, tuple):
+        names = getattr(value_type, "_fields", None)
+        if (
+            isinstance(names, tuple)
+            and len(names) == len(value)
+            and all(isinstance(name, str) for name in names)
+            and not hasattr(value, "__dict__")
+            and not _has_extra_state(value, frozenset(names))
+        ):
+            return tuple(value)
+        return None
+    if isinstance(value, BaseModel):
+        return _model_values(value)
+    return _dataclass_values(value)
+
+
+def _dataclass_values(value: object) -> tuple[object, ...] | None:
+    if isinstance(value, type) or not is_dataclass(value):
+        return None
+    # 未装饰的派生类会继承 dataclass 标记，却可通过普通 setattr 增加新状态。
+    parameters = vars(type(value)).get("__dataclass_params__")
+    if getattr(parameters, "frozen", False) is not True:
+        return None
+    names = tuple(field.name for field in fields(value))
+    if _has_extra_state(value, frozenset(names)):
+        return None
+    return tuple(getattr(value, name, _MISSING) for name in names)
+
+
+def _model_values(value: BaseModel) -> tuple[object, ...] | None:
+    model_type = type(value)
+    # frozen 不保护 PrivateAttr/extra/cached_property；字段检查不能替代这些形态约束。
+    if (
+        model_type.model_config.get("frozen") is not True
+        or model_type.model_config.get("extra") == "allow"
+        or model_type.__private_attributes__
+        or value.__pydantic_extra__
+        or value.__pydantic_private__
+    ):
+        return None
+    names = frozenset(model_type.model_fields)
+    if _has_extra_state(value, names, slots=names | frozenset(BaseModel.__slots__)):
+        return None
+    return tuple(getattr(value, name, _MISSING) for name in model_type.model_fields)
+
+
+def _has_extra_state(
+    value: object, names: frozenset[str], *, slots: frozenset[str] | None = None
+) -> bool:
+    state = getattr(value, "__dict__", {})
+    if not isinstance(state, dict) or state.keys() - names:
+        return True
+    allowed_slots = names if slots is None else slots
+    # 同时检查继承的 slot 和缓存描述符，避免漏掉不在字段元数据中的可变状态。
+    return any(
+        isinstance(member, cached_property)
+        or (isinstance(member, MemberDescriptorType) and name not in allowed_slots)
+        for base in type(value).__mro__
+        for name, member in vars(base).items()
+    )