@fui-org/fui-cli 0.2.0 → 0.3.0

package/skills/fui-skill/references/watcher-patterns.md

@@ -0,0 +1,196 @@
+# Watcher Patterns (FUI Best Practice)
+
+> File này sở hữu: **`watch`: `v_old`, deep-watch, cascading, chống race**. Cú pháp action xem [controls-patterns.md](controls-patterns.md).
+
+Hướng này dùng cho các case:
+- Form phụ thuộc nhiều cấp (Tỉnh/Thành -> Quận/Huyện -> Phường/Xã)
+- Bộ lọc theo thuộc tính (status, loại, ngày, keyword, ...)
+
+Mục tiêu:
+- Đúng cấu trúc FUI (`module.json`: `data`, `watch`, `controls`, `set`)
+- Tránh vòng lặp watcher
+- Giảm gọi API thừa
+- Dễ bảo trì khi module lớn
+
+## 1. Nguyên tắc chuẩn
+
+1. Chỉ watch key đầu vào nhỏ nhất
+- Watch ID hoặc field filter (`provinceID`, `districtID`, `filter.status`), không watch cả object lớn nếu không cần.
+
+2. Tách action theo tầng
+- `handleProvinceChange` chỉ reset dữ liệu phụ thuộc và gọi `apiLoadDistricts`.
+- `handleDistrictChange` chỉ reset cấp dưới và gọi `apiLoadWards`.
+- `applyFilters` gom logic tải list cuối.
+
+3. Dùng `deep-watch` có chọn lọc
+- Chỉ dùng cho object filter nhỏ (ví dụ `filter`).
+- Không deep-watch mảng lớn như `items`, `tableData`.
+
+4. Không để watcher tự tạo loop
+- Không watch biến output của chính action đó.
+- Không watch `items` rồi trong callback lại ghi `items`.
+
+5. Gắn điều kiện trước khi gọi API
+- Dùng `IF/THEN/ELSE` để kiểm tra đầu vào hợp lệ (ví dụ chưa chọn tỉnh thì không gọi huyện).
+
+6. Tách debounce/race-control sang `script.js`
+- Watcher giữ vai trò điều phối.
+- Debounce hoặc chống response cũ ghi đè response mới đặt trong helper JS.
+
+7. Literal string chỉ ép khi truyền qua `IN`
+- Trong action có `IN`, chuỗi không có khoảng trắng có thể bị core hiểu là expression → dùng
+  `` `value`` hoặc `"'value'"`. Quy tắc đầy đủ:
+  [controls-patterns.md §0](controls-patterns.md#0-value-resolution-rules-fundamental).
+
+## 2. Pattern A: Cascading địa giới hành chính
+
+```json
+{
+  "data": [
+    {
+      "formData": {
+        "provinceID": null,
+        "districtID": null,
+        "wardID": null
+      },
+      "provinceList": [],
+      "districtList": [],
+      "wardList": []
+    },
+    {
+      "apiLoadProvinces": {
+        "API": "/api/location/provinces",
+        "OUT": "provinceList"
+      },
+      "apiLoadDistricts": {
+        "API": "/api/location/districts",
+        "IN": { "ProvinceID": "formData.provinceID" },
+        "OUT": "districtList"
+      },
+      "apiLoadWards": {
+        "API": "/api/location/wards",
+        "IN": { "DistrictID": "formData.districtID" },
+        "OUT": "wardList"
+      }
+    },
+    {
+      "handleProvinceChange": [
+        {
+          "districtList": [],
+          "wardList": [],
+          "formData.districtID": null,
+          "formData.wardID": null
+        },
+        {
+          "IF": "formData.provinceID",
+          "THEN": { "CALL": "apiLoadDistricts" }
+        }
+      ],
+      "handleDistrictChange": [
+        {
+          "wardList": [],
+          "formData.wardID": null
+        },
+        {
+          "IF": "formData.districtID",
+          "THEN": { "CALL": "apiLoadWards" }
+        }
+      ]
+    },
+    {
+      "CALL": "apiLoadProvinces"
+    }
+  ],
+  "watch": {
+    "formData.provinceID": { "CALL": "handleProvinceChange" },
+    "formData.districtID": { "CALL": "handleDistrictChange" }
+  }
+}
+```
+
+Điểm chính:
+- Watch theo key cụ thể.
+- Reset cấp dưới trước khi gọi API cấp dưới.
+- Có điều kiện tránh gọi API khi null.
+
+## 3. Pattern B: Filter object + deep-watch
+
+```json
+{
+  "data": [
+    {
+      "filter": {
+        "keyword": "",
+        "status": null,
+        "fromDate": null,
+        "toDate": null
+      },
+      "items": []
+    },
+    {
+      "apiLoadItems": {
+        "API": "/api/items/search",
+        "IN": {
+          "Keyword": "filter.keyword",
+          "Status": "filter.status",
+          "FromDate": "filter.fromDate",
+          "ToDate": "filter.toDate"
+        },
+        "OUT": "items"
+      }
+    },
+    {
+      "handleFilterChanged": {
+        "CALL": "apiLoadItems"
+      }
+    }
+  ],
+  "watch": {
+    "deep-watch": {
+      "filter": { "CALL": "handleFilterChanged" }
+    }
+  }
+}
+```
+
+Khi dùng pattern này:
+- `filter` nên nhỏ và ổn định.
+- Nếu có text search nhập liên tục, nên debounce trong `script.js`.
+
+## 4. Debounce khuyến nghị (script.js)
+
+```javascript
+var filterTimer = null;
+
+function debounceFilter(input) {
+    var callActionName = input && input.callActionName;
+    var waitMs = input && input.waitMs;
+    clearTimeout(filterTimer);
+    filterTimer = setTimeout(function () {
+        CALL(vueData[callActionName]);
+    }, waitMs || 350);
+}
+```
+
+Ví dụ action trong `module.json`:
+
+```json
+{
+  "handleFilterChanged": {
+    "FUN": "debounceFilter",
+    "IN": {
+      "callActionName": "'apiLoadItems'",
+      "waitMs": 350
+    }
+  }
+}
+```
+
+## 5. Checklist QA cho watcher
+
+1. Watch key có đủ nhỏ chưa (ID/field thay vì object lớn)?
+2. Có reset đúng dữ liệu phụ thuộc trước khi gọi API?
+3. Có guard `IF` trước API khi input null/rỗng?
+4. Có nguy cơ loop watcher không?
+5. Có cần debounce cho input text không?
+6. Nếu action có `IN`, đã áp dụng literal string rule cho giá trị text không khoảng trắng chưa?

package/skills/fui-skill/references/websocket-realtime.md

@@ -0,0 +1,254 @@
+# FUI Real-time Messaging — WebSocket (SignalR)
+
+> File này sở hữu: **real-time/SignalR: `webSocketJoinGroup`, `webSocket_Send`**.
+
+FUI cung cấp cơ chế real-time messaging dựa trên **SignalR** (không phải WebSocket API thuần của trình duyệt), host tại domain riêng `ws.fui.vn`. Toàn bộ logic client đã có sẵn trong `defaultfunction.js` (global, không cần viết lại) — chỉ cần khai báo đúng cấu trúc trong `module.json` và gọi 3 hàm sẵn có: `webSocketConnection`, `webSocketJoinGroup`, `webSocket_Send`.
+
+---
+
+## 1. Import bắt buộc
+
+Trước khi dùng, phải thêm 2 file JS qua `file_import_new` — **đúng thứ tự** (dòng dưới phụ thuộc dòng trên):
+
+| Thứ tự | File | Ghi chú |
+|---|---|---|
+| 1 (sort nhỏ hơn) | `https://ws.fui.vn/Scripts/jquery.signalR-2.4.1.min.js` | SignalR client core |
+| 2 (sort lớn hơn) | `https://ws.fui.vn/signalr/hubs` | Hub proxy tự sinh từ server — vẫn là nội dung JS dù URL không có đuôi `.js` |
+
+```
+file_import_new({
+  fileType: ".js", contentType: "link",
+  fileName: "https://ws.fui.vn/Scripts/jquery.signalR-2.4.1.min.js",
+  fileSort: 100
+})
+file_import_new({
+  fileType: ".js", contentType: "link",
+  fileName: "https://ws.fui.vn/signalr/hubs",
+  fileSort: 110
+})
+```
+
+> jQuery đã có sẵn trong FUI runtime — không cần import thêm. Kiểm tra `file_import_list` trước để tránh add trùng (giống quy trình `f-echart` trong [components-echart.md](components-echart.md)).
+
+---
+
+## 2. Cơ chế tự động kết nối khi module load
+
+FUI's bootstrap (`buildApp` trong `fastproject.js`) kiểm tra `vueData.webSocket` ngay sau khi `data[]` chạy xong:
+
+- Nếu `vueData.webSocket` tồn tại → tự tạo `vueData.webSocketState = { code, text }` và gọi `webSocketConnection('https://ws.fui.vn/signalr', vueData.webSocket, vueData.webSocketState)` + `webSocketJoinGroup(vueData.webSocket)` — **không cần tự gọi 2 hàm này ở bootstrap**, chỉ cần khai báo đúng object `webSocket` trong `data[]`.
+- `webSocketState.text` phản ánh trạng thái kết nối: `Reconnecting` / `Connected` / `Disconnected`. Có thể bind trực tiếp lên UI để debug (`innerHTML: "{{webSocketState}}"`).
+
+---
+
+## 3. Khai báo group cần join — trong `data[]`
+
+```json
+"data": [
+  {
+    "TenNhomDong": "`ThuNha",
+    "DGroup": "`device-abc",
+    "webSocket": {
+      "nhom1": [],
+      "nhom2": null,
+      "{{DGroup}}": {}
+    }
+  }
+]
+```
+
+- Mỗi **key** của object `webSocket` là tên một group sẽ được join khi module load.
+- **Kiểu giá trị quyết định cách nhận tin nhắn:**
+  - Giá trị là **array** (`[]`) → tin nhắn mới được **push** vào cuối mảng (giữ lịch sử, dùng cho chat log, danh sách sự kiện...).
+  - Giá trị là **`null` hoặc object** (`{}`) → tin nhắn mới **ghi đè** giá trị hiện tại (chỉ giữ tin mới nhất, dùng cho trạng thái/counter/notification đơn).
+- Group name có thể là chuỗi literal (`nhom1`) hoặc **dynamic qua `{{ }}` interpolation ngay trong key** — `"{{DGroup}}"` sẽ được resolve thành giá trị hiện tại của `DGroup` (ví dụ `device-abc`), cho phép join theo group riêng của user/thiết bị.
+- `` `ThuNha `` / `` `device-abc `` dùng backtick để ép literal string — xem [Value Resolution Rules](controls-patterns.md#0-value-resolution-rules-fundamental).
+
+---
+
+## 4. Join thêm group tại runtime — `FUN: webSocketJoinGroup`
+
+Ngoài khai báo tĩnh ở mục 3, có thể join thêm group bất cứ lúc nào (kể cả ngay trong `data[]` dưới dạng action tự chạy khi load — xem [ui-patterns.md §1](ui-patterns.md)):
+
+```json
+{
+  "FUN": "webSocketJoinGroup",
+  "IN": {
+    "Nhom3": null,
+    "{{TenNhomDong}}": []
+  }
+}
+```
+
+- `IN` ở đây **chính là `groupObj`** (tham số đầu tiên của `webSocketJoinGroup(groupObj, timeout, callBackFunc)`) — không map theo tên tham số như hàm khác. Vì vậy `FUN` + `IN` **không truyền được `timeout`/`callBackFunc`** — nếu cần custom timeout hoặc callback sau khi join xong, dùng `EXE` raw JS: `"EXE": "webSocketJoinGroup({Nhom3:null}, 3000, function(){ ... })"`.
+- Dùng cách này khi group cần join phát sinh **có điều kiện** hoặc **sau khi** module đã load (ví dụ: trong một action, sau khi API trả về ID phòng/chat cần join), thay vì chỉ khai báo tĩnh trong `webSocket: {}`.
+
+---
+
+## 5. Nhận tin nhắn
+
+### watch (khuyến nghị — trigger logic khi có tin mới)
+
+```json
+"watch": {
+  "webSocket.nhom1": { "MESS": "thong bao" },
+  "webSocket.device-abc": { "MESS": "thong bao" }
+}
+```
+
+> **Lưu ý quan trọng:** key trong `watch` **không được** dùng `{{ }}` template (watch key là literal cố định, không interpolate) — phải ghi trực tiếp giá trị đã resolve của group (ví dụ `webSocket.device-abc`, không phải `webSocket.{{DGroup}}`).
+
+### Bind trực tiếp lên UI (hiển thị raw, không cần watch)
+
+```json
+{
+  "el": "v-textarea",
+  "attr": { "v-model": "webSocket.nhom2", "label": "Nội dung nhận nhom2", "rows": 5 }
+}
+```
+
+### Debug toàn bộ state
+
+```json
+{ "el": "div", "attr": {}, "innerHTML": "{{webSocket}}" }
+```
+
+---
+
+## 6. Gửi tin nhắn — `webSocket_Send`
+
+`webSocket_Send(obj)` nhận **một object** `{ group, data }` — `data` có thể là object, array, hoặc string, hàm tự chọn API SignalR phù hợp (`messageSendObject` / `messageSendArray` / `messageSend`).
+
+### Cách 1 — `FUN` + `IN` (payload object)
+
+```json
+{
+  "FUN": "webSocket_Send",
+  "IN": {
+    "group": "`nhom1",
+    "data": { "text": "doi tuong 1", "text2": "doi tuong 2" }
+  }
+}
+```
+
+### Cách 2 — `EXE` raw JS (khi cần đọc giá trị động từ vueData)
+
+```json
+{ "EXE": "webSocket_Send({ group:'nhom2', data:vueData.messText })" }
+```
+
+### Cách 3 — payload dạng array
+
+```json
+{
+  "FUN": "webSocket_Send",
+  "IN": { "group": "`nhom3", "data": ["mang 1", "mang 2"] }
+}
+```
+
+### Gọi trực tiếp trong `script.js` (ngoài action engine)
+
+```js
+webSocket_Send({ group: 'Nhom3', data: 'Gui noi dung từ JS' })
+```
+
+### Cách 4 — Gửi qua HTTP API (không cần client tự giữ kết nối SignalR)
+
+FUI cũng expose endpoint REST để gửi tin nhắn tới group mà không cần gọi `webSocket_Send` từ client:
+
+```json
+{
+  "API": "https://ws.fui.vn/api/messageSend/nhom1",
+  "IN": { "text": "test 1", "text2": "test 2" }
+}
+```
+
+Group name cũng interpolate được trực tiếp trong URL:
+
+```json
+{ "API": "https://ws.fui.vn/api/messageSend/{{DGroup}}" }
+```
+
+Dùng cách này khi muốn gửi tin nhắn từ một action/nơi không tiện dùng `FUN`/`EXE` (ví dụ gọi từ server, hoặc muốn tách hẳn việc gửi ra khỏi client hiện có kết nối SignalR hay không).
+
+---
+
+## 7. Ví dụ đầy đủ (tham khảo)
+
+```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 khi thêm real-time messaging vào module
+
+- [ ] `file_import_list` kiểm tra đã có `jquery.signalR-2.4.1.min.js` + `signalr/hubs` chưa
+- [ ] Thiếu → `file_import_new` cả 2, đúng thứ tự sort (signalR trước, hubs sau)
+- [ ] Khai báo `data[].webSocket = { groupName: [] | null | {} }` — chọn kiểu giá trị theo nhu cầu (lịch sử vs. giá trị mới nhất)
+- [ ] Group cần join runtime/điều kiện → `FUN: webSocketJoinGroup` (không dùng được `timeout`/`callBackFunc` qua `IN`, cần thì dùng `EXE`)
+- [ ] Nhận tin: `watch` (key literal, không `{{ }}`) hoặc bind trực tiếp `v-model="webSocket.<group>"`
+- [ ] Gửi tin: `FUN: webSocket_Send` (object/array payload) hoặc `EXE` khi cần đọc `vueData` động, hoặc `API: https://ws.fui.vn/api/messageSend/<group>` nếu muốn gửi qua HTTP thay vì client SignalR
+- [ ] Không quên `vueData.webSocketState` nếu cần hiển thị trạng thái kết nối cho user