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

@laitszkin/apollo-toolkit 3.9.7 → 3.10.0

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

package/init-project-html/sample-demo/resources/project-architecture/features/get-invite-codes/public-api.html ADDED Viewed

@@ -0,0 +1,152 @@
+<!DOCTYPE html>
+<html lang="zh-Hant">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>子模組 · public-api — 獲取邀請碼</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>public-api</span>
+      </nav>
+      <header class="atlas-header">
+        <p class="atlas-kicker">Submodule · public-api</p>
+        <h1 class="atlas-title">public-api（iss）</h1>
+        <p class="atlas-meta">自身職責：HTTP 邊界：認證解析、輸入綁定、把網域結果映射為狀態碼。</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>AuthMiddleware</code></td>
+              <td class="sub-io__signature">
+                <strong>in:</strong> <code>http.Request</code><br>
+                <strong>out:</strong> <code>Principal</code> | <code>401</code>
+              </td>
+              <td><span class="sub-io__side sub-io__side--io">io</span> 解 cookie / JWT</td>
+              <td>驗證並注入 <code>Principal.UserID</code>。</td>
+            </tr>
+            <tr>
+              <td><code>CreateInviteCodeHandler</code></td>
+              <td class="sub-io__signature">
+                <strong>in:</strong> <code>http.Request</code>, <code>Principal</code><br>
+                <strong>out:</strong> <code>http.Response</code>
+              </td>
+              <td><span class="sub-io__side sub-io__side--io">io</span> 寫 body</td>
+              <td>路由綁定的對外入口。</td>
+            </tr>
+            <tr>
+              <td><code>mapDomainError</code></td>
+              <td class="sub-io__signature">
+                <strong>in:</strong> <code>error</code><br>
+                <strong>out:</strong> <code>(httpStatus, ErrorBody)</code>
+              </td>
+              <td><span class="sub-io__side sub-io__side--pure">pure</span></td>
+              <td>quota → 429（含 <code>Retry-After</code>）等對映。</td>
+            </tr>
+            <tr>
+              <td><code>writeCreated</code></td>
+              <td class="sub-io__signature">
+                <strong>in:</strong> <code>NewCode</code>, <code>http.ResponseWriter</code><br>
+                <strong>out:</strong> —
+              </td>
+              <td><span class="sub-io__side sub-io__side--write">io</span> 寫 201 body</td>
+              <td>序列化新碼 + metadata。</td>
+            </tr>
+          </tbody>
+        </table>
+      </section>
+      <section class="sub-vars">
+        <h2>變數與業務用途</h2>
+        <p class="sub-vars__intro">HTTP 邊界子模組持有的識別子；本子模組的責任是「正確識別調用者」與「正確翻譯網域結果為協議語意」。</p>
+        <table>
+          <thead><tr><th>變數</th><th>型別</th><th>作用域</th><th>業務用途</th></tr></thead>
+          <tbody>
+            <tr>
+              <td class="sub-vars__name">http.Request</td>
+              <td class="sub-vars__type">request</td>
+              <td><span class="sub-vars__scope sub-vars__scope--call">call</span></td>
+              <td>邊界輸入；只在 handler 期間有效。</td>
+            </tr>
+            <tr>
+              <td class="sub-vars__name">Principal.UserID</td>
+              <td class="sub-vars__type">UUID</td>
+              <td><span class="sub-vars__scope sub-vars__scope--call">call</span></td>
+              <td>由 middleware 注入；業務上代表「為誰生成邀請碼」；<strong>禁止</strong>從 body 取以避免使用者冒名為他人發碼。</td>
+            </tr>
+            <tr>
+              <td class="sub-vars__name">httpStatus</td>
+              <td class="sub-vars__type">int</td>
+              <td><span class="sub-vars__scope sub-vars__scope--call">call</span></td>
+              <td><code>mapDomainError</code> 的輸出之一；<code>ErrQuotaExceeded</code> 必須對映成 <code>429</code> 才能搭配 <code>Retry-After</code> 讓 UI 知道是節流。</td>
+            </tr>
+            <tr>
+              <td class="sub-vars__name">ErrorBody</td>
+              <td class="sub-vars__type">{code, message}</td>
+              <td><span class="sub-vars__scope sub-vars__scope--call">call</span></td>
+              <td>結構化錯誤體；<code>code</code> 給 UI 對映本地化文字（例如「今日額度用盡」）。</td>
+            </tr>
+            <tr>
+              <td class="sub-vars__name">Retry-After</td>
+              <td class="sub-vars__type">int seconds</td>
+              <td><span class="sub-vars__scope sub-vars__scope--call">call</span></td>
+              <td>節流提示 header；UI 透過它倒數禁用按鈕，避免使用者反覆 429。</td>
+            </tr>
+            <tr>
+              <td class="sub-vars__name">NewCode</td>
+              <td class="sub-vars__type">string</td>
+              <td><span class="sub-vars__scope sub-vars__scope--call">call</span></td>
+              <td>網域回傳的新碼；序列化為 201 body 給使用者複製分享。</td>
+            </tr>
+            <tr>
+              <td class="sub-vars__name">http.ResponseWriter</td>
+              <td class="sub-vars__type">writer</td>
+              <td><span class="sub-vars__scope sub-vars__scope--call">call</span></td>
+              <td>對外副作用通道；保證一次回應只寫一次。</td>
+            </tr>
+          </tbody>
+        </table>
+      </section>
+      <section class="sub-dataflow">
+        <h2>內部資料流</h2>
+        <ol>
+          <li><code>Request</code> → <code>AuthMiddleware</code> → 注入 <code>Principal{UserID}</code>，失敗即 <code>401</code>。</li>
+          <li><code>Principal.UserID</code> 作為網域層輸入；本子模組不持有 token 明文。</li>
+          <li>從網域層取得 <code>NewCode | error</code>。</li>
+          <li><code>NewCode</code> → <code>writeCreated</code>；<code>error</code> → <code>mapDomainError</code>。</li>
+        </ol>
+      </section>
+      <section class="sub-errors">
+        <h2>HTTP 對映</h2>
+        <table>
+          <thead><tr><th>條件</th><th>HTTP</th></tr></thead>
+          <tbody>
+            <tr><td>無 session</td><td><code>401</code></td></tr>
+            <tr><td>網域 <code>ErrQuotaExceeded</code></td><td><code>429</code> + <code>Retry-After</code></td></tr>
+            <tr><td>網域 <code>ErrForbidden</code></td><td><code>403</code></td></tr>
+            <tr><td>網域 <code>ErrTransient</code></td><td><code>503</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>

