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/21-contrib/347/272/246/345/256/232/344/270/216Provider/346/216/245/345/205/245/350/247/204/350/214/203.md

@@ -0,0 +1,365 @@
+# contrib 约定与 Provider 接入规范
+
+> 本文说明一条固定主线：`pz` 只定义稳定合同与编译装配协议，`pz_contrib` 负责官方通用能力的正式实现与约定消费，其他最小子包只通过既定扩展点提供 provider / middleware / panel / menu / settings patch，不再在宿主或基础层写第二套装配。
+
+## 1. 为什么单独写这篇
+
+只看 `14-分层与扩展规范`，容易知道“基础层不能吞高层实现”，但还不够回答下面这些高频问题：
+
+- 为什么 `contrib` 不是第二基础层，却又要承接很多正式约定。
+- 为什么 `auth`、`seo`、`admin`、`settings operator` 这些能力应该由 `contrib` 集中消费扩展，而不是每个业务包自己拼。
+- 业务包、平台包、站点包到底应该怎么接入，才算遵守约定而不是绕过约定。
+
+本文把这条主线直接固定下来。
+
+## 2. 设计哲学
+
+### 2.1 `pz` 只承载稳定合同
+
+`pz` 的职责是：
+
+- 定义最小子包发现协议。
+- 编译 `RuntimePlan`、`SettingsSnapshot`、`ExtensionRegistry`。
+- 定义 `host.builder`、`settings.provider`、lifecycle、middleware、resource、CLI 等稳定合同。
+- 定义 `infra.provider`，用于把 concrete infra owner app 的 settings 编译进 typed `InfraContext`。
+
+`pz` 不做这些事：
+
+- 不直接承载官方业务实现。
+- 不直接承载 `admin` / `seo` / `auth` / 站点壳 / 宿主页面装配。
+- 不为单个业务场景加临时入口。
+
+也就是说，`pz` 只回答“系统支持什么正式扩展点”，不回答“这些扩展点由谁来具体消费和装配”。
+
+### 2.2 `pz_contrib` 是官方约定层
+
+`pz_contrib` 不是第二基础层，也不是运行时 namespace；它是官方最小子包源码容器。但它承担一件非常关键的事：
+
+- 在 `pz` 已有稳定合同之上，给出官方通用能力的正式实现。
+- 把一些跨业务、跨仓都会用到的约定收敛成统一消费点。
+- 让其他子包只需“声明并接入”，而不是重复发明装配方式。
+
+因此，正式主线是：
+
+1. `pz` 定义扩展点与编译协议。
+2. `pz_contrib` 按这些扩展点提供官方实现和集中消费逻辑。
+3. 其他最小子包遵守这些约定，通过 `apps.py` 声明 provider / panel / menu / settings provider / lifecycle。
+4. 运行时统一从 registry 与 `RuntimePlan` 消费，而不是宿主手工挂载。
+
+这里还要补一条边界，避免把“官方高频能力”误解成“都应进入 `contrib`”：
+
+- `pz_contrib` 负责的是官方通用能力的正式实现与集中消费。
+- 某个最小子包如果本质上是公开页面 owner runtime、站点 owner runtime 或其它高内聚 owner runtime，不因“重要”或“高频”自动进入 `contrib`。
+- 这类子包的长期做法应是：协议进入 `pz` 的正式编译主链，runtime 继续留在自己的 owner 包内。
+- 页面中心是当前明确样例：页面装配与 SEO provider 协议通过 core 的“子包正式协议注册机制”进入 `pz`，但公开页面 owner runtime 继续整体留在 `pz_page_center`，不因为协议进入 core 就拆散到 `contrib`。
+
+### 2.3 其他子包只做“按约定提供”
+
+业务包、平台包、站点包的默认职责不是改 host，也不是改 core，而是：
+
+- 在自己的 `apps.py` 中声明结构化扩展对象。
+- 在自己的模块中提供实际 provider / router / middleware / settings patch 实现。
+- 把实现注册到既定 kind，对应的消费方再统一装配。
+
+这意味着：
+
+- `auth` 相关路由策略不该在宿主里手工判断，而应声明 `auth.route_policy_provider`。
+- 页面 SEO 不该在每个 app 里自己拼 middleware，而应声明 `seo.provider` / `seo.sitemap_provider`。
+- 后台页面不该在宿主里 `include_router()`，而应声明 `admin.panel` / `admin.menu`。
+- 动态 settings 补丁不该再开第二套 loader，而应声明 `settings.provider`。
+
+### 2.4 Provider 的对象纪律
+
+provider 是实现正式合同的对象，不是随处调用的函数集合。
+
+固定规则：
+
+- provider 必须有稳定输入 context 和结构化返回值。
+- provider 必须幂等、可重复调用，不直接改写全局状态。
+- provider 不直接启动长期运行资源；需要资源时通过 owner runtime 暴露的 facade/capability 获取。
+- provider 实现模块可以私有，但声明必须通过 `apps.py` / `extensions()` / 正式 spec 进入编译主链。
+- consumer / assembler 负责 provider 排序、冲突裁决、合并结果、诊断输出与运行期 facade 暴露。
+- 不允许让每个 provider 自己决定全局装配结果。
+
+更完整的对象边界见 [`25-面向对象开发规范`](./25-面向对象开发规范.md)。
+
+## 3. 正式责任分工
+
+### 3.1 `pz` 基础层负责什么
+
+正式来源：
+
+- [`14-分层与扩展规范`](./14-分层与扩展规范.md)
+- [`16-扩展点正式协议清单`](./16-扩展点正式协议清单.md)
+- [`pz_core/runtime/plan.py`](../../runtime/plan.py)
+- [`pz_core/runtime/settings.py`](../../runtime/settings.py)
+
+基础层的正式职责是：
+
+- 编译 app registry、extension registry、event registry。
+- 将 `settings.provider` 编译成 `plan.settings_providers`。
+- 在 settings 装配阶段统一调用 `provider.provide(ctx)`，并做优先级与冲突校验。
+
+所以基础层只持有“协议”和“编译”，不持有高层能力的具体消费实现。
+
+### 3.2 `pz_contrib` 负责什么
+
+`pz_contrib` 中的各最小子包负责把高频正式能力收成统一消费面：
+
+- host / infra owner 持有官方 `host.builder`、infra provider、通用 infra middlewares、resources、migrations 等能力。
+- admin owner 集中消费 `admin.panel` / `admin.menu`，统一做后台 panel 校验、菜单树装配、扩展健康检查。
+- auth owner 集中消费 `auth.control_plane_provider` / `auth.route_policy_provider`，统一形成认证控制面与路由策略。
+- SEO owner 集中消费 `seo.provider` / `seo.sitemap_provider`，统一形成 SEO provider chain 与 sitemap provider chain。
+- settings runtime owner 通过正式 `settings.provider` 主链提供运行时治理实现。
+- shared site UI owner 提供共享站点 UI 壳与正式首帧稳定约定。
+
+这些都属于“官方约定层”，不是宿主的职责，也不应该反向塞回 `pz`。
+
+但这里的“高频正式能力”有一个明确边界：
+
+- 如果某个能力的本质是“集中消费别人的 provider / panel / menu / patch”，那么它适合由 `contrib` owner 收口。
+- 如果某个能力的本质是“自己就是公开运行时 owner，并且拥有页面身份、路由身份、治理身份或站点主链真相”，那么它不应仅因为高频就迁入 `contrib`。
+
+公开页面中心 owner runtime 属于后一类：
+
+- 它不是单纯的 provider consumer。
+- 它拥有公开页面身份真相、canonical / hreflang / sitemap / route alias / HubResolver 等治理输出。
+- 因此当前正式分层应是：协议进 core，runtime 留 `pz_page_center`。
+
+### 3.2.1 共享首帧稳定责任
+
+首屏展示与首帧稳定的统一 core 规范固定为 `23-首屏展示与首帧稳定规范.md`。
+
+本文只保留分层结论：
+
+- core 定义首帧稳定合同与反模式。
+- 官方共享 UI owner 负责落地共享组件、共享 bundle 与共享 runtime 主链。
+- 页面 owner 负责声明页面级状态、资源、heartbeat、轮询与首屏关键资产。
+
+具体共享 UI 实现细节、bundle 拆分、用户态启动链、cookie banner、语言推荐、help widget 与 preload 规则，归属官方共享 UI owner 文档，不在 core contrib 规范里并列维护。
+
+### 3.3 其他最小子包负责什么
+
+其他最小子包只负责：
+
+- 在自己的边界内实现 provider / router / middleware / settings patch。
+- 通过 `apps.py` 把这些实现声明成正式扩展。
+- 让 `contrib` 或 `pz` 的正式消费主链接住。
+
+它们不负责：
+
+- 在宿主里写手工挂载代码。
+- 给 `pz` 增加项目专用快捷路径。
+- 绕开 `ExtensionRegistry` / `RuntimePlan` 走第二套注册表。
+
+## 4. `contrib` 里已经固定下来的正式约定
+
+### 4.0 扩展点责任矩阵
+
+| 扩展点 kind | 合同 owner | 正式 consumer / assembler | 其他子包该提供什么 |
+| --- | --- | --- | --- |
+| `host.builder` | `pz` | official host owner | host builder 实现本身通常只由官方层提供 |
+| `infra.provider` | `pz` | `pz` 编译到 `RuntimePlan.infra` | concrete infra settings -> `InfraPatch` |
+| `admin.panel` | `pz` | official admin owner + official host owner | `/admin` 下的 router 或 router factory |
+| `admin.menu` | `pz` | official admin owner | 菜单节点、children、section、parent 关系 |
+| `seo.provider` | `pz` | official SEO owner | 页面 SEO provider |
+| `seo.sitemap_provider` | `pz` | official SEO owner | sitemap provider |
+| `auth.control_plane_provider` | `pz` | official auth owner | 某个控制面的认证 provider |
+| `auth.route_policy_provider` | `pz` | official auth owner | 路由认证裁决 provider |
+| `settings.provider` | `pz` | `pz.runtime.settings` | `provide(ctx) -> SettingsPatch` |
+| `lifecycle.contribution` | `pz` | `pz` lifecycle 主链 | startup / shutdown handler |
+
+这张表要表达的不是“谁声明 kind”，而是三层关系：
+
+- `pz` 持有稳定合同。
+- `contrib` 持有高频正式 consumer / assembler。
+- 其他子包只往这些约定好的 kind 里提供能力。
+
+### 4.1 Host / Infra 约定
+
+固定约定：
+
+- Web host 实现必须通过 `HostBuilderSpec(kind="host.builder")` 提供。
+- concrete infra owner 必须通过 `InfraProviderSpec(kind="infra.provider")` 把能力编译进 `RuntimePlan.infra`。
+- host 不从宿主硬编码 admin、SEO、auth 或业务模块；只消费 `RuntimePlan` 中已经编译好的 routers、middlewares、extensions。
+- 其他包不应自己发明第二个 host，也不应在宿主入口中手工拼总路由。
+
+具体官方 host / infra owner 的代码路径、settings 字段、启动降级语义与 middleware 归属，写在该 owner 子包文档里。
+
+### 4.2 Admin 约定
+
+固定约定：
+
+- 其它 app 要接入后台，正式方式只有声明 `admin.panel` / `admin.menu`。
+- admin owner 负责统一校验 panel namespace、菜单树结构、group 关系和扩展健康状态。
+- admin 全局侧边栏直接按子包 root 或工作台入口组织，不再要求先按“内容 / 增长 / 商业 / 平台 / 系统”这类业务域分组；`admin.menu.payload.children` 支持递归结构，底层 schema 不限制嵌套层数，但正式信息架构约定为 3 级：子包 root -> 功能分组 -> 页面入口。CMS、配置中心、任务中心等子包应在自己的 root 下声明功能分组，并在功能分组下声明页面入口；如果某个子包只有一个功能分组，admin shell 可以在 presentation 层视觉压平该分组，直接展示 root -> 页面入口，但不得改变 `admin.menu` 真相源和 sidebar 逻辑结构；更深层级属于子包页面内导航或工作流，不提升为全局侧边栏层级。
+- 为兼容历史声明，admin owner 可以把 root 下面直挂的页面入口归入“入口”功能分组以维持 3 级展示；这是迁移兼容，不是新增子包的正式声明方式。
+- host 只负责挂载已编译的 admin panel router，不负责理解每个业务 app 的后台页面细节。
+
+后台集成的真相源是扩展声明，不是宿主里的 `include_router()`；具体 admin shell、菜单、模板、健康页与 facade 写在 admin owner 文档里。
+
+### 4.3 Auth 约定
+
+固定约定：
+
+- 认证链自己的中间件由 auth owner 正式声明。
+- 控制面认证通过 `auth.control_plane_provider` 接入。
+- 路由认证默认通过 app settings 中的 `route_policy` 声明；只有超出配置表达力时才声明 `auth.route_policy_provider`。
+- auth owner 从 extension registry 加载 provider，并注册到自己的 runtime。
+
+未登录拦截、登录页跳转、`next` 回跳、默认保护策略、owner 覆盖、runtime override 暴露等具体行为，归属 auth owner 文档，不在 core contrib 规范里并列维护。
+
+### 4.4 SEO 约定
+
+固定约定：
+
+- 页面 SEO 内容由各 app 提供 `seo.provider`。
+- sitemap 内容由各 app 提供 `seo.sitemap_provider`。
+- SEO owner 统一把这些 provider 组装成 provider chain。
+- SEO middleware 只消费 provider chain，不拥有各业务页面的 SEO 真相。
+
+页面 app 只需要提供 provider，不需要自己再发明一套 SEO middleware 或中心注册逻辑；具体 metadata、robots、sitemap、LLM 文本与 admin/API surface 写在 SEO owner 文档里。
+
+补充边界：
+
+- `SEO owner` 与页面中心 owner 不是同一层职责。
+- `SEO owner` 负责 SEO provider chain、middleware、sitemap provider chain 等“SEO 输出消费面”。
+- 页面中心 owner 负责关键词页注册、公开页面身份、canonical route graph、HubResolver 等“公开页面 owner runtime”。
+- 因此即使公开页面中心与 SEO 都高度相关，也不应简单把公开页面 owner runtime 视为 `contrib` SEO consumer 的一个子实现。
+
+### 4.5 Settings patch 约定
+
+固定约定：
+
+- `settings.provider` 是正式 settings patch 接口。
+- provider 必须实现 `provide(ctx)`，返回 `SettingsPatch`。
+- `pz` 在 settings 装配时统一调用所有 provider，按 priority 合并，并对同优先级写同一路径做冲突报错。
+- settings runtime owner 只能通过这条正式主链提供 runtime override patch，不是第二套 settings loader。
+
+任何动态 settings 覆盖都应该进入 `settings.provider`，而不是重新做一个“运行时特供读取入口”；具体 runtime override 存储、治理、UI/API 与审计归属 settings runtime owner 文档。
+
+## 5. 其他最小子包应该如何接入
+
+### 5.1 统一入口：在 `apps.py` 里声明结构化扩展
+
+其他包的接入步骤固定为：
+
+1. 在自己的模块里实现 provider / router / middleware / settings provider。
+2. 在 `apps.py` 的 `extensions()` 或 `middlewares()` 中返回正式对象。
+3. 让 `pz` 编译进入 `RuntimePlan`，再由 `contrib` 统一消费。
+
+跨可选 runtime owner 的 provider 贡献应使用 `ProtocolExtensionSpec(optional=True)`，不得为了让协议注册存在而把 runtime owner 写进每个 provider 子包的 `requires_apps` 或 distribution 依赖。owner 未安装时贡献不生效；owner 安装后，required fields、import target 与 validator 仍按正式协议完整校验。
+
+正式对象通常包括：
+
+- `ExtensionSpec`
+- `SettingsProviderSpec`
+- `LifecycleContributionSpec`
+- `MiddlewareDecl`
+
+### 5.1.1 前端首帧稳定的业务接入规则
+
+业务接入摘要统一回到 `23-首屏展示与首帧稳定规范.md` 与官方共享 UI owner 文档；本文不再复制首屏关键图、临时 UI、测量后 reveal、SSR widget、页面心跳、cookie consent 等实现细则。
+
+本节只保留接入原则：
+
+- 页面事实由页面 owner 声明。
+- 共享组件由共享 UI owner 沉淀。
+- 页面 owner 发现跨 app 重复问题时，应上提到共享 UI owner，而不是复制到宿主或 core。
+
+### 5.2 典型接入模式
+
+平台包、站点包、业务包如果需要同时接入 settings patch、admin、auth、SEO 或 sitemap，仍然只按既定 kind 声明 provider / panel / menu / route policy。
+
+具体包级例子、代码路径和运行边界，必须写在对应子包自己的 README 或设计文档里；core 文档只保留扩展点合同，不维护平台包、站点包或业务包的实现清单。
+
+## 6. 开发时应该遵守的固定写法
+
+### 6.1 路由
+
+- app 自己的 URL 真相源固定在 `<pkg>.urls`
+- 简单 app 使用 `urls.py`
+- 复杂 app 使用 `urls/` 目录，但正式入口固定为 `urls/__init__.py`
+- 不在宿主主服务中手工拼业务路由
+- prefix 由上层统一挂载
+- 业务包只声明，不装配
+- admin 页面通过 `admin.panel` 接入，不绕过后台装配主链
+
+### 6.2 Settings
+
+- 运行时代码只允许 `import pz_settings_center.public as settings_center`
+- app 私有配置只读 `settings_center.settings.<app_id>.<field>`
+- 动态补丁只通过 `settings.provider`
+
+### 6.3 Public surface
+
+- 跨包依赖优先走对方 `public.py`
+- provider 的实现模块可以是私有模块，但注册动作必须通过 `apps.py`
+- `public.py` 优先暴露窄 facade、Protocol、命令对象、结果对象或 factory，不暴露内部 service、repository、adapter、SDK client、session、pool
+
+### 6.4 Middleware
+
+- 通用 middleware 用 `middlewares()` 返回 `MiddlewareDecl`
+- 不在宿主或 startup 里临时插入全局中间件
+- 某个 middleware 如果是为了消费特定 provider chain，应由对应 owner app 统一拥有
+
+### 6.5 对象边界
+
+- 有身份、生命周期、状态、不变量或可替换实现的能力，必须落成对象。
+- 纯转换、小范围校验、无状态格式化可以保持函数。
+- 运行时资源归明确 owner object；其它对象只能通过 facade/capability 使用。
+- 依赖通过构造参数、factory、context、`RuntimePlan` 或正式 registry 注入。
+- 不在 provider、middleware、route handler 内部临时 import 对方内部实现来绕过合同。
+
+## 7. 明确禁止的反模式
+
+- 在宿主里手工 `include_router()` 去补某个 app 的后台页面。
+- 在宿主或基础层里硬编码 import 某个业务包，再手工注册 provider。
+- 为了热更新或特定业务，再开第二套 settings loader / registry。
+- 在业务 app 里自己发明一套 SEO / auth / admin 装配中心。
+- 把 `apps.py`、`urls.py`、`urls/`、`settings.py` 当成跨包公开面直接依赖。
+- 遇到接入问题就把实现塞回 `pz` 基础层，而不是先看现有扩展点是否足够表达。
+- 把第三方 SDK client、浏览器 session、DB pool、queue connection 等外部资源对象直接暴露给跨包调用方。
+
+## 8. 判断一项新需求应该改哪里
+
+优先按下面顺序判断：
+
+1. 现有 app 内是否已经有对应扩展点可以接入。
+2. 如果是跨多个 app 都会复用的官方通用装配，是否应进入 `pz_contrib`。
+3. 只有在现有正式合同确实表达不了时，才回到 `pz` 基础层补稳定协议。
+
+补充判断：
+
+4. 如果新需求本质上要求某个子包拥有独立公开页面身份、路由真相、canonical/hreflang/sitemap 主链或其它 owner runtime 事实，先判断它是不是一个独立 owner runtime，而不是先默认迁入 `contrib`。
+
+简单判断：
+
+- “我要提供一个页面/菜单/后台入口”
+  - 先看 `admin.panel` / `admin.menu`
+- “我要给页面提供 SEO 数据”
+  - 先看 `seo.provider` / `seo.sitemap_provider`
+- “我要让某个关键词页/公开承接页 runtime 成为页面 owner”
+  - 先判断是否属于独立 owner runtime；像公开页面中心这类场景应走“协议进入 core，runtime 留在 owner 包”的模式
+- “我要给某个控制面提供认证”
+  - 先看 `auth.control_plane_provider`
+- “我要声明某组路由应该怎么认证”
+  - 先看 `auth.route_policy_provider`
+- “我要在运行时补 settings”
+  - 先看 `settings.provider`
+- “我要接入统一 host、资源、静态、middleware 装配”
+  - 先看官方 host / infra owner 的正式 host builder 与 lifecycle
+
+## 9. 先读哪些文档
+
+- [`14-分层与扩展规范`](./14-分层与扩展规范.md)
+- [`15-子包开发使用手册`](./15-子包开发使用手册.md)
+- [`16-扩展点正式协议清单`](./16-扩展点正式协议清单.md)
+- [`18-扩展点冲突裁决总表`](./18-扩展点冲突裁决总表.md)
+- [`25-面向对象开发规范`](./25-面向对象开发规范.md)
+
+如果要真正开发一个新子包，再继续读：
+
+- [`03-App最小子包规范`](./03-App最小子包规范.md)
+- [`04-Settings与配置规范`](./04-Settings与配置规范.md)
+- [`10-测试与契约规范`](./10-测试与契约规范.md)