python-ddd-framework 0.7.3__tar.gz → 0.9.0__tar.gz

{python_ddd_framework-0.7.3 → python_ddd_framework-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-ddd-framework
-Version: 0.7.3
+Version: 0.9.0
 Summary: Modular DDD application framework with project CLI and bundled templates
 License-Expression: LicenseRef-Proprietary
 License-File: LICENSE
@@ -64,7 +64,7 @@ Python DDD Framework combines a module system with FastAPI, Dishka, Pydantic, SQ
 | HTTP APIs | Expose selected application services through FastAPI, or write explicit routers. Use OpenAPI, filters, file uploads, downloads, and streaming responses. |
 | Persistence and events | Use async SQLAlchemy repositories, explicit transaction boundaries, module-owned Alembic migrations, seed contributors, and local events before or after commit. |
 | Identity and permissions | Add JWT authentication, refresh sessions, users and roles, permission definitions, and authorization on service methods. |
-| Cache, settings, and locks | Use typed Redis caching, runtime settings with conditional updates and reset, settings refresh notifications, and explicit Redis-backed business locks. |
+| Cache, settings, and locks | Use typed Redis caching, global runtime settings with conditional updates and reset, and explicit Redis-backed business locks. |
 | Background execution | Enqueue durable PostgreSQL jobs with typed payloads, schedule recurring work, run periodic workers, and select in-process or managed subprocess execution. |
 | Real-time communication | Add authenticated WebSocket connections, typed messages, and targeted notifications to connected clients. |
 | Hosting and observability | Manage long-lived integrations with `HostedService`, coordinate shutdown, and use structured logging, correlation, OpenTelemetry tracing, and lifecycle health endpoints. |
@@ -273,6 +273,12 @@ Edit `backend/app.development.yaml` for local connections, identity settings, lo
 
 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后台与日志).
 
