python-ddd-framework 0.7.3__py3-none-any.whl → 0.9.0__py3-none-any.whl

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/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/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/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/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/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/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/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/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/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/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/settings/catalog.py

@@ -4,28 +4,21 @@ from __future__ import annotations
 
 from collections.abc import Iterator, Mapping
 from types import MappingProxyType
-from typing import TYPE_CHECKING, Any
+from typing import Any
 
 from ..diagnostics import SourceLocation
-from ..modularity import ModuleRegistry
 from ..modularity.discovery import _DiscoveredType
 from .contracts import SettingDefinition
-from .declarations import SettingHandlers
 from .definition_discovery import _collect_setting_definitions
 from .errors import SettingDefinitionError
-from .handlers import SettingHandlerDefinition
-
-if TYPE_CHECKING:
-    from ..services.contribution import ServiceContributionRegistry
 
 
 class SettingCatalog:
-    __slots__ = ("_definitions", "_handlers", "_sources")
+    __slots__ = ("_definitions", "_sources")
 
     def __init__(
         self,
         definitions: tuple[SettingDefinition[Any], ...],
-        handlers: tuple[SettingHandlerDefinition[Any], ...] = (),
         *,
         sources: Mapping[str, SourceLocation] | None = None,
     ) -> None:
@@ -45,26 +38,12 @@ class SettingCatalog:
         self._definitions: Mapping[str, SettingDefinition[Any]] = MappingProxyType(
             dict(sorted(indexed.items()))
         )
-        seen: set[tuple[str, type[object]]] = set()
-        for handler in handlers:
-            if not isinstance(handler, SettingHandlerDefinition):
-                raise SettingDefinitionError(setting="handler", reason="invalid handler definition")
-            self.require_owned(handler.setting)
-            key = (handler.setting.name, handler.handler_type)
-            if key in seen:
-                raise SettingDefinitionError(setting=key[0], reason="handler is declared twice")
-            seen.add(key)
-        self._handlers = handlers
         self._sources = MappingProxyType(dict(sources or {}))
 
     @property
     def sources(self) -> Mapping[str, SourceLocation]:
         return self._sources
 
-    @property
-    def handlers(self) -> tuple[SettingHandlerDefinition[Any], ...]:
-        return self._handlers
-
     @property
     def definitions(self) -> tuple[SettingDefinition[Any], ...]:
         return tuple(self._definitions.values())
@@ -83,40 +62,6 @@ class SettingCatalog:
             )
 
 
-def _build_setting_catalog(
-    registry: ModuleRegistry, discoveries: tuple[_DiscoveredType, ...]
-) -> SettingCatalog:
+def _build_setting_catalog(discoveries: tuple[_DiscoveredType, ...]) -> SettingCatalog:
     definitions, sources = _collect_setting_definitions(discoveries)
-    handlers: list[SettingHandlerDefinition[Any]] = []
-    for descriptor, declaration in registry.declarations(SettingHandlers):
-        declared_handlers = declaration.definitions
-        if not isinstance(declared_handlers, tuple):
-            raise SettingDefinitionError(
-                setting=str(descriptor.key), reason="setting_handler_definitions must be a tuple"
-            )
-        handlers.extend(declared_handlers)
-    return SettingCatalog(definitions, tuple(handlers), sources=sources)
-
-
-def _contribute_setting_handler_defaults(
-    registry: ModuleRegistry,
-    contributions: ServiceContributionRegistry,
-) -> None:
-    from dishka import Provider, Scope
-
-    # 声明只拥有 handler 与 setting 的关系；实例和依赖仍交给原生 Dishka APP binding。
-    registered: set[type[object]] = set()
-    for descriptor, declaration in registry.declarations(SettingHandlers):
-        for definition in declaration.definitions:
-            handler_type = definition.handler_type
-            if handler_type in registered:
-                continue
-            registered.add(handler_type)
-            provider = Provider()
-            provider.provide(handler_type, scope=Scope.APP)
-            contributions._add_framework_default(
-                provider=provider,
-                owner=descriptor.key,
-                source=descriptor.declaration_source,
-                reason=f"Settings handler default for {definition.setting.name}",
-            )
+    return SettingCatalog(definitions, sources=sources)

python_ddd_framework/settings/contracts.py

@@ -2,10 +2,12 @@
 
 from __future__ import annotations
 
+from enum import Enum
 from typing import Generic, TypeVar, cast, get_args, get_origin
 
 from pydantic import BaseModel, Secret, SecretBytes, SecretStr, TypeAdapter, ValidationError
 
