ecoportal-api-graphql 1.3.13 → 1.3.16

data/.ai-assistance/code/ecoPortal_architecture/04_graphql_queries_mutations.md

@@ -1,277 +0,0 @@
-# EcoPortal GraphQL Queries and Mutations
-
----
-
-## Query Root (`currentOrganization`)
-
-All queries nest under `currentOrganization`. There is no top-level resource query —
-everything is scoped to the authenticated user's organisation.
-
-```graphql
-{
-  currentOrganization {
-    id
-    # All other queries go here
-  }
-}
-```
-
----
-
-## Page Queries
-
-### `page(id: ID!)` → `PageUnion`
-
-Fetches a single page by ID. Returns `BasicPage | PhasedPage`.
-
-```graphql
-query GetPage($id: ID!) {
-  currentOrganization {
-    page(id: $id) {
-      ...PageFields         # core metadata
-      ...PhasedPageFields   # stage index (if phased)
-    }
-  }
-}
-```
-
-**Gem class:** `Query::Page`
-**For compat (full data):** Use `...CommonPageUnion` fragment (includes all field data).
-
-### `pages(...)` → `PageUnionConnection`
-
-Org-wide paginated page search. Returns full `PageUnion` from DB.
-
-**Arguments:**
-- `searchConf: Search` — filter/sort/query configuration
-- `templatesOnly: Boolean` — restrict to templates only
-- `showHiddenData: Boolean` — include hidden fields
-- `after/before/first/last` — cursor pagination
-
-**Performance note:** ~3 seconds per page on render (DB-backed). Avoid large result sets.
-
-```graphql
-query OrgSearchPages($searchConf: Search, $first: Int, $after: String) {
-  currentOrganization {
-    pages(searchConf: $searchConf, first: $first, after: $after) {
-      totalCount
-      pageInfo { hasNextPage endCursor }
-      nodes { ...PageFields }
-    }
-  }
-}
-```
-
-**Gem class:** `Query::Pages`
-
-### `templates(...)` → `PageConnection`
-
-Lists templates (pages with `templatesOnly: true`). Same arguments as `pages`.
-
-**Gem class:** `Query::Templates`
-
-### `register(id:) { previewPages(...) }` → `PreviewPageConnection`
-
-ES-backed fast register search. Returns `PreviewPage` — metadata only, no field IDs.
-
-**Arguments on `previewPages`:**
-- `searchConf: Search`
-- `includeArchived: Boolean` (default false)
-- `presetViewId: ID` — apply a register PageView preset
-
-**Performance:** Sub-second (Elasticsearch). Use for metadata lookup.
-**Limitation:** No `patchVer`, no field IDs. Cannot be used for mutation input building.
-
-```graphql
-query RegisterSearch($registerId: ID!, $search: Search, $includeArchived: Boolean) {
-  currentOrganization {
-    register(id: $registerId) {
-      previewPages(searchConf: $search, includeArchived: $includeArchived) {
-        totalCount
-        pageInfo { hasNextPage endCursor }
-        nodes { id uid name state archived externalId createdAt { dateTime } }
-      }
-    }
-  }
-}
-```
-
-**Gem class:** `Query::RegisterPreviewPages`
-
-### `pageDelta(deltaInput: [DeltaInput!]!, searchConf: Search)` → `[DeltaResult!]!`
-
-Cache-invalidation query. Given a list of `{ id, deltaAt }` pairs, returns which pages
-have changed since the given timestamp.
-
-**`DeltaResult`:** `{ id: ID!, delta: DeltaEnum! }` where `DeltaEnum = UPDATED | NOT_FOUND | NEW`
-
-**Gem class:** `Query::PageDelta`
-
----
-
-## Page Mutations
-
-### `buildPageFromTemplate(input: BuildFromTemplateInput!)` → `BuildFromTemplatePayload`
-
-**Step (a) of the 2-step create sequence.** Builds a draft without persisting it.
-Returns a `PageUnion` with server-assigned field IDs (the template's field IDs mapped
-to new instance IDs). Use these IDs to populate `dataFields.updates` in `createFromTemplate`.
-
-```graphql
-mutation BuildPage($input: BuildFromTemplateInput!) {
-  buildPageFromTemplate(input: $input) {
-    errors { details fullMessages }
-    item { ...CommonPageUnion }
-  }
-}
-```
-
-**Variables:** `{ templateId: "...", showHiddenData: true }`
-
-### `createPageFromTemplate(input: CreateFromTemplateInput!)` → `CreateFromTemplatePayload`
-
-**Step (b) of the 2-step create sequence.** Creates the page from a filled draft.
-
-**Key `CreateFromTemplateInput` fields:**
-- `templateId: ID!`
-- `dataFields: DataFieldOneToManyInput!` — field values to set on creation
-- `page: PageInput` — page-level fields (name, state, locations, etc.)
-- `showHiddenData: Boolean`
-- `stageId: ID` — target stage
-- `submit: Boolean` — submit immediately
-- `draft: Boolean` — create as draft
-
-### `updatePage(input: UpdatePageInput!)` → `UpdatePagePayload`
-
-Updates an existing page.
-
-**Key `UpdatePageInput` fields:**
-- `id: ID!`
-- `patchVer: Int` — **MUST match current page patchVer**
-- `page: PageInput` — page-level fields to change
-- `dataFields: DataFieldOneToManyInput` — field updates and/or additions
-- `stageId: ID` — target specific stage (required for stage submit/close-out)
-- `submit: Boolean` — submit the stage (triggers task assignment server-side)
-- `publish: Boolean` — publish a draft page
-- `showHiddenData: Boolean`
-
-**DataFieldOneToManyInput:**
-```json
-{
-  "updates":   [{ "plainText": { "id": "FIELD_ID", "value": "..." } }],
-  "additions": [{ "date": { "id": "NEW_ID", "value": "..." } }],
-  "deletions": ["FIELD_ID_TO_DELETE"]
-}
-```
-
-### `archivePage(input: ArchivePageInput!)` / `unarchivePage(...)` → payload with `item: PageUnion`
-
-Archive/unarchive a page.
-
-**Production pattern (compound mutation):**
-When a page has a unique `externalId`, archive the externalId first to prevent conflicts
-on future re-creation, then archive:
-
-```graphql
-mutation ArchivePage($id: ID!, $blank_external_id: Boolean = true) {
-  updatePage(input: { id: $id, page: { externalId: null } })
-    @include(if: $blank_external_id) {
-    item { id externalId }
-  }
-  archivePage(input: { id: $id }) {
-    item { id archived }
-    errors { details fullMessages }
-  }
-}
-```
-
-This compound mutation (two in one request) was designed for stateless middleware
-clients that cannot sequence separate HTTP calls.
-
----
-
-## Fragments
-
-### `PageFields` (on `BasePageInterface`)
-
-Core metadata fragment — always include `__typename` for `PageUnion` dispatch.
-
-Fields: `__typename id name uid icon patchVer state archived archivedAt draft externalId
-timeZone otherTags taskPriority sourceTemplateId createdAt updatedAt creatorName locations { ...LocationNode }`
-
-**Gem:** `Fragment::PageFields` in `fragment/page.rb`
-
-### `BasicPageFields` (on `BasicPage`)
-
-Sections available directly on BasicPage:
-```graphql
-fragment BasicPageFields on BasicPage {
-  sections { __typename ... on ContentSection { id heading } ... on SplitSection { id heading } }
-}
-```
-
-**Gem:** `Fragment::BasicPageFields`
-
-### `PhasedPageFields` (on `PhasedPage`)
-
-Stage index for phased pages (lightweight — no data fields):
-```graphql
-fragment PhasedPageFields on PhasedPage {
-  stagesIndex { id name ordering state started hasCompleteTask hasReviewTask }
-  currentStage { id name ordering state }
-  activeStages  { id name ordering }
-}
-```
-
-**Gem:** `Fragment::PhasedPageFields`
-
-### `CommonPageUnion` (on `PageUnion`) — THE STANDARD FRAGMENT
-
-The comprehensive fragment covering all customer integration patterns.
-Located in `Fragment::Pages` (sub-namespace, accessed via `fragment.pages.assemble(:CommonPageUnion)`).
-
-**Boolean variables controlling payload:**
-
-| Variable | Purpose |
-|---|---|
-| `$content` | Include field values, stage completion info, files, people |
-| `$only_content` | Exclude structural/config — content values only |
-| `$fields` | Include field definitions (labels, types, options — needed for mutation input building) |
-
-**Three use cases:**
-1. **Build from template** — `$fields: true, $content: false` → get field structure + IDs
-2. **Fetch before update** — `$content: true, $fields: true` → current values + IDs for mutation
-3. **Verify after create/update** — `$content: true, $only_content: true` → confirm result
-
-**Fragment source:** `lib/ecoportal/api/graphql/fragment/pages/common_page_union.rb`
-**Documented in:** Jira API Docs space (Confluence APIDOCS)
-
-### `LocationNode` (on `LocationNodeInterface`)
-
-Location node fragment with ancestors and classifications. Automatically assembled
-when `...LocationNode` appears in a query via the recursive `assemble_fragments` mechanism.
-
----
-
-## Fragment Assembly (How It Works)
-
-The gem scans query strings for `...FragmentName` spreads and assembles the needed
-fragment definitions RECURSIVELY. A fragment that references another fragment
-(e.g. `PageFields → ...LocationNode`) is resolved automatically.
-
-Sub-namespaces (`Fragment::Pages`) are registered via `Fragment.register_namespace(Pages)`
-so `Fragment.assemble(:CommonPageUnion)` finds it.
-
----
-
-## Other Key Queries
-
-### `contractorEntities(...)` → `ContractorEntityConnection`
-### `actionCategories(...)` → `ActionCategoryConnection`
-### `action(id:)` → `Action`
-### `actions(...)` → `ActionConnection`
-### `locationStructure(id:)` → `LocationStructure`
-### `locationStructures(...)` → `LocationStructureConnection`
-### `registers(...)` → register list
-### `personMembers(...)` → `PersonMemberConnection`
-### `pageDelta(...)` → cache invalidation

