ecoportal-api-graphql 1.3.13 → 1.3.16

data/.ai-assistance/code/ecoPortal_architecture/07_data_fields.md

@@ -1,197 +0,0 @@
-# EcoPortal Data Fields
-
----
-
-## Overview
-
-Data fields are the form inputs within a page. Each field is an INSTANCE of a field
-definition from the template. Field instances have:
-- A MongoDB ObjectId (`id`) assigned on page creation — NOT predictable from template
-- The field type (`__typename` in GraphQL)
-- Label (the question/field name shown to users)
-- Value(s) — the user's response
-- `ref` — the ES index key (Field ID / System ID future)
-- `deindex: Boolean` — if true, field is excluded from Elasticsearch index
-- Linked field configuration (cross-reference from another register)
-
----
-
-## All Field Types (`DataFieldUnion`)
-
-The GraphQL `DataFieldUnion` has 20+ concrete types:
-
-| GraphQL type | eco-helpers type | Description |
-|---|---|---|
-| `PlainText` | `:plain_text` | Single or multi-line text |
-| `RichText` | `:rich_text` | HTML rich text editor |
-| `Date` | `:date` | Date/datetime picker |
-| `Number` | `:number` | Numeric input |
-| `Gauge` | `:gauge` | Numeric with min/max (risk matrix output) |
-| `Select` | `:select` | Single or multi-select dropdown |
-| `Checklist` | `:checklist` | Checkbox list (each item: label + checked) |
-| `Signature` | `:signature` | Digital signature capture |
-| `TagField` | `:tag_field` | Location tag selector |
-| `People` | `:people` | Person selector (linked to PersonMember) |
-| `ContractorEntities` | `:contractor_entities` | Contractor selector |
-| `CrossReference` | `:cross_reference` | Reference to pages in another register |
-| `Geo` | `:geo` | Geographic coordinates + address |
-| `ImageGallery` | `:image_gallery` | Image upload gallery |
-| `File` | `:file` | File attachment |
-| `Mailbox` | `:mailbox` | Email inbox linked to the field |
-| `ActionsList` | `:actions_list` | Embedded actions list |
-| `Law` | `:law` | Legal obligation snippets |
-| `AiSummary` | `:ai_summary` | AI-generated summary field |
-| `EmbeddedStructure` | `:embedded_structure` | Embedded reporting structure |
-
----
-
-## DataFieldInput Structure
-
-When updating or adding field values, each field uses a typed input within `DataFieldInput`:
-
-```json
-{
-  "plainText":   { "id": "FIELD_ID", "value": "Job description text" },
-  "richText":    { "id": "FIELD_ID", "content": "<p>HTML content</p>" },
-  "date":        { "id": "FIELD_ID", "value": "2024-11-25T08:30:00+13:00" },
-  "number":      { "id": "FIELD_ID", "value": 42.5 },
-  "gauge":       { "id": "FIELD_ID", "value": 14.0 },
-  "select":      { "id": "FIELD_ID", "options": [{ "id": "OPT_ID", "selected": true }] },
-  "people":      { "id": "FIELD_ID", "peopleIds": ["PERSON_ID_1", "PERSON_ID_2"] },
-  "geo":         { "id": "FIELD_ID", "address": "...", "coordinates": { "lat": -36.86, "lon": 174.76 } },
-  "checklist":   { "id": "FIELD_ID", "items": [{ "id": "ITEM_ID", "checked": true }] },
-  "locationField": { "id": "FIELD_ID", "locationIds": ["LOC_ID"] }
-}
-```
-
-Only ONE field type key is used per `DataFieldInput` object.
-
----
-
-## DataFieldOneToManyInput
-
-Used in both `createPageFromTemplate` and `updatePage`:
-
-```json
-{
-  "additions": [<DataFieldInput>, ...],
-  "updates":   [<DataFieldInput>, ...],
-  "deletions": ["FIELD_ID_TO_DELETE", ...]
-}
-```
-
-- **`updates`** — change values of existing fields (require their current `id`)
-- **`additions`** — add new field data (for fields that exist in template but have no instance data yet)
-- **`deletions`** — remove field instances
-
-**For `createFromTemplate`:** Use `updates` — the `buildFromTemplate` response gives
-instance field IDs, and `updates` sets their values on creation.
-
----
-
-## Field Access in the Gem
-
-### Getting fields from a page
-
-```ruby
-page = graphql.pages.get(page_id)  # fetches CommonPageUnion with $fields: true
-
-# As DataField::Collection
-fields = page.components  # or page.field_collection
-
-# Filter by type
-plain_texts = fields.get_by_type(:plain_text)
-selects     = fields.get_by_type('Select')
-
-# Find by label
-field = fields.get_by_name('Summary')
-
-# Access raw docs (v2 compat)
-fields.doc  # → [raw_hash, ...]
-```
-
-### Modifying fields
-
-```ruby
-# PlainText
-field = page.components.get_by_name('Summary')
-field.value = 'New summary text'
-
-# Select — by option name, value, or id
-field = page.components.get_by_name('Status')
-field.select_option('Active')  # deselects all others
-
-# People
-field = page.components.get_by_name('Assigned To')
-field.people_ids = ['person_id_1', 'person_id_2']
-
-# Date (ISO8601 string)
-field = page.components.get_by_name('Due Date')
-field.value = '2025-06-30T09:00:00+12:00'
-
-# Checklist
-field = page.components.get_by_name('Checklist')
-field.check('Step A')
-field.check('Step B', checked: false)
-
-# Rich text (HTML)
-field = page.components.get_by_name('Description')
-field.content = '<p>Updated description</p>'
-```
-
-### Adding a new field (additions)
-
-```ruby
-# When a field exists in the template but has no data in this instance:
-draft = graphql.pages.get_new(template_id)
-draft.components.add(id: 'f1_from_draft', type: 'PlainText') { |f| f.value = 'X' }
-```
-
----
-
-## Stage-Level Field Access
-
-For PhasedPage, fields are within stages → sections → fields:
-
-```ruby
-# Get stage by name
-stage = page.stages['Risk Assessment']
-
-# Stage sections
-stage.sections.each do |section|
-  puts "Section: #{section.heading}"
-  section.components.each { |f| puts "  Field: #{f.label}" }
-end
-
-# All fields in stage (flat)
-stage.components.get_by_name('Hazard Description').value = 'Exposure to...'
-```
-
----
-
-## Field Visibility: deindex and Hidden
-
-- `deindex: Boolean` — if true, field value is NOT sent to Elasticsearch. Used for
-  sensitive data. Affects: search, filters, analytics, exports.
-- Fields can be hidden (template configuration). `showHiddenData: true` in queries
-  includes hidden fields in the response.
-
----
-
-## Field Reference (ref) — ES Index Key
-
-The `ref` property identifies a field in the search index (ES). It is:
-- Composed of: `<type_shorthand>.<hash_of_label>`
-- Used in: sorters (`key:` field), filters, chart configurations, linked field config
-- Different from the MongoDB instance `id`
-- Breaks if the field label changes (hash of label changes)
-
-**Formula:** `Ecoportal::API::Common::Content::StringDigest` in `ecoportal-api-v2`
-
-**Examples:**
-- Plain text field "Job Number": `plain_text.job_nu` (approximate hash)
-- Date field "Due Date": `date.due_da`
-
-**Known issue:** If a field was added via a tech script without copying from the template,
-its `ref` may be unique per instance rather than consistent across all instances of the
-same template. This causes analytics issues (missing data, duplicate columns in exports).

