pz-cli 5.0.0__py3-none-any.whl

pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/04-Settings/344/270/216/351/205/215/347/275/256/350/247/204/350/214/203.md

@@ -0,0 +1,1177 @@
+# Settings 与配置规范
+
+> 单一正式读取入口：Python 运行时代码只允许 `import pz_settings_center.public as settings_center`，app 配置只允许 `settings_center.settings.<app_id>.<field>`；`settings.py` / `settings/` 只负责 `AppSettings`、normalize、默认值聚合与 `__runtime_overrides__` 声明。
+
+## 1. 目标
+
+配置体系必须同时满足：
+- 标准 `pip` 安装场景
+- 多 app 命名空间装配
+- 结构化配置表达
+- 环境变量覆盖
+- 最小魔法与明确边界
+- 面向人的作者面可理解性
+
+配置协议固定为三类 owner 协作模型：
+
+- module config owner
+  - 全局唯一模块配置编排职责
+- settings runtime owner
+  - 全局唯一配置写入、运行时变更与 runtime override 职责
+- settings center
+  - 全局唯一运行时读取职责
+
+`pz` 本身只负责在启动与编译期按约定组装这些 owner 的声明与 provider 输出，不承载它们的具体实现；官方实现归属对应最小子包文档。
+
+## 1.1 三层职责边界
+
+### module config owner
+
+职责：
+
+- 声明模块配置
+- 编排模块配置
+- 产出可并入最终 settings snapshot 的配置补丁
+
+不负责：
+
+- 业务代码运行时直接读取配置
+- 持有第二套运行态 settings 状态
+- 绕开 `settings_center` 直接提供并列读取 API
+
+### settings runtime owner
+
+职责：
+
+- 配置写入
+- 配置修改校验
+- 配置审计与变更治理
+- runtime override 生效模式治理
+
+不负责：
+
+- 成为业务代码正式读取入口
+- 发明未声明字段
+- 自己维护第二套 settings snapshot
+
+### settings center
+
+职责：
+
+- 提供最终运行时读取 surface
+- 统一暴露 `settings_center.settings`
+- 汇总项目配置、环境层、module config 编排结果与 runtime overrides
+
+不负责：
+
+- 模块配置管理 UI
+- 配置写入后台逻辑
+- 第二套 schema 声明入口
+
+## 1.2 正式数据流
+
+正式数据流固定为：
+
+1. `settings.py` / `settings/` 中的 settings schema
+2. `pz.jsonc`
+3. `pz.{PZ_ENV}.jsonc`
+4. module config owner 编译出的 module config patches
+5. `<project_dir>/.env`
+6. `<project_dir>/.env.{PZ_ENV}`
+7. 显式环境变量
+8. settings runtime owner 产出的 runtime overrides
+9. settings center 读取 surface
+
+结论：
+
+- `module_config` 只影响最终 snapshot
+- settings runtime owner 只在正式声明允许的字段上做运行时覆写
+- 业务代码最终仍然只读 settings center 的正式公开面
+
+## 1.3 面向人的配置作者面原则
+
+配置作者面首先服务于“人应该去哪里找、怎么看、怎么填”，其次才服务于代码如何消费。
+
+完整的人类配置心智固定为：
+
+1. 先按领域找唯一 owner
+   例如观察链去观察 owner app，执行链去执行 owner app，控制面/运行装配去 runtime owner app。
+2. 在 owner app 的 `configs/default.jsonc` 看完整配置骨架
+   非敏感结构、开关、列表、对象、ref 字段，以及敏感字段对应的位置，都应在这里可见。
+3. 在 owner app 的 `configs/default.env` 只填写敏感覆盖值
+   例如密钥、token、密码、cookie、私钥、credential path。
+4. 运行期由 env layer 覆盖项目 JSONC 静态层
+   不允许反过来由 JSONC 覆盖 env 中的 secret。
+
+正式要求：
+
+- 一个领域、一类能力或一组 concrete 凭证，只允许有一个正式配置 owner。
+- 项目维护者看到某类配置时，应当一眼知道该去哪个 owner app 的 settings namespace 查找与 author。
+- 同一领域的 concrete 配置不得拆散在多个 app namespace 中分别 author；调用方可以消费 ref、projection 或编译结果，但不能把同一组 concrete 字段再复制到自己的 settings 下。
+- 根 `pz.jsonc` 只是 `pz settings init/update` 汇总后的项目作者面，不是允许跨 owner 重新分摊 concrete 配置职责的“第二入口”。
+
+判断标准：
+
+- 如果一个配置项属于观察链，就应统一放在观察 owner app。
+- 如果一个配置项属于执行链，就应统一放在执行 owner app。
+- 如果一个配置项属于控制面或运行装配，就应统一放在控制面 / runtime owner app。
+
+禁止：
+
+- 为了让调用方“顺手就近读取”，把同一领域配置拆成东一块、西一块。
+- 在运行控制面、领域 app、宿主 app 或项目根层同时长期 author 同一套 concrete 配置。
+- 让人必须先理解内部调用链，才能判断一个配置该去哪里改。
+
+## 2. 配置来源
+
+正式配置文件：
+- `pz.jsonc`
+- `pz.{PZ_ENV}.jsonc`
+- `<project_dir>/.env`
+- `<project_dir>/.env.{PZ_ENV}`
+
+settings 作者面模板：
+- 已安装子包的 `configs/default.jsonc`
+- 已安装子包的 `configs/default.env`
+
+`configs/default.jsonc` 与 `configs/default.env` 只允许由 `pz settings init/update` 读取，用于生成或补全项目根配置文件。启动阶段不得直接读取已安装子包的 `configs/default.jsonc` 或 `configs/default.env`。
+
+作者面模板口径固定为：
+
+- `configs/default.jsonc` 必须表达该 owner app 的完整配置骨架。
+- 这里的“完整”指：非敏感结构化字段、开关、列表、对象、ref 字段，以及敏感字段在 schema 上对应的位置，都应在 `default.jsonc` 中可见。
+- 敏感字段在 `default.jsonc` 中只保留空值、占位值或 ref 占位，用来告诉人“这里存在这项配置”，不得写入真实 secret。
+- `configs/default.env` 只承载密钥、token、密码、cookie、私钥、credential path 等敏感 env 覆盖项；不承载第二套非敏感结构化配置。
+- `configs/default.env` 的正式语义是：为 `default.jsonc` 中对应的敏感字段提供 env 覆盖作者面，而不是另起第二套 schema。
+
+关键注意事项：
+- 子包升级后新增的默认配置键不会自动进入运行时，必须通过 `pz settings update` 显式同步到项目根配置
+- 启动期发现必需配置缺失时，应报出缺失路径与修复建议，例如提示执行 `pz settings update --project-dir <project_dir>`，不得回退读取包内模板来补值
+- `pz check` 应包含一个正式的 settings update drift 诊断项；该诊断只能复用 `pz settings update` 的同源 dry-run 计划判断“当前执行 update 是否会产生配置同步变更”，不得按 `default.jsonc` 的 mtime、hash 或手写 diff 另建第二套判断规则
+- `settings.py` / `settings/` 可以声明 schema、normalize 与 runtime override metadata，但 import 阶段不得读取包内 `configs/default.jsonc`、包内 `configs/default.env`、项目 `.env*` 或进程环境变量
+- 包内 `configs/default.jsonc` / `configs/default.env` 仍必须随 wheel 分发，因为生产环境的 `pz settings init/update` 需要从已安装包读取模板
+- 包升级、wheel 内容变化、缺少模板文件都不应改变已经生成的运行时 `SettingsSnapshot`；线上默认行为只由项目根配置与 env layer 决定
+
+项目级 JSONC 协议：
+- 项目级配置唯一正式作者面固定为 `pz.jsonc`
+- 环境级项目覆盖唯一正式作者面固定为 `pz.{PZ_ENV}.jsonc`
+- JSONC 的正式读写必须统一通过 `pz/utils/project_jsonc/` 模块，不允许各处自行解析或回写
+- `project_jsonc` 负责：
+  - 解析 JSONC
+  - 过滤普通注释的语义影响
+  - 保留并处理工具注释
+  - 提供统一的读写、托管区更新与写回能力
+
+工具注释约定：
+- 工具注释独占前缀固定为 `// @pz:`
+- 当前正式支持的 directive 只有：
+  - `// @pz:managed:start <path>`
+  - `// @pz:managed:end <path>`
+- 其它 `// @pz:*` 暂视为保留扩展位；当前版本应识别为工具注释但默认忽略，不得因未知 directive 直接报错
+- 其它普通 `// ...` 注释只作为人类说明文本，不参与配置语义
+- `project_jsonc` 在写回时应尽量保留普通 `// ...` 注释与相邻结构位置，但不承诺字节级原样保留
+
+`installed_apps` 语义：
+- `installed_apps` 可以直接声明正式最小子包，也可以声明文件夹/容器目录
+- 每个最小子包都必须显式拥有自己的 `configs/default.jsonc`
+- 每个最小子包都应配对拥有自己的 `configs/default.env`；无密钥字段时保留空模板即可
+- `configs/` 必须是正式 Python 子包并包含 `configs/__init__.py`；`configs/default.jsonc` 与 `configs/default.env` 必须进入 wheel 后仍可被 settings 工具读取
+- 分组目录只用于 Git 与源码组织，不参与运行时 namespace
+- 若声明的是文件夹/容器目录，框架必须自动递归发现其中嵌套的最小子包
+- settings、app registry、resources、routes 等正式装配单元等于递归展开后的最小子包集合
+- `installed_apps` 的条目语法固定为目录名，不接受文件系统路径、distribution 名或 `<pkg>.apps:app`
+
+叶子 app namespace 语义：
+- 每个叶子 app 的唯一配置命名空间固定为其 `app.id`
+- 不允许再单独声明第二个 settings namespace
+- 新建子包默认让 `app.id` 等于最小子包目录名与 import 包名；历史子包已发布的 `app.id` 以稳定值为准，不因文档命名口径变化自动迁移
+
+环境覆盖：
+- 环境变量
+- `<project_dir>/.env`
+- `<project_dir>/.env.{PZ_ENV}`
+
+密钥模板：
+- 已安装子包的 `configs/default.env`
+
+`configs/default.jsonc` 只作为 `pz settings init/update` 生成或补全项目 `pz.jsonc` / `pz.{PZ_ENV}.jsonc` 的 authoring 模板来源，不属于 `SettingsSnapshot` 的启动期输入。
+
+`configs/default.env` 只作为 `pz settings init/update` 生成项目 `.env*` 的 authoring 模板来源，不属于 `SettingsSnapshot` 的启动期输入。启动阶段的 env layer 只读取项目 `.env`、项目 `.env.{PZ_ENV}` 与显式环境变量。
+
+两者关系固定为：
+
+- `default.jsonc` 先声明完整配置骨架。
+- `default.env` 再为其中需要保密的字段提供覆盖入口。
+- 运行期进入 `SettingsSnapshot` 时，env layer 对项目 JSONC 静态层生效覆盖；不允许反过来由 JSONC 覆盖 env 中的 secret。
+- 因此，人的作者面心智应当是“先在 `default.jsonc` 看完整长相，再在 `default.env` 填敏感值覆盖对应字段”。
+
+`configs/default.env` 可对需要自动生成的密钥使用 `@pz:secret:urlsafe64` 或 `@pz:secret:hex64` 作为值。`pz settings init/update` 会在项目 `.env` 中生成持久强随机值；如果项目 `.env` 已存在非空值则保留，存在空值则补齐。`.env.{PZ_ENV}` 仍只渲染注释占位符，除非项目已有显式环境值。
+
+项目环境选择：
+- `PZ_ENV`
+
+约束：
+- `PZ_ENV` 是唯一正式环境选择变量
+- 编译后的 project snapshot 可以暴露派生字段 `project.pz_env`，但它不是新的外部输入入口
+- 未显式指定 `PZ_ENV` 时，正式默认环境固定为 `develop`
+- `product` 环境必须在启动命令或进程环境中显式指定；不允许靠读取 `.env.product` 反向推导当前环境
+- `.env.{PZ_ENV}` 只允许在环境已经选定后参与加载，不得作为环境选择输入来源
+- `project.environment` / `project.env` / `project.pz_env` / 顶层 `environment` / 顶层 `pz_env` 都不再作为输入来源
+- 上述旧环境选择字段如果出现在 `pz.jsonc` 或传入 payload 中，正式行为是直接报错，而不是静默忽略
+
+## 3. 配置优先级
+
+`SettingsSnapshot` 编译顺序固定为：
+
+1. 读取 `settings.py` / `settings/` 的 schema、normalize 与 runtime override 声明；声明模块不得在 import 阶段读取 `configs/default.jsonc` 或 `.env*`
+2. 读取 `pz.jsonc`
+3. 读取 `pz.{PZ_ENV}.jsonc`
+4. 读取 module config owner 编译出的 module config patches
+5. 读取 `<project_dir>/.env`
+6. 在环境已选定后读取 `<project_dir>/.env.{PZ_ENV}`
+7. 叠加显式环境变量，形成受保护的 env layer
+8. 合并项目静态层与 env layer，优先级固定为：
+   - `pz.jsonc`
+   - `pz.{PZ_ENV}.jsonc`
+   - module config patches
+   - `.env`
+   - `.env.{PZ_ENV}`
+   - 显式环境变量
+9. 解析 `installed_apps` / `app_replacements`
+10. 组装 `apps.<app_id>`
+
+补充说明：
+- `.env`、`.env.{PZ_ENV}` 与显式环境变量组成统一 env layer，其中显式环境变量优先于 `.env.{PZ_ENV}`，`.env.{PZ_ENV}` 优先于 `.env`
+- `pz.jsonc` 与 `pz.{PZ_ENV}.jsonc` 是启动期项目静态配置来源，不得覆盖 env layer
+- 上述顺序描述的是 `SettingsSnapshot` 的正式编译主链
+- `SettingsSnapshot` 编译主链不得调用 `load_app_default_settings_payload()`、`load_local_default_settings()` 或任何等价的包内默认模板读取 helper
+- 对 app 运行时代码而言，正式读取顺序固定为：
+  1. `SettingsSnapshot.apps.<app_id>` 基线值
+  2. app settings provider 补充值
+  3. settings runtime owner runtime overrides
+- provider 只参与运行时读取，不参与 `SettingsSnapshot` 编译
+- 普通业务运行时读取入口固定为 `settings_center.settings.<app_id>`；`resolve_settings(project_dir=...)` 只允许用于明确的跨项目工具面或 owner 级基础设施探针，不得成为业务子包的第二套 app settings 读取主链
+- `pz settings init` 只负责一次性读取 `installed_apps` 展开后的所有最小子包 `configs/default.jsonc` / `configs/default.env`，并生成项目根 `pz*.jsonc` 与 `.env*`
+- 底层 scaffold service 应同时生成项目根 `pz.jsonc`、`pz.develop.jsonc`、`pz.test.jsonc`、`pz.product.jsonc`、`.env`、`.env.develop`、`.env.test`、`.env.product`；公开 CLI 初始化入口固定为分组命令
+- `pz.develop.jsonc` / `pz.test.jsonc` / `pz.product.jsonc` 必须写入对应环境的非敏感静态覆盖骨架，不能使用空 `{}` 作为长期正式模板
+- `pz settings init` 在这些文件缺失时也必须补齐同名骨架；其中 `.env` 必须写入默认 env 模板，`.env.develop` / `.env.test` / `.env.product` 必须写入对应环境占位模板
+- `pz settings init/update` 必须读取已安装最小子包的 `configs/default.env`，把其中变量合并进项目 `.env*`；`.env` 使用未注释占位，`.env.{PZ_ENV}` 使用注释占位，已有同名项目值必须保留
+- 默认 `.env` 模板应参考当前正式项目 env 键面，只保留当前正式 settings/source-of-truth 仍认可的 env 项；`PZ_AGENT*`、`SEO_OPS*` 这类已移出当前正式 settings 真相源的键不得进入默认模板
+- 默认环境 JSONC 模板应只放非敏感、结构化、适合进入 `pz.{env}.jsonc` 的覆盖项，例如 `project.base_url`、`project.STATIC_TARGET_*`、middleware 静态覆盖；不得把 secrets 写回 JSONC
+- `pz settings init` 自动补齐 env / jsonc 骨架时，不得覆盖项目中已存在的同名文件
+- `pz settings init` 不得内置业务宿主模板白名单，也不定义面向业务默认值的项目骨架扩展机制
+- 当前版本不定义正式的初始化骨架扩展协议；`pz settings init` 只生成 `pz` 内建的通用作者面骨架
+- `pz` 不提供第二套 init 命令、业务 profile 参数或初始化骨架注册器
+- 项目级 `pz.jsonc` 默认骨架属于作者面能力，正式真相源固定为 `pz/authoring/project_default.jsonc`
+- `project_default.jsonc` 的正式职责固定为：`pz` 的通用作者面默认骨架
+- `project_default.jsonc` 当前没有正式扩展点；项目级通用骨架只能由 `pz` 内建实现维护
+- 各最小子包 `configs/default.jsonc` 的正式职责固定为：各子包自己的 settings 作者面默认模板，只供 `pz settings init/update` 读取
+- 各最小子包 `configs/default.jsonc` 可以声明受控的顶层路由默认值 `routing.default_language`、`routing.all_supported_languages`、`routing.language_aliases`；`pz settings init/update` 会把这些值提升到根 `routing`，并从 `apps.<app_id>` 私有配置中剥离
+- 各最小子包 `configs/default.jsonc` 可以声明受控的顶层快捷命令 `commands`；`pz settings init/update` 会把这些值提升到根 `commands`，同名命令以 app 默认刷新，未声明的项目自定义命令保留
+- 各最小子包 `configs/default.jsonc` 可以声明受控的项目装配状态 `apps.*.sources.source_mode`；`pz settings init/update` 会把该字段提升到根 `apps` 对应 owner，作为 local/git/package 源码策略的单一真相
+- 各最小子包 `configs/default.env` 的正式职责固定为：各子包自己的 Git 可追踪 secret 占位模板，只供 `pz settings init/update` 读取
+- `project_jsonc` 只负责协议与读写规则，不承载默认骨架内容
+- `pz` 是该骨架的唯一作者面与 CLI 执行器；`pz_settings_center` 只提供运行时 settings surface，不再承担作者面职责
+- 生成时应基于当前已安装目录声明递归发现最小子包，并使用 `project_jsonc` 在 JSONC 中生成托管区块
+- 托管区块必须通过 `// @pz:managed:start <path>` / `// @pz:managed:end <path>` 表达，而不是由业务层自行约定其它注释协议
+- `pz settings init` 的正式托管区固定为：
+  - `installed_apps`
+  - `middlewares`
+- `middlewares` 托管区是项目级 middleware 作者面真相源；工具应基于当前发现结果编译 conventional middleware manifest，并写回顶层 `middlewares`
+- 若根目录已存在 `pz.jsonc`，默认必须拒绝覆盖；只有显式传入 `pz settings init --force` 时，才允许在自动备份后按当前发现结果整体重生成 settings 文件
+- `pz settings init --force` 的正式语义是“备份当前 `pz.jsonc`、`pz.{env}.jsonc` 与 `.env*` 后，删除旧 settings 语义并按当前可发现 app 集重新生成”，不是在旧 `pz.jsonc` 上做保留式 merge
+- `pz settings update` 负责再次扫描已安装 app，只补充新增的默认配置键，不覆盖 `pz.jsonc` 中已经存在的项目级值
+- `pz settings update` 是“把包内模板变成项目运行时配置”的唯一正式入口；不要在启动、provider、middleware、lifespan 或业务 import 阶段临时补写默认值
+- settings update drift 诊断是 `pz settings update` 的只读预演：它可以读取同一批 app `configs/default.jsonc` / `configs/default.env` 与项目 settings 文件，比较 dry-run 的 settings payload 与 env 模板合并结果是否会改变 `pz.jsonc`、`pz.{env}.jsonc` 或 `.env*`；诊断结果只进入 `pz check` 的 `CheckReport`，不写文件、不创建备份、不生成运行时默认值
+- 上述“不覆盖”只适用于项目作者显式写入的业务值；如果某个 app 在 `settings.py` / `settings/` 中正式声明了 normalize 规则，`pz settings update` 只允许在当前稳定合同内做归一化，不再负责历史别名或旧键迁移
+- 这类归一化必须由 app 自己在 `settings.py` / `settings/` 中声明，不能靠宿主手改 `pz.jsonc`、middleware 构造期临时补写、bootstrap 阶段偷偷修正，或工具侧兼容旧键
+- `pz settings update` 更新 `middlewares` 托管区时，应先按当前 app 集合重新编译 conventional middleware manifest；若项目中已存在显式 middleware 顺序，则已知 middleware id 的相对顺序保持项目作者面真相，并按 conventional manifest 追加新发现的 middleware
+- `pz settings update --reset-middlewares-order` 可显式要求按当前 conventional middleware manifest 重写托管区顺序；该选项只影响托管区，不覆盖非托管业务配置
+- `pz settings update <target>` 允许只补充指定最小子包的默认配置
+
+边界：
+- `.env` 本质属于环境变量来源的一部分
+- `.env` / `.env.{PZ_ENV}` 仅作为开发便利，不应替代正式配置文件
+- 数据库、Redis、密钥、外部服务地址等敏感或部署相关配置应优先放在 `.env`
+
+补充约束：
+- `.env` 搜索不应继续围绕 `ROOT_DIR` 或框架源码仓库根目录展开
+- `.env` 只允许使用 `<project_dir>/.env`
+- `.env.{PZ_ENV}` 只允许使用 `<project_dir>/.env.{PZ_ENV}`
+- 配置加载器不应再把合并后的环境键值写回 `os.environ`
+- settings 构建应消费显式 env snapshot，而不是通过“先改写进程环境，再让 `BaseSettings` 回读”实现
+- `pyproject.toml` 中的历史框架私有配置段不作为正式配置来源
+
+## 3.1 配置装配的确定性约束
+
+从工程实践看，配置系统首先必须是可预测的。
+
+要求：
+
+- 同一组输入在同一版本下必须产出同一份 settings snapshot
+- 配置解析阶段不得触发网络 I/O
+- 配置解析阶段不得触发 DB/Redis 探测
+- 配置解析阶段不得顺手执行资源 merge、asset build、migrations 聚合
+- settings snapshot 一旦完成，就应作为入口期稳定输入传入后续装配链
+- settings snapshot 必须视为只读编译产物，不允许在 bootstrap/lifespan/startup 中被原地改写
+
+不采用：
+
+- 先给一份半初始化 settings
+- 后续 bootstrap/lifespan 再补字段、改字段、重算字段
+
+## 3.2 Settings 编译边界
+
+Settings 编译阶段只允许做三类事情：
+
+1. 读取输入
+   - `pz.jsonc`
+   - `pz.{PZ_ENV}.jsonc`
+   - `<project_dir>/.env`
+   - `<project_dir>/.env.{PZ_ENV}`
+   - 显式环境变量
+2. 归一化字段
+   - 路径锚点
+   - 命名空间映射
+   - 派生字段计算
+3. 产出只读 `SettingsSnapshot`
+
+禁止：
+
+- 在 `AppSettings` / `CoreSettings` validator 中做跨 app 规则裁决
+- 在配置编译阶段执行 I/O、provider lookup、client 初始化、resource 扫描
+- 在 settings 模型中混入 route/middleware/resource/infra 的运行时装配逻辑
+- 通过 settings hook/validator 顺手修改全局单例或注册 provider
+
+补充要求：
+
+- 数据库、Redis、外部服务 client 等启动前依赖的配置，必须在 `SettingsSnapshot` 编译完成后即可完整可读
+- app provider 只能补充“app 已启动后才能知道的运行态配置”，不能承担基础连接配置真相源职责
+- provider 不得反向改写 `SettingsSnapshot`
+
+正式要求：
+
+- `AppSettings` / `SettingsSnapshot` 只表达配置结果，不承担运行时副作用职责
+- 跨 app 规则、冲突治理、capability 绑定都必须在后续专用 compiler/registry 中完成
+
+## 3.3 配置读取的单一路径原则
+
+从运行时代码视角，配置读取也必须只有一种正式方式。
+
+正式要求：
+
+- 编译阶段统一产出唯一 `SettingsSnapshot`
+- 运行阶段可以基于当前 `SettingsSnapshot` 派生内部 `ResolvedSettings` 视图，但这些都不是应用层正式读取入口
+- Web / CLI / worker / app runtime 在应用层只允许通过 `settings_center.settings` 读取配置
+- app 代码读取私有配置时，只能读取 `settings_center.settings.<app_id>`
+- app 运行时正式入口固定为：
+  - `settings_center.settings`
+
+补充要求：
+
+- `app_id` 必须来自正式叶子 app 的 `app.id`
+- 没有叶子 app 身份的内部模块，不允许自造新的 `app_id`
+- 这类内部模块只能读取所属父 app 的 `<app>.settings` 命名空间，也就是 `settings_center.settings.<parent_app_id>`
+- 若读取的是项目级装配信息，只能读取 `settings_center.settings.project.<field>`
+
+不允许：
+
+- 一部分代码读 `SettingsSnapshot`
+- 一部分代码再读基础包内部 settings helper
+- 一部分代码再直接读 `os.environ`
+- 一部分代码再去项目目录重读 `pz.jsonc`
+- 一部分代码再自己推导非 `PZ_ENV` 的环境选择路径
+
+约束：
+
+- `SettingsSnapshot` 是唯一正式配置真相源
+- `ResolvedSettings` 是唯一正式运行时大 settings 视图
+- `settings_center.settings` 是应用层唯一正式 Python settings 入口对象
+- `pz.runtime.settings` 只保留底层 machinery
+- 任意 request helper、middleware、CLI tool、worker loop 都不得自建第二套 settings 读取路径
+
+补充结论：
+
+- module config owner 不是运行时读取入口
+- settings runtime owner 不是运行时读取入口
+- 运行时代码只允许 `import pz_settings_center.public as settings_center`
+
+### 3.4 settings lazy autoload
+
+`settings_center.settings` 支持正式的 settings lazy autoload。它的目标是让普通脚本与 app 运行时代码拥有同一条配置读取心智：
+
+```python
+import pz_settings_center.public as settings_center
+
+value = settings_center.settings.<app_id>.<field>
+```
+
+正式语义：
+
+- `import pz_settings_center.public as settings_center` 只取得 settings 读取 surface，不得在 import 阶段编译或绑定 `SettingsSnapshot`
+- 第一次访问 `settings_center.settings.project`、`settings_center.settings.<app_id>`、`settings_center.settings.get(...)` 或 `settings_center.settings.app_settings(...)` 时，如果当前进程还没有绑定 snapshot，框架才自动编译当前项目的 `SettingsSnapshot`
+- 如果当前进程已经处在 `pz run`、`pz <app_id> <tool>`、worker 或其它正式入口中，lazy autoload 必须优先消费当前已绑定的 runtime snapshot
+- 直接运行脚本并通过 `settings_center.settings` 读取时，project 选择优先级固定为：已绑定 runtime snapshot > `PZ_PROJECT_DIR` > 从当前工作目录向上查找 `pz.jsonc`
+- 跨项目工具面显式调用 `settings_center.resolve_settings(project_dir=...)` 时，该显式 `project_dir` 只作用于本次解析，并优先于当前进程的默认项目发现
+- 环境选择仍只认 `PZ_ENV`，未显式指定时固定为 `develop`
+- lazy autoload 只保证 settings center 可用；它不是 runtime autoload，不保证 `RuntimePlan`、route manifest、resource manifest、infra provider、middleware、worker lifecycle 或 runtime bindings 已经完成
+
+约束：
+
+- settings lazy autoload 不得读取已安装子包的 `configs/default.jsonc` / `configs/default.env` 来补值
+- 找不到项目、配置缺失或类型错误时，必须按 settings 编译链报正式错误，不得 fallback 到包内默认值或第二套项目发现规则
+- app 运行时代码不得因为 lazy autoload 存在而改用 `resolve_settings(project_dir=...)` 作为第二读取主链；普通读取仍固定为 `settings_center.settings.<app_id>`
+- settings provider 必须轻量、确定且无运行时副作用，只能依赖 `SettingsSnapshot` / `ProjectContext` / provider context，不得依赖 Web app、route manifest、resource build、数据库连接、Redis 连接或 runtime bindings
+- provider patch 仍只参与最终 settings 视图，不得反向改写 `SettingsSnapshot`
+
+## 4. 全局配置与 app 配置
+
+### 4.1 全局配置
+
+核心字段使用：
+- `settings_center.settings.project.<field>`
+
+例如：
+- `settings_center.settings.project.name`
+- `settings_center.settings.project.base_url`
+- `settings_center.settings.project.installed_apps`
+- `settings_center.settings.project.cache_dir`
+- `settings_center.settings.project.runtime_dir`
+- `settings_center.settings.project.asset_dir`
+
+补充约束：
+- `create_app()`、`create_host_app()`、CLI、worker 都不应默认回落到进程级全局 `settings`
+- 它们应优先消费显式传入或显式解析出来的 settings snapshot
+- “导入模块就锁定当前项目上下文”的旧行为必须删除，不能继续作为正式配置模型
+
+### 4.2 app 配置
+
+业务或插件配置统一使用：
+- `settings_center.settings.<app_id>.<field>`
+
+例如：
+- `settings_center.settings.content_app.route_policy`
+- `settings_center.settings.example_app.site_image`
+
+要求：
+- 不再将 app 私有字段扁平化注入全局根命名空间
+
+补充约束：
+- app 运行时代码不应长期保留“命名空间优先、根级历史字段回退”的双读模式
+- 任何 app 私有字段与根级历史字段并存的双读方式，都必须收口到单一路径
+- 新版规范里，app 私有配置的唯一稳定读取入口应为 `settings_center.settings.<app_id>`
+- 不允许再额外引入 `settings.<custom_namespace>` 这类独立于 `app.id` 的第二命名空间
+
+### 4.2.1 app 运行时消费边界
+
+`settings_center.settings.<app_id>` 是 app 运行时拿到的最终 typed 配置对象。进入业务运行时后，字段值已经完成项目配置、环境层、provider patch 与 runtime override 的合并、类型化、默认补齐与必要 normalize。
+
+子包运行时代码只允许消费最终字段值：
+
+- 读取路径固定为 `settings_center.settings.<app_id>.<field>`
+- 可以把字段值直接传入 service、store、client、worker、middleware、URL builder 等运行时对象
+- 可以在 runtime builder 中把多个字段组装成业务构造参数，但该组装不得重新定义配置来源、默认值或类型语义
+
+子包运行时代码不允许再做 settings center 已经负责的事情：
+
+- 不允许新增 `runtime_settings.py`、`system_settings.py`、`load_<app>_settings()`、`resolve_<app>_settings()` 等第二读取主链
+- 不允许读取 `os.environ`、项目 `.env*`、`pz*.jsonc`、包内 `configs/default.jsonc` / `configs/default.env` 来补配置
+- 不允许在运行时使用 `bool(...)`、`int(...)`、`float(...)`、`str(...)` 等方式重新解释 settings 字段类型
+- 不允许用本地 dataclass 默认值、硬编码默认值、`or <default>`、`try/except missing -> default` 覆盖 settings center 的最终值
+- 不允许包装一套本地 “settings missing” 错误来隐藏 settings center / `SettingsSnapshot` 的缺失语义
+- 不允许通过 `env` 参数、legacy root 字段、历史 namespace 或 helper fallback 形成第二套读取顺序
+
+子包需要做的配置工作只限声明层：
+
+- 在 `settings.py` / `settings/` 中声明 `AppSettings` 字段类型、校验、必要 normalize 与 `__runtime_overrides__`
+- 在 `configs/default.jsonc` / `configs/default.env` 中提供 `pz settings init/update` 的作者面默认模板
+- 在子包设计文档中说明字段语义、取值范围、运行时影响与 owner 边界
+
+如果某个字段需要默认值、类型转换、别名兼容、环境变量覆盖或 runtime override 生效，必须进入 settings 编译链或 settings runtime owner 的正式链路，不能落在业务运行时模块里。
+
+## 4.3 app settings 实现方式
+
+新规范采用：
+- app 的 `AppSettings` 使用 `BaseModel`
+- `AppSettings` 只承载 schema、类型校验与必要 normalize，不再承载默认值真相源
+- 框架统一负责从 `pz.jsonc`、`pz.{PZ_ENV}.jsonc`、项目 `.env*`、显式环境变量、运行时覆盖中构建 `settings_center.settings.<app_id>`
+- 运行时不再公开 `load_app_settings()`、`load_typed_app_settings()`、`load_<app>_settings()` 这类第二入口
+
+不允许：
+- 每个 app 自己使用 `BaseSettings + env_prefix` 各自再读一遍环境变量
+
+目的：
+- 避免配置读取逻辑分散
+- 避免聚合器与 app 自读环境形成双重真相源
+- 便于未来统一配置文件语义
+
+补充要求：
+- app settings 聚合器正式只包含：
+  - `pz.jsonc` / `pz.{PZ_ENV}.jsonc` 中的 `apps.<app_id>`
+  - 项目 `.env` / `.env.{PZ_ENV}` / 显式环境变量中的 `<APPID>__*`
+  - app settings provider
+  - 运行时覆盖
+- 包内正式默认模板文件固定为 `configs/default.jsonc`，只由 `pz settings init/update` 消费
+- 不再支持项目级 `configs/apps/*.toml`
+- 项目级 app 配置搜索不应再把 `Path.cwd()` 与 `ROOT_DIR` 一起并列当成 project root 候选
+- app settings 聚合器不应反向 import 基础包全局 settings 实例或私有 env helper 再拼装命名空间
+- namespace attach 与 runtime overrides schema 注册不应再混在同一个副作用流程里
+
+## 4.4 module config 正式协议
+
+module config owner 的正式对象固定为：
+
+- `ModuleConfigDefinition`
+- `ModuleConfigField`
+- `ModuleConfigBinding`
+- `ModuleConfigPatch`
+
+其中：
+
+- 前三者属于声明期对象
+- `ModuleConfigPatch` 属于编译产物
+
+### 4.4.1 `ModuleConfigDefinition`
+
+至少应包含：
+
+- `module_id`
+- `title`
+- `owner_app`
+- `version`
+- `description`
+- `enabled_by_default`
+- `fields`
+- `bindings`
+- `depends_on`
+
+约束：
+
+- `module_id` 全局唯一
+- `owner_app` 必须是正式 `app.id`
+- `fields` 内字段名唯一
+- `bindings` 只能引用本 definition 内已声明的 `source_field`
+
+### 4.4.2 `ModuleConfigField`
+
+至少应包含：
+
+- `name`
+- `type`
+- `label`
+- `description`
+- `required`
+- `default`
+- `choices`
+- `secret`
+- `group`
+- `runtime_override`
+- `restart_mode`
+
+`type` 必须采用封闭类型系统，只允许正式枚举集合：
+
+- `string`
+- `text`
+- `int`
+- `float`
+- `bool`
+- `enum`
+- `json`
+- `list[string]`
+- `list[int]`
+- `list[enum]`
+- `dict[string,string]`
+- `secret`
+- `url`
+- `email`
+- `path`
+- `duration`
+- `bytesize`
+
+不允许：
+
+- `custom`
+- 任意 Python type path
+- callable / class / instance 进入类型层
+
+### 4.4.3 `ModuleConfigBinding`
+
+至少应包含：
+
+- `source_field`
+- `target_app`
+- `target_path`
+- `transform`
+- `priority`
+- `condition`
+
+约束：
+
+- `target_path` 必须是声明式点路径
+- 默认只允许 `source_field -> target_app.target_path`
+- `transform` 仅允许作为受控例外存在
+- `transform` 必须引用已注册、命名、纯函数式转换器
+- 不允许任意写入函数
+- 不允许以执行代码的方式直接改写 settings tree
+
+### 4.4.4 `ModuleConfigPatch`
+
+至少应包含：
+
+- `app_id`
+- `payload`
+- `source_module`
+- `priority`
+
+约束：
+
+- patch 必须是纯数据
+- patch 最终只能并入 `SettingsSnapshot`
+- patch 不是业务代码正式读取对象
+
+### 4.4.5 页面域 module config 输入
+
+页面相关的 `module config` 静态默认值已经并入 `pz_page_center`。
+
+正式输入固定为：
+
+- app `pages/base.jsonc`
+
+约束：
+
+- 页面相关 `module config` 必须由 `pz_page_center` 在启动编译期统一扫描和编译
+- 页面相关 `module config` 拥有独立的页面配置命名空间；它不是 `settings_center.settings.<app_id>` 的子树，也不是第二套 settings namespace
+- 页面配置命名空间固定由 `owner_app + 页面相对路径` 确定，并由 `pz_page_center` 统一裁决
+- 业务 app 不再通过 `public.py` 暴露 `get_public_module_configs()`
+- 多个 app 的页面域静态输入，按 app registry / `installed_apps` 顺序由 `pz_page_center` 统一裁决
+- `base` 页面配置允许由多个 app 在自己的 `pages/base.jsonc` 中共同贡献
+- `locales/config.json` 不再作为 `module config` 的正式文件输入
+- app 若需要私有 JSON 文件，只能作为 app 内部实现细节存在，不得再提升成第二套框架级页面配置入口
+
+## 4.5 module config 与 settings runtime owner 的边界
+
+正式边界：
+
+- module config owner 负责“这是什么配置”
+- settings runtime owner 负责“这个配置如何被修改和生效”
+- settings center 负责“运行时代码如何读取最终配置”
+
+不允许：
+
+- module config owner 自己暴露并列运行时读取 API
+- settings runtime owner 自己成为配置读取入口
+- settings center 再定义第二套模块配置 schema 协议
+
+正式原则：
+
+- 配置可以有声明层、编排层、写入层
+- 运行时读取层只能有一层，即 settings center 的正式公开面
+
+### 4.5.1 基础设施配置归属
+
+database、cache、storage、mail、health、observability、bot logger 这类基础设施配置必须由对应 infra owner 的 app settings 承载。
+
+`pz` core 只规定：
+
+- `pz settings init/update` 从 owner 子包的 `configs/default.jsonc` 把默认配置补入项目配置
+- 项目覆盖来自 `pz.jsonc` / `pz.{PZ_ENV}.jsonc` 的 `apps.<app_id>`
+- 环境变量只作为覆盖层，命名遵守本文规则
+- runtime override 必须通过 `AppSettings.__runtime_overrides__` 声明
+
+具体字段、默认值、降级语义、renderer 名称、第三方通道环境变量等实现细节，必须写在对应 owner 子包设计文档中，不得沉入 core settings 规范。
+
+补充约束：
+
+- owner app 的选择应优先服从“人对这个领域会去哪里找”的心智，而不是“当前哪段代码最先读取到它”。
+- 一旦某类 concrete 配置已经归属某个 owner app，其它 app 只能引用、编译或消费，不得再新增第二处 authoring 入口。
+
+## 4.4 app settings provider 与热更新标注
+
+当某个 app 的部分配置只能在 app 启动后确定时，正式做法如下：
+
+- 由 app `extensions()` 声明正式 `settings.provider`，运行时统一编译为 `SettingsProviderSpec`
+- provider 输入固定为：
+  - `app_id`
+  - `SettingsSnapshot`
+  - `project_dir`
+- provider 只能返回当前 app 的补充值，不得直接读写全局单例 settings
+- provider 必须可 reset，且具备 owner 语义
+
+正式合并顺序固定为：
+
+1. `SettingsSnapshot.apps.<app_id>`
+2. provider 返回值
+3. runtime overrides 作为 `pz_settings_center` 的高优先级 `settings.provider` patch 进入同一条 provider 合并链路；`pz` core 不持有 runtime override 状态或命令式写入口
+
+热更新暴露规则：
+
+- 哪些字段允许被 settings runtime owner 线上热更新，必须在 `AppSettings` 上显式标注
+- 正式标注方式固定为：
+  - `AppSettings.__runtime_overrides__`
+- settings runtime owner 只读取这套标注生成 runtime override schema
+
+正式写法固定为“字段 -> 配置对象”的 dict：
+
+- `__runtime_overrides__ = {"enabled": {"mode": "live", "label": "启用开关"}}`
+
+正式 mode：
+
+- `live`
+- `refresh`
+- `restart_required`
+
+写入行为固定为：
+
+- `live`
+  - 保存后立即应用到当前进程运行态
+- `refresh`
+  - 保存后写入持久层与 L2
+  - 由运行态刷新链路在下一次 refresh 时生效
+- `restart_required`
+  - 保存后只进入持久层
+  - 必须重启进程后才生效
+
+附加约束：
+
+- 未注册 namespace 不允许写入 runtime override
+- 未在 schema 中声明的 key 不允许写入
+- 写入值必须通过服务端类型校验，不能把任意 JSON 直接塞进运行态
+- `__runtime_overrides__` 配置错误必须在注册期直接失败，不能静默忽略
+
+不允许：
+
+- 由 settings runtime owner 直接反射任意 `AppSettings` 字段并默认全部开放热更新
+- 继续在业务代码里长期维护一份脱离 `AppSettings` 的手写热更新白名单
+- 在 `AppSettings` 上同时长期保留 tuple/list 简写、字段级元信息标记等多套并行声明方式
+- 继续暴露手工 `register_runtime_override_schema(...)` 之类的旁路 API 让业务绕过 `AppSettings.__runtime_overrides__`
+
+## 5. 环境变量命名
+
+项目环境选择：
+- `PZ_ENV`
+
+约束：
+- `PZ_ENV` 是唯一正式环境选择变量
+- 未显式指定时默认 `develop`
+- `product` 必须在启动命令或进程环境中显式指定
+- `.env.{PZ_ENV}` 只在 `PZ_ENV` 已确定后参与加载
+- 不允许继续引入 `ENVIRONMENT`、`project.environment`、`project.env` 等第二套环境选择入口
+
+全局字段：
+- 顶层字段继续使用字段名
+- 项目与路由字段必须使用 section path
+
+例如：
+- `CACHE_DIR`
+- `RUNTIME_DIR`
+- `PROJECT__NAME`
+- `PROJECT__DEFAULT_MODULE`
+- `PROJECT__BASE_URL`
+- `ROUTING__DEFAULT_LANGUAGE`
+- `ROUTING__SUPPORTED_LANGUAGES`
+- `DATABASE__HOST`
+- `DATABASE__PORT`
+- `REDIS__HOST`
+- `REDIS__PORT`
+
+app 字段：
+- 使用 `<APPID>__KEY`
+
+例如：
+- `EXAMPLE_APP__FEATURE_ENABLED=false`
+- `EXAMPLE_APP__SITE_IMAGE=https://example.com/cover.png`
+
+规则：
+- `__` 是唯一嵌套分隔符
+- app 代码不得直接自己解析环境变量
+
+补充约束：
+
+- 环境变量只应作为覆盖层，不应成为唯一正式配置源
+- 同一逻辑字段不得同时支持多套长期前缀体系
+- 大小写、分隔符、布尔/列表/对象解析规则必须形成稳定契约
+- `BASE_URL`、`APP_PORT` 这类大写变量属于宿主 `main.py` / host settings override 的启动特例，不属于通用 settings 命名规则
+- 对 `project.base_url` 的正式 settings 覆盖写法仍然是 `project__base_url` 或 `PROJECT__BASE_URL`，不要把 `BASE_URL` 扩散成项目级通用配置键
+
+## 6. `pz.jsonc` / `pz.{PZ_ENV}.jsonc` 正式结构
+
+项目级 JSONC 顶层结构推荐固定为：
+
+```jsonc
+{
+  // @pz:managed:start installed_apps
+  "installed_apps": [],
+  // @pz:managed:end installed_apps
+
+  "project": {},
+  "apps": {}
+}
+```
+
+结构约束：
+- `installed_apps`
+  - 项目装配真相源
+- `project`
+  - 项目级手写配置
+- `apps`
+  - 各 app 的项目级手写 override
+
+正式要求：
+- runtime 编译时只消费 `installed_apps`、`project`、`apps`、环境层与运行时覆盖
+- runtime 编译时不允许业务层直接扫描 `@pz` 注释
+- `project_jsonc` 必须在写回时尽量保留普通 `// ...` 注释，但这些普通注释不参与配置语义，也不承诺字节级原样保留
+
+示例：
+
+```jsonc
+{
+  // @pz:managed:start installed_apps
+  "installed_apps": [
+    "control_panel_app",
+    "identity_app",
+    "content_app",
+    "catalog_app"
+  ],
+  // @pz:managed:end installed_apps
+
+  "project": {
+    "name": "example-project",
+    "default_module": "example_app",
+    "base_url": "https://example.com",
+    "cache_dir": ".runtime/cache",
+    "runtime_dir": ".runtime/run",
+    "asset_dir": ".assets"
+  },
+
+  "app_replacements": {
+    "catalog_app": "custom_catalog_app"
+  },
+
+  "apps": {
+    "content_app": {
+      "route_policy": {
+        "default": "protected"
+      }
+    },
+    "catalog_app": {
+      "default_locale": "zh-CN"
+    },
+    "<infra_owner>": {
+      "database": {
+        "enabled": true,
+        "driver": "postgresql",
+        "host": "127.0.0.1",
+        "port": 5432,
+        "database": "app",
+        "user": "app"
+      },
+      "cache": {
+        "enabled": false
+      },
+      "observability": {
+        "metrics": {
+          "enabled": true,
+          "path": "/metrics",
+          "namespace": "demo_app"
+        }
+      }
+    }
+  }
+}
+```
+
+补充约束：
+
+- `apps.<infra_owner>.database.enabled` / `apps.<infra_owner>.cache.enabled` 是正式稳定字段
+- `apps.<infra_owner>.observability.metrics.enabled` / `path` / `namespace` 是正式稳定字段
+- `[app_replacements]` 是唯一正式 app 替换声明入口
+- 历史 `db_*`、`DB_*`、`redis_*`、`REDIS_*` 必须在单一归一化阶段折叠
+- 像 `db_generate_schemas_on_startup` 这类高影响启动行为，不应继续默认开启而不经过显式能力建模
+- `redis_host = 127.0.0.1`、`redis_port = 6379` 这类“未配置即本机 Redis”默认值不应继续作为正式语义
+- `/metrics` 是否公开、是否鉴权、是否内网暴露，不应继续依赖代码硬编码或反向代理偶然约束
+
+## 6.1 app 配置入口
+
+正式 app 配置入口固定为：
+
+- `pz.jsonc` / `pz.{PZ_ENV}.jsonc` 中的 `apps.<app_id>`
+- 项目 `.env` / `.env.{PZ_ENV}` / 显式环境变量中的 `<APPID>__*`
+
+统一由框架聚合后挂载到：
+
+- `settings_center.settings.<app_id>`
+
+包内 `configs/default.jsonc` 是 `pz settings init/update` 的作者面输入，不是启动期 app 配置入口。
+
+## 6.2 路径字段约束
+
+凡涉及文件系统路径的配置，必须明确声明其锚点：
+
+- 相对 `project_dir`
+- 或显式绝对路径
+
+不再允许隐式相对：
+
+- `ROOT_DIR`
+- 框架源码目录
+- 当前导入文件所在目录
+
+约束：
+- 配置加载器不应因为当前 shell 的 `cwd` 恰好位于某个仓库内，就把该仓库根自动视为当前项目
+
+补充要求：
+
+- 路径归一化只允许发生在 settings compiler 中
+- 一旦进入 `SettingsSnapshot`，所有路径字段都必须已经是确定语义：
+  - 显式绝对路径
+  - 或带明确锚点的 project-relative 结果
+- 后续 registry/facade/adapter 不得再重新解释路径锚点
+
+## 6.3 保留字段与命名空间约束
+
+为了避免 app 生态扩张后互相踩配置命名空间，正式约束如下：
+
+- 顶层字段保留给 core/runtime 边界
+- app 私有配置只进入 `[apps.<app_id>]`
+- 不允许 app 在顶层平铺自己的私有字段
+- 不允许 app 额外声明独立于 `app.id` 的 settings namespace
+- 不允许实现子目录通过目录名、模块路径或历史 alias 占用新的 app 配置空间
+
+以下命名空间是正式保留命名空间：
+
+- `database`
+- `redis`
+- `metrics`
+- `logging`
+- `runtime`
+- `storage`
+- `app_replacements`
+- `apps`
+
+## 7. 默认清单策略
+
+正式规则：
+- `installed_apps` 默认值为空列表
+- 框架自身不再默认硬编码任何业务 `app`
+
+官方样板清单只通过以下渠道提供：
+- 样板项目
+- `pz dev init` / 项目脚手架
+- 文档示例
+
+而不是写死进框架默认 settings。
+
+约束：
+- 当前 `CoreSettings` 中那类“超长默认 installed_apps + installed_apps_extension + 默认 app=app”模型必须退出正式主链
+- 标准 pip 包目标下，默认清单应收缩到真正最小集合，业务 app 不应再由框架默认注入
+- 默认 middleware 清单也应同步瘦身，不应把身份、页面元信息、analytics、db_connection 等平台能力作为基础包硬编码默认值
+- `INSTALLED_APPS` 的环境覆盖语义也不应再把带顺序的声明抹平成纯名字列表
+- `ROUTE_CONFLICT_POLICY` 的正式默认值应收口到显式失败，而不是继续保留 `warn`
+- `analytics_enabled` 这类环境态衍生开关，应进入单一“配置派生阶段”统一计算，而不是散落在 `CoreSettings` validator 中强制改写
+- `db_min_size` / `db_max_size` 这类连接池默认值，若需按环境派生，也应在统一派生阶段完成，而不是由 `DBMixin` 在 validator 中隐式改写
+
+默认 app 清单、env 覆盖后的顺序语义以及运行边界开关，都必须收口到“最小默认值 + 单一配置派生阶段”模型。
+
+## 8. 运行时覆盖
+
+运行时覆盖只应用于显式白名单字段。
+
+要求：
+- 覆盖能力必须可审计
+- 默认只允许非高危配置项动态刷新
+- app 级覆盖仍写入 `settings_center.settings.<app_id>` 命名空间
+
+补充要求：
+- 运行时覆盖不应改写“项目目录边界”字段
+- `project_dir`、`cache_dir`、`runtime_dir`、`asset_dir` 不应在进程运行中被动态切换
+- 运行时覆盖若支持嵌套键，必须正式规定路径语义
+- 运行时覆盖不得依赖“先调用 `ensure_full_settings()` 再原地补挂 namespace”这一类进程级补丁式流程
+- CLI、HTTP、worker 应基于同一份完成聚合后的 settings 快照启动
+- 历史 helper `ensure_full_settings()` 不得继续吞掉装配异常后静默返回残缺 settings
+
+补充约束：
+
+- 运行时覆盖默认不应用于：
+  - app 装载清单
+  - 路由边界
+  - `project_dir/cache_dir/runtime_dir/asset_dir`
+  - DB/Redis driver 这类基础能力类型切换
+- 运行时覆盖更适合：
+  - feature flags
+  - 限流/缓存/展示类参数
+  - 已明确白名单的 app 私有行为配置
+
+补充约束：
+- `ensure_full_settings()` 这类 helper 不得继续承担正式配置装配主路径
+
+### 8.0 settings helper 禁止表
+
+以下行为不得进入正式配置装配主链：
+
+- 通过“先收集 env、再回写 `os.environ`、再让 `BaseSettings` 回读”完成装配。
+- 在模块导入时立即创建全局 `settings` 单例。
+- 在运行期补挂 app namespace，并吞掉装配异常后继续返回对象。
+- app settings 聚合器把空 `installed_apps` 自动回退到类默认清单。
+- app settings 模块保留 `get_settings()` 作为默认值主链。
+- app settings 聚合器反向依赖基础包全局 settings 实例或私有 env helper。
+
+正式要求：
+
+- 任何 helper 不得承担正式配置装配主链。
+- 正式主链必须能独立产出完整 `SettingsSnapshot`。
+- 非正式 helper 一旦被调用，必须输出清晰诊断，而不是静默维持并行语义。
+- 历史 helper 不得吞掉结构性配置错误并返回半初始化结果
+
+迁移落点：
+
+- env 收集、别名折叠、派生字段生成进入单一 settings compiler
+- app namespace 组装进入 compiler/assembly 阶段，而不是运行期 patch helper
+- runtime overrides loader、L2 client、cursor/check interval 进入 context-bound 对象，不再挂在模块级 facade
+
+## 8.1 嵌套覆盖语义
+
+运行时覆盖采用如下唯一语义：
+
+```toml
+[apps.<app_id>]
+images.enabled = true
+```
+
+或运行时注册：
+
+- `images.enabled`
+- `checks.currency.enabled`
+
+则框架必须真正支持对嵌套对象做路径赋值，而不是仅支持顶层 `setattr()`。
+
+正式规则：
+
+- 配置文件里使用结构化 TOML
+- 环境变量用 `APPID__IMAGES__ENABLED`
+- 运行时覆盖使用统一路径语义，例如 `images.enabled`
+
+三者应指向同一命名空间对象结构。
+
+运行时覆盖对 dotted path 的声明能力与实际赋值能力必须一致，overrides/L2 也必须收口到 context-bound 隔离模型。
+
+补充要求：
+
+- 只有在正式实现嵌套路径赋值语义后，才允许注册 dotted key
+- overrides loader、L2 client、version cursor、check interval 都应进入 context-bound facade，而不是继续挂在模块级全局变量上
+
+## 8.2 middleware 相关 settings 收口边界
+
+middleware 相关 settings 仍带有一批历史字段折叠与派生逻辑，重构时需要显式收口，而不是让它们继续散落在 mixin/validator 中。
+
+收口范围：
+
+- `CorsMixin` 仍支持从历史环境变量 `ALLOWED_ORIGINS` 注入 `allow_origins`
+- `I18nMixin` 仍默认：
+  - `i18n_enabled = true`
+  - `i18n_url_prefix = true`
+  - 自动做语言代码规范化与别名折叠
+  - 自动从 `currency_default_languages` 倒排生成 `language_default_currency`
+- `SettingsL2RefreshMixin` 仍默认：
+  - `settings_l2_check_interval = 10.0`
+  - 且强制最小值为 `1.0`
+- 多个 middleware mixin 仍默认启用，或内置默认规则/默认清单，例如：
+  - `TrailingSlashMixin`
+  - `DatabaseRedirectMixin`
+  - `SecurityCSRFMixin`
+  - `DenyAPIMixin`
+  - `CmsAuthGuardMixin`
+  - `RedirectMiddlewareMixin` 不再注入默认语言别名规则，需显式配置 `redirect_rules_raw`
+- HTML 缓存策略也属于 middleware settings 合同的一部分，不能继续留在“源站随手写 header”或“CDN 面板临时补规则”的灰区：
+  - 用户态 HTML 必须显式进入私有缓存路径
+  - 匿名 HTML 必须显式区分浏览器缓存与 CDN 边缘缓存
+  - 用户态识别面若依赖 cookie / `Authorization` / 已编译 settings，可被直接建模为正式配置字段或 normalize 规则，不得继续依赖前端首帧纠偏
+- `BASE_URL` / `API_BASE_URL` / `IMAGE_BASE_URL` / `worker_storage_path` 的历史字段回填，不应继续分散在：
+  - settings validator
+  - app settings bootstrap helper
+
+最小默认基线：
+
+- base install 默认不注入业务 app
+- base install 默认不注入依赖 DB、页面元信息、身份、analytics、内容 guard 的 middleware
+- 若需要提供官方默认链，只能以显式 preset / sample project / init-project 模板提供
+- 任何“默认启用”的 middleware 都必须属于真正最小框架边界，并能在 disabled 场景下显式表达状态
+
+结论：
+
+- middleware 配置当前不只是“字段定义”，还混入了历史别名桥接、运行期派生值和强默认值
+- 某些“便利字段”甚至不是在 settings 聚合阶段确定，而是在 bootstrap 时继续补写
+- 这些历史字段折叠逻辑必须进入单一配置聚合器，而不是继续分散在 middleware mixin 内部
+
+要求：
+
+- 新文档明确区分：
+  - 正式稳定字段
+  - 历史别名
+  - 运行时派生字段
+- 默认启用的 middleware、默认 redirect 规则、默认保护/豁免清单，也要单独归类为显式 preset，而不是隐式散落在各 mixin 默认值里
+- 历史别名若需要被识别，也只能在单一归一化阶段被一次性折叠，不得进入新正式字段模型
+- 运行时派生字段应由统一 settings 聚合层生成，而不是在 middleware 自己的配置类里各自派生
+- `BASE_URL -> API_BASE_URL -> IMAGE_BASE_URL`、`UPLOAD_DIR -> worker_storage_path` 这类历史字段回填，也应只在单一 normalization 阶段完成
+- 对 HTML 缓存控制，正式稳定口径固定为：
+  - 用户态 HTML：`Cache-Control: private, no-store, no-cache, must-revalidate, max-age=0, s-maxage=0`
+  - 用户态 HTML：显式发送 `Cloudflare-CDN-Cache-Control: no-store`
+  - 用户态 HTML：显式发送 `Vary: Cookie, Authorization`
+  - 匿名 HTML：浏览器侧使用 `Cache-Control: public, max-age=0, must-revalidate`
+  - 匿名 HTML：CDN 侧使用 `Cloudflare-CDN-Cache-Control: public, max-age=<ttl_seconds>`，TTL 唯一来自 `apps.pz_foundation.cache_control.policies["http.public_html_cdn"].ttl_seconds`
+  - 健康检查与 no-store 路径：统一 `no-store`
+
+特别约束：
+
+- `ROUTE_CONFLICT_POLICY`、middleware 装配开关、i18n 前缀策略这类运行边界字段，应被视为核心配置契约的一部分
+- 不能继续依赖“middleware 初始化时自动猜 settings 字段名”来弥补配置模型不完整
+- middleware 参数映射若要进入稳定契约，必须来自：
+  - 显式 `ParamsModel`
+  - 或显式字段映射表
+  不能继续依赖：
+  - `__init__` 反射
+  - suffix / normalized match
+  - alias map
+  - manager 内部硬编码修正
+
+## 8.3 配置派生字段的唯一生成点
+
+为了避免 bootstrap、middleware、CLI helper 再次派生配置，所有派生字段必须只有一个生成点。
+
+正式要求：
+
+- 派生字段统一由 settings compiler 生成
+- 派生结果必须直接进入 `SettingsSnapshot`
+- 后续阶段只允许消费派生结果，不允许再次重算
+
+适用范围包括：
+
+- `API_BASE_URL`
+- `IMAGE_BASE_URL`
+- `worker_storage_path`
+- middleware preset 派生值
+- i18n 默认语言/货币映射派生值
+- analytics/feature preset 派生值
+
+禁止：
+
+- bootstrap 再补派生字段
+- middleware 初始化时临时重算派生字段
+- worker/client SDK 按请求临时回退根级历史字段重算派生值
+
+## 9. 禁止事项
+
+不允许：
+- app 自己直接 `os.environ.get(...)`
+- 根 `.env` 承载整个系统的全部默认配置
+- 业务 app 依赖根 settings 中某个历史扁平字段是否存在
+- app 通过 import-time `BaseSettings()` 抢先读取环境并固化为全局单例
+- 用“从对象自动推断哪些字段可 runtime override”替代显式稳定白名单
+- settings loader 默认把 `ROOT_DIR/.env` 注入到所有运行模式
+- app 配置目录发现同时混用 `PZ_PROJECT_DIR`、`cwd`、`ROOT_DIR` 而没有明确单一 project_dir
+- settings 构建先把合并后的 env snapshot 回写 `os.environ`，再让 `BaseSettings` 回读
+- middleware 在构造时再回退读取全局 settings 单例作为正式配置来源
+- environment/profile 候选名由 loader 内部隐式展开，而不是由正式配置契约定义
+- bootstrap helper 在 settings namespace attach 之后继续补写 `API_BASE_URL`、`IMAGE_BASE_URL`、`worker_storage_path`
+- 运行时覆盖注册表声称支持 `images.enabled` 这类 dotted key，但实际仍只做顶层 `setattr()`
+- 通过模块级 `_overrides_loader`、`_l2_client`、`_last_version`、`_last_check_at` 维护跨项目共享的 overrides/L2 状态
+- 在 settings 装配完成后，再由 bootstrap/lifespan 隐式补写正式稳定字段