pz-cli 5.0.0__py3-none-any.whl

pz_core/authoring/templates/app/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

pz_core/authoring/templates/app/api.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from ..shared import dedent
+
+
+def app_api_template(app_id: str) -> str:
+    return dedent(
+        f"""\
+        from __future__ import annotations
+
+
+        # 最小健康检查接口示例。
+        async def healthz() -> dict[str, str]:
+            return {{"app": "{app_id}", "status": "ok"}}
+
+
+        # 最小业务 API 示例。
+        # 推荐让前端通过 AJAX 调用这类后端接口，而不是把业务逻辑塞进页面脚本里。
+        async def api_example() -> dict[str, str]:
+            return {{"app": "{app_id}", "message": "Use AJAX to talk to backend APIs."}}
+        """
+    )
+
+
+__all__ = ["app_api_template"]

pz_core/authoring/templates/app/apps.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from ..shared import dedent
+
+
+def app_apps_template(app_id: str) -> str:
+    return dedent(
+        f"""\
+        from __future__ import annotations
+
+
+        class App:
+            id = "{app_id}"
+            name = "{app_id}"
+            version = "0.1.0"
+            required_pz = ">=5.0.0"
+            priority = 900
+
+            def extensions(self):
+                return ()
+
+
+        app = App()
+
+
+        __all__ = ["App", "app"]
+        """
+    )
+
+
+__all__ = ["app_apps_template"]

pz_core/authoring/templates/app/auth_package_init.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from ..shared import dedent
+
+
+def app_auth_package_init_template() -> str:
+    return dedent(
+        '''\
+        """Reserved package for advanced auth registration logic."""
+        '''
+    )
+
+
+__all__ = ["app_auth_package_init_template"]

pz_core/authoring/templates/app/auth_readme.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from ..shared import dedent
+
+
+def app_auth_readme_template(app_id: str) -> str:
+    return dedent(
+        f"""\
+        # {app_id} auth examples
+
+        This directory is reserved for advanced auth integration.
+
+        Nothing in this directory is imported or registered by default. The generated app exposes
+        `route_policy` through the project settings generated from `configs/default.jsonc`; the installed
+        formal auth owner consumes that runtime settings contract.
+
+        Only add Python modules here when `route_policy` is not expressive enough and the target auth owner
+        documents a formal registration protocol.
+
+        ```python
+        # Demo only. Do not import this from apps.py until an auth owner protocol requires it.
+        def example_policy_context(request):
+            return {{"owner_app": "{app_id}", "path": request.url.path}}
+        ```
+        """
+    )
+
+
+__all__ = ["app_auth_readme_template"]

pz_core/authoring/templates/app/configs_package_init.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from ..shared import dedent
+
+
+def app_configs_package_init_template() -> str:
+    return dedent(
+        '''\
+        """Packaged app configuration defaults."""
+        '''
+    )
+
+
+__all__ = ["app_configs_package_init_template"]

pz_core/authoring/templates/app/default_env.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from ..shared import dedent
+
+
+def app_default_env_template(app_id: str) -> str:
+    return dedent(
+        f"""\
+        # Secret placeholders for {app_id}.
+        # This file is git-trackable and is used by `pz settings init/update`
+        # to hydrate project `.env*` files.
+        # Put only schema-backed password, secret, token, or key placeholders here.
+        # Keep real values in project `.env`, `.env.develop`, `.env.test`, or `.env.product`.
+        """
+    )
+
+
+__all__ = ["app_default_env_template"]

pz_core/authoring/templates/app/default_jsonc.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from ..shared import dedent
+
+
+def app_default_jsonc_template() -> str:
+    return dedent(
+        """\
+        {
+          "enabled": true,
+          "route_policy": {
+            "default_mode": "auth",
+            "auth_paths": [],
+            "public_paths": [],
+            "delegate_paths": [],
+            "auth_owner": null,
+            "public_owner": null,
+            "delegate_owner": null
+          }
+        }
+        """
+    )
+
+
+__all__ = ["app_default_jsonc_template"]

