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

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

@@ -0,0 +1,24 @@
+"""修改业务名称、权限和约束的单一位置。"""
+
+from enum import Enum
+
+from python_ddd_framework import PermissionName
+from python_ddd_framework.errors import BusinessErrorDefinition
+
+MODULE_NAME = "{{ cookiecutter.module_name }}"
+ORDER_CHANGED_MESSAGE = f"{MODULE_NAME}.changed.v1"
+ORDER_SNAPSHOT_MESSAGE = f"{MODULE_NAME}.snapshot.v1"
+TITLE_MAX_LENGTH = 120
+ORDERS_READ = PermissionName(f"{MODULE_NAME}.read")
+ORDERS_WRITE = PermissionName(f"{MODULE_NAME}.write")
+ALREADY_APPROVED = BusinessErrorDefinition(
+    f"{MODULE_NAME}.already_approved", "Order is already approved"
+)
+APPROVAL_DISABLED = BusinessErrorDefinition(
+    f"{MODULE_NAME}.approval_disabled", "Order approval is disabled"
+)
+
+
+class OrderStatus(str, Enum):
+    PENDING = "pending"
+    APPROVED = "approved"

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

@@ -0,0 +1,7 @@
+"""共享层只发布业务常量与权限，不引用基础设施。"""
+
+from python_ddd_framework import AppModule
+
+
+class {{ cookiecutter.class_prefix }}DomainSharedModule(AppModule):
+    scan_packages = (__package__,)

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

@@ -0,0 +1,15 @@
+"""权限名称由共享定义拥有；Provider 仅发布定义。"""
+
+from python_ddd_framework import (
+    PermissionDefinition,
+    PermissionDefinitionContext,
+    PermissionDefinitionProvider,
+)
+
+from .definitions import ORDERS_READ, ORDERS_WRITE
+
+
+class {{ cookiecutter.class_prefix }}PermissionDefinitionProvider(PermissionDefinitionProvider):
+    def define(self, context: PermissionDefinitionContext) -> None:
+        context.add(PermissionDefinition(ORDERS_READ, "Read orders"))
+        context.add(PermissionDefinition(ORDERS_WRITE, "Create and approve orders"))

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

@@ -0,0 +1 @@
+"""HTTP adapter 只依赖服务契约，不反向导入 application 或 sqlalchemy。"""

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

@@ -0,0 +1,73 @@
+"""原生上传与流响应；业务查询在返回响应前完成，不跨网络发送持有事务。"""
+
+import asyncio
+import hashlib
+import logging
+from collections.abc import AsyncIterator, Awaitable, Callable
+from typing import Annotated
+from uuid import UUID
+
+from fastapi import File, Form, UploadFile
+from python_ddd_framework.authorization import authorize
+from python_ddd_framework.fastapi import ActionFilterContext, HttpRouter, service_filter
+from starlette.responses import Response, StreamingResponse
+
+from ..application_contracts.orders import CreateOrder, {{ cookiecutter.class_prefix }}ApplicationService
+from ..domain_shared.definitions import MODULE_NAME, ORDERS_READ, ORDERS_WRITE
+
+router = HttpRouter(use_api_prefix=True, prefix=f"/{MODULE_NAME}/files", permissions=(ORDERS_READ,))
+
+
+class ExportFilter:
+    async def invoke(
+        self, context: ActionFilterContext, next_action: Callable[[], Awaitable[object]]
+    ) -> object:
+        # Filter 的作用域只覆盖已绑定参数到响应准备；不假定流传输已经结束。
+        result = await next_action()
+        logging.getLogger(__name__).info("File response prepared")
+        return result
+
+
+@router.post("/upload", status_code=201)
+@authorize(ORDERS_WRITE)
+async def upload(
+    service: {{ cookiecutter.class_prefix }}ApplicationService,
+    title: Annotated[str, Form()],
+    file: Annotated[UploadFile, File()],
+) -> dict[str, object]:
+    # File/Form 使用框架读取期限额及原生 parser；UploadFile 资源由 REQUEST 关闭。
+    content = await file.read()
+    order = await service.create(CreateOrder(title=title))
+    return {
+        "order": order.model_dump(mode="json"),
+        "bytes": len(content),
+        "sha256": hashlib.sha256(content).hexdigest(),
+    }
+
+
+@router.get("/{id}/download")
+@service_filter(ExportFilter)
+async def download(id: UUID, service: {{ cookiecutter.class_prefix }}ApplicationService) -> Response:
+    order = await service.get(id)
+    return Response(
+        order.model_dump_json(),
+        media_type="application/json",
+        headers={"Content-Disposition": f'attachment; filename="{id}.json"'},
+    )
+
+
+@router.get("/export/stream")
+@service_filter(ExportFilter)
+async def export(service: {{ cookiecutter.class_prefix }}ApplicationService) -> StreamingResponse:
+    orders = await service.get_list()
+
+    async def produce() -> AsyncIterator[bytes]:
+        try:
+            for order in orders:
+                yield (order.model_dump_json() + "\n").encode()
+                await asyncio.sleep(0)
+        finally:
+            # 此示例只持有不可变 DTO，无悬挂 Session／文件；扩展外部资源时在此 shield 异步关闭。
+            logging.getLogger(__name__).info("Order export producer closed")
+
+    return StreamingResponse(produce(), media_type="application/x-ndjson")

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

