ecoportal-api-graphql 1.3.13 → 1.3.16

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

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