pz_core/authoring/templates/app/locales_readme.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from ..shared import dedent
+
+
+def app_locales_readme_template(app_id: str) -> str:
+    return dedent(
+        f"""\
+        # {app_id} locale examples
+
+        Locale files are not registered by default. Add real locale resources only when the installed
+        i18n/locale owner documents the expected file name and schema.
+
+        Demo payload:
+
+        ```json
+        {{
+          "hello": "Hello from {app_id}"
+        }}
+        ```
+        """
+    )
+
+
+__all__ = ["app_locales_readme_template"]

pz_core/authoring/templates/app/migrations_readme.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from ..shared import dedent
+
+
+def app_migrations_readme_template(app_id: str) -> str:
+    return dedent(
+        f"""\
+        # {app_id} migrations
+
+        This package owns database migrations for `{app_id}`.
+
+        No migration is registered by default. Add migration files only after the app declares real models
+        and the project needs a schema change.
+        """
+    )
+
+
+__all__ = ["app_migrations_readme_template"]

pz_core/authoring/templates/app/models.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from ..shared import dedent
+
+
+def app_models_template() -> str:
+    return dedent(
+        """\
+        from __future__ import annotations
+        """
+    )
+
+
+__all__ = ["app_models_template"]

pz_core/authoring/templates/app/package_init.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+
+def app_package_init_template() -> str:
+    return ""
+
+
+__all__ = ["app_package_init_template"]

