npm - @laitszkin/apollo-toolkit - Versions diffs - 3.10.0 → 3.11.1 - Mend

@laitszkin/apollo-toolkit 3.10.0 → 3.11.1

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 (47) hide show

package/init-project-html/sample-demo/resources/project-architecture/features/get-invite-codes/invite-code-generator.html CHANGED Viewed

@@ -1,165 +1,66 @@
 <!DOCTYPE html>
-<html lang="zh-Hant">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>子模組 · invite-code-generator — 獲取邀請碼</title>
-    <link rel="preconnect" href="https://fonts.googleapis.com" />
-    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
-    <link
-      href="https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,500;600&family=Plus+Jakarta+Sans:wght@400;500;600&display=swap"
-      rel="stylesheet"
-    />
-    <link rel="stylesheet" href="../../assets/architecture.css" />
-  </head>
-  <body>
-    <main class="atlas-page atlas-page--feature">
-      <nav class="breadcrumb" aria-label="階層導航">
-        <a href="../../index.html">宏觀架構</a> · <a href="./index.html">獲取邀請碼</a> · <span>invite-code-generator</span>
-      </nav>
-      <header class="atlas-header">
-        <p class="atlas-kicker">Submodule · invite-code-generator</p>
-        <h1 class="atlas-title">invite-code-generator</h1>
-        <p class="atlas-meta">自身職責：把熵編碼成符合產品規格的可讀字串。<strong>無 I/O 副作用</strong>（除讀取隨機源）。本頁只列自身函式 I/O 與內部資料流。</p>
-      </header>
-      <section class="sub-io">
-        <h2>函式 I/O</h2>
-        <table>
-          <thead><tr><th>函式</th><th>簽名</th><th>副作用</th><th>用途</th></tr></thead>
-          <tbody>
-            <tr>
-              <td><code>NewGenerator</code></td>
-              <td class="sub-io__signature">
-                <strong>in:</strong> <code>Config{bits, alphabet, groupSize}</code><br>
-                <strong>out:</strong> <code>Generator</code>
-              </td>
-              <td><span class="sub-io__side sub-io__side--pure">pure</span></td>
-              <td>建構，驗證 <code>bits &gt;= 64</code>、字元表非空且不含易混字。</td>
-            </tr>
-            <tr>
-              <td><code>Generator.Next</code></td>
-              <td class="sub-io__signature">
-                <strong>in:</strong> —<br>
-                <strong>out:</strong> <code>string</code> | <code>ErrEntropy</code>
-              </td>
-              <td><span class="sub-io__side sub-io__side--io">io</span> 讀 <code>crypto/rand</code></td>
-              <td>單次抽碼。</td>
-            </tr>
-            <tr>
-              <td><code>encode</code></td>
-              <td class="sub-io__signature">
-                <strong>in:</strong> <code>bytes</code>, <code>alphabet</code><br>
-                <strong>out:</strong> <code>string</code>
-              </td>
-              <td><span class="sub-io__side sub-io__side--pure">pure</span></td>
-              <td>把位元組以 Crockford Base32（或同類）映射成字元。</td>
-            </tr>
-            <tr>
-              <td><code>group</code></td>
-              <td class="sub-io__signature">
-                <strong>in:</strong> <code>string</code>, <code>groupSize</code><br>
-                <strong>out:</strong> <code>string</code>
-              </td>
-              <td><span class="sub-io__side sub-io__side--pure">pure</span></td>
-              <td>每 N 位插入 <code>-</code>，便於人讀。</td>
-            </tr>
-          </tbody>
-        </table>
-      </section>
-      <section class="sub-vars">
-        <h2>變數與業務用途</h2>
-        <p class="sub-vars__intro">本子模組屬於純函式工具；下表分兩段：上半為建構時固定的設定，下半為單次 <code>Next</code> 期間的臨時值。</p>
-        <table>
-          <thead><tr><th>變數</th><th>型別</th><th>作用域</th><th>業務用途</th></tr></thead>
-          <tbody>
-            <tr>
-              <td class="sub-vars__name">Config</td>
-              <td class="sub-vars__type">{bits, alphabet, groupSize}</td>
-              <td><span class="sub-vars__scope sub-vars__scope--instance">instance</span></td>
-              <td>整個 Generator 生命週期固定；決定碼強度（bits）、可讀性（alphabet）、人讀分組（groupSize）。</td>
-            </tr>
-            <tr>
-              <td class="sub-vars__name">bits</td>
-              <td class="sub-vars__type">int</td>
-              <td><span class="sub-vars__scope sub-vars__scope--instance">instance</span></td>
-              <td>熵預算；決定隨機字串對 UNIQUE 碰撞的容忍度；過低會推高呼叫端的重試次數與失敗率。</td>
-            </tr>
-            <tr>
-              <td class="sub-vars__name">alphabet</td>
-              <td class="sub-vars__type">string</td>
-              <td><span class="sub-vars__scope sub-vars__scope--instance">instance</span></td>
-              <td>字元表；剃除 0/O、1/I/l 等易混字，業務上降低使用者抄錄錯誤率，間接提高分享成功率。</td>
-            </tr>
-            <tr>
-              <td class="sub-vars__name">groupSize</td>
-              <td class="sub-vars__type">int</td>
-              <td><span class="sub-vars__scope sub-vars__scope--instance">instance</span></td>
-              <td>每幾個字元插入連字號；只影響顯示／輸入體驗，不影響熵或唯一性。</td>
-            </tr>
-            <tr>
-              <td class="sub-vars__name">bytes / buf</td>
-              <td class="sub-vars__type">[]byte</td>
-              <td><span class="sub-vars__scope sub-vars__scope--call">call</span></td>
-              <td>從 <code>crypto/rand</code> 讀出的原始熵；只在單次 <code>Next</code> 期間活著，不持久化、不外傳，避免被推測下一次值。</td>
-            </tr>
-            <tr>
-              <td class="sub-vars__name">raw</td>
-              <td class="sub-vars__type">string</td>
-              <td><span class="sub-vars__scope sub-vars__scope--call">call</span></td>
-              <td>經 base32 編碼後尚未分組的中介字串；只是內部步驟，不對外。</td>
-            </tr>
-            <tr>
-              <td class="sub-vars__name">out / candidate</td>
-              <td class="sub-vars__type">string</td>
-              <td><span class="sub-vars__scope sub-vars__scope--call">call</span></td>
-              <td>最終回傳的候選碼；本子模組不快取、不記錄；唯一性由呼叫端結合 DB UNIQUE 保證。</td>
-            </tr>
-          </tbody>
-        </table>
-      </section>
-      <section class="sub-dataflow">
-        <h2>內部資料流（單次 Next）</h2>
-        <ol>
-          <li>從 <code>crypto/rand</code> 讀 <code>bytes[ceil(bits/8)]</code>。</li>
-          <li><code>bytes</code> → <code>encode(bytes, alphabet)</code> → <code>raw: string</code>。</li>
-          <li><code>raw</code> → <code>group(raw, groupSize)</code> → 最終字串。</li>
-          <li>內部不持有狀態（除設定）；多次呼叫互相獨立，無快取無記錄。</li>
-        </ol>
-        <svg class="sub-dataflow__svg" viewBox="0 0 720 110" role="img" aria-label="生成器資料流">
-          <defs>
-            <marker id="d-arr3" markerWidth="9" markerHeight="9" refX="8" refY="4.5" orient="auto">
-              <path d="M0,0 L9,4.5 L0,9 Z" fill="currentColor"></path>
-            </marker>
-          </defs>
-          <g class="d-node"><rect x="20" y="30" width="150" height="50" rx="8"></rect><text x="95" y="50" text-anchor="middle">crypto/rand</text><text x="95" y="68" text-anchor="middle" class="d-label">→ bytes</text></g>
-          <g class="d-node"><rect x="220" y="30" width="150" height="50" rx="8"></rect><text x="295" y="50" text-anchor="middle">encode</text><text x="295" y="68" text-anchor="middle" class="d-label">bytes → raw</text></g>
-          <g class="d-node"><rect x="420" y="30" width="150" height="50" rx="8"></rect><text x="495" y="50" text-anchor="middle">group</text><text x="495" y="68" text-anchor="middle" class="d-label">raw → 字串</text></g>
-          <g class="d-node"><rect x="600" y="30" width="100" height="50" rx="8"></rect><text x="650" y="58" text-anchor="middle">candidate</text></g>
-          <line class="d-edge" x1="170" y1="55" x2="216" y2="55" marker-end="url(#d-arr3)"></line>
-          <line class="d-edge" x1="370" y1="55" x2="416" y2="55" marker-end="url(#d-arr3)"></line>
-          <line class="d-edge" x1="570" y1="55" x2="596" y2="55" marker-end="url(#d-arr3)"></line>
-        </svg>
-      </section>
-      <section class="sub-errors">
-        <h2>本子模組會拋出的錯誤</h2>
-        <table>
-          <thead><tr><th>錯誤</th><th>條件</th></tr></thead>
-          <tbody>
-            <tr><td><code>ErrEntropy</code></td><td><code>crypto/rand.Read</code> 短讀／失敗（罕見）。</td></tr>
-            <tr><td><code>ErrConfig</code></td><td><code>NewGenerator</code> 收到非法 <code>Config</code>。</td></tr>
-          </tbody>
-        </table>
-        <p class="atlas-meta">注意：「唯一性」<strong>不在本子模組</strong>；DB UNIQUE 違例由呼叫端處理（重新呼叫 <code>Next</code>）。</p>
-      </section>
-      <footer class="atlas-meta" style="margin-top: 2rem">
-        <p><a href="../../index.html">← 宏觀架構</a> · <a href="./index.html">← 功能總覽</a></p>
-      </footer>
-    </main>
-  </body>
+<html lang="en" data-atlas-page="submodule">
+<head>
+  <meta charset="utf-8">
+  <title>Get invite codes · invite-code-generator</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <link rel="stylesheet" href="../../assets/architecture.css">
+</head>
+<body>
+  <header class="submodule-header">
+    <nav class="submodule-breadcrumb"><a href="../../index.html">← Atlas</a> · <a href="index.html">← Get invite codes</a></nav>
+    <h1>invite-code-generator <small class="submodule-kind submodule-kind--pure-fn">Pure fn</small></h1>
+    <p class="submodule-role">Pure helper that turns random bytes into a printable invite code.</p>
+  </header>
+  <main class="submodule-main">
+    <section class="sub-io" aria-label="Function I/O">
+      <h2>Function I/O</h2>
+      <table class="sub-table">
+        <thead><tr><th scope="col">Name</th><th scope="col">In</th><th scope="col">Out</th><th scope="col">Side</th><th scope="col">Purpose</th></tr></thead>
+        <tbody>
+          <tr><td>encode</td><td>bytes[8]</td><td>code</td><td>pure</td><td>Base32 encoding without padding for human-readable codes.</td></tr>
+        </tbody>
+      </table>
+    </section>
+    <section class="sub-vars" aria-label="Variables">
+      <h2>Variables</h2>
+      <p class="sub-section__empty">No variables recorded.</p>
+    </section>
+    <section class="sub-dataflow" aria-label="Internal data flow">
+      <h2>Internal data flow</h2>
+      <div class="sub-dataflow__canvas" data-pan-zoom-container>
+        <div class="sub-dataflow__toolbar" role="toolbar" aria-label="Diagram controls">
+          <button type="button" data-pan-zoom="zoom-in" aria-label="Zoom in">+</button>
+          <button type="button" data-pan-zoom="zoom-out" aria-label="Zoom out">−</button>
+          <button type="button" data-pan-zoom="fit" aria-label="Reset view">Fit</button>
+        </div>
+        <div class="sub-dataflow__viewport" data-pan-zoom-viewport>
+          <svg class="sub-dataflow__svg" data-atlas-svg="sub-dataflow" viewBox="0 0 628 252" role="img" aria-label="Internal dataflow">
+  <defs>
+    <marker id="sub-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="9" markerHeight="9" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 Z" /></marker>
+  </defs>
+  <g class="sub-dataflow__step">
+    <circle class="sub-dataflow__badge" cx="42" cy="68" r="18" />
+    <text class="sub-dataflow__badge-text" x="42" y="73" text-anchor="middle">1</text>
+    <rect class="sub-dataflow__box" x="80" y="32" width="520" height="72" rx="14" ry="14" />
+    <text class="sub-dataflow__text" x="340" y="74" text-anchor="middle">Read 8 random bytes.</text>
+  </g>
+  <line class="sub-dataflow__arrow" x1="340" y1="110" x2="340" y2="140" marker-end="url(#sub-arrow)" />
+  <g class="sub-dataflow__step">
+    <circle class="sub-dataflow__badge" cx="42" cy="184" r="18" />
+    <text class="sub-dataflow__badge-text" x="42" y="189" text-anchor="middle">2</text>
+    <rect class="sub-dataflow__box" x="80" y="148" width="520" height="72" rx="14" ry="14" />
+    <text class="sub-dataflow__text" x="340" y="190" text-anchor="middle">Base32 encode without padding.</text>
+  </g>
+</svg>
+        </div>
+      </div>
+    </section>
+    <section class="sub-errors" aria-label="Errors">
+      <h2>Errors</h2>
+      <p class="sub-section__empty">No errors recorded.</p>
+    </section>
+  </main>
+  <script src="../../assets/viewer.client.js" defer></script>
+</body>
 </html>

