@live-change/frontend-template 0.9.198 → 0.9.200

package/.cursor/rules/live-change-backend-actions-views-triggers.mdc

@@ -0,0 +1,290 @@
+---
+description: Rules for implementing actions, views, and triggers in LiveChange services
+globs: **/services/**/*.js
+alwaysApply: false
+---
+
+# LiveChange backend – akcje, widoki, triggery
+
+## Akcje – ogólne zasady
+
+- Akcje umieszczaj w plikach domenowych, razem z modelami, których dotyczą.
+- Każda akcja powinna:
+  - jasno określać wejście (`properties`),
+  - wykonywać minimalną potrzebną walidację,
+  - używać indeksów zamiast pełnych skanów,
+  - zwracać sensowny wynik (ID obiektu, fragment stanu itp.).
+
+### Wzorzec prostej akcji
+
+```js
+definition.action({
+  name: 'registerDeviceConnection',
+  properties: {
+    pairingKey: {
+      type: String
+    },
+    connectionType: {
+      type: String
+    },
+    capabilities: {
+      type: Array
+    }
+  },
+  async execute({ pairingKey, connectionType, capabilities }, { client, service }) {
+    const device = await Device.indexObjectGet('byPairingKey', { pairingKey })
+    if(!device) throw new Error('notFound')
+
+    const id = app.generateUid()
+    const sessionKey = app.generateUid() + app.generateUid()
+
+    await DeviceConnection.create({
+      id,
+      device: device.id,
+      connectionType,
+      capabilities,
+      sessionKey,
+      status: 'offline'
+    })
+
+    return { connectionId: id, sessionKey }
+  }
+})
+```
+
+## Widoki – ogólne zasady
+
+- Widok ma być prostym, czytelnym wejściem do danych:
+  - korzystaj z indeksów (`indexObjectGet`, `indexRangeGet`),
+  - nie implementuj skomplikowanej logiki w widokach, jeśli można ją przenieść do akcji.
+
+## Widoki – reguła: `get` + `observable` zawsze razem
+
+Widok musi być dokładnie jednym z trzech wariantów:
+
+- `daoPath` (preferowane) — framework wygeneruje zarówno `get`, jak i `observable`
+- `get` + `observable` — oba wymagane, jeśli źródło danych jest zewnętrzne lub custom-reactive
+- `fetch` — jednorazowy request/response (często `remote: true`), bez reaktywnego strumienia
+
+Nigdy nie definiuj samego `get` bez `observable` ani samego `observable` bez `get`. To psuje użycie reaktywne i może kończyć się błędami w processorach, które owijają oba callbacki (np. access control).
+
+### Poprawnie: `daoPath` zamiast ręcznego `get`/`observable`
+
+```js
+definition.view({
+  name: 'costInvoice',
+  properties: {
+    costInvoice: {
+      type: String
+    }
+  },
+  returns: { type: Object },
+  async daoPath({ costInvoice }) {
+    return CostInvoice.path(costInvoice)
+  }
+})
+```
+
+### Poprawnie: `get` + `observable` razem (zewnętrzne źródło)
+
+```js
+definition.view({
+  name: 'session',
+  properties: {},
+  returns: { type: Number },
+  async get(params, { client }) {
+    return onlineClient.get(['online', 'session', { ...params, session: client.session }])
+  },
+  async observable(params, { client }) {
+    return onlineClient.observable(
+      ['online', 'session', { ...params, session: client.session }],
+      ReactiveDao.ObservableValue
+    )
+  }
+})
+```
+
+### Źle: samo `get` bez `observable`
+
+```js
+definition.view({
+  name: 'brokenView',
+  properties: {
+    id: { type: String }
+  },
+  returns: { type: Object },
+  async get({ id }) {
+    return await SomeModel.get(id)
+  }
+})
+```
+
+### Wzorzec widoku zakresowego
+
+```js
+definition.view({
+  name: 'pendingCommands',
+  properties: {
+    connectionId: {
+      type: String
+    }
+  },
+  async get({ connectionId }, { client, service }) {
+    return BotCommand.indexRangeGet('byConnectionAndStatus', {
+      connection: connectionId,
+      status: 'pending'
+    })
+  }
+})
+```
+
+## Triggery – online/offline i batchowanie
+
+- Triggery są do reakcji na zdarzenia (np. zmiana stanu sesji, start serwera).
+- Dwie podstawowe kategorie:
+  - triggery dla pojedynczych obiektów (np. połączenie online/offline),
+  - triggery „hurtowe” (np. ustawienie wszystkich na offline przy starcie).
+
+### Wzorzec triggerów online/offline
+
+```js
+definition.trigger({
+  name: 'sessionDeviceConnectionOnline',
+  properties: {
+    connection: {
+      type: String
+    }
+  },
+  async execute({ connection }, { service }) {
+    await DeviceConnection.update(connection, {
+      status: 'online',
+      lastSeenAt: new Date()
+    })
+  }
+})
+
+definition.trigger({
+  name: 'sessionDeviceConnectionOffline',
+  properties: {
+    connection: {
+      type: String
+    }
+  },
+  async execute({ connection }, { service }) {
+    await DeviceConnection.update(connection, {
+      status: 'offline'
+    })
+  }
+})
+```
+
+### Wzorzec batchowania odczytów (unikaj pełnych skanów)
+
+- Przy triggerach, które mają przejść po wielu rekordach, **zawsze** używaj paginacji:
+  - stały `limit` (np. 32 lub 128),
+  - zakres po kluczu (`gt: lastId`),
+  - pętla aż do pustego batcha.
+
+```js
+definition.trigger({
+  name: 'allOffline',
+  async execute({}, { service }) {
+    let last = ''
+    while(true) {
+      const connections = await DeviceConnection.rangeGet({
+        gt: last,
+        limit: 32
+      })
+      if(connections.length === 0) break
+
+      for(const conn of connections) {
+        await DeviceConnection.update(conn.id, {
+          status: 'offline'
+        })
+      }
+
+      last = connections[connections.length - 1].id
+    }
+  }
+})
+```
+
+## Change triggers – reakcja na zmiany modeli
+
+Modele z relacjami (`propertyOf`, `itemOf`, `userItem`, itp.) automatycznie odpalają change triggery przy każdym create/update/delete. Konwencja nazw: `{changeType}{ServiceName}_{ModelName}`:
+
+- `changeSvc_Model` — odpala się przy każdej zmianie (rekomendowane, obsługuje wszystkie przypadki)
+- `createSvc_Model` / `updateSvc_Model` / `deleteSvc_Model` — konkretne zdarzenia cyklu życia
+
+Parametry: `{ objectType, object, identifiers, data, oldData, changeType }`.
+
+```js
+// Reaguj na dowolną zmianę modelu Schedule z serwisu cron
+definition.trigger({
+  name: 'changeCron_Schedule',
+  properties: {
+    object: { type: Schedule, validation: ['nonEmpty'] },
+    data: { type: Object },
+    oldData: { type: Object }
+  },
+  async execute({ object, data, oldData }, { triggerService }) {
+    if(oldData) { /* wyczyść stary stan */ }
+    if(data) { /* ustaw nowy stan */ }
+  }
+})
+```
+
+Sprawdzaj `data`/`oldData`: oba obecne = update, tylko `data` = create, tylko `oldData` = delete.
+
+## Wzorzec „pending + resolve” (asynchroniczny wynik)
+
+- Używaj, gdy akcja w serwisie musi poczekać na wynik z zewnętrznego procesu (np. urządzenie, worker).
+- Struktura:
+  1. Akcja tworzy rekord „pending”.
+  2. Akcja czeka na `Promise` powiązany z ID.
+  3. Inna akcja/trigger aktualizuje rekord i rozwiązuje `Promise`.
+
+Szkic:
+
+```js
+// pendingCommands.js – singleton w pamięci
+const pendingCommands = new Map()
+
+export function waitForCommand(commandId, timeoutMs = 115000) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      pendingCommands.delete(commandId)
+      reject(new Error('timeout'))
+    }, timeoutMs)
+    pendingCommands.set(commandId, { resolve, reject, timer })
+  })
+}
+
+export function resolveCommand(commandId, result) {
+  const pending = pendingCommands.get(commandId)
+  if(pending) {
+    clearTimeout(pending.timer)
+    pendingCommands.delete(commandId)
+    pending.resolve(result)
+  }
+}
+```
+
+W akcji wywołującej:
+
+```js
+await SomeCommand.create({ id, status: 'pending', ... })
+const result = await waitForCommand(id)
+return result
+```
+
+W akcji raportującej:
+
+```js
+await SomeCommand.update(id, {
+  status: 'completed',
+  result
+})
+resolveCommand(id, result)
+```
+