+### Use global settings
+
+Declare a typed `SettingDefinition` and its scanned provider under the owning module's `domain/settings/`, then add `SettingsModule` to that module's dependencies. Inject `SettingProvider` to read values and `SettingManager` for conditional writes/reset. The generated Host already selects Settings persistence and management HTTP; apply its Settings migration before using the store for reads or writes.
+
+Values resolve from runtime override, Host configuration, then definition default. Reset clears an override and resumes fallback. Management provides list/read/update/reset with visibility, permissions, and version checks; business code decides when to use the value. Follow the [complete project recipe](docs/development.md#settings-策略与使用) or the generated project's **Global settings** guide for declarations, configuration, permissions, and request bodies. The minimal contract starts with 0.9.0; see [migration notes](#minimal-settings-migration-090).
+
 ### Run application tests
 
 After completing local database setup, run from `backend/`:
@@ -314,6 +320,24 @@ New `ddd` modules contain the full responsibility directories and necessary comp
 
 See the [migration guide](docs/development.md#数据库聚合与迁移) and [verification record](docs/status.md#http-回收与迁移来源判定未发布).
 
+## Minimal Settings migration (0.9.0)
+
+Settings now owns only global definitions, reads, writes, and clearing overrides. Modules own definitions, the Host selects storage, and business code decides when and how to use the values. Source order, source restrictions, management permissions, typed JSON, independent transactions, UUID concurrency tokens, and reset version records remain unchanged. No dependency, database schema, or migration change is required.
+
+- Remove `SettingsRefreshModule`, `SettingsNotificationsModule`, `SettingHandlers`, `SettingHandlerDefinition`, and Settings refresh options from Host/module wiring. Remove settings observers and the dedicated `application/setting_handlers` directory. Read through `SettingProvider` where the business needs the value; the framework no longer coordinates application, polling, reconnect compensation, retries, or application status. Generic Notifications and HostedService remain available independently.
+- `SettingManager.update/reset` returns `SettingSnapshot[T]` directly: replace `result.snapshot.value/version` with `result.value/version`. `SettingWriteOutcome`, notification feedback, and handler/application status exports are removed.
+- HTTP update/reset returns the same `SettingView` shape as a read: `name`, `value`, `source`, and `version`. Replace `response.setting` with `response`; remove `saved`, `notification`, and `effect` handling. `SettingWriteResult` is removed. Success confirms persistence only, and stale versions still produce a conflict.
+
+Current rules and examples are in the [Settings contract](docs/architecture.md#typed-cache-与-settings) and [usage guide](docs/development.md#settings-策略与使用). Validation and remaining limits are recorded in [status](docs/status.md#settings-最小化未发布).
+
+## Settings policies (0.8.0)
+
+`SettingDefinition` now accepts `allowed_sources`, `management_access`, `read_permission`, and `write_permission`. Existing definitions retain their source order and management visibility. Generic update/reset now also require `settings.read`, in addition to `settings.write` and any declared per-setting permissions, because their responses contain the saved setting snapshot. Update roles that previously held only write permission.
+
+Before excluding `CONFIGURATION` for a setting, remove its entries from YAML, environment variables, dotenv, CLI, explicit configuration and module configuration defaults: composition rejects forbidden inputs even when another value masks them. `HIDDEN` and `READ_ONLY` restrict generic management; internal readers and dedicated application services can still use the existing Provider/Manager subject to source, type and version rules. Defining a per-setting permission does not grant it to existing users or roles; update grants through the application's authorization system. No database migration or dependency change is required for this extension.
+
+Version 0.8.0 includes these policies. Follow [Settings setup and usage](docs/development.md#settings-策略与使用) for definition discovery, permission declarations, internal Provider/Manager calls, and HTTP update/reset with version tokens. The [contract](docs/architecture.md#typed-cache-与-settings) owns the rules; [validation evidence](docs/status.md#settings-最小策略扩展) separates implementation results from the later read-only review.
+
 ## Invocation performance (0.7.2)
 
 Function calls avoid regenerating DI wrappers, empty extension chains skip unnecessary work, and completed filter/interceptor chains release execution references sooner. Managed declaration checks continue to detect dynamic method and policy changes.
@@ -343,7 +367,7 @@ Runnable examples: [HTTP generators](docs/development.md#http-生成器与持续
 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.
+- Wrap capability declarations with `NotificationDefinitions`, `HostedServices`, `BackgroundWorkers`, or `BackgroundSchedules` 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.

{python_ddd_framework-0.7.3 → python_ddd_framework-0.9.0}/README.md

@@ -20,7 +20,7 @@ Python DDD Framework combines a module system with FastAPI, Dishka, Pydantic, SQ
 | HTTP APIs | Expose selected application services through FastAPI, or write explicit routers. Use OpenAPI, filters, file uploads, downloads, and streaming responses. |
 | Persistence and events | Use async SQLAlchemy repositories, explicit transaction boundaries, module-owned Alembic migrations, seed contributors, and local events before or after commit. |
 | Identity and permissions | Add JWT authentication, refresh sessions, users and roles, permission definitions, and authorization on service methods. |
-| Cache, settings, and locks | Use typed Redis caching, runtime settings with conditional updates and reset, settings refresh notifications, and explicit Redis-backed business locks. |
+| Cache, settings, and locks | Use typed Redis caching, global runtime settings with conditional updates and reset, and explicit Redis-backed business locks. |
 | Background execution | Enqueue durable PostgreSQL jobs with typed payloads, schedule recurring work, run periodic workers, and select in-process or managed subprocess execution. |
 | Real-time communication | Add authenticated WebSocket connections, typed messages, and targeted notifications to connected clients. |
 | Hosting and observability | Manage long-lived integrations with `HostedService`, coordinate shutdown, and use structured logging, correlation, OpenTelemetry tracing, and lifecycle health endpoints. |
@@ -229,6 +229,12 @@ Edit `backend/app.development.yaml` for local connections, identity settings, lo
 
 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后台与日志).
 
+### Use global settings
+
+Declare a typed `SettingDefinition` and its scanned provider under the owning module's `domain/settings/`, then add `SettingsModule` to that module's dependencies. Inject `SettingProvider` to read values and `SettingManager` for conditional writes/reset. The generated Host already selects Settings persistence and management HTTP; apply its Settings migration before using the store for reads or writes.
+
+Values resolve from runtime override, Host configuration, then definition default. Reset clears an override and resumes fallback. Management provides list/read/update/reset with visibility, permissions, and version checks; business code decides when to use the value. Follow the [complete project recipe](docs/development.md#settings-策略与使用) or the generated project's **Global settings** guide for declarations, configuration, permissions, and request bodies. The minimal contract starts with 0.9.0; see [migration notes](#minimal-settings-migration-090).
+
 ### Run application tests
 
 After completing local database setup, run from `backend/`:
@@ -270,6 +276,24 @@ New `ddd` modules contain the full responsibility directories and necessary comp
 
 See the [migration guide](docs/development.md#数据库聚合与迁移) and [verification record](docs/status.md#http-回收与迁移来源判定未发布).
 
+## Minimal Settings migration (0.9.0)
+
+Settings now owns only global definitions, reads, writes, and clearing overrides. Modules own definitions, the Host selects storage, and business code decides when and how to use the values. Source order, source restrictions, management permissions, typed JSON, independent transactions, UUID concurrency tokens, and reset version records remain unchanged. No dependency, database schema, or migration change is required.
+
+- Remove `SettingsRefreshModule`, `SettingsNotificationsModule`, `SettingHandlers`, `SettingHandlerDefinition`, and Settings refresh options from Host/module wiring. Remove settings observers and the dedicated `application/setting_handlers` directory. Read through `SettingProvider` where the business needs the value; the framework no longer coordinates application, polling, reconnect compensation, retries, or application status. Generic Notifications and HostedService remain available independently.
+- `SettingManager.update/reset` returns `SettingSnapshot[T]` directly: replace `result.snapshot.value/version` with `result.value/version`. `SettingWriteOutcome`, notification feedback, and handler/application status exports are removed.
+- HTTP update/reset returns the same `SettingView` shape as a read: `name`, `value`, `source`, and `version`. Replace `response.setting` with `response`; remove `saved`, `notification`, and `effect` handling. `SettingWriteResult` is removed. Success confirms persistence only, and stale versions still produce a conflict.
+
+Current rules and examples are in the [Settings contract](docs/architecture.md#typed-cache-与-settings) and [usage guide](docs/development.md#settings-策略与使用). Validation and remaining limits are recorded in [status](docs/status.md#settings-最小化未发布).
+
+## Settings policies (0.8.0)
+
+`SettingDefinition` now accepts `allowed_sources`, `management_access`, `read_permission`, and `write_permission`. Existing definitions retain their source order and management visibility. Generic update/reset now also require `settings.read`, in addition to `settings.write` and any declared per-setting permissions, because their responses contain the saved setting snapshot. Update roles that previously held only write permission.
+
+Before excluding `CONFIGURATION` for a setting, remove its entries from YAML, environment variables, dotenv, CLI, explicit configuration and module configuration defaults: composition rejects forbidden inputs even when another value masks them. `HIDDEN` and `READ_ONLY` restrict generic management; internal readers and dedicated application services can still use the existing Provider/Manager subject to source, type and version rules. Defining a per-setting permission does not grant it to existing users or roles; update grants through the application's authorization system. No database migration or dependency change is required for this extension.
+
+Version 0.8.0 includes these policies. Follow [Settings setup and usage](docs/development.md#settings-策略与使用) for definition discovery, permission declarations, internal Provider/Manager calls, and HTTP update/reset with version tokens. The [contract](docs/architecture.md#typed-cache-与-settings) owns the rules; [validation evidence](docs/status.md#settings-最小策略扩展) separates implementation results from the later read-only review.
+
 ## Invocation performance (0.7.2)
 
 Function calls avoid regenerating DI wrappers, empty extension chains skip unnecessary work, and completed filter/interceptor chains release execution references sooner. Managed declaration checks continue to detect dynamic method and policy changes.
@@ -299,7 +323,7 @@ Runnable examples: [HTTP generators](docs/development.md#http-生成器与持续
 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.
+- Wrap capability declarations with `NotificationDefinitions`, `HostedServices`, `BackgroundWorkers`, or `BackgroundSchedules` 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.

{python_ddd_framework-0.7.3 → python_ddd_framework-0.9.0}/pyproject.toml

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

{python_ddd_framework-0.7.3 → python_ddd_framework-0.9.0}/pyproject.toml.orig

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

{python_ddd_framework-0.7.3 → python_ddd_framework-0.9.0}/src/python_ddd_framework/__init__.py

@@ -280,10 +280,10 @@ from .settings import (
     SettingDefinitionContext,
     SettingDefinitionError,
     SettingDefinitionProvider,
+    SettingManagementAccess,
     SettingManager,
     SettingProvider,
 )
-from .settings.declarations import SettingHandlers
 from .settings.module import SettingsModule
 from .unit_of_work import (
     UnitOfWork,
@@ -527,7 +527,7 @@ __all__ = (
     "SettingDefinitionContext",
     "SettingDefinitionError",
     "SettingDefinitionProvider",
-    "SettingHandlers",
+    "SettingManagementAccess",
     "SettingManager",
     "SettingProvider",
     "SettingsModule",

{python_ddd_framework-0.7.3 → python_ddd_framework-0.9.0}/src/python_ddd_framework/configuration/root.py

@@ -212,4 +212,6 @@ class ConfigurationRoot(Mapping[str, object]):
             provenance=resolved._provenance,
             secret_paths=secret_paths,
             sources=self._sources,
+            # Settings 等能力的晚期策略检查仍需看到被覆盖的输入；沿用冻结引用。
+            payloads=resolved._payloads,
         )

{python_ddd_framework-0.7.3 → python_ddd_framework-0.9.0}/src/python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/README.md

@@ -32,6 +32,12 @@ All responsibility directories and package markers are retained for navigation.
 5. Conventional HTTP exposure can discover the new public service contracts. Add manual routers only where the transport requires them; keep use-case rules out of HTTP. Register workers, jobs, hosted services, schedules, or event handlers explicitly when required.
 6. Update this responsibility record and run the smallest relevant existing checks. New tests and infrastructure validation require the task's authorization; neither an empty test directory nor successful composition proves business correctness.
 
+## Global settings
+
+When a use case requires a global setting, place its `SettingDefinition` and synchronous definition provider under `domain/settings`, add SettingsModule to the Domain Module dependencies, and include the package in discovery. Callers import the same definition and inject SettingProvider; authorized writes use SettingManager with the version read by the caller. Provider selection and database setup belong to the Host.
+
+Follow the application's [Global settings recipe](../../../../docs/development.md#global-settings) for configuration fallback, management permissions, and update/reset requests. Record this module's actual setting names, business use, and effective timing here when implemented. The skeleton has no business settings or observers; reset clears an override, and the framework does not apply values to running components.
+
 ## Persistence and verification
 
 An empty skeleton retains model and migration registration but has no business tables or revisions. Migration commands still use the configured database; an empty registered Base is different from a module with no model registration. Add actual models before generating a business revision, and review it before applying:

{python_ddd_framework-0.7.3 → python_ddd_framework-0.9.0}/src/python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/AGENTS.md

@@ -23,6 +23,7 @@ Use the [official CLI entry points](docs/development.md#cli-operations) for oper
 ## Preserve ownership and contracts
 
 - The Host composes modules, selects providers, and supplies configuration. Keep business state and rules in their owning modules.
+- Global Settings definitions belong to their Domain Module; services own when values are read and applied. Follow the project's [Settings contract](docs/architecture.md#global-settings-ownership) and [usage recipe](docs/development.md#global-settings), preserving source, authorization, and version rules. Do not assume a component-refresh or notification service exists.
 - 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.

{python_ddd_framework-0.7.3 → python_ddd_framework-0.9.0}/src/python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/README.md

@@ -87,6 +87,12 @@ 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).
 
+## Use global settings
+
+The Host includes Settings persistence and management HTTP. After database setup, define each required setting in its owning module and grant management read/write permissions to the intended identity. Follow the self-contained [Global settings recipe](docs/development.md#global-settings) for definition discovery, YAML/environment fallback, service injection, and HTTP read/update/reset.
+
+Settings stores global values; business code decides when they take effect. Reset clears a runtime override and resumes configuration/default fallback. Source restrictions, visibility, authorization, and version checks remain enforced. No business settings or automatic component-refresh workflow are generated.
+
 ## Test and package
 
 ```sh

{python_ddd_framework-0.7.3 → python_ddd_framework-0.9.0}/src/python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/backend/src/host/module.py.jinja

@@ -21,8 +21,6 @@ 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.refresh_module import SettingsRefreshModule
 from python_ddd_framework.settings.sqlalchemy import SqlAlchemyRuntimeSettingsModule
 
 
@@ -36,8 +34,6 @@ class {{ cookiecutter.class_prefix }}HostModule(AppModule):
         RedisModule,
         RedisDistributedLockModule,
         RedisNotificationsModule,
-        SettingsNotificationsModule,
-        SettingsRefreshModule,
         PgQueuerBackgroundJobsModule,
         BackgroundManagementHttpApiModule,
         StructuredLoggingModule,

{python_ddd_framework-0.7.3 → python_ddd_framework-0.9.0}/src/python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/docs/architecture.md

@@ -83,6 +83,12 @@ These constraints apply when a capability models aggregates. The module README o
 | Cross-aggregate consistency | Before implementing a write spanning aggregates, identify the participating owners, what commits atomically, and any later effects. Record concurrency, failure-after-commit, duplicate/retry, and idempotency behavior. A local UoW may coordinate multiple aggregates when that is the confirmed requirement; do not impose one aggregate per transaction mechanically. Cross-module collaboration still uses public contracts, and local events do not promise durable distributed delivery. |
 | Business evidence | For each changed invariant, the module README must identify its rule owner, business operation, and a concrete rejection example, linking the relevant source and verification. Record unverified cases and open decisions explicitly. Directory placement, type checks, and passing unrelated tests do not by themselves prove a business rule. |
 
+## Global settings ownership
+
+Settings owns global definitions, reads, conditional writes, and clearing overrides. Domain Modules contribute definitions under `domain/settings`; the Host selects persistence and management HTTP. Business services decide when to read and apply values. Source precedence is runtime override, Host configuration, then definition default, filtered by the definition's allowed sources.
+
+Management visibility and permissions govern the generic management service. Internal business services own their authorization; all writes still enforce definition ownership, value validation, and version checks. Settings commits independently of an outer business UoW, and reset retains a fresh version record. It does not own component refresh, notifications, reconciliation, retries, or application status. Follow the [usage recipe](development.md#global-settings) for concrete declarations and calls.
+
 ## 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.

{python_ddd_framework-0.7.3 → python_ddd_framework-0.9.0}/src/python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/docs/development.md

@@ -128,7 +128,7 @@ For `basic`, keep public interfaces in `contracts/` and implementations in `serv
 | `domain_shared` | `constants`, `enums`, `errors`, `permissions`, `messages`, `value_objects` |
 | `domain` | `entities`, `value_objects`, `services`, `repositories`, `events`, `settings`, `seeding` |
 | `application_contracts` | `services`, `integration_services`, `inputs`, `views` |
-| `application` | `services`, `integration_services`, `background_jobs`, `background_workers`, `hosted_services`, `event_handlers`, `interceptors`, `caching`, `options`, `setting_handlers` |
+| `application` | `services`, `integration_services`, `background_jobs`, `background_workers`, `hosted_services`, `event_handlers`, `interceptors`, `caching`, `options` |
 | `sqlalchemy` | `models`, `repositories`, `migrations` |
 | `http_api` | `routers`, `filters`, `websockets`, `models` |
 
@@ -238,7 +238,67 @@ orders:
 
 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. Setting definitions belong under `domain/settings/`; declare SettingsModule on the owner when introducing them.
+### Global settings
+
+Settings defines, reads, writes, and clears global runtime overrides. The following is an illustrative recipe, not a generated business feature. Add a definition and its provider under the owning module's `domain/settings/worker_settings.py` only when the setting is required:
+
+```python
+from python_ddd_framework.settings import (
+    SettingDefinition,
+    SettingDefinitionContext,
+    SettingDefinitionProvider,
+)
+
+WORKER_LIMIT = SettingDefinition("worker.limit", int, default=10)
+
+
+class WorkerSettingDefinitionProvider(SettingDefinitionProvider):
+    def define(self, context: SettingDefinitionContext) -> None:
+        context.add(WORKER_LIMIT)
+```
+
+Add `SettingsModule` from `python_ddd_framework` to the existing Domain Module's dependencies, and include its package in `scan_packages`; retain the other dependencies and lifecycle hooks. Import this same definition in callers instead of constructing another object with the same name. Store credentials in Host configuration, not Settings.
+
+By default, values resolve from runtime override, Host configuration, then definition default. An optional Host value in `backend/app.development.yaml` looks like this:
+
+```yaml
+settings:
+  worker:
+    limit: 12
+```
+
+The default environment key is `PDDD_SETTINGS__WORKER__LIMIT`. Without an override the value is 12, or 10 if that configuration is absent. Writing 20 makes it the override; reset resumes the configured 12. Configuration is frozen at startup: restart the Host after changing YAML/environment inputs. Reset does not reload files, and writing the default value still creates an override.
+
+Inject `SettingProvider` for reads and `SettingManager` into an authorized service for writes. In an existing async service method, with `reader` and `manager` already injected:
+
+```python
+limit = await reader.get(WORKER_LIMIT)
+current = await reader.snapshot(WORKER_LIMIT)
+saved = await manager.update(WORKER_LIMIT, 20, expected_version=current.version)
+# saved is SettingSnapshot[int]: name, value, source, version.
+reset = await manager.reset(WORKER_LIMIT, expected_version=saved.version)
+```
+
+This demonstrates an immediate write/reset sequence. Interactive editing must retain the version the operator actually read, rather than fetch a fresh token just before saving. A conflict requires re-reading and a caller decision, not an automatic retry. Application services can also use `self.setting_provider` during managed invocation, not construction. Storage errors propagate; if no allowed source has a value, `snapshot` reports UNSET and `get` fails.
+
+The generated Host selects `SqlAlchemyRuntimeSettingsModule` and `SettingsManagementHttpApiModule`. A custom Host must select them when it needs persistent overrides and management HTTP. Configure its database and run `pddd db upgrade --module settings` as part of database setup; startup does not migrate. Without a store binding, reads can use configuration/defaults but Manager is not registered.
+
+With the default API prefix, use these operations after authenticating and granting the management permissions:
+
+| Operation | Request |
+| --- | --- |
+| List visible settings | `GET /api/settings` |
+| Read a setting and its version | `GET /api/settings/worker.limit` |
+| Save an override | `PUT /api/settings/worker.limit`, body `{"value": 20, "expected_version": "<version from read>"}` |
+| Clear an override | `POST /api/settings/worker.limit/reset`, body `{"expected_version": "<latest version>"}` |
+
+Pass JSON null for `expected_version` only when the read returned null. Reads and writes return `name`, `value`, `source`, and `version`; reset retains a new version token. HTTP 409 means a version conflict. Writes commit independently of the caller's business transaction, and a successful response confirms persistence only.
+
+Definitions may restrict `allowed_sources` without changing their fixed order. Excluding CONFIGURATION rejects matching Host inputs, so remove the YAML/environment setting too. `management_access` defaults to READ_WRITE; READ_ONLY rejects generic writes/reset, while HIDDEN omits the setting from lists and returns not found for individual management operations. Reads require `settings.read`; writes/reset require both `settings.read` and `settings.write`. Optional `read_permission`/`write_permission` values add per-setting requirements: declare those permissions under `domain_shared/permissions`, scan their PermissionDefinitionProvider, and depend on AuthorizationModule. Declaring a permission does not grant it. Internal services own their authorization; Manager still enforces ownership, sources, types, and versions.
+
+Business code decides when to read and apply values. Settings provides no component refresh, change notification, reconciliation, retry, or application status. Generic Notifications and HostedService remain independent capabilities.
+
+### Inspect configuration
 
 Inspect configuration sources and service registrations with:
 

{python_ddd_framework-0.7.3 → python_ddd_framework-0.9.0}/src/python_ddd_framework/settings/__init__.py

@@ -1,30 +1,26 @@
 """Global Runtime Settings 的 typed contract 与 Application-local catalog。"""
 
 from .catalog import SettingCatalog
-from .contracts import SettingDefinition
+from .contracts import SettingDefinition, SettingManagementAccess
 from .definitions import SettingDefinitionContext, SettingDefinitionProvider
 from .errors import RuntimeSettingError, SettingDefinitionError
-from .handlers import SettingApplicationStatus, SettingHandler, SettingHandlerDefinition
 from .manager import SettingManager
 from .provider import SettingProvider
 from .store import RuntimeSettingStore
-from .values import SettingSnapshot, SettingValueSource, SettingWriteOutcome, StoredSetting
+from .values import SettingSnapshot, SettingValueSource, StoredSetting
 
 __all__ = (
     "RuntimeSettingError",
     "RuntimeSettingStore",
-    "SettingApplicationStatus",
     "SettingCatalog",
     "SettingDefinition",
     "SettingDefinitionContext",
     "SettingDefinitionError",
     "SettingDefinitionProvider",
-    "SettingHandler",
-    "SettingHandlerDefinition",
+    "SettingManagementAccess",
     "SettingManager",
     "SettingProvider",
     "SettingSnapshot",
     "SettingValueSource",
-    "SettingWriteOutcome",
     "StoredSetting",
 )

{python_ddd_framework-0.7.3 → python_ddd_framework-0.9.0}/src/python_ddd_framework/settings/application.py

@@ -5,22 +5,25 @@ from __future__ import annotations
 import json
 from typing import Any, cast
 
+from dishka import AsyncContainer
 from pydantic import JsonValue
 
 from ..application_services import ApplicationService, application_service
-from ..authorization import authorize
+from ..authorization import PermissionDeniedError, PermissionName, authorize
+from ..authorization.checking import _check_authorization
+from ..authorization.contracts import _AuthorizationRequirement
 from ..configuration.immutability import _serialization_value
 from ..errors import BusinessError, BusinessErrorDefinition, BusinessErrorField
 from ..errors.base import ResourceNotFoundError
+from ..invocation.runtime import _InvocationRuntime
 from .catalog import SettingCatalog
-from .contracts import SettingDefinition
+from .contracts import SettingDefinition, SettingManagementAccess
 from .management import (
     SETTINGS_READ,
     SETTINGS_WRITE,
     ResetSettingCommand,
     SettingsManagementApplicationService,
     SettingView,
-    SettingWriteResult,
     UpdateSettingCommand,
 )
 from .manager import SettingManager
@@ -32,27 +35,41 @@ _VALUE_FIELD = BusinessErrorField(UpdateSettingCommand, "value")
 
 @application_service(provides=SettingsManagementApplicationService)
 class _SettingsManagementApplicationService(ApplicationService):
-    def __init__(self, catalog: SettingCatalog, settings: SettingManager) -> None:
+    def __init__(
+        self,
+        catalog: SettingCatalog,
+        settings: SettingManager,
+        container: AsyncContainer,
+        runtime: _InvocationRuntime,
+    ) -> None:
         self._catalog = catalog
         self._settings = settings
+        self._container = container
+        self._runtime = runtime
 
     @authorize(SETTINGS_READ)
     async def get_list(self) -> tuple[SettingView, ...]:
-        return tuple(
-            [
-                _view(definition, await self.setting_provider.snapshot(definition))
-                for definition in self._catalog.definitions
-            ]
-        )
+        result: list[SettingView] = []
+        for definition in self._catalog.definitions:
+            if definition.management_access is SettingManagementAccess.HIDDEN:
+                continue
+            try:
+                await self._check_permissions(definition.read_permission)
+            except PermissionDeniedError:
+                continue
+            result.append(_view(definition, await self.setting_provider.snapshot(definition)))
+        return tuple(result)
 
     @authorize(SETTINGS_READ)
     async def get(self, name: str) -> SettingView:
         definition = self._definition(name)
+        await self._check_permissions(definition.read_permission)
         return _view(definition, await self.setting_provider.snapshot(definition))
 
-    @authorize(SETTINGS_WRITE)
-    async def update(self, name: str, command: UpdateSettingCommand) -> SettingWriteResult:
+    @authorize(SETTINGS_READ, SETTINGS_WRITE)
+    async def update(self, name: str, command: UpdateSettingCommand) -> SettingView:
         definition = self._definition(name)
+        await self._check_write(definition)
         try:
             # JSON 数组/日期须由 Pydantic 的 JSON 模式解释，不能误用 strict Python 输入语义。
             value = definition._validate_json(json.dumps(command.value, allow_nan=False))
@@ -61,24 +78,39 @@ class _SettingsManagementApplicationService(ApplicationService):
         saved = await self._settings.update(
             definition, value, expected_version=command.expected_version
         )
-        return SettingWriteResult(
-            setting=_view(definition, saved.snapshot), notification=saved.notification
-        )
+        return _view(definition, saved)
 
-    @authorize(SETTINGS_WRITE)
-    async def reset(self, name: str, command: ResetSettingCommand) -> SettingWriteResult:
+    @authorize(SETTINGS_READ, SETTINGS_WRITE)
+    async def reset(self, name: str, command: ResetSettingCommand) -> SettingView:
         definition = self._definition(name)
+        await self._check_write(definition)
         saved = await self._settings.reset(definition, expected_version=command.expected_version)
-        return SettingWriteResult(
-            setting=_view(definition, saved.snapshot), notification=saved.notification
-        )
+        return _view(definition, saved)
 
     def _definition(self, name: str) -> SettingDefinition[Any]:
         definition = self._catalog.get(name)
-        if definition is None:
+        if definition is None or definition.management_access is SettingManagementAccess.HIDDEN:
             raise ResourceNotFoundError("Setting not found")
         return definition
 
+    async def _check_write(self, definition: SettingDefinition[Any]) -> None:
+        if (
+            definition.management_access is not SettingManagementAccess.READ_WRITE
+            or SettingValueSource.RUNTIME not in definition.allowed_sources
+        ):
+            raise PermissionDeniedError(permission=str(SETTINGS_WRITE))
+        # 写入响应包含完整快照；读权限须在校验设置值及执行保存前成立。
+        await self._check_permissions(definition.read_permission, definition.write_permission)
+
+    async def _check_permissions(self, *permissions: PermissionName | None) -> None:
+        required = tuple(dict.fromkeys(item for item in permissions if item is not None))
+        if required:
+            await _check_authorization(
+                self._container,
+                self._runtime.current_user,
+                _AuthorizationRequirement(True, required, False),
+            )
+
 
 def _view(definition: SettingDefinition[Any], snapshot: SettingSnapshot[Any]) -> SettingView:
     # HTTP DTO 是独立 JSON 副本；不会把内部不可变快照的容器直接交给调用方。

{python_ddd_framework-0.7.3 → python_ddd_framework-0.9.0}/src/python_ddd_framework/settings/binding.py

@@ -6,9 +6,11 @@ from dishka import Provider, Scope
 
 from ..configuration import ConfigurationRoot
 from .catalog import SettingCatalog
+from .errors import SettingDefinitionError
 from .manager import SettingManager
 from .provider import SettingProvider
 from .store import RuntimeSettingStore
+from .values import SettingValueSource
 
 
 def _provide_settings(
@@ -18,6 +20,18 @@ def _provide_settings(
     *,
     has_store: bool,
 ) -> None:
+    # 检查冻结的输入层，不能让存储覆盖或后续配置遮住被禁止的配置贡献。
+    for definition in catalog.definitions:
+        path = f"settings.{definition.name}"
+        if (
+            SettingValueSource.CONFIGURATION not in definition.allowed_sources
+            and configuration._section_inputs(path)
+        ):
+            raise SettingDefinitionError(
+                setting=definition.name,
+                reason=f"configuration source is not allowed at {path}",
+                source=catalog.sources.get(definition.name),
+            )
     if has_store:
 
         def reader(store: RuntimeSettingStore) -> SettingProvider:

python_ddd_framework-0.9.0/src/python_ddd_framework/settings/catalog.py

@@ -0,0 +1,67 @@
+"""Module setting metadata 的 Application-local immutable catalog。"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Mapping
+from types import MappingProxyType
+from typing import Any
+
+from ..diagnostics import SourceLocation
+from ..modularity.discovery import _DiscoveredType
+from .contracts import SettingDefinition
+from .definition_discovery import _collect_setting_definitions
+from .errors import SettingDefinitionError
+
+
+class SettingCatalog:
+    __slots__ = ("_definitions", "_sources")
+
+    def __init__(
+        self,
+        definitions: tuple[SettingDefinition[Any], ...],
+        *,
+        sources: Mapping[str, SourceLocation] | None = None,
+    ) -> None:
+        indexed: dict[str, SettingDefinition[Any]] = {}
+        for definition in definitions:
+            if not isinstance(definition, SettingDefinition):
+                raise SettingDefinitionError(
+                    setting=repr(definition),
+                    reason="catalog entries must be SettingDefinition values",
+                )
+            if definition.name in indexed:
+                raise SettingDefinitionError(
+                    setting=definition.name,
+                    reason="setting is declared more than once",
+                )
+            indexed[definition.name] = definition
+        self._definitions: Mapping[str, SettingDefinition[Any]] = MappingProxyType(
+            dict(sorted(indexed.items()))
+        )
+        self._sources = MappingProxyType(dict(sources or {}))
+
+    @property
+    def sources(self) -> Mapping[str, SourceLocation]:
+        return self._sources
+
+    @property
+    def definitions(self) -> tuple[SettingDefinition[Any], ...]:
+        return tuple(self._definitions.values())
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._definitions)
+
+    def get(self, name: str) -> SettingDefinition[Any] | None:
+        return self._definitions.get(name)
+
+    def require_owned(self, definition: SettingDefinition[Any]) -> None:
+        if self._definitions.get(definition.name) is not definition:
+            raise SettingDefinitionError(
+                setting=definition.name,
+                reason="definition is not owned by this Application",
+            )
+
+
+def _build_setting_catalog(discoveries: tuple[_DiscoveredType, ...]) -> SettingCatalog:
+    definitions, sources = _collect_setting_definitions(discoveries)
+    return SettingCatalog(definitions, sources=sources)