CODING_POLICY.md 6.8 KB

Coding policy — sharix-open-onboarding

  1. The onboarding project file is the only Stage 9 draft state. Do not introduce onboarding ORM tables as a convenience cache.
  2. Before Stage 9.3 materialization, real-mode views must not create or mutate business domain objects.
  3. Never store passwords, API tokens, private keys, acquiring credentials or uploaded identity/legal documents in service-plan.json.
  4. Pre-install capability metadata is generic. Module-specific settings may only be exposed by an actually installed module contribution in Stage 9.2+.
  5. A closed/private unavailable module must not dead-end onboarding. Keep desired capability, chosen fallback/defer/custom implementation and limitation distinct.
  6. Do not invent a fallback that current core or an installed module cannot actually provide.
  7. Project writes must remain atomic, revision-safe and concurrency-safe.
  8. Demo mode reuses Stage 8 reference bootstrap; never create a second demo fixture system here.
  9. Stage closeout must record what/how/why/result plus verification and exact repository push commands.

Dialogue API boundary

  • The versioned API edits only the established project design sections and preserves execution, install evidence, immutable baseline and created_by.
  • A plan UUID is not an access grant: every read/write requires the effective onboarding role and the exact creator. Revision and design-hash confirmation precede freeze and runtime actions.
  • Read-only validation/preview must not create domain objects. Materialization and existing-Service Apply delegate to the same canonical flows as the UI; neither may approve a Ticket or infer live readiness from a started action.
  • An uncertain runtime POST is reconciled by GET/preview, never blindly retried.

Stage 14 touched-page UI contract

This repository is a user-facing UI owner. Stage 14 uses progressive coverage rather than a one-time mechanical translation of every historical page. When a page, form, template or user-visible workflow in this repository is new or materially changed, the same change must close the local UI debt of that touched surface:

  • localize the touched user-visible strings through the repository/module-owned Django i18n catalog and provide both ru and en; do not move module strings into the root webapp catalog merely for convenience;
  • keep canonical model/API/status/role/action codes unchanged and never branch business logic on translated labels;
  • if the page participates in ShariX contextual help, update its help in the same change; help must explain the concrete operations available on that page, their prerequisites, result and important limitations, not only terminology or a general page purpose;
  • review field labels, units, help_text, choices, validation messages and empty states. Prefer an existing canonical finite choice/catalog over technical free text when that does not narrow the supported domain contract;
  • invalid user input must remain a normal form/domain validation result, never an HTTP 500. In particular, a model/ModelForm validation error keyed to a field must target a field that the form actually contains, or be deliberately converted to a non-field/form-owned error;
  • an HTTP 200 page with a missing body is a regression, not an empty state. A legitimate empty dataset must explain why it is empty and, when the current role can act, what operation creates/configures the missing data;
  • add/update regression evidence for the touched valid/invalid form path and rendered page body as appropriate.

Historical untouched UI may remain incomplete during the transition. A later change may not add another untranslated/unexplained fragment and defer the rest of the same touched page again.

Stage 15 compatibility and module metadata

The current project schema is version 4. Explicit v1 -> v2 -> v3 -> v4 migration remains supported. Stage 15.7.1 replaces the legacy Partner booleans with one semantic own_partner.partner_mode and replaces free-form custom-requirement ownership with target_type / target_ref / optional canonical definition_ref. Ambiguous legacy values must remain visible for explicit confirmation, and their original values remain compatibility evidence. A frozen legacy project whose approved hash belongs to the earlier semantic projection must be reviewed and frozen again before materialization; immutable old revision files are not rewritten.

Onboarding must consume canonical module metadata for capability purpose, implementing module, repository and actual license. sharix_translations is GPL v3/public; sharix_russian_post is private/proprietary. Do not infer license from availability (public/free, closed/private) and do not create a second module-status catalogue inside onboarding.

Stage 16.11 existing-Service invariants

  • Keep the historical technical mode=real contract unchanged. onboarding_mode carries the new new / existing distinction.
  • An existing-Service project owns an immutable actor-scoped runtime baseline plus mutable apply-state evidence; apply-state is not part of the frozen design hash.
  • Never infer edit authority from Provider/Partner/ordinary User participation. Existing-Service onboarding remains under the METASERVICE-ADMIN boundary and revalidates that boundary at apply time.
  • Existing objects use stable source_ref identities. A supported edit updates the referenced object through canonical forms/lifecycle; it must not create a duplicate object.
  • Re-read and lock mutable targets immediately before apply. Baseline/runtime/desired conflicts block overwrite and require explicit review/rebase.
  • New-object creation and deletion are not silently synthesized by the existing-Service editor; use the standard domain creation/deletion lifecycle until a dedicated onboarding mapping is implemented.
  • Approval-capable requesters are never auto-approved by onboarding. Normal lifecycle Tickets remain normal Tickets; onboarding may only surface their IDs/review links.
  • Runtime snapshots contain no secrets and may include read-only requirements, checks, relationships, Providers and Orders needed for impact context. Read-only contextual drift does not become an editable three-way conflict.

Stage 15.7.1 semantic migration invariants

  • Do not reintroduce enabled / same_as_operator as ordinary Partner UI controls.
  • Runtime requirement ownership must never be recovered by parsing localized free text.
  • Reusing a CheckDefinition or DocumentTypeDefinition requires revalidation at form submit and again immediately before materialization.
  • needs_confirmation is a migration state only; freeze is blocked until the user selects a real semantic owner/mode.
  • Old frozen plans whose design hash changes under the v3 semantic representation require an explicit review/refreeze path rather than silent acceptance or destructive rewriting.