pz_core/authoring/templates/app/pages_base.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+from ..shared import dedent
+
+
+def app_pages_base_template(app_id: str) -> str:
+    return dedent(
+        f"""\
+        {{
+          // 根默认层：资源合并后对应 pages/base.jsonc。
+          // 覆盖顺序是 pages/base.jsonc < pages/{app_id}/base.jsonc < pages/{app_id}/key.jsonc。
+          // 另外，资源覆盖是文件级覆盖；多个 app 提供同一相对路径时，installed_apps 中靠后的 app 覆盖靠前的同名文件。
+          "api_version": "page_center.base.v1",
+          // kind=base 表示这里只提供页面默认值，不会被当作具体页面注册。
+          "kind": "base",
+          // owner_app 固定为当前最小子包 app_id，用于审计来源；不是第二套页面命名空间字段。
+          "owner_app": "{app_id}",
+          // 默认语言：具体页面没有覆盖时继承这里的语言控制面。
+          "default_language": "en",
+          // Page Center 页面必须声明支持语言；具体页面可在页面层覆盖。
+          "page_supported_language": ["en"],
+          // 根默认层不声明默认关键词，避免所有页面误继承同一个发布级关键词。
+          "default_term": null,
+          // 根默认层不提供公开路由词；具体页面应在 pages/{app_id}/key.jsonc 中声明 slug。
+          "slug": "",
+          // 当前层不允许后续同路径页面覆盖；具体页面可按需要显式改为 true。
+          "route_allow_override": false,
+          // 兜底模板名：命名空间 base 或具体页面通常会覆盖它。
+          "template_name": "{app_id}_index",
+          // 根默认层只放确实要影响所有页面的通用 bundle。
+          "translation_bundles": [],
+          "localized": {{
+            "en": {{
+              // 默认语言变体占位；具体页面应覆盖成真实页面关键词。
+              "term": "base",
+              "synonyms": []
+            }}
+          }},
+          // seo.provider/sitemap_provider 为 null 表示本层不提供 provider 默认值，由下层或运行时策略决定。
+          "seo": {{
+            "provider": null
+          }},
+          "sitemap_provider": null,
+          // nav 属于页面展示默认配置；默认 dict 会深合并，所以下层如果要把 nav 当作完整配置替换根默认层，
+          // 应在对应 page_config 层声明编译期指令：
+          // "$merge": {{"replace_paths": ["nav"]}}
+          // 如果 replace 树里还要保留局部深合并，可补更深的 deep_merge_paths，例如 "nav.collapse"。
+          // $merge 只参与 page_config 编译，不进入 runtime 页面配置。
+          "nav": {{
+            "items": [],
+            // collapse 是可选的桌面 nav SSR/CSS 溢出折叠计划：导航容器变窄时，把顶层 nav item 移入 More 下拉。
+            // 它只影响展示，不改变路由、SEO、sitemap，也不由前端 JS 在运行时重新测量或重排。
+            "collapse": {{
+              "defaults": {{
+                // breakpoints 使用 nav 容器宽度；第 N 个断点会折叠 order 中前 N 个 item。
+                "breakpoints": [980, 860, 760],
+                // order 使用 nav.items[].id 去掉 # 后的 key；留空时 site_ui 会从右到左折叠。
+                // nav.items 为空时没有可折叠项；添加多个 nav item 后可按需要填写。
+                "order": []
+              }},
+              // 需要按语言调整折叠计划时，在这里写对应语言覆盖，例如 zh-CN / ja。
+              "langs": {{}}
+            }}
+          }}
+        }}
+        """
+    )
+
+
+def app_pages_namespace_base_template(app_id: str) -> str:
+    return dedent(
+        f"""\
+        {{
+          // 命名空间默认层：资源合并后对应 pages/{app_id}/base.jsonc。
+          // 覆盖顺序是 pages/base.jsonc < pages/{app_id}/base.jsonc < pages/{app_id}/key.jsonc。
+          // 这一层只放 {app_id} 命名空间下所有页面共享的默认值。
+          "api_version": "page_center.base.v1",
+          "kind": "base",
+          // 如果本层要把某个 dict 路径作为完整配置替换根默认层，可在这里声明编译期 $merge。
+          // 示例： "$merge": {{"replace_paths": ["nav"]}}
+          // 需要排除 replace 树里的更深路径时，用 deep_merge_paths，例如 "nav.collapse"。
+          // $merge 只控制 page_config 层叠加，不进入 runtime 页面配置。
+          "owner_app": "{app_id}",
+          // 继承或覆盖根默认层的默认语言。
+          "default_language": "en",
+          // 命名空间内默认只发布英文页面；具体页面可显式扩展。
+          "page_supported_language": ["en"],
+          // 命名空间默认层仍不声明发布级关键词，避免具体页面误继承。
+          "default_term": null,
+          // 命名空间的基础 route token；长尾/导流页没有 path_segments 时可作为父级 token fallback。
+          "slug": "{app_id.replace('_', '-')}",
+          "route_allow_override": false,
+          // 当前命名空间默认模板；具体页面可以覆盖为自己的 template_name。
+          "template_name": "{app_id}_index",
+          // 命名空间通用页面 bundle 放这里；单页 bundle 放具体页面文件。
+          "translation_bundles": [],
+          "localized": {{
+            "en": {{
+              "term": "{app_id.replace('_', ' ')}",
+              "synonyms": []
+            }}
+          }},
+          "seo": {{
+            "provider": null
+          }},
+          "sitemap_provider": null
+        }}
+        """
+    )
+
+
+def app_pages_key_template(app_id: str) -> str:
+    slug = app_id.replace("_", "-")
+    term = app_id.replace("_", " ")
+    return dedent(
+        f"""\
+        {{
+          // 具体页面层：资源合并后对应 pages/{app_id}/key.jsonc。
+          // 覆盖顺序是 pages/base.jsonc < pages/{app_id}/base.jsonc < pages/{app_id}/key.jsonc。
+          // 复制本文件新增页面时，把文件名 key.jsonc、default_term、slug 和 localized.*.term 改成真实页面值。
+          "api_version": "page_center.page.v1",
+          // kind=page 表示这是会被 Page Center 编译、注册路由、进入 SEO/Sitemap 投影的正式页面声明。
+          "kind": "page",
+          "owner_app": "{app_id}",
+          // 默认语言决定默认语言 canonical 与自动 alias 的生成方向。
+          "default_language": "en",
+          // 当前页面只声明英文版本。
+          "page_supported_language": ["en"],
+          // 默认关键词是发布级字段；它不参与 URL 拼接，但会参与自动 alias 与 SEO 语义。
+          "default_term": "{term}",
+          // slug 是所有语言共享的正式 URL token。
+          "slug": "{slug}",
+          // 为空表示普通承接页；导流/长尾页可声明父级路径段，例如 ["{slug}"]。
+          "path_segments": [],
+          // 允许后安装 app 或后声明页面覆盖同一路由时才设为 true。
+          "route_allow_override": false,
+          // 必须能在 template_config/{app_id}/{app_id}_index.json 找到同名模板声明，否则 Page Center 编译会失败。
+          "template_name": "{app_id}_index",
+          // 单页特有翻译 bundle 放这里；命名空间通用 bundle 放 pages/{app_id}/base.jsonc。
+          "translation_bundles": [],
+          "seo": {{
+            "provider": null
+          }},
+          "sitemap_provider": null,
+          "localized": {{
+            "en": {{
+              // 当前语言真实关键词；不要再写 primary_keyword。
+              "term": "{term}",
+              "synonyms": []
+            }}
+          }}
+        }}
+        """
+    )
+
+
+__all__ = [
+    "app_pages_base_template",
+    "app_pages_key_template",
+    "app_pages_namespace_base_template",
+]

