ecoportal-api-graphql 1.3.5 → 1.3.9

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

@@ -0,0 +1,196 @@
+# 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

data/.ai-assistance/code/ecoPortal_architecture/10_forces_workflow_builder.md

@@ -0,0 +1,132 @@
+# EcoPortal Forces and Workflow Builder
+
+---
+
+## Forces (Legacy Front-End Snippets — Being Replaced)
+
+### What They Are
+
+Forces are AngularJS embedded code snippets that are attached to pages and stages.
+They implement **conditional field behaviour** — things like:
+- Show/hide sections based on field values
+- Compute risk ratings (e.g. `likelihood × severity = risk_score`)
+- Fill gauge values based on select field selections
+- Conditional required field logic
+
+### How They Attach
+
+Forces have **bindings** — connections to specific fields and sections within a stage.
+A force appears in the front-end on a specific stage only if ALL its bindings are
+present in that stage (the bound fields and sections exist in that stage).
+
+### Technical Details
+
+- Backend: `Force` type in GraphQL (`id`, `name`, `script`, `bindings`, `globalBindings`)
+- Front-end: AngularJS components embedded in the stage view
+
+### Forces on GraphQL — CORRECTED (verified, Oscar + code, 2026-07-01)
+
+> ⚠️ An earlier version of this doc (2026-06-09) claimed forces were "not yet scriptable —
+> blocked until a dedicated legacy-forces GraphQL endpoint lands." **That was wrong**, and it
+> persisted because the fact below was only ever captured in machine-local memory. There is no
+> separate "forces endpoint" — forces are managed through the **WorkflowCommandInput command-bus**,
+> the same imperative mechanism used for all template/workflow edits. Full root-cause:
+> `.ai-assistance/projects/ooze-graphql-native-migration/analysis/2026-07-01-forces-via-workflow-commands-miss-rca.md`.
+
+**MUTATING forces — AVAILABLE NOW.** Done via `Workflow*` commands (`WorkflowAddForceInput`,
+`WorkflowEditForceInput`, `WorkflowRemoveForceInput`, `reorderForces`, `addBinding`/`editBinding`/
+`removeBinding`) submitted through `executeWorkflowCommands`. The gem already ships this:
+- Inputs: `lib/ecoportal/api/graphql/input/workflow_command/{add_force,edit_force,remove_force,reorder_forces,add_binding}.rb`
+- Wiring: `input/workflow_command.rb`; mutation `mutation/page/execute_workflow_commands.rb`
+- Model: `base/force.rb` queues `editForce` / `addBinding` commands
+- eco-helpers: `OozeRedirect::ForceCompat#save_force_changes!` already submits them via
+  `graphql.page.execute_force_commands` → `executeWorkflowCommands` (the "to-be-built" sketch was
+  already built).
+
+**READING forces on a page — the only WIP part.** `Query::PageWithForces` (used by
+`ForceCompat#with_each_entry`) currently fails client-side schema validation (PageUnion selections,
+`id` on binding types). This is the genuinely-blocked piece.
+
+**Why scripts still appear "blocked":** `OozeRedirect.force_support?` hard-returns `false`, gating
+read AND write together — so the broken READ disables the working WRITE as collateral. Correcting
+it means splitting the gate (enable writes; gate only the `PageWithForces` fetch) and/or fixing the
+read query. Until then the ~20 force-dependent ooze scripts stay off, but they are **not**
+fundamentally blocked — the write path exists.
+
+**Scripts interact with forces as in v2** (the compat API is real, not a sketch):
+`force.custom_script = new_script` (→ `editForce`), `force.bindings.add(...)` (→ `addBinding`),
+`force.bindings.delete!(...)` (→ `removeBinding`); commands accumulate and submit in one
+`executeWorkflowCommands` call after `process_ooze`.
+
+### Status
+
+**Forces are being replaced** by the Workflow Builder. New templates should use Workflow Builder
+instead of Forces. Existing templates with Forces continue to work and are now editable via the
+command-bus (above).
+
+---
+
+## Workflow Builder (`PagesWorkflow`)
+
+### What It Is
+
+The Workflow Builder is the replacement for Forces. It provides server-side (and
+eventually client-side via React) automation configuration for pages.
+
+### Currently Deployed Features
+
+| Feature | Status |
+|---------|--------|
+| Automated notifications | ✅ Deployed |
+| Automated page creation | ✅ Deployed (from workflow triggers) |
+| Task assignments | ✅ Deployed (per workflow rules) |
+| Conditional field/section workflows | 🔄 In development |
+| Custom computed values (risk matrices) | 🔄 In development |
+
+### Conditional Field Workflows (Not Yet Deployed)
+
+This is the AngularJS Forces replacement. Will enable:
+- Show/hide sections based on field values
+- Computed gauge values from select + number field matrices
+- Conditional required fields
+- Section visibility rules
+
+**Why it matters for scripting:** Once deployed, the server may automatically
+update field values or show/hide sections when a page is updated. Scripts that
+update a field may trigger downstream Workflow Builder effects server-side.
+
+### Recent Status (2026-06-07)
+
+The Workflow Builder was recently refactored. New customers have it deployed for
+their templates. Engineering is doing quick fixes via CI/CD. The Workflow Builder
+API is **not stable enough for scripting against its internals** — use the standard
+`updatePage` mutation and let the server trigger workflow effects as side effects.
+
+### GraphQL Access
+
+The `PagesWorkflow` type is queryable, and its mutations **ARE covered in this gem** — via the
+`WorkflowCommandInput` command-bus (~80 command types under `input/workflow_command/`, applied by
+`executeWorkflowCommands`). This is the imperative mechanism for editing workflows, forces, stages,
+sections, fields, strategies, operations, recipients, etc. (NOT a diff-based update). Key types:
+
+- `PagesWorkflow` — the workflow configuration attached to a register
+- `PagesWorkflowCallbackType` — triggers and operations
+- `PagesWorkflowCommandInterface` — commands that were executed
+- `PagesWorkflowOperationsCreatePage` — auto-create operation
+- `PagesWorkflowOperationsAssignTo` — task assignment operation
+- `PagesWorkflowOperationsSendNotification` — notification operation
+
+The command-bus (`input/workflow_command/*.rb` + `mutation/page/execute_workflow_commands.rb`) is
+the same machinery the templates-maintenance project builds on. The API is volatile — design for
+change. (Earlier "not covered in this gem" was wrong — corrected 2026-07-01 alongside the forces fix.)
+
+### Task Side Effects of `updatePage`
+
+When submitting a stage (`submit: true` in `updatePage`), the server may:
+1. Create/assign a `ReviewPage` or `CompletePage` task for the next stage
+2. Create related pages (if workflow has auto-create configured)
+3. Send notifications to relevant users
+4. Trigger time-delay operations for future tasks
+
+Scripts should check mutation payloads for errors but should NOT attempt to manually
+manage workflow state — the server handles it.