package/init-project-html/sample-demo/resources/project-architecture/features/get-invite-codes/invite-issuance-service.html CHANGED Viewed

@@ -1,198 +1,104 @@
 <!DOCTYPE html>
-<html lang="zh-Hant">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>子模組 · invite-issuance-service — 獲取邀請碼</title>
-    <link rel="preconnect" href="https://fonts.googleapis.com" />
-    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
-    <link
-      href="https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,500;600&family=Plus+Jakarta+Sans:wght@400;500;600&display=swap"
-      rel="stylesheet"
-    />
-    <link rel="stylesheet" href="../../assets/architecture.css" />
-  </head>
-  <body>
-    <main class="atlas-page atlas-page--feature">
-      <nav class="breadcrumb" aria-label="階層導航">
-        <a href="../../index.html">宏觀架構</a> · <a href="./index.html">獲取邀請碼</a> · <span>invite-issuance-service</span>
-      </nav>
-      <header class="atlas-header">
-        <p class="atlas-kicker">Submodule · invite-issuance-service</p>
-        <h1 class="atlas-title">invite-issuance-service</h1>
-        <p class="atlas-meta">自身職責：在同一交易內判斷使用者額度、組裝待寫入列、處理 UNIQUE 碰撞重試。本頁只列自身函式 I/O 與內部資料流。</p>
-      </header>
-      <section class="sub-io">
-        <h2>函式 I/O</h2>
-        <table>
-          <thead><tr><th>函式</th><th>簽名</th><th>副作用</th><th>用途</th></tr></thead>
-          <tbody>
-            <tr>
-              <td><code>IssueInviteCode</code></td>
-              <td class="sub-io__signature">
-                <strong>in:</strong> <code>ctx</code>, <code>userID</code><br>
-                <strong>out:</strong> <code>InviteCodeRecord</code> | <code>error</code>
-              </td>
-              <td><span class="sub-io__side sub-io__side--io">tx</span> 開／關交易<br><span class="sub-io__side sub-io__side--write">db</span> 條件成立時寫入新行</td>
-              <td>對外唯一入口。</td>
-            </tr>
-            <tr>
-              <td><code>checkQuota</code></td>
-              <td class="sub-io__signature">
-                <strong>in:</strong> <code>used</code>, <code>limit</code>, <code>userStatus</code><br>
-                <strong>out:</strong> <code>true | ErrQuotaExceeded | ErrForbidden</code>
-              </td>
-              <td><span class="sub-io__side sub-io__side--pure">pure</span></td>
-              <td>窗口計數 + 帳號狀態合法性判斷。</td>
-            </tr>
-            <tr>
-              <td><code>buildRecord</code></td>
-              <td class="sub-io__signature">
-                <strong>in:</strong> <code>userID</code>, <code>code: string</code>, <code>now</code><br>
-                <strong>out:</strong> <code>InviteCodeRecord</code>
-              </td>
-              <td><span class="sub-io__side sub-io__side--pure">pure</span></td>
-              <td>組裝待寫入承載：<code>owner_user_id</code>、<code>allowed_registration=true</code>、<code>created_at=now</code>。</td>
-            </tr>
-            <tr>
-              <td><code>shouldRetryOnCollision</code></td>
-              <td class="sub-io__signature">
-                <strong>in:</strong> <code>err</code>, <code>attempt: int</code>, <code>max: int</code><br>
-                <strong>out:</strong> <code>bool</code>
-              </td>
-              <td><span class="sub-io__side sub-io__side--pure">pure</span></td>
-              <td><code>err</code> 為 UNIQUE 違例且 <code>attempt &lt; max</code> 才回 <code>true</code>。</td>
-            </tr>
-          </tbody>
-        </table>
-      </section>
-      <section class="sub-vars">
-        <h2>變數與業務用途</h2>
-        <p class="sub-vars__intro">本表盤點額度判定、寫入承載組裝、與 UNIQUE 碰撞重試所依賴的識別子。</p>
-        <table>
-          <thead><tr><th>變數</th><th>型別</th><th>作用域</th><th>業務用途</th></tr></thead>
-          <tbody>
-            <tr>
-              <td class="sub-vars__name">ctx</td>
-              <td class="sub-vars__type">context.Context</td>
-              <td><span class="sub-vars__scope sub-vars__scope--call">call</span></td>
-              <td>限制整次發放的時間預算；避免重試迴圈無限延長導致連線資源被吃光。</td>
-            </tr>
-            <tr>
-              <td class="sub-vars__name">userID</td>
-              <td class="sub-vars__type">UUID</td>
-              <td><span class="sub-vars__scope sub-vars__scope--call">call</span></td>
-              <td>本次發放歸屬；同時也是額度視窗的主鍵；由 <code>public-api</code> 從可信來源（Principal）注入。</td>
-            </tr>
-            <tr>
-              <td class="sub-vars__name">tx</td>
-              <td class="sub-vars__type">*sql.Tx</td>
-              <td><span class="sub-vars__scope sub-vars__scope--tx">tx</span></td>
-              <td>把「額度檢查 + 帳號狀態檢查 + 寫入」綁成原子單元；避免在檢查與寫入之間出現空隙造成雙倍超發。</td>
-            </tr>
-            <tr>
-              <td class="sub-vars__name">used</td>
-              <td class="sub-vars__type">int64</td>
-              <td><span class="sub-vars__scope sub-vars__scope--call">call</span></td>
-              <td>當前滑動視窗已發放數；額度判定的「左值」；錯算即可能放行超額或誤拒。</td>
-            </tr>
-            <tr>
-              <td class="sub-vars__name">limit</td>
-              <td class="sub-vars__type">int</td>
-              <td><span class="sub-vars__scope sub-vars__scope--instance">instance</span></td>
-              <td>滑動視窗額度上限；產品設定，跨呼叫不變；改值代表產品策略改變，需配套更新文案。</td>
-            </tr>
-            <tr>
-              <td class="sub-vars__name">userStatus</td>
-              <td class="sub-vars__type">active | banned | suspended</td>
-              <td><span class="sub-vars__scope sub-vars__scope--call">call</span></td>
-              <td>帳號是否處於可發放狀態；停權或暫停狀態下立即拒絕，不浪費 generator/DB 資源。</td>
-            </tr>
-            <tr>
-              <td class="sub-vars__name">now</td>
-              <td class="sub-vars__type">time.Time</td>
-              <td><span class="sub-vars__scope sub-vars__scope--call">call</span></td>
-              <td>滑動視窗起點計算與 <code>created_at</code> 的基準；測試可注入。</td>
-            </tr>
-            <tr>
-              <td class="sub-vars__name">attempt</td>
-              <td class="sub-vars__type">int</td>
-              <td><span class="sub-vars__scope sub-vars__scope--loop">loop</span></td>
-              <td>UNIQUE 碰撞重試計數；搭配 <code>max</code> 限制最壞情況避免無限循環。</td>
-            </tr>
-            <tr>
-              <td class="sub-vars__name">max</td>
-              <td class="sub-vars__type">int</td>
-              <td><span class="sub-vars__scope sub-vars__scope--instance">instance</span></td>
-              <td>重試上限；超出即拋 <code>ErrCollisionExhausted</code>；上限與 generator 的熵預算共同決定罕見失敗率。</td>
-            </tr>
-            <tr>
-              <td class="sub-vars__name">candidate</td>
-              <td class="sub-vars__type">string</td>
-              <td><span class="sub-vars__scope sub-vars__scope--loop">loop</span></td>
-              <td>一輪重試取得的候選碼；尚未確定唯一；UNIQUE 違例即丟棄並重抽，不會被使用者看到。</td>
-            </tr>
-            <tr>
-              <td class="sub-vars__name">InviteCodeRecord</td>
-              <td class="sub-vars__type">{code, owner_user_id, allowed_registration, created_at}</td>
-              <td><span class="sub-vars__scope sub-vars__scope--loop">loop</span></td>
-              <td>寫入 DB 的承載；<code>allowed_registration=true</code> 是「邀請碼註冊」功能消費的關鍵旗標——關閉此值代表暫停發放但保留歷史紀錄。</td>
-            </tr>
-          </tbody>
-        </table>
-      </section>
-      <section class="sub-dataflow">
-        <h2>內部資料流</h2>
-        <ol>
-          <li>取得 <code>userID</code> + 開 <code>tx</code> → 讀<code>{used, userStatus}</code>（透過 DB 子模組；其 SQL 介面見宏觀圖邊 <code>e-B-...</code>）。</li>
-          <li><code>checkQuota</code> 不通過 → 拋 <code>ErrQuotaExceeded</code>／<code>ErrForbidden</code>；本函式直接結束（呼叫端負責回滾）。</li>
-          <li><code>candidate</code> ← 生成器產出的字串。</li>
-          <li><code>buildRecord(userID, candidate, now)</code> → <code>InviteCodeRecord</code>。</li>
-          <li>嘗試寫入；若 <code>err</code> 與 <code>shouldRetryOnCollision(err, attempt, max)</code> 為 <code>true</code>，<code>attempt+=1</code>，回到步驟 3。</li>
-          <li>寫入成功 → 提交 → 回傳 <code>InviteCodeRecord</code>。</li>
-        </ol>
-        <svg class="sub-dataflow__svg" viewBox="0 0 720 220" role="img" aria-label="內部資料流">
-          <defs>
-            <marker id="d-arr2" markerWidth="9" markerHeight="9" refX="8" refY="4.5" orient="auto">
-              <path d="M0,0 L9,4.5 L0,9 Z" fill="currentColor"></path>
-            </marker>
-          </defs>
-          <g class="d-node"><rect x="20" y="30" width="150" height="50" rx="8"></rect><text x="95" y="58" text-anchor="middle">userID</text></g>
-          <g class="d-node"><rect x="200" y="30" width="150" height="50" rx="8"></rect><text x="275" y="50" text-anchor="middle">checkQuota</text><text x="275" y="68" text-anchor="middle" class="d-label">→ true | err</text></g>
-          <g class="d-node"><rect x="380" y="30" width="170" height="50" rx="8"></rect><text x="465" y="50" text-anchor="middle">candidate</text><text x="465" y="68" text-anchor="middle" class="d-label">← Generator.Next()</text></g>
-          <g class="d-node"><rect x="580" y="30" width="120" height="50" rx="8"></rect><text x="640" y="58" text-anchor="middle">buildRecord</text></g>
-          <g class="d-node"><rect x="380" y="140" width="170" height="50" rx="8"></rect><text x="465" y="160" text-anchor="middle">shouldRetryOnCollision</text><text x="465" y="178" text-anchor="middle" class="d-label">err+attempt → bool</text></g>
-          <g class="d-node"><rect x="580" y="140" width="120" height="50" rx="8"></rect><text x="640" y="168" text-anchor="middle">InviteCodeRecord</text></g>
-          <line class="d-edge" x1="170" y1="55" x2="196" y2="55" marker-end="url(#d-arr2)"></line>
-          <line class="d-edge" x1="350" y1="55" x2="376" y2="55" marker-end="url(#d-arr2)"></line>
-          <line class="d-edge" x1="550" y1="55" x2="576" y2="55" marker-end="url(#d-arr2)"></line>
-          <line class="d-edge" x1="640" y1="80" x2="640" y2="136" marker-end="url(#d-arr2)"></line>
-          <line class="d-edge d-edge--side" x1="465" y1="190" x2="465" y2="80" marker-end="url(#d-arr2)"></line>
-        </svg>
-      </section>
-      <section class="sub-errors">
-        <h2>本子模組會拋出的錯誤</h2>
-        <table>
-          <thead><tr><th>錯誤</th><th>條件</th></tr></thead>
-          <tbody>
-            <tr><td><code>ErrQuotaExceeded</code></td><td><code>checkQuota</code> 失敗（含 <code>retryAfter</code>）</td></tr>
-            <tr><td><code>ErrForbidden</code></td><td>帳號停用</td></tr>
-            <tr><td><code>ErrCollisionExhausted</code></td><td>重試次數用盡；極罕見，視熵設計。</td></tr>
-            <tr><td><code>ErrTransient</code></td><td>連線中斷／<code>ctx</code> 取消</td></tr>
-          </tbody>
-        </table>
-      </section>
-      <footer class="atlas-meta" style="margin-top: 2rem">
-        <p><a href="../../index.html">← 宏觀架構</a> · <a href="./index.html">← 功能總覽</a></p>
-      </footer>
-    </main>
-  </body>
+<html lang="en" data-atlas-page="submodule">
+<head>
+  <meta charset="utf-8">
+  <title>Get invite codes · invite-issuance-service</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <link rel="stylesheet" href="../../assets/architecture.css">
+</head>
+<body>
+  <header class="submodule-header">
+    <nav class="submodule-breadcrumb"><a href="../../index.html">← Atlas</a> · <a href="index.html">← Get invite codes</a></nav>
+    <h1>invite-issuance-service <small class="submodule-kind submodule-kind--service">Service</small></h1>
+    <p class="submodule-role">Domain service that mints and persists a single invite row per request.</p>
+  </header>
+  <main class="submodule-main">
+    <section class="sub-io" aria-label="Function I/O">
+      <h2>Function I/O</h2>
+      <table class="sub-table">
+        <thead><tr><th scope="col">Name</th><th scope="col">In</th><th scope="col">Out</th><th scope="col">Side</th><th scope="col">Purpose</th></tr></thead>
+        <tbody>
+          <tr><td>Issue</td><td>ctx, userId</td><td>InviteCode | error</td><td>tx</td><td>Generates a unique code and writes the matching invite_codes row.</td></tr>
+          <tr><td>generateCode</td><td>rand</td><td>code</td><td>pure</td><td>Produces a 10-char alphanumeric token.</td></tr>
+        </tbody>
+      </table>
+    </section>
+    <section class="sub-vars" aria-label="Variables">
+      <h2>Variables</h2>
+      <table class="sub-table">
+        <thead><tr><th scope="col">Name</th><th scope="col">Type</th><th scope="col">Scope</th><th scope="col">Purpose</th></tr></thead>
+        <tbody>
+          <tr><td>code</td><td>string</td><td>tx</td><td>Newly minted invite token recorded against the member.</td></tr>
+          <tr><td>row</td><td>InviteCodeRow</td><td>tx</td><td>Persisted invite_codes row carrying owner, code, expiry, and consumption state.</td></tr>
+        </tbody>
+      </table>
+    </section>
+    <section class="sub-dataflow" aria-label="Internal data flow">
+      <h2>Internal data flow</h2>
+      <div class="sub-dataflow__canvas" data-pan-zoom-container>
+        <div class="sub-dataflow__toolbar" role="toolbar" aria-label="Diagram controls">
+          <button type="button" data-pan-zoom="zoom-in" aria-label="Zoom in">+</button>
+          <button type="button" data-pan-zoom="zoom-out" aria-label="Zoom out">−</button>
+          <button type="button" data-pan-zoom="fit" aria-label="Reset view">Fit</button>
+        </div>
+        <div class="sub-dataflow__viewport" data-pan-zoom-viewport>
+          <svg class="sub-dataflow__svg" data-atlas-svg="sub-dataflow" viewBox="0 0 628 626" role="img" aria-label="Internal dataflow">
+  <defs>
+    <marker id="sub-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="9" markerHeight="9" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 Z" /></marker>
+  </defs>
+  <g class="sub-dataflow__step">
+    <circle class="sub-dataflow__badge" cx="42" cy="76" r="18" />
+    <text class="sub-dataflow__badge-text" x="42" y="81" text-anchor="middle">1</text>
+    <rect class="sub-dataflow__box" x="80" y="32" width="520" height="88" rx="14" ry="14" />
+    <rect class="sub-dataflow__fn-bg" x="94" y="46" width="79.2" height="20" rx="10" ry="10" />
+    <text class="sub-dataflow__fn-text" x="104" y="60">fn Issue</text>
+    <text class="sub-dataflow__text" x="340" y="98" text-anchor="middle">Open transaction.</text>
+  </g>
+  <line class="sub-dataflow__arrow" x1="340" y1="126" x2="340" y2="156" marker-end="url(#sub-arrow)" />
+  <g class="sub-dataflow__step">
+    <circle class="sub-dataflow__badge" cx="42" cy="221" r="18" />
+    <text class="sub-dataflow__badge-text" x="42" y="226" text-anchor="middle">2</text>
+    <rect class="sub-dataflow__box" x="80" y="164" width="520" height="114" rx="14" ry="14" />
+    <rect class="sub-dataflow__fn-bg" x="94" y="178" width="131" height="20" rx="10" ry="10" />
+    <text class="sub-dataflow__fn-text" x="104" y="192">fn generateCode</text>
+    <text class="sub-dataflow__text" x="340" y="230" text-anchor="middle">Build candidate code from random bytes.</text>
+    <text class="sub-dataflow__chip sub-dataflow__chip--writes" x="586" y="266" text-anchor="end">→ writes: code</text>
+  </g>
+  <line class="sub-dataflow__arrow" x1="340" y1="284" x2="340" y2="314" marker-end="url(#sub-arrow)" />
+  <g class="sub-dataflow__step">
+    <circle class="sub-dataflow__badge" cx="42" cy="379" r="18" />
+    <text class="sub-dataflow__badge-text" x="42" y="384" text-anchor="middle">3</text>
+    <rect class="sub-dataflow__box" x="80" y="322" width="520" height="114" rx="14" ry="14" />
+    <rect class="sub-dataflow__fn-bg" x="94" y="336" width="79.2" height="20" rx="10" ry="10" />
+    <text class="sub-dataflow__fn-text" x="104" y="350">fn Issue</text>
+    <text class="sub-dataflow__text" x="340" y="388" text-anchor="middle">Persist row via INSERT (retry on unique-violation).</text>
+    <text class="sub-dataflow__chip sub-dataflow__chip--reads" x="94" y="424">← reads: code</text>
+    <text class="sub-dataflow__chip sub-dataflow__chip--writes" x="586" y="424" text-anchor="end">→ writes: row</text>
+  </g>
+  <line class="sub-dataflow__arrow" x1="340" y1="442" x2="340" y2="472" marker-end="url(#sub-arrow)" />
+  <g class="sub-dataflow__step">
+    <circle class="sub-dataflow__badge" cx="42" cy="537" r="18" />
+    <text class="sub-dataflow__badge-text" x="42" y="542" text-anchor="middle">4</text>
+    <rect class="sub-dataflow__box" x="80" y="480" width="520" height="114" rx="14" ry="14" />
+    <rect class="sub-dataflow__fn-bg" x="94" y="494" width="79.2" height="20" rx="10" ry="10" />
+    <text class="sub-dataflow__fn-text" x="104" y="508">fn Issue</text>
+    <text class="sub-dataflow__text" x="340" y="546" text-anchor="middle">Commit transaction and return code to caller.</text>
+    <text class="sub-dataflow__chip sub-dataflow__chip--reads" x="94" y="582">← reads: code, row</text>
+  </g>
+</svg>
+        </div>
+      </div>
+    </section>
+    <section class="sub-errors" aria-label="Errors">
+      <h2>Errors</h2>
+      <table class="sub-table">
+        <thead><tr><th scope="col">Name</th><th scope="col">When</th><th scope="col">Means</th></tr></thead>
+        <tbody>
+          <tr><td>ErrCollision</td><td>Unique constraint on code repeatedly violated.</td><td>Surface 503 after retry budget exhausted.</td></tr>
+        </tbody>
+      </table>
+    </section>
+  </main>
+  <script src="../../assets/viewer.client.js" defer></script>
+</body>
 </html>