pz_core/authoring/templates/app/pages_readme.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from ..shared import dedent
+
+
+def app_pages_readme_template(app_id: str) -> str:
+    return dedent(
+        f"""\
+        # {app_id} page declarations
+
+        `pages/` is the formal source of page declarations for `pz_page_center`.
+
+        Authoring rules:
+
+        - Put page declarations here, not in `settings.py` or `configs/default.jsonc`.
+        - Treat `pages/` as the page-configuration namespace for this app.
+        - Merge order is `pages/base.jsonc` < `pages/{app_id}/base.jsonc` < `pages/{app_id}/key.jsonc`.
+        - Resource override is file-level: if multiple apps provide the same relative path, the later app in `installed_apps` wins.
+        - Use `base.jsonc` for root defaults, `{app_id}/base.jsonc` for app namespace defaults, then override per page file.
+        - Keep templates and static assets in `templates/` and `static/`; `pages/` stores declaration data only.
+        """
+    )
+
+
+__all__ = ["app_pages_readme_template"]

pz_core/authoring/templates/app/public.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from ..shared import dedent
+
+
+def app_public_template() -> str:
+    return dedent(
+        """\
+        from __future__ import annotations
+
+        from fastapi import FastAPI
+
+
+        # `mount(...)` 示例使用的最小子应用工厂。
+        # 需要挂载独立后台、代理应用或单独生命周期子应用时，可以按这个形式提供 app factory。
+        def create_demo_mount_app() -> FastAPI:
+            app = FastAPI()
+
+            @app.get("/healthz")
+            async def healthz() -> dict[str, str]:
+                return {"status": "ok", "source": "mounted-demo"}
+
+            return app
+
+
+        __all__ = ["create_demo_mount_app"]
+        """
+    )
+
+
+__all__ = ["app_public_template"]

pz_core/authoring/templates/app/pyproject.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from ..shared import dedent
+
+
+def app_pyproject_template(app_id: str) -> str:
+    distribution = app_id.replace("_", "-")
+    return dedent(
+        f"""\
+        [build-system]
+        requires = ["setuptools>=69", "wheel"]
+        build-backend = "setuptools.build_meta"
+
+        [project]
+        name = "{distribution}"
+        version = "0.1.0"
+        description = "{app_id} local minimal package"
+        readme = "README.md"
+        requires-python = ">=3.11"
+        dependencies = [
+          "fastapi>=0.110,<1.0",
+          "pydantic>=2.10,<3.0",
+          "pz-cli==5.0.0",
+        ]
+
+        [dependency-groups]
+        dev = [
+          "pytest>=8.4,<9",
+        ]
+
+        [tool.setuptools]
+        include-package-data = true
+        package-dir = {{ "" = "." }}
+        packages = [
+          "{app_id}",
+          "{app_id}.auth",
+          "{app_id}.configs",
+          "{app_id}.pages",
+          "{app_id}.template_config",
+          "{app_id}.template_config.{app_id}",
+          "{app_id}.templates",
+          "{app_id}.templates.{app_id}",
+          "{app_id}.static",
+          "{app_id}.static.{app_id}",
+          "{app_id}.locales",
+          "{app_id}.migrations",
+          "{app_id}.migrations.{app_id}",
+        ]
+
+        [tool.setuptools.package-data]
+        "*" = [
+          "*.md",
+          "*.env",
+          "*.json",
+          "*.jsonc",
+          "*.html",
+          "*.js",
+          "*.css",
+          "*.txt",
+          "*.yaml",
+          "*.yml",
+          "**/*.md",
+          "**/*.env",
+          "**/*.json",
+          "**/*.jsonc",
+          "**/*.html",
+          "**/*.js",
+          "**/*.css",
+          "**/*.txt",
+          "**/*.yaml",
+          "**/*.yml",
+        ]
+        """
+    )
+
+
+__all__ = ["app_pyproject_template"]

