@opencxh/domain 1.172.1 → 1.173.0

package/dist/entities/work/types.d.ts

@@ -1,58 +1,56 @@
 import { OwnerScope } from '../scope/types';
 /**
- * Work management — één entiteit voor alles wat *werk* is.
+ * Work management — one entity for everything that is *work*.
  *
- * Taak, subtaak, zaak, project, fase, deal en campagne zijn hier rijen in hetzelfde model.
- * Wat ze onderscheidt is configuratie, geen code: het **project** draagt de workflow, de
- * veldselectie en de toegang, en `typeKey` is niet meer dan een icoon met een etiket.
+ * Task, subtask, case, project, phase, deal and campaign are rows in the same model here. What
+ * distinguishes them is configuration, not code: the **project** carries the workflow, the field
+ * selection and the access, and `typeKey` is no more than an icon with a label.
  *
- * De regel waarmee dit model is afgebakend, in drie vragen:
+ * The rule that bounds this model, in three questions:
  *
- * 1. *Wie bepaalt de statusovergang?* Onze gebruikers → een `WorkItem`. Een extern systeem
- *    (Shopify, de boekhouding) → gespiegeld door de bron-app, hier hooguit een `WorkLink`.
- * 2. *Eigen levensduur, of hangt het ergens aan?* Eigen → een item. Hangt eraan (uren,
- *    notities, attributen, geheugen) → een annotatie op een `scopeKey`, nooit een rij hier.
- * 3. *Ander gedrag, of andere woorden?* Alleen andere woorden → een `WorkProject` met andere
- *    statussen. Pas bij ander gedrag komt er code bij.
+ * 1. *Who decides the status transition?* Our users → a `WorkItem`. An external system (Shopify,
+ *    the accounting package) → mirrored by the source app, at most a `WorkLink` here.
+ * 2. *Own lifetime, or does it hang off something?* Own → an item. Hangs off it (hours, notes,
+ *    attributes, memory) → an annotation on a `scopeKey`, never a row here.
+ * 3. *Different behaviour, or different words?* Only different words → a `WorkProject` with other
+ *    statuses. Code is added only for different behaviour.
  *
- * Test 3 is waarom "Dossier", "Project" en "Deal" geen drie entiteiten zijn.
+ * Test 3 is why "Case", "Project" and "Deal" are not three entities.
  */
 /**
- * De drie categorieën waarin elke status valt.
+ * The three categories every status falls into.
  *
- * Vast, terwijl de statusnaam per project vrij is ("Offerte", "Wacht op cliënt"). Dit is de
- * vraag die élke consument stelt — de lijst, de teller, de rapportage — en zou die de
- * projectconfiguratie moeten lezen om hem te beantwoorden, dan kon geen enkele query het
- * geïndexeerd doen.
+ * Fixed, while the status name is free per project ("Offerte", "Wacht op cliënt"). This is the
+ * question *every* consumer asks — the list, the counter, the reporting — and if it had to read
+ * the project configuration to answer it, no query could do it from an index.
  */
 export type WorkStatusCategory = "todo" | "in_progress" | "done";
 /**
- * Eén stap in de workflow van een project.
+ * One step in a project's workflow.
  *
- * `key` is **org-uniek en niet project-uniek**, en dat is een bewuste last op het
- * beheerscherm in ruil voor iets belangrijks: het item draagt alleen `statusKey`, dus
- * "al mijn open werk over alle projecten heen" is één `{ statusKey: anyOf(openKeys) }`.
- * Zouden twee projecten allebei een `done` mogen hebben met een andere categorie, dan gaf
- * diezelfde query stilzwijgend het verkeerde antwoord. De sleutel wordt daarom net als bij
- * de werksoorten uit het label geslugd en bij botsing opgehoogd.
+ * `key` is **org-unique and not project-unique**, a deliberate burden on the admin screen in
+ * exchange for something important: the item carries only `statusKey`, so "all my open work across
+ * every project" is one `{ statusKey: anyOf(openKeys) }`. If two projects could each have a `done`
+ * with a different category, that same query would silently give the wrong answer. So the key is
+ * slugged from the label and bumped on collision, as with the work types.
  *
- * `label` is vrij te hernoemen; `key` ligt vast zodra er items op staan.
+ * `label` is free to rename; `key` is fixed once items sit on it.
  */
 export interface WorkStatus {
     key: string;
     label: string;
     category: WorkStatusCategory;
     order: number;
-    /** Optionele accentkleur voor de bolletjes in de lijst en het beheerscherm. */
+    /** Optional accent colour for the dots in the list and the admin screen. */
     color?: string;
 }
 /**
- * Een afloopreden: hóé iets eindigde, los van wáár het staat.
+ * A resolution: *how* something ended, apart from where it sits.
  *
- * Bewust een vrij label zonder vaste betekenis en zonder uitkomst-vlag. Een advocatenkantoor
- * onderscheidt "geschikt" van "vonnis", een salesteam "gewonnen" van "verloren", en geen van
- * beide past in een enum die wij bedenken. De prijs staat in het plan: niets kan uitrekenen
- * hoeveel er goed afliep. Komt die vraag, dan is een `positive?: boolean` hier de plek.
+ * Deliberately a free label with no fixed meaning and no outcome flag. A law firm distinguishes
+ * "settled" from "judgment", a sales team "won" from "lost", and neither fits an enum we invent.
+ * The price is in the plan: nothing can compute how much ended well. If that question comes, a
+ * `positive?: boolean` belongs here.
  */
 export interface WorkResolution {
     key: string;
@@ -60,58 +58,57 @@ export interface WorkResolution {
     order: number;
 }
 /**
- * Een project: de drager van een werkproces.
+ * A project: the carrier of a work process.
  *
- * Dit is waar Jira zijn schemes heeft en wij niet. Workflow, veldselectie en toegang hangen
- * rechtstreeks aan het project in plaats van aan drie koppelbare configuratieobjecten — dat
- * scheelt de drie schermen die je bij Jira langs moet om één status te veranderen.
+ * This is where Jira has its schemes and we do not. Workflow, field selection and access hang
+ * directly off the project instead of off three linkable configuration objects — which saves the
+ * three screens Jira makes you visit to change one status.
  */
 export interface WorkProject {
     id: string;
     organizationId: string;
     /**
-     * Org-uniek, hoofdletters: `"SAL"`. Vormt het voorvoegsel van elke itemsleutel
-     * (`SAL-142`), en ligt daarom vast zodra er items zijn — hem wijzigen zou elke sleutel
-     * hernoemen, inclusief de exemplaren die mensen in een mail hebben geplakt.
+     * Org-unique, uppercase: `"SAL"`. Forms the prefix of every item key (`SAL-142`), and is
+     * therefore fixed once items exist — changing it would rename every key, including the ones
+     * people pasted into an email.
      */
     key: string;
     name: string;
     description?: string;
-    /** Lucide-icoonnaam. */
+    /** Lucide icon name. */
     icon?: string;
     color?: string;
     ownerScope: OwnerScope;
-    /** Leden bovenop `ownerScope` — wie er nog meer bij mag. */
+    /** Members on top of `ownerScope` — who else may reach it. */
     memberUserIds?: string[];
     memberTeamIds?: string[];
     /**
-     * De workflow, ingebed in plaats van een eigen entiteit.
+     * The workflow, embedded instead of its own entity.
      *
-     * Drie redenen. Niets bevraagt ooit een losse statusrij: elke itemvraag wordt beantwoord
-     * door de platte `statusKey` op het item. De leesvorm is altijd "de hele ladder tegelijk",
-     * want een lijst rendert alle labels, kleuren en volgordes. En het beheerscherm bewerkt de
-     * ladder als één herordening — deze store kent geen transactie, dus als losse rijen zou
-     * "sleep status 3 boven status 1" N updates worden die half kunnen landen en twee
-     * statussen op dezelfde `order` achterlaten. Als array is het één `$set`.
+     * Three reasons. Nothing ever queries a single status row: every item question is answered by
+     * the flat `statusKey` on the item. The read shape is always "the whole ladder at once", because
+     * a list renders all labels, colours and orders. And the admin screen edits the ladder as one
+     * reordering — this store has no transaction, so as separate rows "drag status 3 above status 1"
+     * would become N updates that can land halfway and leave two statuses on the same `order`. As an
+     * array it is one `$set`.
      *
-     * Wat het kost: uniciteit van `key` wordt niet door de store bewaakt maar door
-     * `validateStatuses` in de app.
+     * The cost: uniqueness of `key` is not guarded by the store but by `validateStatuses` in the app.
      */
     statuses: WorkStatus[];
-    /** Afloopredenen, vrij per project. Leeg = afronden vraagt geen reden. */
+    /** Resolutions, free per project. Empty = closing asks for no reason. */
     resolutions?: WorkResolution[];
-    /** Welke itemtypes dit project aanbiedt. Leeg = alle. */
+    /** Which item types this project offers. Empty = all of them. */
     typeKeys?: string[];
-    /** Sleutels van de `CustomFieldDef`s die op dit project aan staan, in weergavevolgorde. */
+    /** Keys of the `CustomFieldDef`s enabled on this project, in display order. */
     fieldKeys?: string[];
-    /** Waar een nieuw item begint. Afwezig = de eerste status in `order`. */
+    /** Where a new item starts. Absent = the first status in `order`. */
     defaultStatusKey?: string;
     /**
-     * Duurzaam ankerpunt voor de sleutelteller.
+     * Durable anchor for the key counter.
      *
-     * De teller zelf leeft in `Bridge.kv`, maar kv is een cache: hij kan koud starten of
-     * geëvicteerd worden. Dit veld en de `(organizationId, projectId, sequenceNumber)`-index
-     * zijn samen de weg terug, zodat een lege kv geen sleutels hergebruikt.
+     * The counter itself lives in `Bridge.kv`, but kv is a cache: it can start cold or be evicted.
+     * This field and the `(organizationId, projectId, sequenceNumber)` index are together the way
+     * back, so an empty kv does not reuse keys.
      */
     lastSequence?: number;
     archived?: boolean;
@@ -121,93 +118,92 @@ export interface WorkProject {
     updatedAt?: number;
 }
 export type WorkPriority = "low" | "normal" | "high" | "urgent";
-/** Waar een item vandaan komt — een mens of iets automatisch. */
+/** Where an item came from — a person or something automatic. */
 export interface WorkItemSource {
     initiator: "user" | "system";
-    /** Vrije reden bij `system` ("missed_call", "stale_interaction"). */
+    /** Free-form reason with `system` ("missed_call", "stale_interaction"). */
     systemReason?: string;
 }
 /**
- * Een werkitem.
+ * A work item.
  *
- * Let op wat hier **niet** staat: geen `interactionId`, geen `contactId`, geen `companyId`.
- * Verbanden lopen via {@link WorkLink} plus de platgeslagen {@link WorkItem.keys}, zodat "de
- * items op dit gesprek" één geïndexeerde `$in` blijft die combineerbaar is met een
- * statusfilter — wat een omweg langs de koppeltabel niet is.
+ * Note what is **not** here: no `interactionId`, no `contactId`, no `companyId`. Relations run
+ * through {@link WorkLink} plus the flattened {@link WorkItem.keys}, so "the items on this
+ * conversation" stays one indexed `$in` that combines with a status filter — which a detour past
+ * the link table does not.
  *
- * En geen `value`/`currency`: bedragen zijn aangepaste velden in de generieke
- * attribuutstore. Dat maakt sorteren erop een geheugenoperatie; zie het plan.
+ * And no `value`/`currency`: amounts are custom fields in the generic attribute store. That makes
+ * sorting on them an in-memory operation; see the plan.
  */
 export interface WorkItem {
     id: string;
     organizationId: string;
     /**
-     * Afwezig = een **los item**: geen sleutel, geen projectvelden, en de vaste ladder uit
-     * {@link LOOSE_STATUSES}. Dat is wat een losse taak is ("terugbellen", een opvolging op
-     * een gesprek), en het bestaat vanaf dag één zodat werk dat later uit een andere app
-     * hierheen komt geen modelwijziging vraagt.
+     * Absent = a **loose item**: no key, no project fields, and the fixed ladder from
+     * {@link LOOSE_STATUSES}. That is what a loose task is ("call back", a follow-up on a
+     * conversation), and it exists from day one so work arriving later from another app needs no
+     * model change.
      */
     projectId?: string;
-    /** `SAL-142` / `SAL-142-1`. Afwezig bij een los item. Org-uniek waar aanwezig. */
+    /** `SAL-142` / `SAL-142-1`. Absent on a loose item. Org-unique where present. */
     key?: string;
     sequenceNumber?: number;
-    /** Volgnummer binnen de ouder — het `-1` in `SAL-142-1`. */
+    /** Sequence number within the parent — the `-1` in `SAL-142-1`. */
     subSequence?: number;
-    /** Lichte classificatie: icoon en welke velden zinvol zijn. Nooit een workflow. */
+    /** Light classification: icon and which fields make sense. Never a workflow. */
     typeKey: string;
     ownerScope: OwnerScope;
     title: string;
     description?: string;
     /**
-     * Een {@link WorkStatus.key} — die van het project, of uit de vaste ladder. Omdat de
-     * sleutels org-uniek zijn is de categorie er altijd eenduidig bij te zoeken; daarom
-     * staat die hier níet als tweede kolom.
+     * A {@link WorkStatus.key} — the project's, or from the fixed ladder. Because the keys are
+     * org-unique the category can always be looked up unambiguously, which is why it is *not* a
+     * second column here.
      */
     statusKey: string;
-    /** {@link WorkResolution.key}. Alleen zinvol als de status in categorie `done` valt. */
+    /** {@link WorkResolution.key}. Only meaningful when the status falls in category `done`. */
     resolution?: string;
     parentId?: string;
     /**
-     * De scopeKeys van álle voorouders, platgeslagen op schrijfmoment
-     * (`["work_item:program-1", "work_item:project-7"]`, van boven naar beneden).
+     * The scopeKeys of *all* ancestors, flattened at write time
+     * (`["work_item:program-1", "work_item:project-7"]`, top to bottom).
      *
-     * Dít maakt onbeperkte diepte betaalbaar: "alles onder dit project" is één geïndexeerde
-     * `$in` in plaats van een recursieve traversal, en die kan deze store niet. De prijs zit
-     * aan de schrijfkant — een item verslepen betekent de `ancestorKeys` van zijn hele
-     * subtree herschrijven, en dat is een job, geen request.
+     * This is what makes unlimited depth affordable: "everything under this project" is one indexed
+     * `$in` instead of a recursive traversal, which this store cannot do. The price is on the write
+     * side — dragging an item means rewriting the `ancestorKeys` of its whole subtree, and that is a
+     * job, not a request.
      */
     ancestorKeys?: string[];
-    /** UserIds die dit doen. Leeg = de pool van het team. */
+    /** UserIds doing this. Empty = the team's pool. */
     assignees?: string[];
-    /** Wie het inbracht, los van wie het doet. */
+    /** Who brought it in, apart from who does it. */
     reporterId?: string;
     watchers?: string[];
     priority?: WorkPriority;
     labels?: string[];
     /**
-     * De partijen, plat en zonder rol: `["company:123", "contact:456"]`.
+     * The parties, flat and without a role: `["company:123", "contact:456"]`.
      *
-     * Afgeleid uit de {@link WorkLink}s op schrijfmoment. Twee vormen naast elkaar omdat ze
-     * twee vragen beantwoorden: de link weet *in welke hoedanigheid* (cliënt, wederpartij),
-     * deze kolom beantwoordt "alle items waar dit bedrijf in zit" in één indexhit — wat over
-     * een koppeltabel een tweede ronde zou kosten.
+     * Derived from the {@link WorkLink}s at write time. Two shapes side by side because they answer
+     * two questions: the link knows *in which capacity* (client, opposing party), this column
+     * answers "every item this company is in" in one index hit — which over a link table would cost
+     * a second round.
      */
     partyKeys: string[];
     /**
-     * Dossiersleutels — de `keys`-conventie uit `platform/scope.ts`. Eigen sleutel,
-     * projectsleutel, voorouders en partijen. Hiermee vinden uren, geheugen en attributen
-     * dit item terug.
+     * File keys — the `keys` convention from `platform/scope.ts`. Own key, project key, ancestors
+     * and parties. This is how hours, memory and attributes find this item back.
      */
     keys: string[];
-    /** Verwijzingen naar externe systemen (`shopify_order:8842`). Nooit een kopie. */
+    /** References to external systems (`shopify_order:8842`). Never a copy. */
     externalIds?: string[];
     /** Epoch ms. */
     startDate?: number;
     dueDate?: number;
-    /** Gezet zodra de status naar categorie `done` gaat, gewist als hij terugkomt. */
+    /** Set as soon as the status moves to category `done`, cleared when it comes back. */
     closedAt?: number;
     estimateSeconds?: number;
-    /** Standaard voor uren die hierop geboekt worden; de urenregel mag afwijken. */
+    /** Default for hours booked on this; the time entry may differ. */
     billable?: boolean;
     source: WorkItemSource;
     createdBy: string;
@@ -215,40 +211,38 @@ export interface WorkItem {
     updatedAt?: number;
 }
 /**
- * Een getypeerde koppeling tussen een werkitem en wat dan ook.
+ * A typed link between a work item and anything at all.
  *
- * **Eén hop, nooit getraverseerd.** Dat is de afspraak die deze tabel naast de
- * `keys`-conventie laat bestaan in plaats van ermee te concurreren: context en lidmaatschap
- * lopen via `keys` (platgeslagen bij schrijven, één indexhit), en dit is de expliciete,
- * laag-volume, één-niveau-diepe relatie tussen twee dingen. Een link-tabel die alsnog de
- * contextvraag beantwoordt is het begin van de grafiek die hier bewust niet gebouwd is —
- * deze store kan niet recursief traverseren.
+ * **One hop, never traversed.** That is the agreement letting this table exist next to the `keys`
+ * convention instead of competing with it: context and membership run through `keys` (flattened at
+ * write time, one index hit), and this is the explicit, low-volume, one-level-deep relation
+ * between two things. A link table that starts answering the context question too is the
+ * beginning of the graph deliberately not built here — this store cannot traverse recursively.
  */
 export interface WorkLink {
     id: string;
     organizationId: string;
-    /** Altijd `work_item:<id>` op de heenrij. */
+    /** Always `work_item:<id>` on the outbound row. */
     fromKey: string;
-    /** Elke scopeKey: een ander item, een gesprek, een contact, een artefact. */
+    /** Any scopeKey: another item, a conversation, a contact, an artifact. */
     toKey: string;
     /**
-     * De relatie én de partijrol in één vocabulaire: `client` · `opposing` · `context` ·
+     * The relation and the party role in one vocabulary: `client` · `opposing` · `context` ·
      * `blocks` · `blocked_by` · `relates` · `duplicates` · `attachment`.
      *
-     * Eén veld en geen aparte rol-kolom, want het zijn dezelfde soort uitspraak: "dit bedrijf
-     * is de cliënt" en "dit item blokkeert dat item" zijn allebei een benoemde pijl.
+     * One field and no separate role column, because they are the same kind of statement: "this
+     * company is the client" and "this item blocks that item" are both a named arrow.
      */
     type: string;
     /**
-     * Gedeeld door de heen- en terugrij.
+     * Shared by the outbound and the inbound row.
      *
-     * Elke koppeling wordt als **twee** rijen geschreven, zodat een lookup één geïndexeerde
-     * query op `fromKey` is in plaats van een `$or` over twee kolommen — en zodat "welk werk
-     * hangt aan `interaction:123`" dezelfde query is als "wat hangt aan dit item". Dit veld
-     * houdt ontkoppelen daarmee één handeling.
+     * Every link is written as **two** rows, so a lookup is one indexed query on `fromKey` instead
+     * of an `$or` across two columns — and so "which work hangs off `interaction:123`" is the same
+     * query as "what hangs off this item". This field keeps unlinking a single action.
      */
     pairId: string;
-    /** Waar de terugrij zich mee bekendmaakt, zodat de UI "wordt geblokkeerd door" kan tonen. */
+    /** How the inbound row identifies itself, so the UI can show "is blocked by". */
     inverse?: boolean;
     createdBy: string;
     createdAt?: number;