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/00-pz/346/236/266/346/236/204/346/200/273/347/272/262.md

@@ -0,0 +1,240 @@
+# pz 架构总纲
+
+> settings 统一口径：Python 运行时代码只允许 `import pz_settings_center.public as settings_center`，并通过 `settings_center.settings.<app_id>.<field>` 读取；`settings.py` / `settings/` 只负责声明。
+> namespace 统一口径：每个正式最小子包都必须有稳定唯一的 `app.id`，settings namespace 必须与 `app.id` 一致；目录名、import 包名和 distribution 应围绕这个稳定身份收敛，但不强制统一技术前缀；没有叶子 app 身份的内部模块不得自定义 namespace。
+
+## 0. 架构公约
+
+- `pz` 是唯一正式基础包，也是唯一可独立启动的包。
+- 除 `pz` 外，系统里的正式运行单位只有最小子包。
+- `pz` 只负责稳定合同、发现、编译、组装与启动其他最小子包。
+- 官方能力、业务能力、本地 app 都必须走同一套最小子包装配模型。
+- 顶层源码组织根只用于 Git 与源码组织，不是正式架构层，也不进入运行时 namespace。
+- 正式 import 单位、正式安装单位、正式 app 身份、正式源码目录必须对齐到同一个最小子包。
+- `installed_apps` 的唯一正式语法是写目录名；目录名可以是最小子包名，也可以是容器目录名。
+- 运行时不硬编码 `apps`；默认项目配置声明 `apps` 作为扫描目录，框架只按当前项目 `installed_apps` 的实际条目展开。
+- 当项目配置声明 `apps` 时，`apps` 是项目级扫描目录；框架递归发现 `apps/` 下业务仓拥有的真实本地 app 与经过 manifest 校验的可见 binding。物理 `apps/.sources/` checkout 不直接贡献 app，也不形成第二条发现路径。
+- 同一 `app_id` 同时存在于项目源码扫描范围和当前 Python 环境已安装 distribution 时，项目源码优先；只有多个项目本地源码来源同时暴露同一 `app_id` 才构成冲突。
+- 每个最小子包必须只有一个稳定 `app_id` 真相源；新建子包默认让目录名、import 包名与 `app_id` 保持一致，distribution 使用对应的 Python 分发名。
+- 历史子包已发布的 `app_id` 不因目录治理口径变化而强制重命名；若确需重命名，必须作为显式迁移处理，不能在运行时引入第二套 alias namespace。
+
+## 1. 设计目标
+
+- 单一基础包：基础合同、发现协议、编译与通用启动协议统一落在 `pz`。
+- 最小子包平权：官方维护子包、业务子包、第三方子包在装配模型上完全一致。
+- 单一真相源：路由、settings、公开 surface、安装单位、环境选择、扩展声明、启动入口都只有一个正式来源。
+- 编译先于运行：Web、CLI、worker 启动前必须先形成统一 `RuntimePlan` / `SettingsSnapshot` / manifest。
+- 分层清晰：`pz` 不承载官方具体实现、业务逻辑、宿主路径细节或临时兼容方案。
+- 可安装优先：所有路径、入口与资源输出默认面向 wheel / pip 安装场景。
+- 可替换优先：跨 app 协作只通过 public surface、capability、facade、events、provider contract 或必要的 HTTP/CLI/task 协议完成。
+
+## 2. 设计原则
+
+- Django 风格：功能以 app 为最小装配单元。
+- 约定优先：目录名、import 包名、distribution、`app_id`、`installed_apps` 写法、环境命令按统一规则收敛。
+- 单一职责：每个核心构件只解决一个问题，不混入第二条主职责。
+- 依赖倒置：上层只依赖契约、facade、capability，不依赖具体实现模块。
+- 面向对象的设计贯穿整个设计周期。
+- 面向对象边界：凡是存在身份、生命周期、状态、不变量、依赖协作或跨模块合同的能力，必须用清晰对象边界表达。
+- 组合优先继承：默认通过组合、Protocol、provider、strategy、adapter 复用与替换；只有稳定 is-a 合同成立时才允许继承。
+- 状态归 owner：运行时状态只能由明确 owner 对象拥有和释放，不得散落在模块级全局变量、临时 dict 或 import-time 单例里。
+- 单一路径原则：一个问题只保留一种正式解决方案。
+- 不重复造轮子：不同层不得各自重写同类扫描、聚合、推导、注册逻辑。
+- 单一顺序源：`installed_apps` 是唯一 app 装载顺序来源。
+- 文件级资源覆盖：资源覆盖顺序只看 `installed_apps`，后出现 app 覆盖前者同相对路径。
+- 显式优于隐式：替换、覆盖、装配、资源输出路径必须显式声明。
+- 可选基础设施：数据库、Redis、metrics、tracing 等能力按需启用，不成为 base 运行前提。
+
+## 3. 分层模型
+
+正式架构统一分为五层。
+
+这些层必须落实为对象职责，而不是只落实为目录名。声明期合同使用 typed spec/model，编译裁决使用 compiler/resolver/builder，运行时资源由 runtime owner 管理，跨层消费只暴露 facade/capability/provider contract。具体对象边界以 [`25-面向对象开发规范`](./25-面向对象开发规范.md) 为准。
+
+1. 契约层
+   - schema
+   - settings model
+   - manifest
+   - capability interface
+   - provider contract
+
+2. 编译/聚合层
+   - app registry compiler
+   - route manifest compiler
+   - middleware manifest compiler
+   - resource manifest compiler
+   - infra snapshot compiler
+
+3. facade/capability 层
+   - context-bound facade
+   - capability registry
+   - provider registry
+
+4. 适配器层
+   - FastAPI/ASGI
+   - Aerich/Tortoise
+   - Redis client
+   - Prometheus exporter
+   - 其它具体 SDK adapter
+
+5. 入口层
+   - CLI
+   - Web app
+   - worker
+
+依赖方向固定为：
+
+- 入口层 -> facade/capability 层 -> 编译/聚合层 -> 契约层
+- 适配器层 -> 契约层 或 facade/capability 层
+- app 代码 -> public facade / capability contract
+
+禁止：
+
+- 入口层直接操作底层模块级单例。
+- app 直接 import `pz` 内部实现细节。
+- facade 反向依赖某个具体入口。
+- 同一能力在多层各自维护一份规则与状态。
+
+## 4. 最小子包关系
+
+- 官方维护最小子包与其它最小子包在装配层面完全一致。
+- 两者都只能通过 `installed_apps` 进入系统。
+- 两者都没有装配优先级特权。
+
+公开交互面分层：
+
+- 官方维护最小子包定义为官方 library app，允许其它 app 通过稳定 `public.py` 依赖。
+- 独立子包定义为 integration app，不允许其它 app 直接 import 其内部 Python 模块。
+- 跨 app 协作统一走 capability、facade、events、provider contract、CLI/task 协议或必要的 HTTP API。
+
+禁止：
+
+- 让独立子包变成可直接 import 的内部实现仓库。
+- 让任何容器目录在装配上拥有高于其它 app 的优先级。
+- 让 `pz` 点名某个具体 owner app。
+
+## 5. 唯一真相源
+
+以下对象必须各自成为唯一真相源：
+
+- `project_dir`：项目边界唯一真相源。
+- `pz.jsonc`：项目正式配置唯一真相源。
+- `<project_dir>/.env` 与 `<project_dir>/.env.{PZ_ENV}`：环境覆盖文件唯一入口集合。
+- `PZ_ENV`：环境选择唯一正式入口。
+- `installed_apps`：app 装载顺序唯一真相源。
+- `[app_replacements]`：app 替换关系唯一真相源。
+- `RouteManifest`：路由裁决唯一真相源。
+- `MiddlewareManifest`：中间件裁决唯一真相源。
+- `ResourceManifest`：资源合并结果唯一真相源。
+- `SettingsSnapshot`：运行期配置快照唯一真相源。
+- `RuntimePlan`：当前进程运行图唯一真相源。
+
+任何 helper、回退路径或局部门面都不得再生成第二套并行真相源。
+
+## 6. RuntimePlan
+
+正式架构中，必须存在且只存在一个组合根：
+
+- `RuntimePlan` 编译入口
+
+`RuntimePlan` 负责把下层正式产物一次性编译为当前进程的运行计划，至少包含：
+
+- `ProjectContext`
+- `SettingsSnapshot`
+- `AppRegistry`
+- `ResourceManifest`
+- `InfraContext`
+- `RouteManifest`
+- `MiddlewareManifest`
+- `CapabilityRegistry`
+
+正式要求：
+
+- Web、CLI、worker 都只能先构建 `RuntimePlan`，再消费它。
+- `RuntimePlan` 及其 activation 是基础层唯一组合根；具体对象图只能在这里或各 owner runtime 的局部组合根中构造。
+- 不允许某个入口跳过 `RuntimePlan`，单独拼 settings、app registry、resource manifest 或 infra context。
+- `RuntimePlan` 一旦生成，就作为当前进程唯一运行图输入。
+- `RuntimePlan` 产物必须视为不可变快照；后续阶段只能消费，不得原地改写。
+- `lifespan/startup/shutdown` 只允许激活或关闭 `RuntimePlan` 中已经编译好的 capability。
+- `CapabilityRegistry` 只作为运行图内部对象存在，不提升为 app 稳定公共依赖面。
+
+禁止：
+
+- Web 入口自己再扫一遍 apps。
+- worker 入口自己再推一遍 infra config。
+- CLI 命令自己再定位一遍 resources/migrations。
+- bootstrap/lifespan 再补 route、middleware、settings 稳定字段。
+
+## 7. 编译阶段与执行阶段
+
+正式架构统一分为两个阶段。
+
+编译阶段负责：
+
+- 读取配置。
+- 解析 app。
+- 编译 manifest。
+- 编译 typed snapshot。
+- 生成 `RuntimePlan`。
+
+执行阶段负责：
+
+- 挂载 route。
+- 初始化 provider/client。
+- 创建 facade/capability 实例。
+- 启动 Web/CLI/worker。
+- 执行 shutdown/cleanup。
+
+正式要求：
+
+- 编译阶段负责裁决与产出，不负责启动任何运行时副作用。
+- 执行阶段只消费编译结果，不再重新裁决规则。
+- 冲突检测、替换关系、顺序决定、路径决定、enabled/disabled 判定，全部必须在编译阶段完成。
+- DB/Redis client 初始化、logger handler 注册、worker loop 启动、route mutation，只允许发生在执行阶段。
+
+禁止：
+
+- 在编译阶段初始化 DB/Redis/metrics/exporter。
+- 在执行阶段重新扫描 installed apps、重新推导 settings、重新生成 manifest。
+- 在 `startup()`、`lifespan`、middleware 构造期重新做冲突裁决。
+- 在 adapter 层重新实现一套编译规则。
+
+## 8. 运行边界
+
+- 包目录必须视为只读。
+- 合并产物统一写入外部 `cache_dir` / `runtime_dir`。
+- 运行期不得假设当前工作目录就是项目根目录。
+- 宿主启动统一走 `pz run = pz run develop = pz run dev`、`pz run test`、`pz run product`。
+- `pz` 基础层冻结后，官方能力具体实现默认进入 `pz_contrib/` 或其它官方最小子包。
+
+## 9. 稳定公共契约
+
+稳定公共契约包括：
+
+- `pz` CLI 入口语义。
+- `pz` 正式 Python API。
+- `pz.jsonc` / `pz.{PZ_ENV}.jsonc` 配置结构。
+- app 最小协议。
+- `installed_apps` / app registry / migrations / resources 的正式约定。
+- 官方声明为 `public.py`、capability contract、provider contract 的稳定边界。
+
+默认不属于稳定公共契约的内容：
+
+- `pz` 内部 helper 的具体文件布局。
+- 官方维护最小子包/独立子包的内部 service / runtime / module 目录。
+- 未在文档中声明为 stable 的私有模块 import path。
+
+要求：
+
+- 文档必须明确哪些入口是 stable，哪些不属于稳定公共边界。
+- 内部目录可以重构，但不得破坏已声明的 stable 契约。
+
+## 10. 禁止事项
+
+- 新增第二套 core、第二套主 CLI、第二套宿主基础壳。
+- 在 `pz` 中新增业务逻辑、宿主逻辑或 owner-specific 共享运行时逻辑。
+- 通过集合层 namespace 表达正式运行时身份。
+- 在 app 运行时代码中直接读取 `os.environ`、包内默认配置模板或项目 `.env*`。
+- 在 import 阶段创建 DB/Redis/client/exporter、注册全局 handler 或读取项目配置。
+- 为单个 app、单个宿主或单个路径加入硬编码特判。
+- 长期保留两套入口、两套协议、两套实现。

pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/01-/347/233/256/345/275/225/344/270/216/345/210/206/345/261/202/350/247/204/350/214/203.md

@@ -0,0 +1,216 @@
+# 目录与分层规范
+
+本文档定义 `pz` 正式目录结构、源码组织边界与分层职责。迁移步骤、执行清单和历史路径映射不属于本文范围。
+
+## 1. 正式原则
+
+- 同一类职责只允许落在一个目录层。
+- `pz` 只保留基础层协议、发现、编译、组装与启动。
+- `runtime / assembly / core / infra` 是 `pz` 基础层内部职责分层，不是 app namespace。
+- 除 `pz` 外，其它正式能力都必须落成独立最小子包。
+- 每个最小子包必须有稳定唯一的 `app_id`；新建子包默认让目录名、import 包名与 `app_id` 对齐，历史已发布子包以稳定值为准。
+- 外层目录只用于 Git 与源码组织，不表达正式运行时 namespace。
+- 所有公开入口都只通过正式 facade、capability、provider contract、`public.py` 或 CLI/task/API 协议暴露。
+
+## 2. 唯一完整目录结构
+
+完整目录结构只在本文档定义一次，其它文档只允许引用，不再重复展开目录树。
+
+```text
+workspace/
+  pz/  (最小基础仓 Git checkout，不是运行时 namespace)
+    pyproject.toml  (`pz-cli` 唯一 distribution 真相源)
+    uv.lock
+    pz_core/
+      pz_core/
+        __init__.py
+        __main__.py
+        app.py
+        settings.py
+        runtime/
+        assembly/
+        core/
+        infra/
+      tests/
+    pz_contrib/  (同 wheel 内的官方基础子包源码容器；不进入 import namespace)
+      pz_foundation/
+      pz_settings_center/
+  pz_apps/  (其余最小子包仓 Git checkout；不进入 import namespace)
+      <app_id>/
+        pyproject.toml
+        <app_id>/
+          __init__.py
+          public.py
+          apps.py
+          settings.py
+```
+
+边界：
+
+- `pz/` 是唯一正式基础包，也是唯一可独立启动的包。
+- 每个正式能力都必须落成独立最小子包 `<app_id>/`。
+- `pz/` 与 `pz_apps/` 两个顶层源码组织根只承担 Git 与 ownership 分组职责。
+- `pz_contrib/` 只表示框架仓内的官方维护子包容器，不表示特殊运行时层。
+- 不保留 `plugins`、`platform namespace`、`site_runtime namespace` 作为正式目录概念。
+
+## 3. `pz_core` 包根
+
+`pz/pz_core/pz_core/` 包根只保留公开入口与基础声明：
+
+- `__init__.py`
+- `__main__.py`
+- `app.py`
+- `settings.py`
+- `runtime/`
+- `assembly/`
+- `core/`
+- `infra/`
+
+约束：
+
+- `__init__.py` 只暴露公开 Python API。
+- `__main__.py` 只负责 CLI 入口调用。
+- `app.py` 只暴露 ASGI/Python 入口。
+- `settings.py` / `settings/` 只保留 schema / normalize / 默认值声明职责；运行时读取统一走 settings surface owner。
+- 包根不得承载官方具体实现、业务逻辑、宿主路径细节或临时兼容方案。
+
+## 4. `runtime/`
+
+`runtime/` 只放执行期运行图与入口胶水。
+
+允许放入：
+
+- `ProjectContext`、`RuntimePlan` 的运行时持有与访问入口。
+- context-bound registry / facade / provider binding 激活逻辑。
+- request/app-state/runtime helper。
+- Web / CLI / worker 的执行期入口 glue。
+- `startup()` / `shutdown()` 的执行器。
+- health / metrics / debug surface 的执行期暴露。
+- 把已编译 `RouteManifest` / `MiddlewareManifest` / `ResourceManifest` 应用到宿主框架的 adapter glue。
+
+禁止放入：
+
+- settings 读取器、`.env` 发现器、project root 推断器。
+- app 扫描、资源扫描、迁移扫描、middleware 扫描。
+- route / middleware / resource / infra 的编译规则。
+- 具体 middleware 类。
+- 具体 provider/client/SDK 实现。
+- import-time 单例、全局 setter、全局 manager。
+
+## 5. `assembly/`
+
+`assembly/` 只放编译、裁决与诊断编排。
+
+允许放入：
+
+- settings compiler。
+- app registry compiler。
+- route / middleware / resource / infra manifest compiler。
+- project/app/resource 路径归一化逻辑。
+- 冲突检测、替换裁决、顺序裁决。
+- 资源 merge 计划、迁移归属计划、诊断产物编译。
+
+禁止放入：
+
+- FastAPI/ASGI 对象创建与 mutation。
+- DB/Redis/mail/storage client 初始化。
+- logger/exporter/worker loop 启动。
+- 具体 middleware 类与具体 provider 实现。
+- request helper、app.state helper、thread-local/runtime-local 状态。
+- 在编译阶段触发文件写入、网络 I/O、依赖探测。
+
+## 6. `core/`
+
+`core/` 只放纯 contract 与纯规则。
+
+允许放入：
+
+- app protocol、declaration model、dependency rule。
+- route / middleware / resource 的声明模型与纯校验规则。
+- error code、error envelope、health result model。
+- request correlation id / trace correlation model 的纯协议定义。
+- capability contract、provider contract 的纯接口定义。
+- 不依赖具体 app / 具体 provider / 具体目录真相源的纯规则。
+
+禁止放入：
+
+- 具体 app 清单、具体官方 app import path 特判。
+- FastAPI/Request/app.state/CLI 运行时 helper。
+- `startup()` / `shutdown()` / lifespan 副作用。
+- 具体 middleware 类、模板运行时、i18n 运行时、静态资源服务。
+- 具体 DB/Redis/storage/mail/observability provider 实现。
+- 任何临时实现或历史兼容桥接。
+
+## 7. `infra/`
+
+`infra/` 只保留可选基础设施的薄绑定层与 contract。
+
+允许放入：
+
+- typed infra settings / typed context / capability state model。
+- provider contract / adapter protocol / binder interface。
+- capability 装配所需的最小 runtime binder。
+- 最小 noop / null / disabled 语义实现。
+- 不带业务语义的 resilience 工具。
+
+禁止放入：
+
+- 共享 middleware 实现目录。
+- i18n / jinja / site runtime / template helper。
+- 平台 app 专属 registry、provider 注册表、模块配置逻辑。
+- 具体第三方 SDK / 云服务 / exporter / bot handler 实现。
+- import-time 默认 client、默认 registry、默认 logger。
+- 官方 app 或独立子包的业务逻辑。
+
+## 8. 一票否决规则
+
+某个文件只要满足以下任一条件，就不得进入 `core` 或 `infra`：
+
+- 需要知道某个具体官方 app / 独立子包的名字。
+- 需要直接 import 具体 provider / 具体 middleware 类。
+- 需要在导入期或编译期产生运行时副作用。
+- 需要依赖 repo-root、`cwd` 或历史目录布局才能工作。
+- 需要通过临时回退补正式主链缺口。
+
+## 9. 最小子包
+
+最小子包是系统里除 `pz` 外唯一正式能力单位。
+
+源码落位固定为：
+
+- 每个正式能力都必须落在自己的包根：`<app_id>/`。
+- 包根内部的正式 Python 包目录同样必须叫 `<app_id>/`。
+- `<app_id>/` 可以放在任意顶层源码组织根下，但外层目录不参与运行时命名。
+- `installed_apps` 可以直接声明某个 `<app_id>/`，也可以声明容器目录；框架负责递归发现其中嵌套的最小子包。
+
+边界：
+
+- `pz/` 不承载任何业务能力或官方能力的具体实现。
+- 任何能力型代码都必须进入某个最小子包，而不是挂在集合层目录名下。
+- 各最小子包默认不通过内部 Python import 直接协作，只通过 facade / capability / events / provider contract / CLI/task/API 等稳定交互面协作。
+
+## 10. 非运行时目录
+
+不进入正式运行主链：
+
+- `.runtime/`
+- `dist/`
+- `.venv/`
+- `logs/`
+- `docs/`
+
+要求：
+
+- `.runtime/` 只作为运行时输出目录，不纳入包分发语义。
+- `dist/` 只作为构建产物目录。
+- `logs/` 不得作为源码默认依赖目录。
+- `docs/` 只承载文档，不承载运行时发现、配置、资源或装配事实。
+
+## 11. 验收标准
+
+- 包根只剩公开入口与基础声明。
+- `pz / <app_id>` 与 `runtime / assembly / core / infra` 职责边界稳定。
+- 不存在 repo-root / `cwd` / `app/*` 作为正式路径心智。
+- base-only wheel 安装可以正常执行 `pz --help`。
+- 可选依赖缺失不会在 import-time 打崩基础命令。
+- 正式 tests 能按分层验证入口、配置、资源、可选 infra、官方 app 装配。