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

@laitszkin/apollo-toolkit 3.10.0 → 3.11.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 (47) hide show

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

@@ -1,140 +1,67 @@
 <!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 lang="en" data-atlas-page="submodule">
+<head>
+  <meta charset="utf-8">
+  <title>Get invite codes · web-get-invite-ui</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>web-get-invite-ui <small class="submodule-kind submodule-kind--ui">UI</small></h1>
+    <p class="submodule-role">React page that lets a signed-in member request a new 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>handleGenerate</td><td>MouseEvent</td><td>void</td><td>io</td><td>Calls POST /api/invites and renders the returned code.</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>userId</td><td>string</td><td>call</td><td>Identifies the member who will own the new invite row.</td></tr>
+          <tr><td>code</td><td>string</td><td>instance</td><td>Last issued code shown to the member.</td></tr>
+        </tbody>
+      </table>
+    </section>
+    <section class="sub-dataflow" aria-label="Internal data flow">
+      <h2>Internal data flow</h2>
+      <svg class="sub-dataflow__svg" viewBox="0 0 400 264" role="img" aria-label="Internal dataflow">
+  <defs><marker id="sub-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 Z" /></marker></defs>
+  <g class="sub-dataflow__step">
+    <rect x="20" y="20" width="360" height="56" rx="8" ry="8" />
+    <text x="200" y="44" text-anchor="middle">Read userId from auth context.</text>
+  </g>
+  <line class="sub-dataflow__arrow" x1="200" y1="76" x2="200" y2="104" marker-end="url(#sub-arrow)" />
+  <g class="sub-dataflow__step">
+    <rect x="20" y="104" width="360" height="56" rx="8" ry="8" />
+    <text x="200" y="128" text-anchor="middle">POST /api/invites with userId.</text>
+  </g>
+  <line class="sub-dataflow__arrow" x1="200" y1="160" x2="200" y2="188" marker-end="url(#sub-arrow)" />
+  <g class="sub-dataflow__step">
+    <rect x="20" y="188" width="360" height="56" rx="8" ry="8" />
+    <text x="200" y="212" text-anchor="middle">Render returned code or surface error.</text>
+  </g>
+</svg>
+    </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>ErrUnauthenticated</td><td>Session is missing on the client.</td><td>Redirect to sign-in.</td></tr>
+          <tr><td>ErrIssuanceFailed</td><td>API returns 500.</td><td>Show retry banner.</td></tr>
+        </tbody>
+      </table>
+    </section>
+  </main>
+</body>
 </html>

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

@@ -1,53 +1,63 @@
 <!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 lang="en" data-atlas-page="feature">
+<head>
+  <meta charset="utf-8">
+  <title>Invite-code registration</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <link rel="stylesheet" href="../../assets/architecture.css">
+</head>
+<body>
+  <header class="feature-header">
+    <nav class="feature-breadcrumb"><a href="../../index.html">← Atlas</a></nav>
+    <h1>Invite-code registration</h1>
+    <p class="feature-depends">Depends on: <a href="../get-invite-codes/index.html">get-invite-codes</a></p>
+  </header>
+  <main class="feature-main">
+    <section class="feature-story"><p>A visitor holding an invite code submits email/password plus the code. The registration service validates the code inside a single transaction; on success it creates a new user and consumes the invite_codes row issued earlier by `get-invite-codes`.</p></section>
+    <section class="feature-submodules" aria-label="Submodules">
+      <h2>Submodules</h2>
+      <ul class="submodule-nav">
+      <li class="submodule-card">
+        <a class="submodule-card__link" href="web-register-ui.html">
+          <span class="submodule-card__name">web-register-ui</span>
+          <span class="submodule-card__kind submodule-card__kind--ui">UI</span>
+        </a>
+        <p class="submodule-card__role">React page that captures email, password, and invite code.</p>
+      </li>
+      <li class="submodule-card">
+        <a class="submodule-card__link" href="public-api.html">
+          <span class="submodule-card__name">public-api</span>
+          <span class="submodule-card__kind submodule-card__kind--api">API</span>
+        </a>
+        <p class="submodule-card__role">HTTP boundary for `/api/register` POST requests.</p>
+      </li>
+      <li class="submodule-card">
+        <a class="submodule-card__link" href="registration-service.html">
+          <span class="submodule-card__name">registration-service</span>
+          <span class="submodule-card__kind submodule-card__kind--service">Service</span>
+        </a>
+        <p class="submodule-card__role">Owns the registration transaction (consumer side of the invite_codes data row).</p>
+      </li>
+      <li class="submodule-card">
+        <a class="submodule-card__link" href="postgresql.html">
+          <span class="submodule-card__name">postgresql</span>
+          <span class="submodule-card__kind submodule-card__kind--db">DB</span>
+        </a>
+        <p class="submodule-card__role">Stores `users` rows and applies invite-code state transitions inside the registration tx.</p>
+      </li>
+      </ul>
+    </section>
+    <section class="feature-edges" aria-label="Intra-feature edges">
+      <h2>Intra-feature edges</h2>
+      <ul class="feature-edges__list">
+        <li class="feature-edges__item feature-edges__item--call"><span class="feature-edges__endpoints">web-register-ui → public-api</span><span class="feature-edges__kind">call</span><span class="feature-edges__label">POST /api/register</span></li>
+        <li class="feature-edges__item feature-edges__item--call"><span class="feature-edges__endpoints">public-api → registration-service</span><span class="feature-edges__kind">call</span><span class="feature-edges__label">RegisterWithInvite(ctx, RegisterInput)</span></li>
+        <li class="feature-edges__item feature-edges__item--call"><span class="feature-edges__endpoints">registration-service → postgresql</span><span class="feature-edges__kind">call</span><span class="feature-edges__label">SELECT invite_codes FOR UPDATE</span></li>
+        <li class="feature-edges__item feature-edges__item--call"><span class="feature-edges__endpoints">registration-service → postgresql</span><span class="feature-edges__kind">call</span><span class="feature-edges__label">INSERT users</span></li>
+        <li class="feature-edges__item feature-edges__item--call"><span class="feature-edges__endpoints">registration-service → postgresql</span><span class="feature-edges__kind">call</span><span class="feature-edges__label">UPDATE invite_codes.consumed_at</span></li>
+        <li class="feature-edges__item feature-edges__item--return"><span class="feature-edges__endpoints">postgresql → registration-service</span><span class="feature-edges__kind">return</span><span class="feature-edges__label">row | rows_affected</span></li>
+      </ul>
+    </section>
+  </main>
+</body>
 </html>

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

