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/archive//344/270/255/351/227/264/346/200/201/13-/344/270/200/346/254/241/346/200/247/345/256/236/346/226/275/346/270/205/345/215/225.md

@@ -0,0 +1,387 @@
+# 一次性实施清单
+
+> 历史说明：本文中的 `legacy_core` 只用于标记旧主链、旧 helper 与迁移清退对象；当前正式基础包统一为 `pz`。
+
+> settings 统一口径：Python 运行时代码只允许 `import pz_settings_center.public as settings_center`，并通过 `settings_center.settings.<app_id>.<field>` 读取；`settings.py` / `settings/` 只负责声明；`legacy_core.settings`、`get_settings()`、`ensure_full_settings()` 都只属于历史清退对象。
+
+## 1. 实施目标
+
+本次重构按一次到位推进，不再采用“先 phase 1、再 phase 2”的交付策略。
+
+但一次到位不等于无顺序开发，仍需要明确内部执行顺序与完成门禁。
+
+总体要求：
+
+- 以全新设计为目标，运行时只保留新主链
+- 单次重构完成后，应直接达到标准 `pip` 包化目标
+- 实施过程中仍应保留可验证的回滚面
+- 不引入新的长期并行主链
+- 子包改造主要依赖适配改造文档
+- 新版包的开发、依赖锁定、构建与命令执行统一采用 `uv` 工具链
+
+## 2. 一次性实施的内部顺序
+
+虽然不分阶段发布，但固定按以下技术顺序完成，以减少返工。
+
+补充总约束：
+
+- 必须先固化下层契约，再接上层入口
+- 不允许上层入口先落代码，再倒逼下层临时补接口
+- 不允许在不同阶段重复实现同类编译器/聚合器来临时打通链路
+
+### 2.1 包与配置边界收口
+
+必须完成：
+
+- 建立 `project_dir`
+- 建立 `pz.jsonc`
+- 引入标准 `console_scripts`
+- 收敛 settings 解析入口
+- 建立唯一 `RuntimePlan` 编译入口
+
+完成标志：
+
+- 新配置解析器
+- `pz` 标准入口
+- `RuntimePlan` 作为唯一组合根落地
+- `pyproject.toml` 的 `project.scripts`、extras 名称、对外元数据收口到标准 pip 包语义
+- `pz env sync` / `pz ...` / `uv build` / `uv.lock` 成为新版包的正式开发与构建路径
+- `ROOT_DIR/.env` / `cwd` 驱动的历史配置发现被 project_dir 驱动模型替换
+- `create_app/create_host_app` 从全局 settings 回落模式收口为显式上下文 API
+- config schema 的正式字段、旧字段折叠规则与删除边界成文
+- `project_dir`、`pz.jsonc`、`<project_dir>/.env`、`installed_apps`、`[app_replacements]` 这些唯一真相源先固定
+- core/app 的公共导出面收口为 `pz`、`pz.app`、`<app>.public`
+- `pz check` 与 `CheckReport` 确立为系统检查唯一正式入口与唯一正式输出模型
+- 生命周期状态机与错误编码体系先于入口层固定
+- 官方最小子包 `pz_*` 的 wheel / package / import 契约成文并具备 contract test
+- 旧 `legacy_core.settings` helper、`ensure_full_settings()`、`get_settings()` 等历史读取入口的清退策略成文，并明确统一收口到 `settings_center.settings`
+
+### 2.2 运行目录与资源输出迁移
+
+必须完成：
+
+- 引入 `cache_dir/runtime_dir/asset_dir`
+- 资源合并迁出包目录
+- 迁移聚合迁出包目录
+- 上传与本地存储纳入 `asset_dir`
+
+完成标志：
+
+- 新路径服务
+- 新资源输出目录
+- 锁文件目录重定向
+- asset build/bundle/minify 从 repo-root `legacy_core/merged/static` 迁到 `cache_dir`
+- bootstrap/resources 不再直接操作模块级资源/i18n/config 单例
+- mounts/static/uploads 绑定切到当前 project settings/asset_dir
+- 资源 merge 输出切到原子切换模式，并补 manifest/回滚语义
+- `<cache_dir>/resources/manifest.json` 落为资源结果唯一真相源
+- 资源诊断、debug、preflight 全部改为读取同一份 manifest
+- `file_service` / storage public URL 语义收口：无公共访问入口时不再输出宿主机路径、相对路径或 `file://`
+
+### 2.3 可选基础设施化
+
+必须完成：
+
+- DB 可选
+- Redis 可选
+- readiness 只探测启用项
+- `legacy_core` base 安装不强依赖 DB/Redis 驱动
+
+完成标志：
+
+- `database.enabled`
+- `redis.enabled`
+- extras 重新分层
+- CLI 诊断信息完善
+- `pyproject.toml` 与实际 extras/console script 口径一致
+- metrics/tracing 的 label 规范与低侵入策略明确
+- `InfraSettings` / `InfraContext` 成为基础设施能力唯一 typed snapshot
+- Web `startup()` / `setup_infra()` / `/ready` 全部退出 schema 生成、自动建表、迁移修补路径，DDL 只保留显式 `pz db ...`
+
+### 2.4 平台 app 与跨 app 依赖收口
+
+必须完成：
+
+- shared site UI owner
+- settings runtime owner
+- task dispatch / worker owner
+
+这些平台级 app 形成正式公共门面；具体包名与迁移清单归 owning 子包文档维护。
+
+完成标志：
+
+- 清理 core 对具体官方维护最小子包的直接 import
+- 清理不同 `<app_id>` 最小子包之间的内部实现 import
+- 引入显式 `public.py` / facade / capability contract / events 协作方式
+- shared site UI owner、settings runtime owner、task dispatch owner 的默认单例与 facade 边界统一收口
+- CoreSettings 默认 installed_apps/installed_apps_extension 收缩为最小集合
+- app 替换场景下的数据/迁移/storage owner 归属规则完成收口
+- capability registry / provider contract 收口完成
+- 上层 app 只依赖 facade/capability/contract，不再直接依赖具体实现模块
+- `required_protocols` 只依赖 capability contract 名称，不再接受实现模块路径
+
+### 2.5 worker 与入口体系收口
+
+必须完成：
+
+- worker 入口显式化
+- 统一 web/CLI/worker 的配置解析
+- 删除 in-process worker 正式路径
+
+完成标志：
+
+- worker CLI 规范
+- supervisor/lock/runtime 规范
+- 入口层与配置层职责切分完成
+- `init` / 历史 `git_plugins` 迁移命令 / preflight 资产构建都不再围绕 vendored repo 心智
+- `db` / `init` / app CLI 全部切到标准包化心智，不再围绕 wrapper 与 merged workspace
+- entrypoint 只负责组装上下文，不再重复实现 settings/app/resource/infra 规则
+- app CLI 命令发现只保留 `cli/` 目录约定，不再保留第二套动态命令注册链
+- system checks 只保留 `pz check` 入口，不再保留 startup/debug/preflight 自定义检查主链
+- Web / CLI / worker 共用同一套生命周期状态机与错误编码
+- 旧 `run` / `git_plugins` / `init` 的直接删除清单与替代入口成文
+- app `startup()` 内注册 ports、订阅事件、拉起 in-process worker 的路径全部退出正式模型
+- `db` CLI 工作空间切到 `ProjectContext/cache_dir` 模型，不再写 repo-root `merged`
+- 启动诊断输出收口为稳定 `code/stage/owner/action` 结构
+- asset build / 图片优化 / bundle-minify 从 Web startup 正式退出，改为显式编译或显式 preflight 流程
+- `module_config_service` / `redirect_rules_cache` 收口为项目级 runtime cache，具备 owner、reset、invalidate 与 cleanup 语义
+- worker register / heartbeat / pull / ack 热路径不再依赖全局 `settings` 修补；`wid/token` / TTL / re-register 语义形成正式协议
+- worker supervisor 的 lock/state/temp 文件统一迁入 `runtime_dir`，不再使用系统级临时目录
+
+### 2.6 测试矩阵与稳定化
+
+必须完成：
+
+- wheel 安装测试
+- SQLite/MySQL/PostgreSQL 契约测试
+- app 替换测试
+- 单例 reset / 多次启动测试
+- 升级与回滚验证
+- base-only 轻量命令验证
+
+完成标志：
+
+- CI 分层矩阵
+- 回归门禁
+- 旧文档清理清单
+
+### 2.7 首批代码重构切入顺序
+
+真正进入代码重构时，首批切入顺序固定为以下主链断点，不允许绕开。
+
+唯一原则：
+
+- 先切 `core` 主链
+- 再切 app 层实现，包括现有官方维护最小子包 与历史 `plugins/*` 路径
+- 最后清理脚本层与残余旧路径
+
+排序依据：
+
+- 只要 `core` 还在直接依赖旧 `infra` 实现，后面所有 app 改造都会继续被旧主链拖回去
+- 先改 app 层现状目录，只会产生更多临时 adapter 和旧路径胶水
+
+正式禁止：
+
+- 先从某个 feature app 开刀试图“局部证明新架构”
+- 先在历史独立子包路径里打补丁绕过 `setup_infra()` / `db_manager` / `redis_manager`
+- 在 `core` 主链未切断前，提前大面积迁 app 代码
+
+首批代码重构完成后，至少要达成以下结果：
+
+- `core` 不再把旧 `infra` 当作默认运行主链
+- `RuntimePlan -> InfraContext -> CapabilityRegistry` 进入正式启动主链
+- Web / CLI / worker 的主入口不再依赖 `setup_infra()` 这种旧总管函数
+- middleware、resources、storage、health、observability 都开始走新的正式边界
+
+#### 2.7.1 首批关键模块
+
+第一优先级：
+
+- `legacy_core/assembly/settings/compiler.py`
+- `legacy_core/runtime/plan.py`
+- `legacy_core/runtime/http/app.py`
+
+排序依据：
+
+- 这三处直接决定 settings 真相源、`RuntimePlan` 编译链、Web 入口是否真正只消费编译结果
+- 只要它们不改，`RuntimePlan`、`CapabilityRegistry`、`Facade` 仍可能被入口层绕开
+
+第二优先级：
+
+- `legacy_core/assembly/resources/compiler.py`
+- `legacy_core/runtime/facades/storage.py`
+- `legacy_core/runtime/health/service.py`
+
+排序依据：
+
+- 它们分别代表资源主链、storage 主链、health/readiness 主链
+- 它们最容易把新边界重新拖回旧 helper/service/manager
+
+第三优先级：
+
+- `legacy_core/assembly/apps/compiler.py`
+- `legacy_core/assembly/project/compiler.py`
+- `legacy_core/runtime/cli/db.py`
+- `legacy_core/runtime/lifecycle/manager.py`
+
+排序依据：
+
+- 这些文件需要承接新的 typed snapshot / registry / facade 结构
+- 但它们应在第一、二优先级断口明确后再调整
+
+#### 2.7.2 第一批必须先切的三个断点
+
+断点一：`assembly/settings/compiler.py`
+
+- 遗留问题：仍可能保留历史字段折叠、默认 `installed_apps`、派生字段二次补写这类旧主链心智
+- 首批完成标志：默认 `installed_apps` 收口为最小集合或空集合；所有派生字段只在单一 compiler 阶段产出；不再为入口层保留第二套补写空间
+- 不允许：旧默认链与新 manifest 配置并存
+
+断点二：`runtime/http/app.py`
+
+- 遗留问题：Web 入口最容易重新拼 settings/app/resource/infra，或者在 startup/lifespan 中补第二套裁决
+- 首批完成标志：HTTP 入口只消费已编译好的 `RuntimePlan`；不再在 startup/lifespan 内部补第二套 settings/route/infra 裁决；路由/中间件注册顺序完全来自编译产物
+- 不允许：把旧总管函数改名后继续保留；把更多编译逻辑塞进 startup/lifespan 作为临时实现
+
+断点三：`runtime/plan.py`
+
+- 遗留问题：一旦 `RuntimePlan` 不是唯一组合根，后续入口与 facade 就会各自绕开它重建状态
+- 首批完成标志：`RuntimePlan` 固定承载 `ProjectContext`、`SettingsSnapshot`、`AppRegistry`、`ResourceManifest`、`InfraContext`、`RouteManifest`、`MiddlewareManifest`、`CapabilityRegistry` 等正式产物；入口层不再跳过它直接拼装运行图
+- 资源域补充完成标志：资源作者配置统一走 `resources.items`；运行期统一消费 `ResourceManifest.items`；不再保留固定输出字段或目录名映射表
+
+#### 2.7.2A 旧主链专项清理
+
+在进入大规模目录迁移前，还必须明确清掉以下历史路径：
+
+- app import 短名自动补全、`legacy_core.<name>` 自动补前缀、package-level `app` 猜测
+- 重复 `app_id` 静默跳过
+- `init()` / `startup()` 失败后 warning 继续
+- `legacy_core.settings` 的 env 回写、旧全局 `settings` 单例、`ensure_full_settings()` 补挂 namespace
+- `get_settings()` 这类历史 flatten-export 读取入口
+- `clean_and_reorder_routes()` 与 legacy extension adapter
+
+这些专项不要求先把所有代码删光，但必须先把正式新主链与旧路径边界切开，避免迁移过程中继续把旧行为当主路径。
+
+#### 2.7.3 首批顺序
+
+首批顺序如下：
+
+1. 建立最小 `RuntimePlan` / `InfraContext` / `CapabilityRegistry` 正式主链
+2. 改 `assembly/settings/compiler.py`
+3. 改 `runtime/http/app.py`
+4. 改 `assembly/resources/compiler.py`
+5. 改 `runtime/facades/storage.py`
+6. 改 `runtime/health/service.py`
+7. 再改 `assembly/apps/compiler.py`、`assembly/project/compiler.py`、`runtime/cli/db.py`、`runtime/lifecycle/manager.py`
+8. 再开始切 app 层现状路径对 `legacy_core.infra.*` 的直接 import
+
+#### 2.7.4 首批完成后的验收标准
+
+以下条件同时满足，才算首批重构完成：
+
+- `runtime/http/app.py` 不再在入口层重建 settings/app/resource/infra 裁决
+- `runtime/plan.py` 成为唯一组合根，入口层不再绕开它
+- `assembly/settings/compiler.py` 不再为后续入口层保留第二套派生字段补写空间
+- `assembly/resources/compiler.py` 不再直接依赖旧 merge service
+- `runtime/facades/storage.py` 不再硬编码旧 storage adapter 路径
+- `runtime/health/service.py` 不再直接依赖旧 readiness 聚合器
+- Web / CLI / worker 的正式入口都能解释为“先编译 `RuntimePlan`，再执行”
+- 旧 `infra` 仍可作为内部实现残留一段时间，但已不再控制正式主链
+
+## 3. 一次性实施完成定义
+
+整体重构完成至少满足：
+
+1. 设计文档已更新
+2. 有对应自动化测试
+3. 有现状差距项被关闭
+4. 不再新增同类历史并行主链
+5. 有明确迁移说明
+6. 有发布与回滚说明
+7. 有残余风险说明
+8. 需要改造的子包都有明确适配清单
+
+## 4. 固定门禁
+
+整个一次性实施过程中，都应坚持以下门禁：
+
+- 不扩大 `public.py` / facade / capability contract 对外依赖面，除非文档先行
+- 不新增新的 import-time 全局副作用
+- 不新增新的 repo-root / cwd / vendored 路径依赖
+- 不以“先沿用旧路径”名义引入第二套长期真相源
+- 不在不同层重复实现同一类扫描、聚合、裁决逻辑
+- 不允许上层模块反向依赖下层具体实现细节
+- 不允许多个入口各自拼装运行图，必须统一走 `RuntimePlan`
+- 每关闭一条旧路径，都要补诊断与迁移提示
+- 不把 warning-only 的半初始化运行结果当作正式完成
+- 涉及数据/迁移归属变更时，必须同时提供升级和回滚说明
+
+## 4.1 最终红线清单
+
+进入代码重构与合并前，必须额外逐项核对以下红线：
+
+- 没有新增第二套配置/app/resource/infra 真相源
+- 没有把编译逻辑塞回 `startup()` / `lifespan` / adapter
+- 没有新增 import-time 全局单例、全局 setter 主链或隐藏回退
+- 没有新增 repo-root / `cwd` / `ROOT_DIR` 依赖
+- 没有让 core 重新依赖具体官方 app / 独立子包的内部模块
+- 没有允许 app 直接 import 其它 app 的内部模块
+- 没有让旧 middleware manager 逻辑继续进入正式主链
+- 没有出现第二套 system checks 入口或第二套 `CheckReport`
+- 没有让 CLI / Web / worker 的生命周期语义和错误编码分叉
+- 没有让 base 安装基础命令依赖可选驱动或重型 extras
+- 没有把 warning-only 结果带入正式运行态
+- 没有缺失升级说明、回滚说明、版本范围说明
+
+## 5. 发布门禁
+
+虽然设计上一次到位，但发布仍必须保持可控。
+
+发布前必须完成：
+
+- 在主分支合入前完成端到端验证
+- 发布包前完成：
+  - wheel 安装验证
+  - 非源码目录 smoke run
+  - 子包适配清单核对
+- `uv build` 产物与 `pip install` 安装链验证同时通过
+- 若涉及数据/迁移/目录边界切换，必须有一次性 cutover 与回滚步骤
+- 不引入 feature flag、隐藏开关或双路径长期并存来规避一次性实施
+
+补充门禁：
+
+- 发布说明必须显式列出：
+  - 支持的 Python 版本
+  - 支持的数据库范围
+  - 官方聚合 distribution 或分拆官方 wheel 的版本范围
+- 必须验证 base 安装下基础命令可运行：
+  - `pz --help`
+  - `pz list`
+  - `pz check`
+
+## 6. 文档治理要求
+
+本次一次性实施，至少同步维护以下文档：
+
+- 设计规范
+- 迁移说明
+- 发布说明
+- 子包适配改造清单
+
+要求：
+
+- stable 文档、README、示例命令、CLI help 口径必须同步
+- 不允许出现“设计文档已经切换，但 README/help 仍在宣传旧路径”的状态
+- 重构完成后必须进入 core freeze / extension-first 治理
+- 后续 `pz` 相关增量需求默认进入官方扩展包，不再继续向 `legacy_core` 内核堆叠功能
+- 只有框架级公共契约、编译/运行边界、安全修复与缺陷修复，才允许继续修改 `legacy_core`
+
+## 7. 明确不接受的推进方式
+
+不接受：
+
+- 在旧路径上继续打补丁
+- 旧优先级与新显式机制并存
+- 让新旧两套 settings 长期并存
+- 让 wrapper/vendored 模式继续充当主运行路径
+- 以“后续再慢慢补”为理由提交半完成架构