data/.ai-assistance/code/ecoPortal_architecture/05_page_workflows.md

@@ -1,200 +0,0 @@
-# EcoPortal Page Workflows
-
----
-
-## The 2-Step Create Sequence
-
-Creating a page from a template ALWAYS requires two steps because MongoDB assigns field
-IDs at creation time — the client must know these IDs to populate field values.
-
-### Step A: Build from Template
-
-```ruby
-# GraphQL
-payload = Mutation::Page::BuildFromTemplate.new(client).query(
-  input: { templateId: template_id, showHiddenData: true }
-) do
-  item { spread :CommonPageUnion }
-end
-draft = payload.item
-```
-
-This returns a `PageUnion` with:
-- All field definitions for the template (labels, types, options)
-- Server-assigned field IDs (instance IDs, NOT template field IDs)
-- Default values where configured
-- Stage structure (for PhasedPage)
-
-**Important:** The returned page is NOT persisted yet.
-
-### Step B: Fill and Create
-
-```ruby
-# Modify fields using the instance field IDs from the draft
-draft.components.get_by_name('Job Number').value = 'JOB-001'
-draft.components.get_by_type(:select).find { |f| f.label == 'Status' }.select_option('Active')
-
-# Build field updates from dirty fields
-field_updates = draft.data_fields_updates  # → [DataFieldInput, ...]
-
-# Create the page
-payload = Mutation::Page::CreateFromTemplate.new(client).query(
-  input: {
-    templateId: template_id,
-    dataFields: { updates: field_updates },  # uses instance field IDs from draft
-    page: { externalId: 'EXT-001', name: 'My Record' }
-  }
-)
-ref = Compat::PageReference.new(payload.item)
-# ref.page_id → the created page's ID
-# ref.active_stage_id → ID of the first active stage
-```
-
----
-
-## The 2-Step Update Sequence
-
-Updating a page ALWAYS requires fetching first to get:
-1. `patchVer` — required for optimistic concurrency
-2. Current field IDs — for building `dataFields.updates`
-3. Current field values — for computing changes
-
-### Step A: Fetch Current Page
-
-```ruby
-page = Query::Page.new(client).query(id: page_id) do
-  spread :CommonPageUnion
-end
-# OR via compat layer:
-page = graphql.pages.get(page_id)
-```
-
-### Step B: Modify and Update
-
-```ruby
-# Modify page-level fields
-page.name = 'Updated Name'
-page.external_id = 'NEW-EXT-001'
-
-# Modify data fields
-page.components.get_by_name('Summary').value = 'Updated summary'
-
-# Send update
-input = Input::Page::Update.from_model(page)
-# input[:patchVer] — injected automatically from page.patchVer
-# input[:page]     — page-level changes
-# input[:dataFields] — field-level changes
-payload = Builder::Page.new(client).update(input: input)
-```
-
-**Why patchVer matters:** If two scripts update the same page concurrently, the second
-update will fail with a stale-patchVer error. Re-fetch the page to get the new patchVer.
-
----
-
-## Stage Submit / Close-Out Sequence
-
-When a stage needs to be submitted (triggering task assignment on the next stage):
-
-```ruby
-# Fetch page with full stage data
-page = graphql.pages.get(page_id)
-
-# Get stage view for the specific stage
-stage_view = graphql.pages.get(page_id, stage_id: 's1_id')
-# stage_view.sections, stage_view.components → filtered to this stage only
-
-# Fill in field data for this stage
-stage_view.components.get_by_name('Risk Level').select_option('High')
-
-# Submit the stage
-input = Input::Page::Update.from_model(
-  stage_view,
-  stage_id: 's1_id',
-  submit:   true
-)
-payload = Builder::Page.new(client).update(input: input)
-```
-
-**What `submit: true` triggers server-side:**
-- Stage state changes to `complete`
-- Next fill-in task (`CompletePage`) is created and assigned per workflow rules
-- Or if review is configured: `ReviewPage` task is created
-- People fields scoped to the next stage may generate access grants
-
-**Important:** Without `stageId`, the server may not correctly associate the submit
-with the right stage. Always include `stageId` when submitting a specific stage.
-
----
-
-## Archive Sequence
-
-Standard archive (no externalId concern):
-```ruby
-payload = Builder::Page.new(client).archive(input: { id: page_id })
-```
-
-With externalId blanking (production pattern for deduplication safety):
-```graphql
-mutation ArchivePage($id: ID!, $blank_external_id: Boolean = true) {
-  updatePage(input: { id: $id, page: { externalId: null } })
-    @include(if: $blank_external_id) {
-    item { id }
-  }
-  archivePage(input: { id: $id }) {
-    item { id archived }
-    errors { details fullMessages }
-  }
-}
-```
-
----
-
-## Find-Before-Create (Deduplication Pattern)
-
-To prevent creating duplicate pages based on a unique identifier:
-
-```ruby
-# Step 1: Search for existing page
-conf = SearchConf.new
-  .filter(SearchConf::Register.new(register_id))
-  .filter(SearchConf::Exact.new(:external_id, 'EXT-001'))
-
-result = org.pages(searchConf: conf.to_h, first: 1)
-existing = result.nodes.first
-
-if existing
-  # Page exists — update it
-  page = graphql.pages.get(existing.id)
-  # ... modify and update
-else
-  # Page doesn't exist — create it
-  draft = graphql.pages.get_new(template_id)
-  # ... fill and create
-end
-```
-
-**Why org search (not register search):** Register search (`previewPages`) is ES-backed
-and fast, but returns `PreviewPage` without field IDs or `patchVer`. For update workflows,
-always use org search (`pages`) with `register_filter` to get the full page.
-
----
-
-## Simulate / Dry Run Mode (eco-helpers Pattern)
-
-eco-helpers scripts support a dry-run mode where changes are computed but not sent:
-
-```ruby
-# In eco-helpers, dirty? checks for pending changes
-if dirty?(page)
-  if simulate?
-    puts "Would update: #{pages.get_body(page).inspect}"
-  else
-    pages.update(page)
-    page.consolidate!  # reset dirty tracking
-  end
-end
-```
-
-The `get_body(page)` method returns `page.as_update` — the computed change diff.
-`consolidate!` resets the `original_doc` baseline so the page is no longer dirty.