package/init-project-html/sample-demo/resources/project-architecture/features/get-invite-codes/web-get-invite-ui.html ADDED Viewed

@@ -0,0 +1,140 @@
+<!DOCTYPE html>
+<html lang="zh-Hant">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>子模組 · web-get-invite-ui — 獲取邀請碼</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>web-get-invite-ui</span>
+      </nav>
+      <header class="atlas-header">
+        <p class="atlas-kicker">Submodule · web-get-invite-ui</p>
+        <h1 class="atlas-title">web-get-invite-ui</h1>
+        <p class="atlas-meta">自身職責：登入後顯示「我的邀請碼」、列表載入、生成按鈕。本頁只談自身函式 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>useInviteCodes()</code></td>
+              <td class="sub-io__signature">
+                <strong>in:</strong> —<br>
+                <strong>out:</strong> <code>{list, isLoading, refresh}</code>
+              </td>
+              <td><span class="sub-io__side sub-io__side--io">network</span> GET 已發放碼</td>
+              <td>查詢鍵／快取列表。</td>
+            </tr>
+            <tr>
+              <td><code>createInviteCode</code></td>
+              <td class="sub-io__signature">
+                <strong>in:</strong> —<br>
+                <strong>out:</strong> <code>Result&lt;NewCode, UiError&gt;</code>
+              </td>
+              <td><span class="sub-io__side sub-io__side--io">network</span> POST</td>
+              <td>把伺服器產生的新碼樂觀 prepend 到列表。</td>
+            </tr>
+            <tr>
+              <td><code>copyCodeToClipboard</code></td>
+              <td class="sub-io__signature">
+                <strong>in:</strong> <code>code: string</code><br>
+                <strong>out:</strong> <code>void</code>
+              </td>
+              <td><span class="sub-io__side sub-io__side--io">browser</span> clipboard API</td>
+              <td>使用者點復制。</td>
+            </tr>
+            <tr>
+              <td><code>formatQuotaError</code></td>
+              <td class="sub-io__signature">
+                <strong>in:</strong> <code>RetryAfter | null</code><br>
+                <strong>out:</strong> <code>UiMessage</code>
+              </td>
+              <td><span class="sub-io__side sub-io__side--pure">pure</span></td>
+              <td>把 429 訊息翻成本地文字。</td>
+            </tr>
+          </tbody>
+        </table>
+      </section>
+      <section class="sub-vars">
+        <h2>變數與業務用途</h2>
+        <p class="sub-vars__intro">本子模組以前端組件狀態為主；下表為決定使用者體驗的識別子。</p>
+        <table>
+          <thead><tr><th>變數</th><th>型別</th><th>作用域</th><th>業務用途</th></tr></thead>
+          <tbody>
+            <tr>
+              <td class="sub-vars__name">list</td>
+              <td class="sub-vars__type">InviteCode[]</td>
+              <td><span class="sub-vars__scope sub-vars__scope--instance">instance</span></td>
+              <td>使用者已發放的邀請碼清單；驅動畫面呈現與「複製」按鈕可用性；保留順序讓使用者能識別最近一次取得的碼。</td>
+            </tr>
+            <tr>
+              <td class="sub-vars__name">isLoading</td>
+              <td class="sub-vars__type">boolean</td>
+              <td><span class="sub-vars__scope sub-vars__scope--instance">instance</span></td>
+              <td>生成 API 進行中旗標；防止連按重複生成造成額度被無意義消耗。</td>
+            </tr>
+            <tr>
+              <td class="sub-vars__name">retryAfter</td>
+              <td class="sub-vars__type">number seconds | null</td>
+              <td><span class="sub-vars__scope sub-vars__scope--instance">instance</span></td>
+              <td>後端 429 帶回的下次可生成時間；按鈕禁用倒數的依據，業務上提示使用者「節流而非系統故障」。</td>
+            </tr>
+            <tr>
+              <td class="sub-vars__name">Result</td>
+              <td class="sub-vars__type">{ok: NewCode} | {err: UiError}</td>
+              <td><span class="sub-vars__scope sub-vars__scope--call">call</span></td>
+              <td>一次「生成」呼叫結果；驅動是否要把新碼樂觀插入 <code>list</code>，或顯示錯誤 banner。</td>
+            </tr>
+            <tr>
+              <td class="sub-vars__name">UiMessage</td>
+              <td class="sub-vars__type">{lang_tag, text}</td>
+              <td><span class="sub-vars__scope sub-vars__scope--call">call</span></td>
+              <td>額度／網路錯誤的本地化呈現；使用者透過此訊息知道是自己的額度問題還是系統暫時不可用。</td>
+            </tr>
+          </tbody>
+        </table>
+      </section>
+      <section class="sub-dataflow">
+        <h2>內部資料流</h2>
+        <ol>
+          <li>頁面掛載 → <code>useInviteCodes</code> 取得 <code>list</code> 顯示。</li>
+          <li>使用者點生成 → <code>createInviteCode</code>：UI <code>idle → loading</code>。</li>
+          <li><code>Result.ok</code> → 把 <code>NewCode</code> prepend 到 <code>list</code>（保持其餘元素穩定）。</li>
+          <li><code>Result.err</code> 為 quota → <code>formatQuotaError</code> 顯示 <code>UiMessage</code>，<code>list</code> 不變。</li>
+          <li>使用者選擇 <code>copyCodeToClipboard(code)</code>，不影響資料模型。</li>
+        </ol>
+      </section>
+      <section class="sub-errors">
+        <h2>本子模組可暴露的錯誤</h2>
+        <table>
+          <thead><tr><th>來源</th><th>UI 行為</th></tr></thead>
+          <tbody>
+            <tr><td>未登入（401）</td><td>路由守衛攔截 → 導向登入；本子模組不顯示業務錯誤。</td></tr>
+            <tr><td>quota（429）</td><td><code>formatQuotaError</code> banner；按鈕短暫禁用至 <code>retryAfter</code>。</td></tr>
+            <tr><td>網路錯誤</td><td>泛用提示；可重試。</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>