package/.cursor/rules/live-change-backend-architecture.mdc

@@ -0,0 +1,131 @@
+---
+description: Rules for LiveChange backend service architecture and directory structure
+globs: **/services/**/*.js
+alwaysApply: false
+---
+
+# LiveChange backend – architektura serwisów
+
+## Główna zasada
+
+- Każdy serwis LiveChange **musi być katalogiem**, nie pojedynczym plikiem.
+- Serwis ma czytelną, powtarzalną strukturę plików.
+
+## Struktura katalogu serwisu
+
+```
+server/services/<serviceName>/
+  definition.js  # createServiceDefinition + use – żadnych modeli/akcji
+  index.js       # import definition, import plików domenowych, export definition
+  config.js      # opcjonalnie – rozwiązywanie definition.config do plain object
+  <domain>.js    # pliki domenowe: modele, widoki, akcje, triggery
+```
+
+### `definition.js`
+
+- Importuj `app` z `@live-change/framework`.
+- Twórz definicję serwisu **bez** modeli/akcji/widoków w tym pliku.
+- Jeśli serwis używa relacji lub kontroli dostępu, **od razu** podłącz pluginy w `use`.
+
+Przykład:
+
+```js
+import { app } from '@live-change/framework'
+import relationsPlugin from '@live-change/relations-plugin'
+import accessControlService from '@live-change/access-control-service'
+
+const definition = app.createServiceDefinition({
+  name: 'myService',
+  use: [relationsPlugin, accessControlService]
+})
+
+export default definition
+```
+
+### `index.js`
+
+- Importuj `definition`.
+- Importuj wszystkie pliki domenowe tylko po to, żeby wykonały się side-effecty (rejestracja modeli/akcji/widoków/triggerów).
+- Eksportuj `definition` jako default.
+
+```js
+import definition from './definition.js'
+
+import './modelA.js'
+import './modelB.js'
+import './authenticator.js'
+
+export default definition
+```
+
+### `config.js` (opcjonalnie)
+
+- Czyta `definition.config` (ustawiane w `app.config.js`).
+- Nadaje wartości domyślne i eksportuje zwykły obiekt.
+
+```js
+import definition from './definition.js'
+
+const {
+  someOption = 'default'
+} = definition.config
+
+export default { someOption }
+```
+
+## Rejestracja serwisu w projekcie
+
+### `services.list.js`
+
+- Importuj serwis z jego `index.js` w katalogu, nie z płaskiego pliku.
+
+```js
+import myService from './services/myService/index.js'
+
+export default {
+  // ...
+  myService
+}
+```
+
+### `app.config.js`
+
+- Upewnij się, że nazwa serwisu w configu odpowiada nazwie z `createServiceDefinition`.
+- Zachowaj **sensowną kolejność** serwisów:
+  - na początku serwisy bazowe, wspólne i pluginy,
+  - na końcu serwisy właściwe dla aplikacji, które z nich korzystają.
+
+```js
+services: [
+  // serwisy bazowe / wspólne
+  { name: 'user' },
+  { name: 'session' },
+  { name: 'accessControl' },
+  // ...
+  // serwisy własne aplikacji
+  { name: 'myService' }
+]
+```
+
+## Podgląd serwisów komendą `describe`
+
+Komenda CLI `describe` pokazuje co framework wygenerował z twoich definicji (modele, widoki, akcje, triggery, indeksy, eventy):
+
+```bash
+# Przegląd wszystkich serwisów
+node server/start.js describe
+
+# Jeden serwis w YAML (z wygenerowanym kodem)
+node server/start.js describe --service myService --output yaml
+
+# Konkretna encja
+node server/start.js describe --service myService --model MyModel --output yaml
+```
+
+Szczególnie przydatne po użyciu relacji (`userItem`, `itemOf`, `propertyOf`) — `describe` pokaże wszystkie automatycznie wygenerowane widoki, akcje, triggery i indeksy.
+
+## Kiedy tworzyć nowy serwis
+
+- Gdy masz wyraźnie wydzieloną domenę (np. urządzenia, płatności, powiadomienia).
+- Gdy zestaw modeli/akcji/widoków ma własną konfigurację i zależności.
+- Gdy logika nie mieści się sensownie w istniejącym serwisie bez mieszania odpowiedzialności.