data/.ai-assistance/code/ecoPortal_architecture/08_stages_sections.md

@@ -1,243 +0,0 @@
-# EcoPortal Stages and Sections
-
----
-
-## Stage Lifecycle
-
-### Stage States (`StageStateEnum`)
-
-```
-pending → inprogress → complete
-```
-
-- **`pending`** — Stage not yet started. No fill-in task exists yet.
-- **`inprogress`** — Stage is active. A fill-in task (`CompletePage`) exists and is
-  assigned to someone (per workflow rules). The assignee can enter data.
-- **`complete`** — All required tasks are done. Stage is locked.
-
-**Transition triggers:**
-- `pending → inprogress`: Previous stage completes (its task is done/signed off)
-- `inprogress → complete`: Fill-in task completed, OR review task signed off (if review configured)
-
-### Active vs Started
-
-- `active: Boolean` — Stage is currently active for input (the "current" stage)
-- `started: Boolean` — Stage has had at least some input (includes all past stages)
-
-For a PhasedPage: typically ONE stage is `active` at a time. Previous stages are
-`started` but not `active`. Future stages are neither.
-
-### Stage-Specific Submit
-
-When submitting a stage via GraphQL, ALWAYS include `stageId`:
-
-```graphql
-mutation SubmitStage($input: UpdatePageInput!) {
-  updatePage(input: $input) {
-    item { ...PhasedPageFields }
-    errors { details fullMessages }
-  }
-}
-```
-
-```json
-{
-  "input": {
-    "id": "PAGE_ID",
-    "patchVer": 5,
-    "stageId": "STAGE_ID",
-    "submit": true,
-    "dataFields": {
-      "updates": [
-        { "plainText": { "id": "FIELD_ID", "value": "Final value" } }
-      ]
-    }
-  }
-}
-```
-
-Without `stageId`, the submit may not correctly associate with the right stage and
-may not trigger the expected task assignments in the next stage.
-
-**Why a stage is mandatory (verified — Oscar, 2026-06-30):** stage tasks, and the
-permissions granted through them, are **stage-scoped**. A people field can grant the user
-attached to it permission to *only the stage where they were attached* — so a save / submit /
-sign-off MUST be executed against that specific stage as the target. The web/mobile front-ends
-always operate within a stage for this reason. Inferring a "current/active" stage from the
-page is therefore not just unreliable, it is semantically wrong: on a multi-stage page it may
-name a different stage than the one the work was done on. The submit must carry the stage the
-caller actually worked on. ⇒ **submit / sign_off without a target stage is invalid.**
-
-### Gem enforcement & stageId resolution (compat layer)
-
-The gem treats "a submit must name its stage" as a hard invariant:
-
-- `Input::Page::Update.from_model` **raises** (`ArgumentError`) when `submit: true` or a stage
-  `task` is requested with no `stage_id`. This replaced a silent failure: the operation hash's
-  nil-guard used to *drop* a nil `stageId`, so a stage-less submit went out unnoticed (the
-  act-gov TOOCS bug, 2026-06-30). A plain field update / publish needs no stage and is exempt.
-- `Compat::Pages#compat_stage_id` resolves the target most-explicit-first:
-  1. **pinned** — `submit!(stage_id:)` / `sign_off!(stage_id:)` from the script;
-  2. **active** — `page._compat_active_stage_id`, recorded when a `Compat::StageView` is taken
-     over the page (`pages.get(id, stage_id:)` or eco-helpers `OozeRedirect#stage`). This is the
-     reliable source on the OozeSamples path, where the base loop enqueues and updates the FULL
-     page (first-wins by id — the StageView is never the queued object), so the chosen stage must
-     live on the page itself;
-  3. **current** — `Phased#current_stage_id` server-state inference (`state=='inprogress'` /
-     `active==true`). Last resort only, and guarded: if it yields nil the `from_model` guard fires.
-
-So the canonical way to submit a specific stage from a script is to work *through a stage view*
-(`with_stage` → `stage()` → `StageView`), which records the stage; the later `target.submit!`
-then resolves to it automatically.
-
----
-
-## Stage Permissions
-
-Each stage can have restricted access:
-- **User group restrictions** — only members of specified groups can edit the stage
-- **People field access** — if a stage has a people field configured to "grant stage access",
-  the people assigned to that field get editing access to that stage only
-
-**Key insight:** The configuration enum on a people field determines access scope:
-- `stage_only` — grant access only to the stage where the people field is embedded
-- `page_wide` — grant access to the entire page
-
-**GraphQL behaviour:** If a user doesn't have access to a stage, the stage is simply
-ABSENT from the response (`stages`, `stagesIndex`, `activeStages`). No error is thrown.
-This is different from APIv2 which returned explicit access errors per stage.
-
-**Scripting implication:** Scripts should check whether an expected stage is present
-in the response rather than catching errors. If a stage is missing, the authenticated
-user may not have access to it.
-
----
-
-## Section Types (HasSectionsInterface)
-
-Both BasicPage (directly) and Stage (within PhasedPage) implement `HasSectionsInterface`.
-
-### `ContentSection`
-
-Standard section — one column of fields:
-```graphql
-fragment on ContentSection {
-  id
-  heading
-  dataFields { ...dataField }
-}
-```
-
-### `SplitSection`
-
-Two-column section (left + right panels):
-```graphql
-fragment on SplitSection {
-  id
-  heading
-  leftDataFields  { ...dataField }
-  rightDataFields { ...dataField }
-}
-```
-
-When accessing a split section's fields, always merge left + right:
-```ruby
-section.components  # → DataField::Collection merging left + right
-```
-
----
-
-## Stage-Level Field Access (PhasedPage)
-
-In GraphQL, all stage data is returned in one request via `CommonPageUnion`.
-The response has stages → sections → fields.
-
-```ruby
-# Gem access pattern
-page = graphql.pages.get(page_id)
-
-# All stages
-page.stages                          # → StageCollection
-page.stages['Risk Assessment']       # → Stage (by name or ID)
-page.stages.ordered                  # → [Stage, ...] sorted by ordering
-
-# Stage contents
-stage = page.stages['Risk Assessment']
-stage.sections                       # → SectionCollection
-stage.components                     # → DataField::Collection (all fields in stage)
-stage.sections.get_by_type(:content_section)
-stage.sections.get_by_heading('Details')
-
-# Field access in a stage
-stage.components.get_by_name('Hazard Description').value = 'Exposure to...'
-stage.components.get_by_type(:select).find { |f| f.label == 'Risk Level' }.select_option('High')
-```
-
----
-
-## APIv2 vs GraphQL Stage Rendering Comparison
-
-| Concern | APIv2 | GraphQL |
-|---------|-------|---------|
-| Request count for PhasedPage | One per stage | One for entire page |
-| Stage data isolation | Strict — each request scoped to one stage | Full page returned, client filters |
-| Stage-specific mutations | Via stage_id on URL | Via `stageId:` in `UpdatePageInput` |
-| Permission handling | Access error per forbidden stage | Forbidden stages absent from response |
-| Template stages | Full render | Full render |
-
-**Compat layer approach:**
-`graphql.pages.get(page_id, stage_id: 's1')` returns a `StageView` — a client-side
-wrapper that shows only the specified stage's sections and components, while delegating
-all other page accessors (id, name, patchVer, as_update, etc.) to the full page.
-This matches what v2 scripts expect from a per-stage fetch.
-
----
-
-## StageIndex (Lightweight Stage Summary)
-
-For displaying workflow progress without loading full stage content:
-
-```graphql
-fragment PhasedPageFields on PhasedPage {
-  stagesIndex {
-    id
-    name
-    ordering
-    state
-    started
-    hasCompleteTask
-    hasReviewTask
-  }
-}
-```
-
-`hasCompleteTask` — whether a fill-in task is configured for this stage
-`hasReviewTask` — whether a review/sign-off task is configured for this stage
-
----
-
-## Task Types on Stages
-
-| Task type | GraphQL type | Trigger | When complete |
-|-----------|-------------|---------|---------------|
-| Fill-in | `CompletePage` | Stage becomes active | Moves to review (if configured) or completes stage |
-| Review/sign-off | `ReviewPage` | Fill-in task completed | Completes stage → activates next stage |
-
-Task fields: `id`, `complete`, `completedAt`, `completedBy`, `due`, `overdue`, `users`
-
-**Stage close-out sequence:**
-1. Fill-in task assigned to user(s) (per workflow rules)
-2. User submits: `updatePage(stageId:, submit: true)` triggers `CompletePage` completion
-3. If review configured: `ReviewPage` task created and assigned
-4. Review approved: stage state → `complete`, next stage activated
-5. Next fill-in task created per workflow rules
-
-**Scripting a stage submit:**
-```ruby
-input = Input::Page::Update.from_model(page,
-  stage_id: 'STAGE_ID',
-  submit:   true
-)
-# Input will include stageId + submit even if no page/field changes
-Builder::Page.new(client).update(input: input)
-```

