ecoportal-api-graphql 1.3.5 → 1.3.9

data/.ai-assistance/code/schema_analysis.md

@@ -0,0 +1,321 @@
+# Code Spec: EcoPortal GraphQL Schema Analysis
+
+**Source:** Live introspection from `live.ecoportal.com` — `20260605T101224_live_ep_graphql_schema.graphql.json`
+**Last updated:** 2026-06-05
+
+---
+
+## Schema Overview
+
+- **161 mutations** across all feature areas
+- **22 top-level Query fields** — everything important lives under `currentOrganization`
+- **No subscriptions**
+- All mutations use a single `input: SomeMutationType!` wrapper argument (consistent)
+
+---
+
+## Top-Level Query Fields
+
+All via `currentOrganization: Organization!`:
+
+```
+action / actions / actionDelta / actionsByPage / actionCategories / actionsCounter
+contractorEntity / contractorEntities / contractorEntityDelta
+page / pages / pageDelta / myDraftPages / allPages / fullTemplates / minimalTemplates / templates
+locationStructure → via org.locations.structure
+personMember / personMembers / personMemberDelta
+register / registers
+checkInConfig / checkInConfigs / visitorTypes / visits / visitStatus / identifyVisitor
+charts / home / reporting (namespaced dashboards)
+userGroup / userGroups
+... plus 80+ org-level scalar/boolean config fields
+```
+
+---
+
+## Page Model
+
+### PageUnion members
+`BasicPage` | `PhasedPage` — only two concrete page types.
+
+### BasePageInterface (50 fields — all pages)
+
+Key fields for gem mapping:
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `id` | `ID!` | already mapped |
+| `name` | `String!` | already mapped |
+| `uid` | `String` | already mapped |
+| `icon` | `String!` | already mapped |
+| `patchVer` | `Int!` | **critical — concurrency lock** |
+| `state` | `StateEnum` | INACTIVE/ACTIVE/COMPLETE |
+| `archived` | `Boolean!` | already mapped |
+| `archivedAt` | `DateTime` | already mapped |
+| `draft` | `Boolean!` | not mapped |
+| `externalId` | `ID` | not mapped |
+| `locations` | `[LocationNodeInterface!]!` | already mapped (read-only) |
+| `otherTags` | `[String!]` | already mapped |
+| `taskPriority` | `TaskPriorityEnum` | low/medium/high/none — already mapped |
+| `timeZone` | `String` | already mapped |
+| `sourceTemplateId` | `ID` | already mapped |
+| `template` | `Template` | commented out |
+| `organization` | `Organization!` | commented out |
+| `registers` | `[Register!]!` | commented out |
+| `workflow` | `PagesWorkflow` | not mapped |
+| `creatorName` | `String` | already mapped |
+| `lastUpdatedByName` | `String` | already mapped |
+| `printingEnabled` | `Boolean!` | already mapped |
+| `inSystemPagesEnabled` | `Boolean!` | already mapped |
+| `hasSmartFields` | `Boolean!` | not mapped |
+| `contentShareable` | `Boolean!` | not mapped |
+| `enableEmailOut` | `Boolean!` | not mapped |
+| `totalReferencesCount` | `Int!` | not mapped |
+| `mouldCounter` | `String` | not mapped (counter display field) |
+
+### BasicPage (beyond interface)
+`dataFields`, `sections`, `globalBindings`, `activities`, `attachedFiles`, `currentAiSummaryVersion`
++ extensive `can*` authorization fields (canUpdate, canArchive, canPermission, etc.)
+
+### PhasedPage (beyond interface)
+Everything from BasicPage plus:
+`stages`, `activeStages`, `currentStage`, `stagesIndex`, `latestStageOrdering`
+`showAssigneeNamesForRestrictedStages`, `showStrategyForRestrictedStages`, `showTaskDueDateForRestrictedStages`
+
+### Stage type (key fields)
+`id`, `name`, `ordering`, `state (StageStateEnum)`, `active`, `started`, `locked`
+`dataFields`, `sections`, `globalBindings`, `tasks`, `activeTask`
+`completionTaskConfig`, `reviewTaskConfig`, `workflowCallbacks`
+`forces`, `allowedUserGroupIds`, `tags`
+`canUpdate`, `canAccess`, `canPermission`, etc.
+
+### Page mutation inputs
+
+**`UpdatePageInput`** (single `input: UpdatePageInput!` wrapper):
+```
+id: ID!
+stageId: ID              — target stage for phased pages
+submit: Boolean          — submit stage
+dataFields: DataFieldOneToManyInput  — { additions, updates, deletions }
+task: TaskInput
+page: PageInput          — { locations, otherTags, timeZone, state, taskPriority, name, externalId }
+showHiddenData: Boolean
+patchVer: Int            — optimistic lock (optional but recommended)
+publish: Boolean         — for draft pages
+```
+
+**Page creation** — always from a template:
+- `createPageFromTemplate(input: CreateFromTemplateInput!)` — primary creation path
+  - `templateId: ID!`, `dataFields: DataFieldOneToManyInput!` (required), `page: PageInput`, `stageId`, `submit`, `attach`, `draft`
+- `buildPageFromTemplate(input: BuildFromTemplateInput!)` — lighter, no data fields
+- `createPageDraft(input: CreatePageDraftInput!)` — draft from template, `templateId: ID!`
+
+**Page state mutations:**
+`archivePage`, `unarchivePage`, `deleteDraftPage`, `publishDraftPage`
+`approveReviewPageTask`, `rejectReviewPageTask`, `batchUpdateReviewPageTask`, `restartReviewPageTask`, `undoReviewPageTask`
+
+**Page output:**
+`updatePage` → `{ item: PageUnion, nextTasks: [MinimalTaskInterface], errors: ValidationErrors }`
+
+### DataFieldInput (20 field types)
+```
+locationField, plainText, checklist, number, date, select, richText,
+signature, gauge, geo, file, imageGallery, crossReference,
+contractorEntities, people, law, mailbox, actionsList, aiSummary, table
+```
+Passed as `DataFieldOneToManyInput { additions, updates, deletions }`.
+
+### `patchVer` — concurrency control
+- `Int!` on `BasePageInterface` (non-null on every page read)
+- `Int` (optional) on `UpdatePageInput`
+- Also present on `CheckInConfig` — kiosk configurations share this mechanism
+- **Pattern:** read `patchVer` from current page → pass it back in `updatePage` input → server rejects if stale
+
+---
+
+## Action Model
+
+### `Action` type — fields in schema vs gem
+
+| Field | Schema Type | Gem (`Base::Action`) |
+|-------|-------------|----------------------|
+| `id` | `ID!` | `passkey :id` ✓ |
+| `name` | `String!` | `passthrough :name` ✓ |
+| `description` | `String` | `passthrough :description` ✓ |
+| `status` | `String!` | `passthrough :status` ✓ |
+| `relativeStatus` | `String!` | `passthrough :relativeStatus` ✓ |
+| `archived` | `Boolean!` | `passboolean :archived` ✓ |
+| `attached` | `Boolean!` | `passboolean :attached` ✓ |
+| `standaloneAction` | `Boolean!` | `passboolean :standaloneAction` ✓ |
+| `actionCategoryId` | `String` | `passthrough :actionCategoryId` ✓ |
+| `assignedPersonMemberIds` | `[ID!]` | `passarray :assignedPersonMemberIds` ✓ |
+| `locationIds` | `[ID!]` | `passarray :locationIds` ✓ |
+| `fileContainerIds` | `[ID!]!` | `passarray :fileContainerIds` ✓ |
+| `altId` | `String` | `passthrough :altId` ✓ |
+| `timeZone` | `String` | `passthrough :timeZone` ✓ |
+| `dueDate` | `DateTime` | `embeds_one :dueDate` ✓ |
+| `reminderDate` | `DateTime` | `embeds_one :reminderDate` ✓ |
+| `completedAt` | `DateTime` | `embeds_one :completedAt` ✓ |
+| `closedAt` | `DateTime` | `embeds_one :closedAt` ✓ |
+| `createdAt` / `updatedAt` | `DateTime` | `embeds_one` ✓ |
+| `completed` | `Boolean!` (implicit) | `passboolean :completed` ✓ |
+| `closeDetail` | `String` | `passthrough :closeDetail` ⚠ (should embed) |
+| `recurrence` | `Recurrence` | **missing** ✗ |
+| `dueIn` | `DateInMinutes` | commented out ✗ |
+| `reminderIn` | `DateInMinutes` | commented out ✗ |
+| `age` | `Int!` | `passthrough :age` ✓ |
+| `tags` | `[String!]!` | **missing** ✗ |
+| `linkedResources` | `[Resource!]!` | **missing** ✗ |
+| `activities` | `ActionActivityConnection!` | **missing** (read-only, complex) |
+
+### `UpdateActionInput` vs `CreateActionInput`
+
+Both wrapped under `input:` — both take:
+`name: String!`, `description`, `actionCategoryId`, `dueDate/reminderDate`, `timeZone`, `status`, `completed`, `archived`, `assignedPersonMemberIds`, `locationIds`, `fileContainerIds`, `recurrence: ActionRecurrenceInput`, `dueIn`, `reminderIn`, `closeDetail: ActionCloseDetailInput`
+
+`UpdateActionInput` adds: `id: ID!`, `updateMode: SeriesUpdateMode (ALL|FORWARD|ONE)`
+`CreateActionInput` adds: `draft`, `linkedResource: ActionResourceInput`, no `updateMode`
+
+### `ActionRecurrenceInput` — not mapped in gem
+```
+daily:   { frequency: Int!, copyAssignees, creationTimeframe: CreationTimeframeInput!, endTime }
+weekly:  { frequency: Int!, copyAssignees, creationTimeframe, endTime, daysOfWeek: [WeekDay!]! }
+monthly: { frequency: Int!, copyAssignees, creationTimeframe, endTime, daysOfMonth, nthWeekday: NthWeekdayInput }
+```
+
+### `ActionCloseDetailInput`
+`{ comment: String, fileContainerIds: [ID!] }` — currently a raw passthrough, should be embedded model.
+
+---
+
+## ContractorEntity Model
+
+### Create vs Update input difference
+| Field | Create | Update |
+|-------|--------|--------|
+| `leadContractorIds` | `[ID!]` | `IdDiffInput` |
+| `associatedPeopleIds` | `[ID!]` | `IdDiffInput` |
+
+`IdDiffInput = { additions: [ID!], removals: [ID!] }`
+
+The gem must distinguish `Create` vs `Update` input construction for these fields.
+
+---
+
+## LocationStructure
+
+### `UpdateLocationStructureInput`
+```
+id: ID!, name, visitorManagementEnabled: Boolean, archived, published, weight: Int
+```
+No `patchVer` on location structures.
+
+### Additional mutations not yet in gem
+`createLocationStructure`, `updateLocationStructure`, `exportLocationStructureCsv`
+`createLocationStructureSftpIntegration`, `updateLocationStructureSftpIntegration`, `deleteLocationStructureSftpIntegration`
+
+---
+
+## Visitor Management / CheckIn
+
+Accessible via `currentOrganization`:
+```
+checkInConfig(id:)         → CheckInConfig!
+checkInConfigs(...)        → CheckInConfigConnection
+visitorTypes(...)          → VisitorTypeConnection
+visits(...)                → VisitConnection
+visitStatus(...)           → Visit
+identifyVisitor(...)       → IdentifiedVisitor
+```
+
+### `CheckInConfig` — has `patchVer: Int!`
+Key mutable fields: `name`, `primaryColor`, `requirementsEnabled`, `visitorTypeConfigurations`,
+`autoCheckOut`, `legalAgreements`, `locationIds (IdDiffInput)`, `notifyLeadsOnDenial`,
+`smsLeadsEnabled`, `registerIntegrations`
+
+### `UpdateCheckInConfigInput`
+```
+id: ID!, name, primaryColor, requirementsEnabled: Boolean!
+visitorTypeConfigurations: VisitorTypeConfigurationOneToManyInput!
+autoCheckOut: AutoCheckOutConfigurationInput
+legalAgreements: LegalAgreementOneToManyInput
+locationIds: IdDiffInput   ← CRITICAL for kiosk/RS location fixes
+registersAcknowledgement: Boolean!, registerIntegrations: [RegisterIntegrationInput!]
+...
+```
+
+**Customer use case:** when RS location structure changes break kiosk location bindings,
+use `updateCheckInConfig(input: { id:, locationIds: { additions: [...], removals: [...] } })`.
+
+---
+
+## Delta / Incremental Sync
+
+Available on `currentOrganization`:
+```
+pageDelta(ids: [ID!]!)             → [DeltaResult!]!
+actionDelta(ids: [ID!]!)           → [DeltaResult!]!
+contractorEntityDelta(ids: [ID!]!) → [DeltaResult!]!
+personMemberDelta(ids: [ID!]!)     → [DeltaResult!]!
+templateDelta(ids: [ID!]!)         → [DeltaResult!]!
+```
+`DeltaResult = { id: ID!, delta: DeltaEnum! }` where `DeltaEnum = UPDATED | NOT_FOUND | NEW`
+
+**Use case for scripts:** Check if a cached set of IDs has changed before re-fetching.
+
+---
+
+## PersonMember
+
+Rich type — `id`, `name`, `email`, `realEmail`, `externalId`, `phoneNumber`, `avatarUrl`
+`personSchema`, `personSchemaId`, `userGroups`, `userGroupIds`
+`organizationHierarchy`, `supervisorId`, `contractorOrganization`, `contractorOrganizationId`
+`prefilterLocations`, `prefilterTags`, `tagRestrict`
+`privateFields`, `publicFields` (MemberSchemaFields — custom person schema data)
+`relatedPages`, `pinnedItems`, `taskCount`
+
+**No mutation support** in gem, no `Query::PersonMembers`. Org has:
+`personMember(id:)`, `personMembers(searchConf:)`, `attachablePersonMembers(searchConf:)`, `personMembersCreatedSince(date:)`
+
+---
+
+## AI-Powered Mutations (future reference)
+
+```
+aiToolsFixSpellingGrammar    — fix text fields
+aiToolsMakeFormal            — formalize text
+aiToolsRephrase              — rephrase content
+aiToolsSummarize             — summarize content
+aiToolsTranslate             — translate
+generatePageFilters          — AI-generated search filters
+generatePageSmartFieldContent — fill smart fields automatically
+generatePageSummary          — generate page summary
+```
+
+---
+
+## Enums Reference
+
+| Enum | Values |
+|------|--------|
+| `StateEnum` | INACTIVE / ACTIVE / COMPLETE |
+| `ActionsStatusEnum` | open / closed |
+| `TaskPriorityEnum` | low / medium / high / none |
+| `SeriesUpdateMode` | ALL / FORWARD / ONE |
+| `DeltaEnum` | UPDATED / NOT_FOUND / NEW |
+
+---
+
+## Gem Coverage Summary
+
+| Area | Queries | Mutations | Status |
+|------|---------|-----------|--------|
+| Actions | ✓ actions, action, actionCategories | ✓ create, update, archive | Well covered |
+| ContractorEntities | ✓ contractorEntities, contractorEntity | ✓ create, update, destroy | Well covered |
+| LocationStructure | ✓ structure, structures, locationDraftById | ✓ draft mutations | Well covered |
+| **Pages** | **✗ nothing** | **✗ nothing** | **Major gap** |
+| PersonMembers | ✗ | ✗ | Gap |
+| Registers | ✗ | ✗ | Gap |
+| Visitor management | ✗ | ✗ | Gap (customer urgency) |
+| Dashboards/Charts | ✗ | ✗ | Future |
+| Delta queries | ✗ | n/a | Useful for scripts |