package/.cursor/rules/live-change-backend-event-sourcing.mdc

@@ -0,0 +1,185 @@
+---
+description: Event-sourcing data flow rules — emit events for DB writes, use triggerService for cross-service writes
+globs: **/services/**/*.js
+alwaysApply: false
+---
+
+# LiveChange backend – event-sourcing i przepływ danych
+
+## Jak płyną dane w LiveChange
+
+LiveChange stosuje wzorzec event-sourcing:
+
+1. **Akcje i triggery** walidują dane i publikują eventy przez `emit()`.
+2. **Eventy** (`definition.event()`) wykonują faktyczne zapisy do bazy (`Model.create`, `Model.update`, `Model.delete`).
+3. Dla modeli z **relacjami** (`userItem`, `itemOf`, `propertyOf`, itp.) relations plugin auto-generuje eventy i triggery CRUD — używaj ich przez `triggerService()`.
+4. Dla **zapisów między serwisami** zawsze używaj `triggerService()` — `foreignModel` jest tylko do odczytu.
+
+```
+Akcja/Trigger  ──emit()──▶  Event handler  ──▶  Model.create/update/delete
+       │
+       └──triggerService()──▶  Trigger innego serwisu  ──emit()──▶  ...
+```
+
+## Reguła 1: Nie używaj Model.create/update/delete bezpośrednio w akcjach i triggerach
+
+Akcje i triggery **nie powinny** wywoływać `Model.create()`, `Model.update()` ani `Model.delete()` bezpośrednio. Zamiast tego:
+
+- **Jeśli model ma relacje** (auto-generowane CRUD) → użyj `triggerService()` do wywołania triggera relacji (np. `serviceName_createModelName`, `serviceName_updateModelName`, `serviceName_setModelName`).
+- **Jeśli nie ma triggera relacji** → użyj `emit()` do opublikowania eventu, a potem zdefiniuj `definition.event()`, który wykona zapis.
+
+### Poprawnie: emit z akcji
+
+```js
+definition.action({
+  name: 'createImage',
+  properties: { /* ... */ },
+  waitForEvents: true,
+  async execute({ image, name, width, height }, { client, service }, emit) {
+    const id = image || app.generateUid()
+    // walidacja, logika biznesowa...
+    emit({
+      type: 'ImageCreated',
+      image: id,
+      data: { name, width, height }
+    })
+    return id
+  }
+})
+
+definition.event({
+  name: 'ImageCreated',
+  async execute({ image, data }) {
+    await Image.create({ ...data, id: image })
+  }
+})
+```
+
+### Poprawnie: triggerService dla triggerów relacji
+
+```js
+definition.action({
+  name: 'giveCard',
+  properties: { /* ... */ },
+  async execute({ receiverType, receiver }, { client, triggerService }, emit) {
+    // Użyj auto-generowanego triggera z relations plugin
+    await triggerService({
+      service: definition.name,
+      type: 'businessCard_setReceivedCard',
+    }, {
+      sessionOrUserType: receiverType,
+      sessionOrUser: receiver,
+      // ...
+    })
+  }
+})
+```
+
+### Źle: bezpośredni zapis w akcji
+
+```js
+// ❌ NIE RÓB TEGO
+definition.action({
+  name: 'createSomething',
+  async execute({ name }, { client }, emit) {
+    const id = app.generateUid()
+    await Something.create({ id, name })  // ❌ bezpośredni zapis w akcji
+    return id
+  }
+})
+```
+
+## Reguła 2: Eventy mogą modyfikować tylko modele tego samego serwisu
+
+Handlery eventów (`definition.event()`) mogą zapisywać tylko do modeli zdefiniowanych w **tym samym serwisie**. Nie próbuj zapisywać do `foreignModel` — jest tylko do odczytu (`.get()`, `.indexObjectGet()`, `.indexRangeGet()`, ale nie `.create()`, `.update()`, `.delete()`).
+
+Do zapisów między serwisami używaj `triggerService()` z akcji lub triggera:
+
+```js
+// ✅ Poprawnie: zapis między serwisami przez triggerService
+definition.trigger({
+  name: 'chargeCollected_billing_TopUp',
+  async execute(props, { triggerService }, emit) {
+    // Zapis do innego serwisu przez jego zadeklarowany trigger
+    await triggerService({
+      service: 'balance',
+      type: 'balance_setOrUpdateBalance',
+    }, { ownerType: 'billing_Billing', owner: props.cause })
+
+    // Zapis do własnego serwisu przez triggerService (trigger relacji)
+    await triggerService({
+      service: definition.name,
+      type: 'billing_updateTopUp'
+    }, { topUp: props.cause, state: 'paid' })
+  }
+})
+```
+
+```js
+// ❌ NIE RÓB TEGO — foreignModel jest tylko do odczytu
+const ExternalModel = definition.foreignModel('otherService', 'SomeModel')
+
+definition.event({
+  name: 'SomethingHappened',
+  async execute({ id }) {
+    await ExternalModel.update(id, { status: 'done' })  // ❌ nie zadziała
+  }
+})
+```
+
+## `waitForEvents: true`
+
+Gdy akcja lub trigger emituje eventy i musi poczekać na ich przetworzenie przed zwróceniem wyniku, ustaw `waitForEvents: true`:
+
+```js
+definition.action({
+  name: 'createNotification',
+  waitForEvents: true,
+  async execute({ message }, { client }, emit) {
+    const id = app.generateUid()
+    emit({
+      type: 'created',
+      notification: id,
+      data: { message, sessionOrUserType: 'user_User', sessionOrUser: client.user }
+    })
+    return id  // event jest przetworzony zanim to się zwróci
+  }
+})
+```
+
+Bez `waitForEvents: true` akcja zwraca wynik natychmiast, a eventy są przetwarzane asynchronicznie.
+
+## Triggery relacji (auto-generowane)
+
+Gdy model ma relacje (`userItem`, `itemOf`, `propertyOf`, itp.), relations plugin auto-generuje triggery CRUD. Użyj `describe`, żeby je odkryć:
+
+```bash
+node server/start.js describe --service myService --output yaml
+```
+
+Typowe auto-generowane triggery:
+- `serviceName_createModelName` — tworzenie rekordu
+- `serviceName_updateModelName` — aktualizacja rekordu
+- `serviceName_deleteModelName` — usuwanie rekordu
+- `serviceName_setModelName` — upsert (utwórz lub nadpisz)
+- `serviceName_setOrUpdateModelName` — ustaw jeśli nie istnieje, zaktualizuj jeśli istnieje
+
+Wywołuj je przez `triggerService()`:
+
+```js
+await triggerService({
+  service: 'myService',
+  type: 'myService_createMyModel'
+}, {
+  // właściwości pasujące do pól modelu
+})
+```
+
+## Podsumowanie
+
+| Gdzie | Może wywoływać Model.create/update/delete? | Jak zmieniać dane |
+|---|---|---|
+| `definition.event()` | ✅ Tak (tylko modele tego samego serwisu) | Bezpośredni zapis |
+| `definition.action()` | ❌ Nie | `emit()` lub `triggerService()` |
+| `definition.trigger()` | ❌ Nie | `emit()` lub `triggerService()` |
+| Między serwisami | ❌ Nigdy przez foreignModel | `triggerService()` do docelowego serwisu |