python-ddd-framework 0.3.1__py3-none-any.whl

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

@@ -0,0 +1,84 @@
+# Application architecture
+
+This application was generated with Python DDD Framework {{ cookiecutter.framework_version }}. This document records the application's initial boundaries; maintain it as the application evolves. Installed versions and module registrations remain owned by project metadata and source code.
+
+[Run the application](../README.md) · [Development guide](development.md) · [Working rules](../AGENTS.md)
+
+## Composition and ownership
+
+The initial project is a Host without business modules. `pddd add module <name>` adds an example module that the application team adapts to its domain. Generated order-management behavior is a sample, not a declaration of the application's business requirements.
+
+| Owner | Responsibility |
+| --- | --- |
+| `src/host/main.py` | Application and FastAPI factories, configuration inputs, middleware assembly, and the server entry point. |
+| `src/host/module.py` | Explicit module dependencies and provider selection for this deployment. |
+| `src/modules/<name>/` | A business capability, its public contracts, implementation, persistence, transport, and tests. |
+| `app.development.yaml` | Local environment inputs and generated development credentials. |
+| Deployment configuration | Production connections, secrets, environment configuration, and image selection. |
+| `pyproject.toml` and `uv.lock` | Package dependencies, entry points, Python requirements, and resolved versions. |
+
+The Host initially selects PostgreSQL persistence, identity, auditing, Redis capabilities, settings, background jobs, and observability integrations. Read its dependency declarations or run `uv run pddd inspect` for the actual composition. Installing a framework dependency does not enable a module or start its resources.
+
+## Business-module boundaries
+
+Each generated module uses the following dependency direction:
+
+```text
+application -> domain -> domain_shared
+application -> application_contracts -> domain_shared
+http_api -> application_contracts
+sqlalchemy -> domain
+
+Host composes application, sqlalchemy, and http_api modules.
+```
+
+| Layer | Owns | Keep outside this layer |
+| --- | --- | --- |
+| `domain_shared` | Shared values, error definitions, permission names, and business constants. | Host configuration, persistence, and transport behavior. |
+| `domain` | Aggregates, state transitions, events, repository contracts, setting definitions, and seed contributors. | ORM models, HTTP requests, and concrete infrastructure providers. |
+| `application_contracts` | Input/output DTOs and public service Protocols. | Service policies, implementation details, and ORM types. |
+| `application` | Use cases, authorization policies, event handlers, typed job handlers, workers, and integration behavior. | Database mappings and Host-specific provider selection. |
+| `sqlalchemy` | ORM models, repository implementations, model registration, and owned migrations. | Business policy belonging to aggregates or application services. |
+| `http_api` | Service exposure and explicit HTTP/WebSocket transport declarations. | Direct persistence access and duplicated use-case logic. |
+
+The application layer depends on domain and application contracts. The HTTP layer consumes contracts; it does not import the application implementation. The persistence layer implements domain repository contracts. Framework types and selected native Python libraries remain available where appropriate to these responsibilities.
+
+Cross-module access uses public service contracts and explicit Module dependencies. A module owns its own data and migrations. Shared database deployment does not authorize another module to query its tables. Keep internal collaboration contracts separate from end-user service contracts where the caller and authorization semantics differ; `IntegrationService` requires its own contract and is not exposed over HTTP.
+
+## Calls, scopes, and transactions
+
+A managed service call passes through authorization, validation, ACTION scope, unit-of-work handling, and the final implementation. HTTP and direct service invocation share this pipeline. Inject the public service contract; do not construct implementations to bypass it. A self-call is an ordinary Python call and does not re-enter the pipeline.
+
+Dishka owns service lifetimes. Repository implementations use cached REQUEST scope, application-service implementations use cached ACTION scope, and hosted services use cached APP scope. A unit of work independently owns its transaction and Session; REQUEST and ACTION scopes are not themselves transactions.
+
+Default read/write transaction behavior follows framework method/HTTP conventions and explicit policies. For a manually opened unit of work inside a managed invocation, call `complete()` before exiting. A flush is not a commit. Keep sessions local to the owning invocation and avoid transactions across external I/O or long waits.
+
+Repositories map aggregates and ORM models explicitly. Their `SqlAlchemySessionProvider.operation(..., aggregate=...)` boundary stages version changes and collects aggregate events once. Database optimistic concurrency still protects competing writes; do not replace it with a cache or a distributed lock.
+
+Local transactional events run in this order: DOMAIN handlers, flush/version checks, database commit, then AFTER_COMMIT handlers. A post-commit failure does not roll back committed data. Local events provide neither distributed delivery nor crash recovery.
+
+## Configuration and lifecycle
+
+The Host selects the environment through `{{ cookiecutter.host_environment_variable }}` and uses `PDDD_` for business environment variables. Nested fields use `__`. Optional `app.yaml` supplies shared values; `app.<environment>.yaml` supplies environment-specific values. Environment variables override file inputs; explicit Host CLI inputs and overrides have their documented higher precedence.
+
+Modules bind typed `BaseOptions` models with `context.configure(...)`; services inject `Options[T]`. Startup options and mutable runtime settings have separate purposes. `SettingProvider` reads settings; conditional management updates use the current version token.
+
+An Application owns its runtime state, DI container, connections, and background execution. Module definitions can be shared; mutable runtime state cannot. No global application registry or service locator is required.
+
+Module initialization precedes selected hosted services and background execution. Shutdown waits for real cleanup. The Host does not migrate or seed the database. `dev-init` prepares local infrastructure, while explicit `db` commands own migration and seed operations.
+
+## Background work and external boundaries
+
+- Durable jobs use typed, versioned payloads and the PostgreSQL provider. Transactional enqueue must use the same configured connection as the surrounding unit of work. External side effects remain the job's idempotency responsibility.
+- Periodic workers are explicitly registered. Generated example workers are disabled in their class declarations; configuration cannot enable a code-disabled worker.
+- Execution modes are `host`, `shared`, and `exclusive`. Spawned processes compose their own Application; they do not inherit a live Session or container.
+- A `HostedService` owns long-lived SDKs or threads, their failures, recovery, and actual shutdown. It is opt-in; background-process instances need explicit selection. External threads use its supported submission methods.
+- Redis business locks are leases. Preserve cancellation and cleanup when ownership is lost; a lease is not a transaction, fencing guarantee, or exactly-once guarantee.
+- WebSocket delivery targets currently connected clients. The generated sample has no cross-process backplane, offline replay, or delivery acknowledgment. HTTP streaming must release business transactions before network transmission and clean up producers on disconnect.
+- Liveness and readiness report lifecycle state, not continuous infrastructure availability. Trace export is disabled in the generated development configuration until explicitly configured.
+
+## Documentation ownership
+
+`README.md` owns setup and operations; `AGENTS.md` owns development instructions; this file owns architecture boundaries; `development.md` owns usage recipes. Each module README owns its actual business rules, public surface, data, and verification entry points.
+
+Update the affected document with the implementation. Do not duplicate complete dependency, command, route, or module inventories: inspect metadata, CLI help, OpenAPI, and source. Generated documentation belongs to the application after creation and is not overwritten by a framework upgrade.

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

