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

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

@@ -1,98 +1,31 @@
-"""模块贡献自己的服务与任务；provider 选择留给 Host。"""
+"""应用层拥有用例编排；按真实业务需要声明能力依赖，provider 由 Host 选择。"""
 
-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 modules.{{ cookiecutter.module_name }}.application_contracts.module import {{ cookiecutter.class_prefix }}ApplicationContractsModule
 
 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,
-        CachingModule,
-        BackgroundExecutionModule,
-        LocalEventsModule,
-    )
+    dependencies = ({{ cookiecutter.class_prefix }}DomainModule, {{ cookiecutter.class_prefix }}ApplicationContractsModule)
     scan_packages = (__package__,)
-    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,
-        )
+        # 注册服务和普通 Options；业务执行留在所属能力。
+        pass
 
     def post_configure(self, context: PostConfigureContext) -> None:
         # 读取已冻结 PreOptions，补充 Options 或覆盖已有服务注册。

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

@@ -4,8 +4,6 @@ from modules.{{ cookiecutter.module_name }}.domain_shared.module import {{ cooki
 
 from python_ddd_framework import (
     AppModule,
-    SettingsModule,
-    DataSeedingModule,
     ConfigureContext,
     InitializeContext,
     PostConfigureContext,
@@ -17,7 +15,7 @@ from python_ddd_framework import (
 
 
 class {{ cookiecutter.class_prefix }}DomainModule(AppModule):
-    dependencies = ({{ cookiecutter.class_prefix }}DomainSharedModule, SettingsModule, DataSeedingModule)
+    dependencies = ({{ cookiecutter.class_prefix }}DomainSharedModule,)
     scan_packages = (__package__,)
 
     def pre_configure(self, context: PreConfigureContext) -> None:

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

@@ -1,8 +1,7 @@
-"""共享层只发布业务常量与权限，不引用基础设施。"""
+"""共享层拥有跨层契约值；按实际声明增加能力依赖，不预设业务规则。"""
 
 from python_ddd_framework import (
     AppModule,
-    AuthorizationModule,
     ConfigureContext,
     InitializeContext,
     PostConfigureContext,
@@ -14,7 +13,7 @@ from python_ddd_framework import (
 
 
 class {{ cookiecutter.class_prefix }}DomainSharedModule(AppModule):
-    dependencies = (AuthorizationModule,)
+    dependencies = ()
     scan_packages = (__package__,)
 
     def pre_configure(self, context: PreConfigureContext) -> None:

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

@@ -1,21 +1,6 @@
-"""自动服务暴露与手写路由共用正式认证／REQUEST 管线。"""
+"""HTTP 仅暴露本模块公开契约；空契约不产生业务端点。"""
 
-from dishka import Scope
-from modules.{{ cookiecutter.module_name }}.application_contracts.module import (
-    {{ cookiecutter.class_prefix }}ApplicationContractsModule,
-)
-from modules.{{ cookiecutter.module_name }}.application_contracts.services.order_approval_service import (
-    {{ cookiecutter.class_prefix }}ApprovalApplicationService,
-)
-from modules.{{ cookiecutter.module_name }}.application_contracts.services.order_management_service import (
-    {{ cookiecutter.class_prefix }}ManagementApplicationService,
-)
-from modules.{{ cookiecutter.module_name }}.application_contracts.services.order_query_service import (
-    {{ cookiecutter.class_prefix }}QueryApplicationService,
-)
-from modules.{{ cookiecutter.module_name }}.http_api.filters.export_filter import ExportFilter
-from modules.{{ cookiecutter.module_name }}.http_api.routers.order_files import router as files_router
-from modules.{{ cookiecutter.module_name }}.http_api.websockets.order_socket import router as realtime_router
+from modules.{{ cookiecutter.module_name }}.application_contracts.module import {{ cookiecutter.class_prefix }}ApplicationContractsModule
 
 from python_ddd_framework import (
     AppModule,
@@ -27,60 +12,21 @@ from python_ddd_framework import (
     PreInitializeContext,
     ShutdownContext,
 )
-from python_ddd_framework.fastapi import (
-    ApplicationServiceRouteOverride,
-    FastApiRealtimeModule,
-    contributes_routers,
-    exposes_application_services,
-)
 
+from python_ddd_framework.fastapi import FastApiModule, exposes_application_services
 
-@contributes_routers(files_router, realtime_router)
-@exposes_application_services(
-    {{ cookiecutter.class_prefix }}ApplicationContractsModule,
-    overrides=(
-        ApplicationServiceRouteOverride(
-            service={{ cookiecutter.class_prefix }}QueryApplicationService,
-            method={{ cookiecutter.class_prefix }}QueryApplicationService.get,
-            path="{{ cookiecutter.http_service_path }}/{id}",
-            operation_id="{{ cookiecutter.http_operation_prefix }}get",
-        ),
-        ApplicationServiceRouteOverride(
-            service={{ cookiecutter.class_prefix }}QueryApplicationService,
-            method={{ cookiecutter.class_prefix }}QueryApplicationService.get_list,
-            path="{{ cookiecutter.http_service_path }}",
-            operation_id="{{ cookiecutter.http_operation_prefix }}get_list",
-        ),
-        ApplicationServiceRouteOverride(
-            service={{ cookiecutter.class_prefix }}ManagementApplicationService,
-            method={{ cookiecutter.class_prefix }}ManagementApplicationService.create,
-            path="{{ cookiecutter.http_service_path }}",
-            operation_id="{{ cookiecutter.http_operation_prefix }}create",
-        ),
-        ApplicationServiceRouteOverride(
-            service={{ cookiecutter.class_prefix }}ApprovalApplicationService,
-            method={{ cookiecutter.class_prefix }}ApprovalApplicationService.approve,
-            path="{{ cookiecutter.http_service_path }}/{id}/approve",
-            operation_id="{{ cookiecutter.http_operation_prefix }}approve",
-        ),
-        ApplicationServiceRouteOverride(
-            service={{ cookiecutter.class_prefix }}ApprovalApplicationService,
-            method={{ cookiecutter.class_prefix }}ApprovalApplicationService.queue_approval,
-            path="{{ cookiecutter.http_service_path }}/{id}/queue-approval",
-            operation_id="{{ cookiecutter.http_operation_prefix }}queue_approval",
-        ),
-    ),
-)
+
+@exposes_application_services({{ cookiecutter.class_prefix }}ApplicationContractsModule)
 class {{ cookiecutter.class_prefix }}HttpApiModule(AppModule):
-    dependencies = (FastApiRealtimeModule,)
+    dependencies = (FastApiModule,)
 
     def pre_configure(self, context: PreConfigureContext) -> None:
         # 贡献影响后续注册的 PreOptions；此阶段不启动资源。
         pass
 
     def configure(self, context: ConfigureContext) -> None:
-        # 组装扩展：在这里注册 HTTP 层自己的 Filter 等依赖；新路由通过上方 Module 声明接入。
-        context.services.add_scoped(ExportFilter, scope=Scope.REQUEST)
+        # 注册服务和普通 Options；业务执行留在所属能力。
+        pass
 
     def post_configure(self, context: PostConfigureContext) -> None:
         # 读取已冻结 PreOptions，补充 Options 或覆盖已有服务注册。

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

@@ -1,7 +1,6 @@
 """provider 依赖领域契约；Host 显式选择此实现。"""
 
 from modules.{{ cookiecutter.module_name }}.domain.module import {{ cookiecutter.class_prefix }}DomainModule
-from modules.{{ cookiecutter.module_name }}.domain_shared.constants.order_constants import MODULE_NAME
 from modules.{{ cookiecutter.module_name }}.sqlalchemy.models.base import {{ cookiecutter.class_prefix }}Base
 
 from python_ddd_framework import (
@@ -26,7 +25,7 @@ from python_ddd_framework.sqlalchemy import (
         models_package=__package__ + ".models",
         metadata={{ cookiecutter.class_prefix }}Base.metadata,
         migrations_package=__package__ + ".migrations",
-        branch_label=MODULE_NAME,
+        branch_label="{{ cookiecutter.module_name }}",
     )
 )
 class {{ cookiecutter.class_prefix }}SqlAlchemyModule(AppModule):

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

@@ -5,22 +5,37 @@ These instructions apply to this application and its business modules. Follow th
 ## Start with the affected capability
 
 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.
+2. Read the applicable project requirements and accepted decisions, then [architecture](docs/architecture.md) for ownership and dependencies and the relevant section of [development](docs/development.md) for framework usage. Use [README](README.md) for setup and operations. This reading order is required before implementation; reuse existing conclusions for a small change.
+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, CLI, and any user-provided source reference. Check the consumed artifact before relying on a checkout; equal version numbers do not prove identical contents. 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/`.
 
+Use the [official CLI entry points](docs/development.md#cli-operations) for operations it provides, including project/module generation, development startup, infrastructure preparation, migrations, seeding, and inspection. Do not replace them with handwritten generation or direct calls to migration/seed internals. Build and test still use native tools.
+
+## 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 DDD skeleton supplies structure without business rules; documentation recipes are illustrations, and actual 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. Before the first edit, identify **Owner -> layer -> target directory -> verified framework API**, with the relevant requirement and source/example evidence, using the [design and delivery checks](docs/development.md#design-and-delivery-checks). Choose the existing `basic` or `ddd` layout using the [directory rules](docs/development.md#module-layout-and-coding-rules), then map needed capabilities through the [framework selection table](docs/development.md#choose-a-framework-capability). Check the installed API, Module declarations, and existing usage before implementing. Mark an API check as not applicable when appropriate; do not invent an abstraction to fill the record.
+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.
 - Domain and application contracts stay independent of Host, HTTP, and persistence implementations. Cross-module calls use explicitly declared dependencies and public contracts; do not access another module's implementation, ORM models, or tables directly.
 - Use framework application services, repositories, Options, permissions, units of work, events, jobs, and lifecycle hooks before adding custom infrastructure. Do not introduce a parallel DI container, service locator, transaction manager, or wrapper without a missing business capability.
 - Keep public contracts, mutable state, orchestration, and external I/O under clear owners. Split for independent responsibilities, not a fixed line count. Avoid generic `common`, `utils`, or `helpers` collections and speculative abstractions.
-- Resolve conflicting requirements, documented contracts, and implementation before changing the affected boundary. Describe the conflict to the user; do not rewrite documentation to justify an unapproved design.
+- If requirements, accepted decisions, documented responsibilities/contracts, an approved plan, or implementation conflict, pause affected edits and commits. Present both statements with file locations, current behavior, impact, and the decision needed from the user. Obtain an explicit ruling before proceeding; silence or a general instruction to continue does not resolve an unstated boundary change. Never rewrite documentation to retroactively authorize an incorrect implementation.
 - Confirm changes to dependencies, public contracts, persistent data, external protocols, or deployment infrastructure when they extend beyond the requested task. Internal simplification does not authorize breaking consumers or stored data.
 
-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.
+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 retains the full responsibility directories, package markers, Module hooks, ORM Base, and model/migration registration. It generates no business implementations or test cases; this directory 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.
+
+Code and architecture changes must also satisfy the [seven design principles](docs/architecture.md#mandatory-design-principles). Review the applicable principles, DDD boundaries, imports, contracts, state ownership, and resource lifetimes on the final diff. Follow the [delivery checks](docs/development.md#design-and-delivery-checks) and cite actual evidence. Correct confirmed violations within the authorized scope or report the blocking decision; passing builds/tests alone cannot justify completion. These requirements do not authorize new business rules, dependencies, tests, automated gates, infrastructure, or framework changes.
 
 ## Use the framework safely
 
@@ -28,8 +43,8 @@ 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 transactions short. Never carry a business Session or UoW across a network wait or stream `yield`, or transfer execution scopes into ordinary child tasks or external threads. Managed HTTP streaming retains only its transport-owned REQUEST until cleanup; follow the [streaming boundaries](docs/architecture.md#http-streaming-and-continuous-access) and [complete example](docs/development.md#http-generators-and-continuous-access).
+- 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.
@@ -51,7 +66,7 @@ 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.
-- Use the smallest relevant existing checks, and add focused regression coverage when the requested behavior needs it. Read fixtures before running tests that start infrastructure. See [verification](docs/development.md#verification) for available commands.
+- Use the smallest relevant existing checks and authorized build. New test files, cases, or test dependencies require explicit approval; explain their scope and verification benefit first. Read fixtures before running infrastructure tests and keep them within the task's authorization. See [verification](docs/development.md#verification) for available commands.
 - Distinguish source checks, unit tests, real infrastructure tests, and distribution validation. Report actual results and anything not verified; never claim success from a mock or an unexecuted command.
 - Update the owning module README when business rules or public behavior change. Update architecture for dependency or ownership changes, development for usage changes, and README for setup or operations changes. Replace outdated statements rather than appending a work log.
 - Documentation guides development; it is not an executable architecture gate. Use type checks and appropriate boundary tests when the project has them.

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

@@ -1,12 +1,12 @@
 # {{ cookiecutter.project_name }}
 
-A modular Python application generated with Python DDD Framework {{ cookiecutter.framework_version }}. The initial project contains a Host; add business modules with `pddd add module` and adapt their examples to your requirements.
+A modular Python application generated with Python DDD Framework {{ cookiecutter.framework_version }}. The initial project contains a Host; add business modules with `pddd add module` and implement their business behavior from confirmed requirements.
 
 | Document | Purpose |
 | --- | --- |
-| [AGENTS.md](AGENTS.md) | Development instructions and reading order for Codex and other contributors. |
-| [Architecture](docs/architecture.md) | Ownership, dependency direction, transaction boundaries, and lifecycle guarantees. |
-| [Development guide](docs/development.md) | Recipes for services, permissions, persistence, configuration, events, and background work. |
+| [AGENTS.md](AGENTS.md) | Mandatory reading, implementation, and delivery checks for Codex and other contributors. |
+| [Architecture](docs/architecture.md) | Design principles, DDD ownership, dependency direction, transactions, streaming, and lifecycle boundaries. |
+| [Development guide](docs/development.md) | CLI entry points, artifact/source lookup, design checks, and framework usage recipes. |
 
 Each generated business module also has its own README under `backend/src/modules/<name>/`. This README owns application setup and operations.
 
@@ -26,14 +26,14 @@ pddd dev-init
 
 This starts or reuses PostgreSQL and Redis from the Host's development configuration and preserves data. It does not start the application, migrate, seed, or create an `.env` file. The bundled Compose setup requires local URLs with explicit ports; its Redis service does not configure authentication or TLS.
 
-To add the example business module:
+To add a DDD skeleton or a minimal ordinary service:
 
 ```sh
 pddd add module orders --template ddd
 pddd add module conversions --template basic
 ```
 
-Read `backend/src/modules/orders/README.md` before changing the sample. The project is also usable as a pure Host without this step.
+The `orders` name here selects a package, not an order implementation. Read `backend/src/modules/orders/README.md` before adding business code; all responsibility directories are present, but no business service, table, route, or test is generated. The project is also usable as a pure Host without this step.
 
 ## Initialize the database
 
@@ -47,13 +47,13 @@ pddd db upgrade --module background_jobs
 pddd db seed --module identity
 ```
 
-If you added `orders`, generate its first revision:
+After implementing actual models in a DDD module named `orders`, generate its first revision. An empty skeleton retains model and migration registration but has no business tables or revisions. Migration commands still use the configured database:
 
 ```sh
 pddd db revision --module orders
 ```
 
-Review the generated file in `backend/src/modules/orders/sqlalchemy/migrations/`, then apply and seed it:
+Review the generated file in `backend/src/modules/orders/sqlalchemy/migrations/`, then apply it; run seed only when that module declares the intended contributors:
 
 ```sh
 pddd db upgrade --module orders
@@ -75,7 +75,7 @@ Open **http://127.0.0.1:8000/docs**. Call `/api/auth/login` using the generated
 
 Identity includes paged user/role management, password operations, and version-protected assignments. Before using it, apply the framework's Identity migrations; preserve the returned `concurrency_version` in updates. See [Identity management](docs/development.md#identity-management) for API usage, session invalidation, and Host authorization options.
 
-With the `orders` example installed, `/api/orders` supports create/query, `/api/orders/{id}/approve` approves an order, and `/api/orders/{id}/queue-approval` enqueues approval. Read the module README for its rules and OpenAPI for request schemas. A stale version produces a conflict response.
+Adding a DDD skeleton creates no business HTTP endpoints. Implement the public contracts and use cases first, then inspect OpenAPI and update the module README with their actual behavior.
 
 `http.api_prefix` controls business HTTP addresses and defaults to `/api`; `/ws`, `/health/live`, `/health/ready`, and `/docs` retain independent paths. Readiness reports Application lifecycle state, not continuous infrastructure health.
 
@@ -95,7 +95,7 @@ uv run pytest
 uv build --no-sources
 ```
 
-The application tests include real Host infrastructure and require Docker. Module domain tests can be run separately; see [verification](docs/development.md#verification). Module tests are excluded from production wheels and service discovery.
+The application tests include real Host infrastructure and require Docker. A DDD skeleton has no test cases; after authorized domain tests exist, run them separately; see [verification](docs/development.md#verification). Module tests are excluded from production wheels and service discovery.
 
 ## Deploy
 
@@ -135,3 +135,15 @@ uv build --no-sources
 ```
 
 A framework upgrade does not regenerate or overwrite application source, migrations, or these documents. A global CLI upgrade also does not update this project. Apply required adaptations and update the relevant application and module documentation deliberately.
+
+<a id="streaming-and-access-migration-07-unreleased"></a>
+
+### Streaming and access migration (0.7)
+
+These notes describe the current 0.7.0 implementation; they are not a release announcement. Check the consumed artifact using [installed framework lookup](docs/development.md#match-the-installed-framework) before using these APIs.
+
+- Move `fastapi_realtime.authentication_refresh_seconds` to `fastapi_access.authentication_refresh_seconds` in existing environment files and deployment overrides. Rename `PDDD_FASTAPI_REALTIME__AUTHENTICATION_REFRESH_SECONDS` to `PDDD_FASTAPI_ACCESS__AUTHENTICATION_REFRESH_SECONDS` when set. The old realtime field is rejected. `FastApiAccessOptions` belongs to `FastApiModule` and covers managed HTTP streams and WebSocket connections; its default is 60 seconds and minimum is 1. An omitted section uses these defaults; generation does not need an extra configuration block.
+- Existing HTTP streaming code must follow the [preparation, transmission, and cleanup boundaries](docs/architecture.md#http-streaming-and-continuous-access). The [complete generator example](docs/development.md#http-generators-and-continuous-access) demonstrates native SSE, JSONL, and byte streaming. Keep ApplicationService return contracts unchanged and move checks that need ordinary error responses into preparation.
+- `run_host(..., timeout_graceful_shutdown=10)` forwards a non-negative integer number of seconds to Uvicorn. At the deadline Uvicorn requests cancellation; framework drain still waits for streams, subscriptions, and REQUEST resources to actually release. This is not a hard process-exit deadline. A synchronous generator's running `next()` must return; its thread is not abandoned. Applications running Uvicorn directly must configure its native timeout themselves.
+
+Review applicable [design principles](docs/architecture.md#mandatory-design-principles) and [delivery checks](docs/development.md#design-and-delivery-checks) when adapting existing consumers. Template examples do not authorize application business, schema, dependency, or infrastructure changes.

python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/backend/src/host/main.py.jinja

@@ -31,10 +31,13 @@ def create_application(
 def create_web() -> FastAPI:
     # HTTP 组装扩展：在这里设置站点信息和 Host middleware，并在 install 前完成需要的配置。
     application = create_application()
+    api_prefix = application.configuration.get_path("http.api_prefix")
+    if not isinstance(api_prefix, str):
+        raise TypeError("http.api_prefix must be a string")
     # 全局 middleware 使用原生 Starlette 实现，在 adapter.install 前完成配置。
     adapter = FastApiAdapter(
         application, middleware=(Middleware(GZipMiddleware),),
-        api_prefix=application.configuration.get_path("http.api_prefix"),
+        api_prefix=api_prefix,
     )
     web = FastAPI(
         title="{{ cookiecutter.project_name }}", version=version("{{ cookiecutter.project_name }}"), lifespan=adapter.lifespan

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

@@ -6,7 +6,7 @@ This application was generated with Python DDD Framework {{ cookiecutter.framewo
 
 ## Composition and ownership
 
-The initial project is a Host without business modules. `pddd add module <name>` adds an example module that the application team adapts to its domain. Generated order-management behavior is a sample, not a declaration of the application's business requirements.
+The initial project is a Host without business modules. `pddd add module <name>` adds a DDD skeleton with the full responsibility directories and necessary composition. Business rules, services, tables, endpoints, and tests are added only from confirmed requirements; no order example is generated.
 
 | Owner | Responsibility |
 | --- | --- |
@@ -51,9 +51,37 @@ Immutable values shared by domain objects and public DTOs belong in `domain_shar
 
 Cross-module access uses public service contracts and explicit Module dependencies. A module owns its own data and migrations. Shared database deployment does not authorize another module to query its tables. Keep internal collaboration contracts separate from end-user service contracts where the caller and authorization semantics differ; `IntegrationService` requires its own contract and is not exposed over HTTP.
 
-The [development guide](development.md#module-layout-and-coding-rules) owns the complete directory and naming rules. Query, management, approval, and optional item operations have separate user-facing contracts. Internal reporting belongs to a separate integration contract and implementation. HTTP keeps its existing paths and operation identities through public route overrides when Python services move.
+The [development guide](development.md#module-layout-and-coding-rules) owns the complete directory and naming rules. When those use cases exist, separate query, management, approval, and item contracts by caller needs. Internal reporting uses a separate integration contract and implementation when its caller and authorization boundary differ. HTTP keeps its existing paths and operation identities through public route overrides when Python services move.
 
-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.
+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`. The skeleton has no workers, hosted services, or schedules to enable.
+
+## Mandatory design principles
+
+Apply all seven principles that are relevant to a code or architecture change during implementation and review, together with the DDD rules below. An abstraction must serve a real responsibility, public contract, variation point, or reuse need. Counts of files, classes, or interfaces are not evidence of good design.
+
+| Principle | Required implementation and review behavior |
+| --- | --- |
+| Single responsibility | Organize by stable capability, owner, and reason to change. Give public contracts/values, mutable state, orchestration, external I/O, and resource lifecycles explicit owners. Split independent responsibilities; related immutable values, enums, and exceptions may remain together. Do not centralize unrelated state or lifetimes in a generic service. |
+| Open/closed | Use existing Module declarations, DI, and native extension points for implementations that satisfy the current contract. Avoid accumulating provider branches in core use cases. A business-semantic change still needs contract review and authorization; do not anticipate hypothetical changes with plugin layers or compatibility paths. |
+| Liskov substitution | Implementations of a contract must preserve its preconditions, postconditions, and invariants, including errors, cancellation, idempotency, and cleanup. Do not require stronger inputs, weaken outcomes, or return success for unsupported behavior. Review replacements against the caller's contract, not just their signatures. |
+| Interface segregation | Separate public contracts by caller use case, permissions, and lifecycle needs. A caller should depend only on the capability it needs. Avoid an all-purpose service interface and mechanical one-method interfaces. |
+| Dependency inversion | Domain and use cases depend on contracts owned by the relevant capability; persistence and external integrations implement those boundaries. The Host selects providers and composes them. Domain/Contracts must not depend on Host, HTTP, or concrete persistence. Reuse framework abstractions directly. |
+| Law of Demeter | Obtain facts and request operations through direct collaborators' public contracts. Do not reach through another module into its implementation, ORM, tables, or mutable internals. Aggregate changes pass through the root. Do not add a forwarding facade merely to shorten a call chain. |
+| Composition reuse | Prefer injected collaborators, composition, and existing framework capabilities. Use inheritance for a real type relationship or native extension point. Avoid base classes combining permissions, transactions, domain state, and external communication. |
+
+State belongs to its domain or runtime owner; orchestration coordinates those owners without absorbing their rules. A lifecycle owner must await actual release of its resources. The Host remains a composition root, and stable contracts never depend back on orchestration or infrastructure. Use a class for identity, state, lifecycle, ownership, or a real variation point; keep a stateless internal algorithm private to its capability. These constraints do not require extra layers, wrappers, or unused interfaces. Record and review changes using the [design and delivery checks](development.md#design-and-delivery-checks).
+
+## Mandatory DDD rules
+
+These constraints apply when a capability models aggregates. The module README owns its actual business language and invariants; documentation examples do not define its 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
 
@@ -67,8 +95,30 @@ 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.
+
+## HTTP streaming and continuous access
+
+`HttpRouter` supports synchronous and asynchronous generator endpoints with native FastAPI SSE, JSONL, and `StreamingResponse`. ApplicationService methods retain their existing return contract: they may return a native streaming Response, but do not become generator methods. Native FastAPI/Starlette own encoding and transmission; the framework manages invocation and resource boundaries.
+
+| Phase | Owner and invariant |
+| --- | --- |
+| Preparation | Authorization precedes input binding. Dependencies and Filters perform checks and short business calls needed before sending. Function-scoped dependencies exit, business work commits, and preparation ACTION/UoW resources are released before transmission. The framework does not read the first generator item here; code before the first `yield` still runs during iteration. |
+| Transmission | The HTTP transport owner retains REQUEST and supervises production, sending, and access checks. Framework-supervised reads receive the owning task's request identity and invocation permission, without inheriting preparation ACTION/UoW state. Further database work uses an independent short service call or UoW that ends before `yield`. Ordinary child tasks and external threads do not gain that permission. |
+| Cleanup | After production exits, close the source, release preparation subscriptions, and then release REQUEST. Acquire subscriptions through a native request-scoped yield dependency so they are released even if the response generator never starts. Its unstarted `finally` cannot own a subscription acquired elsewhere. Repeated cancellation must not end the wait for actual cleanup; cleanup failures retain their cause. A synchronous generator's running `next()` must eventually return. |
+
+Never carry a business Session, transaction, or AnyIO cancellation scope across a response `yield`. A generator's asynchronous `finally` must shield its own awaited cleanup locally; framework-managed close does not protect arbitrary awaits inside an already-unwinding generator. See the [complete example](development.md#http-generators-and-continuous-access).
+
+Managed HTTP streams with authorization requirements check access before sending and periodically afterwards, including while idle or blocked by a slow client. Each check uses an independent short REQUEST, refreshes identity and permissions, and releases its services/UoW before returning. HTTP authenticators and permission checkers can inject the native `Request` and make short managed calls; they do not share the long request's cached services or transaction. Checks for one connection are serialized; a due send waits for the check. User/session changes invalidate access. Failure is recorded before sending is cancelled; WebSocket transport also discards queued business frames. WebSocket continuous checks concern its connection endpoint declarations, while `invoke` authorizes each service call separately without accumulating historical permissions.
+
+Routes with no authorization requirement or `allow_anonymous` do not opt into HTTP continuous access checks. Shared authorization short-circuits these cases and `authorization.always_allow` before reading the final identity. `always_allow` does not fabricate a user or accept an invalid token; authentication and real-user requirements remain active. An authenticator may call managed methods admitted by these short-circuits, but reading final `CurrentUser` during authentication still raises the authentication-cycle error. An endpoint-injected `CurrentUser` remains its immutable preparation snapshot; new short calls during streaming use the latest checked snapshot.
+
+Actual `http.response.start` is the error boundary. Before it, preparation/access failures can use normal error handlers. After it, terminate and record the failure; do not attempt a replacement JSON response. Shared refresh configuration and Host shutdown timeout belong to [README operations and migration](../README.md#streaming-and-access-migration-07-unreleased).
+
 ## 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.
@@ -100,12 +150,12 @@ Module initialization precedes selected hosted services and background execution
 ## Background work and external boundaries
 
 - 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.
+- Periodic workers are explicitly registered. No workers are generated. When adding one, configuration cannot enable a worker disabled in its class declaration.
 - 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. 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.
+- WebSocket delivery targets currently connected clients. The native process-local transport has no cross-process backplane, offline replay, or delivery acknowledgment. HTTP streams follow the [preparation, transmission, and cleanup boundaries](#http-streaming-and-continuous-access).
 - Liveness and readiness report lifecycle state, not continuous infrastructure availability. Trace export is disabled in the generated development configuration until explicitly configured.
 
 ## Documentation ownership