python-ddd-framework 0.3.2__tar.gz → 0.5.1__tar.gz

{python_ddd_framework-0.3.2 → python_ddd_framework-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-ddd-framework
-Version: 0.3.2
+Version: 0.5.1
 Summary: Modular DDD application framework with project CLI and bundled templates
 License-Expression: LicenseRef-Proprietary
 License-File: LICENSE
@@ -35,6 +35,7 @@ Requires-Dist: opentelemetry-sdk==1.44.0
 Requires-Dist: opentelemetry-exporter-otlp-proto-http==1.44.0
 Requires-Dist: opentelemetry-instrumentation-fastapi==0.65b0
 Requires-Dist: opentelemetry-instrumentation-httpx==0.65b0
+Requires-Dist: binaryornot>=0.5,<0.6 ; extra == 'developer-kit'
 Requires-Dist: cookiecutter>=2.7.1,<2.8 ; extra == 'developer-kit'
 Requires-Dist: libcst>=1.9.0,<1.10 ; extra == 'developer-kit'
 Requires-Python: >=3.12, <3.15
@@ -85,7 +86,7 @@ Runtime integrations ship in the base package; the Host explicitly enables the m
 
 The supported versions and dependencies are defined in [pyproject.toml](https://github.com/componet-architecture/python-ddd-framework/blob/main/pyproject.toml). The framework, CLI, and bundled templates share one package version.
 
-> **Version 0.3:** This version introduces the `python-ddd-framework` name, unified runtime installation, and application documentation templates. Check [release status](https://github.com/componet-architecture/python-ddd-framework/blob/main/docs/status.md#当前发布) before selecting a PyPI version. Use the local-wheel route below when evaluating a checkout that has not been published.
+> **Version 0.5:** This version introduces staged lifecycle shutdown, a temporary `HostedService.stopping` context, and explicit message-channel admission during stopping. Existing applications must apply the lifecycle migration instructions below; applications upgrading from before 0.4 must also apply the earlier capability and consumer-layout migrations. Check [release status](https://github.com/componet-architecture/python-ddd-framework/blob/main/docs/status.md#当前发布) for publication and validation evidence. Use the local-wheel route below when evaluating a checkout that has not been published.
 
 ### 1. Install the CLI and create a project
 
@@ -93,11 +94,11 @@ For a published release:
 
 ```sh
 uv tool install --python 3.12 "python-ddd-framework[developer-kit]"
-pddd new my-app
+pddd new my-app --python 3.12
 cd my-app
 ```
 
-To select a specific release, append `==<version>` to the quoted package requirement. `pddd new` creates the Host, configuration, tests, deployment files, and four application documents: `README.md`, `AGENTS.md`, `docs/architecture.md`, and `docs/development.md`. It then runs `uv sync` and pins both the runtime dependency and developer tools to the CLI's exact framework version. The destination directory must not already exist.
+To select a specific release, append `==<version>` to the quoted package requirement. `pddd new` creates the Host, configuration, tests, deployment files, and four application documents: `README.md`, `AGENTS.md`, `docs/architecture.md`, and `docs/development.md`. Python metadata, configuration, environment, source, tests, and deployment files live in `backend/`; root `scripts/` belongs to the consumer. It then runs `uv sync` inside `backend/` and pins both the runtime dependency and developer tools to the CLI's exact framework version. The destination directory must not already exist. `--python` accepts a supported portable `major.minor[.patch]` version. `--no-sync` writes files only and works without that interpreter installed; later run `uv sync --project backend` to create the target environment. Native uv/test/build and Docker commands run from `backend/`.
 
 <details>
 <summary>Using an unreleased local wheel</summary>
@@ -110,42 +111,45 @@ pddd new my-app --framework-wheel "<absolute-wheel-path>"
 cd my-app
 ```
 
-The generator checks that the wheel contains `python-ddd-framework` at the CLI's version, copies it into the application's `vendor/` directory, and records the local dependency source. Installing a CLI from source alone does not change where generated applications obtain their framework dependency.
+The generator checks that the wheel contains `python-ddd-framework` at the CLI's version, copies it into the application's `backend/vendor/` directory, and records the local dependency source. Installing a CLI from source alone does not change where generated applications obtain their framework dependency.
 
 </details>
 
 ### 2. Prepare infrastructure and add a business module
 
-Run project commands from the generated application's root directory:
+Run installed `pddd` project commands from the application root, `backend/`, or any descendant directory. They locate Host metadata and use the backend's environment and framework version; unrelated nested Python projects do not take ownership:
 
 ```sh
-uv run pddd dev-init
-uv run pddd add module orders
+pddd dev-init
+pddd add module orders --template ddd
+pddd add module conversions --template basic
 ```
 
-`dev-init` starts or reuses local PostgreSQL and Redis using `app.development.yaml`. It preserves existing data; database migration and seeding are separate steps.
+`dev-init` starts or reuses local PostgreSQL and Redis using `backend/app.development.yaml`. It preserves existing data; database migration and seeding are separate steps.
 
 `add module orders` generates an order-management example and registers it with the Host. The example includes an aggregate, service contracts, application services, persistence, HTTP endpoints, module tests, and a module README describing its actual behavior and boundaries.
 
+`ddd` is the default six-layer template. `basic` generates only a Module, a synchronous Protocol service, its transient implementation, and an English README. It has no database/Redis requirement or implicit HTTP/interception. Both templates support `--dry-run` and refuse existing targets.
+
 ### 3. Initialize the database
 
 Apply the provider migrations selected by the generated Host, then generate the business module's first migration:
 
 ```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 revision --module orders
+pddd db upgrade --module identity
+pddd db upgrade --module settings
+pddd db upgrade --module auditing
+pddd db upgrade --module background_jobs
+pddd db revision --module orders
 ```
 
-Review the generated revision in `src/modules/orders/sqlalchemy/migrations/` before applying it. Then upgrade and seed:
+Review the generated revision in `backend/src/modules/orders/sqlalchemy/migrations/` before applying it. Then upgrade and seed:
 
 ```sh
-uv run pddd db upgrade --module orders
-uv run pddd db status --module orders
-uv run pddd db seed --module identity
-uv run pddd db seed --module orders
+pddd db upgrade --module orders
+pddd db status --module orders
+pddd db seed --module identity
+pddd db seed --module orders
 ```
 
 Migration commands operate on the selected module. When a migration requires another module's revision, upgrade that prerequisite explicitly. Starting the Host does not migrate or seed the database.
@@ -153,10 +157,10 @@ Migration commands operate on the selected module. When a migration requires ano
 ### 4. Run the application and explore the API
 
 ```sh
-uv run pddd dev
+pddd dev
 ```
 
-Open **http://127.0.0.1:8000/docs**. Use the generated `identity.seed_admin_username` and `identity.seed_admin_password` in `app.development.yaml` to call `/api/auth/login`, then enter the returned access token in Swagger's **Authorize** dialog.
+Open **http://127.0.0.1:8000/docs**. Use the generated `identity.seed_admin_username` and `identity.seed_admin_password` in `backend/app.development.yaml` to call `/api/auth/login`, then enter the returned access token in Swagger's **Authorize** dialog.
 
 With the `orders` module installed, you can create and query orders at `/api/orders`, approve an order at `/api/orders/{id}/approve`, and enqueue approval at `/api/orders/{id}/queue-approval`. Swagger shows the request schemas and all available operations. The example also includes file transfer and an authenticated WebSocket endpoint at `/ws/orders`.
 
@@ -164,28 +168,28 @@ The default business API prefix is `/api`. Liveness and readiness are exposed at
 
 ## CLI reference
 
-Use `pddd` to create a project. Inside an existing project, use **`uv run pddd`** so commands run with that project's framework version.
+Use `pddd` to create a project. Inside an existing project, use **`pddd`** so commands run with that project's framework version.
 
 | Command | Purpose |
 | --- | --- |
 | `pddd new my-app` | Generate a new Host project and install its dependencies. |
-| `uv run pddd add module orders` | Generate a business module and register its packages and Host dependencies. |
-| `uv run pddd dev-init` | Prepare the local PostgreSQL and Redis services from development configuration. |
-| `uv run pddd dev` | Start the development web server with reload at `127.0.0.1:8000`. |
-| `uv run pddd db revision --module orders` | Generate an Alembic revision for the module's models. Review it before applying. |
-| `uv run pddd db upgrade --module orders` | Apply the selected module's migrations. |
-| `uv run pddd db status --module orders` | Check that the database is at the selected module's migration heads; fail if it is not. |
-| `uv run pddd db seed --module orders` | Run the selected module's seed contributors after checking its migrations. |
-| `uv run pddd inspect` | Print the composed module graph, service registrations, and redacted configuration inputs as JSON. |
+| `pddd add module orders` | Generate a business module and register its packages and Host dependencies. |
+| `pddd dev-init` | Prepare the local PostgreSQL and Redis services from development configuration. |
+| `pddd dev` | Start the development web server with reload at `127.0.0.1:8000`. |
+| `pddd db revision --module orders` | Generate an Alembic revision for the module's models. Review it before applying. |
+| `pddd db upgrade --module orders` | Apply the selected module's migrations. |
+| `pddd db status --module orders` | Check that the database is at the selected module's migration heads; fail if it is not. |
+| `pddd db seed --module orders` | Run the selected module's seed contributors after checking its migrations. |
+| `pddd inspect` | Print the composed module graph, service registrations, and redacted configuration inputs as JSON. |
 
 Common variations:
 
 ```sh
 pddd new my-app --dry-run
-uv run pddd add module billing --dry-run
-uv run pddd dev --host 127.0.0.1 --port 8080
-uv run pddd inspect --environment development
-uv run pddd db status --module orders --environment production
+pddd add module billing --dry-run
+pddd dev --host 127.0.0.1 --port 8080
+pddd inspect --environment development
+pddd db status --module orders --environment production
 ```
 
 Generation supports `--dry-run` without writing files. Database commands require `--module`; aliases come from installed `python_ddd_framework.modules` entry points and must belong to the current application's module graph.
@@ -197,18 +201,18 @@ Generation supports `--dry-run` without writing files. Database commands require
 For the complete options supported by your installed version:
 
 ```sh
-uv run pddd
-uv run pddd new --help
-uv run pddd add module --help
-uv run pddd db --help
-uv run pddd inspect --help
+pddd
+pddd new --help
+pddd add module --help
+pddd db --help
+pddd inspect --help
 ```
 
 ## Application development
 
 ### Find the right place for a change
 
-The generated project starts with `src/host/` for composition and startup. Business modules live under `src/modules/`; each generated module has these responsibilities:
+The generated project starts with `backend/src/host/` for composition and startup. Modules live under `backend/src/modules/`. A `basic` module contains `module.py`, `contracts/`, `services/`, and its README. The default `ddd` module has these responsibilities:
 
 | Location within a module | Responsibility |
 | --- | --- |
@@ -228,15 +232,15 @@ See the [development guide](https://github.com/componet-architecture/python-ddd-
 
 ### Configure the application
 
-Edit `app.development.yaml` for local connections, identity settings, logging, and module Options. An optional `app.yaml` can hold shared configuration. Environment variables override file inputs; generated Hosts use the `PDDD_` prefix and `__` between nested fields. For example, `PDDD_HTTP__API_PREFIX=/v1` changes the business API prefix.
+Edit `backend/app.development.yaml` for local connections, identity settings, logging, and module Options. An optional `backend/app.yaml` can hold shared configuration. Environment variables override file inputs; generated Hosts use the `PDDD_` prefix and `__` between nested fields. For example, `PDDD_HTTP__API_PREFIX=/v1` changes the business API prefix.
 
-`PYTHON_DDD_FRAMEWORK_ENVIRONMENT` selects the Host environment; it is separate from business configuration. Typed Options validate configuration during application composition. Use `uv run pddd inspect` to investigate input values and where they came from.
+`PYTHON_DDD_FRAMEWORK_ENVIRONMENT` selects the Host environment; it is separate from business configuration. Typed Options validate configuration during application composition. Use `pddd inspect` to investigate input values and where they came from.
 
 Generated credentials are for local development. Production configuration is supplied separately in `app.production.yaml`. See [configuration](https://github.com/componet-architecture/python-ddd-framework/blob/main/docs/development.md#定义-module-与配置) and [background and logging configuration](https://github.com/componet-architecture/python-ddd-framework/blob/main/docs/development.md#settings后台与日志).
 
 ### Run application tests
 
-After completing local database setup:
+After completing local database setup, run from `backend/`:
 
 ```sh
 uv run pytest
@@ -246,7 +250,7 @@ The generated application includes module tests and Host tests. Keep Docker avai
 
 ## Deployment
 
-Generated applications include a `Dockerfile` and `compose.production.yaml`. Build an application distribution with:
+Generated applications include `backend/Dockerfile` and `backend/compose.production.yaml`. Run build and deployment commands from `backend/`:
 
 ```sh
 uv build --no-sources
@@ -263,6 +267,85 @@ The image uses `python -m host.main` without development reload. Runtime install
 
 <a id="版本与升级"></a>
 
+## Capability module migration (0.4)
+
+Capability composition now uses the same `AppModule` model as customer modules. Existing applications must migrate their declarations together; there is no compatibility path.
+
+- Declare capability dependencies on the Module that uses them. Selecting a sibling provider in Host does not supply a missing business-module dependency. `ApplicationServicesModule` supplies the usual application-service capabilities; additional capabilities are explicit dependencies.
+- Wrap capability declarations with `NotificationDefinitions`, `HostedServices`, `BackgroundWorkers`, `BackgroundSchedules`, or `SettingHandlers` from their owning packages. Use native service registration for providers and `ServiceComposition` for capability discovery and final binding. Keep provider selection in Host.
+- Replace Application invocation methods with `invoke(application, Service.method, ...)`, `invoke_as(application, user, ...)`, `call(application, function, ...)`, and `call_as(application, user, ...)`. Register interception with `add_interceptor(context, ...)` and events with `subscribe_local_event(context, ...)`. Import these functions from `python_ddd_framework`.
+- Read capability catalogs from their Module instance through `application.modules.instance(ModuleType)` or the catalog's DI binding. Generic service diagnostics remain in `application.service_catalog`; readiness is `application.is_ready`.
+- `DataSeedContributor`, `DataSeeder`, and `DataSeedError` belong to `python_ddd_framework.seeding` and remain available from the root package. Domain Modules with contributors depend on `DataSeedingModule`; remove `@application_service` from contributors. Seed is no longer an ApplicationService or part of its catalog. Explicit seed commands retain contributor ordering, per-item UoW, module dependency selection, failure reporting, and cleanup.
+- HTTP Modules depend on `FastApiModule` (or `FastApiRealtimeModule` for its additional capability). The module registers the native FastAPI integration; remove manual `FastapiProvider` contributions from Host.
+- Ordinary DI services can opt into `@unit_of_work`, `@authorize`, and `ValidationEnabled`. Declare their capability dependencies on the service's owning Module and retain the existing native registration. Only marked async instance methods enter interception; class declarations covering synchronous/static/class/generator methods fail at build. Use `call` / `call_as` for non-DI callers. These services do not become ApplicationServices or HTTP endpoints.
+- Interceptor match functions receive `ServiceMethod`, replacing `ApplicationServiceMethod`. Shared method descriptions, validation policies, interception contracts and execution now belong to `python_ddd_framework.invocation`; import the public symbols from the root package. The old name and moved `application_services` implementation modules have no forwarding aliases. ApplicationService retains its REQUEST-to-ACTION proxy.
+
+The current contracts are in [architecture](https://github.com/componet-architecture/python-ddd-framework/blob/main/docs/architecture.md), the decisions are [ADR-015](https://github.com/componet-architecture/python-ddd-framework/blob/main/docs/adr/ADR-015-application-service-contract-proxy-and-dispatch.md) and [ADR-032](https://github.com/componet-architecture/python-ddd-framework/blob/main/docs/adr/ADR-032-capability-module-composition.md), and validation limits are in [status](https://github.com/componet-architecture/python-ddd-framework/blob/main/docs/status.md). Slice 3 data/event migration is documented below; later slice status is recorded on the status page.
+
+## Data and event migration (0.4)
+
+- Replace `SqlAlchemyRepository.add` with `insert`. Use `find` for optional results; `get` now raises `ResourceNotFoundError` when absent. List/page return lists, insert/update return the entity, and delete/batch methods return `None`. `auto_save=True` flushes the owning UoW without committing an outer transaction. Explicit mapping repositories retain their own business methods; update their callers and use the new names where they expose the standard operations.
+- Manual `UnitOfWorkManager.begin()` creates missing execution scopes and owns their exit. Call `complete()` explicitly. Existing scopes, task/connection limits, outer participation and `requires_new` ownership remain intact.
+- Replace synchronous `publish_domain`/`publish_after_commit` with `await events.publish(event, phase=LocalEventPhase.DOMAIN/AFTER_COMMIT)`, or omit phase to notify both. No UoW dispatches immediately; transactional UoW defers by default; nontransactional UoW rejects explicit and automatic events before repository writes. `on_unit_of_work_complete=False` never advances AFTER_COMMIT ahead of a successful commit.
+- Replace `CacheDefinition`/`CacheDefinitions`/`CacheCatalog` with injected `DistributedCache[ValueType]`; remove cache declarations from Modules. Use `@cache_name("stable.name")` on the value type if required. Calls take keys/values directly. Configure global `caching.default_entry_options` or pass a complete `DistributedCacheEntryOptions`; omitted options use the default 20-minute sliding expiration, while an empty options object is persistent. Development Hosts explicitly set `caching.hide_errors: false`.
+- Redis cache keys and entry encoding changed; old disposable entries are not read or migrated. They expire under their old TTL. `consider_uow=True` stages writes/deletions per concrete UoW; completion failures retain the committed database fact and do not make the two resources atomic. Do not retry an entire committed business operation merely because an AFTER_COMMIT handler or cache write failed.
+
+## Message processing (0.4)
+
+Opt in with `MessagingModule`, `MessageChannelDefinition[T]`, `MessageHandler[T]` and the
+APP-scoped `MessageChannel[T]`. Register a concrete Handler as a cached ACTION single binding.
+`send()` returns an acceptance receipt; `receipt.wait()` reports processing and cleanup, not
+commit or external acknowledgement. `submit()` is the bounded external-thread entry. Only
+replaceable snapshots may declare `snapshot_key`. Existing events, Jobs, WebSockets and hosted
+callbacks retain their semantics. See the [usage guide](https://github.com/componet-architecture/python-ddd-framework/blob/main/docs/development.md#进程内消息) and
+[reference module](https://github.com/componet-architecture/python-ddd-framework/blob/main/reference_app/orders/messaging_module.py). Existing applications may explicitly
+adopt the sample; upgrades do not rewrite their code or generated documentation.
+
+## User entry migration (0.4)
+
+- `@exposes_application_services(ContractsModule)` now contributes the formal Module dependency. Remove the repeated ContractsModule entry from the HTTP Module's `dependencies`; keep required transport capabilities. Conventional methods remain automatic, `remote_service(is_enabled=False)` excludes them, and route overrides still handle deliberate URL/operation identity differences.
+- A plain Pydantic DTO on a generated GET endpoint binds to query parameters. Use explicit `Body`, `Query`, `Header` or `Depends` to select another native binding. Applications that intentionally sent GET bodies must now declare `Body`; complex parameter shapes retain FastAPI's native limits.
+- Construct schedules as `BackgroundJobSchedule(name="orders.daily", cron="0 0 * * *", job=JobType, payload=Payload(...))`. A registered function's `BackgroundJobDefinition` is also accepted. Remove caller-supplied `job_name`, `job_version` and JSON bytes. Keep existing schedule names and Job definitions to retain durable identity; enqueue and PgQueuer storage are unchanged.
+- Pass a `RealtimeMessage` subclass instance to `send_to_user(user_id, message)`, `send_to_connection(connection_id, message)` or `connection.send(message)`. Put the existing versioned name in the class's `message_type` and declare its payload fields with Pydantic. Preserve existing names/fields when migrating clients. The envelope and queue acceptance report retain their meaning.
+- `locks.acquire(key, wait_timeout=timedelta(...))` overrides only that acquisition's waiting time; `None` uses configured waiting and zero tries without waiting. Lease/renewal settings remain global.
+- `SettingManager.update` now pairs `SettingDefinition[T]` with `value: T`; validate dynamic input at its boundary. Version tokens, reset and refresh behavior are unchanged. `BusinessError(..., data=PublicData(...))` optionally publishes a Pydantic DTO under `error.data`; absence omits the field. Include only intentionally public fields, never raw exceptions or SQL.
+
+See the [usage guide](https://github.com/componet-architecture/python-ddd-framework/blob/main/docs/development.md#用户入口示例) for typed examples. Slice 5 is implemented; current extension/Identity migrations are documented below; the new consumer layout remains pending.
+
+## CLI module layout migration (0.4)
+
+New modules use the [responsibility directory rules](https://github.com/componet-architecture/python-ddd-framework/blob/main/docs/development.md#模块目录与编码规范), delivered inside each generated project. Existing applications are not regenerated by `pddd upgrade`.
+
+- Replace the former `<Module>ApplicationService` with `<Module>QueryApplicationService`, `<Module>ManagementApplicationService`, and `<Module>ApprovalApplicationService`; the consumer item example has a separate item service. Inject the contract for the called use case.
+- Move contracts from `application_contracts/orders.py` into `services`, `inputs`, and `views`; internal reporting goes in `integration_services`. Move aggregate/value/event/repository declarations into their Domain responsibility directories. Import the precise owner, without legacy aliases.
+- Shared immutable values used by Domain and public DTOs belong in `domain_shared/value_objects`; domain-only values remain in `domain/value_objects`. The Catalog consumer moves `Money` out of `domain_shared/values.py` without changing its validation or normalization.
+- Move `application/tasks.py` declarations into `background_jobs/order_approval`, `background_workers`, and their capability files. Hosted integration belongs in `hosted_services`; ORM Base belongs in `sqlalchemy/models/base.py`. Update tests and explicit registrations along with imports.
+- Preserve external HTTP identities through the existing public route overrides. Keep Worker admission and HostedService/schedule enablement explicit; do not change existing schema, transactions, event ordering, or resource cleanup as part of this source migration. Merge the generated AGENTS/development conventions into application-owned documentation deliberately.
+
+## Identity migration (0.4)
+
+Slice 7 adds user/role management and an application-local authorization switch. Existing public service contracts change without compatibility aliases.
+
+- Apply `pddd db upgrade --module identity` before running the new code. The new `identity_0004` revision adds `concurrency_version` to users and roles with a non-null initial value; published revisions and token formats remain unchanged. Consumer extension columns/indexes and revisions stay in the consumer project.
+- `get_users(query)` and `get_roles(query)` accept `PagedResultRequestDto` and return `PagedResult` (`items`, `total_count`). Update callers that expected a bare array, custom repository implementations, and subclasses of the public defaults. New management DTOs are exported from `python_ddd_framework.identity`.
+- Read `concurrency_version` from the current user/role or relationship view and supply it for edits, activation, deletion, passwords, and whole-set relationship updates. Relationship writes return the resulting version. HTTP DELETE takes a JSON version command. Handle 409 by rereading and resolving the edit; do not replace the supplied version and retry blindly. `permission_version` remains internal authorization cache state.
+- Current-user password changes use `ChangePasswordCommand` with the old password and the version returned by `me()`. Administrator resets use `SetPasswordCommand` and the existing user-management permission. Password changes, deactivation, and deletion invalidate existing sessions after commit. Permission changes are reconsidered on subsequent requests.
+- Access/refresh lifetimes and lockout controls now belong to `IdentityOptions`; defaults are preserved. Replace imports of the removed module-level duration/attempt constants with the owning Options. Existing refresh sessions use the currently configured lifetimes.
+- `AuthorizationOptions.always_allow` defaults to `False`. Configure `authorization.always_allow` in the Host when authorization bypass is intended. It covers shared service/HTTP authorization without synthesizing identity or accepting invalid tokens; business validation, transactions, password checks, and realtime identity requirements remain active. Keep permission declarations so disabling the setting restores normal authorization.
+
+See the [Identity guide](https://github.com/componet-architecture/python-ddd-framework/blob/main/docs/development.md#identity-管理与授权配置) and [validation limits](https://github.com/componet-architecture/python-ddd-framework/blob/main/docs/status.md#identity-与授权切片-7未发布). Consumer delivery is described in the layout migration below; fresh acceptance and remaining release limits are recorded on the status page.
+
+## Extension migration (0.4)
+
+- Identity exposes `DefaultAuthenticationApplicationService` and `DefaultIdentityManagementApplicationService`. Specialize these public defaults and use the existing module override registration; keep policies on the final methods. Remove imports of the former private implementations.
+- `UserView` is now a Pydantic `ExtensibleModel`; construct it with named arguments. `CreateUserCommand`, `UpdateUserCommand`, `UserView` (including paged results), and `IdentityUser` share `IDENTITY_USER_EXTENSION`. Declare typed `ExtensionProperties` through `ModelExtensions`; unknown fields are rejected. HTTP extension values remain inside `extra_properties`, including properties mapped to SQL columns.
+- Nested DTOs and native Pydantic generic containers use the same Application-specific schema. Property types must be closed, including type aliases; nested models and dataclasses must reject unknown fields. Keep explicit Query/Header/Body bindings on the implementation when using a separate service contract.
+- Upgrade Identity with `pddd db upgrade --module identity` before using the new JSON container (`identity_0003`). Never edit an applied base revision. A custom Identity store must preserve `IdentityUser.extra_properties`; SQL stores use the Application's `SqlAlchemyModelCatalog.extension_model` binding for queries and reads/writes.
+- For independent columns, the consumer persistence Module contributes `SqlAlchemyModelExtension` and `SqlAlchemyExtensionMigrations`. Register that Module's CLI alias in project metadata, create its local migrations package, and declare the required base revision in `depends_on`. Do not register the base table or Schema again.
+- After upgrading the base, run `pddd db revision --module employee`, review the generated file in the consumer extension module, then run `pddd db upgrade --module employee` and `pddd db status --module employee`. Replace `employee` with your declared alias. Generation includes only that extension's declared columns/indexes; installed framework files remain read-only. A standalone extension upgrade rejects missing prerequisites; the programmatic global migrator follows Alembic dependencies.
+- When a later extension change requires a newer base revision, update the declaration's `depends_on`, apply that base revision, then generate the next extension revision. Earlier extension files keep their original dependencies. Upgrade/status require each current extension head to satisfy the current declaration.
+- Plan explicit data migrations for backfills, required new properties on existing rows, or destructive changes. Host startup never changes tables. Declaration and storage examples are in the [extension guide](https://github.com/componet-architecture/python-ddd-framework/blob/main/docs/development.md#服务与模型扩展).
+
 ## Upgrading
 
 Framework upgrades update dependencies. They do not regenerate your business code, Host, configuration, templates, or migrations. Updating a globally installed CLI also leaves existing projects unchanged.
@@ -285,6 +368,22 @@ During `0.x`, compatible fixes use a patch release; changes requiring consumer a
 
 These notes remain the authoritative consumer migration instructions. Historical versions below refer to the former package name.
 
+#### Lifecycle shutdown migration (0.5)
+
+Version 0.5.1 changes shutdown after the published 0.4.0 baseline. Custom `RuntimeParticipant` implementations must use the new global barriers: `quiesce` → `stopping(reason)` → `close_admission` → `drain` → `stop(reason)` → Module/container cleanup. Move accepted-work draining out of resource `stop`; keep dependencies alive until all drains complete. `prepare(bool)` still selects the startup mode.
+
+Move business calls needed before resource release into the optional `HostedService.stopping(context, reason)` hook. Use its separate context for SDK/thread callbacks; the startup context stays closed. Only successfully started services receive the hook. `stop` still cleans every touched service, including partial startup failures. Each hook uses the existing `shutdown_timeout`; cancellation waits for actual cleanup and is not a total shutdown deadline.
+
+Channels that must accept these callbacks declare `stopping_owners=(ServiceType,)` and pass the current hook context with `send(value, stopping=context)` or `submit(value, stopping=context)`. The channel Module must depend on the declared service owner. The default permits no shutdown input. Capacity, receipts and per-call scope/UoW behavior remain unchanged; HTTP/WebSocket retain native transport shutdown. See the [lifecycle decision](docs/adr/ADR-033-staged-lifecycle-shutdown.md) and [usage guide](docs/development.md#hostedservice-收尾).
+
+#### Additional fixes in 0.4.0
+
+`BackgroundJobRetryPolicy.max_attempts` now counts all executions, including the first. A value of `2` permits two executions; `1` disables failure retries. The 0.3.2 PgQueuer mapping allowed one extra execution. If your application intentionally relied on that behavior, increase its configured total by one. `BackgroundJobContext.attempt` remains zero-based. No queue schema migration is required.
+
+The developer-kit dependency constrains `binaryornot` to `0.5.x`, because `0.6.0` can classify bundled templates containing Chinese comments as binary and skip rendering them. Re-resolve the developer-kit environment when installing 0.4.0. Updating the dependency does not replace existing generated application code.
+
+The new `DomainService` marker uses existing constructor injection and transient REQUEST lifetime. It does not create transactions or expose HTTP endpoints. Newly generated modules place approval policy in `domain/services/order_approval_service.py`; existing projects can adopt that example explicitly after upgrading. The application checks existence and the submitted version before the domain policy; a stale or missing order therefore takes precedence over a disabled approval setting when both inputs are invalid. Domain rules, schema, and installation files are not automatically rewritten.
+
 <a id="框架更名迁移未发布"></a>
 
 <details>
@@ -377,3 +476,7 @@ Generated applications include a self-contained English README, `AGENTS.md`, arc
 ## License
 
 Python DDD Framework is distributed under the [hank-repo Proprietary License](https://github.com/componet-architecture/python-ddd-framework/blob/main/LICENSE). Use requires a separate written agreement; public package availability does not grant additional rights. The source repository is private, with public PyPI packages as the intended delivery channel. PgQueuer-derived code retains its [upstream license](https://github.com/componet-architecture/python-ddd-framework/blob/main/src/python_ddd_framework/background_jobs/pgqueuer/UPSTREAM_LICENSE.txt).
+
+## Consumer layout migration (0.4)
+
+Move an existing application's Python project files, configuration, source, tests, lockfile, vendor wheels, and deployment files into `backend/`; keep application documentation and consumer-owned `scripts/` at the root. Recreate `.venv` with `uv sync --project backend` instead of moving an environment. Update relative script/deployment paths and module README links. Keep portable Python declarations in `backend/.python-version` and `backend/pyproject.toml`. Use installed `pddd` from any application directory, or `uv run pddd` inside `backend/`. Module aliases remain standard entry points and runtime types remain `AppModule`; template selection adds no registration or compatibility path.