From 921ffa1c509157c3c161d9dbba96784c6068a032 Mon Sep 17 00:00:00 2001 From: qzl Date: Mon, 13 Apr 2026 11:35:15 +0800 Subject: [PATCH] docs: add application initialization contract to user-points protocol --- .../common/user-points-chat-data-protocol.md | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/protocols/common/user-points-chat-data-protocol.md b/docs/protocols/common/user-points-chat-data-protocol.md index abbf5df..d978e3e 100644 --- a/docs/protocols/common/user-points-chat-data-protocol.md +++ b/docs/protocols/common/user-points-chat-data-protocol.md @@ -176,3 +176,30 @@ JSON constraints: - Backend service must derive owner identity from verified auth context. - Client must not be trusted for `user_id`/`operator_id` ownership semantics. - `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 ` — 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.