pz_core/authoring/templates/app/readme.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from ..shared import dedent
+
+
+def app_readme_template(app_id: str) -> str:
+    distribution = app_id.replace("_", "-")
+    return dedent(
+        f"""\
+        # {app_id}
+
+        这个最小子包由 `pz startapp` 生成。
+
+        ## 文件结构
+
+        - `pyproject.toml`：`{distribution}` 的最小分发元数据
+        - `{app_id}/apps.py`：app 声明与正式扩展入口
+        - `{app_id}/urls.py`：本 app 的 URL 真相源
+        - `{app_id}/models.py`：MVC 心智下的数据模型入口
+        - `{app_id}/views.py`：页面入口函数与控制器职责
+        - `{app_id}/api.py`：后端 API 入口函数
+        - `{app_id}/pages/`：页面声明目录，由 `pz_page_center` 编译
+        - `{app_id}/pages/base.jsonc`：页面根默认声明
+        - `{app_id}/pages/{app_id}/base.jsonc`：本 app 页面命名空间默认声明
+        - `{app_id}/pages/{app_id}/key.jsonc`：具体页面声明示例
+        - `{app_id}/template_config/{app_id}/{app_id}_index.json`：Page Center 模板声明示例
+        - `{app_id}/templates/`、`{app_id}/static/`：MVC 心智下的展示层资源目录
+        - `{app_id}/templates/{app_id}/index.html`：页面模板示例
+        - `{app_id}/static/{app_id}/app.js`：AJAX + API 交互示例脚本
+        - `{app_id}/configs/default.jsonc`：本 app 的默认配置模板，只服务 `pz settings init/update`
+        - `{app_id}/configs/default.env`：本 app 的密钥/密码/令牌/Key 占位模板
+        - `{app_id}/locales/`：预留语言资源目录；默认只放 demo 说明
+        - `{app_id}/settings.py`：正式 `<app>.settings` 声明入口
+        - `{app_id}/public.py`：对外稳定公开面
+        - `{app_id}/auth/`：预留的 auth 注册包；默认只放未注册 demo 说明，仅在需要超出 `route_policy` 表达力的高级 auth 扩展时使用
+
+        ## 日常开发入口
+
+        - 大多数代码修改都应发生在 `{app_id}/` 目录内。
+        - URL 声明从 `{app_id}/urls.py` 开始看，配置声明从 `{app_id}/settings.py` 开始看，默认配置模板从 `{app_id}/configs/default.jsonc` 开始看，密钥占位模板从 `{app_id}/configs/default.env` 开始看。
+        - 页面开发默认遵循 MVC 心智：`models.py` 管数据模型，`templates/` / `static/` 管展示，`views.py` 承担页面入口函数与控制器职责，`api.py` 承担后端 API 入口。
+        - 页面声明从 `{app_id}/pages/` 开始看；页面默认值按 `{app_id}/pages/base.jsonc` < `{app_id}/pages/{app_id}/base.jsonc` < `{app_id}/pages/{app_id}/key.jsonc` 叠加。
+        - 如果要写一个最小可运行示例，可以先看 `{app_id}/urls.py`、`{app_id}/views.py`、`{app_id}/api.py`、`{app_id}/pages/{app_id}/key.jsonc`、`{app_id}/template_config/{app_id}/{app_id}_index.json`、`{app_id}/templates/{app_id}/index.html` 和 `{app_id}/static/{app_id}/app.js`。
+        - `{app_id}/apps.py` 只负责 app 元信息与正式扩展声明。
+        - `{app_id}/public.py` 是跨 app 调用时唯一稳定公开面。
+        - `{app_id}/auth/` 默认只是保留位；不要在还没形成正式高级 auth 规则前往里面堆私有逻辑。
+        - 只有在分发元数据或依赖确实变化时，才修改 `pyproject.toml`。
+
+        ## 重要约定
+
+        - host 装配保持在项目根 `main.py` 与正式 host 扩展里，不在这个 app 内重复造壳。
+        - `urls.py` 是本 app 唯一正式 URL 声明文件，只放 Django 风格的 `urlpatterns` 声明。
+        - `urls.py` 不负责构建路由；具体路由构建与绑定由 `pz_foundation.routing` 统一编译。
+        - `urls.py` 里的 `path(...)` 用于声明当前 app 自己提供的普通 HTTP 路由，`mount(...)` 用于声明需要挂载的独立子应用。
+        - 页面入口函数放到 `views.py`，后端 API 入口函数放到 `api.py`。
+        - `pages/` 保留给页面声明目录；不要再把页面入口实现文件命名成 `pages.py`。
+        - 默认配置模板放在 `configs/default.jsonc`，只用于 `pz settings init/update` 生成或补全项目 `pz*.jsonc`。
+        - `configs/default.env` 只放 schema 已声明的密钥/密码/令牌/Key 占位符；它只用于 `pz settings init/update` 生成项目 `.env*`，不是启动期配置来源。
+        - `pages/` 是页面声明真相源；页面配置命名空间由 `owner_app + 页面相对路径` 确定。
+        - `pages/base.jsonc`、`pages/{app_id}/base.jsonc` 只放页面默认声明，不在里面塞业务运行逻辑；具体页面字段放到 `pages/{app_id}/key.jsonc` 或其它具体页面文件。
+        - 页面资源覆盖是文件级覆盖；多个 app 提供同一相对路径时，`installed_apps` 中靠后的 app 覆盖靠前的同名文件。
+        - `templates/{app_id}/index.html` 与 `static/{app_id}/app.js` 是 authoring demo；只有被 `pages/{app_id}/key.jsonc` 和 `template_config/{app_id}/{app_id}_index.json` 引用时才进入 Page Center 页面链路。
+        - `templates/README.md`、`static/README.md`、`locales/README.md` 都只是 demo；默认不会自动渲染或加载。
+        - `settings.py` 只负责 schema、校验、normalize 与 runtime override metadata，import 阶段不得读取包内默认模板或项目 `.env*`。
+        - 新 app 默认预留 `route_policy` 配置块与 `auth/` 空包；具体认证实现由已安装的正式 auth owner 消费该配置。
+        - 只要 `AppSettings` 声明了 `route_policy`，正式 settings runtime owner 就可以把它纳入可治理 URL 规则。
+        - 运行时代码通过 `settings_center.settings.{app_id}.<field>` 读配置，不直接从 `settings.py` 取值。
+        - 不要在这个 app 里创建本地 FastAPI host shell。
+        - 前端默认只负责展示与局部增强；数据交互优先走 AJAX + 后端 API。
+        """
+    )
+
+
+__all__ = ["app_readme_template"]

