@fui-org/fui-cli 2.1.3 → 2.2.0

package/skills/{fui-skill → fui}/references/sql-clr-functions.md

@@ -1,225 +1,225 @@
-# SQL CLR Functions — DLL-backed SQL Server functions
-
-> Owns: **SQL CLR functions: httpCall, sendMail, ImageResize, FileReader, RegexMatch...**
-
-A project DB may have **SQL CLR scalar functions** (precompiled .NET DLL, registered via `CREATE ASSEMBLY` + `CREATE FUNCTION ... EXTERNAL NAME`). If they appear in `fui schema` or in an existing SP definition, **call them directly in T-SQL** like built-ins — no install, no need to know the C#.
-
-A needed function is not in the DB → **do not invent it**; tell the user the DB lacks it.
-
----
-
-## 1. `SQLImageHelper` — images
-
-### `dbo.ImageResize`
-
-```sql
-dbo.ImageResize(@extension nvarchar(10), @OriginalImage varbinary(max), @maxWidth int, @maxHeight int, @preserverAspectRatio bit, @quality int)
-RETURNS varbinary(max)
-```
-
-Resizes to at most `@maxWidth` x `@maxHeight`.
-
-| Param                     | Meaning                                                                        |
-| ------------------------- | ------------------------------------------------------------------------------ |
-| `@extension`              | Output format, e.g. `'jpg'`, `'png'`                                           |
-| `@OriginalImage`          | Source image `varbinary`                                                       |
-| `@maxWidth`, `@maxHeight` | Max size (px)                                                                  |
-| `@preserverAspectRatio`   | `1` = keep ratio, fit longest side; `0` = force exactly `maxWidth`x`maxHeight` |
-| `@quality`                | Compression quality (usually 1-100)                                            |
-
-Returns resized `varbinary` — write to a `varbinary` column/file or return via tAPI File.
-
-### `dbo.ImageCrop`
-
-```sql
-dbo.ImageCrop(@OriginalImage varbinary(max), @StartAtX int, @StartAtY int, @Width int, @Height int)
-RETURNS varbinary(max)
-```
-
-Crops a `@Width` x `@Height` rectangle starting at `(@StartAtX, @StartAtY)`.
-
----
-
-## 2. `SQLHttpHelper` — HTTP, public value store, mail
-
-### `dbo.publicValueUUID` / `publicValueGet` / `publicValueSet`
-
-Server-level shared key-value store (not a SQL table) — keeps temp state across SP calls without a table.
-
-```sql
-dbo.publicValueUUID() RETURNS nvarchar(max)          -- sinh 1 UUID mới, dùng làm key
-dbo.publicValueGet(@name nvarchar(max)) RETURNS nvarchar(max)   -- đọc value theo key
-dbo.publicValueSet(@name nvarchar(max), @Data nvarchar(max)) RETURNS int   -- ghi value theo key
-```
-
-### `dbo.httpCall` / `dbo.httpAPI` — HTTP from T-SQL
-
-```sql
-dbo.httpCall(@Method nvarchar(max), @URL nvarchar(max), @Header nvarchar(max), @Data nvarchar(max))
-RETURNS nvarchar(max)
-```
-
-`httpAPI` has the **identical** signature (different internals): use `httpAPI` for internal tAPI calls, `httpCall` for general outbound HTTP.
-
-| Param     | Meaning                                                                                                                          |
-| --------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `@Method` | `'GET'`, `'POST'`, `'PUT'`, `'DELETE'`... (case-insensitive; empty → `GET`)                                                      |
-| `@URL`    | Full, valid absolute URL                                                                                                         |
-| `@Header` | Header list, syntax below — `''` for none                                                                                        |
-| `@Data`   | JSON string body — **sent only when Method is not GET/HEAD**; always `Content-Type: application/json` unless `@Header` overrides |
-
-**Example:**
-
-```sql
-SELECT dbo.httpCall('POST', 'https://tapi.example.vn/me/auth/ApplicationList', '', '')
-```
-
-#### `@Header` syntax — pipe-delimited `Key: Value`
-
-Most important part. One string; pairs separated by `|`; each pair `Key: Value`, split on the **first** `:` (the rest, including further `:`, is the value):
-
-```
-"Authorization: Bearer eyJhbGciOi...|X-Custom-Header: abc123"
-```
-
-Header names are **case-insensitive**; special handling:
-
-| Header name                       | Behavior                                                                                                                                  |
-| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `Authorization`, `X-*`, any other | Added to request headers as-is (`TryAddWithoutValidation`) — tokens, API keys                                                             |
-| `referer` / `referrer`            | Parsed to URI → `request.Headers.Referrer`                                                                                                |
-| `user-agent`                      | Overrides default `User-Agent`                                                                                                            |
-| `accept`                          | Overrides `Accept`                                                                                                                        |
-| `accept-language`                 | Overrides `Accept-Language`                                                                                                               |
-| `accept-encoding`                 | Overrides `Accept-Encoding`                                                                                                               |
-| `content-type`                    | With body (Method not GET/HEAD) → `Content.Headers.Content-Type` (overrides default `application/json`); no body → normal request headers |
-| Any other `content-*`             | With body → routed to `Content.Headers` instead of request headers                                                                        |
-
-**Bearer token + custom header:**
-
-```sql
-SELECT dbo.httpCall(
-  'POST',
-  'https://api.example.com/data',
-  'Authorization: Bearer abc123xyz|Content-Type: application/json; charset=utf-8',
-  '{"key":"value"}'
-)
-```
-
-**Joining headers:** exactly one `|` between pairs, no extra/missing `|`. A pair without `:` is **silently skipped** (no error).
-
-#### `httpCall`/`httpAPI` response
-
-- Status **200**: raw response body verbatim (JSON, text, anything).
-- Status **not 200** (400, 401, 404, 500...): wrapped JSON:
-  ```json
-  { "httpErrorCode": 404, "responseData": "<nội dung body, hoặc escaped string nếu không phải JSON>" }
-  ```
-  → in SPs, always check for an `httpErrorCode` field to tell error from success.
-- Invalid URL: `{"httpErrorCode":0,"responseData":"Invalid URL"}`.
-- Timeout/other exception: plain-text error message (not JSON) — check the format before `OPENJSON`.
-
-### `dbo.sendMail`
-
-```sql
-dbo.sendMail(@email_to nvarchar(max), @subject nvarchar(max), @content nvarchar(max), @from nvarchar(max), @fromDisplayName nvarchar(max), @smtp_server nvarchar(max), @smtp_port int, @userName nvarchar(max), @Password nvarchar(max), @EnableSSL bit)
-RETURNS nvarchar(max)
-```
-
-Sends email over SMTP from T-SQL.
-
-| Param                        | Meaning                                                    |
-| ---------------------------- | ---------------------------------------------------------- |
-| `@email_to`                  | Recipient                                                  |
-| `@subject`                   | Subject                                                    |
-| `@content`                   | Body (HTML or text)                                        |
-| `@from`                      | Sender address (must match/be allowed by the SMTP account) |
-| `@fromDisplayName`           | Sender display name                                        |
-| `@smtp_server`, `@smtp_port` | e.g. `'smtp.gmail.com'`, `587`                             |
-| `@userName`, `@Password`     | SMTP auth account                                          |
-| `@EnableSSL`                 | `1` = SSL/TLS (required for Gmail SMTP)                    |
-
-```sql
-SELECT dbo.sendMail('user@example.vn','Tiêu đề','Nội dung','noreply@example.vn','My System','smtp.gmail.com',587,'noreply@example.vn','app-password',1)
-```
-
-> **Security:** avoid hardcoding the SMTP `@Password` in the SP — store it via `publicValueSet`/`publicValueGet` or a permission-restricted config table so it is not exposed in the SP definition.
-
----
-
-## 3. `SQLFileSystem` — server files
-
-```sql
-dbo.FileCreateFolder(@Path nvarchar(max)) RETURNS nvarchar(max)
-dbo.FileReader(@Path nvarchar(max)) RETURNS varbinary(max)
-dbo.FileWriter(@Content varbinary(max), @Path nvarchar(max)) RETURNS nvarchar(max)
-dbo.FileExists(@Path nvarchar(max)) RETURNS bit
-dbo.FileDelete(@Path nvarchar(max)) RETURNS nvarchar(max)
-dbo.FileMove(@SourceFileName nvarchar(max), @DestFileName nvarchar(max)) RETURNS nvarchar(max)
-```
-
-Operates on the **SQL Server machine's** filesystem (not the client); `@Path` is an absolute server path. Use when an SP saves output (e.g. `ImageResize` result, exported PDF) to a fixed folder served by tAPI File API or IIS.
-
-| Function           | Meaning                                                       |
-| ------------------ | ------------------------------------------------------------- |
-| `FileCreateFolder` | Creates folder (nested too), returns result message           |
-| `FileReader`       | Reads whole file as `varbinary`                               |
-| `FileWriter`       | Writes `@Content` (varbinary) to `@Path`, create or overwrite |
-| `FileExists`       | Returns `bit`                                                 |
-| `FileDelete`       | Deletes file                                                  |
-| `FileMove`         | Moves/renames `@SourceFileName` → `@DestFileName`             |
-
-> Real server disk: add a permission check in the SP before letting client input drive `FileDelete`/`FileWriter` — same DDL/DML guard principle as `fui exec`.
-
----
-
-## 4. `SQLExpansionFunction` — regex & string compare
-
-```sql
-dbo.RegexReplace(@Input nvarchar(max), @Pattern nvarchar(1000), @Replacement nvarchar(4000)) RETURNS nvarchar(max)
-dbo.RegexIsMatch(@Input nvarchar(max), @Pattern nvarchar(1000)) RETURNS bit
-dbo.RegexMatch(@Input nvarchar(max), @Pattern nvarchar(1000)) RETURNS nvarchar(max)
-dbo.RegexMatchArray(@Input nvarchar(max), @Pattern nvarchar(1000)) RETURNS nvarchar(max)
-dbo.CompareWord(@String1 nvarchar(max), @String2 nvarchar(max)) RETURNS int
-```
-
-| Function          | Meaning                                                                                                                                      |
-| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| `RegexReplace`    | .NET regex replace — when T-SQL `REPLACE` (literal only) is not enough                                                                       |
-| `RegexIsMatch`    | `bit` match test — validate format (email, phone, codes...) in the SP                                                                        |
-| `RegexMatch`      | **First match** only (`Match.Value`, whole match, no groups); empty if none                                                                  |
-| `RegexMatchArray` | **All matches with each capture group**, as a **flat JSON object** (not array) — see below                                                   |
-| `CompareWord`     | Similarity of 2 strings as `int` (likely differing-char count or a score — check the scale with `SELECT dbo.CompareWord('a','b')` if needed) |
-
-`@Pattern` is standard .NET regex (`\d`, `\w`, `^$`, groups `()`...), not T-SQL `LIKE`. All 4 regex functions **always** use `IgnoreCase | Multiline | Singleline`: case-insensitive, `^`/`$` per line, `.` matches newlines — cannot be turned off.
-
-#### `RegexMatchArray` shape — JSON object, not array
-
-Flat object (`{...}`, not `[...]`), keys `"M{m}G{g}"`:
-
-- `m` = match index in `@Input`, from 1.
-- `g` = group index **within that match**, from 1: `G1` is always the **whole match** (`Match.Groups[0]`, same as `RegexMatch`); `G2`, `G3`... are the capture groups `(...)` in `@Pattern`, if any.
-- No match → `"{}"`.
-- Values have tab/newline/CR (`\t`, `\n`, `\r`) removed and `"` escaped.
-
-`RegexMatchArray('SDT: 0901 - 0902', '(\d{4})')` (one group) returns:
-
-```json
-{ "M1G1": "0901", "M1G2": "0901", "M2G1": "0902", "M2G2": "0902" }
-```
-
-(G1 = G2 here because the whole match equals the only group; with no groups each match yields only `G1`.)
-
-Parsing in T-SQL (it is an object):
-
-- `OPENJSON(@result)` still works but returns `key/value/type` rows (one row per key like `"M1G1"`), not one structured row per match.
-- One known match/group: `JSON_VALUE(@result, '$."M1G1"')`.
-- Iterate all: `OPENJSON(@result)` without path, parse the `M{m}G{g}` prefix from `key` to group by match.
-
----
-
-## 5. When to use them in SPs
-
-- Always confirm the function exists first (`fui schema` filtered to functions, or `SELECT * FROM sys.objects WHERE type='FS'`) — usable only if the assembly was `CREATE ASSEMBLY`'d on that DB. Not every DB has them.
-- Use in `spAPI_*` when needed: external API (`httpCall`), uploaded image processing (`ImageResize`/`ImageCrop`), notification email (`sendMail`), regex validation (`RegexIsMatch`), saving files to server disk (`FileWriter`).
-- JSON `nvarchar(max)` results (`httpCall`, `RegexMatchArray`) → parse with `OPENJSON`/`JSON_VALUE` in T-SQL before returning via tAPI.
+# SQL CLR Functions — DLL-backed SQL Server functions
+
+> Owns: **SQL CLR functions: httpCall, sendMail, ImageResize, FileReader, RegexMatch...**
+
+A project DB may have **SQL CLR scalar functions** (precompiled .NET DLL, registered via `CREATE ASSEMBLY` + `CREATE FUNCTION ... EXTERNAL NAME`). If they appear in `fui schema` or in an existing SP definition, **call them directly in T-SQL** like built-ins — no install, no need to know the C#.
+
+A needed function is not in the DB → **do not invent it**; tell the user the DB lacks it.
+
+---
+
+## 1. `SQLImageHelper` — images
+
+### `dbo.ImageResize`
+
+```sql
+dbo.ImageResize(@extension nvarchar(10), @OriginalImage varbinary(max), @maxWidth int, @maxHeight int, @preserverAspectRatio bit, @quality int)
+RETURNS varbinary(max)
+```
+
+Resizes to at most `@maxWidth` x `@maxHeight`.
+
+| Param                     | Meaning                                                                        |
+| ------------------------- | ------------------------------------------------------------------------------ |
+| `@extension`              | Output format, e.g. `'jpg'`, `'png'`                                           |
+| `@OriginalImage`          | Source image `varbinary`                                                       |
+| `@maxWidth`, `@maxHeight` | Max size (px)                                                                  |
+| `@preserverAspectRatio`   | `1` = keep ratio, fit longest side; `0` = force exactly `maxWidth`x`maxHeight` |
+| `@quality`                | Compression quality (usually 1-100)                                            |
+
+Returns resized `varbinary` — write to a `varbinary` column/file or return via tAPI File.
+
+### `dbo.ImageCrop`
+
+```sql
+dbo.ImageCrop(@OriginalImage varbinary(max), @StartAtX int, @StartAtY int, @Width int, @Height int)
+RETURNS varbinary(max)
+```
+
+Crops a `@Width` x `@Height` rectangle starting at `(@StartAtX, @StartAtY)`.
+
+---
+
+## 2. `SQLHttpHelper` — HTTP, public value store, mail
+
+### `dbo.publicValueUUID` / `publicValueGet` / `publicValueSet`
+
+Server-level shared key-value store (not a SQL table) — keeps temp state across SP calls without a table.
+
+```sql
+dbo.publicValueUUID() RETURNS nvarchar(max)          -- sinh 1 UUID mới, dùng làm key
+dbo.publicValueGet(@name nvarchar(max)) RETURNS nvarchar(max)   -- đọc value theo key
+dbo.publicValueSet(@name nvarchar(max), @Data nvarchar(max)) RETURNS int   -- ghi value theo key
+```
+
+### `dbo.httpCall` / `dbo.httpAPI` — HTTP from T-SQL
+
+```sql
+dbo.httpCall(@Method nvarchar(max), @URL nvarchar(max), @Header nvarchar(max), @Data nvarchar(max))
+RETURNS nvarchar(max)
+```
+
+`httpAPI` has the **identical** signature (different internals): use `httpAPI` for internal tAPI calls, `httpCall` for general outbound HTTP.
+
+| Param     | Meaning                                                                                                                          |
+| --------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `@Method` | `'GET'`, `'POST'`, `'PUT'`, `'DELETE'`... (case-insensitive; empty → `GET`)                                                      |
+| `@URL`    | Full, valid absolute URL                                                                                                         |
+| `@Header` | Header list, syntax below — `''` for none                                                                                        |
+| `@Data`   | JSON string body — **sent only when Method is not GET/HEAD**; always `Content-Type: application/json` unless `@Header` overrides |
+
+**Example:**
+
+```sql
+SELECT dbo.httpCall('POST', 'https://tapi.example.vn/me/auth/ApplicationList', '', '')
+```
+
+#### `@Header` syntax — pipe-delimited `Key: Value`
+
+Most important part. One string; pairs separated by `|`; each pair `Key: Value`, split on the **first** `:` (the rest, including further `:`, is the value):
+
+```
+"Authorization: Bearer eyJhbGciOi...|X-Custom-Header: abc123"
+```
+
+Header names are **case-insensitive**; special handling:
+
+| Header name                       | Behavior                                                                                                                                  |
+| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `Authorization`, `X-*`, any other | Added to request headers as-is (`TryAddWithoutValidation`) — tokens, API keys                                                             |
+| `referer` / `referrer`            | Parsed to URI → `request.Headers.Referrer`                                                                                                |
+| `user-agent`                      | Overrides default `User-Agent`                                                                                                            |
+| `accept`                          | Overrides `Accept`                                                                                                                        |
+| `accept-language`                 | Overrides `Accept-Language`                                                                                                               |
+| `accept-encoding`                 | Overrides `Accept-Encoding`                                                                                                               |
+| `content-type`                    | With body (Method not GET/HEAD) → `Content.Headers.Content-Type` (overrides default `application/json`); no body → normal request headers |
+| Any other `content-*`             | With body → routed to `Content.Headers` instead of request headers                                                                        |
+
+**Bearer token + custom header:**
+
+```sql
+SELECT dbo.httpCall(
+  'POST',
+  'https://api.example.com/data',
+  'Authorization: Bearer abc123xyz|Content-Type: application/json; charset=utf-8',
+  '{"key":"value"}'
+)
+```
+
+**Joining headers:** exactly one `|` between pairs, no extra/missing `|`. A pair without `:` is **silently skipped** (no error).
+
+#### `httpCall`/`httpAPI` response
+
+- Status **200**: raw response body verbatim (JSON, text, anything).
+- Status **not 200** (400, 401, 404, 500...): wrapped JSON:
+  ```json
+  { "httpErrorCode": 404, "responseData": "<nội dung body, hoặc escaped string nếu không phải JSON>" }
+  ```
+  → in SPs, always check for an `httpErrorCode` field to tell error from success.
+- Invalid URL: `{"httpErrorCode":0,"responseData":"Invalid URL"}`.
+- Timeout/other exception: plain-text error message (not JSON) — check the format before `OPENJSON`.
+
+### `dbo.sendMail`
+
+```sql
+dbo.sendMail(@email_to nvarchar(max), @subject nvarchar(max), @content nvarchar(max), @from nvarchar(max), @fromDisplayName nvarchar(max), @smtp_server nvarchar(max), @smtp_port int, @userName nvarchar(max), @Password nvarchar(max), @EnableSSL bit)
+RETURNS nvarchar(max)
+```
+
+Sends email over SMTP from T-SQL.
+
+| Param                        | Meaning                                                    |
+| ---------------------------- | ---------------------------------------------------------- |
+| `@email_to`                  | Recipient                                                  |
+| `@subject`                   | Subject                                                    |
+| `@content`                   | Body (HTML or text)                                        |
+| `@from`                      | Sender address (must match/be allowed by the SMTP account) |
+| `@fromDisplayName`           | Sender display name                                        |
+| `@smtp_server`, `@smtp_port` | e.g. `'smtp.gmail.com'`, `587`                             |
+| `@userName`, `@Password`     | SMTP auth account                                          |
+| `@EnableSSL`                 | `1` = SSL/TLS (required for Gmail SMTP)                    |
+
+```sql
+SELECT dbo.sendMail('user@example.vn','Tiêu đề','Nội dung','noreply@example.vn','My System','smtp.gmail.com',587,'noreply@example.vn','app-password',1)
+```
+
+> **Security:** avoid hardcoding the SMTP `@Password` in the SP — store it via `publicValueSet`/`publicValueGet` or a permission-restricted config table so it is not exposed in the SP definition.
+
+---
+
+## 3. `SQLFileSystem` — server files
+
+```sql
+dbo.FileCreateFolder(@Path nvarchar(max)) RETURNS nvarchar(max)
+dbo.FileReader(@Path nvarchar(max)) RETURNS varbinary(max)
+dbo.FileWriter(@Content varbinary(max), @Path nvarchar(max)) RETURNS nvarchar(max)
+dbo.FileExists(@Path nvarchar(max)) RETURNS bit
+dbo.FileDelete(@Path nvarchar(max)) RETURNS nvarchar(max)
+dbo.FileMove(@SourceFileName nvarchar(max), @DestFileName nvarchar(max)) RETURNS nvarchar(max)
+```
+
+Operates on the **SQL Server machine's** filesystem (not the client); `@Path` is an absolute server path. Use when an SP saves output (e.g. `ImageResize` result, exported PDF) to a fixed folder served by tAPI File API or IIS.
+
+| Function           | Meaning                                                       |
+| ------------------ | ------------------------------------------------------------- |
+| `FileCreateFolder` | Creates folder (nested too), returns result message           |
+| `FileReader`       | Reads whole file as `varbinary`                               |
+| `FileWriter`       | Writes `@Content` (varbinary) to `@Path`, create or overwrite |
+| `FileExists`       | Returns `bit`                                                 |
+| `FileDelete`       | Deletes file                                                  |
+| `FileMove`         | Moves/renames `@SourceFileName` → `@DestFileName`             |
+
+> Real server disk: add a permission check in the SP before letting client input drive `FileDelete`/`FileWriter` — same DDL/DML guard principle as `fui exec`.
+
+---
+
+## 4. `SQLExpansionFunction` — regex & string compare
+
+```sql
+dbo.RegexReplace(@Input nvarchar(max), @Pattern nvarchar(1000), @Replacement nvarchar(4000)) RETURNS nvarchar(max)
+dbo.RegexIsMatch(@Input nvarchar(max), @Pattern nvarchar(1000)) RETURNS bit
+dbo.RegexMatch(@Input nvarchar(max), @Pattern nvarchar(1000)) RETURNS nvarchar(max)
+dbo.RegexMatchArray(@Input nvarchar(max), @Pattern nvarchar(1000)) RETURNS nvarchar(max)
+dbo.CompareWord(@String1 nvarchar(max), @String2 nvarchar(max)) RETURNS int
+```
+
+| Function          | Meaning                                                                                                                                      |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `RegexReplace`    | .NET regex replace — when T-SQL `REPLACE` (literal only) is not enough                                                                       |
+| `RegexIsMatch`    | `bit` match test — validate format (email, phone, codes...) in the SP                                                                        |
+| `RegexMatch`      | **First match** only (`Match.Value`, whole match, no groups); empty if none                                                                  |
+| `RegexMatchArray` | **All matches with each capture group**, as a **flat JSON object** (not array) — see below                                                   |
+| `CompareWord`     | Similarity of 2 strings as `int` (likely differing-char count or a score — check the scale with `SELECT dbo.CompareWord('a','b')` if needed) |
+
+`@Pattern` is standard .NET regex (`\d`, `\w`, `^$`, groups `()`...), not T-SQL `LIKE`. All 4 regex functions **always** use `IgnoreCase | Multiline | Singleline`: case-insensitive, `^`/`$` per line, `.` matches newlines — cannot be turned off.
+
+#### `RegexMatchArray` shape — JSON object, not array
+
+Flat object (`{...}`, not `[...]`), keys `"M{m}G{g}"`:
+
+- `m` = match index in `@Input`, from 1.
+- `g` = group index **within that match**, from 1: `G1` is always the **whole match** (`Match.Groups[0]`, same as `RegexMatch`); `G2`, `G3`... are the capture groups `(...)` in `@Pattern`, if any.
+- No match → `"{}"`.
+- Values have tab/newline/CR (`\t`, `\n`, `\r`) removed and `"` escaped.
+
+`RegexMatchArray('SDT: 0901 - 0902', '(\d{4})')` (one group) returns:
+
+```json
+{ "M1G1": "0901", "M1G2": "0901", "M2G1": "0902", "M2G2": "0902" }
+```
+
+(G1 = G2 here because the whole match equals the only group; with no groups each match yields only `G1`.)
+
+Parsing in T-SQL (it is an object):
+
+- `OPENJSON(@result)` still works but returns `key/value/type` rows (one row per key like `"M1G1"`), not one structured row per match.
+- One known match/group: `JSON_VALUE(@result, '$."M1G1"')`.
+- Iterate all: `OPENJSON(@result)` without path, parse the `M{m}G{g}` prefix from `key` to group by match.
+
+---
+
+## 5. When to use them in SPs
+
+- Always confirm the function exists first (`fui schema` filtered to functions, or `SELECT * FROM sys.objects WHERE type='FS'`) — usable only if the assembly was `CREATE ASSEMBLY`'d on that DB. Not every DB has them.
+- Use in `spAPI_*` when needed: external API (`httpCall`), uploaded image processing (`ImageResize`/`ImageCrop`), notification email (`sendMail`), regex validation (`RegexIsMatch`), saving files to server disk (`FileWriter`).
+- JSON `nvarchar(max)` results (`httpCall`, `RegexMatchArray`) → parse with `OPENJSON`/`JSON_VALUE` in T-SQL before returning via tAPI.