package/init-project-html/sample-demo/resources/project-architecture/features/invite-code-registration/index.html ADDED Viewed

@@ -0,0 +1,53 @@
+<!DOCTYPE html>
+<html lang="zh-Hant">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>邀請碼註冊 — 功能模組總覽</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> · <span>邀請碼註冊（功能模組）</span>
+      </nav>
+      <header class="atlas-header">
+        <p class="atlas-kicker">Feature module · invite-code-registration</p>
+        <h1 class="atlas-title">邀請碼註冊</h1>
+        <p class="atlas-meta">對外能力：訪客憑邀請碼建立帳號（消費邀請碼）。</p>
+      </header>
+      <section class="feature-story">
+        <h2>使用者故事</h2>
+        <p>訪客提交註冊 → 系統以邀請碼狀態判定 → 通過則建立帳號並核銷邀請碼，失敗則不留下任何持久化副作用。</p>
+        <p class="atlas-meta">
+          <strong>跨子模組交互（誰呼叫誰、誰讀誰寫、回應如何流回）以及與「獲取邀請碼」功能的資料行傳遞，已在<a href="../../index.html">宏觀架構圖</a>內統一呈現</strong>，本頁不重述。
+        </p>
+      </section>
+      <section class="submodule-nav">
+        <h2>本功能的子模組</h2>
+        <table>
+          <thead><tr><th>子模組</th><th>自身職責</th><th>頁面（自身 I/O + 內部資料流）</th></tr></thead>
+          <tbody>
+            <tr><td><code>web-register-ui</code></td><td>表單、客戶端驗證、發 HTTP</td><td><a href="web-register-ui.html">web-register-ui.html</a></td></tr>
+            <tr><td><code>public-api</code></td><td>HTTP 邊界、輸入綁定、錯誤映射</td><td><a href="public-api.html">public-api.html</a></td></tr>
+            <tr><td><code>registration-service</code></td><td>網域規則、交易編排</td><td><a href="registration-service.html">registration-service.html</a></td></tr>
+            <tr><td><code>postgresql</code></td><td>SQL：讀邀請碼、寫 user、核銷邀請</td><td><a href="postgresql.html">postgresql.html</a></td></tr>
+          </tbody>
+        </table>
+      </section>
+      <footer class="atlas-meta" style="margin-top: 2rem">
+        <p><a href="../../index.html">← 宏觀架構（含完整交互圖）</a> · <code>features/invite-code-registration/</code></p>
+      </footer>
+    </main>
+  </body>
+</html>