data/.ai-assistance/code/ecoPortal_architecture/09_people_contractors_locations.md

@@ -1,196 +0,0 @@
-# EcoPortal People, Contractors, and Locations
-
----
-
-## People (PersonMember)
-
-### GraphQL Type
-
-`PersonMember` — represents a user in the ecoPortal platform.
-
-Key fields: `id`, `name`, `email`, `externalId`, `archived`, `publicFields`, `privateFields`,
-`supervisor_id`, `organizationHierarchy`
-
-### Query
-
-```graphql
-query GetPeople($filters: [SearchFilter!], $includeArchived: Boolean) {
-  currentOrganization {
-    personMembers(
-      first: 20,
-      includeArchived: $includeArchived,
-      searchConf: {
-        filters: $filters,
-        sorters: [{ key: "created_at", direction: "desc" }]
-      }
-    ) {
-      totalCount
-      pageInfo { hasNextPage endCursor }
-      nodes { id name email externalId publicFields privateFields }
-    }
-  }
-}
-```
-
-### Finding a Person by externalId
-
-```json
-{
-  "filters": [
-    { "operation": "exact_filter", "params": { "key": "external_id", "value": "FRODO" } }
-  ]
-}
-```
-
-Note: The `searchConf` for `personMembers` uses the ARRAY format for `filters` and
-sorters use `key:` not `fieldName:`.
-
----
-
-## Contractor Entities
-
-### GraphQL Type
-
-`ContractorEntity` — represents an external contractor/supplier in the system.
-
-Key fields: `id`, `externalId`, `name`, `schemaId`, `active`, `approved`,
-`associatedPeopleIds`, `leadContractorIds`
-
-### Query
-
-```graphql
-query Contractors($searchConf: Search) {
-  currentOrganization {
-    contractorEntities(searchConf: $searchConf) {
-      totalCount
-      nodes { id externalId name active approved associatedPeopleIds leadContractorIds }
-      pageInfo { endCursor hasNextPage }
-    }
-  }
-}
-```
-
-### Find by externalId
-
-```json
-{ "searchConf": { "filters": [{ "operation": "exact_filter", "params": { "key": "external_id", "value": "9429041280072" } }] } }
-```
-
-### Update: IdDiffInput Pattern
-
-Contractor's `associatedPeopleIds` and `leadContractorIds` use the **IdDiff pattern**
-for updates — instead of sending the full array, send additions and removals:
-
-```json
-{
-  "associatedPeopleIds": { "additions": ["new_person_id"], "removals": ["old_person_id"] }
-}
-```
-
-**Gem class:** `Input::ContractorEntity::Update` handles this via `from_model`
-which reads `doc` vs `original_doc` to compute the diff.
-
-### Mutations
-
-```graphql
-mutation CreateContractor($input: CreateContractorEntityInput!) {
-  createContractorEntity(input: $input) {
-    item { id externalId name schemaId active approved associatedPeopleIds leadContractorIds }
-    errors { details fullMessages }
-  }
-}
-
-mutation UpdateContractor($input: UpdateContractorEntityInput!) {
-  updateContractorEntity(input: $input) {
-    item { ... }
-    errors { ... }
-  }
-}
-```
-
----
-
-## Location Structure (Reporting Structure / RS)
-
-### Concept
-
-The location structure is a hierarchical tree used to tag pages and scope analytics.
-Also called "Reporting Structure" (RS) internally.
-
-Used for:
-- Assigning pages to locations/departments (`locations: [LocationNodeInterface]`)
-- Filtering searches by location (`location_ids` filter)
-- Analytics and dashboard scoping
-- Permission scoping (some permissions are location-based)
-
-### GraphQL Access
-
-```graphql
-query GetLocationStructure($id: ID!) {
-  currentOrganization {
-    locationStructure(id: $id) {
-      id name
-      nodes {
-        id name weight archived
-        classifications { name }
-        ancestors { id name }
-      }
-    }
-  }
-}
-```
-
-### Draft-Based Edits
-
-Location structure changes go through a **draft** system:
-1. `createLocationDraft(...)` — create an edit draft
-2. Apply commands: `insertNode`, `moveNode`, `archiveNode`, `renameNode`, etc.
-3. `publishDraft(...)` — apply to production
-
-This is the most complex part of the GraphQL API. The gem has full coverage in
-`Mutation::LocationStructure::Draft::*` and `Input::LocationStructure::Draft::*`.
-
-### LocationNode Type
-
-```graphql
-type LocationNodeInterface {
-  id: ID!
-  name: String!
-  weight: Int!
-  archived: Boolean!
-  archivedToken: ID
-  parent: LocationNodeInterface
-  children: [LocationNodeInterface!]!
-  classifications: [LocationClassificationType!]!
-  ancestors: [LocationNodeInterface!]!
-}
-```
-
-### TagField (Location Picker Data Field)
-
-`TagField` on a page is the location tag input. It stores `locations: [LocationNodeInterface]`
-— the selected location nodes for that field. Multiple pages can have different location
-tags from the same RS tree.
-
----
-
-## IdDiff Pattern
-
-Used whenever an array relationship is updated. Instead of sending the full new array,
-send only what changed:
-
-```graphql
-input IdDiffInput {
-  additions: [ID!]!
-  removals: [ID!]!
-}
-```
-
-Used in:
-- `ContractorEntity` `associatedPeopleIds` and `leadContractorIds` updates
-- Potentially other relationship updates
-
-**Gem support:**
-- `Input::IdDiff` — the input class
-- `Input::ContractorEntity::Update.from_model` — auto-computes additions/removals
-  from `doc` vs `original_doc` comparison