package/skills/{fui-skill → fui}/references/system-design.md

@@ -36,7 +36,7 @@ Before any module.json:
 
 1. Tables + PK + FK for **all** entities. Per [db-table-design.md](db-table-design.md): `tbl` + PascalCase, PK `[Entity]ID`, audit `CreateUser/CreateTime/UpdateUser/UpdateTime`.
 2. n-n → junction table (e.g. `tblUserRole`).
-3. **`CREATE TABLE` is run by the developer** — fui blocks it; present DDL for review. Existing tables, gated by data loss: `ALTER TABLE ... ADD` and `DROP CONSTRAINT` run directly; `ALTER COLUMN` needs `--confirm-write`; `DROP COLUMN`/`DROP TABLE`/`SWITCH` hard-blocked.
+3. **`CREATE TABLE` is run by the developer** — fui has no guard for it, so do not run it yourself; present DDL for review. Existing tables, gated by data loss: `ALTER TABLE ... ADD` and `DROP CONSTRAINT` run directly; `ALTER COLUMN` needs `--confirm-write`; `DROP COLUMN`/`DROP TABLE`/`SWITCH` hard-blocked.
 4. Design lookup/catalog tables early (shared dropdowns).
 
 **Output:** tables + relations, user-confirmed.
@@ -57,7 +57,7 @@ Each entity → standard set `List/Get/Insert/Update/Delete` + `AUTH_*Options` f
 
 ## Step 4b — Create right DEFINITIONS before any guarded module.json
 
-A code exists only as a row in the project's `acc.tblSysRight`/`acc.tblFunction`. `FunctionRight.includes('42')` **does not create** 42; a missing code silently hides the control ([permission-system.md](permission-system.md) §"Mandatory: a right code must EXIST before you guard with it"). Often forgotten: it is not in the project DB, schema, or any workspace file.
+A code exists only as a row in the project's `acc.tblSysRight`/`acc.tblFunction`. `FunctionRight.includes('42')` **does not create** 42; a missing code silently hides the control ([permission-system.md](permission-system.md) §"A right code must EXIST before guarding with it"). Often forgotten: it is not in the project DB, schema, or any workspace file.
 
 1. `fui right system list` + `fui right function list` — see what exists (new projects usually empty); writes cache `_db/rights.json` **keyed by `apiName`** for `fui module validate`. Multi-alias → run **per alias**; never reuse one alias's cache for another.
 2. Each Step-0 role → a `SystemRight` level (`fui right system new`, level + note). `9` = Project Admin exists already.