sharix-open-onboarding

ShariX Open Onboarding

Stage 9 service-design module for ShariX Open.

The module helps a METASERVICE-ADMIN describe a future service in business terms before technical module configuration or legally significant business records are created.

Stage 9.1/9.2 contract

Stage 9.1/9.2 implements only the Semantic Service Designer:

1. Demo vs real branch;
2. service name/idea/audience;
3. service categories;
4. delivery/location/resource/time/execution semantics;
5. client/provider eligibility semantics;
6. money model;
7. service operator;
8. own Partner cabinet blueprint;
9. tariffs and first provider/offer blueprint;
10. human-readable requirements/documents/checks;
11. semantic capability resolution and pre-install module cards;
12. project review, revisions, export/import.

Real-mode POST requests write only to the deployment-local project file. They do not create Company, Relationship, Permissions, ServiceCategory, Service, Provider or requirement evidence.

The only Stage 9.1/9.2 branch that may create business records is explicit Demo activation, which reuses the canonical Stage 8 ensure_demo_scenario implementation and is valid only for METASERVICE_ID=0.

Storage

Projects are stored outside Git:

<Open root>/conf-real/onboarding/<plan_id>/
    service-plan.json
    revisions/
    locks/

No onboarding Django models or migrations exist.

Writes are revision-checked, file-locked and atomic. Every save produces an immutable JSON revision. A stale browser tab receives a conflict instead of silently overwriting a newer revision.

The JSON schema rejects secret-looking keys. Passwords, API tokens, private keys, acquiring credentials and user documents must never be stored there.

Module recommendations before installation

Stage 9.1/9.2 may know only pre-install metadata and semantic capabilities. Stage 15.7.2 makes the metadata boundary explicit: module purpose, active repository/branch, source visibility, runtime status and verified software-license identity come from the canonical sharix_sysadmin module metadata/health projection rather than an onboarding-owned catalogue. Repository visibility (public/private) is not a software license. Unknown license identity remains unknown instead of being inferred from repository visibility. It must not show Moodle/Appointments/Payments/etc. configuration fields before those modules are actually loaded. Installed-module contribution forms belong to Stage 9.2.

Capability mappings explicitly include Landing for the public showcase and Appointments for extended date/time planning while preserving the established base scheduling default. Closed/private or otherwise unavailable modules are not dead ends. If an exact implementation is unavailable, the project can select a documented core fallback, CUSTOM_EXTERNAL, or defer the capability. The final plan keeps the resulting limitation visible.

URLs

When enabled through INSTALLED_APPS_LOCAL, core.urls auto-connects the module under:

/my/onboarding/

Access is restricted to effective METASERVICE-ADMIN (superuser also passes the central access matrix).

Validation

python manage.py check
python manage.py check_onboarding_projects
python -m compileall -q sharix_onboarding

check_onboarding_projects is read-only.

Stage 9.2 — modules and installed contributions

The designer now separates pre-install semantic selection from post-install module configuration. A missing module exposes only general metadata. Runtime-installed apps may provide <app>.sharix_onboarding.get_onboarding_contribution(); only then can their module-specific fields appear. The onboarding module does not own a second installer: selected accessible modules are connected through the existing Системная панель -> Модули workflow and then materialized by the canonical ./bin/install.sh. Closed/private modules are installable only when the installation already has access/source configuration; otherwise a safe fallback, defer, or custom extension remains selectable. A project cannot be frozen while it still selects a module implementation that is not actually runtime-installed.

The final review can freeze a design revision/hash for Stage 9.3. Freezing still creates no Company, Relationship, Permission, ServiceCategory, Service or Provider.

Stage 9.3 — canonical materialization and guided evidence

A frozen real project can be materialized from /my/onboarding/<plan_id>/materialize/ or from the management command:

python manage.py materialize_onboarding_project <plan_id> --user-id <actor_id>
python manage.py materialize_onboarding_project <plan_id> --user-id <actor_id> --refresh-only

Materialization is resumable and idempotent. It creates/reuses only canonical domain objects and request flows: Company, ST/NEG/ACCESS requests, ServiceCategory/Service, DocumentTypeDefinition/CheckDefinition/RequirementRule and real requirement actions. It never marks evidence PASSED merely to complete the wizard and does not create Provider/offers (Stage 9.4).

The project file stores only public/domain references, checkpoints and errors. Once materialization starts, domain models become authoritative. A semantic edit invalidates the frozen execution state and requires a new freeze/change plan; existing domain objects are not silently rewritten.

Installed modules may implement the neutral contribution materialize hook. Current 9.3 integrations create only module-owned structures: Appointments check bindings, Moodle check-to-course bindings, Constructor draft execution plans, and Legal category profiles. Missing schedules, unpublished execution plans, external approvals and real evidence remain visible blockers and must be completed in their canonical module/UI.

Stage 9.4 launch and closeout

After Stage 9.3 reaches execution.status=materialized, /my/onboarding/<plan_id>/launch/ reconciles the first production marketplace path. The launch layer keeps only execution bindings/checkpoints in service-plan.json; it does not add a second Provider/order/payment engine.

Rules:

