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/10-/346/265/213/350/257/225/344/270/216/345/245/221/347/272/246/350/247/204/350/214/203.md

@@ -0,0 +1,1001 @@
+# 测试与契约规范
+
+> settings 契约统一口径：运行时代码只读 `settings_center.settings`；app 配置只读 `settings_center.settings.<app_id>`；项目级读取只允许 `settings_center.settings.project.<field>`；`load_app_settings()`、`load_typed_app_settings()`、`load_<app>_settings()` 和任何绕开 `settings_center` 的重复 helper 都不再是正式读取链。
+> namespace 契约统一口径：叶子 app 的 namespace 固定为其最终生效的 `app.id`；标准 `apps.py` 必须通过模块级 `app` 对象显式声明 `app.id`，目录名/import 包名默认应与 `app.id` 收敛一致；非叶子内部模块不得自定义 namespace，只能读取父 app 的 settings namespace，或读取 `settings_center.settings.project.<field>`。
+> 基础层契约统一口径：`pz` 是唯一正式基础包与唯一可独立启动的包。
+
+## 1. 目标
+
+新设计不能只停留在文档层，必须通过契约测试证明：
+
+- 安装包模式成立
+- 项目目录边界成立
+- 可选基础设施成立
+- app 替换与平台 app 边界成立
+
+## 2. 测试分层
+
+测试固定分为四层：
+
+### 2.1 单元测试
+
+覆盖：
+
+- 路径解析
+- 配置优先级
+- app settings 聚合
+- 资源发现顺序
+- 单例 reset / lazy factory 行为
+
+### 2.2 契约测试
+
+覆盖：
+
+- 标准入口
+- 安装包运行方式
+- app 替换
+- 平台 app 公共门面
+- 扩展点冲突策略
+- system checks / `pz check`
+
+### 2.3 集成测试
+
+覆盖：
+
+- SQLite
+- MySQL
+- PostgreSQL
+- Redis 可选启用
+- 资源合并
+- 迁移聚合
+- 发布升级与回滚验证
+
+### 2.4 烟雾测试
+
+覆盖：
+
+- `pz --help`
+- 最小 app 启动
+- 最小 worker 启动
+
+### 2.5 架构契约测试
+
+覆盖：
+
+- 分层依赖方向
+- 唯一真相源不被重复实现
+- facade/capability 边界
+- 编译阶段与执行阶段分离
+- 核心构件命名与职责唯一化
+- `pz.runtime` 与 workspace `devtools/*` 的边界
+- owner-specific host/runtime 的归属边界
+
+验证点：
+
+- 上层模块不会直接 import 下层具体实现细节
+- 子包不会自行重写 settings/app/resource/infra 聚合逻辑
+- route/middleware/resource/infra 只存在一套正式 manifest/snapshot 编译链
+- Web / CLI / worker 共用同一条 `RuntimePlan` 编译链
+- 编译阶段不会偷偷触发运行时副作用
+- `Compiler` / `Registry` / `Facade` / `Provider` / `Adapter` 的职责边界可被静态检查或契约测试证明
+- `manager` / `service` / `helper` 不会被实现成稳定公共契约入口
+- 最小子包源码树 / 外部 app / scripts 不会直接 import `pz.infra.*` 具体实现
+- `pz.runtime/*` 与 workspace `devtools/*` 不会点名任何 `apps.<owner>` 包路径
+- owner-specific host/runtime 入口不会留在 `pz`
+
+## 3. 必测场景矩阵
+
+### 3.1 安装包模式
+
+必须测试：
+
+- 构建 wheel
+- 安装到全新虚拟环境
+- 从非源码目录执行 `pz`
+
+验证点：
+
+- 不依赖仓库根路径
+- 不依赖 vendored 子目录
+- 不向 `site-packages` 写入任何运行态文件
+- 官方最小子包装态安装后可稳定 import 自己声明的正式 Python 包
+- 正式 Python 包的 import 成立不依赖源码 checkout、editable 特例或 `PYTHONPATH` 注入
+- `BASE_URL` / `API_BASE_URL` / `IMAGE_BASE_URL` / `worker_storage_path` 的最终值来自单一归一化阶段，而不是 bootstrap 二次补写
+- 外部项目依赖面只来自 `pz`、`pz.app`、`<app>.public`
+- base 安装下执行 `pz --help`、`pz list`、`pz check` 不会拉起重依赖初始化
+
+补充边界：
+
+- 官方最小子包的 import contract 属于对应最小子包装态验证，不等于要求 `pz` base wheel 自带这些模块
+- 若采用分仓布局，官方 app 真相源位于独立 `apps` 工作区根下的 `apps/`
+- 因此 `pz` 基础包只负责 base wheel/base-only 验证；官方维护最小子包 import smoke 应在对应 app 组合包安装后单独验证
+
+### 3.1.1 system checks 契约
+
+必须测试：
+
+- `pz check` 可在 wheel 安装模式下运行
+- `pz check --json` 输出稳定结构
+- Web/debug/preflight 若展示检查结果，内容与 `pz check` 同源
+
+验证点：
+
+- system checks 只有一条正式入口链
+- `CheckReport` 结构稳定且可审计
+- 不存在第二套 best-effort 检查主链
+- 新增检查必须先覆盖所属领域的无副作用原子诊断能力，再覆盖 `pz check` 的编排接入；不得只测试 CLI 输出而跳过领域原子能力
+- `CheckReport` 中的 `severity`、`code`、`owner`、`scope` 语义稳定
+
+### 3.2 项目目录与配置
+
+必须测试：
+
+- `pz.jsonc`
+- `PZ_PROJECT_DIR`
+- `--project-dir`
+
+验证点：
+
+- 配置优先级一致
+- worker 与 web 解析结果一致
+- 相对路径统一相对 `project_dir`
+- `.env` 只在 `project_dir` 作用域内生效，不再混入框架仓库 `ROOT_DIR/.env`
+- 配置加载不会把合并后的结果写回 `os.environ`
+- environment/profile 候选名解析规则稳定且可预测，不依赖 loader 内部隐式扩展
+- 导入 `pz.settings` 本身不会提前锁定某个 `project_dir` / env snapshot 并污染后续入口
+- 导入 `pz_settings_center.public` 本身不会提前编译或绑定 `SettingsSnapshot`
+- `settings_center.settings` 首次访问会按 settings lazy autoload 规则解析当前项目并读取最终 settings
+- 直接脚本场景可通过 `PZ_PROJECT_DIR` 在非项目 cwd 下读取 `settings_center.settings.<app_id>`
+- settings lazy autoload 不会编译完整 `RuntimePlan`，也不会触发 route / middleware / resource / infra / worker lifecycle 装配
+- settings provider 在 lazy autoload 下保持轻量、确定、无网络/DB/Redis/资源 build 副作用
+- app settings 聚合结果同时反映：
+  - 包内默认值
+  - `[apps.<app_id>]`
+  - 环境变量
+  - app settings provider
+  - runtime override
+- 空 `installed_apps` 不会再被 helper 自动回退到一长串类默认清单
+- app settings 的 `get_settings()` 等历史读取入口不再允许作为默认值主链；遗留入口必须直接报错，运行时代码统一只读 `settings_center.settings`
+- settings runtime owner 读取“文件默认值”时不会重新跑一遍全量 app 装配主链
+- 配置装配阶段不会触发网络 I/O、DB/Redis 初始化或资源 build
+- settings snapshot 在编译完成后保持只读，不会在 bootstrap/lifespan/startup 中被原地改写
+- `AppSettings` / `CoreSettings` validator 不承担跨 app 裁决、provider 注册或运行时副作用
+- 已删除的历史环境选择字段与旧键写法会稳定报错，不再静默忽略或自动迁移
+- 运行时代码不会再通过 `pz.settings`、`os.environ`、重读 `pz.jsonc` 形成第二套配置读取路径
+- 所有派生字段都只来自单一 settings compiler，而不会在 bootstrap/middleware/worker 中再次重算
+- `settings_center.settings.<app_id>` 与 runtime settings proxy 的 app 读取顺序一致，都是：
+  - snapshot
+  - provider
+  - runtime override
+- provider 补值不会反向改写 `SettingsSnapshot`
+- 启动前必须可直接从 snapshot 读到 DB/Redis 等基础连接配置，不依赖 provider 兜底
+- 如果声明了 settings provider，其 patch 必须在 `RuntimePlan.settings` 编译阶段生效；app lifecycle startup 不得靠具体 owner 插队来完成 settings 裁决
+- runtime override schema 只从 `AppSettings.__runtime_overrides__` 稳定提取
+- `__runtime_overrides__` 配置错误时，注册期必须直接失败，不能静默跳过
+- 未注册 namespace / 未声明 key / 类型不匹配的 runtime override 写入必须被拒绝
+- 自定义 `app.id` 不会破坏 settings namespace 绑定；目录名与 `app.id` 不一致时，运行时仍只认显式 `app.id`
+- 非叶子内部模块不会因目录名或模块路径自动获得新的 settings namespace
+- `live / refresh / restart_required` 必须在运行时写入行为上可观测地区分
+
+### 3.3 运行目录
+
+必须测试：
+
+- `cache_dir`
+- `runtime_dir`
+- `asset_dir`
+
+验证点：
+
+- 资源合并输出进入 `cache_dir`
+- 锁与 pid 进入 `runtime_dir`
+- 上传、本地存储、长期身份、账号、记忆、浏览器环境 inventory 等不可删除文件进入 `asset_dir`
+- 本地 storage 默认值不再回落到相对 `"uploads"` / `"var/media"`
+- 相对资源目录 helper 不再回落到 `Path.cwd()`
+- 资源 merge 失败时不会污染当前已激活产物目录
+- 公开挂载不会把整个 `runtime_dir` / `asset_dir` 暴露出去
+- 资源诊断页、CLI 诊断、debug surface 都读取同一份资源 manifest，而不是各自重扫目录
+- 资源服务不会在 import `core/resources/*` 时基于全局 settings/path 快照提前实例化
+- Web `startup()` / `create_app()` / `create_host_app()` 不会默认触发 asset build、图片生成、bundle/minify
+- `file_service` / `StorageFacade.url()` 在无公共访问语义时稳定返回 `None` 或显式能力错误，而不是回退为宿主机绝对路径、相对路径或 `file://`
+- `file_service presign` / `resolve_url` 不会把“缺失 public base_url / backend 未声明”伪装成可公开访问的 URL 成功
+
+### 3.3.1 路由增强与冲突检测
+
+必须测试：
+
+- `base_prefix` 展开正确
+- `api_version=true` 时路径前缀展开正确
+- `i18n_aware=true` 时按正式语言列表显式展开默认语言路径与 `/{lang}` 路径
+- 路由冲突在真实注册前即可被检测
+- core health/metrics/debug routes 与 app routes 的注册顺序可预测，且不靠后续重排兜底
+
+验证点：
+
+- route enhancer 的展开规则是稳定契约
+- 不再依赖“先挂载、再清理重排、最后报错”的流程
+- `"/"` / `"/{path:path}"` / `"/{lang}/{module}"` 这类 generic route 的分类与排序规则形成稳定契约，或被显式替代
+- `i18n_aware` 统一按配置语言列表显式展开，不再保留“只生成通用 `/{lang}` 参数路由”的两套展开语义
+
+### 3.4 可选基础设施
+
+必须测试：
+
+- 无 DB 启动
+- 无 Redis 启动
+- SQLite 启动与迁移
+- MySQL 启动与迁移
+- PostgreSQL 启动与迁移
+
+验证点：
+
+- 未启用组件不参与 readiness
+- 未启用组件不在 startup 阶段初始化
+- 缺失驱动时错误信息明确
+- `InfraSettings` / `InfraContext` 在 disabled 场景下能正确表达 `disabled` 而不是伪造默认 host/port
+- `/ready` 不再无条件初始化 DB/Redis
+- Redis 未启用时不会回退到 `127.0.0.1:6379`
+- disabled 组件不会把整体 readiness 错误降级为 `degraded`
+- metrics/tracing 关闭时不会影响主业务启动链
+- metrics 默认标签不会引入高基数敏感值
+- base 安装命令路径不会因缺失可选驱动而在无关命令上失败
+- `create_app()`、Web `startup()`、`setup_infra()`、`/ready` 都不会触发 `generate_schemas`、自动建表、迁移修补或 schema auto-heal
+- DB 初始化、连通性校验、schema/migration 执行是三段可区分行为；启动失败诊断不会把 DDL 副作用混进 readiness / bootstrap
+- `.sources` 官方/共享包只走数据库 init，不走 Aerich 历史迁移链；契约测试必须证明共享包不会出现在 migration executor 的 runnable owners 中
+- 业务宿主包仍可作为 migration executor owner 执行自己的迁移链
+
+### 3.5 app 替换与平台 app
+
+必须测试：
+
+- 外部 app 显式替换官方维护最小子包
+- `[app_replacements]` 是唯一正式替换声明入口
+- 重复 `app_id` 默认失败
+- `requires_apps` 缺失依赖时报错
+- app dependency cycle 报错
+- app import path 解析不会依赖 `pz.<name>` 自动补前缀或 package-level `app` 猜测才成立
+- 最小安装场景不会自动装载整套默认官方 app / 独立子包清单
+- shared site UI owner 被替换后的模板公共门面保持同一公开契约
+- settings runtime owner 缺失时错误明确
+- task dispatch / worker owner 未启用 Redis 时行为明确
+- provider registry 在平台 app 替换后不会残留旧 provider
+- shared site UI owner 模板环境在替换后不会复用旧的 globals/merged 目录绑定
+- account / profile owner 这类扩展消费侧在替换后不会同时残留 legacy provider 与 unified registry 两份状态
+- auth owner / task dispatch owner 替换后不会残留旧 provider binding、旧事件订阅或旧后台任务
+- 涉及 DB/存储的 app 替换，不会出现 migration owner / storage owner 双写
+- settings runtime owner 在显式 `project_dir` 与默认项目目录两种场景下都继续委托 core runtime settings 主链
+- settings runtime owner 线上热更新只覆盖显式声明允许热更新的字段，不会把整个 `AppSettings` 默认暴露
+
+### 3.5.1 app registry 与依赖图契约
+
+必须测试：
+
+- `installed_apps` 顺序可稳定形成 app registry
+- `installed_apps` 条目语法固定为目录名，不接受文件系统路径、distribution 名或 `<pkg>.apps:app`
+- `installed_apps` 声明文件夹/容器目录时，会稳定展开到嵌套最小子包
+- 最小子包判定只认标准 `apps.py`：
+  - 候选目录或其 Python 包目录内存在 `apps.py`
+  - `apps.py` 内有 app class
+  - app class 内用静态字符串声明 `id`
+  - `apps.py` 内有模块级 `app = <AppClass>()`
+  - `app` 对象最终可解析出合法 `app.id`
+- 命中最小子包后会停止继续向下扫描其子目录
+- 非 app 模块不允许使用 `apps.py` 作为普通实现文件名，避免被发现链误识别
+- 容器目录内部展开顺序固定为目录名字典序深度优先
+- Web / CLI / worker / resources / settings 消费的是同一份最小子包展开结果，而不是各自再做第二套扫描
+- 依赖拓扑排序结果稳定
+- 官方维护最小子包 缺失 `required_pz` 时失败
+- `required_pz` 不满足时失败
+- 重复 `app_id`、错误 import path、suffix match 命中错误 app 时都有明确诊断
+- app `init()` 失败时不会被 warning 后静默带入后续装配链
+- `INSTALLED_APPS` 的顺序语义稳定，不会因 env 解析被抹平
+- 旧的短名自动补全、`pz.<name>` 自动补前缀、package-level `app` 猜测不再作为正式成功路径
+- 非源码目录如 `.git/`、`.venv/`、`__pycache__/`、`dist/`、`build/` 不会被发现算法误识别为 app 扫描目标
+- 重复 `app_id` 不再被 debug log 后静默跳过
+- app 元数据不会自触发替换关系，只有 `[app_replacements]` 生效
+- `[app_replacements]` 构成一对一、无环的替换图，不存在链式替换或一对多替换
+- app-level 替换后，被替换 app 不会再残留部分 provider/route/resource 声明进入正式主链
+- app 声明只来自标准 `apps.py` 元数据与正式声明方法，不存在第二套 decorator/registry 声明主链
+- `required_protocols` 只解析 capability contract 名称，不解析具体实现模块路径
+
+验证点：
+
+- 保留 Django 风格 app registry / dependency graph 的优点
+- 移除重复 `app_id` 静默跳过这类历史隐式行为
+
+### 3.6 host 边界契约
+
+必须测试：
+
+- `pz.runtime` 只暴露正式通用 runtime helper；开发态辅助脚本不进入 installable package，只允许位于仓根 `devtools/*`
+- `pz` 源码树不点名任何 `apps.<owner>` 路径
+- 官方 infra owner 的 DB / Redis / cache / lifespan host 入口位于该 owner 子包内部，不回写 `pz` core
+- task dispatch / worker owner 的 owner-specific host/runtime 入口位于该 owner 子包内部
+
+验证点：
+
+- core 不再通过硬编码 import path 支持某个特定 app
+- owner-specific host/runtime 逻辑回到 owner 自己的 app 包
+- 宿主项目不会重新引入 `project_runtime` 一类第二装配层
+- `pz.runtime` 与 workspace `devtools/*` 的存在不等于 `pz` 拥有外部 app 的运行时真相
+
+### 3.6.1 扩展点对象协议契约
+
+必须测试：
+
+- `extensions()` 返回值只包含结构化扩展对象
+- 每个扩展对象都带：
+  - `kind`
+  - `id`
+  - `owner_app`
+  - `api_version`
+  - `priority`
+- 不允许裸函数、字符串路径、import-time 隐式注册器进入正式扩展主链
+- `host.builder` 只能通过 `build(ctx) -> result` 产出 host
+- `settings.provider` 只能通过 `provide(ctx) -> tuple[SettingsPatch, ...]` 返回 patch
+- `cli.tool` 只能通过 `configure(parser)` 与 `run(ctx)` 暴露命令
+- `route.contribution` 只能声明正式 router 来源，不承担最终跨 app 排序裁决
+- `middleware.contribution` 只能声明 factory/replace，不接受历史类路径与隐式补参
+- `lifecycle.contribution` 只能声明 `init/startup/shutdown` 三类正式 phase
+- `resource.contribution` 只能声明标准资源目录来源
+- 同类扩展对象同 `id` 冲突时，按 `priority` 裁决；同优先级冲突直接报错
+
+验证点：
+
+- 扩展点声明与实现解耦
+- 冲突治理在编译期完成
+- 不存在第二套隐式扩展注册主链
+
+### 3.6.2 module config / settings / operator 协作链契约
+
+必须测试：
+
+- module config owner 只输出结构化 `ModuleConfigPatch`
+- settings surface owner 只消费 patch 并产出最终读取视图
+- settings runtime owner 只在正式声明允许的字段上做 runtime override
+- 运行时代码不会通过 `module_config` 或 settings runtime owner 直接读取业务配置值
+- `ModuleConfigField.type` 只允许正式封闭类型集合
+- `ModuleConfigBinding.target_path` 只允许声明式点路径
+- `transform` 只允许命名、纯函数、可审计的受控转换器
+
+验证点：
+
+- 配置声明层、编排层、写入层、读取层职责清晰
+- 不存在第二套运行时配置读取入口
+- module config 不会退化成可执行代码协议
+
+### 3.6.3 `RuntimePlan` 组合根契约
+
+必须测试：
+
+- `RuntimePlan` 至少包含：
+  - `project`
+  - `settings`
+  - `app_registry`
+  - `route_manifest`
+  - `middleware_manifest`
+  - `resource_manifest`
+  - `cli_manifest`
+  - `lifecycle_manifest`
+  - `capability_registry`
+  - `extension_conflicts`
+- 所有扩展点都先编译进入 `RuntimePlan`
+- app CLI 的 `<app>/cli/<tool>.py` 声明必须先编译进入 `RuntimePlan.cli_manifest`
+- Web / CLI / worker 执行阶段只消费 `RuntimePlan`
+- `RuntimePlan` 生成后保持不可变快照语义
+- `startup()` / `lifespan` / adapter 不会在 `RuntimePlan` 外重新拼装第二份运行图
+
+验证点：
+
+- `RuntimePlan` 是唯一运行图组合根
+- 不存在与 `RuntimePlan` 等价的第二套稳定核心名词并行存在
+- 执行阶段不反向修改 manifest、snapshot、registry 或运行图本身
+
+### 3.5.2 架构分层与依赖倒置契约
+
+必须测试：
+
+- app 只依赖 public facade / capability contract
+- `pz.settings` 不再作为稳定公共入口被正式主链依赖
+- entrypoint 不直接 import 底层具体 adapter 去拼规则
+- facade 不反向依赖 CLI/Web/worker 入口
+
+验证点：
+
+- 依赖方向固定为“入口 -> facade/capability -> compiler/registry -> contract”
+- 不存在反向跨层 import 把内部实现抬成事实公共 API
+- 平台 app 替换后，上层依赖仍通过同一 facade/capability 工作
+- adapter 不会重新读取 settings、重做 app/resource/infra 裁决或维护第二套真相源
+- provider 不会绕过 `RuntimePlan` 直接把默认 client/registry 写进进程级全局状态
+- app 不会把 `CapabilityRegistry` 本身当作稳定公共依赖面
+- `ProjectContext` 是目录边界唯一真相源，不存在第二套 path helper 主链
+- app CLI 命令发现只来自标准 `cli/` 目录，不存在第二套动态注册主链
+- runtime Python 模块不会再从扁平 host proxy 读取 `settings.APP_NAME`、`settings.BASE_URL`、`settings.SITE_URL`、`settings.default_language`、`settings.supported_languages`、`settings.project_dir`
+- 如需读取项目级信息，只允许：
+  - `RuntimePlan.settings` 的正式 section
+  - `settings_center.public` 的显式 `get_project_*` helper
+  - app 自己 namespaced settings facade
+- 非容器级跨子仓 runtime import 默认只允许：
+  - 对方 `public.py`
+  - 对方 `api/*`
+  - 文档与契约测试里冻结的极少量 allowlist 例外
+- allowlist 的治理方向必须是收缩，不允许把旧模块路径长期保留成历史白名单
+
+### 3.5.3 核心构件唯一命名契约
+
+必须测试：
+
+- 编译阶段正式对象统一使用 `Compiler` 语义
+- context-bound 索引统一使用 `Registry` 语义
+- app 对外公共入口统一使用 `Facade` 语义
+- 外部系统绑定统一使用 `Provider` / `Adapter` 语义
+
+验证点：
+
+- 同一能力不会同时并存 `service`、`manager`、`helper` 三套等价公共入口
+- 文档中的核心对象名称与代码实现名称对齐
+- 不存在与 `RuntimePlan` 等价的第二套稳定核心名词并行存在
+
+### 3.5.4 启动失败与降级语义契约
+
+必须测试：
+
+- 必需配置缺失时 fail-fast
+- app `init()` / `startup()` 中的必需依赖错误不会被 warning 后吞掉
+- optional capability 在 disabled / unavailable 时有稳定降级语义
+- 不同装配阶段的失败信息能明确区分：
+  - 配置错误
+  - app registry 错误
+  - route/extension/middleware 冲突
+  - provider 缺失
+
+验证点：
+
+- 框架默认语义是“显式失败或显式降级”
+- 不再输出 warning 后继续携带半初始化状态运行
+- 不存在 process-wide 默认事件总线、默认 registry、默认 facade 这类正式运行态单例
+- app `init()` 失败不会再被 warning 后继续
+- `startup()` 失败不会再默认带着半初始化 app 进入后续主链
+
+### 3.5.5 生命周期状态机契约
+
+必须测试：
+
+- app 生命周期统一遵循 declared -> compiled -> bound -> started -> stopped
+- `init()` 不会启动运行期副作用
+- `startup()` 不会补声明或重编译
+- `shutdown()` 会对称清理 startup 期激活的资源
+
+验证点：
+
+- Web / CLI / worker / tests 共享同一套生命周期语义
+- 重复调用 `startup()` / `shutdown()` 不会制造第二套隐式状态迁移
+
+### 3.5.6 错误编码契约
+
+必须测试：
+
+- CLI `--json` 失败输出带稳定 `code`
+- `CheckReport` 中的检查项带稳定 `code`
+- 配置错误、装配错误、能力错误、运行错误分别落入正式编码前缀
+- HTTP error envelope 带稳定 `code` 与 `request_id`
+- validation / HTTPException / 500 error 的公共 message 与内部 detail 分层明确
+
+验证点：
+
+- 不依赖自由文本断言核心失败语义
+- 不同入口不会为同一类错误发明不同 code
+- 启动失败输出稳定 `stage` / `owner` / `action`
+- 不依赖 `print()`、warning 文本、traceback 偶然内容作为正式故障协议
+- API 错误响应不会直接回显底层异常字符串、密码、token、DSN、宿主机绝对路径等敏感信息
+- request 级错误日志可用 `request_id` 或等价 correlation id 与客户端错误响应稳定关联
+
+### 3.5.7 单一真相源与禁止重复实现契约
+
+必须测试：
+
+- `project_dir`、`pz.jsonc`、`installed_apps`、`[app_replacements]` 各自只有一套正式读取入口
+- `<cache_dir>/resources/manifest.json` 是资源结果唯一真相源
+- `InfraSettings` / `InfraContext` 是基础设施状态唯一真相源
+- `RuntimePlan` 是运行图唯一组合根
+- app、worker、CLI 不会各自再实现一套 app 扫描、resource merge、infra 探测
+
+验证点：
+
+- 相同问题只存在一个正式编译器/聚合器
+- 其它层只消费结果，不再派生第二份规则
+- `RuntimePlan` 生成后保持不可变快照语义，不会在后续阶段被原地改写
+- `lifespan/startup/shutdown` 不会在 `RuntimePlan` 之外重新拼装第二份运行图
+
+### 3.5.8 编译阶段与执行阶段契约
+
+必须测试：
+
+- settings/app/resource/infra 编译阶段不初始化 DB/Redis/metrics/exporter
+- route/middleware 冲突在执行阶段前已完成裁决
+- Web/CLI/worker 执行阶段只消费 `RuntimePlan`，不再重新生成局部计划
+
+验证点：
+
+- 编译阶段产物是不可变快照
+- 执行阶段不反向修改 settings/app registry/resource manifest/infra snapshot
+- `startup()` / `lifespan` / adapter 层不会成为第二套规则编译器
+- route 去重、route 重排、legacy extension adapter 不会在执行阶段再补一轮启发式裁决
+
+### 3.5.9 历史 route / extension 启发式清退契约
+
+必须测试：
+
+- `admin_panels`、`account_widgets` 这类 legacy app methods 不再是正式扩展声明主链
+- extension 冲突不会再仅靠历史来源优先级的隐式决胜
+- route 冲突不会再通过“先注册、再去重、再重排”兜底
+- `"/"`、`"/{path:path}"`、`"/{lang}/{module}"` 这类 generic route 的处理只依赖正式 manifest 规则
+
+验证点：
+
+- legacy extension adapter 不进入正式主链
+- `_CONFLICTS` 一类运行期候选缓存不是正式冲突治理真相源
+- app-local `clean_and_reorder_routes()` 一类后处理 helper 不再控制正式路由主链
+
+### 3.5.10 ORM model discovery 契约
+
+必须测试：
+
+- `installed_apps` 驱动 ORM models 自动发现
+- `<app>.models`
+- `<app>.module.models`
+- `<app>.runtime.models`
+- 多级 `models/` 包递归扫描
+- `Meta.app` 与 `app.id` 不一致时报错
+
+验证点：
+
+- 保留 Django 风格 “installed apps -> model discovery” 哲学
+- 但发现规则、label 规则、错误诊断都形成稳定契约
+- 有 models 的 app 缺失 `migrations/<app_id>/` 时错误明确
+
+### 3.6 单例与热启动
+
+必须测试：
+
+- import-time 单例可 reset
+- 多次创建 app 不重复污染状态
+- 多 worker / 多进程场景锁目录正确
+- 默认事件总线、默认 Redis/client、默认 email/i18n factory 不再作为正式运行模型
+- 包级 `__getattr__` lazy export、模块级 `_DEFAULT_*`、`set_default_*` 不再构成正式公共 API
+- 热重载后二次启动不复用脏状态
+- 全局 provider 注册表可清理
+- 资源服务 / 模块配置服务可按新 settings 重建
+- i18n runtime 默认值与模板环境可按新 project context 重建
+- wildcard event subscriber 与模块级 buffer 可清理
+- 同一进程内切换不同 `project_dir` 时，旧全局 settings 单例 / CLI manager 不会复用前一个项目的全局快照
+- `ensure_full_settings()` 失败时不会吞异常后留下半初始化状态作为正式运行结果
+- `create_app()` / `create_host_app()` 不会隐式触发 assets build/deploy
+- `create_app()` / `create_host_app()` 不会通过全局 setter 重配默认 event bus / Redis config / email config / i18n runtime
+- merged locales 不会在 bootstrap 阶段反向改写全局 i18n runtime 与 modules provider
+- translation manager / module config runtime 不会在不同 `project_dir`、多次 create_app、并行测试中复用脏快照
+- `redirect_rules_cache` / `email_manager` 在不同 project_dir、多次 create_app、测试并行时不会共享脏状态
+- `ResourcesMixin` 初始资源路径计算不再依赖 repo-root helper 或反向 import 包目录
+- `I18nPrefixMiddleware` / `SettingsL2RefreshMiddleware` / redirect middlewares 在不同 project context 下不会复用前一次全局 settings/provider 状态
+- settings snapshot 在入口期完成后，不会再被 bootstrap/lifespan 隐式重写稳定字段
+- `preflight` 优化任务不会在 Web 正式 startup 路径里默认执行
+
+### 3.6.1 扩展点与 middleware 冲突契约
+
+必须测试：
+
+- 同 `Extension.id` 默认失败
+- 不再按历史 source rank 静默保留
+- legacy adapter 关闭后，旧式 `admin_*` / `account_*` 声明有明确迁移诊断
+- legacy adapter 若开启，其冲突行为也必须可预测，不得仍走来源优先级静默裁剪
+- middleware 重复声明默认失败
+- middleware 显式 replace 时结果可预测
+- middleware 冲突诊断包含 `id` / `owner`
+- `_CONFLICTS` 不再只是诊断副本，默认失败策略下必须能阻止裁剪后的结果进入正式运行态
+
+验证点：
+
+- extension registry 是唯一正式冲突裁决点
+- middleware registry 不再退回“类路径 key + 后写覆盖”
+
+### 3.6.2 Redis / cache / overrides 一致性契约
+
+必须测试：
+
+- `redis.enabled = false` 时：
+  - 不创建默认 Redis client
+  - `/ready` 不探测 Redis
+  - cache/L2/version helper 有明确 disabled 语义
+- settings runtime owner 无 Redis 时，多实例一致性策略明确
+- `cache_service` / `redis_manager` / `module_config_service` 可 reset 或按 context 重建
+
+验证点：
+
+- 不再依赖默认 `127.0.0.1:6379`
+- 不再依赖“吞异常 + 周期 reload”作为正式跨实例同步模型
+- Redis disabled / unavailable / cache miss / local-only hit 是可区分语义
+- `set_default_redis_config()` / `create_redis()` / `reset_all_redis_connections()` 不会让不同 project context 在同进程内互相污染
+- settings overrides loader / L2 client 不再通过全局 setter 把项目上下文写进进程级单例
+- `configure_settings_db_overrides()` 的 deferred loader 语义不会在 provider 缺失时静默吞掉配置边界错误
+- settings runtime override 写入失败时不会只修改当前进程内存态并伪装成持久化成功
+- module_config_service 不会在 import 时绑定 merged locales 路径与全局 `PZ_ENV`
+- `ModuleConfigL2RefreshMiddleware` 不再依赖“version=0 也周期 reload”来维持正式一致性语义
+- storage 本地回退路径不再隐式合成 `default/media` backend 并写入相对本地目录
+- `StorageServiceMixin` / local storage 默认值会先被统一归一化到 `asset_dir` 语义，而不是直接沿用 `"uploads"` / `"/uploads"`
+- local storage 在无 public base_url 时，不再把 `file://<absolute-path>` 当成公共 URL 语义
+- `module_config_service` / `module_config_manager` 的 `_composed_cache` 不会跨 `project_dir`、多次 `create_app()` 或测试用例复用旧快照
+- `redirect_rules_cache` 的规则快照、版本号与 reload 时间不会跨项目上下文共享；reload / invalidate / clear 操作带有明确 owner 与 project scope
+- settings runtime owner / redirects owner 在 reload 失败或 L2 不可用时不会偷偷沿用失败前的内存快照并伪装成“已完成同步”
+
+### 3.6.3 Middleware 装配契约
+
+必须测试：
+
+- middleware kwargs 不再依赖 `__init__` 参数名反射自动猜测
+- `MiddlewareDecl.id` / `owner` 真正参与冲突治理
+- path 声明式 middleware 与 app 声明式 middleware 的冲突默认失败
+- middleware 初始化不会偷偷回退到全局 `settings` / `translation_manager` / ports getter 作为正式配置源
+- redirect middlewares 不在构造期直接缓存来自全局 settings 的规则或 provider 结果
+- middleware 默认规则、默认放行清单、默认保护清单都可被显式审计
+- `MiddlewareDecl.factory` / `ParamsModel` 若声明存在，其行为是正式生效且可测试的；否则不出现在稳定契约中
+- middleware 去重不再按类路径 key 做“最后写入 wins”
+- manager 内部不再依赖 suffix match / normalized match 自动猜 settings 属性
+- request logging / geo_country / audit 中间件不会无条件信任 `X-Forwarded-For`、`X-Real-IP`、`Forwarded`；trusted proxy 链必须显式配置
+- `CORS allow_origins = "*"` 与 credentials 的关系在编译期被显式裁决，不再依赖运行时静默改写
+- CSRF cookie/header/path/mode 之外，cookie 的 `SameSite` / `Secure` / domain / path 语义也必须显式建模并可审计
+- security headers / CSRF 中间件不再在构造期直接 import 全局 `settings`，而是消费编译后的配置快照
+- auth cookie 的 domain / `SameSite` / `Secure` / `HttpOnly` 不再在 middleware/router 运行时临时推导，而是来自显式编译配置
+- `session_recovery` 不会对任意 API 请求拿 refresh token 静默续签；其触发路径、允许方法和失败语义可审计
+- request logging 对 `Authorization`、`Cookie`、`Set-Cookie`、session proof、API key 等敏感头的脱敏不受 allowlist/环境差异影响
+
+验证点：
+
+- middleware 生效参数来自显式声明或正式配置映射
+- 不再是“类路径 key + 最后写入 wins”
+- `RedirectMiddlewareMixin` 的默认规则、`SecurityCSRFMixin` / `DenyAPIMixin` / `CmsAuthGuardMixin` 的默认清单，不会在最小安装场景下被偷偷当成基础包强约束
+- manager 内部不再夹带类似“CORS wildcard 自动把 credentials 改成 false”这类未文档化硬编码规则
+- 请求日志、geo_country、风控链路使用的 client IP 解析结果可审计，且不会因为未受信代理头而被伪造
+- Host / Origin / CORS 白名单规则显式且可预测，不依赖 `Host` / `Origin` 头的宽松透传
+- 生产 HTTPS 场景下，安全相关 cookie 不会继续默认以缺失 `Secure`/宽松 `SameSite` 的方式下发
+- `X-User-ID`、认证派生标识等响应头不会在公共边界默认暴露；若启用内部透传，也具备显式 owner 与 deployment scope
+- 请求日志在错误场景、调试场景、JSON 模式下都不会泄露 access token、refresh token、cookie 原文或 session proof
+
+### 3.6.3.1 Runtime Architecture Allowlist 契约
+
+必须测试：
+
+- runtime architecture contract 对所有 owner repo 扫描 Python 源码与模板源码
+- 非容器级跨 app import 视图与 allowlist 保持一致
+- allowlist 只记录当前仍存在且仍被允许的正式 import 面
+- 历史文件路径重构后，contract test 必须同步到新的正式真相源
+
+验证点：
+
+- contract test 只认 `<pkg>.urls` 作为正式入口
+- `site_runtime`、`platform`、`customer_service` 之间的跨子仓依赖只走 `public` / `api`
+- app 若只是读取另一子仓 settings 的单个值，也必须由对方 `public facade` 暴露，不允许直连 `settings`
+- allowlist 的每次变更都应体现“边界更清晰”而不是“为了过测试临时加白”
+
+### 3.6.4 Route Registry 与冲突裁决契约
+
+必须测试：
+
+- `RouteRegistry` 在正式契约中持有 owner / app_id / route hints / replace target 等元数据
+- route conflict 能在真实 `FastAPI.include_router()` 之前被检测
+- 每个 app 的 URL 真相源来自专门的 `<pkg>.urls`，而不是 `apps.py` / `startup()` / 局部 include hook
+- `<pkg>.urls` 必须直接使用原生 `APIRouter()` / `include_router()` 声明本 app 路由，不再引入第二套 route declaration DSL
+- route registry 的正式真相源来自每个 app 的 `<pkg>.urls` 与统一 registry，而不是注册后的启发式修补
+- app-local `clean_and_reorder_routes()` 不得存在
+- 官方扩展层允许存在唯一的 `clean_and_reorder_routes()` 作为最终 route finalizer，但它只能在所有 app、host route、mount 加载完成后最后执行
+- `ROUTE_CONFLICT_POLICY` 默认失败语义稳定
+- 每个 app 的 `route_hints` 在声明期即固化，不会在后续 apply 阶段读取到错误的外层 app 状态
+- startup 之后不会再通过二次 route repair 改写既有路由语义
+- 目录型页面 canonical URL 统一以 `/` 结尾，文件型 URL 不以 `/` 结尾
+- slash 规范化行为在 host / routing 层具备统一契约，不依赖业务包各自实现
+- canonical、hreflang、sitemap 与 redirect target 输出不会偏离正式尾斜杠规则
+
+验证点：
+
+- 路由顺序首先来自声明与规则，最终表可由官方扩展层 finalizer 做统一清理与排序
+- generic route 与 definite route 的优先级形成稳定契约
+- route manifest 与最终 FastAPI 路由表是一致且可审计的
+- app 内部的 URL 聚合方式保持原生、可读、接近 Django `urls.py`
+- slashless 请求到目录型 canonical 的规范化结果稳定且可审计
+- 文件型 URL 不会被错误补成带 `/` 的第二 canonical
+
+### 3.6.5 provider binding / events / worker lifecycle 契约
+
+必须测试：
+
+- 内部 provider binding 注册项可 reset / unregister
+- auth owner startup/shutdown 前后 user resolver / admin checker 生命周期对称
+- task dispatch owner business event subscriber 可 detach
+- in-process worker 在 shutdown 后不会残留后台任务
+- settings runtime owner / redirects owner / auth owner 通过 binder/provider binding 注册的能力都具备 owner 与对称清理
+- 未实现 `shutdown()` 的平台 app 不会把 startup 注册的全局 provider 残留到下一次 create_app
+- 资源服务不会在 import `pz.core.resources.file_service` 时就绑定一份全局 settings/path 快照
+- i18n/modules provider 不会在本次 resources merge 之前就基于旧 merged locales 快照提前完成同步
+
+验证点：
+
+- 平台 app 生命周期不再留下 process-wide 脏状态
+- provider binding registry、event bus subscriber、worker scheduler 都有明确 owner 和清理路径
+- worker/background loops 不再在运行中反复依赖 `ensure_full_settings()` 修补配置
+- task dispatch owner business events 订阅与 buffer 都具备对称清理路径
+- app startup 失败语义是稳定契约，不依赖某个临时环境变量决定是 warning 还是 fail-fast
+
+### 3.6.6 Event Bus 与 Worker SDK 契约
+
+必须测试：
+
+- 默认 event bus 可 reset
+- auth owner email events 订阅可对称解绑
+- task dispatch owner business events wildcard 订阅可清理
+- worker SDK 在非 loopback / 分离部署场景下不依赖本地 socket 探测
+- worker SDK 不把固定成功的 Web `/ready` 当作任务系统真实可用性证明
+- `publish_nowait()` 在不同 loop 状态下具有一致、可预测的执行语义，不依赖 `asyncio.run()` / 当前 loop 回退的隐式分支
+- MailFacade 在 provider 不可用、仅日志降级、真正投递成功三种场景下语义可区分
+- mail provider 备用链若存在，其顺序、启用条件与最终诊断结果可测试，不会对调用方伪装成统一成功
+
+验证点：
+
+- process-wide event bus 不再残留跨 app/跨测试订阅
+- worker runtime 与 Web runtime 可以独立部署而不互相耦合本地网络前置条件
+- task dispatch owner worker 热路径不会在每次 pull/register/heartbeat 时重新触发全局 settings 补挂
+- task dispatch Web readiness 不再固定成功，且 worker SDK 不依赖 loopback socket 探测
+- worker `wid/token`、TTL、stale_seconds、`re-register` 语义形成稳定协议，过期或权限失效不会被旧分支静默掩盖
+- worker supervisor 的 host-local lock / state / temp 路径来自 `runtime_dir`，而不是系统级临时目录
+- 若代码里仍残留 `401 -> 自动 re-register`，其行为、边界与诊断输出必须可测试，且不会把协议错误伪装成成功恢复
+- `publish_nowait()` 在无运行中 loop 时不会偷偷改成同步执行，也不会靠 `asyncio.run()` 改变上下文语义
+- fire-and-forget 事件处理失败时有稳定 owner/topic/handler 诊断，而不是只留下不可归属的 warning
+- mail send/enqueue 失败不会只写日志后向上层返回“看似成功”的结果
+
+### 3.6.7 ORM 配置与迁移快照契约
+
+必须测试：
+
+- `aerich_config` 不在模块导入时固化全局 `TORTOISE_ORM`
+- ORM config 基于当前 project context 惰性构建
+- DB config 不会在内部再次重建一套与入口分叉的 installed apps 列表
+- `aerich.models`、`<app>.models`、`<app>.module.models`、`<app>.runtime.models` 的发现规则在显式 app registry 下保持稳定
+
+验证点：
+
+- ORM/迁移配置与入口期 app registry 使用同一真相源
+- 不再依赖全局 settings 旧门面或 import-time 快照
+
+### 3.6.8 CLI 入口与项目上下文契约
+
+必须测试：
+
+- `init` 类旧入口不得生成 wrapper 或修改 shell rc
+- `git_plugins` 类命令不是正式入口，也不得承载正式子包发现逻辑
+- `db` CLI 不再写 repo-root 或包内 `aerich.ini`
+- `db` CLI 不再通过 `PYTHONPATH` 注入兜底导入项目包
+- `db` CLI 不再依赖 owner heuristic、suffix match、历史 `app` 路径猜测才能决定迁移归属
+
+验证点：
+
+- CLI 都围绕显式 project context 工作
+- 包安装场景与源码仓场景共享同一入口语义
+
+### 3.6.9 Observability / Health Surface 契约
+
+必须测试：
+
+- 导入 logging/metrics 模块本身不会在 `cwd` 下偷偷创建 `logs/` 或注册不可清理的全局状态
+- logging 输出目录来自 `runtime_dir/logs` 或显式外部配置
+- root logger、bot handlers、metrics registry 在多次 `create_app()` / 多个 `project_dir` 下可 reset 或隔离
+- `/metrics` 仅在显式启用时挂载，且路径/暴露策略可预测
+- `/dev/extensions` / `/dev/routes` 仅在正式 debug/capability 开关下暴露
+- app/worker 可通过统一 facade 注册指标，而不是直接依赖模块级全局 `metrics`
+- Prometheus exporter route 只负责导出，不把 scrape job / dashboard / alert 语义混入框架设置
+- 默认 metrics label 策略不会把高基数或敏感字段写进公共指标
+- 文件日志输出在未显式启用时不会自动创建 `runtime_dir/logs` 或附加文件 handler
+- Feishu / Telegram 这类 bot handler 的线程池、实例缓存、投递队列具有可测试的 shutdown 与背压/丢弃语义，不会无限积压或跨项目复用
+
+验证点：
+
+- observability 是 facade 组，底层依赖显式 capability 与 provider 绑定，而不是 import-time 全局副作用
+- health / metrics / dev surface 的暴露边界稳定且可审计
+- `pz` 只提供监控集成边界，不把部署层监控平台职责塞进 core
+- bot/告警通道失败不会阻塞主请求路径，但也不会因“只写日志”而完全失去可审计性
+- logger `MARKDOWN` 渲染能力有正式 renderer 与契约测试，不再依赖匿名字符串替换
+- bot handler 默认并发度来自 settings 真相源或显式环境覆盖，而不是模块级硬编码
+
+### 3.6.10 Capability 与平台 app 契约
+
+必须测试：
+
+- app 可以依赖 capability/facade，而不是依赖某个固定官方实现模块
+- 替换平台 app 后，capability registry 仍保持可用
+- 最小安装场景下，缺失某 capability 时错误或降级语义明确
+- app 不直接依赖 `CapabilityRegistry` 内部结构，而是依赖 facade 或稳定 capability contract
+
+验证点：
+
+- 平台能力可以替换、拆仓、裁剪
+- app 生态不会被某个官方 app 或独立子包的内部模块路径绑定死
+
+### 3.6.11 apps 目录与装配边界契约
+
+必须测试：
+
+- 正式最小子包源码只从标准 `apps.py` 入口发现，目录名/import 包名默认按 `<app_id>` 收敛
+- 容器目录只负责递归发现嵌套最小子包，不再作为运行时源码根
+- 模板、资源、源码定位逻辑不会依赖历史集合层目录、旧 `distributions/*` 或集合层包的 `__file__`
+- 测试与构建脚本不会把集合层目录或历史分发目录假定为正式源码真相源
+- 官方 app 若允许被其他包 import，也只能通过文档声明的稳定 `public.py facade` 依赖面
+
+验证点：
+
+- `pz` 与 `pz_apps` 只承担源码组织职责，正式 app 真相源始终是各自标准 `apps.py` 暴露的 `app.id`
+- 官方维护最小子包与其它最小子包都按同一运行时规则治理；跨包协作默认只通过 facade/API/events/CLI 等稳定交互面
+- 宿主测试若要消费项目 `.sources` 中的共享源码仓，必须通过共享 bootstrap 与显式 import mode 完成，不允许各测试私自改 `sys.path`
+
+### 3.6.12 Packaging / Assets / Lifespan 契约
+
+必须测试：
+
+- `pyproject.toml` 实际暴露的 extras 名称与对外文档一致
+- wheel 安装后存在正式 `console_scripts`，不依赖 wrapper/init
+- `register_core()` / `create_app()` 默认不会触发 asset build
+- preflight/asset build 若启用，也只能通过显式 task/CLI 进入
+- lifespan 不会在 startup 后依赖 `clean_and_reorder_routes()` 修补路由 plan
+- settings overrides/L2/default redis config 注册不会在 lifespan 与 infra setup 中重复写入全局状态
+
+验证点：
+
+- 包元数据与运行时入口语义一致
+- assets/build 是显式能力，而不是默认装配副作用
+- lifecycle 语义稳定，不靠 startup 后补丁式修复
+
+### 3.6.13 Settings Overrides / ORM Config 契约
+
+必须测试：
+
+- `pz.settings` 导入本身不会把最终 env snapshot 写回 `os.environ`
+- overrides/L2 状态在不同 `project_dir`、多次 `create_app()`、并行测试中可隔离或 reset
+- dotted runtime override key 若被声明支持，必须真的能更新嵌套对象
+- 未实现 dotted path 时，会给出明确诊断，而不是静默忽略/半生效
+- `aerich_config` / `TORTOISE_ORM` 不在模块导入时固化全局 settings
+- ORM config 使用入口期 app registry，不再在内部重复 merge `installed_apps + installed_apps_extension`
+
+验证点：
+
+- 旧全局 settings 单例不再是进程级隐式真相源；应用层正式读取入口固定为 `settings_center.settings`
+- runtime overrides 与 ORM config 的作用域、输入来源、失败语义都稳定可预测
+
+### 3.6.14 Default App List / App Settings / DB CLI 契约
+
+必须测试：
+
+- 最小安装场景下，框架不会默认注入整套官方 app / 独立子包清单与业务包 `app`
+- `installed_apps` / `installed_apps_extension` 的顺序语义在 env 覆盖后仍保持稳定
+- `attach_app_settings()` 不再依赖全局 `pz.settings.settings` / `_collect_env`
+- app settings 聚合正式只包含项目配置中的 `[apps.<app_id>]`、项目 `.env*`、显式环境变量与运行态补值
+- runtime override 白名单不再依赖 `auto_register_overrides_from_obj()` 的对象反射结果
+- `db` CLI 的 owner 归属不再依赖 suffix match / `label == models -> app` 回退规则
+- `db` CLI 不再自动执行 `fix-migrations` 或补丁式修复迁移文件格式
+
+验证点：
+
+- 默认 app 清单符合“最小框架包”目标
+- app settings 聚合链是单一且显式的
+- DB CLI 的迁移归属、失败语义、帮助文案都围绕标准包化模型工作
+
+## 4. 资源与包内容测试
+
+必须验证 wheel 中确实包含：
+
+- `templates/`
+- `static/`
+- `locales/`
+- `migrations/`
+- `configs/`
+- `configs/__init__.py`
+- `configs/default.jsonc`
+- `configs/default.env`
+
+并验证安装后：
+
+- 资源发现可读
+- `pz settings init/update` 可从包内 `configs/default.jsonc` 同步默认配置模板到项目 `pz*.jsonc`
+- `pz settings init/update` 可从包内 `configs/default.env` 合并项目 `.env*` 占位
+- `configs/default.env` 中的变量必须是已由 `configs/default.jsonc` 展示的 password、secret、token、key 类路径；非密钥业务字段不得进入 `.env*` 模板
+- 启动阶段不得直接读取包内 `configs/default.jsonc` 或 `configs/default.env`
+- 包内资源只读不影响运行
+
+补充覆盖：
+
+- `static/templates/locales` merge 目标目录都来自当前 project settings
+- `static/templates/locales` merge 必须按 `installed_apps` 从前到后执行；同相对路径资源必须由后面的 app 覆盖前面的 app
+- 不再依赖 `ROOT_DIR`、`app` 或容器 token 或 shared site UI owner 特殊顺序才能得到正确覆盖结果
+- assets build 不再依赖 repo-root 推断或具体最小子包 builder 实现
+- resources bootstrap 不会再隐式触发全局 `module_config_manager.load_configs()` / `translation_manager.reload_translations()`
+- preflight image generation 不再默认写回 `app/static`
+- `ResourcesMixin` / merge order 不得通过 `_repo_root()`、`ROOT_DIR`、自动补包名前缀来决定资源根目录
+
+## 5. CLI 与 worker 测试
+
+必须覆盖：
+
+- `pz list`
+- `pz <app> <tool>`
+- `pz db ...`
+- 独立 worker CLI
+- worker 锁路径与状态目录
+
+要求：
+
+- `pz db ...` 在 DB 未启用时给出明确诊断
+- worker 与 web 复用同一 settings 解析路径
+- 不再依赖 wrapper 初始化
+- `CliManager` 错误提示与帮助文案不再输出 `python pz ...`
+- `__main__` 在标准入口模式下不再依赖修改 `sys.path` 才能发现项目 app
+
+补充覆盖：
+
+- `pz db makemigrations` 导出的 owner 判定必须可预测
+- 不再依赖 suffix match / 历史 `app` 路径猜测这类启发式才能决定迁移归属
+- `CliManager` 不再通过 app_id last-segment 回退或 tool-module direct import 回退掩盖错误配置
+- `aerich_config` / Tortoise config 不会在 import 时固化错误的全局 settings 快照
+- worker SDK 不再默认依赖 loopback socket preflight
+- worker SDK 不会把某个 owner 私有 readiness URL 的宽松响应语义误判成系统 ready
+- `401 -> 自动 re-register` 这条历史恢复路径有明确测试，且不会掩盖正式 session 协议错误
+
+## 5.1 配置中心与资源门面测试
+
+必须覆盖：
+
+- settings runtime owner 注册 provider 后可在 shutdown 时清理
+- 如果声明了 settings provider，最终 settings 必须在 app lifecycle startup 前完成解析，不依赖某个具体 app 被特殊提前启动
+- runtime settings 默认值读取不重复触发完整 app 装配副作用
+- `locales` / `static` / `templates` merge 服务在变更 `cache_dir` 后可重建
+- 本地 storage URL 在未配置 base_url 时不会把宿主机路径当公共契约输出
+- `db` CLI 在 wheel 安装模式下不依赖 repo-root 或包内 merged 目录
+- CLI help 文案不再把 `python pz` 或 `python -m pz` 作为标准主路径
+- Web `startup()` / `setup_infra()` / `/ready` 不会替代显式 `pz db ...` 去执行 schema 生成或迁移修补
+
+补充覆盖：
+
+- `CorsMixin` 历史环境变量别名是否仍按字段折叠计划工作
+- `I18nMixin` 的默认值、语言代码规范化和派生字段是否由统一 settings 聚合层产出
+- `settings_l2_check_interval` 这类 middleware 配置边界是否仍保持稳定且可测试
+- `register_core()` / `create_app()` 在显式传入 settings snapshot 时不会偷偷回退到全局 settings
+- account / profile owner widget/menu/assets 在 app 替换、多次 create_app、不同 project_dir 下不会残留旧 registry、旧模板环境或旧静态目录绑定
+
+## 6. CI 正式矩阵
+
+至少包含：
+
+- Linux 安装 smoke
+- macOS 安装 smoke
+- 纯 base 环境
+- `db + sqlite`
+- `db-postgres`
+- `db-mysql`
+- `redis`
+- wheel 安装模式
+
+执行规则：
+
+- SQLite 作为 PR 必跑
+- MySQL、PostgreSQL、Redis、wheel 安装模式进入正式 CI 矩阵，不再只作为口头建议
+- Linux 与 macOS 至少各保留一组非源码目录的 wheel 安装与基础命令 smoke run
+
+补充要求：
+
+- 至少保留一组“升级前 -> 升级后 -> 回滚后”验证
+- 至少保留一组 base-only 轻量命令矩阵
+
+## 7. 回归门禁
+
+每完成一组主链改造，应新增相应门禁测试，至少包括：
+
+- 一项安装包模式测试
+- 一项可选基础设施测试
+- 一项平台 app / app 替换测试
+- 一项“旧实现行为基线”回归测试，覆盖路由、配置、资源、错误语义或 worker 协议中的至少一个外部可观察行为
+
+没有测试的设计项，不应视为完成。