@live-change/frontend-template 0.9.198 → 0.9.200

package/.cursor/rules/live-change-backend-models-and-relations.mdc

@@ -0,0 +1,256 @@
+---
+description: Rules for defining models, relations, indexes and access control in LiveChange
+globs: **/services/**/*.js
+alwaysApply: false
+---
+
+# LiveChange backend – modele i relacje
+
+## Ogólne zasady
+
+- Modele zapisuj w plikach domenowych (`<domain>.js`) importowanych w `index.js` serwisu.
+- Dbaj o czytelność definicji – **właściwości wieloliniowo**, z jasnymi polami `type`, `default`, `validation` itd.
+- Tam, gdzie to możliwe, używaj relacji (`userItem`, `itemOf`, `propertyOf`, `foreignModel`) zamiast ręcznego klepania CRUD i widoków.
+
+## Styl definicji `properties`
+
+- Każde pole opisane wieloliniowo, jedna rzecz na linię.
+- Unikaj upychania typu i walidacji w jednej linii, jeśli zmniejsza to czytelność.
+
+```js
+properties: {
+  name: {
+    type: String,
+    validation: ['nonEmpty']
+  },
+  status: {
+    type: String,
+    default: 'offline'
+  },
+  capabilities: {
+    type: Array,
+    of: {
+      type: String
+    }
+  }
+}
+```
+
+## `userItem` – zasób należący do użytkownika
+
+Używaj, gdy model należy do zalogowanego użytkownika.
+
+```js
+definition.model({
+  name: 'Device',
+  properties: {
+    name: {
+      type: String
+    }
+  },
+  userItem: {
+    readAccessControl: { roles: ['owner', 'admin'] },
+    writeAccessControl: { roles: ['owner', 'admin'] },
+    writeableProperties: ['name']
+  }
+})
+```
+
+Skutek:
+
+- automatyczne widoki typu „moje X”,
+- automatyczne akcje create/update/delete dla właściciela.
+
+## `itemOf` – dziecko należy do rodzica
+
+Używaj, gdy model jest listą elementów powiązanych z innym modelem.
+
+```js
+definition.model({
+  name: 'DeviceConnection',
+  properties: {
+    connectionType: {
+      type: String
+    },
+    status: {
+      type: String,
+      default: 'offline'
+    }
+  },
+  itemOf: {
+    what: Device,
+    readAccessControl: { roles: ['owner', 'admin'] },
+    writeAccessControl: { roles: ['owner', 'admin'] }
+  }
+})
+```
+
+Zasady:
+
+- rodzic `what` to model zadeklarowany wcześniej w tym lub innym serwisie,
+- relacja generuje standardowe widoki/akcje dla listy i elementów.
+
+## `propertyOf` – właściwość z ID równym rodzicowi
+
+Używaj, gdy model przechowuje „stan” jednego obiektu (ID dziecka = ID rodzica).
+
+```js
+definition.model({
+  name: 'DeviceCursorState',
+  properties: {
+    x: { type: Number },
+    y: { type: Number }
+  },
+  propertyOf: {
+    what: Device,
+    readAccessControl: { roles: ['owner', 'admin'] },
+    writeAccessControl: { roles: ['owner', 'admin'] }
+  }
+})
+```
+
+Skutek:
+
+- prosty dostęp: `DeviceCursorState.get(deviceId)`,
+- bez potrzeby dodatkowych indeksów po polu `device`.
+
+## `propertyOf` dla wielu modeli (relacja 1:1 do każdego z nich)
+
+W niektórych domenach model jest „łącznikiem 1:1” pomiędzy rekordami (np. faktura ↔ kontrahent w roli dostawcy/klienta).
+Najczęściej są to 2 modele, ale `propertyOf` może wskazywać na **dowolnie wiele** modeli (np. relacja łącząca 3+ encje), jeśli taka jest semantyka domeny.
+
+Wtedy:
+
+- **nie** przechowuj „drugiej strony” jako zwykłego `contractorId` (albo ogólnie `someId`) w `properties`
+- **nie** dodawaj ręcznie pól `...Id` w modelu relacyjnym, jeśli to ma być relacja – to utrudnia generatorowi CRUD/relacji poprawne wnioskowanie o powiązaniach
+- zamiast tego zdefiniuj relacje jako `propertyOf` do **każdego** z modeli, które mają być rodzicami relacji
+
+To jest istotne, bo generator CRUD/relacji rozumie wtedy, że encja jest powiązaniem pomiędzy dwiema encjami, a nie „zwykłym obiektem z polem id”.
+
+Przykład (schematycznie):
+
+```js
+const CostInvoice = definition.foreignModel('invoice', 'CostInvoice')
+const Contractor = definition.foreignModel('company', 'Contractor')
+
+definition.model({
+  name: 'Supplier',
+  properties: {
+    // dodatkowe pola relacji (opcjonalnie)
+  },
+  propertyOf: [
+    { what: CostInvoice },
+    { what: Contractor }
+  ]
+})
+```
+
+## `foreignModel` – relacja do modelu z innego serwisu
+
+Używaj, gdy `itemOf`/`propertyOf` ma wskazywać na model spoza aktualnego serwisu.
+
+```js
+const Device = definition.foreignModel('deviceManager', 'Device')
+
+definition.model({
+  name: 'BotSession',
+  properties: {
+    // ...
+  },
+  itemOf: {
+    what: Device,
+    readAccessControl: { roles: ['owner', 'admin'] }
+  }
+})
+```
+
+Zasady:
+
+- pierwszy argument to nazwa serwisu,
+- drugi to nazwa modelu w tamtym serwisie.
+
+## Automatycznie dodawane pola z relacji
+
+Relacje automatycznie dodają **pola identyfikatorów** i **indeksy** do modelu. **Nie definiuj ich ponownie** w `properties`.
+
+**Konwencja nazw:** nazwa pola = nazwa modelu rodzica z małą pierwszą literą (`Device` → `device`, `CostInvoice` → `costInvoice`).
+
+| Relacja | Dodane pole/pola | Dodane indeksy |
+|---|---|---|
+| `itemOf: { what: Device }` | `device` | `byDevice` |
+| `propertyOf: { what: Device }` | `device` | `byDevice` |
+| `userItem` | `user` | `byUser` |
+| `userProperty` | `user` | `byUser` |
+| `sessionOrUserProperty` | `sessionOrUserType`, `sessionOrUser` | `bySessionOrUser` (hash) |
+| `sessionOrUserProperty: { extendedWith: ['object'] }` | + `objectType`, `object` | indeksy złożone |
+| `propertyOfAny: { ownerTypes: [...] }` | `ownerType`, `owner` | `byOwner` (hash) |
+| `boundTo: { what: Device }` | `device` | `byDevice` (hash) |
+
+Dla relacji z wieloma rodzicami (np. `propertyOf: [{ what: A }, { what: B }]`) tworzone są wszystkie kombinacje indeksów (`byA`, `byB`, `byAAndB`).
+
+## `propertyOfAny` — typy rodzica (`{name}Types`)
+
+`propertyOfAny` jest relacją polimorficzną. Lista dozwolonych typów jest podawana w polach `{name}Types`, gdzie `{name}` pochodzi z `to`.
+
+- Gdy `to` nie jest podane, domyślnie jest `['owner']`, więc użyj `ownerTypes`.
+- Gdy `to: ['invoice']`, użyj `invoiceTypes`.
+
+```js
+// domyślnie to: ['owner']
+propertyOfAny: {
+  ownerTypes: ['invoice_CostInvoice', 'invoice_IncomeInvoice']
+}
+
+// jawnie
+propertyOfAny: {
+  to: ['invoice'],
+  invoiceTypes: ['invoice_CostInvoice', 'invoice_IncomeInvoice']
+}
+```
+
+```js
+// ✅ Poprawnie — definiuj tylko SWOJE pola
+definition.model({
+  name: 'Connection',
+  properties: {
+    status: { type: String }  // 'device' NIE jest tutaj — dodaje go itemOf
+  },
+  itemOf: { what: Device }   // automatycznie dodaje pole 'device' + indeks 'byDevice'
+})
+
+// ❌ Źle — redundantne pole
+definition.model({
+  name: 'Connection',
+  properties: {
+    device: { type: String },  // ❌ już dodane przez itemOf
+    status: { type: String }
+  },
+  itemOf: { what: Device }
+})
+```
+
+Użyj `node server/start.js describe --service myService --model MyModel --output yaml` żeby zobaczyć wszystkie pola łącznie z automatycznie dodanymi.
+
+## Indeksy
+
+- Definiuj indeksy jawnie w modelu, gdy będziesz często wyszukiwać po danym polu lub kombinacji pól.
+- Nazwy indeksów powinny być opisowe, bez skrótów trudnych do odczytania.
+
+```js
+indexes: {
+  bySessionKey: {
+    property: ['sessionKey']
+  },
+  byDeviceAndStatus: {
+    property: ['device', 'status']
+  }
+}
+```
+
+Poza serwisem indeks bywa widoczny pod nazwą z prefiksem serwisu, np. `myService_Model_byDeviceAndStatus`.
+
+## Access control na relacjach
+
+- Zawsze ustawiaj `readAccessControl` i `writeAccessControl` na relacjach (`userItem`, `itemOf`, `propertyOf`), zamiast polegać na domyślnym zachowaniu.
+- Traktuj to jako część modelu, nie dodatek na końcu.
+