+from ..authorization import PermissionName
 from ..configuration.immutability import (
     _serialization_value,
     freeze_typed_value,
@@ -13,16 +15,65 @@ from ..configuration.immutability import (
 )
 from ..configuration.values import _looks_secret_name, canonical_path
 from .errors import RuntimeSettingError, SettingDefinitionError
+from .values import SettingValueSource
 
 _T = TypeVar("_T")
 _MISSING = object()
+_ALL_VALUE_SOURCES = frozenset(
+    source for source in SettingValueSource if source is not SettingValueSource.UNSET
+)
+
+
+class SettingManagementAccess(str, Enum):
+    """只限制通用管理入口；内部读写仍遵守设置自身的来源与值契约。"""
+
+    HIDDEN = "hidden"
+    READ_ONLY = "read_only"
+    READ_WRITE = "read_write"
 
 
 class SettingDefinition(Generic[_T]):
-    __slots__ = ("_adapter", "_default", "_name", "_value_type")
+    __slots__ = (
+        "_adapter",
+        "_allowed_sources",
+        "_default",
+        "_management_access",
+        "_name",
+        "_read_permission",
+        "_value_type",
+        "_write_permission",
+    )
 
-    def __init__(self, name: str, value_type: type[_T], *, default: object = _MISSING) -> None:
+    def __init__(
+        self,
+        name: str,
+        value_type: type[_T],
+        *,
+        default: object = _MISSING,
+        allowed_sources: frozenset[SettingValueSource] = _ALL_VALUE_SOURCES,
+        management_access: SettingManagementAccess = SettingManagementAccess.READ_WRITE,
+        read_permission: PermissionName | None = None,
+        write_permission: PermissionName | None = None,
+    ) -> None:
         _validate_setting_name(name)
+        if (
+            not isinstance(allowed_sources, frozenset)
+            or not allowed_sources
+            or any(
+                not isinstance(source, SettingValueSource) or source is SettingValueSource.UNSET
+                for source in allowed_sources
+            )
+        ):
+            raise SettingDefinitionError(
+                setting=name, reason="allowed_sources must contain value sources, not UNSET"
+            )
+        if not isinstance(management_access, SettingManagementAccess):
+            raise SettingDefinitionError(setting=name, reason="invalid management_access")
+        for permission in (read_permission, write_permission):
+            if permission is not None and not isinstance(permission, PermissionName):
+                raise SettingDefinitionError(
+                    setting=name, reason="permissions must be PermissionName values"
+                )
         if not isinstance(value_type, type):
             raise SettingDefinitionError(setting=name, reason="value_type must be a runtime type")
         if _contains_secret_type(value_type):
@@ -46,6 +97,10 @@ class SettingDefinition(Generic[_T]):
         self._value_type = value_type
         self._adapter = adapter
         self._default = validated_default
+        self._allowed_sources = allowed_sources
+        self._management_access = management_access
+        self._read_permission = read_permission
+        self._write_permission = write_permission
 
     @property
     def name(self) -> str:
@@ -59,6 +114,22 @@ class SettingDefinition(Generic[_T]):
     def has_default(self) -> bool:
         return self._default is not _MISSING
 
+    @property
+    def allowed_sources(self) -> frozenset[SettingValueSource]:
+        return self._allowed_sources
+
+    @property
+    def management_access(self) -> SettingManagementAccess:
+        return self._management_access
+
+    @property
+    def read_permission(self) -> PermissionName | None:
+        return self._read_permission
+
+    @property
+    def write_permission(self) -> PermissionName | None:
+        return self._write_permission
+
     def _validate_python(self, value: object) -> _T:
         return cast(
             _T, freeze_typed_value(self._adapter.validate_python(value), allow_secrets=False)

python_ddd_framework/settings/management.py

@@ -2,14 +2,13 @@
 
 from __future__ import annotations
 
-from typing import Literal, Protocol
+from typing import Protocol
 from uuid import UUID
 
 from pydantic import BaseModel, ConfigDict, JsonValue
 
 from ..application_services import ApplicationServiceContract
 from ..authorization import PermissionName
-from ..notifications import NotificationPublishStatus
 from .values import SettingValueSource
 
 SETTINGS_READ = PermissionName("settings.read")
@@ -36,15 +35,6 @@ class SettingView(BaseModel):
     value: JsonValue
     source: SettingValueSource
     version: UUID | None
-    effect: str = "New operations read the saved value; running components apply it separately."
-
-
-class SettingWriteResult(BaseModel):
-    model_config = ConfigDict(frozen=True)
-
-    saved: Literal[True] = True
-    setting: SettingView
-    notification: NotificationPublishStatus
 
 
 class SettingsManagementApplicationService(ApplicationServiceContract, Protocol):
@@ -52,6 +42,6 @@ class SettingsManagementApplicationService(ApplicationServiceContract, Protocol)
 
     async def get(self, name: str) -> SettingView: ...
 
-    async def update(self, name: str, command: UpdateSettingCommand) -> SettingWriteResult: ...
+    async def update(self, name: str, command: UpdateSettingCommand) -> SettingView: ...
 
-    async def reset(self, name: str, command: ResetSettingCommand) -> SettingWriteResult: ...
+    async def reset(self, name: str, command: ResetSettingCommand) -> SettingView: ...