pz-cli 5.0.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- pz_cli-5.0.0.dist-info/METADATA +51 -0
- pz_cli-5.0.0.dist-info/RECORD +399 -0
- pz_cli-5.0.0.dist-info/WHEEL +4 -0
- pz_cli-5.0.0.dist-info/entry_points.txt +5 -0
- pz_core/__init__.py +64 -0
- pz_core/__main__.py +7 -0
- pz_core/app.py +45 -0
- pz_core/assembly/__init__.py +17 -0
- pz_core/assembly/app_discovery.py +1240 -0
- pz_core/assembly/apps/__init__.py +25 -0
- pz_core/assembly/apps/compiler.py +824 -0
- pz_core/assembly/apps/providers.py +188 -0
- pz_core/assembly/cli/__init__.py +9 -0
- pz_core/assembly/cli/compiler.py +166 -0
- pz_core/assembly/diagnostics/__init__.py +21 -0
- pz_core/assembly/diagnostics/checks.py +257 -0
- pz_core/assembly/diagnostics/dev_sources.py +569 -0
- pz_core/assembly/events/__init__.py +5 -0
- pz_core/assembly/events/compiler.py +219 -0
- pz_core/assembly/extensions/__init__.py +5 -0
- pz_core/assembly/extensions/compiler.py +696 -0
- pz_core/assembly/infra/__init__.py +6 -0
- pz_core/assembly/infra/compiler.py +272 -0
- pz_core/assembly/lifecycle/__init__.py +5 -0
- pz_core/assembly/lifecycle/compiler.py +95 -0
- pz_core/assembly/middlewares/__init__.py +19 -0
- pz_core/assembly/middlewares/compiler.py +508 -0
- pz_core/assembly/project/__init__.py +7 -0
- pz_core/assembly/project/compiler.py +9 -0
- pz_core/assembly/project/context.py +17 -0
- pz_core/assembly/project/discovery.py +227 -0
- pz_core/assembly/resources/__init__.py +19 -0
- pz_core/assembly/resources/compiler.py +310 -0
- pz_core/assembly/resources/settings.py +129 -0
- pz_core/assembly/routes/__init__.py +7 -0
- pz_core/assembly/routes/compiler.py +400 -0
- pz_core/assembly/runtime_manifests/__init__.py +13 -0
- pz_core/assembly/runtime_manifests/compiler.py +159 -0
- pz_core/assembly/settings/__init__.py +17 -0
- pz_core/assembly/settings/compiler.py +786 -0
- pz_core/assembly/settings/host_project_overrides.py +82 -0
- pz_core/assembly/settings/host_runtime_endpoint.py +207 -0
- pz_core/authoring/__init__.py +79 -0
- pz_core/authoring/app_init_service.py +946 -0
- pz_core/authoring/app_versions.py +814 -0
- pz_core/authoring/cli.py +192 -0
- pz_core/authoring/commands.py +1810 -0
- pz_core/authoring/conflicts.py +180 -0
- pz_core/authoring/dev_bindings.py +916 -0
- pz_core/authoring/dev_git.py +1087 -0
- pz_core/authoring/dev_import.py +1061 -0
- pz_core/authoring/dev_manifest.py +522 -0
- pz_core/authoring/dev_sources.py +1638 -0
- pz_core/authoring/env_cli.py +454 -0
- pz_core/authoring/files.py +109 -0
- pz_core/authoring/ide_projection.py +1129 -0
- pz_core/authoring/naming.py +58 -0
- pz_core/authoring/official_dev_sources.py +432 -0
- pz_core/authoring/official_sources.json +156 -0
- pz_core/authoring/orchestration_service.py +558 -0
- pz_core/authoring/project_default.jsonc +53 -0
- pz_core/authoring/project_defaults.py +88 -0
- pz_core/authoring/project_metadata_service.py +199 -0
- pz_core/authoring/project_settings_checks.py +51 -0
- pz_core/authoring/project_settings_cli.py +299 -0
- pz_core/authoring/project_settings_service.py +1700 -0
- pz_core/authoring/project_state.py +399 -0
- pz_core/authoring/publish_git.py +423 -0
- pz_core/authoring/publish_lock.py +188 -0
- pz_core/authoring/publish_source.py +195 -0
- pz_core/authoring/release.py +1382 -0
- pz_core/authoring/repo_keys.py +29 -0
- pz_core/authoring/root_cli.py +28 -0
- pz_core/authoring/scaffold_service.py +325 -0
- pz_core/authoring/sync_service.py +787 -0
- pz_core/authoring/templates/app/__init__.py +1 -0
- pz_core/authoring/templates/app/api.py +25 -0
- pz_core/authoring/templates/app/apps.py +31 -0
- pz_core/authoring/templates/app/auth_package_init.py +14 -0
- pz_core/authoring/templates/app/auth_readme.py +29 -0
- pz_core/authoring/templates/app/configs_package_init.py +14 -0
- pz_core/authoring/templates/app/default_env.py +18 -0
- pz_core/authoring/templates/app/default_jsonc.py +25 -0
- pz_core/authoring/templates/app/locales_readme.py +25 -0
- pz_core/authoring/templates/app/migrations_readme.py +19 -0
- pz_core/authoring/templates/app/models.py +14 -0
- pz_core/authoring/templates/app/package_init.py +8 -0
- pz_core/authoring/templates/app/pages_base.py +161 -0
- pz_core/authoring/templates/app/pages_readme.py +25 -0
- pz_core/authoring/templates/app/public.py +31 -0
- pz_core/authoring/templates/app/pyproject.py +77 -0
- pz_core/authoring/templates/app/readme.py +74 -0
- pz_core/authoring/templates/app/settings.py +46 -0
- pz_core/authoring/templates/app/static_app_js.py +24 -0
- pz_core/authoring/templates/app/static_readme.py +31 -0
- pz_core/authoring/templates/app/template_config_page.py +23 -0
- pz_core/authoring/templates/app/template_index_html.py +28 -0
- pz_core/authoring/templates/app/templates_readme.py +32 -0
- pz_core/authoring/templates/app/urls.py +36 -0
- pz_core/authoring/templates/app/views.py +36 -0
- pz_core/authoring/templates/project/__init__.py +1 -0
- pz_core/authoring/templates/project/agents.py +51 -0
- pz_core/authoring/templates/project/apps_container_readme.py +37 -0
- pz_core/authoring/templates/project/main_py.py +59 -0
- pz_core/authoring/templates/project/project_env.py +19 -0
- pz_core/authoring/templates/project/pyproject.py +26 -0
- pz_core/authoring/templates/project/pz_env_env.py +65 -0
- pz_core/authoring/templates/project/pz_env_jsonc.py +69 -0
- pz_core/authoring/templates/project/pz_jsonc.py +12 -0
- pz_core/authoring/templates/project/readme.py +94 -0
- pz_core/authoring/templates/project/root_gitkeep.py +8 -0
- pz_core/authoring/templates/shared/__init__.py +5 -0
- pz_core/authoring/templates/shared/text.py +10 -0
- pz_core/authoring/venv_service.py +87 -0
- pz_core/authoring/workspace.py +167 -0
- pz_core/cli.py +291 -0
- pz_core/cli_options.py +74 -0
- pz_core/core/__init__.py +3 -0
- pz_core/core/errors/__init__.py +5 -0
- pz_core/core/errors/models.py +117 -0
- pz_core/core/events/__init__.py +5 -0
- pz_core/core/events/registry.py +54 -0
- pz_core/core/extensions/__init__.py +51 -0
- pz_core/core/extensions/registry.py +790 -0
- pz_core/core/health/__init__.py +6 -0
- pz_core/core/health/contracts.py +10 -0
- pz_core/core/middlewares/__init__.py +6 -0
- pz_core/core/middlewares/models.py +24 -0
- pz_core/core/routing/__init__.py +5 -0
- pz_core/core/routing/models.py +21 -0
- pz_core/core/settings_contracts.py +25 -0
- pz_core/docs/README.md +20 -0
- pz_core/docs/distribution-README.md +438 -0
- pz_core/docs/pz/345/221/275/344/273/244/346/200/273/350/247/210.md +1011 -0
- 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 +240 -0
- 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 +216 -0
- pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/02-/345/214/205/344/270/216/345/210/206/345/217/221/350/247/204/350/214/203.md +403 -0
- 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 +571 -0
- pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/04-Settings/344/270/216/351/205/215/347/275/256/350/247/204/350/214/203.md +1177 -0
- pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/05-/350/265/204/346/272/220/344/270/216/350/277/220/350/241/214/347/233/256/345/275/225/350/247/204/350/214/203.md +575 -0
- pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/06-/346/225/260/346/215/256/345/272/223/344/270/216/345/217/257/351/200/211/345/237/272/347/241/200/350/256/276/346/226/275/350/247/204/350/214/203.md +499 -0
- pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/07-App/346/233/277/346/215/242/350/247/204/350/214/203.md +206 -0
- pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/08-/345/271/263/345/217/260/347/272/247App/344/270/216/350/277/220/350/241/214/346/227/266/345/215/225/344/276/213/350/247/204/350/214/203.md +445 -0
- pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/09-CLI/344/270/216Worker/345/205/245/345/217/243/350/247/204/350/214/203.md +950 -0
- pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/10-/346/265/213/350/257/225/344/270/216/345/245/221/347/272/246/350/247/204/350/214/203.md +1001 -0
- pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/11-/344/273/223/345/272/223/347/234/237/347/233/270/346/272/220/345/234/260/345/233/276.md +102 -0
- pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/12-/346/236/204/345/273/272/344/270/216/345/217/221/345/270/203/346/243/200/346/237/245/346/270/205/345/215/225.md +171 -0
- pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/13-/346/255/243/345/274/217Facade/346/200/273/350/241/250.md +402 -0
- pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/14-/345/210/206/345/261/202/344/270/216/346/211/251/345/261/225/350/247/204/350/214/203.md +550 -0
- pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/15-/345/255/220/345/214/205/345/274/200/345/217/221/344/275/277/347/224/250/346/211/213/345/206/214.md +1004 -0
- pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/16-/346/211/251/345/261/225/347/202/271/346/255/243/345/274/217/345/215/217/350/256/256/346/270/205/345/215/225.md +352 -0
- pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/17-pz.protocols.v1/346/255/243/345/274/217/345/215/217/350/256/256.md +266 -0
- pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/18-/346/211/251/345/261/225/347/202/271/345/206/262/347/252/201/350/243/201/345/206/263/346/200/273/350/241/250.md +131 -0
- pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/19-/351/224/231/350/257/257/347/240/201/344/270/216/350/257/212/346/226/255/345/215/217/350/256/256.md +176 -0
- pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/20-/347/247/201/346/234/211/345/214/205/344/273/223/344/270/216/347/273/237/344/270/200/350/256/244/350/257/201/351/203/250/347/275/262/350/247/204/350/214/203.md +243 -0
- 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 +365 -0
- pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/22-/345/244/232/345/233/275/350/257/255/350/250/200/350/265/204/346/272/220/346/262/273/347/220/206/344/270/216/346/214/211/351/234/200/345/212/240/350/275/275/350/247/204/350/214/203.md +912 -0
- pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/23-/351/246/226/345/261/217/345/261/225/347/244/272/344/270/216/351/246/226/345/270/247/347/250/263/345/256/232/350/247/204/350/214/203.md +269 -0
- pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/24-pz/345/220/257/345/212/250/344/270/216/350/277/220/350/241/214/346/227/266/347/274/226/350/257/221/346/265/201/347/250/213.md +245 -0
- pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/25-/351/235/242/345/220/221/345/257/271/350/261/241/345/274/200/345/217/221/350/247/204/350/214/203.md +300 -0
- pz_core/docs/pz/350/247/204/350/214/203/344/270/216/344/275/277/347/224/250/README.md +98 -0
- 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/00-legacy_core/346/240/207/345/207/206pip/345/214/205/345/214/226/351/207/215/346/236/204/346/200/273/347/272/262.md +1073 -0
- 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/01-/347/233/256/345/275/225/344/270/216/345/210/206/345/261/202/351/207/215/346/236/204/346/211/247/350/241/214/346/226/271/346/241/210.md +224 -0
- 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/02-/345/214/205/344/270/216/345/210/206/345/217/221/350/247/204/350/214/203-/345/220/253/345/216/206/345/217/262/345/217/243/345/276/204.md +671 -0
- 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 +387 -0
- 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/14-/345/255/220/345/214/205/351/200/202/351/205/215/346/224/271/351/200/240/346/270/205/345/215/225.md +592 -0
- 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/15-infra/350/243/201/345/211/252/344/270/216/350/220/275/344/275/215/346/270/205/345/215/225.md +81 -0
- 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/19-core/345/215/225/344/270/200/346/255/243/345/274/217/346/226/271/346/241/210/346/224/266/346/225/233/346/211/247/350/241/214/346/270/205/345/215/225.md +161 -0
- 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/25-/345/215/217/350/256/256/345/210/260/346/272/220/347/240/201/345/267/256/350/267/235/346/270/205/345/215/225.md +377 -0
- 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/26-cutover/345/256/214/345/267/245/346/243/200/346/237/245/346/270/205/345/215/225.md +117 -0
- 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/29-/345/244/232/345/233/275/350/257/255/350/250/200/350/265/204/346/272/220/346/262/273/347/220/206/344/270/216/346/214/211/351/234/200/345/212/240/350/275/275/350/247/204/350/214/203-/345/220/253/350/277/201/347/247/273/347/255/226/347/225/245.md +956 -0
- 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/99-/350/265/204/346/272/220/346/224/266/345/217/243/345/220/216/347/273/255TODO.md +84 -0
- pz_core/docs//345/217/221/347/211/210/345/211/215/346/270/205/345/215/225-4.0.11.md +84 -0
- pz_core/docs//346/226/260/346/211/213/346/214/207/345/215/227.md +422 -0
- pz_core/infra/__init__.py +17 -0
- pz_core/infra/db/__init__.py +23 -0
- pz_core/infra/db/contracts.py +73 -0
- pz_core/infra/health/__init__.py +5 -0
- pz_core/infra/health/contracts.py +8 -0
- pz_core/infra/kv/__init__.py +5 -0
- pz_core/infra/kv/contracts.py +17 -0
- pz_core/infra/observability/__init__.py +23 -0
- pz_core/infra/observability/contracts.py +142 -0
- pz_core/infra/resilience/__init__.py +5 -0
- pz_core/infra/resilience/contracts.py +17 -0
- pz_core/infra/resources/__init__.py +5 -0
- pz_core/infra/resources/contracts.py +16 -0
- pz_core/infra/settings/__init__.py +17 -0
- pz_core/infra/settings/models.py +81 -0
- pz_core/infra/storage/__init__.py +5 -0
- pz_core/infra/storage/ports.py +27 -0
- pz_core/project_root_commands.py +282 -0
- pz_core/project_runtime_cli.py +344 -0
- pz_core/project_sources.py +253 -0
- pz_core/pz_launcher.py +209 -0
- pz_core/root_cli.py +70 -0
- pz_core/runtime/__init__.py +229 -0
- pz_core/runtime/access.py +86 -0
- pz_core/runtime/adapters/__init__.py +5 -0
- pz_core/runtime/adapters/base.py +18 -0
- pz_core/runtime/asyncio_bridge.py +18 -0
- pz_core/runtime/bindings/__init__.py +5 -0
- pz_core/runtime/bindings/container.py +50 -0
- pz_core/runtime/cli/__init__.py +5 -0
- pz_core/runtime/cli/_args.py +67 -0
- pz_core/runtime/cli/app_commands.py +417 -0
- pz_core/runtime/cli/check.py +214 -0
- pz_core/runtime/cli/db.py +297 -0
- pz_core/runtime/cli/main.py +89 -0
- pz_core/runtime/cli/resources.py +280 -0
- pz_core/runtime/discovery.py +23 -0
- pz_core/runtime/environment_integrity.py +157 -0
- pz_core/runtime/errors.py +5 -0
- pz_core/runtime/events.py +87 -0
- pz_core/runtime/facades/__init__.py +38 -0
- pz_core/runtime/facades/_capabilities.py +46 -0
- pz_core/runtime/facades/cache.py +103 -0
- pz_core/runtime/facades/database.py +71 -0
- pz_core/runtime/facades/events.py +380 -0
- pz_core/runtime/facades/health.py +101 -0
- pz_core/runtime/facades/mail.py +121 -0
- pz_core/runtime/facades/observability.py +102 -0
- pz_core/runtime/facades/providers.py +75 -0
- pz_core/runtime/facades/resources.py +52 -0
- pz_core/runtime/facades/storage.py +296 -0
- pz_core/runtime/health/__init__.py +5 -0
- pz_core/runtime/health/service.py +102 -0
- pz_core/runtime/host.py +188 -0
- pz_core/runtime/host_runner.py +282 -0
- pz_core/runtime/http/__init__.py +20 -0
- pz_core/runtime/http/app.py +576 -0
- pz_core/runtime/http_timing.py +173 -0
- pz_core/runtime/invocation.py +29 -0
- pz_core/runtime/json_safe.py +47 -0
- pz_core/runtime/lifecycle/__init__.py +25 -0
- pz_core/runtime/lifecycle/manager.py +533 -0
- pz_core/runtime/plan.py +214 -0
- pz_core/runtime/plan_context.py +33 -0
- pz_core/runtime/plan_snapshot.py +177 -0
- pz_core/runtime/registries/__init__.py +27 -0
- pz_core/runtime/registries/capabilities.py +101 -0
- pz_core/runtime/registries/providers.py +396 -0
- pz_core/runtime/resource_assets.py +344 -0
- pz_core/runtime/run_cli.py +211 -0
- pz_core/runtime/settings.py +888 -0
- pz_core/runtime/worker/__init__.py +21 -0
- pz_core/runtime/worker/engine.py +921 -0
- pz_core/runtime/worker/runtime.py +25 -0
- pz_core/testing/__init__.py +15 -0
- pz_core/testing/doc_route_contracts.py +305 -0
- pz_core/utils/__init__.py +44 -0
- pz_core/utils/env.py +65 -0
- pz_core/utils/project_jsonc/__init__.py +29 -0
- pz_core/utils/project_jsonc/document.py +420 -0
- pz_core/utils/project_settings.py +99 -0
- pz_foundation/__init__.py +50 -0
- pz_foundation/_contracts.py +81 -0
- pz_foundation/_errors.py +34 -0
- pz_foundation/api.py +14 -0
- pz_foundation/apps.py +127 -0
- pz_foundation/auth/__init__.py +1 -0
- pz_foundation/cache_control.py +233 -0
- pz_foundation/cli/__init__.py +2 -0
- pz_foundation/cli/workers.py +565 -0
- pz_foundation/configs/__init__.py +0 -0
- pz_foundation/configs/default.env +15 -0
- pz_foundation/configs/default.jsonc +452 -0
- pz_foundation/db/__init__.py +94 -0
- pz_foundation/db/aerich_executor.py +664 -0
- pz_foundation/db/config.py +358 -0
- pz_foundation/db/connection_manager.py +689 -0
- pz_foundation/db/connection_probe.py +204 -0
- pz_foundation/db/database.py +1291 -0
- pz_foundation/db/deps.py +47 -0
- pz_foundation/db/lifecycle_status.py +85 -0
- pz_foundation/db/migrations.py +477 -0
- pz_foundation/db/mysql.py +57 -0
- pz_foundation/db/postgresql.py +409 -0
- pz_foundation/db/production_pool_fallback.py +143 -0
- pz_foundation/db/public.py +45 -0
- pz_foundation/db/session.py +369 -0
- pz_foundation/db/sqlite.py +15 -0
- pz_foundation/db/tortoise_manager.py +724 -0
- pz_foundation/db/tortoise_psycopg.py +148 -0
- pz_foundation/docs/README.md +18 -0
- pz_foundation/docs/distribution-README.md +319 -0
- pz_foundation/docs/infra/350/243/201/345/211/252/344/270/216/350/220/275/344/275/215/350/257/264/346/230/216.md +39 -0
- pz_foundation/docs//345/205/254/345/274/200/345/205/215/350/264/271/346/216/245/345/217/243/351/230/262/346/273/245/347/224/250/344/270/216/344/272/272/346/234/272/346/240/241/351/252/214.md +680 -0
- pz_foundation/docs//350/256/276/350/256/241/346/226/207/346/241/243.md +288 -0
- pz_foundation/docs//350/267/257/347/224/261/344/270/216URL/345/244/204/347/220/206/350/247/204/350/214/203.md +119 -0
- pz_foundation/health.py +105 -0
- pz_foundation/host/__init__.py +11 -0
- pz_foundation/host/builder.py +34 -0
- pz_foundation/host/cache_runtime.py +44 -0
- pz_foundation/host/db/__init__.py +17 -0
- pz_foundation/host/db/aerich_config.py +36 -0
- pz_foundation/host/db/config.py +106 -0
- pz_foundation/host/db/connection_manager.py +48 -0
- pz_foundation/host/db/deps.py +5 -0
- pz_foundation/host/db/orm_retry_patch.py +566 -0
- pz_foundation/host/db/request_adapter.py +325 -0
- pz_foundation/host/db/router.py +28 -0
- pz_foundation/host/db/session.py +284 -0
- pz_foundation/host/db/tortoise_manager.py +10 -0
- pz_foundation/host/idempotency.py +132 -0
- pz_foundation/host/lifespan.py +247 -0
- pz_foundation/host/redis_runtime.py +100 -0
- pz_foundation/host/web.py +790 -0
- pz_foundation/infra_provider.py +236 -0
- pz_foundation/kv/__init__.py +25 -0
- pz_foundation/kv/cache.py +1166 -0
- pz_foundation/kv/deps.py +84 -0
- pz_foundation/kv/public.py +25 -0
- pz_foundation/kv/redis_manager.py +1531 -0
- pz_foundation/lazy_exports.py +43 -0
- pz_foundation/lazy_imports.py +124 -0
- pz_foundation/lifecycle.py +392 -0
- pz_foundation/managed_workers.py +1117 -0
- pz_foundation/middlewares/__init__.py +26 -0
- pz_foundation/middlewares/_settings.py +250 -0
- pz_foundation/middlewares/analytics.py +124 -0
- pz_foundation/middlewares/cache_control.py +156 -0
- pz_foundation/middlewares/compression.py +202 -0
- pz_foundation/middlewares/cors.py +62 -0
- pz_foundation/middlewares/geo_country.py +44 -0
- pz_foundation/middlewares/inner_router.py +50 -0
- pz_foundation/middlewares/rate_limited/__init__.py +3 -0
- pz_foundation/middlewares/rate_limited/key_limiter.py +115 -0
- pz_foundation/middlewares/request_logging.py +104 -0
- pz_foundation/middlewares/route_owner.py +309 -0
- pz_foundation/middlewares/security_csrf.py +44 -0
- pz_foundation/middlewares/security_headers/__init__.py +4 -0
- pz_foundation/middlewares/security_headers/conflicts.py +44 -0
- pz_foundation/middlewares/security_headers/csp_nonce.py +200 -0
- pz_foundation/middlewares/security_headers/security_headers.py +44 -0
- pz_foundation/migrations/__init__.py +1 -0
- pz_foundation/migrations/pz_foundation/__init__.py +1 -0
- pz_foundation/models.py +22 -0
- pz_foundation/notifications/__init__.py +23 -0
- pz_foundation/notifications/email.py +542 -0
- pz_foundation/notifications/public.py +31 -0
- pz_foundation/observability/__init__.py +71 -0
- pz_foundation/observability/http.py +34 -0
- pz_foundation/observability/logger/__init__.py +49 -0
- pz_foundation/observability/logger/_bot_settings.py +126 -0
- pz_foundation/observability/logger/bot_message.py +592 -0
- pz_foundation/observability/logger/core.py +385 -0
- pz_foundation/observability/logger/delivery_audit.py +84 -0
- pz_foundation/observability/logger/feishu_bot.py +199 -0
- pz_foundation/observability/logger/telegram_bot.py +194 -0
- pz_foundation/observability/metrics.py +365 -0
- pz_foundation/observability/runtime.py +68 -0
- pz_foundation/public.py +405 -0
- pz_foundation/resources/__init__.py +12 -0
- pz_foundation/resources/builder.py +900 -0
- pz_foundation/resources/images.py +363 -0
- pz_foundation/root_cli.py +20 -0
- pz_foundation/routing/__init__.py +203 -0
- pz_foundation/routing/canonical.py +486 -0
- pz_foundation/routing/convertors.py +82 -0
- pz_foundation/routing/declarations.py +843 -0
- pz_foundation/routing/exports.py +148 -0
- pz_foundation/routing/loaders.py +138 -0
- pz_foundation/routing/manifest.py +215 -0
- pz_foundation/routing/manifest_provider.py +47 -0
- pz_foundation/routing/mounts.py +101 -0
- pz_foundation/routing/ordering.py +172 -0
- pz_foundation/routing/registry.py +133 -0
- pz_foundation/routing/utils.py +28 -0
- pz_foundation/runtime.py +234 -0
- pz_foundation/settings.py +253 -0
- pz_foundation/settings_normalization.py +130 -0
- pz_foundation/storage/__init__.py +25 -0
- pz_foundation/storage/local.py +209 -0
- pz_foundation/storage/public.py +106 -0
- pz_foundation/storage/s3.py +116 -0
- pz_foundation/storage/service.py +234 -0
- pz_foundation/urls.py +19 -0
- pz_foundation/utils/__init__.py +6 -0
- pz_foundation/utils/merge.py +160 -0
- pz_foundation/worker_replicas.py +55 -0
- pz_settings_center/__init__.py +5 -0
- pz_settings_center/api/__init__.py +5 -0
- pz_settings_center/api/runtime_overrides.py +360 -0
- pz_settings_center/apps.py +28 -0
- pz_settings_center/configs/__init__.py +0 -0
- pz_settings_center/configs/default.env +2 -0
- pz_settings_center/configs/default.jsonc +1 -0
- pz_settings_center/docs/01-settings_center/350/203/275/345/212/233/350/276/271/347/225/214.md +124 -0
- pz_settings_center/docs/README.md +12 -0
- pz_settings_center/docs/distribution-README.md +150 -0
- pz_settings_center/docs//350/256/276/350/256/241/346/226/207/346/241/243.md +48 -0
- pz_settings_center/integration_payload.py +18 -0
- pz_settings_center/project_helpers.py +405 -0
- pz_settings_center/public.py +139 -0
- pz_settings_center/routing_helpers.py +73 -0
- pz_settings_center/runtime_override_provider.py +61 -0
- pz_settings_center/typed_settings.py +324 -0
- pz_settings_center/urls.py +9 -0
|
@@ -0,0 +1,300 @@
|
|
|
1
|
+
# 面向对象开发规范
|
|
2
|
+
|
|
3
|
+
本文档固定 `pz` 体系下的面向对象开发口径。
|
|
4
|
+
|
|
5
|
+
适用范围:
|
|
6
|
+
|
|
7
|
+
- `pz` 基础层
|
|
8
|
+
- `pz_contrib` 官方子包
|
|
9
|
+
- 平台 / 站点 / 业务最小子包
|
|
10
|
+
- 宿主项目中少量必要装配代码
|
|
11
|
+
|
|
12
|
+
本文不是要求所有代码都写成 class。纯函数、数据转换、schema 校验、常量定义仍然可以保持函数式或声明式。本文要求的是:凡是存在身份、生命周期、状态、不变量、依赖协作或跨模块合同的能力,必须用清晰对象边界表达,而不是散落成全局函数、模块级状态和隐式调用顺序。
|
|
13
|
+
|
|
14
|
+
## 1. 总原则
|
|
15
|
+
|
|
16
|
+
- 对象表达边界:一个类或对象必须代表一个清晰领域概念、运行时资源、协议实现、facade、adapter、service 或编译产物。
|
|
17
|
+
- 状态归 owner:状态只能归拥有该状态生命周期的对象;不得散落在模块级全局变量、临时 dict、隐藏 cache 或 import-time 单例里。
|
|
18
|
+
- 行为靠对象承载:和状态、不变量、生命周期强相关的行为应放回 owner 对象,不要长期放在远离数据的 helper 函数里。
|
|
19
|
+
- 依赖显式注入:对象依赖应通过构造参数、factory、context 或 `RuntimePlan` 显式传入;不得在对象内部临时 import 具体高层实现来绕过 contract。
|
|
20
|
+
- 组合优先继承:默认使用组合、Protocol、provider、strategy、adapter;只有明确稳定的 is-a 合同成立时才允许继承。
|
|
21
|
+
- 接口隔离:跨层公开面必须窄而稳定;不要暴露胖 service,也不要让调用方知道实现对象的内部字段。
|
|
22
|
+
- 编译产物不可变:`RuntimePlan`、manifest、snapshot、registry projection 等编译产物应视为不可变对象;执行阶段只能消费,不得原地改写。
|
|
23
|
+
- 生命周期对称:创建、绑定、启动、释放必须由同一个 owner 对象或明确的 lifecycle manager 负责。
|
|
24
|
+
|
|
25
|
+
## 2. PZ 对象分层
|
|
26
|
+
|
|
27
|
+
`pz` 的分层必须映射到对象职责,而不是只映射到目录名。
|
|
28
|
+
|
|
29
|
+
### 2.1 契约对象
|
|
30
|
+
|
|
31
|
+
用于表达稳定协议和跨包合同。
|
|
32
|
+
|
|
33
|
+
典型对象:
|
|
34
|
+
|
|
35
|
+
- `AppSpec`
|
|
36
|
+
- `ExtensionSpec`
|
|
37
|
+
- `SettingsProviderSpec`
|
|
38
|
+
- `HostBuilderSpec`
|
|
39
|
+
- `RuntimePlan`
|
|
40
|
+
- `SettingsSnapshot`
|
|
41
|
+
- `ResourceManifest`
|
|
42
|
+
|
|
43
|
+
要求:
|
|
44
|
+
|
|
45
|
+
- 只表达合同、字段、不变量和版本语义。
|
|
46
|
+
- 不持有运行期副作用资源。
|
|
47
|
+
- 不在 import 阶段读取项目配置、环境变量、数据库、网络或文件系统运行态。
|
|
48
|
+
|
|
49
|
+
### 2.2 编译对象
|
|
50
|
+
|
|
51
|
+
用于把声明输入编译成不可变产物。
|
|
52
|
+
|
|
53
|
+
典型对象:
|
|
54
|
+
|
|
55
|
+
- compiler
|
|
56
|
+
- resolver
|
|
57
|
+
- validator
|
|
58
|
+
- conflict detector
|
|
59
|
+
- manifest builder
|
|
60
|
+
|
|
61
|
+
要求:
|
|
62
|
+
|
|
63
|
+
- 输入显式,输出明确。
|
|
64
|
+
- 负责裁决,不负责启动运行时资源。
|
|
65
|
+
- 不直接调用 Web、CLI、worker 的执行副作用。
|
|
66
|
+
- 同类规则只能有一个正式 compiler;不要让入口层、adapter 层、业务子包各自重写扫描或裁决。
|
|
67
|
+
|
|
68
|
+
### 2.3 Runtime Owner 对象
|
|
69
|
+
|
|
70
|
+
用于拥有运行时资源和生命周期。
|
|
71
|
+
|
|
72
|
+
典型对象:
|
|
73
|
+
|
|
74
|
+
- host runtime
|
|
75
|
+
- worker runtime
|
|
76
|
+
- browser/session/runtime owner
|
|
77
|
+
- DB/cache/storage/mail/metrics owner
|
|
78
|
+
- task/queue/registry owner
|
|
79
|
+
|
|
80
|
+
要求:
|
|
81
|
+
|
|
82
|
+
- owner 负责资源 acquire/release、heartbeat、health、shutdown。
|
|
83
|
+
- owner 暴露稳定 facade 或 capability,不暴露内部 client、pool、session、临时 cache。
|
|
84
|
+
- 同一个运行时资源只能有一个 owner;其它对象只能借用 owner 的 facade。
|
|
85
|
+
|
|
86
|
+
### 2.4 Facade / Capability 对象
|
|
87
|
+
|
|
88
|
+
用于跨层或跨包消费。
|
|
89
|
+
|
|
90
|
+
要求:
|
|
91
|
+
|
|
92
|
+
- 调用方只依赖 facade/capability contract。
|
|
93
|
+
- facade 不反向依赖具体入口,不持有宿主路径特判。
|
|
94
|
+
- facade 只暴露业务上必要的方法,不把内部 registry、settings、client 原样泄露出去。
|
|
95
|
+
|
|
96
|
+
### 2.5 Provider / Strategy / Adapter 对象
|
|
97
|
+
|
|
98
|
+
用于实现可替换能力。
|
|
99
|
+
|
|
100
|
+
要求:
|
|
101
|
+
|
|
102
|
+
- provider 负责“提供某类输入”,consumer 负责“统一消费与装配”。
|
|
103
|
+
- strategy 负责可替换算法,不负责持有全局状态。
|
|
104
|
+
- adapter 负责第三方 SDK、HTTP、DB、CLI、浏览器等外部系统适配,不把外部 SDK 类型泄露到上层合同。
|
|
105
|
+
|
|
106
|
+
## 3. 类与函数的边界
|
|
107
|
+
|
|
108
|
+
优先使用类的场景:
|
|
109
|
+
|
|
110
|
+
- 有稳定身份,例如 actor、app、runtime、worker、lease、session、tool、provider。
|
|
111
|
+
- 有生命周期,例如 acquire/start/heartbeat/stop/release。
|
|
112
|
+
- 有不变量,例如 account binding、route policy、task lease、resource manifest。
|
|
113
|
+
- 有多方法协作,例如 compiler、manager、facade、repository、adapter。
|
|
114
|
+
- 需要替换实现,例如 provider、strategy、runtime engine。
|
|
115
|
+
|
|
116
|
+
优先使用函数的场景:
|
|
117
|
+
|
|
118
|
+
- 纯数据转换。
|
|
119
|
+
- 小范围校验。
|
|
120
|
+
- 无状态格式化。
|
|
121
|
+
- 单步骤算法,且不需要被替换或持有依赖。
|
|
122
|
+
|
|
123
|
+
禁止把类当作函数集合:
|
|
124
|
+
|
|
125
|
+
- 只有一堆 `@staticmethod` 且没有对象语义的类,应改为模块函数或真实对象。
|
|
126
|
+
- 只保存外部传入 dict、没有不变量和行为的类,应改为 typed model / dataclass / Pydantic model。
|
|
127
|
+
- 名为 `Manager` / `Service` 但同时做 settings、IO、编译、执行、展示的类,必须拆分职责。
|
|
128
|
+
|
|
129
|
+
## 4. 依赖倒置写法
|
|
130
|
+
|
|
131
|
+
正式依赖方向:
|
|
132
|
+
|
|
133
|
+
- 高层编排依赖 Protocol / Spec / Facade。
|
|
134
|
+
- 具体实现依赖稳定合同。
|
|
135
|
+
- 组合根负责把具体实现注入合同。
|
|
136
|
+
|
|
137
|
+
推荐写法:
|
|
138
|
+
|
|
139
|
+
```python
|
|
140
|
+
class BrowserTool(Protocol):
|
|
141
|
+
def run(self, command: BrowserCommand) -> BrowserResult: ...
|
|
142
|
+
|
|
143
|
+
|
|
144
|
+
class ActorTaskExecutor:
|
|
145
|
+
def __init__(self, *, browser_tool: BrowserTool, memory: ActorMemory) -> None:
|
|
146
|
+
self._browser_tool = browser_tool
|
|
147
|
+
self._memory = memory
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
不推荐:
|
|
151
|
+
|
|
152
|
+
```python
|
|
153
|
+
class ActorTaskExecutor:
|
|
154
|
+
def run(self, command):
|
|
155
|
+
from agent_tools.browser import run_browser_flow
|
|
156
|
+
return run_browser_flow(command)
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
说明:
|
|
160
|
+
|
|
161
|
+
- import 可以出现在模块顶部依赖稳定 public surface。
|
|
162
|
+
- 具体实现选择应发生在 factory、registry、RuntimePlan activation 或 owner runtime 中。
|
|
163
|
+
- 业务对象不应在方法内部临时 import 另一个 app 的内部模块来绕过合同。
|
|
164
|
+
|
|
165
|
+
## 5. 组合根
|
|
166
|
+
|
|
167
|
+
每个运行链路只能有一个组合根。
|
|
168
|
+
|
|
169
|
+
在 `pz` 基础层,组合根是 `RuntimePlan` 及其 activation。
|
|
170
|
+
|
|
171
|
+
在子包内部,也必须有自己的局部组合根,例如:
|
|
172
|
+
|
|
173
|
+
- `AgentLauncher`
|
|
174
|
+
- `AgentManager`
|
|
175
|
+
- `TaskCenterRuntime`
|
|
176
|
+
- `BrowserRuntime`
|
|
177
|
+
- `PageCenterRuntime`
|
|
178
|
+
- `SeoProviderChain`
|
|
179
|
+
|
|
180
|
+
组合根职责:
|
|
181
|
+
|
|
182
|
+
- 读取已编译输入。
|
|
183
|
+
- 选择具体实现。
|
|
184
|
+
- 构造对象图。
|
|
185
|
+
- 绑定生命周期。
|
|
186
|
+
- 暴露 facade。
|
|
187
|
+
|
|
188
|
+
组合根不应:
|
|
189
|
+
|
|
190
|
+
- 把所有业务逻辑吞进自己。
|
|
191
|
+
- 让下游对象再自行重建第二套对象图。
|
|
192
|
+
- 在运行中修改编译阶段产物。
|
|
193
|
+
|
|
194
|
+
## 6. Provider 设计纪律
|
|
195
|
+
|
|
196
|
+
provider 是对象,不是随处调用的函数集合。
|
|
197
|
+
|
|
198
|
+
正式要求:
|
|
199
|
+
|
|
200
|
+
- provider 必须有稳定输入 context。
|
|
201
|
+
- provider 必须返回结构化结果。
|
|
202
|
+
- provider 应幂等、可重复调用。
|
|
203
|
+
- provider 不直接改写全局状态。
|
|
204
|
+
- provider 不直接启动长期运行资源。
|
|
205
|
+
- provider 的实现模块可以私有,但声明必须通过正式 `apps.py` / `extensions()` / CLI spec 进入编译主链。
|
|
206
|
+
|
|
207
|
+
consumer / assembler 负责:
|
|
208
|
+
|
|
209
|
+
- provider 排序。
|
|
210
|
+
- 冲突裁决。
|
|
211
|
+
- 合并结果。
|
|
212
|
+
- 诊断输出。
|
|
213
|
+
- 运行期 facade 暴露。
|
|
214
|
+
|
|
215
|
+
不要让每个 provider 自己决定全局装配结果。
|
|
216
|
+
|
|
217
|
+
## 7. 最小子包内部推荐对象结构
|
|
218
|
+
|
|
219
|
+
业务复杂度较低时,不需要强行创建目录。复杂度上来后,推荐按职责自然拆分:
|
|
220
|
+
|
|
221
|
+
- `models.py` / `models/`:领域模型、持久化模型、typed value object。
|
|
222
|
+
- `contracts.py`:本子包对外稳定合同、Protocol、命令 / 结果对象。
|
|
223
|
+
- `facade.py`:对外消费面。
|
|
224
|
+
- `runtime.py`:运行时组合根或 runtime owner。
|
|
225
|
+
- `service/`:应用服务,只编排领域对象和 repository,不拥有框架装配。
|
|
226
|
+
- `repository/`:持久化访问,不承担业务决策。
|
|
227
|
+
- `adapters/`:外部系统适配。
|
|
228
|
+
- `providers/`:正式 provider 实现。
|
|
229
|
+
- `public.py`:只导出稳定 facade / contract,不导出内部 helper。
|
|
230
|
+
|
|
231
|
+
不得为了“分层好看”机械造目录;只有职责真实分离时才拆。
|
|
232
|
+
|
|
233
|
+
## 8. 命名约束
|
|
234
|
+
|
|
235
|
+
- `*Spec`:声明期协议对象。
|
|
236
|
+
- `*Snapshot`:编译后的配置快照。
|
|
237
|
+
- `*Manifest`:编译后的注册清单。
|
|
238
|
+
- `*Plan`:运行图。
|
|
239
|
+
- `*Context`:一次调用或一次编译所需上下文。
|
|
240
|
+
- `*Facade`:稳定消费面。
|
|
241
|
+
- `*Provider`:向主链提供某类输入。
|
|
242
|
+
- `*Adapter`:外部系统适配。
|
|
243
|
+
- `*Runtime`:拥有运行时资源和生命周期。
|
|
244
|
+
- `*Manager`:只在确实管理多个同类 runtime/resource/lease 时使用。
|
|
245
|
+
- `*Service`:应用服务;不得变成万能杂物类。
|
|
246
|
+
|
|
247
|
+
禁止用模糊名字掩盖职责:
|
|
248
|
+
|
|
249
|
+
- `utils`
|
|
250
|
+
- `helpers`
|
|
251
|
+
- `common`
|
|
252
|
+
- `manager`
|
|
253
|
+
- `service`
|
|
254
|
+
|
|
255
|
+
这些名字只有在范围极小且职责明确时才允许存在。
|
|
256
|
+
|
|
257
|
+
## 9. 反模式
|
|
258
|
+
|
|
259
|
+
明确禁止:
|
|
260
|
+
|
|
261
|
+
- import-time 创建运行时对象、DB client、HTTP client、浏览器 session、worker、registry。
|
|
262
|
+
- 模块级可变全局状态充当运行时真相源。
|
|
263
|
+
- 在入口层绕过 facade 直接操作内部 repository / adapter。
|
|
264
|
+
- 在业务对象内部读取 `os.environ`、项目配置文件或 app 默认模板。
|
|
265
|
+
- 把 dict 在多层之间传递,靠调用方记住字段含义。
|
|
266
|
+
- 用继承表达“想复用几行代码”,而不是表达稳定 is-a 合同。
|
|
267
|
+
- 让一个 `Manager` 同时负责编译、执行、存储、网络、诊断、CLI 输出。
|
|
268
|
+
- 为同一能力同时保留函数入口、类入口、CLI 入口和 registry 入口,且语义不完全一致。
|
|
269
|
+
- 直接把第三方 SDK 对象暴露为跨包公开面。
|
|
270
|
+
|
|
271
|
+
## 10. 开发流程
|
|
272
|
+
|
|
273
|
+
新增或重构能力时,先写清楚下面几个问题,再动代码:
|
|
274
|
+
|
|
275
|
+
1. 这个能力的 owner 是谁?
|
|
276
|
+
2. 它是声明期对象、编译对象、runtime owner、facade、provider、adapter,还是纯函数?
|
|
277
|
+
3. 它拥有什么状态?状态生命周期由谁关闭?
|
|
278
|
+
4. 它依赖哪些能力?这些依赖是否已经有 public surface / Protocol / provider contract?
|
|
279
|
+
5. 它输出什么稳定对象?调用方是否需要知道内部实现?
|
|
280
|
+
6. 它会不会形成第二套真相源?
|
|
281
|
+
7. 它的替换点在哪里?测试如何替换实现?
|
|
282
|
+
|
|
283
|
+
如果回答不清楚,不应通过新增 helper、全局变量或临时 import 继续推进。
|
|
284
|
+
|
|
285
|
+
## 11. 代码评审检查清单
|
|
286
|
+
|
|
287
|
+
评审时至少检查:
|
|
288
|
+
|
|
289
|
+
- 对象是否有单一职责。
|
|
290
|
+
- 状态是否归明确 owner。
|
|
291
|
+
- 依赖是否通过 contract / facade / provider 注入。
|
|
292
|
+
- 编译阶段和执行阶段是否分离。
|
|
293
|
+
- 是否有 import-time 副作用。
|
|
294
|
+
- 是否绕过 `RuntimePlan` 或子包自己的组合根。
|
|
295
|
+
- 是否新增第二套 registry / loader / settings reader / path helper。
|
|
296
|
+
- 是否把内部模块变成跨包依赖。
|
|
297
|
+
- 是否为了复用代码滥用继承。
|
|
298
|
+
- 是否为同一问题保留两套入口。
|
|
299
|
+
|
|
300
|
+
这份清单是开发约束,不只是重构建议。
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
# pz 规范与使用
|
|
2
|
+
|
|
3
|
+
本目录用于沉淀 `pz` 最终态架构下的正式规范、使用约定与持续演进边界。
|
|
4
|
+
|
|
5
|
+
## 设计依据
|
|
6
|
+
|
|
7
|
+
如果本 README 与正式设计文档、正式 contract 或正式装配约定冲突,以对应主题设计文档为准。
|
|
8
|
+
|
|
9
|
+
建议优先阅读:
|
|
10
|
+
|
|
11
|
+
- [`00-pz架构总纲`](./00-pz架构总纲.md)
|
|
12
|
+
- [`01-目录与分层规范`](./01-目录与分层规范.md)
|
|
13
|
+
- [`03-App最小子包规范`](./03-App最小子包规范.md)
|
|
14
|
+
- [`10-测试与契约规范`](./10-测试与契约规范.md)
|
|
15
|
+
- [`14-分层与扩展规范`](./14-分层与扩展规范.md)
|
|
16
|
+
- [`15-子包开发使用手册`](./15-子包开发使用手册.md)
|
|
17
|
+
- [`21-contrib约定与Provider接入规范`](./21-contrib约定与Provider接入规范.md)
|
|
18
|
+
- [`23-首屏展示与首帧稳定规范`](./23-首屏展示与首帧稳定规范.md)
|
|
19
|
+
- [`24-pz启动与运行时编译流程`](./24-pz启动与运行时编译流程.md)
|
|
20
|
+
- [`25-面向对象开发规范`](./25-面向对象开发规范.md)
|
|
21
|
+
|
|
22
|
+
## 架构公约
|
|
23
|
+
|
|
24
|
+
本目录所有正式文档统一服从下面这条最高优先级公约:
|
|
25
|
+
|
|
26
|
+
- `pz` 是唯一正式基础包,也是唯一可独立启动的包。
|
|
27
|
+
- 必须区分源码 / 分层依赖与 distribution 安装依赖;默认安装组合不等于源码边界反转。
|
|
28
|
+
- 除 `pz` 外,系统里真正存在的正式运行单元只有最小子包。
|
|
29
|
+
- 应用层 settings surface 由正式 settings surface owner 提供;应用层运行时代码统一通过该 owner 的公开面读取配置。
|
|
30
|
+
- 顶层源码组织根只用于 Git 与源码组织,不再是正式架构层,不进入 Python import namespace。
|
|
31
|
+
- 正式 import 单位、正式安装单位、正式 app 身份、正式源码目录必须对齐到同一个最小子包,不保留集合层 namespace。
|
|
32
|
+
- `installed_apps` 的正式语法固定为“写目录名”。目录名可以是最小子包名,也可以是容器目录名;框架负责按稳定顺序递归发现容器中嵌套的最小子包。
|
|
33
|
+
- 每个最小子包必须有稳定唯一的 `app_id`,settings namespace 必须与 `app_id` 一致。
|
|
34
|
+
- 新建子包默认让目录名、import 包名与 `app_id` 对齐,distribution 使用对应的 Python 分发名;不强制特定技术前缀。
|
|
35
|
+
- 历史子包已发布的 `app_id` 以稳定值为准,不因文档命名口径变化自动迁移。
|
|
36
|
+
|
|
37
|
+
## 文档生命周期
|
|
38
|
+
|
|
39
|
+
- 当前目录根部只保留最终态正式设计、正式规范、使用手册与长期治理约束。
|
|
40
|
+
- 迁移步骤、cutover 记录、差距清单、执行清单、TODO 等中间态内容只保留在 [`archive/中间态`](./archive/中间态/)。
|
|
41
|
+
- 正式设计文档不得把历史过程当作当前架构事实;需要引用历史背景时,只能指向 archive。
|
|
42
|
+
|
|
43
|
+
## 正式文档
|
|
44
|
+
|
|
45
|
+
主干规范:
|
|
46
|
+
|
|
47
|
+
- `00-pz架构总纲.md`
|
|
48
|
+
- `01-目录与分层规范.md`
|
|
49
|
+
- `02-包与分发规范.md`
|
|
50
|
+
- `03-App最小子包规范.md`
|
|
51
|
+
- `04-Settings与配置规范.md`
|
|
52
|
+
- `05-资源与运行目录规范.md`
|
|
53
|
+
- `06-数据库与可选基础设施规范.md`
|
|
54
|
+
- `07-App替换规范.md`
|
|
55
|
+
- `08-平台级App与运行时单例规范.md`
|
|
56
|
+
- `09-CLI与Worker入口规范.md`
|
|
57
|
+
- `10-测试与契约规范.md`
|
|
58
|
+
- `11-仓库真相源地图.md`
|
|
59
|
+
- `12-构建与发布检查清单.md`
|
|
60
|
+
- `24-pz启动与运行时编译流程.md`
|
|
61
|
+
|
|
62
|
+
长期治理与使用文档:
|
|
63
|
+
|
|
64
|
+
- `13-正式Facade总表.md`
|
|
65
|
+
- `14-分层与扩展规范.md`
|
|
66
|
+
- `15-子包开发使用手册.md`
|
|
67
|
+
- `16-扩展点正式协议清单.md`
|
|
68
|
+
- `17-pz.protocols.v1正式协议.md`
|
|
69
|
+
- `18-扩展点冲突裁决总表.md`
|
|
70
|
+
- `19-错误码与诊断协议.md`
|
|
71
|
+
- `20-私有包仓与统一认证部署规范.md`
|
|
72
|
+
- `21-contrib约定与Provider接入规范.md`
|
|
73
|
+
- `22-多国语言资源治理与按需加载规范.md`
|
|
74
|
+
- `23-首屏展示与首帧稳定规范.md`
|
|
75
|
+
- `25-面向对象开发规范.md`
|
|
76
|
+
|
|
77
|
+
历史中间态:
|
|
78
|
+
|
|
79
|
+
- `archive/中间态/00-legacy_core标准pip包化重构总纲.md`
|
|
80
|
+
- `archive/中间态/01-目录与分层重构执行方案.md`
|
|
81
|
+
- `archive/中间态/02-包与分发规范-含历史口径.md`
|
|
82
|
+
- `archive/中间态/13-一次性实施清单.md`
|
|
83
|
+
- `archive/中间态/14-子包适配改造清单.md`
|
|
84
|
+
- `archive/中间态/15-infra裁剪与落位清单.md`
|
|
85
|
+
- `archive/中间态/19-core单一正式方案收敛执行清单.md`
|
|
86
|
+
- `archive/中间态/25-协议到源码差距清单.md`
|
|
87
|
+
- `archive/中间态/26-cutover完工检查清单.md`
|
|
88
|
+
- `archive/中间态/29-多国语言资源治理与按需加载规范-含迁移策略.md`
|
|
89
|
+
- `archive/中间态/99-资源收口后续TODO.md`
|
|
90
|
+
|
|
91
|
+
## 阅读顺序
|
|
92
|
+
|
|
93
|
+
1. 先看 `00-pz架构总纲.md`。
|
|
94
|
+
2. 再看 `01-目录与分层规范.md`。
|
|
95
|
+
3. 然后按主题看 `02` 至 `12`。
|
|
96
|
+
4. 进入治理或新增子包时,再看 `13` 至 `19`、`21` 至 `25`。
|
|
97
|
+
5. 涉及私有包仓、上传、下载安装与统一认证时,再看 `20`。
|
|
98
|
+
6. 只有需要追溯历史决策或迁移记录时,才阅读 `archive/中间态/`。
|