package/.cursor/rules/live-change-frontend-vue-primevue.mdc

@@ -0,0 +1,290 @@
+---
+description: Rules for Vue 3, PrimeVue, Tailwind frontend development on LiveChange
+globs: **/front/src/**/*.{vue,js,ts}
+alwaysApply: false
+---
+
+# Frontend na live-change-stack – Vue 3 + PrimeVue + Tailwind
+
+## Stack
+
+- Vue 3 + TypeScript
+- PrimeVue 4 – główna biblioteka komponentów UI
+- Tailwind CSS – podstawowe stylowanie (unikaj zbędnego custom CSS)
+- vite-plugin-pages – file-based routing w `src/pages/`
+- @live-change/vue3-ssr – integracja z backendem LiveChange
+
+## Pobieranie danych – `live` + `Promise.all`
+
+- **Nie** używaj `ref(null)` + `onMounted` do ładowania danych.
+- Dane ładuj w `setup`/`script setup` przez `await Promise.all(...)` na `live(path()....)`.
+- Rodzic powinien owijać stronę w `<Suspense>` (w projektach live-change robi to zazwyczaj `ViewRoot` globalnie).
+
+Przykład:
+
+```js
+import { path, live, api as useApi } from '@live-change/vue3-ssr'
+
+const api = useApi()
+
+const [devices] = await Promise.all([
+  live(path().deviceManager.myUserDevices({}))
+])
+
+const [device, connections] = await Promise.all([
+  live(path().deviceManager.myUserDevice({ device: deviceId })),
+  live(path().deviceManager.deviceOwnedDeviceConnections({ device: deviceId }))
+])
+```
+
+Dostęp w template:
+
+```vue
+<template>
+  <div v-if="device.value">
+    {{ device.value.name }}
+  </div>
+</template>
+```
+
+## Komendy i formularze – wybór wzorca
+
+Są 4 sposoby wywoływania akcji backendowych. Używaj właściwego:
+
+| Wzorzec | Kiedy używać |
+|---|---|
+| `editorData` | **Edycja rekordów modelu** (create/update). Drafty, walidacja, `AutoField`. Ustawienia, edytory, profile. |
+| `actionData` | **Jednorazowe formularze akcji** (nie CRUD). Submit → done. Publikacja, zaproszenie, import. |
+| `api.command` | **Pojedynczy przycisk lub wywołanie z kodu** (bez pól formularza). Usuwanie, toggle, akcje z kodu. |
+| `<command-form>` | **Unikaj.** Legacy, tylko trywialne prototypy. Preferuj `editorData` lub `actionData`. |
+
+Schemat decyzji:
+
+1. Użytkownik wypełnia pola formularza? → **Nie**: użyj `api.command` (owijaj w `workingZone.addPromise` dla przycisków).
+2. Edytuje rekord modelu (create/update)? → **Tak**: użyj `editorData`. **Nie**: użyj `actionData`.
+3. `<command-form>` tylko do najprostszych jednorazowych przypadków.
+
+### `api.command`
+
+```js
+await api.command(['deviceManager', 'createMyUserDevice'], {
+  name: 'Moje urządzenie'
+})
+
+await api.command(['deviceManager', 'deleteMyUserDevice'], {
+  device: id
+})
+```
+
+Format komendy:
+
+- tablica `[serviceName, actionName]`,
+- payload jako zwykły obiekt.
+
+## Routing – blok `<route>` i meta `signedIn`
+
+- Każda strona w `src/pages/` może mieć blok `<route>` z metadanymi.
+- Używaj `meta.signedIn` do oznaczania stron wymagających logowania.
+
+```vue
+<route>
+  { "name": "devices", "meta": { "signedIn": true } }
+</route>
+```
+
+Dynamiczne ścieżki:
+
+- plik `[id].vue` odpowiada ścieżce `/devices/:id`.
+
+```js
+import { useRoute } from 'vue-router'
+
+const route = useRoute()
+const deviceId = route.params.id
+```
+
+## Confirm + Toast – wzorzec dla akcji destrukcyjnych
+
+```js
+import { useConfirm } from 'primevue/useconfirm'
+import { useToast } from 'primevue/usetoast'
+
+const confirm = useConfirm()
+const toast = useToast()
+
+function deleteDevice(id) {
+  confirm.require({
+    message: 'Czy na pewno chcesz usunąć to urządzenie?',
+    header: 'Potwierdzenie',
+    icon: 'pi pi-exclamation-triangle',
+    accept: async () => {
+      await api.command(['deviceManager', 'deleteMyUserDevice'], { device: id })
+      toast.add({
+        severity: 'success',
+        summary: 'Usunięto',
+        life: 2000
+      })
+    }
+  })
+}
+```
+
+## Wzorce UI – lista i szczegóły
+
+### Lista
+
+```vue
+<template>
+  <div class="container mx-auto p-4">
+    <div class="flex items-center justify-between mb-6">
+      <h1 class="text-2xl font-bold">Urządzenia</h1>
+      <Button label="Dodaj" icon="pi pi-plus" @click="openDialog" />
+    </div>
+
+    <Card v-if="devices.value?.length === 0">
+      <template #content>
+        <p class="text-center text-gray-500">
+          Brak urządzeń
+        </p>
+      </template>
+    </Card>
+
+    <div class="grid gap-4">
+      <Card v-for="device in devices.value" :key="device.id">
+        <template #content>
+          <!-- zawartość -->
+        </template>
+      </Card>
+    </div>
+  </div>
+</template>
+```
+
+### Tag statusu
+
+```vue
+<Tag
+  :value="conn.status"
+  :severity="conn.status === 'online' ? 'success' : 'secondary'"
+/>
+```
+
+## Computed paths – reaktywne parametry
+
+Gdy ścieżki zależą od reaktywnych wartości (route params, props), owijaj je w `computed()`:
+
+```js
+import { computed, unref } from 'vue'
+import { usePath, live } from '@live-change/vue3-ssr'
+
+const path = usePath()
+
+const articlePath = computed(() => path.blog.article({ article: unref(articleId) }))
+const [article] = await Promise.all([live(articlePath)])
+```
+
+Dla warunkowego ładowania (np. tylko gdy zalogowany), zwróć wartość falsy:
+
+```js
+import { useClient } from '@live-change/vue3-ssr'
+const client = useClient()
+
+const myDataPath = computed(() => client.value.user && path.blog.myArticles({}))
+const [myData] = await Promise.all([live(myDataPath)])
+```
+
+## Powiązane dane – `.with()`
+
+Dołączaj powiązane obiekty do elementów w jednym reaktywnym zapytaniu:
+
+```js
+path.blog.articles({})
+  .with(article => path.userIdentification.identification({
+    sessionOrUserType: article.authorType,
+    sessionOrUser: article.author
+  }).bind('authorProfile'))
+```
+
+Dostęp: `article.authorProfile?.firstName`. Działa zarówno z `live()` jak i `RangeViewer`.
+
+## WorkingZone dla akcji asynchronicznych
+
+`ViewRoot` opakowuje każdą stronę w `<WorkingZone>`. Używaj `inject('workingZone')` dla akcji przycisków poza formularzami:
+
+```js
+import { inject } from 'vue'
+const workingZone = inject('workingZone')
+
+function doAction() {
+  workingZone.addPromise('actionName', (async () => {
+    await actions.blog.publishArticle({ article: id })
+    toast.add({ severity: 'success', summary: 'Opublikowano', life: 2000 })
+  })())
+}
+```
+
+Aktywuje globalny spinner/blur na czas trwania promisy.
+
+## Kontrola dostępu z `useClient`
+
+```js
+import { useClient } from '@live-change/vue3-ssr'
+const client = useClient()
+```
+
+- `client.value.user` – truthy gdy zalogowany
+- `client.value.roles` – tablica ról (np. `['admin', 'owner']`)
+
+W template:
+
+```vue
+<Button v-if="client.roles.includes('admin')" label="Admin" />
+<div v-if="!client.user">Zaloguj się</div>
+```
+
+## Locale i czas
+
+- Wywołaj `useLocale().captureLocale()` w `App.vue` żeby zapisać locale przeglądarki do backendu.
+- Używaj `locale.localTime(date)` z `d()` z vue-i18n do wyświetlania dat bezpiecznego dla SSR.
+- `currentTime` z `@live-change/frontend-base` to reaktywny ref który tykuje co 500ms.
+- `useTimeSynchronization()` z `@live-change/vue3-ssr` koryguje różnicę zegarów – używaj gdy timing jest krytyczny (odliczanie, eventy real-time).
+
+## Analityka
+
+Używaj `analytics` z `@live-change/vue3-components`:
+
+```js
+import { analytics } from '@live-change/vue3-components'
+analytics.emit('article:published', { articleId: id })
+```
+
+Podpinaj providery (PostHog, GA4) w osobnym pliku importowanym z `App.vue`.
+
+## SSR i konfiguracja frontendu
+
+- Utrzymuj standardowy układ entry points:
+
+```js
+// entry-client.js
+import { clientEntry } from '@live-change/frontend-base/client-entry.js'
+export default clientEntry(App, createRouter, config)
+
+// entry-server.js
+import { serverEntry, sitemapEntry } from '@live-change/frontend-base/server-entry.js'
+export const render = serverEntry(App, createRouter, config)
+export const sitemap = sitemapEntry(App, createRouter, routerSitemap, config)
+```
+
+- Konfigurację PrimeVue trzymaj w jednym miejscu (`config.js`) i używaj `definePreset` do nadpisania motywu.
+
+## Odkrywanie widoków i akcji z `describe`
+
+Komenda CLI `describe` pozwala znaleźć dostępne widoki (do `live()`) i akcje (do `api.command` / `editorData` / `actionData`):
+
+```bash
+node server/start.js describe --service blog
+node server/start.js describe --service blog --view articlesByCreatedAt --output yaml
+node server/start.js describe --service blog --action createMyUserArticle --output yaml
+```
+
+To najszybszy sposób na odkrycie jakie ścieżki i akcje są dostępne, w tym te wygenerowane automatycznie przez relacje.