data/.ai-assistance/code/ecoPortal_architecture/11_integration_gems.md

@@ -0,0 +1,187 @@
+# EcoPortal Integration Gem Stack
+
+---
+
+## Dependency Chain
+
+```
+[graphql-ruby] [graphql-client] [graphlient (forked)] (upstream, external/forked)
+      ↓
+ecoportal-api  /  ecoportal-api-v2              (upstream, team-managed)
+      ↓
+ecoportal-api-graphql                           ← THIS REPO
+      ↓
+eco-helpers                                     (downstream, team-managed)
+```
+
+---
+
+## graphlient (Forked)
+
+**Purpose:** GraphQL DSL for building and executing queries.
+**Fork:** `C:\ruby_scripts\git\graphlient` (Oscar's fork of `ashkan18/graphlient`)
+**Branch:** `feature/dsl-only-mode`
+
+**Custom additions to the fork:**
+- `Client#to_query_string(&block)` — builds a full query document from the DSL block
+  and returns a `String` WITHOUT touching Faraday/HTTP. Keystone for the schema-less
+  dispatch mode.
+- `Query#spread(name)` — DSL helper that emits `...FragmentName` in the query string.
+  Replaced the `___Ecoportal__API__GraphQL__Fragment__X` convention from graphql-client.
+
+---
+
+## ecoportal-api (Upstream)
+
+**Purpose:** Core base models, auth, content model, base HTTP client.
+**Local path:** `C:\ruby_scripts\git\ecoportal-api`
+
+Provides:
+- `Ecoportal::API::Common::BaseModel` — base model with passthrough, passkey, etc.
+- `Ecoportal::API::Common::Content::DoubleModel` — dirty tracking base
+- `Ecoportal::API::Common::BaseClass` — class_resolver, resolve_class DSL
+- `Ecoportal::API::Common::GraphQL::AuthService` — OAuth authentication
+- `Ecoportal::API::Common::GraphQL::HashHelpers` — deep_dup, etc.
+
+---
+
+## ecoportal-api-v2 (Upstream, Being Retired)
+
+**Purpose:** REST API v2 client gem (Page, Register, PersonMember, etc.)
+**Local path:** `C:\ruby_scripts\git\ecoportal-api-v2`
+
+Key things to look for in the source:
+- `Ecoportal::API::Common::Content::StringDigest` — Field ID / ref formula
+- `HashDiffPatch` — the diff algorithm the GraphQL gem adapted
+- `passthrough`, `passarray`, `passboolean`, `passdate` DSL macros
+- Page model with `.as_update` and dirty tracking
+
+---
+
+## ecoportal-api-graphql (THIS GEM)
+
+**Local path:** `C:\ruby_scripts\git\ecoportal-api-graphql`
+**Branch:** `pages` (primary development branch)
+
+### Namespace Structure
+
+```
+Ecoportal::API::GraphQL::
+  Logic::         Base classes (BaseModel, BaseQuery, Query, Mutation, etc.)
+  Common::        Shared utilities (DiffService, HashHelpers, etc.)
+  Interface::     GraphQL interfaces (BasePage, LocationStructure)
+  Base::          Concrete base model classes (Page::Basic, Page::Phased, DataField::*)
+  Model::         Domain model classes (inherits from Base::, adds resolvers)
+  Fragment::      GraphQL fragment definitions
+  Fragment::Pages Sub-namespace for customer-facing fragments (CommonPageUnion)
+  Connection::    Connection classes for paginated results
+  Query::         Query classes (Page, Pages, Templates, RegisterPreviewPages, etc.)
+  Mutation::      Mutation classes (Page::Update, Page::Archive, etc.)
+  Payload::       Mutation payload classes
+  Input::         Input object classes (Page::Update, SearchConf, DeltaInput, etc.)
+  Builder::       Builder pattern (Page, Action, ContractorEntity, LocationStructure)
+  Compat::        v2 compatibility layer (Pages, Registers, StageView, StageCollection, etc.)
+  Concerns::      Shared modules (PageCompat, DataFieldAccess, SnakeCamelAccess, etc.)
+```
+
+### Key Conventions
+
+**passthrough vs passboolean vs passdate vs passarray:**
+All macros from ecoportal-api that create read/write accessors:
+- `passthrough :externalId` → `def externalId; doc['externalId']; end` + setter
+- `passboolean :archived` → same but returns `true/false` cast
+- `passdate :createdAt` → same but wraps in DateTime model
+- `passarray :stages` → returns Array from doc
+
+**SnakeCamelAccess concern:** Included in `Logic::BaseModel`. All GraphQL model objects
+respond to snake_case versions of camelCase methods via `method_missing`:
+- `page.external_id` → `page.externalId`
+- `page.patch_ver` → `page.patchVer`
+- `page.source_template_id` → `page.sourceTemplateId`
+- `page.time_zone = 'UTC'` → `page.timeZone = 'UTC'`
+
+**class_resolver pattern:** Used to lazily resolve class references (avoids circular
+requires):
+```ruby
+class_resolver :item_class, 'Ecoportal::API::GraphQL::Model::PageUnion'
+```
+`resolve_class` accepts String (const_get), Symbol (send), or Class.
+
+**Fragment assembly:** `BaseQuery#assemble_fragments` recursively scans query strings
+for `...FragmentName` spreads and appends all needed fragment definitions. Fragment
+sub-namespaces registered via `Fragment.register_namespace(klass)`.
+
+### eco-helpers Compat Layer
+
+```
+Compat::Pages         — graphql.pages (matches apiv2.pages interface)
+Compat::Registers     — graphql.registers (matches apiv2.registers interface)
+Compat::StageView     — page view filtered to one stage (matches v2 stage fetch)
+Compat::StageCollection — stages[name], get_by_name, ordered
+Compat::SearchResults — .total, .total_before_filtering
+Compat::PageReference — .page_id, .active_stage_id
+Compat::Response      — .success?, .status, .body
+```
+
+**Concerns included in Interface::BasePage (all page models):**
+- `PageCompat` — v2 method aliases (external_id, template_id, components, stages?, consolidate!, dirty?, validate)
+- `DataFieldAccess` — components, sections, field_collection, section_collection, data_fields_updates, data_fields_additions
+- `SnakeCamelAccess` — camelCase→snake_case method delegation
+
+**Data field types with full read/write:**
+PlainText, RichText, DateField, Number, Gauge, People, Select, Checklist, TagField, Geo
+
+---
+
+## eco-helpers (Downstream)
+
+**Purpose:** Integration script framework for the ecoPortal Integrations Team.
+**Local path:** `C:\ruby_scripts\git\eco-helpers`
+
+Key patterns:
+- Script use case classes inherit from `OozeBase` or `RegisterUpdate`
+- `RegisterUpdate` manages a loop: search register → fetch page → modify → save
+- `RegisterUpdate` tracks changes: if `dirty?(page)`, triggers `pages.update(page)`
+- `RegisterUpdate` tracks stage changes: if stage changes, fetches new stage view
+
+**Stage iteration pattern:**
+```ruby
+# In RegisterUpdate
+apiv2.registers.search(register_id, search_options) do |page_result|
+  ooze = apiv2.pages.get(page_result.id)
+  stage = ooze.stages.get_by_name('Risk Assessment')
+  apiv2.pages.get(ooze.id, stage_id: stage.id).tap do |stage_view|
+    with_fields(stage_view, type: :plain_text) { |f| f.value = 'Updated' }
+    apiv2.pages.update(stage_view)
+  end
+end
+```
+
+With GraphQL compat, `apiv2` is replaced by `graphql` and the pattern works unchanged.
+
+### Filter helpers (eco-helpers)
+
+```ruby
+date_range_filter(from: Date.today - 7, to: Date.today, key: :updated_at)
+# → { type: "date_filter", key: "updated_at", lbound: "ISO8601", ubound: "ISO8601", time_zone: "..." }
+
+tags_filter(['Auckland', 'Wellington'], any: true)
+# → { type: "tag_filter", tags: [...], mode: "any", negate: false, key: "tags" }
+```
+
+The GraphQL compat layer translates `date_filter` lbound/ubound → gte/lte.
+Other filter types pass through to the ES backend unchanged.
+
+---
+
+## Backend Source (ecoPortal Rails)
+
+**Local path:** `C:\docker\ecoPortal_master\`
+
+Key namespaces and files to look up:
+- `Enzyme::` — old Rails models (AngularJS era, being replaced)
+- `NewEp::` — current Rails models (React era)
+- `NewEp::DataField` — current data field model (was `Enzyme::Membrane`)
+- `Ecoportal::API::Common::Content::StringDigest` (actually in ecoportal-api-v2) — Field ID formula
+- Rails `services/` loadable path — Migrator and other background services
+- `.graphql` files — front-end React component GraphQL queries/fragments