data/.ai-assistance/code/ecoPortal_architecture/06_search_and_filters.md

@@ -1,228 +0,0 @@
-# EcoPortal Search and Filters
-
----
-
-## Two Search Modalities
-
-### 1. Org Search — `currentOrganization { pages(...) }`
-
-**Data source:** PostgreSQL/MongoDB — full DB render
-**Returns:** `PageUnion` (BasicPage | PhasedPage) — complete data
-**Performance:** ~3 seconds per page (API-layer assembly)
-**Supports archived:** Yes (via `searchConf` state filter)
-**Has field IDs:** Yes — use for pre-update fetch
-**patchVer:** Yes — required for mutations
-
-Use when you need full field data to build mutation inputs.
-
-**Arguments:**
-- `searchConf: Search` — filter/sort/query
-- `templatesOnly: Boolean` — restrict to templates
-- `showHiddenData: Boolean` — include hidden fields
-- `first/last/after/before` — cursor pagination
-
-**Key `searchConf` filter for register-scoping within org search:**
-```json
-{ "operation": "register_filter", "params": { "ids": ["REGISTER_ID"] } }
-```
-This scopes the org search to a register without switching to `previewPages`.
-
-### 2. Register Search — `currentOrganization { register(id:) { previewPages(...) } }`
-
-**Data source:** Elasticsearch — search index snapshot
-**Returns:** `PreviewPage` — metadata only (id, name, state, locations, dataFields as previews)
-**Performance:** Sub-second (ES-powered)
-**Supports archived:** Yes — `includeArchived: Boolean` parameter (default false)
-**Has field IDs:** NO — cannot build mutation inputs from this
-**patchVer:** NO
-
-Use for fast metadata lookup (find page IDs, check existence, list pages).
-
-**Additional arguments:**
-- `presetViewId: ID` — apply a register PageView preset configuration
-- `searchConf: Search`
-- `includeArchived: Boolean`
-
-**Field name:** `previewPages` (not `pages`) — common confusion point.
-
----
-
-## SearchConf Structure
-
-`searchConf` is a `Hash` type (`Search` in the schema) — NOT a typed GraphQL input.
-Engineering has backend classes but they are not exposed as GraphQL types.
-
-```json
-{
-  "filters": [ <filter_object>, ... ],
-  "sorters": { "key": "created_at", "direction": "asc" },
-  "query":   "optional full-text search string"
-}
-```
-
-**Note on sorters:** Can be a single object OR an array. Key field is `key` (not `fieldName`).
-
----
-
-## Filter Operations
-
-**ALL operation names are snake_case strings.** If CamelCase is used (e.g. `ExactFilter`),
-the server returns NO error AND NO results — completely silent failure. This is one of
-the hardest bugs for customers to diagnose.
-
-**`filters` should always be an Array.** The server normalises a single object to an
-array internally, but always use array form for consistency.
-
-### `exact_filter`
-
-Equality match on a field.
-
-```json
-{ "operation": "exact_filter", "params": { "key": "external_id", "value": "EXT-001" } }
-```
-
-Common keys: `external_id`, `state`, `creator_id`, `template_id`
-
-### `date_filter`
-
-Date range filter.
-
-```json
-{
-  "operation": "date_filter",
-  "params": {
-    "key":       "updated_at",
-    "gte":       "2025-01-01T00:00:00Z",
-    "lte":       "2025-12-31T23:59:59Z",
-    "time_zone": "UTC"
-  }
-}
-```
-
-`gte` = lower bound, `lte` = upper bound. Both optional.
-
-**v2 format note:** APIv2 used `lbound`/`ubound` instead of `gte`/`lte`. The
-eco-helpers compat layer translates these automatically.
-
-### `register_filter`
-
-Scope org search to specific registers (org search only — not applicable to `previewPages`).
-
-```json
-{ "operation": "register_filter", "params": { "ids": ["REGISTER_ID"] } }
-```
-
-### `and_filter`
-
-Explicit AND group (top-level `filters` array is already implicit AND).
-
-```json
-{
-  "operation": "and_filter",
-  "params": {
-    "filters": [
-      { "operation": "exact_filter", "params": { "key": "external_id", "value": "X" } },
-      { "operation": "date_filter",  "params": { "key": "updated_at",  "gte": "..." } }
-    ]
-  }
-}
-```
-
-### `or_filter`
-
-OR group.
-
-```json
-{
-  "operation": "or_filter",
-  "params": {
-    "filters": [
-      { "operation": "exact_filter", "params": { "key": "external_id", "value": "A" } },
-      { "operation": "exact_filter", "params": { "key": "external_id", "value": "B" } }
-    ]
-  }
-}
-```
-
-### `tag_filter` (v2 pass-through)
-
-Filter by location tags. Used by APIv2 eco-helpers scripts. Passes through to the ES
-backend unchanged. Same ES backend as GraphQL register search.
-
-```json
-{
-  "type": "tag_filter",
-  "tags": ["Auckland", "Wellington"],
-  "mode": "any",
-  "negate": false,
-  "key": "tags"
-}
-```
-
----
-
-## SearchConf Builder (Gem)
-
-The gem provides `Input::SearchConf` for building filters programmatically:
-
-```ruby
-# Find by externalId
-conf = SearchConf.new.filter(SearchConf::Exact.new(:external_id, 'EXT-001'))
-
-# Register-scoped date range
-conf = SearchConf.new
-  .filter(SearchConf::Register.new('REG_ID'))
-  .filter(SearchConf::DateRange.new(:updated_at, gte: '2025-01-01', time_zone: 'UTC'))
-  .sort(:created_at, :asc)
-
-# OR filter (multiple externalIds)
-conf = SearchConf.new.filter(
-  SearchConf::Or.new(
-    SearchConf::Exact.new(:external_id, 'EXT-001'),
-    SearchConf::Exact.new(:external_id, 'EXT-002')
-  )
-)
-
-# Parametrize (same search, different value)
-base = SearchConf.new.filter(SearchConf::Exact.new(:external_id, 'X'))
-copy = base.with(external_id: 'Y')  # original unchanged
-
-# Use with queries
-org.pages(searchConf: conf.to_h, first: 10)
-```
-
-**Filter classes:** `SearchConf::Exact`, `SearchConf::DateRange`, `SearchConf::Register`,
-`SearchConf::And`, `SearchConf::Or`
-
----
-
-## Known Filterable Field Keys (confirmed from production queries)
-
-| key | Type | Operations |
-|-----|------|------------|
-| `external_id` | string | `exact_filter` |
-| `updated_at` | datetime | `date_filter` |
-| `created_at` | datetime | `date_filter` (likely) |
-| `state` | enum | `exact_filter` (key: active/archived/draft) |
-| `location_ids` | ID array | likely `in_filter` or similar |
-| `creator_id` | ID | `exact_filter` |
-| `template_id` | ID | `exact_filter` |
-
-**Note:** The `fieldName` convention in some Confluence docs uses this same key concept.
-The keys are snake_case corresponding to indexed ES document fields — NOT necessarily
-the GraphQL field names.
-
----
-
-## Future: Fluent DSL (Planned)
-
-A more ergonomic API using Ruby's `&` (AND) and `|` (OR) operators is planned:
-
-```ruby
-Search[:external_id].eq('EXT-001') & Search.in_register('REG_ID')
-Search[:state].is(:active) | Search[:state].is(:draft)
-(Search[:state].is(:active) | Search[:state].is(:draft)) & Search.in_register('REG_ID')
-```
-
-This is operator-based (familiar to Arel/Sequel users), avoids ambiguity in chaining,
-and will support AI-assisted filter generation. See `search-filter-builder/` project.