package/.cursor/rules/live-change-service-structure.mdc

@@ -0,0 +1,107 @@
+---
+description: LiveChange service file structure — every service must be a directory with separate definition.js, index.js, etc.
+globs: server/**/*.js
+alwaysApply: true
+---
+
+# LiveChange Service Structure
+
+Every LiveChange service **must** be a directory, not a single file.
+
+## Required structure
+
+```
+server/<serviceName>/
+  definition.js   # creates app.createServiceDefinition({ name }) – nothing else
+  index.js        # imports definition, imports all domain files, exports definition
+  config.js       # required – resolves definition.config, sets definition.clientConfig, exports plain config object
+  <domain>.js     # one file per domain area (models, views, actions, triggers)
+```
+
+## definition.js
+
+Only creates and exports the definition. No models, no actions here.
+
+```js
+import App from '@live-change/framework'
+const app = App.app()
+
+const definition = app.createServiceDefinition({ name: 'myService' })
+
+export default definition
+```
+
+## index.js
+
+Imports definition and all domain files (side-effect imports), then re-exports definition.
+
+```js
+import App from '@live-change/framework'
+const app = App.app()
+
+import definition from './definition.js'
+
+import './authenticator.js'
+import './myModel.js'
+import './otherModel.js'
+
+export default definition
+```
+
+## config.js (required)
+
+Reads `definition.config` (passed from `app.config.js`), resolves defaults, sets `definition.clientConfig` (for frontend),
+and exports a plain config object used by other domain files.
+
+```js
+import definition from './definition.js'
+
+const {
+  defaultAccess = {
+    writeAccessControl: ['owner', 'admin'],
+    readAllAccess: ['admin']
+  }
+} = definition.config || {}
+
+definition.clientConfig = {
+  // values exposed to frontend, if needed
+}
+
+export default { defaultAccess }
+```
+
+## Domain files (e.g. myModel.js)
+
+Each file imports `definition` (and `config` if needed) and registers models/views/actions/triggers.
+
+```js
+import App from '@live-change/framework'
+const app = App.app()
+
+import definition from './definition.js'
+import config from './config.js'
+
+export const MyModel = definition.model({ name: 'MyModel', ... })
+
+definition.view({ name: 'myList', ... })
+definition.action({ name: 'doThing', ... })
+```
+
+Rule of thumb:
+
+- Domain files should read configuration from `config` (exported from `config.js`), not directly from `definition.config`.
+
+## services.list.js import
+
+Always import from the directory index, not a flat file:
+
+```js
+import myService from './myService/index.js'   // ✓
+import myService from './myService.js'         // ✗
+```
+
+## Why
+
+A flat single-file service makes it hard to add new domain files (auth, models, triggers, etc.)
+without the file growing unmanageably. The directory structure mirrors the pattern used in
+`@live-change/live-change-stack/services/*`.