@fui-org/fui-cli 2.1.4 → 2.2.0

package/skills/{fui-skill → fui}/references/websocket-realtime.md

@@ -1,271 +1,271 @@
-# FUI Real-time Messaging — WebSocket (SignalR)
-
-> Owns: **real-time/SignalR: `webSocketJoinGroup`, `webSocket_Send`**.
-
-Real-time uses **SignalR** (not the browser WebSocket API), hosted at `ws.fui.vn`. Client logic is already global in `defaultfunction.js` — do not rewrite it. Declare the right structure in `module.json` and use the 3 built-ins: `webSocketConnection`, `webSocketJoinGroup`, `webSocket_Send`.
-
----
-
-## 1. Required imports
-
-Add 2 JS files with `fui import new` — **in this order** (second depends on first):
-
-| Order           | File                                                    | Note                                                               |
-| --------------- | ------------------------------------------------------- | ------------------------------------------------------------------ |
-| 1 (lower sort)  | `https://ws.fui.vn/Scripts/jquery.signalR-2.4.1.min.js` | SignalR client core                                                |
-| 2 (higher sort) | `https://ws.fui.vn/signalr/hubs`                        | Server-generated hub proxy — JS content despite no `.js` extension |
-
-```bash
-fui import new --type .js --content-type link --name "https://ws.fui.vn/Scripts/jquery.signalR-2.4.1.min.js" --sort 100
-fui import new --type .js --content-type link --name "https://ws.fui.vn/signalr/hubs" --sort 110
-```
-
-See `fui import new --help`.
-
-> jQuery is already in the FUI runtime — do not import it. Run `fui import list` first to avoid duplicates (same flow as `f-echart` in [components-echart.md](components-echart.md)).
-
----
-
-## 2. Auto-connect on module load
-
-FUI bootstrap (`buildApp` in `fastproject.js`) checks `vueData.webSocket` right after `data[]` runs:
-
-- If `vueData.webSocket` exists → creates `vueData.webSocketState = { code, text }` and calls `webSocketConnection('https://ws.fui.vn/signalr', vueData.webSocket, vueData.webSocketState)` + `webSocketJoinGroup(vueData.webSocket)`. **Do not call these yourself at bootstrap** — just declare `webSocket` in `data[]`.
-- `webSocketState.text`: `Reconnecting` / `Connected` / `Disconnected`. Bind to UI for debugging (`innerHTML: "{{webSocketState}}"`).
-
----
-
-## 3. Declare groups to join — in `data[]`
-
-```json
-"data": [
-  {
-    "TenNhomDong": "`ThuNha",
-    "DGroup": "`device-abc",
-    "webSocket": {
-      "nhom1": [],
-      "nhom2": null,
-      "{{DGroup}}": {}
-    }
-  }
-]
-```
-
-- Each **key** of `webSocket` = a group joined on load.
-- **Value type sets receive behavior:**
-  - **array** (`[]`) → new messages **pushed** to the end (history: chat log, event list...).
-  - **`null` or object** (`{}`) → new message **overwrites** (latest only: status/counter/single notification).
-- Group name: literal (`nhom1`) or **dynamic via `{{ }}` in the key** — `"{{DGroup}}"` resolves to `DGroup`'s current value (e.g. `device-abc`), for per-user/device groups.
-- `` `ThuNha `` / `` `device-abc `` use backtick to force a literal string — see [Value Resolution Rules](controls-patterns.md#0-value-resolution-rules-fundamental).
-
----
-
-## 4. Join more groups at runtime — `FUN: webSocketJoinGroup`
-
-Join any time, including as an auto-run action in `data[]` (see [ui-patterns.md §1](ui-patterns.md)):
-
-```json
-{
-  "FUN": "webSocketJoinGroup",
-  "IN": {
-    "Nhom3": null,
-    "{{TenNhomDong}}": []
-  }
-}
-```
-
-- `IN` **is the `groupObj`** (first param of `webSocketJoinGroup(groupObj, timeout, callBackFunc)`), not mapped by param name. So `FUN` + `IN` **cannot pass `timeout`/`callBackFunc`** — for those use raw `EXE`: `"EXE": "webSocketJoinGroup({Nhom3:null}, 3000, function(){ ... })"`.
-- Use for groups that are **conditional** or known only **after** load (e.g. after an API returns a room/chat ID), instead of static `webSocket: {}`.
-
----
-
-## 5. Receive messages
-
-### watch (recommended — run logic on new message)
-
-```json
-"watch": {
-  "webSocket.nhom1": { "MESS": "thong bao" },
-  "webSocket.device-abc": { "MESS": "thong bao" }
-}
-```
-
-> **Important:** `watch` keys **cannot** use `{{ }}` (literal, not interpolated) — write the resolved group (`webSocket.device-abc`, not `webSocket.{{DGroup}}`).
-
-### Bind directly to UI (raw, no watch)
-
-```json
-{
-  "el": "v-textarea",
-  "attr": { "v-model": "webSocket.nhom2", "label": "Nội dung nhận nhom2", "rows": 5 }
-}
-```
-
-### Debug all state
-
-```json
-{ "el": "div", "attr": {}, "innerHTML": "{{webSocket}}" }
-```
-
----
-
-## 6. Send — `webSocket_Send`
-
-`webSocket_Send(obj)` takes **one object** `{ group, data }`; `data` may be object, array or string — the function picks the SignalR API (`messageSendObject` / `messageSendArray` / `messageSend`).
-
-### Way 1 — `FUN` + `IN` (object payload)
-
-```json
-{
-  "FUN": "webSocket_Send",
-  "IN": {
-    "group": "`nhom1",
-    "data": { "text": "doi tuong 1", "text2": "doi tuong 2" }
-  }
-}
-```
-
-### Way 2 — raw `EXE` (read dynamic vueData values)
-
-```json
-{ "EXE": "webSocket_Send({ group:'nhom2', data:vueData.messText })" }
-```
-
-### Way 3 — array payload
-
-```json
-{
-  "FUN": "webSocket_Send",
-  "IN": { "group": "`nhom3", "data": ["mang 1", "mang 2"] }
-}
-```
-
-### Directly in `script.js` (outside the action engine)
-
-```js
-webSocket_Send({ group: "Nhom3", data: "Gui noi dung từ JS" });
-```
-
-### Way 4 — HTTP API (no client SignalR connection needed)
-
-REST endpoint to send to a group:
-
-```json
-{
-  "API": "https://ws.fui.vn/api/messageSend/nhom1",
-  "IN": { "text": "test 1", "text2": "test 2" }
-}
-```
-
-Group name interpolates in the URL:
-
-```json
-{ "API": "https://ws.fui.vn/api/messageSend/{{DGroup}}" }
-```
-
-Use when `FUN`/`EXE` is inconvenient (e.g. server-side sends, or decoupling sending from whether the client holds a SignalR connection).
-
----
-
-## 7. Full example
-
-```json
-{
-  "data": [
-    {
-      "TenNhomDong": "`ThuNha",
-      "DGroup": "`device-abc",
-      "webSocket": { "nhom1": [], "nhom2": null, "{{DGroup}}": {} }
-    },
-    {
-      "FUN": "webSocketJoinGroup",
-      "IN": { "Nhom3": null, "{{TenNhomDong}}": [] }
-    }
-  ],
-  "watch": {
-    "webSocket.nhom1": { "MESS": "thong bao" },
-    "webSocket.device-abc": { "MESS": "thong bao" }
-  },
-  "controls": [
-    {
-      "prop": "fluid grid-list-md",
-      "rows": [
-        {
-          "prop": "",
-          "cols": [
-            {
-              "el": "v-textarea",
-              "col": { "class": "" },
-              "attr": { "v-model": "messText", "label": "noi dung", ":required": false, "rows": 5 },
-              "w": ""
-            },
-            {
-              "el": "f-button",
-              "col": { "class": "shrink" },
-              "attr": {
-                "label": "send - nhom2",
-                ":action": [
-                  {
-                    "FUN": "webSocket_Send",
-                    "IN": { "group": "`nhom1", "data": { "text": "doi tuong 1", "text2": "doi tuong 2" } }
-                  },
-                  { "EXE": "webSocket_Send({ group:'nhom2', data:vueData.messText})" },
-                  { "FUN": "webSocket_Send", "IN": { "group": "`nhom3", "data": ["mang 1", "mang 2"] } }
-                ]
-              }
-            }
-          ]
-        },
-        {
-          "prop": "",
-          "cols": [
-            {
-              "el": "v-textarea",
-              "col": {},
-              "attr": { "v-model": "webSocket.nhom2", "label": "Nội dung nhận nhom2", ":required": false, "rows": 5 }
-            }
-          ]
-        },
-        { "prop": "", "cols": [{ "el": "div", "col": {}, "attr": {}, "innerHTML": "{{webSocket}}" }] },
-        {
-          "prop": "",
-          "cols": [
-            {
-              "el": "f-button",
-              "col": {},
-              "attr": {
-                "label": "send by API - nhom1",
-                ":action": [
-                  { "API": "https://ws.fui.vn/api/messageSend/nhom1", "IN": { "text": "test 1", "text2": "test 2" } }
-                ]
-              }
-            },
-            {
-              "el": "f-button",
-              "col": {},
-              "attr": {
-                ":label": "'send by API - ' + DGroup",
-                ":action": [{ "API": "https://ws.fui.vn/api/messageSend/{{DGroup}}" }]
-              }
-            }
-          ]
-        },
-        { "prop": "", "cols": [{ "el": "div", "col": {}, "attr": {}, "innerHTML": "{{webSocketState}}" }] }
-      ]
-    }
-  ],
-  "set": {}
-}
-```
-
----
-
-## 8. Checklist
-
-- [ ] `fui import list`: are `jquery.signalR-2.4.1.min.js` + `signalr/hubs` present?
-- [ ] Missing → `fui import new` both, sort order signalR first, hubs second
-- [ ] Declare `data[].webSocket = { groupName: [] | null | {} }` — value type by need (history vs latest)
-- [ ] Runtime/conditional groups → `FUN: webSocketJoinGroup` (no `timeout`/`callBackFunc` via `IN`; use `EXE` if needed)
-- [ ] Receive: `watch` (literal key, no `{{ }}`) or bind `v-model="webSocket.<group>"`
-- [ ] Send: `FUN: webSocket_Send` (object/array), `EXE` for dynamic `vueData`, or `API: https://ws.fui.vn/api/messageSend/<group>` for HTTP instead of client SignalR
-- [ ] Use `vueData.webSocketState` if the user needs to see connection status
+# FUI Real-time Messaging — WebSocket (SignalR)
+
+> Owns: **real-time/SignalR: `webSocketJoinGroup`, `webSocket_Send`**.
+
+Real-time uses **SignalR** (not the browser WebSocket API), hosted at `ws.fui.vn`. Client logic is already global in `defaultfunction.js` — do not rewrite it. Declare the right structure in `module.json` and use the 3 built-ins: `webSocketConnection`, `webSocketJoinGroup`, `webSocket_Send`.
+
+---
+
+## 1. Required imports
+
+Add 2 JS files with `fui import new` — **in this order** (second depends on first):
+
+| Order           | File                                                    | Note                                                               |
+| --------------- | ------------------------------------------------------- | ------------------------------------------------------------------ |
+| 1 (lower sort)  | `https://ws.fui.vn/Scripts/jquery.signalR-2.4.1.min.js` | SignalR client core                                                |
+| 2 (higher sort) | `https://ws.fui.vn/signalr/hubs`                        | Server-generated hub proxy — JS content despite no `.js` extension |
+
+```bash
+fui import new --type .js --content-type link --name "https://ws.fui.vn/Scripts/jquery.signalR-2.4.1.min.js" --sort 100
+fui import new --type .js --content-type link --name "https://ws.fui.vn/signalr/hubs" --sort 110
+```
+
+See `fui import new --help`.
+
+> jQuery is already in the FUI runtime — do not import it. Run `fui import list` first to avoid duplicates (same flow as `f-echart` in [components-echart.md](components-echart.md)).
+
+---
+
+## 2. Auto-connect on module load
+
+FUI bootstrap (`buildApp` in `fastproject.js`) checks `vueData.webSocket` right after `data[]` runs:
+
+- If `vueData.webSocket` exists → creates `vueData.webSocketState = { code, text }` and calls `webSocketConnection('https://ws.fui.vn/signalr', vueData.webSocket, vueData.webSocketState)` + `webSocketJoinGroup(vueData.webSocket)`. **Do not call these yourself at bootstrap** — just declare `webSocket` in `data[]`.
+- `webSocketState.text`: `Reconnecting` / `Connected` / `Disconnected`. Bind to UI for debugging (`innerHTML: "{{webSocketState}}"`).
+
+---
+
+## 3. Declare groups to join — in `data[]`
+
+```json
+"data": [
+  {
+    "TenNhomDong": "`ThuNha",
+    "DGroup": "`device-abc",
+    "webSocket": {
+      "nhom1": [],
+      "nhom2": null,
+      "{{DGroup}}": {}
+    }
+  }
+]
+```
+
+- Each **key** of `webSocket` = a group joined on load.
+- **Value type sets receive behavior:**
+  - **array** (`[]`) → new messages **pushed** to the end (history: chat log, event list...).
+  - **`null` or object** (`{}`) → new message **overwrites** (latest only: status/counter/single notification).
+- Group name: literal (`nhom1`) or **dynamic via `{{ }}` in the key** — `"{{DGroup}}"` resolves to `DGroup`'s current value (e.g. `device-abc`), for per-user/device groups.
+- `` `ThuNha `` / `` `device-abc `` use backtick to force a literal string — see [Value Resolution Rules](controls-patterns.md#0-value-resolution-rules-fundamental).
+
+---
+
+## 4. Join more groups at runtime — `FUN: webSocketJoinGroup`
+
+Join any time, including as an auto-run action in `data[]` (see [ui-patterns.md §1](ui-patterns.md)):
+
+```json
+{
+  "FUN": "webSocketJoinGroup",
+  "IN": {
+    "Nhom3": null,
+    "{{TenNhomDong}}": []
+  }
+}
+```
+
+- `IN` **is the `groupObj`** (first param of `webSocketJoinGroup(groupObj, timeout, callBackFunc)`), not mapped by param name. So `FUN` + `IN` **cannot pass `timeout`/`callBackFunc`** — for those use raw `EXE`: `"EXE": "webSocketJoinGroup({Nhom3:null}, 3000, function(){ ... })"`.
+- Use for groups that are **conditional** or known only **after** load (e.g. after an API returns a room/chat ID), instead of static `webSocket: {}`.
+
+---
+
+## 5. Receive messages
+
+### watch (recommended — run logic on new message)
+
+```json
+"watch": {
+  "webSocket.nhom1": { "MESS": "thong bao" },
+  "webSocket.device-abc": { "MESS": "thong bao" }
+}
+```
+
+> **Important:** `watch` keys **cannot** use `{{ }}` (literal, not interpolated) — write the resolved group (`webSocket.device-abc`, not `webSocket.{{DGroup}}`).
+
+### Bind directly to UI (raw, no watch)
+
+```json
+{
+  "el": "v-textarea",
+  "attr": { "v-model": "webSocket.nhom2", "label": "Nội dung nhận nhom2", "rows": 5 }
+}
+```
+
+### Debug all state
+
+```json
+{ "el": "div", "attr": {}, "innerHTML": "{{webSocket}}" }
+```
+
+---
+
+## 6. Send — `webSocket_Send`
+
+`webSocket_Send(obj)` takes **one object** `{ group, data }`; `data` may be object, array or string — the function picks the SignalR API (`messageSendObject` / `messageSendArray` / `messageSend`).
+
+### Way 1 — `FUN` + `IN` (object payload)
+
+```json
+{
+  "FUN": "webSocket_Send",
+  "IN": {
+    "group": "`nhom1",
+    "data": { "text": "doi tuong 1", "text2": "doi tuong 2" }
+  }
+}
+```
+
+### Way 2 — raw `EXE` (read dynamic vueData values)
+
+```json
+{ "EXE": "webSocket_Send({ group:'nhom2', data:vueData.messText })" }
+```
+
+### Way 3 — array payload
+
+```json
+{
+  "FUN": "webSocket_Send",
+  "IN": { "group": "`nhom3", "data": ["mang 1", "mang 2"] }
+}
+```
+
+### Directly in `script.js` (outside the action engine)
+
+```js
+webSocket_Send({ group: "Nhom3", data: "Gui noi dung từ JS" });
+```
+
+### Way 4 — HTTP API (no client SignalR connection needed)
+
+REST endpoint to send to a group:
+
+```json
+{
+  "API": "https://ws.fui.vn/api/messageSend/nhom1",
+  "IN": { "text": "test 1", "text2": "test 2" }
+}
+```
+
+Group name interpolates in the URL:
+
+```json
+{ "API": "https://ws.fui.vn/api/messageSend/{{DGroup}}" }
+```
+
+Use when `FUN`/`EXE` is inconvenient (e.g. server-side sends, or decoupling sending from whether the client holds a SignalR connection).
+
+---
+
+## 7. Full example
+
+```json
+{
+  "data": [
+    {
+      "TenNhomDong": "`ThuNha",
+      "DGroup": "`device-abc",
+      "webSocket": { "nhom1": [], "nhom2": null, "{{DGroup}}": {} }
+    },
+    {
+      "FUN": "webSocketJoinGroup",
+      "IN": { "Nhom3": null, "{{TenNhomDong}}": [] }
+    }
+  ],
+  "watch": {
+    "webSocket.nhom1": { "MESS": "thong bao" },
+    "webSocket.device-abc": { "MESS": "thong bao" }
+  },
+  "controls": [
+    {
+      "prop": "fluid grid-list-md",
+      "rows": [
+        {
+          "prop": "",
+          "cols": [
+            {
+              "el": "v-textarea",
+              "col": { "class": "" },
+              "attr": { "v-model": "messText", "label": "noi dung", ":required": false, "rows": 5 },
+              "w": ""
+            },
+            {
+              "el": "f-button",
+              "col": { "class": "shrink" },
+              "attr": {
+                "label": "send - nhom2",
+                ":action": [
+                  {
+                    "FUN": "webSocket_Send",
+                    "IN": { "group": "`nhom1", "data": { "text": "doi tuong 1", "text2": "doi tuong 2" } }
+                  },
+                  { "EXE": "webSocket_Send({ group:'nhom2', data:vueData.messText})" },
+                  { "FUN": "webSocket_Send", "IN": { "group": "`nhom3", "data": ["mang 1", "mang 2"] } }
+                ]
+              }
+            }
+          ]
+        },
+        {
+          "prop": "",
+          "cols": [
+            {
+              "el": "v-textarea",
+              "col": {},
+              "attr": { "v-model": "webSocket.nhom2", "label": "Nội dung nhận nhom2", ":required": false, "rows": 5 }
+            }
+          ]
+        },
+        { "prop": "", "cols": [{ "el": "div", "col": {}, "attr": {}, "innerHTML": "{{webSocket}}" }] },
+        {
+          "prop": "",
+          "cols": [
+            {
+              "el": "f-button",
+              "col": {},
+              "attr": {
+                "label": "send by API - nhom1",
+                ":action": [
+                  { "API": "https://ws.fui.vn/api/messageSend/nhom1", "IN": { "text": "test 1", "text2": "test 2" } }
+                ]
+              }
+            },
+            {
+              "el": "f-button",
+              "col": {},
+              "attr": {
+                ":label": "'send by API - ' + DGroup",
+                ":action": [{ "API": "https://ws.fui.vn/api/messageSend/{{DGroup}}" }]
+              }
+            }
+          ]
+        },
+        { "prop": "", "cols": [{ "el": "div", "col": {}, "attr": {}, "innerHTML": "{{webSocketState}}" }] }
+      ]
+    }
+  ],
+  "set": {}
+}
+```
+
+---
+
+## 8. Checklist
+
+- [ ] `fui import list`: are `jquery.signalR-2.4.1.min.js` + `signalr/hubs` present?
+- [ ] Missing → `fui import new` both, sort order signalR first, hubs second
+- [ ] Declare `data[].webSocket = { groupName: [] | null | {} }` — value type by need (history vs latest)
+- [ ] Runtime/conditional groups → `FUN: webSocketJoinGroup` (no `timeout`/`callBackFunc` via `IN`; use `EXE` if needed)
+- [ ] Receive: `watch` (literal key, no `{{ }}`) or bind `v-model="webSocket.<group>"`
+- [ ] Send: `FUN: webSocket_Send` (object/array), `EXE` for dynamic `vueData`, or `API: https://ws.fui.vn/api/messageSend/<group>` for HTTP instead of client SignalR
+- [ ] Use `vueData.webSocketState` if the user needs to see connection status