python-ddd-framework 0.6.0__tar.gz → 0.7.0__tar.gz

{python_ddd_framework-0.6.0 → python_ddd_framework-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-ddd-framework
-Version: 0.6.0
+Version: 0.7.0
 Summary: Modular DDD application framework with project CLI and bundled templates
 License-Expression: LicenseRef-Proprietary
 License-File: LICENSE
@@ -127,28 +127,33 @@ pddd add module conversions --template basic
 
 `dev-init` starts or reuses local PostgreSQL and Redis using `backend/app.development.yaml`. It preserves existing data; database migration and seeding are separate steps.
 
-`add module orders` generates an order-management example and registers it with the Host. The example includes an aggregate, service contracts, application services, persistence, HTTP endpoints, module tests, and a module README describing its actual behavior and boundaries.
+`add module orders` generates a DDD skeleton named `orders` and registers its Application, SQLAlchemy, and HttpApi Modules with the Host. It retains all responsibility directories, package markers, lifecycle hooks, ORM Base, model discovery, migration registration, and a module README. It creates no business entities, services, tables, endpoints, tasks, or test cases. Add them from confirmed requirements. The former order implementation is available as a separate [order-management example](examples/order_management/README.md), outside the runtime wheel.
 
 `ddd` is the default six-layer template. `basic` generates only a Module, a synchronous Protocol service, its transient implementation, and an English README. It has no database/Redis requirement or implicit HTTP/interception. Both templates support `--dry-run` and refuse existing targets.
 
 ### 3. Initialize the database
 
-Apply the provider migrations selected by the generated Host, then generate the business module's first migration:
+Apply the provider migrations selected by the generated Host:
 
 ```sh
 pddd db upgrade --module identity
 pddd db upgrade --module settings
 pddd db upgrade --module auditing
 pddd db upgrade --module background_jobs
+pddd db seed --module identity
+```
+
+An empty DDD skeleton retains model and migration registration but has no business tables or revisions. Add actual models before generating a business revision; migration commands still use the configured database. For a module named `orders`:
+
+```sh
 pddd db revision --module orders
 ```
 
-Review the generated revision in `backend/src/modules/orders/sqlalchemy/migrations/` before applying it. Then upgrade and seed:
+Review the generated revision in `backend/src/modules/orders/sqlalchemy/migrations/` before applying it. Run seed only after declaring the intended contributors:
 
 ```sh
 pddd db upgrade --module orders
 pddd db status --module orders
-pddd db seed --module identity
 pddd db seed --module orders
 ```
 
@@ -162,7 +167,7 @@ pddd dev
 
 Open **http://127.0.0.1:8000/docs**. Use the generated `identity.seed_admin_username` and `identity.seed_admin_password` in `backend/app.development.yaml` to call `/api/auth/login`, then enter the returned access token in Swagger's **Authorize** dialog.
 
-With the `orders` module installed, you can create and query orders at `/api/orders`, approve an order at `/api/orders/{id}/approve`, and enqueue approval at `/api/orders/{id}/queue-approval`. Swagger shows the request schemas and all available operations. The example also includes file transfer and an authenticated WebSocket endpoint at `/ws/orders`.
+The empty `orders` skeleton contributes no business routes. The independent [order-management example](examples/order_management/README.md) supplies `/api/orders`, approval and queued approval, file transfer, and an authenticated WebSocket at `/ws/orders`; use its initializer when you want to explore those capabilities.
 
 The default business API prefix is `/api`. Liveness and readiness are exposed at `/health/live` and `/health/ready`; readiness describes application lifecycle state, not continuous database or Redis health.
 
@@ -295,6 +300,22 @@ The image uses `python -m host.main` without development reload. Runtime install
 
 <a id="版本与升级"></a>
 
+### DDD skeleton generation (0.7)
+
+New `ddd` modules contain the full responsibility directories and necessary composition, with no preset business code or tests. `basic` is unchanged. This affects subsequent generation only: upgrades do not delete or rewrite existing consumers' order code. Keep existing business contracts and data under their application owners. The former order implementation and its existing domain test now live in [the independent example](examples/order_management/README.md); its initializer uses the official CLI, requires a new destination, and is not bundled in the runtime wheel. No CLI parameter or dependency has been added.
+
+<a id="streaming-and-access-migration-07-unreleased"></a>
+
+## Streaming and access migration (0.7)
+
+- Move `fastapi_realtime.authentication_refresh_seconds` to `fastapi_access.authentication_refresh_seconds`. The shared `FastApiAccessOptions` applies to managed HTTP streams and WebSocket connections; its default is 60 seconds and minimum is 1. The old realtime field is rejected.
+- HTTP endpoints on `HttpRouter` can directly yield synchronous or asynchronous values using native FastAPI SSE, JSONL, or `StreamingResponse`. Keep checks required before the response starts in preparation dependencies or Filters. Authorization precedes binding; function dependencies, commit, and business resource cleanup finish before sending. The framework does not read the first item during preparation. Application services keep their existing return contract and may return a native streaming Response.
+- Register subscriptions acquired during preparation with a native request-scoped yield dependency. An unstarted generator's `finally` cannot release those subscriptions. Database work in preparation or during iteration must use an independent short service call or UoW and finish before yielding data. Generator cleanup that awaits must shield its own `finally`, without holding a cancellation scope across `yield`.
+- Streams with authorization declarations automatically recheck identity and endpoint permissions, including while idle or blocked on a slow client. Anonymous declarations retain their meaning. WebSocket `invoke` continues to authorize each service call separately. Failed checks terminate the transport; after `http.response.start`, no replacement JSON response is sent.
+- `run_host(..., timeout_graceful_shutdown=10)` passes a non-negative integer to Uvicorn. When that period expires, cancellation is requested and framework drain still waits for actual resource release. Direct Uvicorn consumers must configure its native timeout themselves. A synchronous generator's running `next()` must eventually return; a timeout does not abandon its thread.
+
+Runnable examples: [HTTP generators](docs/development.md#http-生成器与持续访问). Verification and limitations: [0.7.0 status](docs/status.md#070-通用生成器与持续访问未发布).
+
 ## Capability module migration (0.4)
 
 Capability composition now uses the same `AppModule` model as customer modules. Existing applications must migrate their declarations together; there is no compatibility path.
@@ -452,7 +473,7 @@ Channels that must accept these callbacks declare `stopping_owners=(ServiceType,
 
 The developer-kit dependency constrains `binaryornot` to `0.5.x`, because `0.6.0` can classify bundled templates containing Chinese comments as binary and skip rendering them. Re-resolve the developer-kit environment when installing 0.4.0. Updating the dependency does not replace existing generated application code.
 
-The new `DomainService` marker uses existing constructor injection and transient REQUEST lifetime. It does not create transactions or expose HTTP endpoints. Newly generated modules place approval policy in `domain/services/order_approval_service.py`; existing projects can adopt that example explicitly after upgrading. The application checks existence and the submitted version before the domain policy; a stale or missing order therefore takes precedence over a disabled approval setting when both inputs are invalid. Domain rules, schema, and installation files are not automatically rewritten.
+The new `DomainService` marker uses existing constructor injection and transient REQUEST lifetime. It does not create transactions or expose HTTP endpoints. The independent order example places approval policy in `domain/services/order_approval_service.py`; existing projects can adopt it explicitly after upgrading. The example application checks existence and the submitted version before the domain policy; a stale or missing order therefore takes precedence over a disabled approval setting when both inputs are invalid. Domain rules, schema, and installation files are not automatically rewritten.
 
 <a id="框架更名迁移未发布"></a>
 
@@ -541,7 +562,7 @@ The engineering guides below are maintained in Chinese in the private GitHub rep
 | Check release evidence and remaining validation limits | [Status and validation](https://github.com/componet-architecture/python-ddd-framework/blob/main/docs/status.md) |
 | Change the framework itself | [Contributor guidance](https://github.com/componet-architecture/python-ddd-framework/blob/main/AGENTS.md) and [focused reading paths](https://github.com/componet-architecture/python-ddd-framework/blob/main/docs/README.md#重构的最短阅读路径) |
 
-Generated applications include a self-contained English README, `AGENTS.md`, architecture document, and development guide for their template version. `AGENTS.md` guides contributors from business rules and ownership to framework capability selection and verification. The development guide maps common tasks to framework capabilities and includes commands to locate the installed version's source and bundled examples; each DDD module README records the sample business model and traces approval through its owners. The application maintains these documents after generation; framework upgrades do not overwrite them. Existing applications can use their installed package's `developer_kit/templates` as a read-only reference when updating affected guidance, preserving their own business model and decisions.
+Generated applications include a self-contained English README, `AGENTS.md`, architecture document, and development guide for their template version. They require an owner/layer/directory/API check before implementation and a review of the seven design principles, DDD boundaries, and actual verification before delivery. The development guide provides CLI entry points, installed-artifact/source comparison, capability recipes, and a complete native HTTP generator example; architecture owns streaming/access boundaries, and the generated README owns configuration migration and shutdown operations. These instructions do not imply an automated architecture gate. Each DDD module README records the empty skeleton and guides the first authorized use case; the independent order example owns its own business documentation and acceptance source. The application maintains these documents after generation; upgrades do not overwrite them. Existing applications can use their installed package's `developer_kit/templates` as a read-only reference while preserving application rules and decisions. A user-provided framework checkout is also read-only; matching version numbers alone do not prove it matches the consumed artifact.
 
 ## License
 

{python_ddd_framework-0.6.0 → python_ddd_framework-0.7.0}/README.md

@@ -83,28 +83,33 @@ pddd add module conversions --template basic
 
 `dev-init` starts or reuses local PostgreSQL and Redis using `backend/app.development.yaml`. It preserves existing data; database migration and seeding are separate steps.
 
-`add module orders` generates an order-management example and registers it with the Host. The example includes an aggregate, service contracts, application services, persistence, HTTP endpoints, module tests, and a module README describing its actual behavior and boundaries.
+`add module orders` generates a DDD skeleton named `orders` and registers its Application, SQLAlchemy, and HttpApi Modules with the Host. It retains all responsibility directories, package markers, lifecycle hooks, ORM Base, model discovery, migration registration, and a module README. It creates no business entities, services, tables, endpoints, tasks, or test cases. Add them from confirmed requirements. The former order implementation is available as a separate [order-management example](examples/order_management/README.md), outside the runtime wheel.
 
 `ddd` is the default six-layer template. `basic` generates only a Module, a synchronous Protocol service, its transient implementation, and an English README. It has no database/Redis requirement or implicit HTTP/interception. Both templates support `--dry-run` and refuse existing targets.
 
 ### 3. Initialize the database
 
-Apply the provider migrations selected by the generated Host, then generate the business module's first migration:
+Apply the provider migrations selected by the generated Host:
 
 ```sh
 pddd db upgrade --module identity
 pddd db upgrade --module settings
 pddd db upgrade --module auditing
 pddd db upgrade --module background_jobs
+pddd db seed --module identity
+```
+
+An empty DDD skeleton retains model and migration registration but has no business tables or revisions. Add actual models before generating a business revision; migration commands still use the configured database. For a module named `orders`:
+
+```sh
 pddd db revision --module orders
 ```
 
-Review the generated revision in `backend/src/modules/orders/sqlalchemy/migrations/` before applying it. Then upgrade and seed:
+Review the generated revision in `backend/src/modules/orders/sqlalchemy/migrations/` before applying it. Run seed only after declaring the intended contributors:
 
 ```sh
 pddd db upgrade --module orders
 pddd db status --module orders
-pddd db seed --module identity
 pddd db seed --module orders
 ```
 
@@ -118,7 +123,7 @@ pddd dev
 
 Open **http://127.0.0.1:8000/docs**. Use the generated `identity.seed_admin_username` and `identity.seed_admin_password` in `backend/app.development.yaml` to call `/api/auth/login`, then enter the returned access token in Swagger's **Authorize** dialog.
 
-With the `orders` module installed, you can create and query orders at `/api/orders`, approve an order at `/api/orders/{id}/approve`, and enqueue approval at `/api/orders/{id}/queue-approval`. Swagger shows the request schemas and all available operations. The example also includes file transfer and an authenticated WebSocket endpoint at `/ws/orders`.
+The empty `orders` skeleton contributes no business routes. The independent [order-management example](examples/order_management/README.md) supplies `/api/orders`, approval and queued approval, file transfer, and an authenticated WebSocket at `/ws/orders`; use its initializer when you want to explore those capabilities.
 
 The default business API prefix is `/api`. Liveness and readiness are exposed at `/health/live` and `/health/ready`; readiness describes application lifecycle state, not continuous database or Redis health.
 
@@ -251,6 +256,22 @@ The image uses `python -m host.main` without development reload. Runtime install
 
 <a id="版本与升级"></a>
 
+### DDD skeleton generation (0.7)
+
+New `ddd` modules contain the full responsibility directories and necessary composition, with no preset business code or tests. `basic` is unchanged. This affects subsequent generation only: upgrades do not delete or rewrite existing consumers' order code. Keep existing business contracts and data under their application owners. The former order implementation and its existing domain test now live in [the independent example](examples/order_management/README.md); its initializer uses the official CLI, requires a new destination, and is not bundled in the runtime wheel. No CLI parameter or dependency has been added.
+
+<a id="streaming-and-access-migration-07-unreleased"></a>
+
+## Streaming and access migration (0.7)
+
+- Move `fastapi_realtime.authentication_refresh_seconds` to `fastapi_access.authentication_refresh_seconds`. The shared `FastApiAccessOptions` applies to managed HTTP streams and WebSocket connections; its default is 60 seconds and minimum is 1. The old realtime field is rejected.
+- HTTP endpoints on `HttpRouter` can directly yield synchronous or asynchronous values using native FastAPI SSE, JSONL, or `StreamingResponse`. Keep checks required before the response starts in preparation dependencies or Filters. Authorization precedes binding; function dependencies, commit, and business resource cleanup finish before sending. The framework does not read the first item during preparation. Application services keep their existing return contract and may return a native streaming Response.
+- Register subscriptions acquired during preparation with a native request-scoped yield dependency. An unstarted generator's `finally` cannot release those subscriptions. Database work in preparation or during iteration must use an independent short service call or UoW and finish before yielding data. Generator cleanup that awaits must shield its own `finally`, without holding a cancellation scope across `yield`.
+- Streams with authorization declarations automatically recheck identity and endpoint permissions, including while idle or blocked on a slow client. Anonymous declarations retain their meaning. WebSocket `invoke` continues to authorize each service call separately. Failed checks terminate the transport; after `http.response.start`, no replacement JSON response is sent.
+- `run_host(..., timeout_graceful_shutdown=10)` passes a non-negative integer to Uvicorn. When that period expires, cancellation is requested and framework drain still waits for actual resource release. Direct Uvicorn consumers must configure its native timeout themselves. A synchronous generator's running `next()` must eventually return; a timeout does not abandon its thread.
+
+Runnable examples: [HTTP generators](docs/development.md#http-生成器与持续访问). Verification and limitations: [0.7.0 status](docs/status.md#070-通用生成器与持续访问未发布).
+
 ## Capability module migration (0.4)
 
 Capability composition now uses the same `AppModule` model as customer modules. Existing applications must migrate their declarations together; there is no compatibility path.
@@ -408,7 +429,7 @@ Channels that must accept these callbacks declare `stopping_owners=(ServiceType,
 
 The developer-kit dependency constrains `binaryornot` to `0.5.x`, because `0.6.0` can classify bundled templates containing Chinese comments as binary and skip rendering them. Re-resolve the developer-kit environment when installing 0.4.0. Updating the dependency does not replace existing generated application code.
 
-The new `DomainService` marker uses existing constructor injection and transient REQUEST lifetime. It does not create transactions or expose HTTP endpoints. Newly generated modules place approval policy in `domain/services/order_approval_service.py`; existing projects can adopt that example explicitly after upgrading. The application checks existence and the submitted version before the domain policy; a stale or missing order therefore takes precedence over a disabled approval setting when both inputs are invalid. Domain rules, schema, and installation files are not automatically rewritten.
+The new `DomainService` marker uses existing constructor injection and transient REQUEST lifetime. It does not create transactions or expose HTTP endpoints. The independent order example places approval policy in `domain/services/order_approval_service.py`; existing projects can adopt it explicitly after upgrading. The example application checks existence and the submitted version before the domain policy; a stale or missing order therefore takes precedence over a disabled approval setting when both inputs are invalid. Domain rules, schema, and installation files are not automatically rewritten.
 
 <a id="框架更名迁移未发布"></a>
 
@@ -497,7 +518,7 @@ The engineering guides below are maintained in Chinese in the private GitHub rep
 | Check release evidence and remaining validation limits | [Status and validation](https://github.com/componet-architecture/python-ddd-framework/blob/main/docs/status.md) |
 | Change the framework itself | [Contributor guidance](https://github.com/componet-architecture/python-ddd-framework/blob/main/AGENTS.md) and [focused reading paths](https://github.com/componet-architecture/python-ddd-framework/blob/main/docs/README.md#重构的最短阅读路径) |
 
-Generated applications include a self-contained English README, `AGENTS.md`, architecture document, and development guide for their template version. `AGENTS.md` guides contributors from business rules and ownership to framework capability selection and verification. The development guide maps common tasks to framework capabilities and includes commands to locate the installed version's source and bundled examples; each DDD module README records the sample business model and traces approval through its owners. The application maintains these documents after generation; framework upgrades do not overwrite them. Existing applications can use their installed package's `developer_kit/templates` as a read-only reference when updating affected guidance, preserving their own business model and decisions.
+Generated applications include a self-contained English README, `AGENTS.md`, architecture document, and development guide for their template version. They require an owner/layer/directory/API check before implementation and a review of the seven design principles, DDD boundaries, and actual verification before delivery. The development guide provides CLI entry points, installed-artifact/source comparison, capability recipes, and a complete native HTTP generator example; architecture owns streaming/access boundaries, and the generated README owns configuration migration and shutdown operations. These instructions do not imply an automated architecture gate. Each DDD module README records the empty skeleton and guides the first authorized use case; the independent order example owns its own business documentation and acceptance source. The application maintains these documents after generation; upgrades do not overwrite them. Existing applications can use their installed package's `developer_kit/templates` as a read-only reference while preserving application rules and decisions. A user-provided framework checkout is also read-only; matching version numbers alone do not prove it matches the consumed artifact.
 
 ## License
 

{python_ddd_framework-0.6.0 → python_ddd_framework-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-ddd-framework"
-version = "0.6.0"
+version = "0.7.0"
 description = "Modular DDD application framework with project CLI and bundled templates"
 readme = "README.md"
 license = "LicenseRef-Proprietary"

{python_ddd_framework-0.6.0 → python_ddd_framework-0.7.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "python-ddd-framework"
-version = "0.6.0"
+version = "0.7.0"
 description = "Modular DDD application framework with project CLI and bundled templates"
 readme = "README.md"
 license = "LicenseRef-Proprietary"

python_ddd_framework-0.7.0/src/python_ddd_framework/authorization/checking.py

@@ -0,0 +1,35 @@
+"""所有调用与持续访问边界共用的授权规则；不拥有传输或调用 scope。"""
+
+from collections.abc import Callable
+
+from dishka import AsyncContainer
+from dishka.exceptions import NoFactoryError
+
+from ..options import Options
+from .contracts import CurrentUser, PermissionChecker, _AuthorizationRequirement
+from .errors import PermissionCheckerUnavailableError, PermissionDeniedError, UnauthenticatedError
+from .options import AuthorizationOptions
+
+
+async def _check_authorization(
+    container: AsyncContainer,
+    get_user: Callable[[], CurrentUser],
+    requirement: _AuthorizationRequirement,
+) -> None:
+    if requirement.allows_anonymous or not requirement.requires_authenticated_user:
+        return
+    if (await container.get(Options[AuthorizationOptions])).value.always_allow:
+        return
+    # 认证阶段也可调用无需授权的服务；只有实际校验身份时才读取最终 CurrentUser。
+    user = get_user()
+    if not user.is_authenticated:
+        raise UnauthenticatedError
+    if not requirement.permissions:
+        return
+    try:
+        checker = await container.get(PermissionChecker)
+    except NoFactoryError:
+        raise PermissionCheckerUnavailableError from None
+    for permission in requirement.permissions:
+        if not await checker.is_granted(user, permission):
+            raise PermissionDeniedError(permission=str(permission))

{python_ddd_framework-0.6.0 → python_ddd_framework-0.7.0}/src/python_ddd_framework/developer_kit/generation.py

@@ -219,15 +219,6 @@ def _add_module(
         )
         return
     context = {"module_name": package, "class_prefix": class_prefix}
-    if template == "ddd":
-        from ..fastapi.service_routes import _operation_id, _service_path
-
-        # HTTP 身份由正式约定推导；basic 不读取或生成传输层配置。
-        http_identity = type(class_prefix + "ApplicationService", (), {})
-        context.update(
-            http_service_path=_service_path("", http_identity),
-            http_operation_prefix=_operation_id(http_identity, ""),
-        )
     with publication.step("render"):
         staged = _render(
             "basic" if template == "basic" else "module", context, staging=publication.rendering

python_ddd_framework-0.7.0/src/python_ddd_framework/developer_kit/templates/module/cookiecutter.json

@@ -0,0 +1 @@
+{"module_name": "capability", "class_prefix": "Capability"}

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

@@ -0,0 +1,53 @@
+# {{ cookiecutter.class_prefix }} module
+
+This is a DDD module skeleton. It has no business rules, entities, DTOs, services, endpoints, database tables, seed data, background tasks, or test cases. The Host selects its Application, SQLAlchemy, and HttpApi Modules; infrastructure providers remain Host-owned.
+
+[Project setup](../../../../README.md) · [Working rules](../../../../AGENTS.md) · [Architecture](../../../../docs/architecture.md) · [Design checks](../../../../docs/development.md#design-and-delivery-checks) · [Directory rules](../../../../docs/development.md#module-layout-and-coding-rules)
+
+## Record the business responsibility
+
+Before implementation, record the confirmed capability, caller, business language, public contracts, and data owner here. For each invariant, identify its aggregate or service owner, business operation, and a concrete rejection example. Record consistency, concurrency, idempotency, failure-after-commit, and collaboration decisions when relevant. Unresolved questions remain explicit; directory names and documentation recipes do not authorize business rules.
+
+Keep this README current with the implementation and its actual verification. A small correction may reference existing conclusions rather than creating another design document.
+
+## Layers and initial wiring
+
+| Layer | Responsibility and current state |
+| --- | --- |
+| `domain_shared` | Shared contract values, constants, errors, permissions, and messages. No business declarations or framework capability dependencies yet. |
+| `domain` | Aggregates, domain services, repository contracts, events, settings, and seed contributors. Depends on DomainShared; it contains no business implementation. |
+| `application_contracts` | Public service Protocols and input/output DTOs. Depends on DomainShared; contracts do not depend on Domain or implementations. |
+| `application` | Use-case orchestration and handlers. Depends on Domain and ApplicationContracts; its package is scanned but has no services or task declarations. |
+| `sqlalchemy` | Persistence implementations and owned migrations. Depends on Domain and SqlAlchemyPersistenceModule; it retains its Base, model discovery, repository scanning, and migration registration. |
+| `http_api` | Transport declarations. Depends on FastApiModule and exposes this module's contracts; empty contracts produce no business endpoints. |
+
+All responsibility directories and package markers are retained for navigation. Add implementations only for authorized requirements; do not fill them with placeholder interfaces or services. `module.py` owns dependencies, registration, and the seven lifecycle hooks. Empty hooks use `pass`; package markers contain no business or compatibility exports. `tests/` initially contains only its package marker.
+
+## Implement the first use case
+
+1. Identify **owner -> layer -> directory -> verified framework API**, following the project design checks. Add shared values only when they are actually shared.
+2. Model aggregate transitions and invariants in Domain. Define domain-facing repositories without ORM or Session types. Add public DTOs and service Protocols in ApplicationContracts, then implement the authorized use case in Application.
+3. Declare the framework capability dependencies where used: for example, ApplicationServicesModule for application services, AuthorizationModule for permission definitions, or DataSeedingModule for seed contributors. The Host's provider choices do not repair missing module dependencies.
+4. Implement persistence under `sqlalchemy/models` and `sqlalchemy/repositories`. The existing [Base](sqlalchemy/models/base.py) and [registration](sqlalchemy/module.py) own this module's metadata and migration branch. Business models, tables, and schema decisions must come from requirements.
+5. Conventional HTTP exposure can discover the new public service contracts. Add manual routers only where the transport requires them; keep use-case rules out of HTTP. Register workers, jobs, hosted services, schedules, or event handlers explicitly when required.
+6. Update this responsibility record and run the smallest relevant existing checks. New tests and infrastructure validation require the task's authorization; neither an empty test directory nor successful composition proves business correctness.
+
+## Persistence and verification
+
+An empty skeleton retains model and migration registration but has no business tables or revisions. Migration commands still use the configured database; an empty registered Base is different from a module with no model registration. Add actual models before generating a business revision, and review it before applying:
+
+```sh
+pddd db revision --module {{ cookiecutter.module_name }}
+pddd db upgrade --module {{ cookiecutter.module_name }}
+pddd db status --module {{ cookiecutter.module_name }}
+```
+
+Run `pddd db seed --module {{ cookiecutter.module_name }}` only after declaring the intended contributors and preparing their database. Keep applied revisions immutable and upgrade prerequisites explicitly. Host startup never migrates or seeds.
+
+Run installed `pddd` commands from any application directory. Run native tools from `backend/`:
+
+```sh
+uv build --no-sources
+```
+
+After authorized test cases exist, run `uv run pytest src/modules/{{ cookiecutter.module_name }}/tests`. The empty skeleton has no tests to pass. Host tests cover generic health and identity and require their configured infrastructure; see the project verification guide. Module tests are excluded from production wheels and service discovery. The `basic` template remains available for an ordinary in-process service without DDD layers.

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

@@ -0,0 +1,48 @@
+"""应用层拥有用例编排；按真实业务需要声明能力依赖，provider 由 Host 选择。"""
+
+from modules.{{ cookiecutter.module_name }}.domain.module import {{ cookiecutter.class_prefix }}DomainModule
+from modules.{{ cookiecutter.module_name }}.application_contracts.module import {{ cookiecutter.class_prefix }}ApplicationContractsModule
+
+from python_ddd_framework import (
+    AppModule,
+    ConfigureContext,
+    InitializeContext,
+    PostConfigureContext,
+    PostInitializeContext,
+    PreConfigureContext,
+    PreInitializeContext,
+    ShutdownContext,
+)
+
+
+class {{ cookiecutter.class_prefix }}ApplicationModule(AppModule):
+    dependencies = ({{ cookiecutter.class_prefix }}DomainModule, {{ cookiecutter.class_prefix }}ApplicationContractsModule)
+    scan_packages = (__package__,)
+
+    def pre_configure(self, context: PreConfigureContext) -> None:
+        # 贡献影响后续注册的 PreOptions；此阶段不启动资源。
+        pass
+
+    def configure(self, context: ConfigureContext) -> None:
+        # 注册服务和普通 Options；业务执行留在所属能力。
+        pass
+
+    def post_configure(self, context: PostConfigureContext) -> None:
+        # 读取已冻结 PreOptions，补充 Options 或覆盖已有服务注册。
+        pass
+
+    async def pre_initialize(self, context: PreInitializeContext) -> None:
+        # 异步初始化前置条件；依赖模块在同一阶段先完成。
+        pass
+
+    async def initialize(self, context: InitializeContext) -> None:
+        # 初始化本模块资源；不手工启动框架管理的 Worker 或 HostedService。
+        pass
+
+    async def post_initialize(self, context: PostInitializeContext) -> None:
+        # 完成初始化收尾；应用此时尚未对外就绪。
+        pass
+
+    async def shutdown(self, context: ShutdownContext) -> None:
+        # 逆依赖关闭本模块拥有的资源；返回前等待清理结束。
+        pass

{python_ddd_framework-0.6.0 → python_ddd_framework-0.7.0}/src/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-0.6.0 → python_ddd_framework-0.7.0}/src/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-0.7.0/src/python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/http_api/module.py.jinja

@@ -0,0 +1,49 @@
+"""HTTP 仅暴露本模块公开契约；空契约不产生业务端点。"""
+
+from modules.{{ cookiecutter.module_name }}.application_contracts.module import {{ cookiecutter.class_prefix }}ApplicationContractsModule
+
+from python_ddd_framework import (
+    AppModule,
+    ConfigureContext,
+    InitializeContext,
+    PostConfigureContext,
+    PostInitializeContext,
+    PreConfigureContext,
+    PreInitializeContext,
+    ShutdownContext,
+)
+
+from python_ddd_framework.fastapi import FastApiModule, exposes_application_services
+
+
+@exposes_application_services({{ cookiecutter.class_prefix }}ApplicationContractsModule)
+class {{ cookiecutter.class_prefix }}HttpApiModule(AppModule):
+    dependencies = (FastApiModule,)
+
+    def pre_configure(self, context: PreConfigureContext) -> None:
+        # 贡献影响后续注册的 PreOptions；此阶段不启动资源。
+        pass
+
+    def configure(self, context: ConfigureContext) -> None:
+        # 注册服务和普通 Options；业务执行留在所属能力。
+        pass
+
+    def post_configure(self, context: PostConfigureContext) -> None:
+        # 读取已冻结 PreOptions，补充 Options 或覆盖已有服务注册。
+        pass
+
+    async def pre_initialize(self, context: PreInitializeContext) -> None:
+        # 异步初始化前置条件；依赖模块在同一阶段先完成。
+        pass
+
+    async def initialize(self, context: InitializeContext) -> None:
+        # 初始化本模块资源；不手工启动框架管理的 Worker 或 HostedService。
+        pass
+
+    async def post_initialize(self, context: PostInitializeContext) -> None:
+        # 完成初始化收尾；应用此时尚未对外就绪。
+        pass
+
+    async def shutdown(self, context: ShutdownContext) -> None:
+        # 逆依赖关闭本模块拥有的资源；返回前等待清理结束。
+        pass

{python_ddd_framework-0.6.0 → python_ddd_framework-0.7.0}/src/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-0.6.0 → python_ddd_framework-0.7.0}/src/python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/AGENTS.md

@@ -5,17 +5,19 @@ 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.
+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, and CLI. Generated guidance records the template version; upgrades do not update it automatically.
+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 generated order example supplies implementation examples; actual business requirements come from the application.
+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. 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).
+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
@@ -24,22 +26,24 @@ Python code, metadata, configuration, environment, and deployment files belong u
 - 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
 
 - 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.
 
 - 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 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.
@@ -62,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.