package/init-project-html/sample-demo/resources/project-architecture/features/invite-code-registration/postgresql.html ADDED Viewed

@@ -0,0 +1,161 @@
+<!DOCTYPE html>
+<html lang="zh-Hant">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>子模組 · postgresql — 邀請碼註冊（reg 視角）</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>postgresql</span>
+      </nav>
+      <header class="atlas-header">
+        <p class="atlas-kicker">Submodule · postgresql（reg 視角）</p>
+        <h1 class="atlas-title">postgresql — 註冊側操作</h1>
+        <p class="atlas-meta">
+          自身職責：以 SQL 對 <code>invite_codes</code>／<code>users</code> 表執行讀鎖、寫入與條件更新。本子模組同時是<strong>讀者</strong>（查邀請碼）與<strong>寫者</strong>（建 user、核銷邀請）。本頁只列自身 SQL 函式的 I/O。
+        </p>
+      </header>
+      <section class="sub-io">
+        <h2>SQL 函式 I/O</h2>
+        <table>
+          <thead><tr><th>函式</th><th>簽名／SQL</th><th>副作用</th><th>用途</th></tr></thead>
+          <tbody>
+            <tr>
+              <td><code>GetInviteForUpdate</code></td>
+              <td class="sub-io__signature">
+                <strong>in:</strong> <code>tx</code>, <code>code: text</code><br>
+                <strong>out:</strong> <code>InviteRow</code> | <code>NotFound</code><br>
+                SQL: <code>SELECT … FROM invite_codes WHERE code=$1 FOR UPDATE</code>
+              </td>
+              <td><span class="sub-io__side sub-io__side--io">lock</span> 對該列加 row lock 直到 tx 結束</td>
+              <td>取得邀請碼狀態並阻止他人並行核銷。</td>
+            </tr>
+            <tr>
+              <td><code>InsertUser</code></td>
+              <td class="sub-io__signature">
+                <strong>in:</strong> <code>tx</code>, <code>{email, passwordHash, inviteID}</code><br>
+                <strong>out:</strong> <code>UserID</code> | <code>UniqueViolation</code><br>
+                SQL: <code>INSERT INTO users (...) RETURNING id</code>
+              </td>
+              <td><span class="sub-io__side sub-io__side--write">write</span> 新列（待 commit）</td>
+              <td>建立使用者列；<code>users.email UNIQUE</code>。</td>
+            </tr>
+            <tr>
+              <td><code>MarkInviteConsumed</code></td>
+              <td class="sub-io__signature">
+                <strong>in:</strong> <code>tx</code>, <code>inviteID</code>, <code>userID</code>, <code>now</code><br>
+                <strong>out:</strong> <code>RowsAffected</code><br>
+                SQL: <code>UPDATE invite_codes SET consumed_at=$3, consumed_by=$2 WHERE id=$1 AND consumed_at IS NULL</code>
+              </td>
+              <td><span class="sub-io__side sub-io__side--write">write</span> 條件更新</td>
+              <td>標記核銷；<code>RowsAffected=0</code> 表示已被搶先核銷。</td>
+            </tr>
+          </tbody>
+        </table>
+      </section>
+      <section class="sub-vars">
+        <h2>變數與業務用途</h2>
+        <p class="sub-vars__intro">本表分兩段：上半為 SQL 函式參數，下半為 <code>invite_codes</code> / <code>users</code> 表上的關鍵列欄位（被本子模組讀寫）。</p>
+        <table>
+          <thead><tr><th>變數</th><th>型別</th><th>作用域</th><th>業務用途</th></tr></thead>
+          <tbody>
+            <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>上層管理的隔離單元；本子模組所有 SQL 都掛在這個 <code>tx</code> 上，未 commit 即視為「無事發生」，保證註冊原子性。</td>
+            </tr>
+            <tr>
+              <td class="sub-vars__name">code</td>
+              <td class="sub-vars__type">text</td>
+              <td><span class="sub-vars__scope sub-vars__scope--call">call</span></td>
+              <td><code>GetInviteForUpdate</code> 的查鎖鍵；對應到列上欄位 <code>invite_codes.code</code> 的 UNIQUE 索引，避免並行核銷相同邀請。</td>
+            </tr>
+            <tr>
+              <td class="sub-vars__name">inviteID</td>
+              <td class="sub-vars__type">UUID</td>
+              <td><span class="sub-vars__scope sub-vars__scope--tx">tx</span></td>
+              <td>從 SELECT 取得後跨多個寫入；把「核銷哪一張邀請」與「新 user 屬於哪張邀請」綁定，作為日後審計鏈。</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--tx">tx</span></td>
+              <td><code>InsertUser RETURNING id</code> 的結果；同一 <code>tx</code> 內回填到 <code>consumed_by</code>，完成「誰用了邀請」的紀錄。</td>
+            </tr>
+            <tr>
+              <td class="sub-vars__name">now</td>
+              <td class="sub-vars__type">timestamp</td>
+              <td><span class="sub-vars__scope sub-vars__scope--call">call</span></td>
+              <td>核銷時的官方時間；由應用層提供以避免應用與 DB 時鐘漂移影響審計順序。</td>
+            </tr>
+            <tr>
+              <td class="sub-vars__name">RowsAffected</td>
+              <td class="sub-vars__type">int</td>
+              <td><span class="sub-vars__scope sub-vars__scope--call">call</span></td>
+              <td><code>MarkInviteConsumed</code> 條件更新結果；<code>0</code> 表示已被搶先核銷，本次必須回滾，否則會發生雙倍消費。</td>
+            </tr>
+            <tr>
+              <td class="sub-vars__name">consumed_at</td>
+              <td class="sub-vars__type">timestamp NULL</td>
+              <td><span class="sub-vars__scope sub-vars__scope--persist">persist</span></td>
+              <td><code>invite_codes</code> 列上欄位；非空代表「這張邀請已被消費」，與 <code>WHERE consumed_at IS NULL</code> 一起防雙重核銷。</td>
+            </tr>
+            <tr>
+              <td class="sub-vars__name">consumed_by</td>
+              <td class="sub-vars__type">FK → users.id</td>
+              <td><span class="sub-vars__scope sub-vars__scope--persist">persist</span></td>
+              <td><code>invite_codes</code> 列上欄位；紀錄是哪個 user 用掉這張邀請，是「邀請碼註冊」這條業務路徑留下的最終痕跡。</td>
+            </tr>
+            <tr>
+              <td class="sub-vars__name">users.email</td>
+              <td class="sub-vars__type">text UNIQUE</td>
+              <td><span class="sub-vars__scope sub-vars__scope--persist">persist</span></td>
+              <td>使用者唯一鍵；UNIQUE 違例代表「相同信箱已註冊」，業務上以 409 回應，呼叫端不應靜默忽略。</td>
+            </tr>
+          </tbody>
+        </table>
+      </section>
+      <section class="sub-dataflow">
+        <h2>內部資料流（單一交易視角）</h2>
+        <ol>
+          <li>呼叫端開 <code>tx</code> → 本子模組以該 <code>tx</code> 執行 SQL；交易控制不在本子模組內。</li>
+          <li><code>GetInviteForUpdate</code> 取得 <code>InviteRow</code> 並把 <strong>列鎖</strong> 綁在 <code>tx</code> 上。</li>
+          <li><code>InsertUser</code> 取得 <code>UserID</code>，作為下一步 <code>consumed_by</code> 的 FK 值。</li>
+          <li><code>MarkInviteConsumed</code> 以 <code>WHERE consumed_at IS NULL</code> 防雙重核銷。</li>
+          <li>所有寫入皆在 <code>tx</code> 內；commit／rollback 由呼叫端決定，本子模組對外只報告每個 SQL 的結果。</li>
+        </ol>
+      </section>
+      <section class="sub-errors">
+        <h2>本子模組會回傳的錯誤</h2>
+        <table>
+          <thead><tr><th>錯誤</th><th>觸發 SQL</th><th>含義</th></tr></thead>
+          <tbody>
+            <tr><td><code>NotFound</code></td><td><code>GetInviteForUpdate</code></td><td>無該邀請碼列。</td></tr>
+            <tr><td><code>UniqueViolation</code></td><td><code>InsertUser</code></td><td>email 重複。</td></tr>
+            <tr><td><code>LockWaitTimeout</code></td><td><code>GetInviteForUpdate</code></td><td>其他並發交易長時間持有鎖。</td></tr>
+            <tr><td><code>ConnTransient</code></td><td>任意</td><td>網路／restart；交易不會 partial。</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>