docs: add application initialization contract to user-points protocol

This commit is contained in:
qzl
2026-04-13 11:35:15 +08:00
parent 697d2c0fd6
commit 921ffa1c50
@@ -176,3 +176,30 @@ JSON constraints:
- Backend service must derive owner identity from verified auth context. - Backend service must derive owner identity from verified auth context.
- Client must not be trusted for `user_id`/`operator_id` ownership semantics. - Client must not be trusted for `user_id`/`operator_id` ownership semantics.
- `metadata` and `settings` must not include secrets. - `metadata` and `settings` must not include secrets.
## Application initialization contract
Application initialization is split into two separate concerns: deterministic seed data and dynamic notification template sync. These are intentionally decoupled to avoid non-deterministic side effects during bootstrap.
### Seed data (deterministic)
Managed by `python -m core.runtime.cli init-data` (called by `dev-migrate.sh bootstrap`):
- `initialize_llm_catalog()` — seeds `llm_factory` and `llms` tables with known model definitions
- `initialize_system_agents()` — seeds `system_agents` table
These are idempotent and version-locked to code; they do not depend on runtime state or user data.
### Notification templates (declarative sync)
Managed by `python -m core.runtime.cli sync-notifications [flags]`:
- Reads notification definitions from YAML files under `backend/src/core/config/static/notification/notifications/`
- Syncs to `notifications` table; links existing users via `user_notifications` when `--reconcile-targets` is set
- Supports flags:
- `--dry-run` — validate without writing
- `--prune` — remove static notifications no longer present in YAML files
- `--reconcile-targets` — insert `user_notifications` entries for all existing users matching each notification's `target` predicate
- `--source-key <key>` — sync only the notification with the matching `source_key`
Run after migrations on fresh environments or after adding new notification YAML definitions. Not included in `bootstrap` to keep bootstrap fast and free of unintended side effects.