ZZD public AI gateway · zzd_public_ai_gateway_v3
Resource: 09 · Publish and maintain / 生命周期
Canonical map: https://zzd.show/docs/ai/map.json
Full handbook: https://zzd.show/llms-full.txt
REST capabilities: https://zzd.show/api/v1/capabilities/

# Show lifecycle

Canonical state flow:

`authorized -> private hidden draft -> built_pending_validation ->
validated -> public visible -> maintained or unpublished`

## Create

- `POST /api/v1/shows/` always begins `private=true`,
  `hidden=true`; clients cannot override that draft state.
- Save accurate metadata and readable authoritative Pieces.
- Upload/bind assets and configure dependencies.
- Configure BaaS only when the product needs it.
- Keep a known-good baseline and validation matrix.

## Validate

Pass rendered-experience, live-source-quality, and environment-parity
checks. A build is only `built_pending_validation` until browser
evidence passes. Capture a fresh final-state screenshot, upload it
through `POST /api/v1/shows/{show_id}/thumbnail/`, and verify its
owner-scoped content route. REST verifies image bytes but does not
automate or prove the browser evidence.

## Publish

Public visibility is consequential. Ask the user to confirm, then
call `POST /api/v1/shows/{show_id}/publication/` with
`{"action":"publish","confirm":true}` and `shows:publish`:

- server preflight checks required metadata, prompt, thumbnail, and
  safe source structure;
- private developer assets and the verified thumbnail are promoted
  to public presentation copies only as publication succeeds;
- successful publication sets `private=false` and `hidden=false`;
- reopen detail, blank, editor preview, and embed;
- report stable returned URLs and remaining dependencies.

Server preflight does not run the browser validation matrix. A
public-but-hidden/link-only choice is available through the signed-in
product UI, not through the current binary REST publication action.

## Maintain

On every edit:

1. identify affected metadata, Pieces, assets, bindings, BaaS schema,
   and states;
2. preserve or record a last known-good version/duplicate before a
   risky change;
3. PATCH only intended metadata and PUT the complete intended Piece
   tree; Piece replacement is atomic, destructive replacement;
4. note that Piece replacement recreates authoritative rows with
   empty compiled state; draft-producing Show mutations set both
   `private=true` and `hidden=true` and remove promoted public asset/
   thumbnail copies while retaining private sources;
5. rerun the same state matrix in all environments;
6. POST a replacement verified thumbnail if the visible result changed;
7. summarize change, evidence, migration impact, and rollback path.

For BaaS schema changes, use additive/backward-compatible migration
when possible and protect existing user data. For dependency
upgrades, pin versions and compare timing, layout, render output, and
bundle behavior with the known-good version.

## Unpublish

Ask for confirmation before changing a public Show. REST v1 accepts
`{"action":"unpublish","confirm":true}` at the same publication
endpoint and sets both `private=true` and `hidden=true`. Use the
signed-in UI for a supported link-only/unlisted state. Recheck
Sale/buyer impact before restricting a bundled Show.

Deletion is destructive and is not part of the default deploy flow.
REST v1 exposes no deletion route.
Never delete a Show, asset, collection, or Sale without exact target
resolution, impact review, explicit user confirmation, and a
recoverable path where available.