pz_core/authoring/templates/app/settings.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from ..shared import dedent
+
+
+def app_settings_template() -> str:
+    return dedent(
+        """\
+        from __future__ import annotations
+
+        from typing import Literal
+
+        from pydantic import BaseModel, Field
+
+
+        class RoutePolicySettings(BaseModel):
+            default_mode: Literal["auth", "public"] = "auth"
+            auth_paths: tuple[str, ...] = ()
+            public_paths: tuple[str, ...] = ()
+            delegate_paths: tuple[str, ...] = ()
+            auth_owner: str | None = None
+            public_owner: str | None = None
+            delegate_owner: str | None = None
+
+
+        class AppSettings(BaseModel):
+            enabled: bool
+            route_policy: RoutePolicySettings = Field(default_factory=RoutePolicySettings)
+
+            __runtime_overrides__ = {
+                "enabled": {"mode": "live", "label": "启用开关"},
+                "route_policy": {
+                    "type": dict,
+                    "mode": "live",
+                    "label": "认证路由规则",
+                    "description": "默认整包受保护；只在这里声明公开例外、强制保护、delegate 路径或 owner 覆盖。该字段会自动进入 settings runtime owner。",
+                },
+            }
+
+
+        __all__ = ["AppSettings"]
+        """
+    )
+
+
+__all__ = ["app_settings_template"]