npm - sd-render - Versions diffs - 1.2.1 → 1.2.4 - Mend

sd-render 1.2.1 → 1.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (93) hide show

package/api-docs.html ADDED Viewed

@@ -0,0 +1,1460 @@
+<!DOCTYPE html>
+<html lang="th">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>SDForm API Process - Function Reference</title>
+<style>
+* { margin: 0; padding: 0; box-sizing: border-box; }
+body { font-family: 'Segoe UI', Tahoma, sans-serif; background: #1e1e2e; color: #cdd6f4; display: flex; }
+/* Sidebar */
+.sidebar { width: 280px; height: 100vh; background: #181825; border-right: 1px solid #313244; position: fixed; overflow-y: auto; padding: 16px 0; }
+.sidebar h2 { padding: 8px 20px 16px; color: #cba6f7; font-size: 16px; border-bottom: 1px solid #313244; }
+.sidebar .group { padding: 12px 0 4px; }
+.sidebar .group-title { padding: 4px 20px; font-size: 11px; text-transform: uppercase; color: #6c7086; font-weight: 700; letter-spacing: 1px; }
+.sidebar a { display: block; padding: 6px 20px 6px 28px; color: #a6adc8; text-decoration: none; font-size: 13px; font-family: 'Fira Code', 'Consolas', monospace; transition: all .15s; }
+.sidebar a:hover { background: #313244; color: #cba6f7; }
+.sidebar a.active { background: #313244; color: #cba6f7; border-left: 3px solid #cba6f7; padding-left: 25px; }
+/* Main */
+.main { margin-left: 280px; padding: 32px 48px; flex: 1; max-width: 900px; }
+.main h1 { color: #cba6f7; font-size: 28px; margin-bottom: 8px; }
+.main .subtitle { color: #6c7086; margin-bottom: 32px; font-size: 14px; }
+/* Section */
+.section { margin-bottom: 48px; scroll-margin-top: 24px; }
+.section h2 { color: #f5c2e7; font-size: 20px; margin-bottom: 16px; padding-bottom: 8px; border-bottom: 1px solid #313244; }
+.section h3 { color: #89b4fa; font-size: 15px; margin: 0 0 4px; font-family: 'Fira Code', monospace; }
+/* Card */
+.card { background: #1e1e2e; border: 1px solid #313244; border-radius: 8px; padding: 20px; margin-bottom: 20px; }
+.card:hover { border-color: #45475a; }
+.sig { background: #181825; padding: 10px 14px; border-radius: 6px; font-family: 'Fira Code', monospace; font-size: 13px; color: #a6e3a1; margin: 8px 0; overflow-x: auto; }
+.desc { color: #9399b2; font-size: 13px; margin: 6px 0; line-height: 1.6; }
+.tag { display: inline-block; padding: 2px 8px; border-radius: 4px; font-size: 11px; font-weight: 600; margin-right: 4px; }
+.tag-return { background: #1e3a2f; color: #a6e3a1; }
+.tag-param { background: #1e2d3d; color: #89b4fa; }
+.tag-warn { background: #3d2e1e; color: #fab387; }
+/* Code */
+pre { background: #11111b; border: 1px solid #313244; border-radius: 8px; padding: 16px; overflow-x: auto; margin: 10px 0; font-size: 13px; line-height: 1.6; }
+pre code { font-family: 'Fira Code', 'Consolas', monospace; color: #cdd6f4; }
+.kw { color: #cba6f7; }
+.str { color: #a6e3a1; }
+.cm { color: #6c7086; }
+.fn { color: #89b4fa; }
+.num { color: #fab387; }
+.var { color: #f38ba8; }
+/* Table */
+table { width: 100%; border-collapse: collapse; margin: 10px 0; font-size: 13px; }
+th { background: #181825; color: #cba6f7; text-align: left; padding: 8px 12px; }
+td { padding: 8px 12px; border-bottom: 1px solid #313244; color: #bac2de; }
+td code { background: #313244; padding: 2px 6px; border-radius: 4px; font-size: 12px; color: #89b4fa; }
+</style>
+</head>
+<body>
+<nav class="sidebar">
+  <h2>SDForm API Docs</h2>
+  <div class="group">
+    <div class="group-title">Database CRUD</div>
+    <a href="#dbInsert">dbInsert</a>
+    <a href="#dbInsertMany">dbInsertMany</a>
+    <a href="#dbFindAll">dbFindAll</a>
+    <a href="#dbFindOne">dbFindOne</a>
+    <a href="#dbFindById">dbFindById</a>
+    <a href="#dbUpdate">dbUpdate</a>
+    <a href="#dbUpdateMany">dbUpdateMany</a>
+    <a href="#dbDelete">dbDelete</a>
+    <a href="#dbObjectId">dbObjectId</a>
+    <a href="#curDate">curDate</a>
+  </div>
+  <div class="group">
+    <div class="group-title">SDForm Functions</div>
+    <a href="#sdformGetOne">sdformGetOne</a>
+    <a href="#sdformGetAll">sdformGetAll</a>
+    <a href="#sdformSetOne">sdformSetOne</a>
+    <a href="#sdformDelOne">sdformDelOne</a>
+  </div>
+  <div class="group">
+    <div class="group-title">Form Management</div>
+    <a href="#dataPolicyAudit">dataPolicyAudit</a>
+    <a href="#initSaveForm">initSaveForm</a>
+    <a href="#insertData">insertData</a>
+    <a href="#insertDataForm">insertDataForm</a>
+    <a href="#updateFileStatus">updateFileStatus</a>
+    <a href="#deleteFileSystem">deleteFileSystem</a>
+    <a href="#afterSaveForm">afterSaveForm</a>
+    <a href="#afterDeleteForm">afterDeleteForm</a>
+  </div>
+  <div class="group">
+    <div class="group-title">Process & Event</div>
+    <a href="#runProcess">runProcess</a>
+    <a href="#subProcess">subProcess</a>
+  </div>
+  <div class="group">
+    <div class="group-title">Transactions & Locks</div>
+    <a href="#txn-overview">ภาพรวม Transactions</a>
+    <a href="#mongoTxn">mongoTxn</a>
+    <a href="#withVersion">withVersion</a>
+    <a href="#txn-patterns">Pattern การใช้งาน</a>
+    <a href="#txn-errors">Error handling</a>
+  </div>
+  <div class="group">
+    <div class="group-title">xformDatax (Return to Form)</div>
+    <a href="#xformDatax-overview">วิธีส่งค่ากลับฟอร์ม</a>
+    <a href="#xformDatax-basic">ตัวอย่าง: คำนวณ BMI</a>
+    <a href="#xformDatax-multi">ส่งกลับหลาย field</a>
+    <a href="#xformDatax-lookup">ดึงข้อมูลเติมฟอร์ม</a>
+    <a href="#xformDatax-rules">กฎสำคัญ</a>
+  </div>
+  <div class="group">
+    <div class="group-title">SQL & Query</div>
+    <a href="#runSql">runSql</a>
+    <a href="#parsedSQL">parsedSQL</a>
+    <a href="#parsedProvider">parsedProvider</a>
+    <a href="#pgQuery">pgQuery</a>
+  </div>
+  <div class="group">
+    <div class="group-title">WebSocket & Notify</div>
+    <a href="#wsSend">wsSend</a>
+    <a href="#notifySend">notifySend</a>
+  </div>
+  <div class="group">
+    <div class="group-title">User & Roles</div>
+    <a href="#getUserInfo">getUserInfo</a>
+    <a href="#isRole">isRole</a>
+    <a href="#isAdmin">isAdmin</a>
+    <a href="#isManager">isManager</a>
+    <a href="#isSuper">isSuper</a>
+    <a href="#isAuth">isAuth</a>
+    <a href="#assignRole">assignRole</a>
+    <a href="#revokeRole">revokeRole</a>
+  </div>
+  <div class="group">
+    <div class="group-title">Encryption</div>
+    <a href="#encode">encode</a>
+    <a href="#decode">decode</a>
+    <a href="#encodeObj">encodeObj</a>
+    <a href="#decodeObj">decodeObj</a>
+    <a href="#generateKeyPair">generateKeyPair</a>
+  </div>
+  <div class="group">
+    <div class="group-title">Report</div>
+    <a href="#wordReport">wordReport</a>
+  </div>
+  <div class="group">
+    <div class="group-title">Utilities (this.*)</div>
+    <a href="#isNotNull">isNotNull / isNull</a>
+    <a href="#isEmptyStr">isEmptyStr / isEmptyObj</a>
+    <a href="#generateId_util">generateId / genUidTime / genUUID</a>
+    <a href="#deepClone">deepClone</a>
+    <a href="#compareHash">compareHash</a>
+    <a href="#objectPath">setObjectByPath / getObjectByPath</a>
+    <a href="#string2Json">string2Json / string2boolean</a>
+    <a href="#object2Path">object2Path</a>
+  </div>
+  <div class="group">
+    <div class="group-title">Interfaces</div>
+    <a href="#SdProvider">SdProvider</a>
+    <a href="#SdDataProvider">SdDataProvider</a>
+    <a href="#UserInfo">UserInfo</a>
+  </div>
+</nav>
+<main class="main">
+<h1>SDForm API Process</h1>
+<p class="subtitle">Function Reference สำหรับเขียน api_process ใน API Factory</p>
+<!-- ============================================ -->
+<!-- DATABASE CRUD -->
+<!-- ============================================ -->
+<div class="section" id="db-crud">
+<h2>Database CRUD</h2>
+<p class="desc">เข้าถึง MongoDB โดยตรง ไม่ผ่านระบบสิทธิ์ของ sdform</p>
+<div class="card" id="dbInsert">
+<h3>app.dbInsert()</h3>
+<div class="sig">app.dbInsert(data, from, userInfo)</div>
+<p class="desc">Insert เอกสารเดียวลง collection พร้อมเพิ่ม audit fields อัตโนมัติ (created_by, created_at, updated_by, updated_at)</p>
+<table>
+  <tr><th>Param</th><th>Type</th><th>Description</th></tr>
+  <tr><td><code>data</code></td><td>object</td><td>ข้อมูลที่ต้องการ insert</td></tr>
+  <tr><td><code>from</code></td><td>string</td><td>ชื่อ collection</td></tr>
+  <tr><td><code>userInfo</code></td><td>UserInfo</td><td>ข้อมูลผู้ใช้</td></tr>
+</table>
+<span class="tag tag-return">return</span> <code>{ success, reply: { message, data, id } }</code>
+<pre><code><span class="cm">// Insert ข้อมูลลง collection ตรง</span>
+<span class="kw">const</span> result = <span class="kw">await</span> app.<span class="fn">dbInsert</span>({
+    name: <span class="str">'สมชาย'</span>,
+    email: <span class="str">'somchai@email.com'</span>,
+    age: <span class="num">30</span>
+}, <span class="str">'zdata_employee'</span>, userInfo);
+<span class="kw">if</span> (result.success) {
+    <span class="kw">return</span> { id: result.id, data: result.reply.data };
+}</code></pre>
+</div>
+<div class="card" id="dbInsertMany">
+<h3>app.dbInsertMany()</h3>
+<div class="sig">app.dbInsertMany(data, from, userInfo)</div>
+<p class="desc">Insert หลายเอกสารพร้อมกัน</p>
+<table>
+  <tr><th>Param</th><th>Type</th><th>Description</th></tr>
+  <tr><td><code>data</code></td><td>array</td><td>array ของ object ที่ต้องการ insert</td></tr>
+  <tr><td><code>from</code></td><td>string</td><td>ชื่อ collection</td></tr>
+  <tr><td><code>userInfo</code></td><td>UserInfo</td><td>ข้อมูลผู้ใช้</td></tr>
+</table>
+<span class="tag tag-return">return</span> <code>{ success, reply: { message, data, ids[] } }</code>
+<pre><code><span class="kw">const</span> items = [
+    { name: <span class="str">'A'</span>, value: <span class="num">1</span> },
+    { name: <span class="str">'B'</span>, value: <span class="num">2</span> },
+    { name: <span class="str">'C'</span>, value: <span class="num">3</span> }
+];
+<span class="kw">const</span> result = <span class="kw">await</span> app.<span class="fn">dbInsertMany</span>(items, <span class="str">'zdata_items'</span>, userInfo);</code></pre>
+</div>
+<div class="card" id="dbFindAll">
+<h3>app.dbFindAll()</h3>
+<div class="sig">app.dbFindAll(dataProvider, totalEnable, limitEnable)</div>
+<p class="desc">ดึงข้อมูลหลายรายการ รองรับ where, join, pagination, sort, group by</p>
+<table>
+  <tr><th>Param</th><th>Type</th><th>Description</th></tr>
+  <tr><td><code>dataProvider</code></td><td>SdDataProvider</td><td>เงื่อนไขการ query</td></tr>
+  <tr><td><code>totalEnable</code></td><td>boolean</td><td>นับจำนวนทั้งหมดด้วย</td></tr>
+  <tr><td><code>limitEnable</code></td><td>boolean</td><td>เปิดใช้ limit/offset</td></tr>
+</table>
+<span class="tag tag-return">return</span> <code>{ success, reply: { message, data[], total, offset } }</code>
+<pre><code><span class="cm">// ดึงข้อมูลพนักงานที่ active เรียงตามชื่อ</span>
+<span class="kw">let</span> dp = {
+    from: <span class="str">'zdata_employee'</span>,
+    select: [<span class="str">'name'</span>, <span class="str">'email'</span>, <span class="str">'department'</span>],
+    where: <span class="str">"xrstatx NOT IN(0,3) AND status = :status"</span>,
+    orderBy: [{ column: <span class="str">'name'</span>, sort: <span class="str">'ASC'</span> }],
+    limit: <span class="num">20</span>,
+    page: <span class="num">1</span>,
+    params: { status: <span class="str">'active'</span> }
+};
+<span class="kw">const</span> result = <span class="kw">await</span> app.<span class="fn">dbFindAll</span>(dp, <span class="kw">true</span>, <span class="kw">true</span>);
+<span class="cm">// result.reply.data   = [{ name, email, department }, ...]</span>
+<span class="cm">// result.reply.total  = 150  (จำนวนทั้งหมด)</span>
+<span class="cm">// result.reply.offset = 0</span></code></pre>
+<pre><code><span class="cm">// ใช้ NoSQL aggregate ตรง</span>
+<span class="kw">let</span> dp = {
+    from: <span class="str">'zdata_employee'</span>,
+    nosql: {
+        type: <span class="str">'aggregate'</span>,
+        collections: [<span class="str">'zdata_employee'</span>],
+        pipeline: [
+            { $match: { xrstatx: { $nin: [<span class="num">0</span>, <span class="num">3</span>] } } },
+            { $group: { _id: <span class="str">'$department'</span>, count: { $sum: <span class="num">1</span> } } }
+        ]
+    }
+};
+<span class="kw">const</span> result = <span class="kw">await</span> app.<span class="fn">dbFindAll</span>(dp, <span class="kw">false</span>, <span class="kw">false</span>);</code></pre>
+</div>
+<div class="card" id="dbFindOne">
+<h3>app.dbFindOne()</h3>
+<div class="sig">app.dbFindOne(dataProvider)</div>
+<p class="desc">ดึงข้อมูล 1 รายการ</p>
+<span class="tag tag-return">return</span> <code>{ success, id, reply: { message, data } }</code>
+<pre><code><span class="kw">let</span> dp = {
+    from: <span class="str">'zdata_employee'</span>,
+    where: <span class="str">"_id = CONVERT(:id, 'objectId')"</span>,
+    params: { id: params.dataid }
+};
+<span class="kw">const</span> result = <span class="kw">await</span> app.<span class="fn">dbFindOne</span>(dp);
+<span class="kw">if</span> (result.success) {
+    <span class="kw">return</span> { employee: result.reply.data };
+}</code></pre>
+</div>
+<div class="card" id="dbFindById">
+<h3>app.dbFindById()</h3>
+<div class="sig">app.dbFindById(dataObjectId, from, projection?)</div>
+<p class="desc">ดึงข้อมูลด้วย ObjectId ตรง ง่ายกว่า dbFindOne</p>
+<table>
+  <tr><th>Param</th><th>Type</th><th>Description</th></tr>
+  <tr><td><code>dataObjectId</code></td><td>ObjectId</td><td>ObjectId ของเอกสาร</td></tr>
+  <tr><td><code>from</code></td><td>string</td><td>ชื่อ collection</td></tr>
+  <tr><td><code>projection</code></td><td>object?</td><td>เลือก field ที่ต้องการ</td></tr>
+</table>
+<pre><code><span class="kw">const</span> result = <span class="kw">await</span> app.<span class="fn">dbFindById</span>(
+    app.<span class="fn">dbObjectId</span>(params.dataid),
+    <span class="str">'zdata_employee'</span>,
+    { name: <span class="num">1</span>, email: <span class="num">1</span> }  <span class="cm">// เฉพาะ field ที่ต้องการ</span>
+);
+<span class="kw">if</span> (result.success) {
+    <span class="kw">return</span> { data: result.reply.data };
+}</code></pre>
+</div>
+<div class="card" id="dbUpdate">
+<h3>app.dbUpdate()</h3>
+<div class="sig">app.dbUpdate(data, from, userInfo, filter, upsert?)</div>
+<p class="desc">อัพเดทเอกสาร 1 รายการ merge กับข้อมูลเดิม เพิ่ม updated_by, updated_at อัตโนมัติ</p>
+<table>
+  <tr><th>Param</th><th>Type</th><th>Description</th></tr>
+  <tr><td><code>data</code></td><td>object</td><td>ข้อมูลที่ต้องการอัพเดท</td></tr>
+  <tr><td><code>from</code></td><td>string</td><td>ชื่อ collection</td></tr>
+  <tr><td><code>userInfo</code></td><td>UserInfo</td><td>ข้อมูลผู้ใช้</td></tr>
+  <tr><td><code>filter</code></td><td>object</td><td>เงื่อนไข filter</td></tr>
+  <tr><td><code>upsert</code></td><td>boolean?</td><td>insert ถ้าไม่เจอ (default: false)</td></tr>
+</table>
+<pre><code><span class="cm">// อัพเดท status ของพนักงาน</span>
+<span class="kw">const</span> result = <span class="kw">await</span> app.<span class="fn">dbUpdate</span>(
+    { status: <span class="str">'inactive'</span>, reason: <span class="str">'ลาออก'</span> },
+    <span class="str">'zdata_employee'</span>,
+    userInfo,
+    { _id: app.<span class="fn">dbObjectId</span>(params.dataid) }
+);
+<span class="cm">// upsert: insert ถ้าไม่มี</span>
+<span class="kw">const</span> result = <span class="kw">await</span> app.<span class="fn">dbUpdate</span>(
+    { count: <span class="num">1</span>, name: <span class="str">'ใหม่'</span> },
+    <span class="str">'zdata_counter'</span>,
+    userInfo,
+    { code: <span class="str">'VISIT'</span> },
+    <span class="kw">true</span>  <span class="cm">// upsert</span>
+);</code></pre>
+</div>
+<div class="card" id="dbUpdateMany">
+<h3>app.dbUpdateMany()</h3>
+<div class="sig">app.dbUpdateMany(data, from, userInfo, filter, upsert?)</div>
+<p class="desc">อัพเดทหลายเอกสารที่ตรงเงื่อนไข</p>
+<pre><code><span class="cm">// เปลี่ยน status พนักงานทั้งแผนก</span>
+<span class="kw">const</span> result = <span class="kw">await</span> app.<span class="fn">dbUpdateMany</span>(
+    { status: <span class="str">'transferred'</span> },
+    <span class="str">'zdata_employee'</span>,
+    userInfo,
+    { department: <span class="str">'IT'</span> }
+);</code></pre>
+</div>
+<div class="card" id="dbDelete">
+<h3>app.dbDelete()</h3>
+<div class="sig">app.dbDelete(from, filter)</div>
+<p class="desc">ลบเอกสารจริงจาก collection</p>
+<span class="tag tag-warn">Warning</span> ลบถาวร ไม่สามารถกู้คืนได้
+<pre><code><span class="kw">const</span> result = <span class="kw">await</span> app.<span class="fn">dbDelete</span>(
+    <span class="str">'zdata_temp'</span>,
+    { expired: <span class="kw">true</span> }
+);</code></pre>
+</div>
+<div class="card" id="dbObjectId">
+<h3>app.dbObjectId()</h3>
+<div class="sig">app.dbObjectId(id?)</div>
+<p class="desc">แปลง string เป็น MongoDB ObjectId หรือสร้างใหม่ถ้าไม่ส่งค่า</p>
+<pre><code><span class="cm">// แปลง string → ObjectId</span>
+<span class="kw">const</span> oid = app.<span class="fn">dbObjectId</span>(<span class="str">'69d78e1a160f454e4e480cd3'</span>);
+<span class="cm">// สร้าง ObjectId ใหม่</span>
+<span class="kw">const</span> newOid = app.<span class="fn">dbObjectId</span>();</code></pre>
+</div>
+<div class="card" id="curDate">
+<h3>app.curDate()</h3>
+<div class="sig">app.curDate(format?)</div>
+<p class="desc">วันที่-เวลาปัจจุบัน format ด้วย dayjs (default: 'YYYY-MM-DD HH:mm:ss')</p>
+<pre><code><span class="kw">const</span> now = app.<span class="fn">curDate</span>();              <span class="cm">// "2026-04-09 18:30:00"</span>
+<span class="kw">const</span> date = app.<span class="fn">curDate</span>(<span class="str">'YYYY-MM-DD'</span>); <span class="cm">// "2026-04-09"</span>
+<span class="kw">const</span> thai = app.<span class="fn">curDate</span>(<span class="str">'DD/MM/YYYY'</span>); <span class="cm">// "09/04/2026"</span></code></pre>
+</div>
+</div>
+<!-- ============================================ -->
+<!-- SDFORM FUNCTIONS -->
+<!-- ============================================ -->
+<div class="section" id="sdform-func">
+<h2>SDForm Functions</h2>
+<p class="desc">เข้าถึงข้อมูลผ่านระบบ sdform — เช็คสิทธิ์ + รัน form event อัตโนมัติ</p>
+<div class="card" id="sdformGetOne">
+<h3>app.sdformGetOne()</h3>
+<div class="sig">app.sdformGetOne(sdProvider, userInfo)</div>
+<p class="desc">ดึงข้อมูล 1 รายการผ่าน sdform เช็คสิทธิ์ view + data sharing policy</p>
+<span class="tag tag-return">return</span> <code>{ success, data, message, sdformModel, id }</code>
+<pre><code><span class="kw">let</span> sdProvider = {
+    providerId: <span class="str">'69d785d4160f454e4e480c82'</span>,  <span class="cm">// formId</span>
+    providerType: <span class="str">'FORM'</span>,
+    options: {
+        where: <span class="str">"_id = CONVERT(:id, 'objectId')"</span>
+    },
+    params: { id: params.dataid }
+};
+<span class="kw">const</span> result = <span class="kw">await</span> app.<span class="fn">sdformGetOne</span>(sdProvider, userInfo);
+<span class="kw">if</span> (result.success) {
+    <span class="kw">return</span> { data: result.data };
+}</code></pre>
+</div>
+<div class="card" id="sdformGetAll">
+<h3>app.sdformGetAll()</h3>
+<div class="sig">app.sdformGetAll(sdProvider, totalEnable, userInfo)</div>
+<p class="desc">ดึงข้อมูลหลายรายการผ่าน sdform เช็คสิทธิ์ view</p>
+<span class="tag tag-return">return</span> <code>{ success, data[], message, sdformModel, id }</code>
+<pre><code><span class="kw">let</span> sdProvider = {
+    providerId: <span class="str">'69d785d4160f454e4e480c82'</span>,
+    providerType: <span class="str">'FORM'</span>,
+    options: {
+        limit: <span class="num">10</span>,
+        orderBy: [{ column: <span class="str">'created_at'</span>, sort: <span class="str">'DESC'</span> }]
+    },
+    params: {}
+};
+<span class="kw">const</span> result = <span class="kw">await</span> app.<span class="fn">sdformGetAll</span>(sdProvider, <span class="kw">true</span>, userInfo);</code></pre>
+</div>
+<div class="card" id="sdformSetOne">
+<h3>app.sdformSetOne()</h3>
+<div class="sig">app.sdformSetOne(formId, dataId, dataUpdate, rstat, userInfo)</div>
+<p class="desc">บันทึกข้อมูลผ่าน sdform — เช็คสิทธิ์ insert/update, รัน initSaveForm + afterSaveForm event</p>
+<table>
+  <tr><th>Param</th><th>Type</th><th>Description</th></tr>
+  <tr><td><code>formId</code></td><td>string</td><td>ID ของฟอร์มใน sdform_manage</td></tr>
+  <tr><td><code>dataId</code></td><td>string</td><td>ID ของ record (ว่าง = insert ใหม่)</td></tr>
+  <tr><td><code>dataUpdate</code></td><td>object</td><td>ข้อมูลที่ต้องการบันทึก</td></tr>
+  <tr><td><code>rstat</code></td><td>number</td><td>0=draft, 1=active, 2=submitted, 3=deleted</td></tr>
+  <tr><td><code>userInfo</code></td><td>UserInfo</td><td>ข้อมูลผู้ใช้</td></tr>
+</table>
+<pre><code><span class="cm">// อัพเดท record ที่มีอยู่</span>
+<span class="kw">const</span> result = <span class="kw">await</span> app.<span class="fn">sdformSetOne</span>(
+    <span class="str">'69d785d4160f454e4e480c82'</span>,  <span class="cm">// formId</span>
+    params.dataid,                   <span class="cm">// dataId</span>
+    { weight: <span class="num">70</span>, height: <span class="num">175</span> },     <span class="cm">// data</span>
+    <span class="num">1</span>,                               <span class="cm">// rstat = active</span>
+    userInfo
+);
+<span class="kw">if</span> (result.success) {
+    <span class="kw">return</span> { data: result.data, id: result.id };
+}</code></pre>
+</div>
+<div class="card" id="sdformDelOne">
+<h3>app.sdformDelOne()</h3>
+<div class="sig">app.sdformDelOne(formId, dataId, userInfo)</div>
+<p class="desc">ลบข้อมูลผ่าน sdform (soft delete: xrstatx = 3) เช็คสิทธิ์ delete + รัน afterDeleteForm event</p>
+<pre><code><span class="kw">const</span> result = <span class="kw">await</span> app.<span class="fn">sdformDelOne</span>(
+    <span class="str">'69d785d4160f454e4e480c82'</span>,
+    params.dataid,
+    userInfo
+);</code></pre>
+</div>
+</div>
+<!-- ============================================ -->
+<!-- FORM MANAGEMENT -->
+<!-- ============================================ -->
+<div class="section" id="form-mgmt">
+<h2>Form Management</h2>
+<div class="card" id="dataPolicyAudit">
+<h3>app.dataPolicyAudit()</h3>
+<div class="sig">app.dataPolicyAudit(sdProvider, userInfo, policyAction, data, type)</div>
+<p class="desc">ตรวจสอบสิทธิ์การเข้าถึงฟอร์ม/SQL ตาม form_share, policy, roles</p>
+<table>
+  <tr><th>Param</th><th>Type</th><th>Description</th></tr>
+  <tr><td><code>policyAction</code></td><td>string</td><td>'insert' | 'update' | 'delete' | 'view'</td></tr>
+  <tr><td><code>type</code></td><td>string</td><td>'one' | 'all'</td></tr>
+</table>
+<pre><code><span class="kw">let</span> sdProvider = { providerId: formId, providerType: <span class="str">'FORM'</span> };
+<span class="kw">const</span> perm = <span class="kw">await</span> app.<span class="fn">dataPolicyAudit</span>(
+    sdProvider, userInfo, <span class="str">'view'</span>, <span class="kw">undefined</span>, <span class="str">'all'</span>
+);
+<span class="kw">if</span> (perm.permissionDenied) {
+    <span class="kw">return</span> { success: <span class="kw">false</span>, message: <span class="str">'ไม่มีสิทธิ์'</span> };
+}
+<span class="cm">// perm.from = collection name</span>
+<span class="cm">// perm.dataProvider = prepared SdDataProvider</span>
+<span class="cm">// perm.formModel = SdFormType model</span></code></pre>
+</div>
+<div class="card" id="initSaveForm">
+<h3>app.initSaveForm()</h3>
+<div class="sig">app.initSaveForm(sdformModel, dataUpdate, dataObjectId, rstat, userInfo)</div>
+<p class="desc">เตรียมข้อมูลก่อน save — แปลง type, จัดการ auto-number, เช็ค unique record</p>
+<pre><code><span class="kw">const</span> init = <span class="kw">await</span> app.<span class="fn">initSaveForm</span>(
+    sdformModel, dataUpdate, app.<span class="fn">dbObjectId</span>(dataId), <span class="num">1</span>, userInfo
+);
+<span class="kw">if</span> (init.success) {
+    <span class="cm">// init.data = processed data ready to save</span>
+}</code></pre>
+</div>
+<div class="card" id="insertData">
+<h3>app.insertData()</h3>
+<div class="sig">app.insertData(formId, userInfo)</div>
+<p class="desc">สร้าง record เปล่าใหม่ (xrstatx = 0) สำหรับฟอร์ม</p>
+<pre><code><span class="kw">const</span> result = <span class="kw">await</span> app.<span class="fn">insertData</span>(
+    <span class="str">'69d785d4160f454e4e480c82'</span>, userInfo
+);
+<span class="cm">// result.id = ID ของ record ใหม่</span></code></pre>
+</div>
+<div class="card" id="insertDataForm">
+<h3>app.insertDataForm()</h3>
+<div class="sig">app.insertDataForm(sdformModel, userInfo)</div>
+<p class="desc">สร้าง record ใหม่จาก sdformModel พร้อม system fields (site, unit, version)</p>
+<pre><code><span class="kw">const</span> result = <span class="kw">await</span> app.<span class="fn">insertDataForm</span>(sdformModel, userInfo);</code></pre>
+</div>
+<div class="card" id="updateFileStatus">
+<h3>app.updateFileStatus()</h3>
+<div class="sig">app.updateFileStatus(sdformModel, formData, userInfo)</div>
+<p class="desc">อัพเดท use_status ของไฟล์ใน core_files_manage เป็น true</p>
+</div>
+<div class="card" id="deleteFileSystem">
+<h3>app.deleteFileSystem()</h3>
+<div class="sig">app.deleteFileSystem(formData, userInfo)</div>
+<p class="desc">ลบไฟล์จาก filesystem และ record ใน core_files_manage</p>
+</div>
+<div class="card" id="afterSaveForm">
+<h3>app.afterSaveForm()</h3>
+<div class="sig">app.afterSaveForm(sdformModel, dataUpdate, dataObjectId, isInsert, userInfo)</div>
+<p class="desc">รัน form event หลัง save (api_onevent, update_relational_fields, harvest_data)</p>
+<span class="tag tag-return">return</span> <code>{ updateData: boolean, data }</code>
+</div>
+<div class="card" id="afterDeleteForm">
+<h3>app.afterDeleteForm()</h3>
+<div class="sig">app.afterDeleteForm(sdformModel, dataUpdate, dataObjectId, userInfo)</div>
+<p class="desc">รัน form event หลัง delete (api_onevent on delete, delete_children_record, harvest_data)</p>
+<span class="tag tag-return">return</span> <code>{ updateData: boolean, data }</code>
+</div>
+</div>
+<!-- ============================================ -->
+<!-- PROCESS & EVENT -->
+<!-- ============================================ -->
+<div class="section" id="process-event">
+<h2>Process & Event</h2>
+<div class="card" id="runProcess">
+<h3>app.runProcess()</h3>
+<div class="sig">app.runProcess(processId, params, userInfo)</div>
+<p class="desc">เรียก API Factory ตัวอื่น (full result รวม apiModel)</p>
+<span class="tag tag-return">return</span> <code>{ success, permissionDenied, reply: { status, message, data, error }, apiModel }</code>
+<pre><code><span class="kw">const</span> result = <span class="kw">await</span> app.<span class="fn">runProcess</span>(
+    <span class="str">'69d78073160f454e4e480c7c'</span>,
+    { title: <span class="str">'Hello'</span>, message: <span class="str">'Test'</span> },
+    userInfo
+);
+<span class="kw">if</span> (result.success) {
+    <span class="kw">return</span> result.reply.data;
+}</code></pre>
+</div>
+<div class="card" id="subProcess">
+<h3>app.subProcess()</h3>
+<div class="sig">app.subProcess(processId, params, userInfo)</div>
+<p class="desc">เรียก API Factory ตัวอื่น (simplified result) เหมาะใช้ chain หลาย API</p>
+<span class="tag tag-return">return</span> <code>{ success, message, data }</code>
+<pre><code><span class="cm">// เรียก API ต่อเนื่อง</span>
+<span class="kw">const</span> step1 = <span class="kw">await</span> app.<span class="fn">subProcess</span>(<span class="str">'api_id_1'</span>, params, userInfo);
+<span class="kw">if</span> (step1.success) {
+    <span class="kw">const</span> step2 = <span class="kw">await</span> app.<span class="fn">subProcess</span>(<span class="str">'api_id_2'</span>, step1.data, userInfo);
+    <span class="kw">return</span> step2.data;
+}</code></pre>
+</div>
+</div>
+<!-- ============================================ -->
+<!-- TRANSACTIONS & OPTIMISTIC LOCK -->
+<!-- ============================================ -->
+<div class="section" id="transactions">
+<h2>Transactions & Optimistic Lock</h2>
+<p class="desc">
+  ใช้เมื่อต้องการความถูกต้องของข้อมูลภายใต้ <strong>concurrent writes</strong> เช่น ตัดงบประมาณ, โอนเงิน, ลดสต๊อก, update balance
+  ระบบใช้ MongoDB Transaction + Optimistic Lock (version field) ป้องกัน lost update
+</p>
+<div class="card" id="txn-overview">
+<h3>ภาพรวม</h3>
+<p class="desc">มี 2 helper ที่ทำงานคู่กัน:</p>
+<table>
+  <tr><th>Helper</th><th>หน้าที่</th></tr>
+  <tr><td><code>this.mongoTxn</code></td><td>ห่อฟังก์ชันใน <strong>MongoDB transaction</strong> — commit ทั้งหมดหรือ rollback ทั้งหมด + retry อัตโนมัติเมื่อเจอ conflict</td></tr>
+  <tr><td><code>this.withVersion</code></td><td><strong>Optimistic lock</strong> — อ่าน doc → คำนวณ patch → update ด้วย filter <code>{_id, version: current}</code> + bump version (+1). ถ้าคนอื่นเขียนก่อน → throw <code>VERSION_CONFLICT</code> → mongoTxn retry ให้</td></tr>
+</table>
+<p class="desc">ใช้ร่วมกันเมื่อต้องการความถูกต้องระดับ <strong>ACID</strong> + <strong>lost-update protection</strong></p>
+<pre><code><span class="cm">// โครงสร้างพื้นฐาน</span>
+<span class="kw">await</span> <span class="kw">this</span>.<span class="fn">mongoTxn</span>(<span class="kw">async</span> (session) =&gt; {
+    <span class="kw">await</span> <span class="kw">this</span>.<span class="fn">withVersion</span>(session, <span class="str">'zdata_budget'</span>, budgetId, (doc) =&gt; {
+        <span class="kw">if</span> (doc.balance &lt; amount) <span class="kw">throw new</span> <span class="fn">Error</span>(<span class="str">'Insufficient'</span>);
+        <span class="kw">return</span> { $inc: { balance: -amount, expense: amount } };
+    });
+}, { name: <span class="str">'deductBudget'</span>, maxRetry: <span class="num">5</span> });</code></pre>
+<span class="tag tag-warn">Requirement</span> MongoDB ต้องเป็น <strong>Replica Set</strong> ไม่ใช่ standalone (ระบบ setup แล้วเป็น <code>rs0</code>)
+</div>
+<div class="card" id="mongoTxn">
+<h3>this.mongoTxn()</h3>
+<div class="sig">this.mongoTxn(fn, options?)</div>
+<p class="desc">
+  รัน <code>fn(session)</code> ภายใน MongoDB transaction พร้อม retry อัตโนมัติ (exponential backoff + jitter)
+  เมื่อเจอ conflict ที่ retry ได้ (VERSION_CONFLICT, WriteConflict/112, NoSuchTransaction/251, TransientTransactionError, UnknownTransactionCommitResult)
+</p>
+<table>
+  <tr><th>Param</th><th>Type</th><th>Description</th></tr>
+  <tr><td><code>fn</code></td><td>async (session) =&gt; any</td><td>ฟังก์ชันที่ทำงานภายใน transaction — ต้องส่ง <code>session</code> เข้า mongo operations ทุกตัว</td></tr>
+  <tr><td><code>options.name</code></td><td>string?</td><td>ชื่อสำหรับ log (default: <code>'anonymous'</code>)</td></tr>
+  <tr><td><code>options.maxRetry</code></td><td>number?</td><td>จำนวนครั้งที่ retry ได้ (default: <code>3</code>, ต้อง &gt;= 1)</td></tr>
+  <tr><td><code>options.baseDelayMs</code></td><td>number?</td><td>delay เริ่มต้น (default: <code>50</code>) — delay จริง = <code>base * 2^attempt + jitter</code></td></tr>
+  <tr><td><code>options.timeoutMs</code></td><td>number? | null</td><td><strong>CSOT</strong> (Client Side Operation Timeout) — จำกัดเวลาที่ mongo driver ทำ <strong>internal retry loop</strong> เมื่อเจอ <code>TransientTransactionError</code> (default: <code>15000</code> = 15s เหมาะกับ interactive request / API response) ตั้งเป็น <code>null</code> เพื่อปิด CSOT แล้วใช้ <code>maxCommitTimeMS=10s</code> + driver default 120s แทน</td></tr>
+</table>
+<span class="tag tag-return">return</span> <code>ค่าที่ fn return กลับมา</code>
+<span class="tag tag-warn">throws</span> <code>'Transaction conflict — please retry later'</code> เมื่อ maxRetry หมด หรือ original error หาก non-retryable
+<span class="tag tag-warn">throws</span> <code>MongoOperationTimeoutError</code> เมื่อ CSOT หมดและไม่ succeed — <strong>ไม่ถูก retry อัตโนมัติ</strong> เพราะเสี่ยง double-commit (ดู warning ด้านล่าง)
+<div style="border-top: 1px solid #313244;border-bottom: 1px solid #313244;border-right: 1px solid #313244; border-left:4px solid #ff9800;padding:10px 14px;margin:12px 0;border-radius:4px">
+  <strong>⚠️ ทำไม default = 15s?</strong><br>
+  MongoDB driver v6+ ถ้าไม่ตั้ง <code>timeoutMs</code> จะใช้ internal retry timeout <strong>hardcoded 120 วินาที</strong> — อันตรายมากสำหรับ interactive request เพราะผู้ใช้จะเห็นหน้าค้าง 2 นาที ค่า 15s คือ sweet spot สำหรับ API ทั่วไป<br><br>
+  <strong>⚠️ Double-commit risk เมื่อ CSOT fire ตอน commit phase</strong><br>
+  ถ้า CSOT timeout เกิดระหว่างตอน <code>commitTransaction()</code> — server อาจ commit สำเร็จไปแล้ว แต่ ack กลับมาช้าเกิน timeout → <code>mongoTxn</code> จะ <strong>ไม่ retry</strong> ให้ (โยน <code>MongoOperationTimeoutError</code> ออกไป) เพราะถ้า retry จะไป mutate doc อีกครั้ง → <strong>double-commit</strong><br><br>
+  <strong>วิธีการใช้ที่แนะนำ:</strong>
+  <ul style="margin:6px 0 0 20px">
+    <li><strong>Interactive API</strong> (default 15s) — เพียงพอสำหรับ transaction ปกติ</li>
+    <li><strong>Batch job / Migration</strong> — ตั้ง <code>timeoutMs: 60000</code> ขึ้นไป หรือ <code>null</code> (เพื่อใช้ 120s default)</li>
+    <li><strong>Heavy contention</strong> — ตั้งสูง ๆ เช่น <code>120000+</code> ป้องกัน CSOT fire ตอน commit</li>
+    <li>ถ้าต้อง catch <code>MongoOperationTimeoutError</code> เอง ให้ตรวจสถานะ doc ก่อนตัดสินใจ retry</li>
+  </ul>
+</div>
+<pre><code><span class="cm">// ตัดงบประมาณ 500 บาท (full pattern)</span>
+<span class="kw">const</span> result = <span class="kw">await</span> <span class="kw">this</span>.<span class="fn">mongoTxn</span>(<span class="kw">async</span> (session) =&gt; {
+    <span class="kw">await</span> <span class="kw">this</span>.<span class="fn">withVersion</span>(session, <span class="str">'zdata_budget'</span>, params.budgetId, (doc) =&gt; {
+        <span class="kw">if</span> (doc.balance &lt; <span class="num">500</span>) <span class="kw">throw new</span> <span class="fn">Error</span>(<span class="str">'งบประมาณไม่พอ'</span>);
+        <span class="kw">return</span> { $inc: { balance: -<span class="num">500</span>, expense: <span class="num">500</span> } };
+    });
+    <span class="cm">// ใส่ log (ใช้ session เดียวกัน)</span>
+    <span class="kw">await</span> app.db.<span class="fn">collection</span>(<span class="str">'zdata_budget_log'</span>).<span class="fn">insertOne</span>({
+        budget_id: params.budgetId,
+        amount: <span class="num">500</span>,
+        type: <span class="str">'EXPENSE'</span>,
+        created_at: <span class="kw">new</span> <span class="fn">Date</span>()
+    }, { session });
+    <span class="kw">return</span> { ok: <span class="kw">true</span>, amount: <span class="num">500</span> };
+}, {
+    name: <span class="str">'deductBudget'</span>,
+    maxRetry: <span class="num">5</span>,
+    timeoutMs: <span class="num">15000</span>  <span class="cm">// default 15s — safe for interactive API</span>
+});
+<span class="kw">return</span> { xformDatax: { status: <span class="str">'DEDUCTED'</span>, amount: result.amount } };</code></pre>
+</div>
+<div class="card" id="withVersion">
+<h3>this.withVersion()</h3>
+<div class="sig">this.withVersion(session, collection, id, mutate)</div>
+<p class="desc">
+  Optimistic lock helper — อ่าน doc ด้วย <code>session</code> → เรียก <code>mutate(doc)</code> ให้คืน update operator →
+  write กลับด้วย filter <code>{_id, version: current}</code> + auto bump <code>$inc: {version: 1}</code> + auto <code>$set: {updated_at: now}</code>
+</p>
+<table>
+  <tr><th>Param</th><th>Type</th><th>Description</th></tr>
+  <tr><td><code>session</code></td><td>ClientSession</td><td>session จาก <code>mongoTxn</code></td></tr>
+  <tr><td><code>collection</code></td><td>string</td><td>ชื่อ collection</td></tr>
+  <tr><td><code>id</code></td><td>string | ObjectId</td><td>_id ของ document (รองรับทั้ง string และ ObjectId)</td></tr>
+  <tr><td><code>mutate</code></td><td>(doc) =&gt; patch</td><td>ฟังก์ชัน (async ได้) รับ doc ปัจจุบันและคืน update operator <code>{ $inc, $set, ... }</code> หรือ <code>null</code> เพื่อ no-op</td></tr>
+</table>
+<span class="tag tag-return">return</span> <code>{ ...doc, version: currentVersion + 1 }</code> (in-memory, merge กับ doc ก่อน patch)
+<span class="tag tag-warn">throws</span> <code>'VERSION_CONFLICT'</code> เมื่อ doc ถูกเขียนทับไปแล้ว — <code>mongoTxn</code> จะ catch และ retry ให้อัตโนมัติ
+<span class="tag tag-warn">throws</span> <code>'[withVersion] collection/id not found'</code> เมื่อไม่เจอ doc
+<pre><code><span class="cm">// Patch แบบต่าง ๆ</span>
+<span class="cm">// 1) ตัดเงินธรรมดา</span>
+<span class="kw">await</span> <span class="kw">this</span>.<span class="fn">withVersion</span>(session, <span class="str">'account'</span>, accId, (doc) =&gt; ({
+    $inc: { balance: -<span class="num">100</span> }
+}));
+<span class="cm">// 2) ผสม $inc + $set</span>
+<span class="kw">await</span> <span class="kw">this</span>.<span class="fn">withVersion</span>(session, <span class="str">'expense'</span>, expId, (doc) =&gt; ({
+    $inc: { amount: <span class="num">50</span> },
+    $set: { status: <span class="str">'APPROVED'</span>, approved_by: userInfo.username }
+}));
+<span class="cm">// 3) Business rule check — throw ภายใน mutate ก็ได้</span>
+<span class="kw">await</span> <span class="kw">this</span>.<span class="fn">withVersion</span>(session, <span class="str">'budget'</span>, budgetId, (doc) =&gt; {
+    <span class="kw">if</span> (doc.status === <span class="str">'CLOSED'</span>) <span class="kw">throw new</span> <span class="fn">Error</span>(<span class="str">'งบปิดแล้ว'</span>);
+    <span class="kw">if</span> (doc.balance &lt; params.amount) <span class="kw">throw new</span> <span class="fn">Error</span>(<span class="str">'ยอดไม่พอ'</span>);
+    <span class="kw">return</span> { $inc: { balance: -params.amount } };
+});
+<span class="cm">// 4) Conditional no-op — return null</span>
+<span class="kw">await</span> <span class="kw">this</span>.<span class="fn">withVersion</span>(session, <span class="str">'budget'</span>, budgetId, (doc) =&gt; {
+    <span class="kw">if</span> (doc.already_processed) <span class="kw">return</span> <span class="kw">null</span>;  <span class="cm">// ไม่ทำอะไร</span>
+    <span class="kw">return</span> { $set: { already_processed: <span class="kw">true</span> } };
+});
+<span class="cm">// 5) Async mutate — await ภายในได้</span>
+<span class="kw">await</span> <span class="kw">this</span>.<span class="fn">withVersion</span>(session, <span class="str">'budget'</span>, budgetId, <span class="kw">async</span> (doc) =&gt; {
+    <span class="kw">const</span> rate = <span class="kw">await</span> <span class="kw">this</span>.<span class="fn">fetchRate</span>();
+    <span class="kw">return</span> { $inc: { balance: -params.amount * rate } };
+});</code></pre>
+<p class="desc"><strong>การป้องกันระบบ:</strong> helper ป้องกันการ override version โดยผู้ใช้:</p>
+<table>
+  <tr><th>ความพยายาม</th><th>ผลลัพธ์</th></tr>
+  <tr><td><code>$set: { version: 999 }</code></td><td>ถูกลบออก → version += 1 ปกติ</td></tr>
+  <tr><td><code>$unset: { version: 1 }</code></td><td>ถูกลบออก → version += 1 ปกติ</td></tr>
+  <tr><td><code>$inc: { version: 99 }</code></td><td>ถูก override เป็น +1</td></tr>
+  <tr><td>doc ไม่มี version field</td><td>รองรับ — filter ใช้ <code>{$or: [{version:0}, {version: {$exists: false}}]}</code></td></tr>
+</table>
+</div>
+<div class="card" id="txn-patterns">
+<h3>Pattern การใช้งานที่พบบ่อย</h3>
+<h4 style="color:#89b4fa; margin:12px 0 6px; font-size:14px;">1. Transfer เงินระหว่าง 2 accounts</h4>
+<pre><code><span class="kw">await</span> <span class="kw">this</span>.<span class="fn">mongoTxn</span>(<span class="kw">async</span> (session) =&gt; {
+    <span class="kw">await</span> <span class="kw">this</span>.<span class="fn">withVersion</span>(session, <span class="str">'account'</span>, fromId, (doc) =&gt; {
+        <span class="kw">if</span> (doc.balance &lt; amount) <span class="kw">throw new</span> <span class="fn">Error</span>(<span class="str">'Insufficient'</span>);
+        <span class="kw">return</span> { $inc: { balance: -amount } };
+    });
+    <span class="kw">await</span> <span class="kw">this</span>.<span class="fn">withVersion</span>(session, <span class="str">'account'</span>, toId, () =&gt; ({
+        $inc: { balance: amount }
+    }));
+}, { name: <span class="str">'transfer'</span> });
+<span class="cm">// ถ้า account ที่ 2 fail → account ที่ 1 rollback อัตโนมัติ</span></code></pre>
+<h4 style="color:#89b4fa; margin:12px 0 6px; font-size:14px;">2. ตัดงบ + สร้าง expense record + insert log</h4>
+<pre><code><span class="kw">const</span> result = <span class="kw">await</span> <span class="kw">this</span>.<span class="fn">mongoTxn</span>(<span class="kw">async</span> (session) =&gt; {
+    <span class="cm">// 1) ตัดงบประมาณ</span>
+    <span class="kw">await</span> <span class="kw">this</span>.<span class="fn">withVersion</span>(session, <span class="str">'zdata_budget'</span>, params.budget_id, (doc) =&gt; {
+        <span class="kw">if</span> (doc.balance &lt; params.amount) <span class="kw">throw new</span> <span class="fn">Error</span>(<span class="str">'งบไม่พอ'</span>);
+        <span class="kw">return</span> { $inc: { balance: -params.amount, expense: params.amount } };
+    });
+    <span class="cm">// 2) สร้าง expense record</span>
+    <span class="kw">const</span> expId = app.<span class="fn">dbObjectId</span>();
+    <span class="kw">await</span> app.db.<span class="fn">collection</span>(<span class="str">'zdata_expense'</span>).<span class="fn">insertOne</span>({
+        _id: expId,
+        budget_id: params.budget_id,
+        amount: params.amount,
+        status: <span class="str">'POSTED'</span>,
+        version: <span class="num">0</span>,
+        created_at: <span class="kw">new</span> <span class="fn">Date</span>(),
+        created_by: userInfo.username
+    }, { session });
+    <span class="cm">// 3) Log transaction</span>
+    <span class="kw">await</span> app.db.<span class="fn">collection</span>(<span class="str">'zdata_audit_log'</span>).<span class="fn">insertOne</span>({
+        ref_type: <span class="str">'expense'</span>,
+        ref_id: expId,
+        action: <span class="str">'CREATE'</span>,
+        amount: params.amount,
+        created_at: <span class="kw">new</span> <span class="fn">Date</span>()
+    }, { session });
+    <span class="kw">return</span> { expId };
+}, { name: <span class="str">'postExpense'</span>, maxRetry: <span class="num">5</span> });
+<span class="kw">return</span> { xformDatax: { status: <span class="str">'POSTED'</span>, expense_id: result.expId } };</code></pre>
+<h4 style="color:#89b4fa; margin:12px 0 6px; font-size:14px;">3. Approve expense (flip status + trail history)</h4>
+<pre><code><span class="kw">await</span> <span class="kw">this</span>.<span class="fn">mongoTxn</span>(<span class="kw">async</span> (session) =&gt; {
+    <span class="kw">await</span> <span class="kw">this</span>.<span class="fn">withVersion</span>(session, <span class="str">'zdata_expense'</span>, params.expId, (doc) =&gt; {
+        <span class="kw">if</span> (doc.status !== <span class="str">'PENDING'</span>) <span class="kw">throw new</span> <span class="fn">Error</span>(<span class="str">'ต้องเป็น PENDING เท่านั้น'</span>);
+        <span class="kw">return</span> {
+            $set: {
+                status: <span class="str">'APPROVED'</span>,
+                approved_by: userInfo.username,
+                approved_at: <span class="kw">new</span> <span class="fn">Date</span>()
+            }
+        };
+    });
+    <span class="kw">await</span> app.db.<span class="fn">collection</span>(<span class="str">'zdata_status_history'</span>).<span class="fn">insertOne</span>({
+        ref_id: params.expId,
+        from_status: <span class="str">'PENDING'</span>,
+        to_status: <span class="str">'APPROVED'</span>,
+        by: userInfo.username,
+        at: <span class="kw">new</span> <span class="fn">Date</span>()
+    }, { session });
+});</code></pre>
+</div>
+<div class="card" id="txn-errors">
+<h3>Error handling &amp; ข้อควรระวัง</h3>
+<h4 style="color:#f38ba8; margin:12px 0 6px; font-size:14px;">ข้อควรระวัง (Pitfalls)</h4>
+<table>
+  <tr><th>อย่าทำ</th><th>ทำแบบนี้แทน</th></tr>
+  <tr>
+    <td>เรียก <code>app.dbInsert</code> / <code>app.dbUpdate</code> ภายใน mongoTxn</td>
+    <td>ใช้ <code>app.db.collection(...).insertOne(..., { session })</code> ตรง ๆ</td>
+  </tr>
+  <tr>
+    <td>ลืมส่ง <code>{ session }</code> ให้ mongo operation</td>
+    <td>ทุก <code>insertOne/updateOne/deleteOne/find</code> ในทรานแซกชัน <strong>ต้อง</strong>มี <code>{ session }</code></td>
+  </tr>
+  <tr>
+    <td>ทำงานหนัก (loop ใหญ่ / call external API) ใน fn</td>
+    <td>แยก logic ออกมาก่อน เข้า txn แค่ส่วน write — ไม่งั้น lock ค้างนาน</td>
+  </tr>
+  <tr>
+    <td>เรียก <code>mongoTxn</code> ซ้อน (nested)</td>
+    <td>ทำในชั้นเดียว — MongoDB ไม่รองรับ nested transaction</td>
+  </tr>
+  <tr>
+    <td>Side effect (email, webhook) ภายใน fn</td>
+    <td>เก็บข้อมูลไว้ใน result แล้วยิงหลัง <code>mongoTxn</code> commit เสร็จ</td>
+  </tr>
+</table>
+<h4 style="color:#f38ba8; margin:12px 0 6px; font-size:14px;">Error ที่เจอบ่อย</h4>
+<table>
+  <tr><th>Error</th><th>สาเหตุ / วิธีแก้</th></tr>
+  <tr>
+    <td><code>Transaction conflict — please retry later</code></td>
+    <td>retry หมดแล้วยังชน → เพิ่ม <code>maxRetry</code> หรือลด contention โดยการแยก doc ออก</td>
+  </tr>
+  <tr>
+    <td><code>[withVersion] xxx not found</code></td>
+    <td>doc ไม่มีใน collection — ตรวจ id, collection name, หรือเช็คก่อนเรียก</td>
+  </tr>
+  <tr>
+    <td><code>Transaction numbers are only allowed on a replica set</code></td>
+    <td>MongoDB ไม่ใช่ replica set — ตรวจ <code>MONGODB_URL</code> ว่ามี <code>?replicaSet=rs0</code> ไหม</td>
+  </tr>
+  <tr>
+    <td><code>maxRetry must be &gt;= 1</code></td>
+    <td>ส่ง <code>maxRetry: 0</code> ไม่ได้ — ต้องอย่างน้อย 1</td>
+  </tr>
+  <tr>
+    <td><code>MongoOperationTimeoutError</code></td>
+    <td>CSOT (<code>timeoutMs</code>) หมดเวลา — ops ช้าเกิน หรือ contention สูงเกิน <strong>ไม่ถูก auto-retry</strong> เพราะเสี่ยง double-commit — ให้ตั้ง <code>timeoutMs</code> สูงขึ้น หรือลด contention</td>
+  </tr>
+</table>
+<h4 style="color:#a6e3a1; margin:12px 0 6px; font-size:14px;">เมื่อไหร่ถึงควรใช้?</h4>
+<table>
+  <tr><th>ควรใช้</th><th>ไม่จำเป็นต้องใช้</th></tr>
+  <tr>
+    <td>ตัดงบ / เบิกจ่าย / โอนเงิน</td>
+    <td>Insert บันทึกข้อมูลธรรมดา (เช่น zdata_employee)</td>
+  </tr>
+  <tr>
+    <td>Update ที่ต้องป้องกัน lost update (balance, stock)</td>
+    <td>Update audit fields (created_at, note)</td>
+  </tr>
+  <tr>
+    <td>หลายเอกสาร/หลาย collection ต้อง commit พร้อมกัน</td>
+    <td>Read-only query</td>
+  </tr>
+  <tr>
+    <td>Workflow state transition (ต้องไม่กระโดด step)</td>
+    <td>Log บันทึกเหตุการณ์ (ไม่กระทบ state อื่น)</td>
+  </tr>
+</table>
+<p class="desc" style="margin-top:12px;">
+  <span class="tag tag-warn">Stress tested</span>
+  ผ่าน 91/91 assertions รวมถึง 10,000 concurrent ops (T16) และ 1,000 ops/doc contention test (T17)
+  — run <code>npm run stress</code> เพื่อทดสอบใหม่ หรือ <code>npm run stress:quick</code> สำหรับ quick run (ข้าม 10k tests)
+</p>
+</div>
+</div>
+<!-- ============================================ -->
+<!-- xformDatax - RETURN DATA TO FORM -->
+<!-- ============================================ -->
+<div class="section" id="xformDatax">
+<h2>xformDatax — ส่งค่ากลับไปให้ฟอร์ม</h2>
+<p class="desc">
+  กลไกที่สำคัญที่สุดของ API Factory คือการ <strong>ส่งค่ากลับไปเขียนทับข้อมูลในฟอร์ม</strong> หลังจาก save
+  โดยใช้ key พิเศษ <code>xformDatax</code> ใน return ของ api_process
+</p>
+<div class="card" id="xformDatax-overview">
+<h3>วิธีการทำงาน</h3>
+<p class="desc">เมื่อฟอร์มมี <strong>Form Event</strong> ผูก API ไว้ (on: save / insert / update / delete) ระบบจะ:</p>
+<table>
+  <tr><th>ลำดับ</th><th>สิ่งที่เกิดขึ้น</th></tr>
+  <tr><td>1</td><td>User กด Save → ฟอร์มบันทึกข้อมูลลง DB ก่อน</td></tr>
+  <tr><td>2</td><td>ระบบเรียก <code>afterSaveForm()</code> → วน loop form_event ที่ตรงกับ event</td></tr>
+  <tr><td>3</td><td>แต่ละ event เรียก <code>app.subProcess(apiId, params, userInfo)</code></td></tr>
+  <tr><td>4</td><td>api_process ทำงาน → <code>return { xformDatax: { ... } }</code></td></tr>
+  <tr><td>5</td><td>ระบบเจอ key <code>xformDatax</code> → <strong>merge ข้อมูลกลับเข้า document ที่เพิ่ง save</strong></td></tr>
+  <tr><td>6</td><td>ข้อมูลถูก update ลง DB อัตโนมัติ + frontend รับค่าใหม่ไปแสดง</td></tr>
+</table>
+<pre><code><span class="cm">// โค้ดภายในระบบ (ZzEventForm.ts) — เพื่อให้เข้าใจกลไก</span>
+<span class="kw">const</span> apiOutput = <span class="kw">await</span> app.<span class="fn">subProcess</span>(processId, dataUpdate, userInfo);
+<span class="kw">if</span> (apiOutput.success) {
+    <span class="kw">if</span> (!!apiOutput.data &amp;&amp; !!apiOutput.data[<span class="str">'xformDatax'</span>]) {
+        updateData = <span class="kw">true</span>;
+        formData = { ...formData, ...apiOutput.data[<span class="str">'xformDatax'</span>] };
+    }
+}</code></pre>
+<p class="desc">สังเกตว่าระบบใช้ <code>{ ...formData, ...xformDatax }</code> คือ <strong>merge ทับ</strong> เฉพาะ field ที่ส่งมา field อื่นไม่กระทบ</p>
+</div>
+<div class="card" id="xformDatax-basic">
+<h3>ตัวอย่าง: คำนวณ BMI แล้วส่งกลับ</h3>
+<p class="desc">ฟอร์มมี field: <code>weight</code>, <code>height</code>, <code>bmi</code> — ผูก Form Event on: save → API นี้</p>
+<pre><code><span class="cm">// api_process: คำนวณ BMI แล้วเขียนกลับลง field "bmi" ของฟอร์ม</span>
+<span class="kw">const</span> weight = <span class="fn">Number</span>(params.weight);
+<span class="kw">const</span> height = <span class="fn">Number</span>(params.height);
+<span class="kw">if</span> (!weight || !height) {
+    <span class="kw">await</span> app.<span class="fn">notifySend</span>({
+        title: <span class="str">'BMI'</span>,
+        detail: <span class="str">'กรุณากรอกน้ำหนักและส่วนสูง'</span>,
+        mode: <span class="str">'target'</span>,
+        target: [userInfo.username]
+    }, userInfo);
+    <span class="kw">return</span> {};
+}
+<span class="kw">const</span> heightM = height / <span class="num">100</span>;
+<span class="kw">const</span> bmi = (weight / (heightM * heightM)).<span class="fn">toFixed</span>(<span class="num">2</span>);
+<span class="cm">// ✅ ส่งค่ากลับฟอร์ม — field "bmi" จะถูก update อัตโนมัติ</span>
+<span class="kw">return</span> { <span class="var">xformDatax</span>: { bmi: bmi } };</code></pre>
+<span class="tag tag-warn">สำคัญ</span> ชื่อ key ใน xformDatax <strong>ต้องตรงกับชื่อ field ในฟอร์มเป๊ะ</strong> — ถ้าฟอร์มตั้งชื่อ <code>detile</code> (แม้สะกดผิด) ก็ต้องใช้ <code>detile</code>
+</div>
+<div class="card" id="xformDatax-multi">
+<h3>ส่งกลับหลาย field พร้อมกัน</h3>
+<p class="desc">สามารถส่งกลับหลาย field ในครั้งเดียว ระบบจะ merge ทุก field ที่ส่งมา</p>
+<pre><code><span class="cm">// คำนวณราคารวมแล้วส่งกลับหลาย field</span>
+<span class="kw">const</span> qty = <span class="fn">Number</span>(params.quantity) || <span class="num">0</span>;
+<span class="kw">const</span> price = <span class="fn">Number</span>(params.unit_price) || <span class="num">0</span>;
+<span class="kw">const</span> subtotal = qty * price;
+<span class="kw">const</span> vat = subtotal * <span class="num">0.07</span>;
+<span class="kw">const</span> total = subtotal + vat;
+<span class="kw">return</span> {
+    <span class="var">xformDatax</span>: {
+        subtotal: subtotal,
+        vat: vat.<span class="fn">toFixed</span>(<span class="num">2</span>),
+        total: total.<span class="fn">toFixed</span>(<span class="num">2</span>),
+        last_calc: <span class="kw">new</span> <span class="fn">Date</span>().<span class="fn">toISOString</span>()
+    }
+};</code></pre>
+</div>
+<div class="card" id="xformDatax-lookup">
+<h3>ตัวอย่าง: ดึงข้อมูลจาก DB เติมกลับฟอร์ม</h3>
+<p class="desc">เช่น user เลือกรหัสพนักงาน → API ดึงชื่อ, แผนก, ตำแหน่ง มาเติมให้อัตโนมัติ</p>
+<pre><code><span class="cm">// params.emp_code มาจาก field ในฟอร์ม</span>
+<span class="kw">const</span> emp = <span class="kw">await</span> app.<span class="fn">dbFindOne</span>(
+    { emp_code: params.emp_code },
+    <span class="str">'zdata_employee'</span>
+);
+<span class="kw">if</span> (!emp.success || !emp.reply.data) {
+    <span class="kw">return</span> {};
+}
+<span class="kw">const</span> d = emp.reply.data;
+<span class="kw">return</span> {
+    <span class="var">xformDatax</span>: {
+        emp_name: d.fname + <span class="str">' '</span> + d.lname,
+        department: d.department,
+        position: d.position
+    }
+};</code></pre>
+</div>
+<div class="card" id="xformDatax-rules">
+<h3>กฎสำคัญที่ต้องจำ</h3>
+<table>
+  <tr><th>#</th><th>กฎ</th><th>รายละเอียด</th></tr>
+  <tr><td>1</td><td><strong>ชื่อ field ต้องตรง</strong></td><td>key ใน xformDatax ต้องตรงกับ field name ในฟอร์ม ตัวพิมพ์เล็ก/ใหญ่ต้องเหมือนกัน</td></tr>
+  <tr><td>2</td><td><strong>ทำงานผ่าน Form Event เท่านั้น</strong></td><td>xformDatax ทำงานเมื่อ API ถูกเรียกจาก form_event (on: save/insert/update/delete) เท่านั้น เรียก API ตรงจาก script จะไม่ merge กลับ</td></tr>
+  <tr><td>3</td><td><strong>Merge ไม่ใช่ Replace</strong></td><td>ระบบใช้ spread <code>{ ...formData, ...xformDatax }</code> ส่งเฉพาะ field ที่ต้องการ field อื่นไม่หาย</td></tr>
+  <tr><td>4</td><td><strong>return {} ถ้าไม่ต้องการ update</strong></td><td>ถ้าไม่ส่ง xformDatax กลับ ระบบจะไม่ update อะไร</td></tr>
+  <tr><td>5</td><td><strong>params = ข้อมูลฟอร์มที่เพิ่ง save</strong></td><td>params ที่ API ได้รับคือข้อมูลของ document ที่เพิ่งบันทึก รวม <code>_id</code> ด้วย</td></tr>
+  <tr><td>6</td><td><strong>ใช้ได้กับทุก event</strong></td><td>ใช้ได้ทั้ง save, insert, update, delete — ทุก event ที่มี api ผูกอยู่จะเช็ค xformDatax</td></tr>
+</table>
+<pre><code><span class="cm">// ❌ ผิด — ไม่มี xformDatax ครอบ ข้อมูลจะไม่กลับไปที่ฟอร์ม</span>
+<span class="kw">return</span> { bmi: <span class="num">25.5</span> };
+<span class="cm">// ✅ ถูก — ครอบด้วย xformDatax ข้อมูลจะถูก merge กลับ</span>
+<span class="kw">return</span> { <span class="var">xformDatax</span>: { bmi: <span class="num">25.5</span> } };
+<span class="cm">// ✅ ไม่ต้องการ update — return เปล่า</span>
+<span class="kw">return</span> {};</code></pre>
+</div>
+</div>
+<!-- ============================================ -->
+<!-- SQL & QUERY -->
+<!-- ============================================ -->
+<div class="section" id="sql-query">
+<h2>SQL & Query</h2>
+<div class="card" id="runSql">
+<h3>app.runSql()</h3>
+<div class="sig">app.runSql(type, sqlId, params, userInfo, totalEnable?, options?)</div>
+<p class="desc">เรียก SQL Factory ที่สร้างไว้ เช็คสิทธิ์อัตโนมัติ</p>
+<table>
+  <tr><th>Param</th><th>Type</th><th>Description</th></tr>
+  <tr><td><code>type</code></td><td>string</td><td>'one' | 'all'</td></tr>
+  <tr><td><code>sqlId</code></td><td>string</td><td>_id ของ SQL Factory ใน module_sql</td></tr>
+  <tr><td><code>params</code></td><td>object</td><td>พารามิเตอร์สำหรับ :paramName</td></tr>
+  <tr><td><code>totalEnable</code></td><td>boolean?</td><td>นับจำนวนทั้งหมด</td></tr>
+</table>
+<span class="tag tag-return">return</span> <code>{ success, data, model }</code>
+<span class="tag tag-warn">Note</span> return เป็น <code>result.data</code> ตรงๆ ไม่มี <code>result.reply</code>
+<pre><code><span class="cm">// ดึงหลายรายการ</span>
+<span class="kw">const</span> result = <span class="kw">await</span> app.<span class="fn">runSql</span>(
+    <span class="str">'all'</span>,
+    <span class="str">'69d793bf503ebb2a35565c47'</span>,
+    { p_code: String(params.p_code) },
+    userInfo,
+    <span class="kw">true</span>
+);
+<span class="kw">if</span> (result.success) {
+    <span class="kw">return</span> { data: result.data };
+}
+<span class="cm">// ดึง 1 รายการ</span>
+<span class="kw">const</span> one = <span class="kw">await</span> app.<span class="fn">runSql</span>(
+    <span class="str">'one'</span>, sqlId, params, userInfo
+);
+<span class="kw">if</span> (one.success) {
+    <span class="kw">return</span> { item: one.data };
+}</code></pre>
+</div>
+<div class="card" id="parsedSQL">
+<h3>app.parsedSQL()</h3>
+<div class="sig">app.parsedSQL(sql, params)</div>
+<p class="desc">แปลง SQL string เป็น MongoDB query ผ่าน @synatic/noql พร้อม inject params</p>
+<span class="tag tag-warn">Note</span> nested field ใช้ <code>`parent.child`</code> ครอบ backtick ก้อนเดียว
+<pre><code><span class="kw">const</span> nsql = app.<span class="fn">parsedSQL</span>(
+    <span class="str">"SELECT * FROM zdata_prov WHERE `p_code` = :code"</span>,
+    { code: <span class="str">'97'</span> }
+);
+<span class="cm">// nsql = { collection, type, query, projection, ... }</span></code></pre>
+</div>
+<div class="card" id="parsedProvider">
+<h3>app.parsedProvider()</h3>
+<div class="sig">app.parsedProvider(dataProvider)</div>
+<p class="desc">แปลง SdDataProvider เป็น MongoDB query + total count query</p>
+<span class="tag tag-return">return</span> <code>{ nsql, nsqlTotal, nsqlSum, sql, sqlTotal }</code>
+<pre><code><span class="kw">let</span> dp = {
+    from: <span class="str">'zdata_prov'</span>,
+    select: [<span class="str">'p_code'</span>, <span class="str">'p_name'</span>],
+    where: <span class="str">"xrstatx NOT IN(0,3)"</span>,
+    orderBy: [{ column: <span class="str">'p_name'</span>, sort: <span class="str">'ASC'</span> }]
+};
+<span class="kw">const</span> parsed = app.<span class="fn">parsedProvider</span>(dp);
+<span class="cm">// parsed.nsql = MongoDB query object</span>
+<span class="cm">// parsed.sql  = Generated SQL string</span></code></pre>
+</div>
+<div class="card" id="pgQuery">
+<h3>app.pgQuery()</h3>
+<div class="sig">app.pgQuery(sql, params?)</div>
+<p class="desc">รัน PostgreSQL query ตรง — ใช้ <code>:paramName</code> สำหรับ parameter substitution</p>
+<table>
+  <tr><th>Param</th><th>Type</th><th>Description</th></tr>
+  <tr><td><code>sql</code></td><td>string</td><td>SQL query ใช้ <code>:paramName</code> แทนค่า</td></tr>
+  <tr><td><code>params</code></td><td>object?</td><td>ค่า parameter เป็น key-value</td></tr>
+</table>
+<pre><code><span class="kw">const</span> result = <span class="kw">await</span> app.<span class="fn">pgQuery</span>(
+    <span class="str">'SELECT * FROM employees WHERE dept = :dept'</span>,
+    { dept: <span class="str">'IT'</span> }
+);
+<span class="kw">return</span> { data: result.rows };</code></pre>
+</div>
+</div>
+<!-- ============================================ -->
+<!-- WEBSOCKET & NOTIFY -->
+<!-- ============================================ -->
+<div class="section" id="ws-notify">
+<h2>WebSocket & Notify</h2>
+<div class="card" id="wsSend">
+<h3>app.wsSend()</h3>
+<div class="sig">app.wsSend(channel, clientId, username, sendData)</div>
+<p class="desc">ส่ง WebSocket message ไปยัง client ที่เชื่อมต่ออยู่</p>
+<table>
+  <tr><th>Param</th><th>Type</th><th>Description</th></tr>
+  <tr><td><code>channel</code></td><td>string</td><td>ชื่อ channel เช่น 'notify', 'gridform', 'sdform'</td></tr>
+  <tr><td><code>clientId</code></td><td>string</td><td>ID ของ client หรือ 'broadcast'</td></tr>
+  <tr><td><code>username</code></td><td>string</td><td>username ผู้ส่ง</td></tr>
+  <tr><td><code>sendData</code></td><td>object</td><td>{ data, method, keyid, target?, params? }</td></tr>
+</table>
+<pre><code><span class="cm">// broadcast อัพเดท datagrid</span>
+app.<span class="fn">wsSend</span>(<span class="str">'gridform'</span>, formId, userInfo.username, {
+    data: updatedData,
+    method: <span class="str">'update'</span>,
+    keyid: <span class="str">'_id'</span>
+});
+<span class="cm">// ส่งให้เฉพาะคน</span>
+app.<span class="fn">wsSend</span>(<span class="str">'notify'</span>, <span class="str">'broadcast'</span>, userInfo.username, {
+    data: notifyData,
+    method: <span class="str">'insert'</span>,
+    keyid: resultId,
+    target: [<span class="str">'admin'</span>]  <span class="cm">// frontend จะ filter เอง</span>
+});</code></pre>
+</div>
+<div class="card" id="notifySend">
+<h3>app.notifySend()</h3>
+<div class="sig">app.notifySend(title, message, detail, mode, type, userInfo, target?, site?, unit?, tage?)</div>
+<p class="desc">สร้าง notification + ส่งผ่าน WebSocket อัตโนมัติ เก็บใน module_notify</p>
+<table>
+  <tr><th>Param</th><th>Type</th><th>Description</th></tr>
+  <tr><td><code>mode</code></td><td>string</td><td>'broadcast' | 'target' | 'site' | 'unit'</td></tr>
+  <tr><td><code>type</code></td><td>string</td><td>'info' | 'success' | 'warning' | 'error'</td></tr>
+  <tr><td><code>target</code></td><td>string[]?</td><td>array ของ username (ใช้กับ mode target)</td></tr>
+  <tr><td><code>site</code></td><td>string[]?</td><td>array ของ site code (ใช้กับ mode site)</td></tr>
+  <tr><td><code>unit</code></td><td>string[]?</td><td>array ของ unit code (ใช้กับ mode unit)</td></tr>
+</table>
+<pre><code><span class="cm">// แจ้งเตือนทุกคน</span>
+<span class="kw">await</span> app.<span class="fn">notifySend</span>(
+    <span class="str">'ประกาศ'</span>, <span class="str">'ระบบจะปิดปรับปรุง'</span>, <span class="str">'รายละเอียด...'</span>,
+    <span class="str">'broadcast'</span>, <span class="str">'warning'</span>, userInfo
+);
+<span class="cm">// แจ้งเฉพาะคนที่กรอก</span>
+<span class="kw">await</span> app.<span class="fn">notifySend</span>(
+    <span class="str">'Error'</span>, <span class="str">'กรุณากรอกข้อมูลให้ครบ'</span>, <span class="str">''</span>,
+    <span class="str">'target'</span>, <span class="str">'error'</span>, userInfo,
+    [userInfo.username]
+);
+<span class="cm">// แจ้งตามหน่วยงาน</span>
+<span class="kw">await</span> app.<span class="fn">notifySend</span>(
+    <span class="str">'งานใหม่'</span>, <span class="str">'มีเอกสารรออนุมัติ'</span>, <span class="str">''</span>,
+    <span class="str">'unit'</span>, <span class="str">'info'</span>, userInfo,
+    <span class="kw">undefined</span>, <span class="kw">undefined</span>, [<span class="str">'00001'</span>]
+);</code></pre>
+</div>
+</div>
+<!-- ============================================ -->
+<!-- USER & ROLES -->
+<!-- ============================================ -->
+<div class="section" id="user-roles">
+<h2>User & Roles</h2>
+<div class="card" id="getUserInfo">
+<h3>app.getUserInfo()</h3>
+<div class="sig">app.getUserInfo(request)</div>
+<p class="desc">ดึงข้อมูล user จาก JWT token ใน request header</p>
+<span class="tag tag-return">return</span> <code>UserInfo { username, account, roles, site, unit }</code>
+</div>
+<div class="card" id="isRole">
+<h3>app.isRole()</h3>
+<div class="sig">app.isRole(role, roles)</div>
+<p class="desc">เช็คว่า user มี role ที่ระบุหรือไม่</p>
+<pre><code><span class="kw">if</span> (app.<span class="fn">isRole</span>(<span class="str">'editor'</span>, userInfo.roles)) {
+    <span class="cm">// user มี role editor</span>
+}</code></pre>
+</div>
+<div class="card" id="isAdmin">
+<h3>app.isAdmin() / isManager() / isSuper() / isAuth()</h3>
+<div class="sig">app.isAdmin(roles) | app.isManager(roles) | app.isSuper(roles) | app.isAuth(roles)</div>
+<p class="desc">เช็ค role ระดับต่างๆ</p>
+<pre><code>app.<span class="fn">isAuth</span>(roles)    <span class="cm">// มี role ที่ไม่ใช่ guest</span>
+app.<span class="fn">isManager</span>(roles) <span class="cm">// มี role manager, admin, หรือ super</span>
+app.<span class="fn">isAdmin</span>(roles)   <span class="cm">// มี role admin หรือ super</span>
+app.<span class="fn">isSuper</span>(roles)   <span class="cm">// มี role super เท่านั้น</span></code></pre>
+</div>
+<div class="card" id="assignRole">
+<h3>app.assignRole() / revokeRole()</h3>
+<div class="sig">app.assignRole(userId, role) | app.revokeRole(userId, role)</div>
+<p class="desc">เพิ่ม/ลบ role ของ user อัพเดททั้ง DB และ cache</p>
+<pre><code><span class="cm">// เพิ่ม role</span>
+<span class="kw">await</span> app.<span class="fn">assignRole</span>(params.user_id, <span class="str">'editor'</span>);
+<span class="cm">// ลบ role</span>
+<span class="kw">await</span> app.<span class="fn">revokeRole</span>(params.user_id, <span class="str">'editor'</span>);</code></pre>
+</div>
+</div>
+<!-- ============================================ -->
+<!-- ENCRYPTION -->
+<!-- ============================================ -->
+<div class="section" id="encryption">
+<h2>Encryption</h2>
+<div class="card" id="encode">
+<h3>app.encode() / app.decode()</h3>
+<div class="sig">app.encode(str) | app.decode(strEncrypted)</div>
+<p class="desc">RSA encrypt/decrypt string ด้วย private/public key</p>
+<pre><code><span class="kw">const</span> encrypted = app.<span class="fn">encode</span>(<span class="str">'secret data'</span>);
+<span class="kw">const</span> decrypted = app.<span class="fn">decode</span>(encrypted);</code></pre>
+</div>
+<div class="card" id="encodeObj">
+<h3>app.encodeObj() / app.decodeObj()</h3>
+<div class="sig">app.encodeObj(obj) | app.decodeObj(payload, publicKey)</div>
+<p class="desc">AES-256-CBC encrypt/decrypt object (key ถูก RSA encrypt อีกชั้น)</p>
+<span class="tag tag-return">return encodeObj</span> <code>{ key, iv, data }</code>
+<pre><code><span class="cm">// Encrypt object</span>
+<span class="kw">const</span> payload = <span class="kw">await</span> app.<span class="fn">encodeObj</span>({ secret: <span class="str">'data'</span> });
+<span class="cm">// payload = { key: "RSA encrypted AES key", iv: "hex", data: "AES encrypted" }</span>
+<span class="cm">// Decrypt object</span>
+<span class="kw">const</span> obj = app.<span class="fn">decodeObj</span>(payload, publicKey);</code></pre>
+</div>
+<div class="card" id="generateKeyPair">
+<h3>app.generateKeyPair()</h3>
+<div class="sig">app.generateKeyPair()</div>
+<p class="desc">สร้าง RSA key pair ขนาด 2048 bit</p>
+<span class="tag tag-return">return</span> <code>{ privateKey, publicKey }</code>
+</div>
+</div>
+<!-- ============================================ -->
+<!-- REPORT -->
+<!-- ============================================ -->
+<div class="section" id="report">
+<h2>Report</h2>
+<div class="card" id="wordReport">
+<h3>app.wordReport()</h3>
+<div class="sig">app.wordReport(reportData, params, userInfo, subForm?)</div>
+<p class="desc">สร้าง Word document จาก Report Factory รองรับ table, text, image, QR code</p>
+<pre><code><span class="cm">// reportData มาจาก module_report</span>
+<span class="kw">const</span> patches = <span class="kw">await</span> app.<span class="fn">wordReport</span>(
+    reportData, params, userInfo
+);
+<span class="cm">// patches = { widget_name: IPatch, ... }</span></code></pre>
+</div>
+</div>
+<!-- ============================================ -->
+<!-- UTILITIES -->
+<!-- ============================================ -->
+<div class="section" id="utilities">
+<h2>Utilities (this.*)</h2>
+<p class="desc">ฟังก์ชันที่เรียกผ่าน <code>this</code> ใน api_process</p>
+<div class="card" id="isNotNull">
+<h3>this.isNotNull() / this.isNull()</h3>
+<div class="sig">this.isNotNull(value) | this.isNull(value)</div>
+<p class="desc">เช็คว่า value เป็น null/undefined หรือไม่</p>
+<pre><code><span class="kw">if</span> (<span class="kw">this</span>.<span class="fn">isNotNull</span>(params.name)) {
+    <span class="cm">// มีค่า ไม่ใช่ null/undefined</span>
+}
+<span class="kw">if</span> (<span class="kw">this</span>.<span class="fn">isNull</span>(params.email)) {
+    <span class="cm">// เป็น null หรือ undefined</span>
+}</code></pre>
+</div>
+<div class="card" id="isEmptyStr">
+<h3>this.isEmptyStr() / this.isEmptyObj()</h3>
+<div class="sig">this.isEmptyStr(str) | this.isEmptyObj(obj)</div>
+<pre><code><span class="kw">this</span>.<span class="fn">isEmptyStr</span>(<span class="str">''</span>)       <span class="cm">// true</span>
+<span class="kw">this</span>.<span class="fn">isEmptyStr</span>(<span class="str">'  '</span>)     <span class="cm">// true (whitespace)</span>
+<span class="kw">this</span>.<span class="fn">isEmptyStr</span>(<span class="str">'hello'</span>) <span class="cm">// false</span>
+<span class="kw">this</span>.<span class="fn">isEmptyObj</span>({})       <span class="cm">// true</span>
+<span class="kw">this</span>.<span class="fn">isEmptyObj</span>({a:<span class="num">1</span>})    <span class="cm">// false</span></code></pre>
+</div>
+<div class="card" id="generateId_util">
+<h3>this.generateId() / genUidTime() / genUUID()</h3>
+<div class="sig">this.generateId() | this.genUidTime() | this.genUUID()</div>
+<pre><code><span class="kw">this</span>.<span class="fn">generateId</span>()  <span class="cm">// 58291 (random 5 digits)</span>
+<span class="kw">this</span>.<span class="fn">genUidTime</span>()  <span class="cm">// 17441234567891234 (timestamp-based)</span>
+<span class="kw">this</span>.<span class="fn">genUUID</span>()     <span class="cm">// "550e8400-e29b-41d4-a716-446655440000"</span></code></pre>
+</div>
+<div class="card" id="deepClone">
+<h3>this.deepClone()</h3>
+<div class="sig">this.deepClone(object)</div>
+<p class="desc">Deep clone object (JSON parse/stringify)</p>
+<pre><code><span class="kw">const</span> copy = <span class="kw">this</span>.<span class="fn">deepClone</span>(params);
+copy.name = <span class="str">'changed'</span>;
+<span class="cm">// params.name ไม่เปลี่ยน</span></code></pre>
+</div>
+<div class="card" id="compareHash">
+<h3>this.compareHash()</h3>
+<div class="sig">this.compareHash(hash, value)</div>
+<p class="desc">เปรียบเทียบ bcrypt hash กับ plain text</p>
+<pre><code><span class="kw">const</span> match = <span class="kw">await</span> <span class="kw">this</span>.<span class="fn">compareHash</span>(
+    user.password_hash,
+    params.password
+);
+<span class="kw">if</span> (!match) {
+    <span class="kw">return</span> { success: <span class="kw">false</span>, message: <span class="str">'รหัสผ่านไม่ถูกต้อง'</span> };
+}</code></pre>
+</div>
+<div class="card" id="objectPath">
+<h3>this.setObjectByPath() / this.getObjectByPath()</h3>
+<div class="sig">this.setObjectByPath(obj, path, value) | this.getObjectByPath(obj, path)</div>
+<p class="desc">อ่าน/เขียน nested object ด้วย dot-notation path</p>
+<pre><code><span class="kw">let</span> obj = { a: { b: { c: <span class="num">10</span> } } };
+<span class="kw">this</span>.<span class="fn">getObjectByPath</span>(obj, <span class="str">'a.b.c'</span>);     <span class="cm">// 10</span>
+<span class="kw">this</span>.<span class="fn">setObjectByPath</span>(obj, <span class="str">'a.b.c'</span>, <span class="num">20</span>); <span class="cm">// obj.a.b.c = 20</span>
+<span class="kw">this</span>.<span class="fn">setObjectByPath</span>(obj, <span class="str">'x.y'</span>, <span class="num">99</span>);   <span class="cm">// สร้าง obj.x.y = 99</span></code></pre>
+</div>
+<div class="card" id="string2Json">
+<h3>this.string2Json() / this.string2boolean()</h3>
+<div class="sig">this.string2Json(jsonStr, defaultNull?) | this.string2boolean(value)</div>
+<pre><code><span class="kw">this</span>.<span class="fn">string2Json</span>(<span class="str">'{"a":1}'</span>)     <span class="cm">// { a: 1 }</span>
+<span class="kw">this</span>.<span class="fn">string2Json</span>(<span class="str">'invalid'</span>, {}) <span class="cm">// {} (default)</span>
+<span class="kw">this</span>.<span class="fn">string2boolean</span>(<span class="str">'true'</span>)  <span class="cm">// true</span>
+<span class="kw">this</span>.<span class="fn">string2boolean</span>(<span class="str">'1'</span>)     <span class="cm">// true</span>
+<span class="kw">this</span>.<span class="fn">string2boolean</span>(<span class="str">'false'</span>) <span class="cm">// false</span></code></pre>
+</div>
+<div class="card" id="object2Path">
+<h3>this.object2Path()</h3>
+<div class="sig">this.object2Path(object)</div>
+<p class="desc">แปลง object เป็น template path สำหรับ string substitution</p>
+<pre><code><span class="kw">const</span> paths = <span class="kw">this</span>.<span class="fn">object2Path</span>({ name: <span class="str">'สมชาย'</span>, age: <span class="num">30</span> });
+<span class="cm">// { "{{name}}": "สมชาย", "{{age}}": "30" }</span></code></pre>
+</div>
+</div>
+<!-- ============================================ -->
+<!-- INTERFACES -->
+<!-- ============================================ -->
+<div class="section" id="interfaces">
+<h2>Interfaces</h2>
+<div class="card" id="SdProvider">
+<h3>SdProvider</h3>
+<pre><code>{
+    providerId: <span class="str">string</span>,      <span class="cm">// formId หรือ sqlId</span>
+    providerType: <span class="str">'FORM'</span> | <span class="str">'SQL'</span> | <span class="str">'SYS'</span>,
+    params: <span class="str">object</span>,          <span class="cm">// พารามิเตอร์</span>
+    options: {               <span class="cm">// ตัวเลือกเพิ่มเติม</span>
+        select: <span class="str">string[]</span>,
+        where: <span class="str">string</span>,
+        orderBy: [{ column: <span class="str">string</span>, sort: <span class="str">'ASC'</span>|<span class="str">'DESC'</span> }],
+        groupBy: <span class="str">string[]</span>,
+        limit: <span class="str">number</span>,
+        page: <span class="str">number</span>
+    }
+}</code></pre>
+</div>
+<div class="card" id="SdDataProvider">
+<h3>SdDataProvider</h3>
+<pre><code>{
+    from: <span class="str">string</span>,             <span class="cm">// ชื่อ collection</span>
+    select: <span class="str">string[]</span>,          <span class="cm">// field ที่ต้องการ</span>
+    where: <span class="str">string</span>,             <span class="cm">// SQL-like WHERE</span>
+    params: <span class="str">object</span>,            <span class="cm">// :paramName substitution</span>
+    search: <span class="str">string[]</span>,          <span class="cm">// field ที่ค้นหาด้วย LIKE :q</span>
+    orderBy: [{ column, sort }],
+    groupBy: <span class="str">string[]</span>,
+    join: [{
+        type: <span class="str">'INNER JOIN'</span> | <span class="str">'LEFT JOIN'</span>,
+        hint: <span class="str">''</span> | <span class="str">'FIRST'</span> | <span class="str">'LAST'</span> | <span class="str">'UNWIND'</span> | <span class="str">'OPTIMIZE'</span>,
+        table: <span class="str">string</span>,
+        on: <span class="str">string</span>
+    }],
+    limit: <span class="str">number</span>,
+    page: <span class="str">number</span>,
+    offset: <span class="str">number</span>,
+    nosql: {                  <span class="cm">// MongoDB native query</span>
+        type: <span class="str">'query'</span> | <span class="str">'aggregate'</span>,
+        collection: <span class="str">string</span>,
+        query: <span class="str">object</span>,
+        projection: <span class="str">object</span>,
+        pipeline: <span class="str">any[]</span>
+    },
+    pgSql: <span class="str">string</span>             <span class="cm">// PostgreSQL query</span>
+}</code></pre>
+</div>
+<div class="card" id="UserInfo">
+<h3>UserInfo</h3>
+<pre><code>{
+    username: <span class="str">string</span>,          <span class="cm">// "admin"</span>
+    account: {
+        id: <span class="str">ObjectId</span>,         <span class="cm">// user _id</span>
+        name: <span class="str">string</span>           <span class="cm">// "SuperAdmin InitAPI (admin@initSDK.com)"</span>
+    },
+    roles: <span class="str">string[]</span>,           <span class="cm">// ["super", "admin", "auth", "user"]</span>
+    site: {
+        code: <span class="str">string</span>,          <span class="cm">// "00000"</span>
+        name: <span class="str">string</span>           <span class="cm">// "Center"</span>
+    },
+    unit: {
+        code: <span class="str">string</span>,          <span class="cm">// "00000"</span>
+        name: <span class="str">string</span>           <span class="cm">// "Center"</span>
+    }
+}</code></pre>
+</div>
+</div>
+</main>
+<script>
+// Active sidebar link
+document.querySelectorAll('.sidebar a').forEach(link => {
+    link.addEventListener('click', () => {
+        document.querySelectorAll('.sidebar a').forEach(a => a.classList.remove('active'));
+        link.classList.add('active');
+    });
+});
+// Highlight on scroll
+const observer = new IntersectionObserver(entries => {
+    entries.forEach(entry => {
+        if (entry.isIntersecting) {
+            const id = entry.target.id;
+            document.querySelectorAll('.sidebar a').forEach(a => {
+                a.classList.toggle('active', a.getAttribute('href') === '#' + id);
+            });
+        }
+    });
+}, { rootMargin: '-20% 0px -80% 0px' });
+document.querySelectorAll('.card[id], .section[id]').forEach(el => observer.observe(el));
+</script>
+</body>
+</html>