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

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/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/developer_kit/templates/module/cookiecutter.json

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

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

@@ -1,101 +1,53 @@
 # {{ cookiecutter.class_prefix }} module
 
-This module owns the generated order example. Adapt its business rules from confirmed requirements. The Host explicitly selects its Application, SQLAlchemy, and HttpApi Modules and infrastructure providers.
+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) · [Business planning](../../../../docs/development.md#plan-a-business-change) · [Framework choices](../../../../docs/development.md#choose-a-framework-capability) · [Directory rules](../../../../docs/development.md#module-layout-and-coding-rules)
+[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)
 
-## Business model record
+## Record the business responsibility
 
-The following facts describe the generated example. When adapting it, replace them with confirmed business language, boundaries, and acceptance examples. Keep reasons for aggregate/consistency choices and unresolved questions here, with links to their code and checks. A proposed rule remains a proposal until the business requirement is established.
+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.
 
-| Concern | Current example |
-| --- | --- |
-| Owner and language | This capability owns an Order's title and approval state. The six layer Modules implement this capability under the Host. Decide actual business boundaries from the application's language and rules. |
-| Identity and values | `Order` has a UUID identity and a version; `OrderTitle` owns title validation and `OrderStatus` defines states. `Money` demonstrates a shared immutable value without becoming an Order field. |
-| Commands and invariants | Creation produces a pending order. Direct approval requires an existing order and the supplied expected version; the approval setting must allow it, and an approved order cannot be approved again. See the walkthrough below for each rule's owner. |
-| Consistency and collaboration | The repository stages one aggregate change in the caller's UoW, preserving optimistic concurrency. Commit precedes cache invalidation and optional online notification. Collaborating modules use public contracts with declared dependencies. |
-| Acceptance and open decisions | The generated domain test covers repeated approval. Real business rejection rules, aggregate relationships, and integration guarantees must come from the application's requirements and receive their own verification. See [verification](#persistence-and-verification) for the current coverage boundary. |
-
-### Invariants and rejection examples
-
-Maintain this record for each changed business invariant under the project's [mandatory DDD rules](../../../../docs/architecture.md#mandatory-ddd-rules). Add its source owner, operation, and concrete rejection case; distinguish implemented behavior from executed verification. The following rows describe the generated example, not additional requirements for another domain.
-
-| Rule | Owner and operation | Rejection example and evidence |
-| --- | --- | --- |
-| An approved order cannot be approved again. | [Order](domain/entities/order.py), `approve()`. | Calling `approve()` twice raises the domain error. The generated domain test covers this path; report its actual run result. |
-| Approval must be enabled. | [Domain approval policy](domain/services/order_approval_service.py), `approve()`. | A disabled approval setting rejects the operation before the aggregate changes. This rule needs its own evidence when adapting the domain; the repeated-approval test does not prove it. |
-| An interactive approval requires a current expected version. | [Application approval service](application/services/order_approval_service.py), `approve()`, plus repository/database concurrency enforcement. | A stale expected version is rejected; a competing database write must also be rejected at persistence. Domain-only tests do not prove the database race. |
+Keep this README current with the implementation and its actual verification. A small correction may reference existing conclusions rather than creating another design document.
 
-For child entities, record the root operation that protects their invariant. For cross-aggregate writes, extend the consistency row above with the participating owners, atomic writes, later effects, and failure/idempotency decisions before implementation. Keep unresolved decisions explicit; do not infer distributed delivery or retry guarantees from the sample's local events.
+## Layers and initial wiring
 
-## Approval walkthrough
-
-Follow one use case across its owners before changing a similar operation:
+| 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. |
 
-1. The caller uses the [approval contract](application_contracts/services/order_approval_service.py) with [ApproveOrder](application_contracts/inputs/approve_order.py). The [application implementation](application/services/order_approval_service.py) applies the write permission, loads the order, and rejects a missing order or stale expected version.
-2. The [domain policy](domain/services/order_approval_service.py) reads the approval setting, then asks the [aggregate](domain/entities/order.py) to approve. The aggregate enforces the state transition and records a stable `OrderChanged` value; it does not save itself.
-3. The application calls the [repository](sqlalchemy/repositories/order_repository.py). It maps the aggregate, checks its persistence version, stages the next version, and lets `operation(..., aggregate=order)` collect events once. The managed UoW owns commit.
-4. After commit, the [event handler](application/event_handlers/order_changed_handler.py) removes the cached order and sends an online notification when a user ID is present. A failure here leaves the database commit intact; it does not justify blindly repeating the business write.
-5. For deferred approval, `queue_approval` returns a Job ID after transactional enqueue. [ApprovalPayload](application/background_jobs/order_approval/payload.py) carries the order ID; it does not carry the interactive expected version or user identity. The [Job](application/background_jobs/order_approval/handler.py) reads current state, skips missing/already-approved orders or disabled approval, and reuses the domain policy and repository. Queue acceptance and completed approval are separate outcomes.
+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.
 
-Use this trace to record the required behavior before adding an operation: which rule changes, who owns it, which framework capability executes it, and which check proves it. Keep the table above aligned with the resulting code.
+## Implement the first use case
 
-## Owners and entry points
-
-| Capability | Entry |
-| --- | --- |
-| Shared constraints, permissions, errors, messages | [Shared layer](domain_shared/module.py), [constants](domain_shared/constants/order_constants.py), [permissions](domain_shared/permissions/order_permission_provider.py) |
-| Aggregate, value, domain policy | [Order](domain/entities/order.py), [title](domain/value_objects/order_title.py), [approval policy](domain/services/order_approval_service.py) |
-| Shared immutable value example | [Money](domain_shared/value_objects/money.py), reusable by Domain and public DTOs; no new sample HTTP fields |
-| Repository contract and settings | [Repository](domain/repositories/order_repository.py), [approval setting](domain/settings/approval_settings.py) |
-| User contracts and use cases | [Query contract](application_contracts/services/order_query_service.py), [management](application/services/order_management_service.py), [approval](application/services/order_approval_service.py) |
-| Internal reporting | [Contract](application_contracts/integration_services/order_reporting_service.py), [implementation](application/integration_services/order_reporting_service.py) |
-| Background and lifecycle | [Approval Job](application/background_jobs/order_approval/handler.py), [statistics schedule](application/background_jobs/order_statistics/schedule.py), [maintenance Worker](application/background_workers/order_maintenance_worker.py), [HostedService](application/hosted_services/order_integration_service.py) |
-| Events, interception, settings refresh | [After-commit handler](application/event_handlers/order_changed_handler.py), [interceptor](application/interceptors/order_timing_interceptor.py), [observer](application/setting_handlers/approval_setting_observer.py) |
-| Persistence | [Model](sqlalchemy/models/order_model.py), [repository](sqlalchemy/repositories/order_repository.py), [registration](sqlalchemy/module.py) |
-| Transport | [HTTP exposure](http_api/module.py), [file router](http_api/routers/order_files.py), [WebSocket](http_api/websockets/order_socket.py) |
-
-## Behavior and enablement
-
-- Query, management, and approval use separate `{{ cookiecutter.class_prefix }}QueryApplicationService`, `{{ cookiecutter.class_prefix }}ManagementApplicationService`, and `{{ cookiecutter.class_prefix }}ApprovalApplicationService` contracts. The exposure decorator contributes the ContractsModule dependency; overrides retain the sample's deliberate paths and operation IDs. Other conventional methods are automatic, with plain GET Pydantic DTOs bound as query parameters unless explicitly declared otherwise. Reporting uses `OrderReportingService` internally without end-user permissions or HTTP exposure.
-- The [approval walkthrough](#approval-walkthrough) traces aggregate rules, domain policy, concurrency, transaction completion, and post-commit effects through their owners.
-- The approval Job participates in transactional enqueue and ignores missing/already-approved orders. The statistics schedule refers to its Job type and typed payload; the Job definition owns persisted name/version/schema. Generated Workers are code-disabled; HostedService and periodic schedule require explicit Module registration as described in the project development guide. Settings refresh and timing interception reuse framework extensions.
-- The hosted example uses `stopping` for an independent business call and an SDK thread callback with the temporary context, then `stop` joins the actual thread after accepted work drains. Startup contexts stay closed during shutdown. To keep message input during this phase, declare this service in the channel's `stopping_owners`, depend on its Module owner, and pass `stopping=context`; no channel opts in by default.
-- File upload/download/stream and `/ws/{{ cookiecutter.module_name }}` call public contracts. Typed messages in [order_messages](domain_shared/messages/order_messages.py) own their versioned names and payload schemas; handlers and the socket explicitly map business values. Sending reports local queue acceptance, with no offline replay, cross-process backplane or client acknowledgment.
-
-Startup [Options](application/options/order_options.py) bind to the `{{ cookiecutter.module_name }}` YAML section; `allow_background_approval` defaults to true. Runtime approval settings and seed contributors belong to Domain. Its Module declares `SettingsModule` and `DataSeedingModule`; contributors are independent DI services, not ApplicationServices. The Domain [OrderApprovalService](domain/services/order_approval_service.py) opts into `ValidationEnabled` through the transitive InvocationModule dependency, retains its transient lifetime, and leaves saving and transaction completion to its caller. Capability dependencies and typed declarations are owned by each Module, while Host selects providers. Change declarations at their owners rather than copying names into another registry.
-
-## Optional in-process observations
-
-The external integration example includes a pure-value [snapshot](domain_shared/messages/order_observation.py)
-and a [Handler](application/hosted_services/order_observation_handler.py). It is not enabled by
-default and does not replace existing callbacks. Follow the project's development guide to add
-MessagingModule, declare the typed channel and register the ACTION Handler. Only pending
-snapshots may coalesce; acceptance, completion, commit and external acknowledgement differ.
+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
 
-This module's ordinary models do not automatically become extension targets. To publish a reusable extension point, declare `ExtensionPoints` with explicit DTO/entity targets and use `ExtensibleModel` for those DTOs. Customer modules contribute typed `ExtensionProperties`; SQL column mappings reference the same fields and belong to their persistence Module. The base module keeps table/Schema/core ownership, while customer extension revisions declare native Alembic `depends_on` and include only their declared columns/indexes. Effective DTO and mapper state belong to each Application.
-
-From the application root, generate and review a revision, then apply and seed explicitly:
+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 }}
-pddd db seed --module {{ cookiecutter.module_name }}
-cd backend
-uv run pytest src/modules/{{ cookiecutter.module_name }}/tests
 ```
 
-Keep applied migrations immutable. The domain test covers repeat-approval rejection; it does not prove infrastructure, HTTP, background, or deployment behavior. Host tests cover generic health and identity. Update the owning contracts, implementation, documentation, and existing verification when adapting the example. Every Module supplies all seven lifecycle hooks; keep empty stages as `pass`.
-
-## Data and events
+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.
 
-`OrderRepository.find` returns an optional aggregate; `get` requires one. List/count/page methods keep explicit ORM mapping and stable ordering. Business `save` participates in the caller's UoW and records entity and aggregate events once. Nontransactional UoWs reject event-producing writes before staging. The framework repository's `auto_save` flushes without committing an outer UoW.
+Run installed `pddd` commands from any application directory. Run native tools from `backend/`:
 
-`OrderChanged` captures UUIDs and an enum in a frozen dataclass. `raise_local_event` checks nested values before enqueueing: use native stable scalars, tuples/frozensets, or frozen records; avoid mutable containers, mapping views, entity references, cycles, and undeclared state. Pydantic event models must be frozen without extra/private/cached state. Dataclass subclasses must themselves declare `frozen=True`. Rejection raises TypeError and preserves already queued events; the framework keeps accepted event objects without copying. Repository entity-change notifications continue to carry entity references.
-
-Inject `DistributedCache[OrderCacheItem]` (or the statistics item), using keys directly. Item classes in `application/caching/` own stable names. Global defaults and explicit entry options are complete alternatives. Use `consider_uow=True` for writes/deletions that should apply after a successful commit. `await events.publish(message)` dispatches immediately without a UoW and follows DOMAIN/AFTER_COMMIT stages inside a transaction; post-commit errors do not undo saved data.
+```sh
+uv build --no-sources
+```
 
-This is the `ddd` template (the default), with all six layers and supported examples. Use `--template basic` for an ordinary in-process service. This module lives under `backend/src/modules/`; native uv/test/build commands run from `backend/`, while installed `pddd` project commands locate the owning backend from any application directory.
+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/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,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.