• a Provider offer is created only for a real active user that already has the effective provider admission required by the normal offer facade;
• startup offer blueprints never bind arbitrary users: founder may use the onboarding actor after normal provider admission, while unassigned remains a blueprint for later normal provider setup;
• a Resource is never invented from the free-text blueprint description: when a tariff requires one, bind an existing active Resource ID;
• offer creation uses create_mobile_provider_offer() and therefore keeps the existing validation and activation-ticket lifecycle;
• active offers are moved online/gap through the existing provider availability facade only after activation;
• the first order is created by the normal client order flow; onboarding detects the first placed order for its materialized services rather than impersonating a client;
• paid rehearsals are read from the actual payment owner/environment and OrderPaymentState; onboarding links to the standard payment UI and never performs a synthetic production charge;
• individual categories may be explicitly deferred. If at least one unaffected category launches, the final result can be PARTIALLY_LAUNCHED;
• final result is READY, READY_WITH_LIMITATIONS, or PARTIALLY_LAUNCHED.

CLI reconciliation uses the same service:

./venv/bin/python manage.py reconcile_onboarding_launch <plan_id> --user-id <id>
./venv/bin/python manage.py reconcile_onboarding_launch <plan_id> --user-id <id> --refresh-only

Stage 10.2 dynamic wizard collections

Categories, tariffs, provider/offer blueprints and custom requirements are no longer constrained by fixed extra=3/4 rows. The web wizard uses Django formsets with a reusable client-side add/remove layer; server validation remains authoritative. The delivery step also normalizes dependent values server-side: location_mode=client always includes the address order input and resource_mode=none clears a stale resource note.

Recovery and future schema versions

ProjectStore reports corrupt/missing current files instead of silently hiding them. Recovery is explicit and only restores service-plan.json from the latest valid immutable revision:

./venv/bin/python manage.py onboarding_project_doctor
./venv/bin/python manage.py onboarding_project_doctor --repair <plan_id>

The project schema keeps an explicit stepwise migrator registry. Old immutable revision files are not rewritten. The current schema is v4 with explicit 1 -> 2 -> 3 -> 4 migration. A legacy project is migrated only in memory; the first subsequent save creates a current-schema revision while historical JSON remains unchanged. Future unsupported schema versions fail closed.

Schema v4 adds Stage 16.11 existing-Service planning without renaming the historical technical mode=real field. onboarding_mode=new|existing selects the workflow. Existing mode captures an actor-scoped immutable runtime baseline with stable source_ref identities, previews baseline/runtime/desired changes, blocks concurrent conflicts, and applies supported updates only through the canonical ServiceCategory/Tariff forms and their normal approval lifecycle.

Schema v2 is deliberately structural rather than a premature business rewrite: repeatable categories, tariffs, provider/offer blueprints and custom requirements have stable public_id values and may be edited by dynamic add/remove formsets. Unknown legacy fields are preserved. Pricing/provider/location semantic changes belong to the later Stage 10 domain step rather than being guessed by the v1->v2 migrator.

A semantic edit after materialization/launch starts a new change-plan. The old object references and launch result are archived under execution.history, while the new revision returns to draft and must pass freeze/materialization again. This avoids mutating an already launched service behind its approved hash.

Stage 10.4 module-aware refinement

Optional-module availability is now taken from the canonical sharix_sysadmin module-health/lifecycle state instead of a second onboarding-specific installed check. This is especially important for modules such as Nextcloud: a runtime-enabled module is treated as installed even when its installation-level credentials still make health not_configured/degraded. Secrets remain outside the project JSON.

The onboarding contribution contract is version 2. Version-1 contributions remain supported unchanged; v2 adds project-derived initial values and repeatable structured sections. Stage 15.7.3 adds an optional backward-compatible section preview hook to v2: the contributing module owns preview source/semantics, while onboarding only validates the current form values and renders the returned text result. Stage 15.7.4 lets a v2 repeatable declare ordered=True; the generic editor then uses Django formset ORDER, add/delete/move controls and an optional module-owned prepare_rows normalizer. A preview path must not call ProjectStore.update, contribution materialization or Document Engine artifact persistence. Stage 12 therefore refines earlier decisions instead of silently presenting unrelated defaults. Payments inherits the finance owner/subscription choice, Appointments inherits the interview choice, and installed module configuration never asks again for installation-level secrets.

Service Constructor no longer asks free-text “which stages should be implemented”. Its contribution edits an ordered repeatable corresponding to real StageTemplate properties and materializes those rows into the module-owned DRAFT plan. The editor keeps hidden stable public_id/technical code values while ordinary title edits and Django-formset reordering change only presentation data/order. Public StageTemplate title/description localization remains owned by the Service Constructor registration in sharix_translations.py; onboarding does not add name_ru/name_en fields. Legal replaces the generic “additional document requirements” textarea with structured LegalCategoryProfile and LegalServiceProvision rows.

ProjectStore.create() persists the canonical normalized v4 shape that load() returns. Legacy v1/v2 files migrate explicitly in memory: Partner booleans become one partner_mode, custom requirements use structured target/type/reference fields, and ambiguous legacy choices require confirmation instead of being guessed. A frozen project whose legacy approved hash no longer matches the v3 semantic projection must be reviewed and frozen again before materialization; immutable historical revision files are not rewritten. Existing-Service projects add a separate v4 baseline/apply-state envelope while retaining these v3 semantic fields.