@@ -0,0 +1,185 @@
+# Development guide
+
+Use this guide with the project's [architecture](architecture.md) and [working rules](../AGENTS.md). It describes the generated application's use of Python DDD Framework {{ cookiecutter.framework_version }}. Follow the installed version when adapting examples after an upgrade.
+
+[Add a module](#add-a-module) · [Services and permissions](#services-and-permissions) · [Options and settings](#options-and-settings) · [Persistence](#persistence-and-migrations) · [Events and background work](#events-and-background-work) · [Verification](#verification)
+
+## Add a module
+
+From the application root:
+
+```sh
+uv run pddd add module orders --dry-run
+uv run pddd add module orders
+```
+
+The CLI generates `src/modules/orders/`, registers its application/persistence/HTTP modules in the Host, updates standard package metadata, and synchronizes dependencies. It also creates the module's README. Existing module directories are not overwritten. Repeat with another valid lowercase name when a separate business owner is needed.
+
+Read the generated module README before replacing the order example with your domain. The examples below assume an `orders` module; substitute your actual package and contract names. The application remains usable as a pure Host before adding a module.
+
+## Services and permissions
+
+1. Define shared business values and permission names in `domain_shared/`.
+2. Put aggregate invariants and repository contracts in `domain/`.
+3. Define Pydantic DTOs and an `ApplicationServiceContract, Protocol` in `application_contracts/`.
+4. Implement the contract with `ApplicationService` in `application/`. Keep permission and HTTP method policies on the final implementation.
+5. Keep `scan_packages` scoped to the owning package. The generated application module already scans its package; the HTTP module explicitly exposes its contracts.
+
+The generated implementation illustrates a managed write:
+
+```python
+from uuid import uuid4
+
+from python_ddd_framework.authorization import authorize
+from python_ddd_framework.fastapi import http
+
+from ..application_contracts.orders import CreateOrder, OrderView
+from ..domain.orders import Order, OrderTitle
+from ..domain_shared.definitions import ORDERS_WRITE
+
+# Method inside the generated ApplicationService implementation:
+@authorize(ORDERS_WRITE)
+@http.post(status_code=201)
+async def create(self, command: CreateOrder) -> OrderView:
+    order = Order.create(uuid4(), OrderTitle(value=command.title))
+    await self._repository.save(order)
+    return OrderView.model_validate(order)
+```
+
+Reuse the existing permission definition provider when adding a permission. A new permission definition does not replace the application's grant policy. Do not grant end-user permissions to background components to repair an incorrectly chosen service boundary.
+
+In DI-managed code, inject the public contract and call `await service.method(...)`. Outside DI, use `await application.invoke(ServiceContract.method, ...)`; it is anonymous by default. Trusted Host/test callers can supply a validated identity through `invoke_as`. Use `application.call` for ordinary async callables that need DI. Do not resolve or instantiate the private service implementation yourself.
+
+For ordinary services, use the module's existing registration methods or native Dishka providers. Repository, application-service, and hosted-service scopes are fixed by the framework. Do not add a wrapper or custom container around those roles.
+
+## Options and settings
+
+Startup configuration belongs in a `BaseOptions` type and is bound by the owning module:
+
+```python
+from python_ddd_framework import BaseOptions, Options
+
+class OrdersOptions(BaseOptions):
+    allow_background_approval: bool = True
+
+# In the module's configure(context) method:
+# context.configure(OrdersOptions, section="orders")
+
+class ApprovalPolicy:
+    def __init__(self, options: Options[OrdersOptions]) -> None:
+        self._options = options
+
+    def background_approval_allowed(self) -> bool:
+        return self._options.value.allow_background_approval
+```
+
+This demonstrates the existing Options declaration and injection pattern; extend the generated types rather than defining a second `OrdersOptions`. Register any new ordinary service in the owning module. Configure the generated option in `app.development.yaml`:
+
+```yaml
+orders:
+  allow_background_approval: false
+```
+
+The corresponding environment key is `PDDD_ORDERS__ALLOW_BACKGROUND_APPROVAL`. `PDDD_HTTP__API_PREFIX` changes the business API prefix. `{{ cookiecutter.host_environment_variable }}` selects the Host environment and is separate from business configuration. Values that affect composition require the framework's pre-configuration phase; do not read unbound Options during construction.
+
+Use runtime settings when a value must be changed while the application is running. Add definitions through a scanned `SettingDefinitionProvider`, read them through `SettingProvider`, and use `SettingManager` or the management API for conditional updates/reset with the queried version token. Application services can use `self.setting_provider` during managed invocation, not during construction. The sample's approval setting is defined in `domain/settings.py`.
+
+Inspect configuration sources and service registrations with:
+
+```sh
+uv run pddd inspect --environment development
+```
+
+This composes and closes a new Application without starting it. Output contains redacted configuration inputs, not running-process state or the final Options values after defaults and module contributions. Mark secrets through the framework's existing secret types/metadata; do not log configuration objects or credentials.
+
+## Persistence and migrations
+
+The generated repository interface inherits `RepositoryContract, Protocol`. Its SQLAlchemy implementation nominally implements that contract under `sqlalchemy/repositories/`, which the persistence module scans. Keep Sessions and ORM types inside this layer.
+
+Map aggregates and rows explicitly within `SqlAlchemySessionProvider.operation`. Pass `aggregate=order` when staging an aggregate write, keep the optimistic version checks, and let that boundary collect the aggregate's events. Avoid collecting the same events again in the service.
+
+Place model files in `sqlalchemy/models/` and inherit the package's Base. `SqlAlchemyModelRegistration.from_package` imports that package before freezing metadata, so a new model file does not need a separate import registry. Keep migration scripts in the separate `sqlalchemy/migrations/` package.
+
+After the initial provider setup in the [README](../README.md#initialize-the-database):
+
+```sh
+uv run pddd db revision --module orders
+```
+
+Review the revision, especially renames, data backfills, external revision dependencies, and destructive operations. Autogeneration does not decide whole-table deletion or another owner's migration for you. Then run:
+
+```sh
+uv run pddd db upgrade --module orders
+uv run pddd db status --module orders
+uv run pddd db seed --module orders
+```
+
+Upgrade prerequisites explicitly. Do not modify already applied revisions or write migrations into the installed framework package. Seed contributors run in independent transactions and should be idempotent; seeding a business module does not seed identity on its behalf.
+
+Managed application-service calls provide the normal unit-of-work boundary. Open an explicit short unit of work only when the operation requires it, inside a managed invocation, and complete it explicitly. Never hold it across a device call, long-running task, external network wait, or streamed response. A child task or thread cannot reuse the parent's Session.
+
+For shared databases, configure installation-specific Alembic version table locations, queue schema/object prefixes, and Redis prefixes through their existing Options. A queue schema has one migration owner; it cannot contain the Alembic version table. Changing installation identity after data exists requires an explicit data and migration-record plan.
+
+## Events and background work
+
+Raise domain events on the aggregate. Put typed handlers in a scanned package and select the required `LocalEventPhase` with `@local_event_handler`. Use DOMAIN for transactional rules and AFTER_COMMIT for work such as the sample's cache invalidation and online notifications. Post-commit failures cannot undo a committed order; local events are not a durable message bus.
+
+Jobs inherit `BackgroundJobHandler[Payload]`, declare their durable name/version/current/timeout on the class, and are discovered by module scanning. The generated `ApprovalJob` and `ApprovalPayload` show an idempotent business handler. Enqueue by type from a managed invocation, using the same configured database connection for transactional enqueue:
+
+```python
+from uuid import UUID
+
+from python_ddd_framework.background_jobs import BackgroundJobEnqueuer
+
+from modules.orders.application.tasks import ApprovalJob, ApprovalPayload
+
+async def queue_approval(jobs: BackgroundJobEnqueuer, order_id: UUID) -> str:
+    return await jobs.enqueue(ApprovalJob, ApprovalPayload(order_id=order_id))
+```
+
+Keep persisted payload versions until their queued jobs are drained or explicitly migrated. A job's external side effects must tolerate repeat execution.
+
+Workers implement `BackgroundWorker.run_iteration` and are registered in `Module.background_workers`; their period, timeout, and enabled state live on the class. Both generated workers are disabled. Change a worker's code declaration deliberately before expecting it to run; configuration and management endpoints cannot enable a code-disabled worker.
+
+Background execution Options use catalog names to select `host`, `shared`, or `exclusive` placement. Only worker configuration accepts `enabled`; job configuration does not. Management start/stop is asynchronous: query status after a request. Stopping a job processor preserves its queued data.
+
+Use the existing `DistributedLock` provider for explicit business leases. If acquisition returns false, skip or report the operation as appropriate. Preserve cancellation and cleanup on lease loss. Use database concurrency and idempotency for their separate guarantees.
+
+A `HostedService` manages a long-lived SDK or thread through async `start`/`stop`, including actual thread termination. Register it explicitly in `Module.hosted_services`; the generated integration example is not registered by default. External threads submit through the hosted-service context, and the component owns runtime failures and recovery.
+
+## HTTP, files, and real-time communication
+
+The Host passes `http.api_prefix` to `FastApiAdapter`, defaulting to `/api`. The generated HTTP module exposes its application contracts; special method behavior uses `http` decorators on implementations. Check `/docs` after route changes. Keep method paths relative to their service; module overrides do not repeat the global prefix.
+
+For explicit business routes, use `HttpRouter(use_api_prefix=True, ...)` and inject public service contracts. Independent endpoints such as WebSocket and health routes retain separate paths. Native FastAPI parameter and response types remain supported.
+
+Use `UploadFile`, `File`, and `Form` for uploads and native response types for downloads/streams. Keep byte limits enforced while reading. Release database work before sending a stream, pass detached data to the producer, and protect asynchronous cleanup in its `finally` block; never carry the previous business Session across yields.
+
+The example WebSocket accepts authenticated clients, sends an initial snapshot, and handles `{}` as a refresh request. Invocations recheck identity and permissions. Non-loopback deployments require WSS; query-token authentication requires an explicit Origin policy. Sample notifications stay within the Host process and do not promise replay or delivery acknowledgment.
+
+Use `logging.getLogger(__name__)` for application logs. Configure logging in the Host's YAML, keep credentials and payloads out of messages, and enable existing tracing export only when its destination is configured. Avoid process-global logging/tracing setup in a business module.
+
+## Verification
+
+Run commands from the application root. Read fixtures first: Host tests use disposable PostgreSQL and Redis containers, so Docker must be available.
+
+```sh
+# After adding an orders module: its domain tests do not need Docker.
+uv run pytest src/modules/orders/tests
+
+# Full application tests include real Host infrastructure.
+uv run pytest
+
+# Check the application distribution without local source overrides.
+uv build --no-sources
+```
+
+For custom service tests, use `TestApplication(ApplicationBuilder(...))`, its async context manager, and typed `invoke`/`invoke_as`. The wrapper uses normal composition and cleanup; choose only the modules and providers required by the behavior being tested. Preserve identity and transaction boundaries in integration tests.
+
+The template does not install Ruff or mypy as application dependencies and does not add an architecture-test suite. If those gates are needed, add and configure them as an explicit project decision. Do not describe a static check or a mock as live database, HTTP, or deployment verification.
+
+## Maintain the application
+
+Update a module README for changed business rules, contracts, persistence, or background behavior. Keep architecture and usage instructions in their respective documents. Record a new architectural decision only when there is an actual decision to preserve; do not pre-generate empty plans or status logs.
+
+Framework upgrades update dependencies, not application source or documentation. Follow the target release's migration notes and update these documents deliberately. Add application dependencies with `uv add <package>`; preserve their source overrides and version choices when changing the framework dependency.

python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/pyproject.toml.jinja

@@ -0,0 +1,28 @@
+[project]
+name = "{{ cookiecutter.project_name }}"
+version = "0.1.0"
+requires-python = "=={{ cookiecutter.python_version }}"
+dependencies = ["python-ddd-framework=={{ cookiecutter.framework_version }}"]
+
+[project.entry-points."python_ddd_framework.hosts"]
+application = "host.main:create_application"
+web = "host.main:create_web"
+[dependency-groups]
+dev = ["python-ddd-framework[developer-kit]=={{ cookiecutter.framework_version }}", "pytest", "anyio", "testcontainers[postgres,redis]"]
+
+{% if cookiecutter.framework_source %}[tool.uv.sources]
+python-ddd-framework = {{ cookiecutter.framework_source }}
+{% endif %}
+[build-system]
+requires = ["uv_build=={{ cookiecutter.build_version }}"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "host"
+module-root = "src"
+wheel-exclude = ["**/tests/**"]
+
+[tool.pytest.ini_options]
+anyio_mode = "auto"
+testpaths = ["tests", "src/modules"]
+addopts = "--import-mode=importlib"

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

@@ -0,0 +1 @@
+"""应用 composition root；业务代码由 pddd add module 生成。"""

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

@@ -0,0 +1,47 @@
+"""标准入口一次 build/start/stop；生产和开发使用同一 factory。"""
+
+import os
+from importlib.metadata import version
+from pathlib import Path
+
+from fastapi import FastAPI
+from python_ddd_framework import Application, ApplicationBuilder
+from python_ddd_framework.cli import ENVIRONMENT_VARIABLE
+from python_ddd_framework.fastapi import FastApiAdapter
+from starlette.middleware import Middleware
+from starlette.middleware.gzip import GZipMiddleware
+
+from .module import {{ cookiecutter.class_prefix }}HostModule
+
+
+def create_application(
+    *, environment: str | None = None, cli_args: tuple[str, ...] = ()
+) -> Application:
+    environment = environment or os.environ.get(ENVIRONMENT_VARIABLE, "development")
+    return ApplicationBuilder(
+        {{ cookiecutter.class_prefix }}HostModule,
+        environment=environment,
+        base_path=Path.cwd(),
+        env_prefix="PDDD_",
+        cli_args=cli_args,
+    ).build()
+
+
+def create_web() -> FastAPI:
+    application = create_application()
+    # 全局 middleware 使用原生 Starlette 实现，在 adapter.install 前完成配置。
+    adapter = FastApiAdapter(
+        application, middleware=(Middleware(GZipMiddleware),),
+        api_prefix=application.configuration.get_path("http.api_prefix"),
+    )
+    web = FastAPI(
+        title="{{ cookiecutter.project_name }}", version=version("{{ cookiecutter.project_name }}"), lifespan=adapter.lifespan
+    )
+    adapter.install(web)
+    return web
+
+
+if __name__ == "__main__":
+    from python_ddd_framework.fastapi.server import run_host
+
+    run_host("host.main:create_web", host="0.0.0.0", port=8000)

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

@@ -0,0 +1,37 @@
+"""Host 只选择 provider 与组合 Module，不拥有业务规则。"""
+
+from dishka.integrations.fastapi import FastapiProvider
+from python_ddd_framework import AppModule, ConfigureContext
+from python_ddd_framework.auditing.sqlalchemy import SqlAlchemyAuditingModule
+from python_ddd_framework.background_jobs.pgqueuer import PgQueuerBackgroundJobsModule
+from python_ddd_framework.fastapi.background import BackgroundManagementHttpApiModule
+from python_ddd_framework.fastapi.settings import SettingsManagementHttpApiModule
+from python_ddd_framework.identity.http_api import IdentityHttpApiModule
+from python_ddd_framework.identity.sqlalchemy import SqlAlchemyIdentityModule
+from python_ddd_framework.observability.logging import StructuredLoggingModule
+from python_ddd_framework.observability.tracing import TracingModule
+from python_ddd_framework.redis import RedisDistributedLockModule, RedisModule
+from python_ddd_framework.redis.notifications import RedisNotificationsModule
+from python_ddd_framework.settings.notifications import SettingsNotificationsModule
+from python_ddd_framework.settings.sqlalchemy import SqlAlchemyRuntimeSettingsModule
+
+
+class {{ cookiecutter.class_prefix }}HostModule(AppModule):
+    dependencies = (
+        SqlAlchemyIdentityModule,
+        IdentityHttpApiModule,
+        SqlAlchemyAuditingModule,
+        SqlAlchemyRuntimeSettingsModule,
+        SettingsManagementHttpApiModule,
+        RedisModule,
+        RedisDistributedLockModule,
+        RedisNotificationsModule,
+        SettingsNotificationsModule,
+        PgQueuerBackgroundJobsModule,
+        BackgroundManagementHttpApiModule,
+        StructuredLoggingModule,
+        TracingModule,
+    )
+
+    def configure(self, context: ConfigureContext) -> None:
+        context.services.contribute(FastapiProvider(), reason="Native HTTP request context")

python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/tests/conftest.py.jinja

@@ -0,0 +1,8 @@
+"""Host 验收使用 asyncio；业务模块测试位于模块内部。"""
+
+import pytest
+
+
+@pytest.fixture
+def anyio_backend():
+    return "asyncio"

python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/tests/host/test_http.py.jinja

@@ -0,0 +1,57 @@
+"""Host 只验证通用健康和身份流程；业务断言归各模块。"""
+
+from host.main import create_application, create_web
+from httpx import ASGITransport, AsyncClient
+from testcontainers.community.postgres import PostgresContainer
+from testcontainers.community.redis import RedisContainer
+
+from python_ddd_framework import DataSeeder
+from python_ddd_framework.cli import ENVIRONMENT_VARIABLE
+from python_ddd_framework.identity import IdentityOptions
+from python_ddd_framework.sqlalchemy import SqlAlchemyMigrator
+
+
+async def test_host_http_workflow(monkeypatch):
+    monkeypatch.setenv(ENVIRONMENT_VARIABLE, "development")
+    composed = create_application()
+    try:
+        configuration = composed.configuration
+        identity = composed.options.get(IdentityOptions)
+        postgres_image = configuration.get_path("development.compose.postgres_image")
+        redis_image = configuration.get_path("development.compose.redis_image")
+        api_prefix = configuration.get_path("http.api_prefix")
+    finally:
+        await composed.stop()
+    with PostgresContainer(postgres_image, driver="asyncpg") as postgres:
+        with RedisContainer(redis_image) as redis:
+            monkeypatch.setenv(
+                "PDDD_CONNECTION_STRINGS__DEFAULT", postgres.get_connection_url(driver="asyncpg")
+            )
+            monkeypatch.setenv(
+                "PDDD_REDIS__URL",
+                f"redis://{redis.get_container_host_ip()}:{redis.get_exposed_port(redis.port)}/0",
+            )
+            application = create_application()
+            try:
+                await SqlAlchemyMigrator(application).upgrade_heads()
+                await application.start()
+                await DataSeeder(application).seed_all()
+            finally:
+                await application.stop()
+            web = create_web()
+            async with web.router.lifespan_context(web):
+                async with AsyncClient(
+                    transport=ASGITransport(web), base_url="http://test"
+                ) as client:
+                    assert (await client.get("/health/live")).status_code == 200
+                    assert (await client.get("/health/ready")).status_code == 200
+                    login = await client.post(
+                        f"{api_prefix}/auth/login",
+                        json={
+                            "username": identity.seed_admin_username,
+                            "password": identity.seed_admin_password.get_secret_value(),
+                        },
+                    )
+                    assert login.status_code == 200
+                    client.headers["Authorization"] = "Bearer " + login.json()["access_token"]
+                    assert (await client.get(f"{api_prefix}/auth/me")).status_code == 200

python_ddd_framework/developer_kit/wiring.py

@@ -0,0 +1,162 @@
+"""LibCST 只修改已识别 startup class 的依赖；不重写用户文件的格式和注释。"""
+
+from __future__ import annotations
+
+from typing import cast
+
+import libcst as cst
+import libcst.matchers as matchers
+from libcst.codemod import CodemodContext
+from libcst.codemod.visitors import AddImportsVisitor
+from libcst.helpers import get_full_name_for_node
+from libcst.metadata import ClassScope, MetadataWrapper, ScopeProvider
+
+from ..cli.errors import CommandError
+
+
+class _AddDependency(cst.CSTTransformer):
+    def __init__(self, startup: cst.ClassDef, dependency: str) -> None:
+        self._startup = startup
+        self._dependency = dependency
+        self.matches = 0
+
+    def leave_ClassDef(
+        self, original_node: cst.ClassDef, updated_node: cst.ClassDef
+    ) -> cst.ClassDef:
+        if original_node is not self._startup:
+            return updated_node
+        body = cast(cst.IndentedBlock, updated_node.body)
+        statements = list(body.body)
+        for index, statement in enumerate(statements):
+            if not isinstance(statement, cst.SimpleStatementLine) or len(statement.body) != 1:
+                continue
+            assignment = statement.body[0]
+            if isinstance(assignment, cst.Assign) and len(assignment.targets) == 1:
+                target = assignment.targets[0].target
+            elif isinstance(assignment, cst.AnnAssign):
+                target = assignment.target
+            else:
+                continue
+            if not isinstance(target, cst.Name) or target.value != "dependencies":
+                continue
+            value = assignment.value
+            if not isinstance(value, cst.Tuple) or any(
+                isinstance(item, cst.StarredElement) for item in value.elements
+            ):
+                raise CommandError(
+                    "Startup dependencies must be an explicit tuple without unpacking"
+                )
+            self.matches += 1
+            replacement = _append_dependency(value, self._dependency)
+            statements[index] = statement.with_changes(
+                body=(assignment.with_changes(value=replacement),)
+            )
+        return updated_node.with_changes(body=body.with_changes(body=statements))
+
+
+def _append_dependency(value: cst.Tuple, dependency: str) -> cst.Tuple:
+    elements = list(value.elements)
+    right = value.rpar
+    if elements and value.lpar and right:
+        opening = value.lpar[0].whitespace_after
+        closing = right[0].whitespace_before
+        if isinstance(opening, cst.ParenthesizedWhitespace) and isinstance(
+            closing, cst.ParenthesizedWhitespace
+        ):
+            # LibCST 将最后一项的行尾注释归右括号；把它移到原项之后，保留所属关系。
+            last = elements[-1]
+            comma = last.comma if isinstance(last.comma, cst.Comma) else cst.Comma()
+            elements[-1] = last.with_changes(
+                comma=comma.with_changes(
+                    whitespace_after=closing.with_changes(last_line=opening.last_line)
+                )
+            )
+            right = (
+                right[0].with_changes(
+                    whitespace_before=closing.with_changes(
+                        first_line=cst.TrailingWhitespace(newline=closing.first_line.newline),
+                        empty_lines=(),
+                    )
+                ),
+                *right[1:],
+            )
+            elements.append(cst.Element(cst.Name(dependency), comma=cst.Comma()))
+            return value.with_changes(elements=elements, rpar=right)
+    return value.with_changes(elements=(*elements, cst.Element(cst.Name(dependency))))
+
+
+def add_dependency(source: str, startup: str, import_path: str, dependency: str) -> str:
+    wrapper = MetadataWrapper(cst.parse_module(source))
+    module = wrapper.module
+    # 星号导出的绑定无法由静态 scope 确定，不能冒险覆盖用户的既有依赖。
+    if matchers.findall(module, matchers.ImportStar()):
+        raise CommandError("Star imports prevent safe startup dependency wiring")
+    # 原生作用域绑定防止覆盖用户符号；仅修改实际顶层节点，不触及嵌套同名类。
+    candidates = tuple(
+        statement
+        for statement in module.body
+        if isinstance(statement, cst.ClassDef) and statement.name.value == startup
+    )
+    if len(candidates) != 1:
+        raise CommandError("Startup Module must be a unique top-level class")
+    candidate = candidates[0]
+    if not isinstance(candidate.body, cst.IndentedBlock):
+        raise CommandError("Startup Module must use an indented class body")
+    # 类体的名称查找包含本类和外层模块；两层绑定均不得被新增裸名称遮蔽。
+    scope = cast(ClassScope, wrapper.resolve(ScopeProvider)[candidate.body.body[0]])
+    if dependency in scope:
+        raise CommandError(f"Dependency name already bound in startup module: {dependency}")
+    transformer = _AddDependency(candidate, dependency)
+    updated = module.visit(transformer)
+    if transformer.matches != 1:
+        raise CommandError("Cannot uniquely identify the startup Module dependencies assignment")
+    context = CodemodContext()
+    AddImportsVisitor.add_needed_import(context, import_path, dependency)
+    imports = AddImportsVisitor(context)
+    imported = imports.transform_module(updated)
+    if any(
+        isinstance(node, cst.ImportFrom)
+        and not node.relative
+        and node.module is not None
+        and get_full_name_for_node(node.module) == import_path
+        for node in imports.all_imports
+    ):
+        return imported.code
+    return _place_dependency_import(imported, import_path).code
+
+
+def _place_dependency_import(module: cst.Module, import_path: str) -> cst.Module:
+    # LibCST 原生负责添加/合并 import；这里只定位同一业务 package 内的新接线。
+    # 不排序已有语句，也不重写其注释；首次接线与第三方 imports 之间留空行。
+    body = list(module.body)
+    package = import_path.partition(".")[0]
+    imports: list[tuple[int, str]] = []
+    for index, statement in enumerate(body):
+        if not isinstance(statement, cst.SimpleStatementLine) or len(statement.body) != 1:
+            break
+        node = statement.body[0]
+        # 原生 visitor 可在首行 docstring 或 __strict__ 声明之后插入 import。
+        if index == 0 and not isinstance(node, (cst.Import, cst.ImportFrom)):
+            continue
+        if isinstance(node, cst.ImportFrom) and not node.relative and node.module is not None:
+            name = get_full_name_for_node(node.module)
+            if name is not None and name.partition(".")[0] == package:
+                imports.append((index, name))
+        elif not isinstance(node, (cst.Import, cst.ImportFrom)):
+            break
+    target_index = next(index for index, name in imports if name == import_path)
+    target = cast(cst.SimpleStatementLine, body[target_index])
+    siblings = [(index, name) for index, name in imports if index != target_index]
+    before = next((index for index, name in siblings if name > import_path), None)
+    insertion = before if before is not None else siblings[-1][0] + 1 if siblings else target_index
+    if before is not None:
+        following = cast(cst.SimpleStatementLine, body[before])
+        lines = following.leading_lines
+        if lines and lines[0].comment is None:
+            target = target.with_changes(leading_lines=(lines[0], *target.leading_lines))
+            body[before] = following.with_changes(leading_lines=lines[1:])
+    elif not siblings and target_index and not target.leading_lines:
+        target = target.with_changes(leading_lines=(cst.EmptyLine(),))
+    body.pop(target_index)
+    body.insert(insertion - (target_index < insertion), target)
+    return module.with_changes(body=body)

python_ddd_framework/diagnostics/__init__.py

@@ -0,0 +1,23 @@
+"""Diagnostic contracts 与 Application-owned journal 的 capability 边界。"""
+
+from .model import (
+    DiagnosticMessage,
+    DiagnosticSnapshot,
+    EventStatus,
+    FailureRecord,
+    LifecyclePhase,
+    LifecycleStage,
+    PhaseEvent,
+    SourceLocation,
+)
+
+__all__ = (
+    "DiagnosticMessage",
+    "DiagnosticSnapshot",
+    "EventStatus",
+    "FailureRecord",
+    "LifecyclePhase",
+    "LifecycleStage",
+    "PhaseEvent",
+    "SourceLocation",
+)