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/06-/346/225/260/346/215/256/345/272/223/344/270/216/345/217/257/351/200/211/345/237/272/347/241/200/350/256/276/346/226/275/350/247/204/350/214/203.md

@@ -0,0 +1,499 @@
+# 数据库与可选基础设施规范
+
+## 1. 目标
+
+数据库、Redis、观测能力必须成为可选基础设施，而不是 `pz` 最小运行前提。
+
+## 2. base 运行要求
+
+`pz` base 安装必须支持：
+- 无数据库
+- 无 Redis
+- 无 Prometheus
+- 无 OpenTelemetry
+
+最小应用在这种情况下仍应可以：
+- 装载 app
+- 注册路由
+- 使用模板/静态/语言资源
+- 正常启动与关闭
+
+约束：
+
+- “最小应用可运行”不等于“所有官方 app 都可运行”
+- 凡依赖 DB/Redis/metrics/OTel 的能力，都必须通过显式 capability 建模
+
+## 3. 数据库支持范围
+
+正式数据库支持：
+- SQLite
+- MySQL
+- PostgreSQL
+
+约束：
+- SQLite 必须是一级支持目标，不是临时开发兜底
+- MySQL 与 PostgreSQL 通过独立 extras 装驱动
+
+## 4. 依赖分层
+
+- `pz[db]`
+  - ORM、迁移基础能力
+- `pz[db-postgres]`
+  - PostgreSQL 驱动
+- owning infra package extra, e.g. `[db-mysql]`
+  - MySQL 驱动
+- owning infra package extra, e.g. `[redis]`
+  - Redis 客户端
+
+要求：
+- 安装 `pz` core 本体时不应强制拉取全部数据库驱动
+
+## 5. 启用策略
+
+数据库与 Redis 应显式启用。
+
+示例：
+
+```toml
+[apps.<infra_owner>.database]
+enabled = true
+driver = "sqlite"
+database = "app.db"
+
+[apps.<infra_owner>.cache]
+enabled = false
+```
+
+行为要求：
+- `enabled = false` 时不初始化对应客户端
+- 未安装对应 extra 且配置启用时，启动期给出明确错误
+
+补充要求：
+- `database.enabled = false` 时，不应再要求提供默认 `db_host/db_name/db_user`
+- `redis.enabled = false` 时，不应再默认回落到 `127.0.0.1:6379`
+
+settings 模型必须按 `database.enabled` 与 SQLite 一级支持目标收口，不得默认假设数据库存在。
+
+## 6. 生命周期行为
+
+### 6.1 数据库
+
+- 配置启用时初始化
+- 未配置或禁用时跳过
+- readiness 仅在启用数据库后才探测数据库状态
+- 不得在全局 `setup_infra()` 中默认强制初始化 DB 并把失败视为所有应用的启动失败
+- `create_app()`、Web `startup()`、`setup_infra()`、`/ready` 都不得执行 `generate_schemas`、自动建表、迁移修补或 schema auto-heal
+
+启动链必须拆出“数据库初始化”和“数据库连通性前提”，按 `database.enabled` 驱动的可选模型收口。
+
+补充要求：
+
+- 将“初始化数据库连接池”和“执行 schema/migration 操作”拆成两个明确阶段
+- Web 启动不应隐式承担 migration/apply-schema 职责
+- schema 创建、迁移执行、迁移文件修补只能通过显式 `pz db ...` 或显式 repair/check 流程触发，不能作为“启动成功前顺手完成”的副作用
+
+### 6.2 Redis
+
+- 配置启用时初始化
+- 未配置或禁用时跳过
+- app 代码若依赖 Redis，必须显式声明并在运行时优雅失败
+- 不得在 `create_redis()`、dependency helper、middleware 构造阶段默认回落 `127.0.0.1:6379`
+- 中间件、限流器、task runtime 若依赖 Redis，必须先消费统一的 `redis.enabled` 判定
+
+### 6.3 Task dispatch / Worker 类基础设施
+
+task dispatch / worker owner 这类平台级 app 与 Redis 的关系应明确建模：
+
+- 若 task dispatch / worker owner 需要 Redis，则必须显式声明
+- Redis 未启用时，应明确报错或禁用该 app 的相关入口
+- 不应通过全局单例隐式探测后“半工作”
+- task dispatch / worker owner 的 readiness surface 不能只返回固定 `ok`，必须反映其自身关键依赖是否可用
+- worker SDK 不应仅靠轮询 Web 进程的 owner 私有 readiness URL 来推断整个任务系统已可用
+
+补充约束：
+- task dispatch / worker owner 的 delay sweeper / reclaimer / worker cleanup 后台循环，不应在运行过程中反复 `ensure_full_settings(global_settings)`
+- worker register / heartbeat / pull 协议里返回给客户端的 server 参数，应在入口期由当前 settings snapshot 固定，而不是每次请求从全局 settings 现取
+
+### 6.4 InfraSettings 快照约束
+
+正式运行时必须构造唯一一份 `InfraSettings` / `InfraContext` typed snapshot：
+
+- 这些对象必须带 `enabled` 语义
+- 不能默认把 DB/Redis 视为必填对象
+- 不能在 disabled 场景下仍构造出“看似可用”的默认 host/port 配置
+- Web、worker、CLI、health/readiness 都只允许消费这同一份 typed snapshot，而不是各自重新从全局 settings 推导
+
+typed snapshot 必须真正表达 `enabled/disabled/ready/unavailable`，不能只是“再包装一层全局 settings”。
+
+补充要求：
+
+- `InfraSettings` / `InfraContext` 成为基础设施能力的唯一真相源
+- DB、Redis、mail、metrics、overrides/L2 都必须先编译进 typed snapshot，再进入后续 capability 装配
+- `pz` 基础层只拥有 typed snapshot 与编译协议，不直接拥有 concrete database/redis/mail/storage 作者面
+- concrete 配置真相源必须归属正式 capability owner app；官方或业务实现通过自己的 settings 持有 `database/cache/mail/storage/health/observability` 等配置，再通过 `infra.provider` 编译进 `InfraContext`
+- 基础设施状态统一收敛为显式枚举：
+  - `disabled`
+  - `enabled`
+  - `ready`
+  - `unavailable`
+- 不再允许某些入口使用 typed snapshot，另一些入口直接读取全局 settings 或默认单例
+
+### 6.5 readiness 聚合器约束
+
+readiness 聚合器必须只探测显式启用的组件：
+
+- `database.enabled = false` 时，不调用 DB 初始化或连接校验
+- `redis.enabled = false` 时，不创建 Redis client，不探测 Redis
+- 未启用的依赖统一返回 `disabled`
+- 已声明但属于 disabled capability 的 provider，不得把状态抬升成 `enabled` 或 `unavailable`
+
+不允许：
+
+- 为了生成 `/ready` 响应而隐式初始化 DB/Redis
+- 把“未配置”解释成“检查本机默认实例”
+
+现有 `/ready` 语义必须收口为“只探测显式启用组件”，并把 `disabled` 作为正式状态语义。
+
+## 7. app 编码约束
+
+app 不得：
+- 在 import 阶段无条件初始化 DB
+- 在 import 阶段无条件初始化 Redis
+- 假设 Redis 一定存在
+- 假设数据库一定存在
+- 将测试专用降级路径作为正式运行时契约的一部分
+
+app 应：
+- 通过依赖注入或门面获取 DB / Redis 能力
+- 在缺失可选基础设施时有明确错误或降级行为
+
+约束：
+- 像 `PZ_TEST_DISABLE_REDIS` 这类测试开关，只能是测试辅助机制，不能成为生产运行模型的一部分
+
+补充约束：
+- cache/L2/version/lock 一类基础能力若依赖 Redis，也必须先经过统一 `redis.enabled` 判定
+- 不应通过“拿不到 Redis 就吞异常并假装成功”把一致性问题静默隐藏
+
+## 8. 健康检查约定
+
+健康检查应区分：
+- liveness
+- readiness
+
+readiness 规则：
+- 只聚合当前已启用的基础设施探针
+- 未启用的后端不计为失败项
+
+约束：
+- 未启用 DB/Redis 时，对应 readiness 项统一标注 `disabled`
+- 不得标成 `error`
+- liveness 必须保持纯轻量，不得触发重型 DB/Redis 初始化
+
+补充要求：
+
+- `liveness` 与 `readiness` 必须是两条明确分离的 surface
+- `readiness` 结果必须来自显式 capability 状态聚合，而不是在 router 内部 best-effort import 某个旧聚合器
+- 当 readiness 聚合器不可用、某项 probe 未实现或 capability 未声明时，不得默认回退成固定成功的 `/ready`
+- dev/debug/extensions 之类诊断 surface 不得混入 health 默认路由
+- readiness probe 不得因为“顺便验证数据库可用”而触发 schema 创建、自动建表、迁移修补或 provider init 副作用
+- 周期性数据库 readiness probe 可以由数据库 owner 后台任务提供；如果执行 SQL，必须证明使用 autocommit-safe 连接，且不得进入请求路径或 liveness 路由
+- 数据库探活不得留下 `idle in transaction`；无法证明不引入事务时必须拒绝探活，而不是用隐式事务和 rollback 作为正式运行模型
+- 数据库连接池容量耗尽、获取连接超时一类信号不得被当成断连自动重建信号，应作为性能或连接泄漏风险暴露
+
+正式失败语义：
+
+- 缺 capability 定义
+  - `disabled` 或显式配置错误
+- capability 已启用但 probe 缺失
+  - 配置/装配错误
+- capability 已启用但初始化失败
+  - `unavailable`
+
+不得采用：
+
+- import 失败就返回固定 `{"status": "ready"}`
+- 为了让 worker 继续跑而把 readiness 永久做成宽松成功
+
+## 8.1 指标与追踪的工程边界
+
+观测能力除了“可选启用”，还需要遵守工程上的低侵入原则。
+
+要求：
+
+- metrics/tracing 关闭时，业务热路径仍可正常运行
+- metrics/tracing 开启时，不应把高基数标签变成默认行为
+- exporter 不可用时，不应拖垮主业务请求路径
+
+要求：
+
+- metrics 名称、标签、单位形成正式规范
+- request path、user id、query text 这类高基数或敏感信息不得直接作为默认 label
+- tracing/metrics 的 flush/export 重试策略必须显式，而不是隐式阻塞请求关闭流程
+
+## 9. 迁移约定
+
+迁移仅在数据库启用时有意义。
+
+要求：
+- `pz db ...` 相关 CLI 必须在数据库未启用时给出明确诊断
+- SQLite、MySQL、PostgreSQL 共用同一迁移归属规则：`migrations/<app_id>/`
+
+补充要求：
+- 有 ORM models 的 app，必须显式提供：
+  - `migrations/`
+  - `migrations/<app_id>/`
+- migration owner 应优先由 app registry / 项目配置决定
+- 不应继续依赖：
+  - suffix match
+  - 历史 `app` 路径猜测
+  - 临时 `PYTHONPATH` 注入
+  这类启发式来决定迁移归属
+- Aerich/Tortoise 配置应按当前 project context 惰性生成，不能在模块导入时固化全局 `TORTOISE_ORM`
+- ORM app 列表应优先来自正式 app registry，而不是在 DB config 内部再次拼接 `installed_apps + installed_apps_extension`
+- 宿主业务 app 可以保留正式迁移链；`apps/.sources` 下的官方/共享源码包只保留数据库 init，不进入 Aerich 历史迁移链
+- `pz db migrate` 对共享源码包只能执行幂等 schema 初始化；真正传给迁移执行器的 owners 应只包含非 `.sources` 的业务包
+
+补充约束：
+
+- `db` CLI 的临时配置文件、迁移工作目录、日志输出目录都必须来自当前 `ProjectContext`
+- 不得写入 repo-root 或包内 merged 目录下的 `aerich.ini`
+- 不得再通过 `_repo_root()`、`_merged_base_dir()`、`PYTHONPATH` 注入来推导迁移工作空间
+- `db` CLI 不得在正式迁移主路径里自动执行“best-effort 修补旧 migration 文件格式”
+
+ORM/迁移配置必须复用入口期 app registry 真相源，`aerich` 相关配置也不得再带 import-time 固化快照。
+
+## 9.1 concrete owner 约束
+
+对于 database、cache、mail、storage、health、metrics、tracing 这类 capability，需要同时区分两层 owner：
+
+- `pz`
+  - 只拥有 typed contract、编译协议与 capability 状态语义
+- capability owner app
+  - 拥有 concrete settings namespace、默认值、provider/client/bootstrap 实现
+
+正式要求：
+
+- 不允许 `pz` 顶层 project settings 与 owner app namespace 同时长期承载同一套 concrete infra 配置
+- 若 `pz` 已退回协议层，则 concrete 作者面必须统一下放到 owner app
+- owner app 的正式字段必须通过 `infra.provider` 编译进 `InfraContext`
+
+## 10. 依赖分发目标
+
+依赖分发目标：
+
+- base 不强装全部数据库与 Redis 依赖
+- `aerich`、DB 驱动、Redis 客户端按 extra 分层
+- SQLite 在 base 或 `db` extra 中即可使用
+
+## 11. Redis 客户端生命周期补充约束
+
+Redis 的“可选”不仅是 settings 开关，也包括客户端创建与缓存语义。
+
+要求：
+
+- `redis.enabled = false` 时，不应创建任何默认 Redis client
+- Redis client cache 不应仅按 host/port 值缓存，还应受当前 project context / lifecycle 管理
+- 不能继续让 `_DEFAULT_CFG`、模块级 `redis_manager`、`atexit` 清理构成正式运行模型
+
+Redis 必须出清“默认存在”的旧心智，client lifecycle 也必须按 owner/reset/project scope 收口。
+
+## 12. metrics / health 可选能力补充约束
+
+Prometheus、health surface 也必须遵守显式启用原则。
+
+要求：
+
+- `metrics_enabled = false` 时，不应导入后就把默认 metrics registry 当成正式全局事实
+- `/metrics` 是否挂载、挂载在哪里、是否公开，必须显式配置
+- dev/debug route 不应混入 health 默认 surface
+- `pz` 基础层只应预留 metrics/exporter/provider 边界，不应把 Prometheus server、Grafana、Alertmanager、scrape jobs 变成框架内核职责
+- 文件日志输出是否启用、输出到哪里，也必须显式配置；不得默认落到进程当前工作目录
+- Bot/告警 handler 若存在，必须具备显式 enabled 开关、背压/丢弃策略与 shutdown 语义，不能只靠类级 `ThreadPoolExecutor` 常驻进程
+
+metrics / health / dev surface 都必须收口到统一 capability 边界，并按显式启用模型出清。
+
+## 12.1 Prometheus 集成的正式边界
+
+针对“整个项目统一接 Prometheus”这个目标，`pz` 应当预留空位，但空位必须收口在框架边界内。
+
+`pz` 基础层应负责：
+
+- 提供统一 metrics facade / provider interface
+- web app、worker、平台 app、外部 app 都通过统一接口注册指标
+- 根据 settings 显式决定是否挂载 exporter route
+- 提供 exporter 路径、namespace、labels、暴露策略等正式配置入口
+
+`pz` 基础层不应负责：
+
+- Prometheus server 本身部署
+- Prometheus scrape jobs 编排
+- Alertmanager 规则
+- Grafana dashboard
+- 监控平台拓扑、remote write、存储保留策略
+
+也就是说：
+
+- `pz` 需要“集成边界”
+- 但不需要“内置完整监控平台”
+
+## 12.2 metrics 正式配置模型
+
+正式配置段如下：
+
+```toml
+[metrics]
+enabled = true
+path = "/metrics"
+namespace = "pz"
+include_process_metrics = true
+bind_internal_only = true
+protected = false
+
+[metrics.labels]
+project = "manga-translate"
+service = "web"
+```
+
+补充约束：
+
+- `metrics.enabled` 是唯一正式启用开关
+- Prometheus 是当前唯一正式 exporter，不提供第二套 `metrics.exporter` 配置
+- `metrics.path` 不应硬编码为根路径 `/metrics`
+- `namespace`、常驻 labels、process/runtime metrics 是否启用，都应显式配置
+- `/metrics` 是否内网暴露、是否鉴权，必须进入正式配置或部署契约
+
+## 12.3 Core 预留的能力点
+
+为支持整项目统一监控，`pz` 基础层必须明确预留以下能力点：
+
+### 12.3.1 指标门面
+
+- 统一的 counter / gauge / histogram 注册入口
+- 统一的 label 规范
+- 统一的 disabled / noop 语义
+
+要求：
+
+- app/worker 不应直接依赖模块级全局 `metrics`
+- 业务代码不应直接假设 Prometheus 默认 registry 就是唯一真相源
+
+### 12.3.2 exporter 挂载边界
+
+- exporter route 的挂载必须走显式 capability
+- 路径、prefix、鉴权、可见性必须可配置
+- health、metrics、debug surface 不应共用同一个“顺手挂载”的隐式逻辑
+
+### 12.3.3 app / worker 扩展注册点
+
+- 外部 app 通过统一 facade 注册自己的指标
+- worker/background jobs 通过统一 facade 注册自己的 collector
+- 平台级 app 若暴露观测能力，应通过 facade/provider 暴露，而不是直接 import 全局 registry
+
+### 12.3.4 生命周期与隔离
+
+- metrics provider 必须支持 reset / shutdown / project scope
+- 多次 `create_app()`、多项目上下文、并行测试之间不得共享脏状态
+- scoped registry 只允许由 context-bound provider 决定，不得由 import-time 单例决定
+
+## 12.4 Prometheus 集成中的禁止事项
+
+不应继续采用：
+
+- 模块导入即创建正式全局 `MetricsRegistry`
+- 直接绑定 Prometheus 默认 registry 作为跨项目共享事实
+- `metrics_enabled = true` 时就把 `/metrics` 固定挂到根路径
+- 把 `/metrics` 默认视为公开接口
+- 让 app 直接 import `pz.infra.observability.metrics.metrics` 作为稳定公共契约
+- 把项目级 scrape 目标、抓取频率、监控平台部署配置写死在 `pz` 包内
+
+## 12.5 对标准 pip 包化的意义
+
+Prometheus 边界如果不提前收口，会直接影响 `pz` 的 pip 包化质量：
+
+- base 安装会继续携带过强的 observability 假设
+- 多项目 / 多实例 / 测试环境容易共享同一批全局指标状态
+- `/metrics` 暴露边界会和项目部署边界纠缠在一起
+
+因此结论是：
+
+- `pz` 必须为 Prometheus 预留正式空位
+- 但这块空位应是“接口与配置边界”
+- 不是“把整套监控平台实现进 core”
+
+## 13. `infra` 边界引用
+
+`infra` 的正式目录边界以 `01-目录与分层规范.md` 为准；facade / capability 公开面以 `13-正式Facade总表.md` 为准。
+
+在本文件中，`infra` 只保留一条约束：
+
+- 与 DB、Redis、mail、metrics、storage 相关的基础设施语义，必须通过最小基础设施边界进入运行图，不得通过 `pz.infra.*` 私有实现路径扩散为公共依赖面
+
+## 14. settings overrides / L2 依赖补充约束
+
+settings overrides / L2 不应被重新定义为 core/infra 基础能力；它们属于 settings runtime owner 或替代平台 app 提供的配置能力，但其底层仍可能依赖 DB/Redis。
+
+要求：
+
+- DB overrides loader、L2 client 不应在基础包启动时默认写入进程级全局 facade
+- 没有 provider / 没有 Redis / 没有 settings runtime owner 时，语义必须显式为 `disabled` 或 `unavailable`
+- 不应通过 deferred lookup + 吞异常 + 返回 `{}` 来把配置边界错误静默隐藏
+
+overrides/L2 必须出清“默认开启的全局机制”心智，并按 `config` 平台 capability 和 project scope 收口。
+
+补充要求：
+
+- overrides/L2 不并入 `InfraContext` 作为 core/infra capability
+- overrides/L2 应通过 `config` 平台 capability 或对应 facade 暴露
+- `overrides.enabled = false` 时，不注册 loader，不创建 L2 client，不暴露 reload 入口
+- provider 缺失、Redis 缺失、版本游标缺失时，必须分别落入 `disabled` 或 `unavailable`，不再统一吞成 `{}` 或静默 no-op
+
+## 15. 基础设施 adapter 边界
+
+数据库、Redis、metrics 相关实现都必须经过统一基础设施边界，不得在 adapter 层重新定义策略；overrides/L2 的底层依赖只通过其所消费的 DB/Redis/config 平台能力进入。
+
+基础设施 adapter 只允许做：
+
+- 依据 `InfraContext` 创建或关闭客户端
+- 把 typed snapshot 翻译为第三方库要求的参数格式
+- 输出标准化的 `ready/unavailable` 结果
+
+基础设施 adapter 不允许做：
+
+- 读取全局 settings 或环境变量补配置
+- 默认补 host/port/user/password/db name
+- 根据 import 成功与否静默切换另一套行为
+- 在内部自行决定 `enabled/disabled`
+- 自行维护进程级默认 client、默认 registry、默认 exporter
+- 把网络错误、认证错误、驱动缺失错误统一吞成空对象或固定成功
+
+正式要求：
+
+- SQLite / MySQL / PostgreSQL 的差异只体现在 provider/adapter 实现，不体现在上层 capability 语义
+- Redis、metrics 必须先由 `InfraContext` 决定是否启用，再进入 adapter 层；overrides/L2 只通过其所归属的 `config` 平台 capability 决定启用语义
+- readiness、health、metrics exporter、DB CLI 不得各自再维护一套 infra 判定逻辑
+
+## 16. 基础设施能力的单一路径原则
+
+从工程治理角度，基础设施能力必须明确“编译一次、执行一次、消费多次”的单一路径。
+
+正式要求：
+
+1. `SettingsSnapshot` 编译出 `InfraSettings`
+2. `InfraSettings` 编译出 `InfraContext`
+3. 执行阶段基于 `InfraContext` 创建 provider/client
+4. Web / CLI / worker / readiness / exporter 统一消费同一份 `InfraContext`
+
+禁止：
+
+- Web 启动自己建一份 DB/Redis 配置
+- readiness 再临时建一份探针配置
+- worker 再从全局 settings 动态拼一份 redis client 参数
+- metrics exporter 再通过模块级默认 registry 判断自己是否启用
+
+这条约束适用于：
+
+- DB client
+- Redis client
+- mail provider
+- metrics provider
+- overrides/L2 provider

pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/07-App/346/233/277/346/215/242/350/247/204/350/214/203.md

@@ -0,0 +1,206 @@
+# App 替换规范
+
+## 1. 目标
+
+外部 app 替换官方维护最小子包的唯一正式方式，是项目在 `pz.jsonc` 中显式声明替换关系。
+
+## 2. 默认冲突策略
+
+默认规则：
+
+- 同 `app_id` 冲突直接报错
+- 同 `Extension.id` 冲突直接报错
+- 同 `(method, path)` 路由冲突直接报错
+- 同一 middleware 重复声明直接报错，只有显式 `replace_target` 才允许替换
+
+目的：
+
+- 避免“谁后加载谁覆盖”的隐式行为
+- 避免模板、迁移、settings、路由、模型归属产生不透明结果
+- 避免继续依赖历史来源优先级
+
+## 3. 显式替换机制
+
+替换关系的唯一正式真相源：
+
+- `pz.jsonc` 中的 `[app_replacements]`
+
+示例：
+
+```toml
+[app_replacements]
+"catalog_app" = "third_party.catalog_app"
+```
+
+约束：
+
+- app 包元数据不负责触发替换
+- 第三方 app 可以声明自己的 `app_id`、`required_pz`、public facade 与 capability contract
+- 是否替换官方 app 只能由项目配置决定
+- route、middleware、extension 若存在 replace 语义，必须在声明对象中显式携带 owner、id、replace target
+- app import path 只能走单一路径，不接受短名补全、自动前缀拼接或 package-level `app` 猜测
+- 扩展点消费侧统一走正式 extension registry，不保留第二套私有收集链
+
+## 3.1 替换关系图模型
+
+app 替换必须是单一、可审计、无歧义的映射关系。
+
+要求：
+
+- 一个 target app 只能有一个 replacement app
+- 一个 replacement app 只能替换一个 target app
+- 不允许链式替换
+- 不允许一对多替换
+- 不允许运行时动态改写替换图
+
+也就是说：
+
+- `[app_replacements]` 必须构成一张一对一、无环、一次解析完成的映射图
+- 替换关系必须在 app registry compiler 阶段一次性裁决完成
+- 后续 route、middleware、extension、resource、infra 都只消费裁决后的结果
+
+## 4. 替换规则
+
+替换生效的前提：
+
+- 项目配置中显式声明替换关系
+- 替换目标与替换来源都已出现在 `installed_apps`
+
+替换生效后：
+
+- 被替换 app 不参与装载
+- 被替换 app 的资源、迁移、settings 不再进入合并链
+- 路由、模型、扩展点均以替换后的 app 为准
+
+约束：
+
+- app 级替换成功后，依赖图中的 `requires_apps` 指向替换后的正式 app 实体
+- 被替换 app 不得先装载再在后续阶段被清理
+- 冲突检测必须发生在 app registry、extension registry、middleware plan 与 route manifest 编译阶段
+
+## 4.1 app 替换与声明级 replace 的边界
+
+app 替换与 route/middleware/extension replace 不是一回事。
+
+要求：
+
+- app 替换只解决“哪个 app 进入装配链”
+- route replace 只解决 route 声明冲突
+- middleware replace 只解决 middleware 声明冲突
+- extension replace 只解决 extension 声明冲突
+
+禁止：
+
+- 用 route/middleware/extension replace 模拟整 app 替换
+- 已经 app-level 替换后，仍让原 app 的部分声明进入正式主链
+- 一边声明 app 替换，一边仍保留原 app 的 provider、route、template、static 或 migration 声明
+
+## 4.2 数据与迁移归属
+
+app 替换最大风险在于数据、迁移和存储归属是否清晰。
+
+要求：
+
+- 替换 app 若接管原 app 的持久化模型，必须显式声明迁移归属策略
+- 不允许两个 app 在未声明关系的情况下共同写同一批表、集合或持久化目录
+- 被替换 app 的 migration owner、model owner、storage owner 必须有明确切换方案
+- 替换不能只看 `app_id` 相同，还要看：
+  - schema 连续性
+  - migration 连续性
+  - `public.py`、facade、capability contract 是否保持同一公开契约
+
+对涉及 DB/存储的替换，额外提供：
+
+- 升级路径
+- 回滚路径
+- 数据变化说明
+
+## 5. 不允许的替换方式
+
+不允许：
+
+- 依赖 `installed_apps` 顺序隐式覆盖
+- 仅凭相同 `app_id` 静默抢占
+- 通过 monkey patch 强行替换其它 app 内部实现
+- 依赖 `Extension.source` 或来源 rank 做静默覆盖
+- 依赖重复路由去重逻辑“保留先注册项”
+- 依赖 middleware 去重逻辑“保留最后一个同 key”
+- 依赖 `requires_apps` 的 suffix match 抢占命名
+- 依赖自动补全导入成功来伪装“可替换 app”
+- 依赖 package-level `app` 导出作为正式 app 装载入口
+- 依赖多套 provider 收集链做隐式替换
+
+## 6. 公共契约要求
+
+外部替换 app 若要替代官方维护最小子包，必须保持以下公开契约：
+
+- 稳定的 `app_id`
+- 必需的扩展点协议
+- 必需的 settings 命名空间
+- 必需的路由或 `public.py` / facade 契约
+- 必需的 provider contract / internal binding / events 协议
+
+约束：
+
+- 若被替换对象本身承担平台级能力，则替换 app 还必须保持其 facade、`public.py` 与 capability contract 的同一公开边界
+- middleware 判定不能只看“最终类名相同”，还应看：
+  - middleware `id`
+  - `owner`
+  - 显式配置契约
+- 身份 / 展示层这类平台侧替换，还必须保持：
+  - widget、menu、assets 的统一消费门面
+  - 模板渲染门面
+  - 静态资源版本与公共静态目录定位
+
+## 7. 版本范围
+
+继续使用：
+
+- `required_pz`
+
+补充要求：
+
+- 替换 app 必须声明其支持的 core 版本范围
+- 如替换的是官方维护最小子包，应在文档中声明对应的官方版本范围
+
+## 8. 项目级声明
+
+项目配置正式支持且必须作为唯一替换声明入口：
+
+```toml
+[app_replacements]
+"catalog_app" = "third_party.catalog_app"
+```
+
+用途：
+
+- 让项目显式表达“我用哪个外部 app 替代哪个官方 app”
+- 便于 CLI、诊断输出和契约测试识别
+
+若替换涉及数据或迁移归属，则显式声明元数据，例如：
+
+- 是否接管原 migration owner
+- 是否要求一次性 schema cutover
+- 是否仅替换路由或 UI 层
+
+## 9. 诊断要求
+
+装配期应输出清晰诊断：
+
+- 哪些 app 被装载
+- 哪些 app 因替换被跳过
+- 哪些替换关系来自项目配置
+- 哪些冲突导致装配中止
+
+## 10. 测试要求
+
+替换机制需要契约测试覆盖：
+
+- 同 `app_id` 默认冲突报错
+- `requires_apps` 缺失依赖时报错
+- app dependency cycle 默认报错
+- app import path 不再依赖短名补全、自动前缀拼接或 package-level `app` 猜测
+- `validate_and_sort_apps()` 不再接受 module suffix match 作为正式依赖解析语义
+- 同 `Extension.id` 默认冲突报错
+- route、middleware、extension replace 的结果可预测
+- 未满足版本范围约束时装配失败