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/03-App/346/234/200/345/260/217/345/255/220/345/214/205/350/247/204/350/214/203.md

@@ -0,0 +1,571 @@
+# App 最小子包规范
+
+> settings 单一路径口径：Python 运行时代码只允许 `import pz_settings_center.public as settings_center`，并通过 `settings_center.settings.<app_id>.<field>` 读取；`settings.py` / `settings/` 只负责声明，不再作为运行时读取入口。
+> 命名单一路径口径：每个正式最小子包必须有稳定唯一的 `app_id`，settings namespace 必须与 `app_id` 一致；新建子包默认让目录名、import 包名与 `app_id` 对齐，distribution 使用对应的 Python 分发名，但不强制特定技术前缀。运行时发现的唯一入口真相源是标准 `apps.py`，目录结构只作为组织与治理约束。
+
+## 1. 目标
+
+`pz` 的最小装配单元是 app。
+
+- `pz` 是唯一正式基础包，也是唯一可以独立启动的包
+- 其它最小子包统一作为 `pz` 的插件被发现和加载
+
+无论是官方维护最小子包、外部业务子包还是独立子包，均使用同一套结构约定。
+
+分类：
+
+- 官方维护最小子包
+  - 官方 `library app`
+  - 允许被其它 app 通过 `public.py` 依赖
+- 独立子包 app
+  - `integration app`
+  - 不允许被其它 app 直接 import
+  - 只允许通过稳定集成边界交互
+
+## 2. 标准目录要求
+
+完整项目目录结构以 `01-目录与分层规范.md` 为准。
+
+app 子包自身至少应具备以下组成：
+
+- `pyproject.toml`
+- app 包目录
+- `__init__.py`
+- `apps.py`
+- `public.py`
+- `auth/`
+- `configs/default.jsonc`
+- `configs/default.env`
+- `settings.py` 或 `settings/`
+- `urls.py` 或 `urls/`
+- `models.py`
+- `templates/`
+- `static/`
+- `locales/`
+- `pages/`
+- `migrations/<app_id>/`
+
+约束：
+- `apps.py` 是唯一正式 app 入口
+- `public.py`、`auth/`、`configs/default.jsonc`、`configs/default.env`、`settings.py` 或 `settings/`、`urls.py` 或 `urls/`、`models.py`、`templates/`、`static/`、`locales/`、`pages/`、`migrations/` 按能力需要出现
+- `configs/` 是正式 Python 子包，必须包含 `configs/__init__.py`；`configs/default.jsonc` 与 `configs/default.env` 必须随 wheel 一起分发
+- `pages/` 是页面声明目录，只放页面中心可编译的页面声明，不放 settings 默认值、secret、运行时逻辑或业务 provider 实现
+- `auth/` 推荐作为每个最小子包都预留的空包；普通场景保持为空，不作为第二套默认认证入口
+
+### 2.1 `pages/` 页面声明目录
+
+`pages/` 用于承载页面中心从业务 app 收集的正式页面声明。它是 app 资源的一类，不是第二套 settings，也不是第二套 app 入口。
+
+`pages/` 是按治理需求启用的声明目录，不是所有 Web 页面的必填登记册。普通功能页、用户态页面、轻量支持页优先使用 `<pkg>.urls` 声明显式路由，用 `templates/`、`static/`、`locales/` 和页面 controller 完成渲染；需要共享 shell、多语言页面状态时，通过 `page.profile_provider` / `PageProfile` 或 `pz_site_ui` 的 request page state 合同提供事实。只有页面需要 Page Center 的自动注册、canonical / alias / hreflang、sitemap、page renderer、长尾治理或索引审查能力时，才进入 `pages/*.jsonc`。
+
+正式约束：
+
+- 路径固定为 `<app_package>/pages/`
+- 页面声明按页面命名空间与页面文件组织，例如 `pages/base.jsonc`、`pages/<namespace>/base.jsonc`、`pages/<namespace>/<page>.jsonc`
+- 页面声明拥有独立的页面配置命名空间；它和 settings namespace 一样必须稳定、单一、可审计
+- 页面配置命名空间固定由 `owner_app + 页面相对路径` 共同确定，不允许再单独声明第二个 `page_namespace`
+- `pages/base.jsonc` 属于 owner app 自己的根页面命名空间，不是无主的全局页面
+- `pages/` 服从和 `templates/`、`static/`、`locales/`、`template_config/`、`migrations/` 相同的正式资源覆盖语义
+- 页面声明文件必须由页面中心定义 schema、校验、冲突裁决和编译诊断
+- 页面声明在运行时使用前必须先进入 app registry / resource discovery / `ResourceManifest` / 页面中心编译链
+- Web、CLI、worker 运行期不得绕过编译链临时扫描 `pages/` 并形成第二份运行图
+- 未进入 `pages/` 的普通页面不得为了共享多语言或 shell 再发明第二套页面配置；它们应消费 `PageProfile` / `pz_site_ui` 的正式页面状态合同
+- `configs/default.jsonc` 只放 `pz settings init/update` 可同步到项目配置的 app settings 默认值和受控顶层路由默认值；页面声明不得塞回 `configs/default.jsonc`
+
+## 3. `apps.py` 约定
+
+每个 app 必须暴露一个 `app` 对象。
+
+补充说明：
+
+- `installed_apps` 可以声明正式最小子包，也可以声明文件夹/容器目录
+- 每个最小子包都必须显式提供自己的 `apps.py`
+- 分组目录只用于 Git 与源码组织，不是运行时 namespace
+- 若 `installed_apps` 声明的是文件夹/容器目录，框架必须自动递归发现其中嵌套的最小子包
+- 宿主不需要手工把容器内所有最小子包逐个列出
+- `installed_apps` 的条目语法固定为目录名，不接受文件系统路径、distribution 名或 `<pkg>.apps:app`
+- `installed_apps` 一旦同时出现容器条目与显式叶子条目，作者面工具写回时必须收敛成单一的叶子 app 有序列表，不保留长期混写状态
+
+### 3.1 最小子包发现算法
+
+为了避免不同入口各自实现一套扫描逻辑，最小子包发现算法固定如下：
+
+1. 先按 `installed_apps` 中声明的顺序处理每个目录名
+2. 若条目本身命中最小子包，则直接收录并停止继续向下递归
+3. 若条目是容器目录，则只递归扫描其子目录
+4. 容器内部统一按目录名字典序做深度优先展开
+5. 展开完成后，以得到的最小子包有序列表进入 app registry / settings / resources / routes
+
+最小子包的判定标准固定为标准 `apps.py`：
+
+- 候选目录或其 Python 包目录内存在 `apps.py`
+- `apps.py` 内有 app class
+- app class 内以静态字符串声明 `id`
+- `apps.py` 内有模块级 `app = <AppClass>()`
+- 该 `app` 对象最终可解析出合法 `app.id`
+
+补充约束：
+
+- 一旦某个目录已被判定为最小子包，就停止向下扫描其内部子目录
+- 不允许通过模块名猜测、历史 alias、旧容器命名或 package-level `app` 猜测把一个目录判成最小子包
+- 非 app 模块不允许使用 `apps.py` 作为普通实现文件名；`apps.py` 是 app 入口保留名
+- 只有标准 `apps.py` 才能进入 app registry / settings / resources / routes 的正式装配链
+- 发现阶段若得到重复 `app_id`，必须直接报错，不允许静默跳过或以后出现者覆盖先出现者
+- 发现阶段必须忽略 `.git/`、`.venv/`、`__pycache__/`、`dist/`、`build/` 这类非源码目录
+
+最小示例：
+
+```python
+from fastapi import APIRouter
+
+
+class MyApp:
+    id = "pz_my_app"
+    name = "My App"
+    version = "0.1.0"
+    required_pz = ">=0.1.0"
+
+    def routers(self):
+        return []
+
+
+app = MyApp()
+```
+
+## 4. app 元数据约定
+
+正式字段：
+- `id`
+- `name`
+- `version`
+- `required_pz`
+
+按需字段：
+- `requires_apps`
+- `required_protocols`
+
+约束：
+- `id` 必须稳定、唯一，并使用项目内正式注册的 app id
+- 同一 app 的配置命名空间、迁移目录、模型 label 应统一使用同一 `app_id`
+- `required_pz` 应成为标准字段，不只在官方维护最小子包中使用
+- 若声明 `requires_apps`，应优先写 `app_id`，而不是依赖模块路径后缀匹配
+
+补充要求：
+- `name` 只用于展示，不参与装配判断
+- `id` 一旦对外发布，不应随重构轻易变更
+- app 元数据不负责声明“替换谁”；app 替换关系的唯一正式真相源是项目级 `[app_replacements]`
+
+补充约束：
+
+- `id` 应使用稳定的 lower_snake_case 技术名，不应混用大小写、短横风格或展示名
+- `id` 必须同时作为：
+  - settings namespace
+  - migration owner
+  - extension owner
+  - 诊断输出中的正式身份
+- 不强制特定技术前缀；历史 app id 以已发布稳定值为准。若后续确需改名，必须对 `app.id`、settings namespace、目录名、import 包名、distribution 和项目配置做一次性显式迁移，不允许长期同时支持两套 namespace。
+- 若 app 需要被外部依赖，还应明确声明其 `public.py` 入口与对外 facade/capability contract
+
+### 4.1 `app.id` 与 settings namespace 的单一规则
+
+为了避免“包名一套、`app.id` 一套、settings namespace 又一套”的三重真相源，正式规则固定如下：
+
+- 每个正式叶子 app 只有一个稳定身份：`app.id`
+- settings namespace 必须与 `app.id` 完全一致
+- 不允许再单独声明 `settings_namespace`、`config_namespace` 或任何同义字段
+- 不允许通过包尾名、replacement 名、历史 alias 自动派生第二个 namespace
+
+补充要求：
+
+- `apps.py` 必须通过模块级 `app` 对象显式声明 `app.id`
+- `app.id` 应是 class 上的静态字符串，不能依赖 settings 常量、环境变量、函数调用或运行时计算
+- 新建子包的 `app.id` 默认应等于最小子包目录名与 import 包名
+- 不允许再声明第二个 settings namespace；运行时以 `app.id` 为唯一身份真相
+- 脚手架默认使用最小子包目录名填充 `app.id`
+
+结论：
+
+- 标准 `apps.py` 中的 `app.id` 是正式 namespace 真相源
+- “最小子包名字”是脚手架默认值来源；历史子包若已发布稳定 `app.id`，不得仅因命名口径变化强制迁移
+- 不存在独立可配置的第二个 settings namespace
+
+## 5. 生命周期约定
+
+app 可按需实现以下钩子：
+- `init(pz_ctx)`
+- `startup(fastapi_app, pz_ctx)`
+- `shutdown(fastapi_app, pz_ctx)`
+- `extensions()`
+
+要求：
+- 生命周期钩子应幂等
+- 不能无条件依赖 DB、Redis 等可选设施
+- 不能在 import 阶段执行重型初始化
+- `startup()` 不应默认偷偷启动后台 worker 或注册长期循环任务
+- 若 app 需要后台 worker，应提供显式 CLI / runner 入口
+- `shutdown()` 若注册了 provider、event subscriber、background loop，必须对称清理
+- `init()` / `startup()` 失败语义应明确，不应靠 warning 吞掉后继续装配
+
+### 5.0 生命周期状态机
+
+app 生命周期统一服从正式状态机：
+
+- declared
+- compiled
+- bound
+- started
+- stopped
+
+钩子语义固定为：
+
+- `init()`
+  - 只负责声明期注册
+  - 不启动运行期副作用
+- `startup()`
+  - 只负责激活已绑定的运行期能力
+  - 不补声明、不补裁决
+- `shutdown()`
+  - 只负责对称清理已启动能力
+  - 不承担重新配置或重新编译
+
+不允许：
+
+- app 在 `startup()` 中补 route/extension/provider 正式声明
+- app 在 `shutdown()` 中隐式触发下一轮初始化准备
+- app 自定义第二套正式生命周期名词替代上述状态机
+
+### 5.1 `extensions()` 约定
+
+`extensions()` 是 app 向 `pz` 声明正式扩展点的唯一入口。
+
+正式要求：
+
+- `extensions()` 返回值必须是结构化扩展对象序列
+- 每个扩展对象至少必须包含：
+  - `kind`
+  - `id`
+  - `owner_app`
+  - `api_version`
+  - `priority`
+- 扩展对象声明本身不得带副作用
+
+最常用的正式扩展点包括：
+
+- `host.builder`
+- `settings.provider`
+- `cli.tool`
+- middleware / lifecycle / route / resource contribution
+
+额外约束：
+
+- `host.builder` 只能通过 `build(ctx) -> HostBuildResult` 产出 host
+- `settings.provider` 只能通过 `provide(ctx) -> tuple[SettingsPatch, ...]` 返回 patch
+- `cli.tool` 只能通过 `configure(parser)` 与 `run(ctx) -> int` 暴露命令
+- 不允许 `extensions()` 返回裸函数、字符串路径或依赖 import-time 注册的对象
+
+## 5.2 app 声明协议的单一路径原则
+
+app 的声明面必须固定，避免 decorator、全局 registry、脚本扫描并存。
+
+正式要求：
+
+- app 的正式声明只来自：
+  - `apps.py` 中的 `app` 对象元数据
+  - `configs/default.jsonc`
+  - `settings.py` / `settings/` 中的 `AppSettings`
+  - `urls.py` 或 `urls/`
+  - `extensions()`
+  - 标准资源目录
+  - 标准迁移目录
+  - 标准 `cli/` 目录
+- `init()` 只负责声明期注册，不得承担第二套声明协议
+- `startup()` / `shutdown()` 只负责运行期激活与清理，不得补声明
+
+不允许：
+
+- import-time decorator 注册 route/extension/provider 当成正式声明来源
+- 模块级全局列表/字典作为第二套声明真相源
+- 通过扫描任意模块名猜测 app 资源、命令或声明对象
+
+结论：
+
+- app 的声明协议只有一套
+- 编译阶段只读取这套声明协议
+- 运行阶段不再补第二套声明
+
+## 5.3 `required_protocols` 的唯一语义
+
+`required_protocols` 不得成为含糊的“随便依赖某个实现模块”字段。
+
+正式要求：
+
+- `required_protocols` 只声明 capability contract 名称
+- 其解析只基于当前 `CapabilityRegistry`
+- 不允许写模块路径、类名、导入短名或具体官方 app / 独立子包实现名
+
+结论：
+
+- app 依赖的是协议，不是实现
+- `required_protocols` 只服务于依赖倒置，不服务于实现耦合
+
+## 6. 路由约定
+
+每个 app 必须通过 `<app_package>.urls` 暴露自己的 URL 真相源。
+
+推荐形态：
+
+- 简单 app 使用 `urls.py`
+- 复杂 app 使用 `urls/` 目录，但正式入口仍然是 `urls/__init__.py`
+- 宿主与共享层永远只认 `<pkg>.urls`
+
+`<pkg>.urls` 的职责：
+
+- 作为 app URL 的唯一正式声明入口
+- 使用 FastAPI 原生 `APIRouter()` / `include_router()` 组织本 app 的路由树
+- 只声明本 app 自己的路径结构、子模块 include 关系与稳定 namespace
+- 不承担跨 app prefix 挂载、全局排序、全局清理、冲突修补
+
+正式原则：
+
+- 采用 Django 风格的 include 式装配
+- 子包自带独立路由模块
+- prefix 由上层统一挂载
+- namespace 必须清晰、稳定、可审计
+- 业务包只声明，不装配
+- 全站 URL 末尾斜杠语义必须统一
+
+全站 URL 末尾斜杠规则：
+
+- 目录型页面 canonical path 必须以 `/` 结尾
+- 文件型资源、文件型接口与显式文件下载 URL 不得以 `/` 结尾
+- 同一条正式 URL 不允许同时长期暴露“带 `/`”与“不带 `/`”两份 canonical
+- slashless 到带 `/`、或带 `/` 到 slashless 的规范化跳转必须由共享 host / routing 规则统一承接，不允许每个业务包各自发明第二套 trailing-slash 语义
+- 页面 owner、SEO owner、sitemap owner、redirect owner 输出的 canonical / alias / hreflang / sitemap URL 必须与这套规则一致
+- 业务包在 `urls.py` 中只声明 canonical 版本，不手工注册成对的重复尾斜杠别名，除非该别名本身就是正式 route alias
+
+约束：
+
+- `apps.py` 不负责组装 URL 主链
+- URL 注册顺序不由 `apps.py`、`startup()`、`lifespan` 或局部 helper 的隐式顺序决定
+- 所有 app 的 URL 声明由官方扩展层统一收集并装配
+- `clean_and_reorder_routes()` 这类最终清理与排序逻辑只能存在于共享装配层
+- 通用动态路由必须显式处理与静态路由的冲突
+- 不允许依赖“某个官方 app 一定先于自己加载”，除非显式写入 `requires_apps`
+- 不允许依赖“重复路由时框架会替自己保留某一份”这类隐式行为
+- 不允许在 `startup()`、`lifespan`、局部 helper 中临时补挂正式路由
+
+模块组织约定：
+
+- 普通业务包优先只写一个 `urls.py`
+- 只有路由树复杂时才拆成 `urls/` 目录
+- 即使拆目录，对外也只暴露 `<pkg>.urls`
+- `<pkg>.urls` 只负责声明 Django 风格的 `urlpatterns`；它不负责构建路由，实际路由构建与绑定统一通过 `foundation/routing` 的正式 helper 完成
+- 如果 app 涉及页面开发，目录组织应遵循 MVC 心智：`models` 负责数据模型，`templates` / `static` 负责视图展示，页面处理函数负责控制器职责
+- `pages/` 保留给 Page Center 治理页声明目录；普通页面入口函数从 `urls.py` 拆出时统一命名为 `views.py` 或 `views/`
+- `urls.py` 或 `urls/` 只存放 URL 声明与 `urlpatterns` 导出；不在其中堆业务编排、页面配置拼装、数据访问细节、手工路由绑定或任何路由构建逻辑
+- `urlpatterns` 里的路径字符串使用 FastAPI / Starlette 原生 path 参数语法；既支持 `/{lang}/{module}/{slug}`，也支持 `/{lang:locale}/{slug}` 这类 convertor 形式
+
+页面开发补充约定：
+
+- 页面 HTML、模板片段、样式与前端脚本优先只负责展示层
+- 数据交互、状态修改、异步提交与查询优先通过 AJAX 调用后端 API 完成
+- 不鼓励把复杂业务状态机、数据聚合逻辑或长期演进的交互协议堆进模板脚本
+- 页面控制器负责把模板渲染和 API 接线接到正式后端能力，不负责在前端复制第二套业务主链
+
+## 7. settings 声明与读取约定
+
+每个 app 的 settings 作者面默认模板只允许有一个正式来源。
+
+默认情况下，正式来源是 app 根目录下的 `configs/default.jsonc`。
+
+`configs/default.jsonc` 只由 `pz settings init/update` 读取，用于生成或补全项目根 `pz.jsonc` / `pz.{PZ_ENV}.jsonc`。其中 `routing.default_language`、`routing.all_supported_languages`、`routing.language_aliases` 会被提升到项目根 `routing`；`commands` 会被提升到项目根快捷命令区；`apps.*.sources.source_mode` 这类项目装配状态会被提升到根 `apps` 中对应 owner。它们不会作为声明它们的 app 私有 settings 暴露。启动阶段不得直接读取 app 包内的 `configs/default.jsonc`。
+
+`configs/default.env` 是同一 app 的密钥模板配对文件，只允许放已由 `settings.py` / `settings/` schema 声明的 password、secret、token、key 类占位符。它可以被 Git 追踪，由 `pz settings init/update` 合并生成项目根 `.env` 与 `.env.{PZ_ENV}`。启动阶段不得直接读取 app 包内的 `configs/default.env`。
+
+每个 app 的 settings 声明模块固定为：`settings.py` 或 `settings/`。
+每个 app 的 Python 运行时读取入口固定为：`settings_center.settings.<app_id>`。
+
+文件形态允许两种：
+
+- `settings.py`
+- `settings/__init__.py`
+
+无论采用哪种形态，声明侧都只负责：
+- `AppSettings`
+- `__runtime_overrides__`
+
+示例：
+
+```python
+from pydantic import BaseModel
+
+
+class AppSettings(BaseModel):
+    ENABLED: bool
+    FEATURE_FLAG: bool
+```
+
+要求：
+- app 私有配置统一走 `settings_center.settings.<app_id>`
+- app 代码不得直接读取 `os.environ`
+- 不再向全局根 settings 扁平化暴露业务私有字段
+- `AppSettings` 必须使用 `BaseModel`，由框架统一完成环境变量与配置文件聚合
+- 各 app 不再通过 `BaseSettings + env_prefix` 独立读取环境变量
+- app 默认配置模板只能位于 `configs/default.jsonc`，且只能由 `pz settings init/update` 消费
+- app 密钥占位模板只能位于 `configs/default.env`，且只能由 `pz settings init/update` 消费
+- 启动阶段的 settings 编译只读取项目根 `pz.jsonc`、`pz.{PZ_ENV}.jsonc`、`.env`、`.env.{PZ_ENV}` 与显式环境变量
+- 子包新增 settings 字段后，必须同时更新 `configs/default.jsonc` 模板，并要求项目执行 `pz settings update` 把新键同步到项目配置；启动期不得从包内模板临时补齐
+- Python 运行时代码不再直接 import app 的 `settings.py`
+
+### 7.1 namespace 与读取边界
+
+settings 读取边界固定如下：
+
+- 正式叶子 app：
+  - 只通过自己的 `settings_center.settings.<app_id>` 读取配置
+  - 其运行时 namespace 固定为 `app.id`
+- 非 app 的内部实现模块：
+  - 不允许自建 namespace
+  - 只能读取所属最小子包的 `settings_center.settings.<app_id>`
+  - 若读取的是项目级装配信息，只能通过 `settings_center.settings.project.<field>` 读取
+
+不允许：
+
+- 内部 client / adapter / service 子目录各自声明一套独立 namespace
+- 没有 `apps.py` 的实现子目录偷偷读取一份自己的 TOML
+- 用模块路径或目录名临时拼接出新的 settings 读取规则
+
+判断标准：
+
+- 有正式 `apps.py` 且被安装声明的最小子包，才有资格拥有自己的 settings namespace
+- 没有最小子包身份，就没有自己的 settings namespace
+- 若使用 `settings/` 目录，只有 `settings/__init__.py` 可以作为正式入口；其它文件只允许做内部拆分
+- `apps.py`、`urls.py`、`urls/`、`public.py`、`services/*` 不得再成为第二套默认配置模板来源或运行时配置读取入口
+- `settings.py` / `settings/` 不得在 import 阶段读取 `configs/default.jsonc`、`configs/default.env` 或项目 `.env*`
+
+补充要求：
+
+- `AppSettings` 应只表达配置 schema、结构化校验、normalize 与 `__runtime_overrides__`
+- 不应在 `AppSettings` validator 中夹带跨模块 I/O、路径推断或全局单例改写
+- 允许线上热更新的字段，应在 `configs/default.jsonc` 中给出 settings init/update 模板默认值；若字段允许 `None` 且 TOML 无法表达空值，可暂时省略该键
+
+## 8. 资源约定
+
+若存在以下目录，则视为 app 资源：
+- `templates/`
+- `static/`
+- `locales/`
+
+规则：
+- 资源发现只依赖 app 包路径
+- 覆盖顺序只依赖 `installed_apps`：按 `installed_apps` 从前到后合并，同相对路径资源由后面的 app 覆盖前面的 app
+- 运行时合并产物写入外部 `cache_dir`
+
+## 9. 模型与迁移约定
+
+模型：
+- 统一放在 `<app>.models` 入口下，即 `models.py` 或 `models/`
+- 其所属 app label 必须与 `app.id` 保持一致
+- 不应依赖 `pz` 为某个具体 app 特判 `module.models` / `runtime.models` 才能工作
+- 若模型显式声明 ORM 的 app label，应与 `app.id` 完全一致
+
+迁移：
+- 必须位于 `migrations/<app_id>/`
+- 若 app 提供模型，则必须提供对应迁移目录
+- 不允许一个 app 包内同时维护多个 app_id 的迁移归属
+
+## 10. 依赖规则
+
+正式允许的依赖：
+- `app -> pz`
+- `app -> pz` 暴露的稳定门面
+
+不允许：
+- app 直接依赖其它 app 的内部实现模块
+- app 在无门面情况下直接耦合 infra 私有实现
+
+正式要求：
+- 跨 app 依赖统一走 `public.py`
+- 若某 app 提供平台能力，应将该能力做成 `public.py` 暴露的稳定 facade，而不是让调用方 import 内部 service/models
+
+## 10.1 app 的最小交付要求
+
+从工程实用角度，能被长期维护的 app 不应只有代码结构，还应有最小交付面。
+
+每个正式 app 至少具备：
+
+- `apps.py`
+- `settings.py` 或明确声明“无 app settings”
+- 迁移目录或明确声明“无持久化模型”
+- `public.py` 或明确声明“仅内部使用”
+- 最小契约测试
+
+对外分发的 app 还必须具备：
+
+- README
+- 版本范围声明
+- 配置示例
+- 替换/升级说明
+
+## 11. import 时行为约束
+
+app 模块在 import 阶段不得：
+- 启动后台任务
+- 初始化 DB / Redis 连接
+- 创建依赖首次 settings 快照的重型全局对象
+- 注册影响全局进程状态且不可回滚的 provider / resolver / singleton
+- 订阅无法显式取消的全局事件处理器
+
+app 模块仅允许：
+- 定义轻量 schema、常量、纯内存 registry
+- 暴露 lazy factory 或 facade
+
+## 12. app 公共 API 约定
+
+如果 app 需要被其它 app 或项目代码依赖，稳定入口只允许放在：
+
+- `public.py`
+
+不再把以下路径当作长期公共契约：
+
+- `service.py`
+- `runtime/*`
+- `module/*`
+- `models.py`
+- 任意内部 helper
+
+原则：
+
+- 能力通过 facade 暴露
+- 实现保持可替换
+- 对外依赖面尽量小
+
+## 13. app CLI 发现约定
+
+app CLI 也必须只有一种正式发现方式。
+
+正式要求：
+
+- app CLI 工具固定放在 `<app>/cli/<tool>.py`
+- 框架只按这个目录约定发现并暴露 `pz <app_id> <tool>`
+- 不再支持通过 entry point、模块级注册器、import-time decorator 动态注册第二套 app CLI 主链
+
+结论：
+
+- app CLI 的正式真相源是包内 `cli/` 目录
+- CLI manager 只做发现与执行，不做二次猜测和旁路注册
+
+## 14. app 资源声明约定
+
+资源边界同样必须只有一种正式表达方式。
+
+正式要求：
+
+- 模板、静态、语言、迁移目录统一按标准目录约定声明
+- 框架只从 app 包内标准目录读取资源源
+- app 不再自定义第二套 `resources()` / `assets()` / path helper 协议作为正式资源声明入口
+
+结论：
+
+- app 的资源源真相源是标准包目录布局
+- 资源合并、模板渲染、静态定位都只消费后续编译出的 manifest，不回头读私有声明协议