@@ -0,0 +1,25 @@
+"""自动服务暴露与手写路由共用正式认证／REQUEST 管线。"""
+
+from dishka import Scope
+from python_ddd_framework import AppModule, ConfigureContext
+from python_ddd_framework.fastapi import (
+    FastApiRealtimeModule,
+    contributes_routers,
+    exposes_application_services,
+)
+
+from ..application_contracts.module import {{ cookiecutter.class_prefix }}ApplicationContractsModule
+from .files import ExportFilter
+from .files import router as files_router
+from .realtime import router as realtime_router
+
+
+@contributes_routers(files_router, realtime_router)
+@exposes_application_services(
+    {{ cookiecutter.class_prefix }}ApplicationContractsModule,
+)
+class {{ cookiecutter.class_prefix }}HttpApiModule(AppModule):
+    dependencies = ({{ cookiecutter.class_prefix }}ApplicationContractsModule, FastApiRealtimeModule)
+
+    def configure(self, context: ConfigureContext) -> None:
+        context.services.add_scoped(ExportFilter, scope=Scope.REQUEST)

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

@@ -0,0 +1,36 @@
+"""单进程在线通知；连接认证由框架管理，业务授权仍经过服务契约。"""
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends
+from pydantic import BaseModel, ConfigDict
+from python_ddd_framework import FrameworkError
+from python_ddd_framework.fastapi import WebSocketConnection, websocket_connection
+from starlette.websockets import WebSocketDisconnect
+
+from ..application_contracts.orders import {{ cookiecutter.class_prefix }}ApplicationService
+from ..domain_shared.definitions import MODULE_NAME, ORDER_SNAPSHOT_MESSAGE
+
+router = APIRouter()
+
+
+class RefreshOrders(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+
+@router.websocket(f"/ws/{MODULE_NAME}")
+async def orders_socket(
+    connection: Annotated[WebSocketConnection, Depends(websocket_connection)],
+) -> None:
+    try:
+        while True:
+            orders = await connection.invoke({{ cookiecutter.class_prefix }}ApplicationService.get_list)
+            await connection.send(
+                ORDER_SNAPSHOT_MESSAGE,
+                {"orders": [item.model_dump(mode="json") for item in orders]},
+            )
+            await connection.receive(RefreshOrders)
+    except WebSocketDisconnect:
+        return
+    except FrameworkError as error:
+        await connection.send_problem(error)

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

@@ -0,0 +1 @@
+"""数据库实现由 consuming Host 选择。"""

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

@@ -0,0 +1 @@
+"""初始无业务 revision；执行 pddd db revision --module {{ cookiecutter.module_name }} 后人工审查。"""

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

@@ -0,0 +1,7 @@
+"""本模块模型的原生 MetaData owner；具体模型由 Module 的包声明加载。"""
+
+from sqlalchemy.orm import DeclarativeBase
+
+
+class {{ cookiecutter.class_prefix }}Base(DeclarativeBase):
+    pass

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

@@ -0,0 +1,25 @@
+"""修改模型后显式生成并审查迁移，不在 Host 启动时建表。"""
+
+from uuid import UUID
+
+from python_ddd_framework.sqlalchemy import AuditedEntityMixin
+from sqlalchemy import Integer, String, Uuid
+from sqlalchemy.orm import Mapped, mapped_column
+
+from ...domain_shared.definitions import MODULE_NAME, TITLE_MAX_LENGTH, OrderStatus
+from . import {{ cookiecutter.class_prefix }}Base
+
+
+class OrderRow(AuditedEntityMixin, {{ cookiecutter.class_prefix }}Base):
+    __tablename__ = MODULE_NAME
+    id: Mapped[UUID] = mapped_column(Uuid, primary_key=True)
+    title: Mapped[str] = mapped_column(String(TITLE_MAX_LENGTH), nullable=False)
+    status: Mapped[str] = mapped_column(
+        String(max(len(item.value) for item in OrderStatus)), nullable=False
+    )
+    version: Mapped[int] = mapped_column(Integer, nullable=False)
+    # SQLAlchemy 以行版本检查并发；聚合暂存版本与数据库提交版本保持一致。
+    __mapper_args__ = {  # noqa: RUF012 -- SQLAlchemy 原生声明属性，基类不允许 ClassVar。
+        "version_id_col": version,
+        "version_id_generator": False,
+    }

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

@@ -0,0 +1,26 @@
+"""provider 依赖领域契约；Host 显式选择此实现。"""
+
+from python_ddd_framework import AppModule
+from python_ddd_framework.sqlalchemy import (
+    SqlAlchemyModelRegistration,
+    SqlAlchemyPersistenceModule,
+    contributes_sqlalchemy_models,
+)
+
+from ..domain.module import {{ cookiecutter.class_prefix }}DomainModule
+from ..domain_shared.definitions import MODULE_NAME
+from .models import {{ cookiecutter.class_prefix }}Base
+
+
+@contributes_sqlalchemy_models(
+    SqlAlchemyModelRegistration.from_package(
+        models_package=__package__ + ".models",
+        metadata={{ cookiecutter.class_prefix }}Base.metadata,
+        migrations_package=__package__ + ".migrations",
+        branch_label=MODULE_NAME,
+    )
+)
+class {{ cookiecutter.class_prefix }}SqlAlchemyModule(AppModule):
+    dependencies = ({{ cookiecutter.class_prefix }}DomainModule, SqlAlchemyPersistenceModule)
+
+    scan_packages = (__package__ + ".repositories",)

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

@@ -0,0 +1 @@
+"""本模块的仓储实现发现边界。"""

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

@@ -0,0 +1,49 @@
+"""仓储参与当前 UoW，成功暂存后由 operation 收集聚合事件。"""
+
+from uuid import UUID
+
+from python_ddd_framework import OptimisticConcurrencyError
+from python_ddd_framework.sqlalchemy import SqlAlchemySessionProvider
+from sqlalchemy import select
+
+from ...domain.orders import Order, OrderTitle
+from ...domain.repository import OrderRepository
+from ...domain_shared.definitions import OrderStatus
+from ..models.orders import OrderRow
+
+
+class SqlAlchemyOrderRepository(OrderRepository):
+    def __init__(self, provider: SqlAlchemySessionProvider) -> None:
+        self._provider = provider
+
+    async def get(self, id: UUID) -> Order | None:
+        async with self._provider.operation("get"):
+            row = await (await self._provider.get_session()).get(OrderRow, id)
+            return None if row is None else _order(row)
+
+    async def get_list(self) -> tuple[Order, ...]:
+        async with self._provider.operation("get_list"):
+            rows = await (await self._provider.get_session()).scalars(
+                select(OrderRow).order_by(OrderRow.created_at, OrderRow.id)
+            )
+            return tuple(_order(row) for row in rows)
+
+    async def save(self, order: Order) -> None:
+        async with self._provider.operation("save", aggregate=order):
+            session = await self._provider.get_session()
+            row = await session.get(OrderRow, order.id)
+            if row is None:
+                if order.version:
+                    raise OptimisticConcurrencyError
+                row = OrderRow(id=order.id)
+                session.add(row)
+            elif row.version != order.version:
+                raise OptimisticConcurrencyError
+            order.stage_next_version(order.version)
+            row.title, row.status, row.version = order.title, order.status.value, order.version
+
+
+def _order(row: OrderRow) -> Order:
+    return Order(
+        row.id, OrderTitle(value=row.title), status=OrderStatus(row.status), version=row.version
+    )

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

@@ -0,0 +1,18 @@
+"""模块内领域验收，不随生产 wheel 打包或参与服务扫描。"""
+
+from uuid import uuid4
+
+import pytest
+from python_ddd_framework.errors import BusinessError
+
+from modules.{{ cookiecutter.module_name }}.domain.orders import Order, OrderTitle
+from modules.{{ cookiecutter.module_name }}.domain_shared.definitions import OrderStatus
+
+
+def test_order_approval_rejects_repeat():
+    order = Order.create(uuid4(), OrderTitle(value="Example order"))
+    order.approve()
+    assert order.status is OrderStatus.APPROVED
+    assert len(order.release_local_events()) == 2
+    with pytest.raises(BusinessError):
+        order.approve()

python_ddd_framework/developer_kit/templates/project/cookiecutter.json

@@ -0,0 +1,6 @@
+{
+  "project_name": "application", "package_name": "application", "class_prefix": "Application",
+  "framework_version": "", "framework_source": "", "python_version": "", "build_version": "",
+  "database_password": "", "admin_password": "", "jwt_key": "",
+  "host_environment_variable": ""
+}

python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/.dockerignore

@@ -0,0 +1,9 @@
+.venv
+.git
+.env
+.env.*
+app.*.yaml
+tests
+__pycache__
+.pytest_cache
+dist

python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.env
+app.production.yaml
+dist/

python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/.python-version

@@ -0,0 +1 @@
+{{ cookiecutter.python_version }}

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

@@ -0,0 +1,38 @@
+# Project development guidance
+
+These instructions apply to this application and its business modules. Follow the user's task scope and any more specific instructions in the affected directory.
+
+## Start with the affected capability
+
+1. Check the branch, worktree, requested outcome, and existing changes before editing. Analysis and review requests are read-only unless implementation is requested.
+2. Use [README](README.md) for setup and commands, [architecture](docs/architecture.md) for ownership and dependencies, and the relevant section of [development](docs/development.md) for framework usage.
+3. Before changing a business module, read its `src/modules/<name>/README.md`, then inspect the affected source and direct callers. Expand the investigation only when those facts reveal another affected boundary.
+4. Read versions and dependencies from `pyproject.toml`, exact resolutions from `uv.lock`, and commands from `uv run pddd --help`. Verify behavior against the installed framework version when the application documentation is insufficient.
+
+## Preserve ownership and contracts
+
+- The Host composes modules, selects providers, and supplies configuration. Keep business state and rules in their owning modules.
+- Domain and application contracts stay independent of Host, HTTP, and persistence implementations. Cross-module calls use explicitly declared dependencies and public contracts; do not access another module's implementation, ORM models, or tables directly.
+- Use framework application services, repositories, Options, permissions, units of work, events, jobs, and lifecycle hooks before adding custom infrastructure. Do not introduce a parallel DI container, service locator, transaction manager, or wrapper without a missing business capability.
+- Keep public contracts, mutable state, orchestration, and external I/O under clear owners. Split for independent responsibilities, not a fixed line count. Avoid generic `common`, `utils`, or `helpers` collections and speculative abstractions.
+- Resolve conflicting requirements, documented contracts, and implementation before changing the affected boundary. Describe the conflict to the user; do not rewrite documentation to justify an unapproved design.
+- 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 framework safely
+
+- Invoke application services through their injected public contracts or the application's public invocation methods. Manual construction and self-calls do not create a new managed invocation.
+- Keep transactions short. Never carry a Session, unit of work, or request scope into an ordinary child task, external thread, network wait, or streamed response.
+- Keep aggregate rules and optimistic concurrency checks intact. Use repository operations to stage changes and collect events; do not publish the same aggregate events twice.
+- Review generated migrations. Do not edit applied revisions, bypass migration guards, or treat Host startup as migration or seeding.
+- Keep background side effects idempotent. Local events and WebSocket messages do not provide durable distributed delivery; distributed locks do not replace database concurrency or idempotency.
+- Validate external inputs, propagate meaningful failures, and preserve cancellation and cleanup. Add defaults, retries, or fallbacks only for an identified requirement.
+- Use typed public APIs and native framework extension points. Keep dynamic data narrowing at external boundaries; do not use `Any`, unchecked casts, or broad exception handlers to hide contract mistakes.
+
+## 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.
+- 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.
+- Commit or push only when requested. Review the final diff, choose owned paths explicitly, and exclude secrets, caches, temporary artifacts, and unrelated changes.

python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/Dockerfile

@@ -0,0 +1,22 @@
+# syntax=docker/dockerfile:1
+FROM debian:bookworm-slim AS build
+COPY --from=ghcr.io/astral-sh/uv:{{ cookiecutter.build_version }} /uv /usr/local/bin/uv
+RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates build-essential
+ENV UV_PYTHON_INSTALL_DIR=/opt/python UV_LINK_MODE=copy UV_COMPILE_BYTECODE=1
+WORKDIR /app
+COPY . .
+# Python 版本只从项目 .python-version 读取；PyPI 或 vendor wheel 均由 uv.lock 固定。
+RUN uv python install && uv sync --locked --no-default-groups --no-editable
+
+FROM debian:bookworm-slim AS runtime
+RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates libstdc++6 && useradd --create-home app
+COPY --from=build /opt/python /opt/python
+COPY --from=build /app/.venv /app/.venv
+COPY --from=build /app/pyproject.toml /app/
+WORKDIR /app
+ENV PATH="/app/.venv/bin:$PATH" {{ cookiecutter.host_environment_variable }}=production PYTHONUNBUFFERED=1
+RUN mkdir /app/.python-ddd-framework && chown app:app /app/.python-ddd-framework
+USER app
+EXPOSE 8000
+# 独立 access handler 会绕过安全 formatter；请求诊断由框架审计和追踪负责。
+CMD ["python", "-m", "host.main"]

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

@@ -0,0 +1,130 @@
+# {{ cookiecutter.project_name }}
+
+A modular Python application generated with Python DDD Framework {{ cookiecutter.framework_version }}. The initial project contains a Host; add business modules with `pddd add module` and adapt their examples to your requirements.
+
+| Document | Purpose |
+| --- | --- |
+| [AGENTS.md](AGENTS.md) | Development instructions and reading order for Codex and other contributors. |
+| [Architecture](docs/architecture.md) | Ownership, dependency direction, transaction boundaries, and lifecycle guarantees. |
+| [Development guide](docs/development.md) | Recipes for services, permissions, persistence, configuration, events, and background work. |
+
+Each generated business module also has its own README under `src/modules/<name>/`. This README owns application setup and operations.
+
+## Prerequisites
+
+Use the Python version declared by this project's metadata, uv, and a running Docker installation with Compose. `pddd new` has already synchronized dependencies. On an existing checkout, run `uv sync --locked`.
+
+Run project commands from this directory with `uv run pddd` so they use the project's framework version. Use `uv run pddd` or a subcommand's `--help` to see available commands and options.
+
+## Prepare local development
+
+Review `app.development.yaml`, then start the local infrastructure:
+
+```sh
+uv run pddd dev-init
+```
+
+This starts or reuses PostgreSQL and Redis from the Host's development configuration and preserves data. It does not start the application, migrate, seed, or create an `.env` file. The bundled Compose setup requires local URLs with explicit ports; its Redis service does not configure authentication or TLS.
+
+To add the example business module:
+
+```sh
+uv run pddd add module orders
+```
+
+Read `src/modules/orders/README.md` before changing the sample. The project is also usable as a pure Host without this step.
+
+## Initialize the database
+
+Apply the migrations for the providers selected by the generated Host:
+
+```sh
+uv run pddd db upgrade --module identity
+uv run pddd db upgrade --module settings
+uv run pddd db upgrade --module auditing
+uv run pddd db upgrade --module background_jobs
+uv run pddd db seed --module identity
+```
+
+If you added `orders`, generate its first revision:
+
+```sh
+uv run pddd db revision --module orders
+```
+
+Review the generated file in `src/modules/orders/sqlalchemy/migrations/`, then apply and seed it:
+
+```sh
+uv run pddd db upgrade --module orders
+uv run pddd db status --module orders
+uv run pddd db seed --module orders
+```
+
+All database operations select an explicit module. Upgrade prerequisite owners explicitly; commands do not migrate unrelated modules. Host startup does not migrate or seed. Database commands do not start workers or hosted services. See [persistence and migrations](docs/development.md#persistence-and-migrations) before changing models or existing data.
+
+## Run and inspect
+
+```sh
+uv run pddd dev
+```
+
+Open **http://127.0.0.1:8000/docs**. Call `/api/auth/login` using the generated `identity.seed_admin_username` and `identity.seed_admin_password` from `app.development.yaml`, then enter the access token in **Authorize**. Local credentials must not be reused for production.
+
+With the `orders` example installed, `/api/orders` supports create/query, `/api/orders/{id}/approve` approves an order, and `/api/orders/{id}/queue-approval` enqueues approval. Read the module README for its rules and OpenAPI for request schemas. A stale version produces a conflict response.
+
+`http.api_prefix` controls business HTTP addresses and defaults to `/api`; `/ws`, `/health/live`, `/health/ready`, and `/docs` retain independent paths. Readiness reports Application lifecycle state, not continuous infrastructure health.
+
+To inspect module composition, service registrations, and redacted configuration inputs:
+
+```sh
+uv run pddd inspect --environment development
+```
+
+Inspection composes and closes a new Application without starting it. It does not query an existing process, and its input snapshot is not the final Options view. Configuration, workers, jobs, real-time communication, and logging are covered in the [development guide](docs/development.md).
+
+## Test and package
+
+```sh
+uv run pytest
+uv build --no-sources
+```
+
+The application tests include real Host infrastructure and require Docker. Module domain tests can be run separately; see [verification](docs/development.md#verification). Module tests are excluded from production wheels and service discovery.
+
+## Deploy
+
+The deployment supplies `app.production.yaml`, following the development file's key structure with independent database, Redis, JWT, and administrator credentials. Set the production logging environment and format. Keep the file out of Git and the image; production Compose mounts it read-only at `/app/app.production.yaml` for both web and migration services.
+
+Build an image, validate it, and set `APP_IMAGE` to its immutable digest. In PowerShell, run the following for each required module, replacing the module alias and digest:
+
+```powershell
+docker build -t {{ cookiecutter.project_name }}:candidate .
+$env:APP_IMAGE = "<verified-image>@sha256:<digest>"
+$env:MODULE = "orders"
+docker compose -f compose.production.yaml run --rm migrate
+```
+
+Complete all required module migrations in dependency order and run initial seeds explicitly with `pddd db seed --module <alias> --environment production` in the same application environment. Then start the web service:
+
+```sh
+docker compose -f compose.production.yaml up -d web
+```
+
+The image starts `python -m host.main`, using the public framework server entry point without reload. Web, migration, and background processes use the same application image. Shutdown waits for actual cleanup. `APP_IMAGE`, `MODULE`, and `WEB_PORT` are deployment controls; they do not replace the application's configuration sources.
+
+The base framework dependency includes runtime capabilities. Production does not require `developer-kit`; generation tools, tests, and development tools are excluded from the final image. Configure TLS, secrets, external health monitoring, capacity, and database recovery for the deployment's actual requirements.
+
+## Upgrade the framework
+
+Read the target framework release's migration instructions. Pin `python-ddd-framework` in runtime dependencies and `python-ddd-framework[developer-kit]` in the development group to the same target version. Preserve the application's own dependencies and source overrides.
+
+For a first move from a local wheel or old Git source to PyPI, remove only the framework entry in `[tool.uv.sources]`; retain other dependencies and vendor files. Then run:
+
+```sh
+uv lock --upgrade-package python-ddd-framework
+uv sync --locked
+uv run pytest
+uv build --no-sources
+```
+
+A framework upgrade does not regenerate or overwrite application source, migrations, or these documents. A global CLI upgrade also does not update this project. Apply required adaptations and update the relevant application and module documentation deliberately.

python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/app.development.yaml.jinja

@@ -0,0 +1,30 @@
+# pddd new 生成的随机凭据仅供本机开发；共享环境和生产必须使用独立凭据。
+development:
+  compose:
+    postgres_image: postgres:18-bookworm
+    redis_image: redis:7-bookworm
+connection_strings:
+  default: "postgresql+asyncpg://{{ cookiecutter.package_name }}:{{ cookiecutter.database_password }}@127.0.0.1:5432/{{ cookiecutter.package_name }}"
+identity:
+  issuer: "{{ cookiecutter.project_name }}"
+  audience: "{{ cookiecutter.project_name }}"
+  active_kid: development
+  keys:
+    development: "{{ cookiecutter.jwt_key }}"
+  seed_admin_username: admin
+  seed_admin_password: "{{ cookiecutter.admin_password }}"
+redis:
+  url: redis://127.0.0.1:6379/0
+  key_prefix: "{{ cookiecutter.project_name }}"
+logging:
+  application: "{{ cookiecutter.project_name }}"
+  environment: development
+  format: text
+  level: INFO
+tracing:
+  service_name: "{{ cookiecutter.project_name }}"
+  export_enabled: false
+pgqueuer_background_jobs:
+  connection_name: default
+http:
+  api_prefix: /api

python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/compose.dev.yaml.jinja

@@ -0,0 +1,24 @@
+services:
+  postgres:
+    image: ${POSTGRES_IMAGE:?Run pddd dev-init to load development configuration}
+    environment:
+      POSTGRES_DB: ${POSTGRES_DB}
+      POSTGRES_USER: ${POSTGRES_USER}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+    ports: ["127.0.0.1:${POSTGRES_PORT}:5432"]
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"]
+      interval: 2s
+      timeout: 2s
+      retries: 20
+    volumes: ["postgres-data:/var/lib/postgresql"]
+  redis:
+    image: ${REDIS_IMAGE:?Run pddd dev-init to load development configuration}
+    ports: ["127.0.0.1:${REDIS_PORT}:6379"]
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 2s
+      timeout: 2s
+      retries: 20
+volumes:
+  postgres-data:

python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/compose.production.yaml.jinja

@@ -0,0 +1,20 @@
+# APP_IMAGE 使用验收通过的同一 digest；显式选择模块迁移，成功后启动 Host。
+x-configuration: &configuration
+  type: bind
+  source: ./app.production.yaml
+  target: /app/app.production.yaml
+  read_only: true
+  bind:
+    create_host_path: false
+services:
+  migrate:
+    image: ${APP_IMAGE:?Provide the verified application image digest}
+    volumes: [*configuration]
+    command: ["pddd", "db", "--environment", "production", "upgrade", "--module", "${MODULE:?Select the migration module alias}"]
+    profiles: ["operations"]
+  web:
+    image: ${APP_IMAGE:?Provide the verified application image digest}
+    volumes: [*configuration]
+    ports: ["${WEB_PORT:-8000}:8000"]
+    stop_grace_period: 45s
+    restart: unless-stopped