@@ -1,161 +1,68 @@
 <!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 lang="en" data-atlas-page="submodule">
+<head>
+  <meta charset="utf-8">
+  <title>Invite-code registration · postgresql</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">← Invite-code registration</a></nav>
+    <h1>postgresql <small class="submodule-kind submodule-kind--db">DB</small></h1>
+    <p class="submodule-role">Stores `users` rows and applies invite-code state transitions inside the registration tx.</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>SELECT_invite_for_update</td><td>code</td><td>InviteCodeRow | nil</td><td>lock</td><td>Locks the invite row for the duration of the transaction.</td></tr>
+          <tr><td>INSERT_users</td><td>userRow</td><td>userId</td><td>write</td><td>Persists the new account.</td></tr>
+          <tr><td>UPDATE_invite_consumed</td><td>code, now</td><td>rows_affected</td><td>write</td><td>Marks the invite as consumed.</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>users.email</td><td>text</td><td>persist</td><td>Unique account identity.</td></tr>
+          <tr><td>invite_codes.consumed_at</td><td>timestamptz</td><td>persist</td><td>Timestamp set the moment the invite row is consumed.</td></tr>
+        </tbody>
+      </table>
+    </section>
+    <section class="sub-dataflow" aria-label="Internal data flow">
+      <h2>Internal data flow</h2>
+      <svg class="sub-dataflow__svg" viewBox="0 0 400 264" role="img" aria-label="Internal dataflow">
+  <defs><marker id="sub-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 Z" /></marker></defs>
+  <g class="sub-dataflow__step">
+    <rect x="20" y="20" width="360" height="56" rx="8" ry="8" />
+    <text x="200" y="44" text-anchor="middle">Apply row lock on invite_codes.</text>
+  </g>
+  <line class="sub-dataflow__arrow" x1="200" y1="76" x2="200" y2="104" marker-end="url(#sub-arrow)" />
+  <g class="sub-dataflow__step">
+    <rect x="20" y="104" width="360" height="56" rx="8" ry="8" />
+    <text x="200" y="128" text-anchor="middle">Validate uniqueness of users.email.</text>
+  </g>
+  <line class="sub-dataflow__arrow" x1="200" y1="160" x2="200" y2="188" marker-end="url(#sub-arrow)" />
+  <g class="sub-dataflow__step">
+    <rect x="20" y="188" width="360" height="56" rx="8" ry="8" />
+    <text x="200" y="212" text-anchor="middle">Write users row and update invite_codes.consumed_at.</text>
+  </g>
+</svg>
+    </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>ErrUniqueEmail</td><td>users.email unique constraint violated.</td><td>Bubble up so service can return ErrEmailTaken.</td></tr>
+        </tbody>
+      </table>
+    </section>
+  </main>
+</body>
 </html>