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/invite-code-registration/registration-service.html CHANGED Viewed

@@ -1,190 +1,100 @@
 <!DOCTYPE html>
-<html lang="zh-Hant">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>子模組 · registration-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>registration-service</span>
-      </nav>
-      <header class="atlas-header">
-        <p class="atlas-kicker">Submodule · registration-service</p>
-        <h1 class="atlas-title">registration-service</h1>
-        <p class="atlas-meta">
-          自身職責：在<strong>單一交易</strong>內以邀請碼狀態判定是否建立 user 並核銷邀請碼。本頁只記述<strong>本子模組自身函式的 I/O 與內部資料流</strong>；與其他子模組之間的呼叫關係請見<a href="../../index.html">宏觀架構圖</a>。
-        </p>
-      </header>
-      <section class="sub-io">
-        <h2>函式 I/O</h2>
-        <table>
-          <thead>
-            <tr><th>函式</th><th>簽名／I/O</th><th>副作用</th><th>用途</th></tr>
-          </thead>
-          <tbody>
-            <tr>
-              <td><code>RegisterWithInvite</code></td>
-              <td class="sub-io__signature">
-                <strong>in:</strong> <code>ctx</code>, <code>RegisterInput{Email, Password, InviteCode}</code><br>
-                <strong>out:</strong> <code>NewUserID</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> 條件成立時寫入 user + 標記邀請碼已用<br>
-                <span class="sub-io__side sub-io__side--io">hash</span> 對密碼做 hash
-              </td>
-              <td>對外唯一入口。</td>
-            </tr>
-            <tr>
-              <td><code>validateInput</code></td>
-              <td class="sub-io__signature">
-                <strong>in:</strong> <code>RegisterInput</code><br>
-                <strong>out:</strong> <code>NormalizedInput</code> | <code>ErrInvalidInput</code>
-              </td>
-              <td><span class="sub-io__side sub-io__side--pure">pure</span></td>
-              <td>email 規範化、邀請碼 trim／大小寫策略、密碼最小強度。</td>
-            </tr>
-            <tr>
-              <td><code>decideInviteValid</code></td>
-              <td class="sub-io__signature">
-                <strong>in:</strong> <code>InviteRow | nil</code>, <code>now</code><br>
-                <strong>out:</strong> <code>true | ErrInviteInvalid</code>
-              </td>
-              <td><span class="sub-io__side sub-io__side--pure">pure</span></td>
-              <td>判斷邀請列是否存在、未過期、未核銷、<code>allowed_registration==true</code>。</td>
-            </tr>
-            <tr>
-              <td><code>hashPassword</code></td>
-              <td class="sub-io__signature">
-                <strong>in:</strong> <code>plaintext</code><br>
-                <strong>out:</strong> <code>passwordHash</code>
-              </td>
-              <td><span class="sub-io__side sub-io__side--io">cpu</span> 高成本（bcrypt/argon2）</td>
-              <td>密碼絕不外傳明文；本函式回傳後 plaintext 應被丟棄。</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">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">RegisterInput</td>
-              <td class="sub-vars__type">{Email, Password, InviteCode}</td>
-              <td><span class="sub-vars__scope sub-vars__scope--call">call</span></td>
-              <td>使用者註冊意圖承載：要為誰建立帳號、用什麼憑證、套用哪張邀請碼；任一欄缺值即無法進入業務判定。</td>
-            </tr>
-            <tr>
-              <td class="sub-vars__name">NormalizedInput</td>
-              <td class="sub-vars__type">{email_lc, code_norm, pwd_plain}</td>
-              <td><span class="sub-vars__scope sub-vars__scope--call">call</span></td>
-              <td>規範化後的業務輸入；保證 email／邀請碼比較在同一基準上，避免大小寫造成的可避免失敗。<code>pwd_plain</code> 在 hash 之後即被丟棄。</td>
-            </tr>
-            <tr>
-              <td class="sub-vars__name">row / InviteRow</td>
-              <td class="sub-vars__type">DB row</td>
-              <td><span class="sub-vars__scope sub-vars__scope--tx">tx</span></td>
-              <td>「能否註冊」的唯一證據；<code>AllowedRegistration</code> / <code>ConsumedAt</code> / <code>ExpiresAt</code> 三欄直接決定進入「拒絕」或「建立」分支；列鎖在本 <code>tx</code> 內持續至結束。</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>consumed_at</code> 的官方時戳；測試可注入以避免依賴牆鐘。</td>
-            </tr>
-            <tr>
-              <td class="sub-vars__name">passwordHash</td>
-              <td class="sub-vars__type">[]byte</td>
-              <td><span class="sub-vars__scope sub-vars__scope--call">call</span></td>
-              <td>不可逆密碼承載；確保任何明文不會離開本子模組或進入持久化路徑與日誌。</td>
-            </tr>
-            <tr>
-              <td class="sub-vars__name">UserToInsert</td>
-              <td class="sub-vars__type">{email_lc, passwordHash, invite_id}</td>
-              <td><span class="sub-vars__scope sub-vars__scope--tx">tx</span></td>
-              <td>把「業務通過」結果翻譯成 DB 寫入承載；<code>invite_id</code> 把新使用者與其邀請來源綁定，作為日後審計依據。</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>把「邀請判定 + 建立 user + 核銷邀請」綁成原子單元；commit／rollback 決定本次註冊是否在世界上留下任何持久化痕跡。</td>
-            </tr>
-          </tbody>
-        </table>
-      </section>
-      <section class="sub-dataflow">
-        <h2>內部資料流</h2>
-        <p>下列步序描述<strong>同一個 <code>RegisterWithInvite</code> 呼叫</strong>內部資料如何在自身函式之間流動。每一步只標記值的變化與作用，不展開外部子模組的細節。</p>
-        <ol>
-          <li><code>RegisterInput</code> → <code>validateInput</code> → <code>NormalizedInput{email_lc, code_norm, pwd_plain}</code>。</li>
-          <li><code>NormalizedInput.code_norm</code> 作為查鎖讀的鍵；讀回 <code>InviteRow | nil</code>，記在區域變數 <code>row</code>。</li>
-          <li><code>row</code> 連同 <code>time.Now()</code> 傳入 <code>decideInviteValid</code>；不通過則拋 <code>ErrInviteInvalid</code> 並結束（交易在外層被回滾）。</li>
-          <li><code>NormalizedInput.pwd_plain</code> → <code>hashPassword</code> → <code>passwordHash</code>；之後 <code>pwd_plain</code> 不再使用。</li>
-          <li>組合 <code>UserToInsert{email_lc, passwordHash, invite_id=row.ID}</code>，作為寫入承載。</li>
-          <li>條件分支結束後將控制權交給交易管理；本子模組函式自此不再持有任何明文敏感資料。</li>
-        </ol>
-        <svg class="sub-dataflow__svg" viewBox="0 0 720 220" role="img" aria-label="內部資料流">
-          <defs>
-            <marker id="d-arr" 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">RegisterInput</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">validateInput</text><text x="275" y="68" text-anchor="middle" class="d-label">→ NormalizedInput</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">decideInviteValid</text><text x="465" y="68" text-anchor="middle" class="d-label">(row, now) → bool</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">ErrInviteInvalid</text></g>
-          <g class="d-node"><rect x="200" y="140" width="150" height="50" rx="8"></rect><text x="275" y="160" text-anchor="middle">hashPassword</text><text x="275" y="178" text-anchor="middle" class="d-label">pwd → passwordHash</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">UserToInsert</text><text x="465" y="178" text-anchor="middle" class="d-label">{email_lc, hash, invite_id}</text></g>
-          <line class="d-edge" x1="170" y1="55" x2="196" y2="55" marker-end="url(#d-arr)"></line>
-          <line class="d-edge" x1="350" y1="55" x2="376" y2="55" marker-end="url(#d-arr)"></line>
-          <line class="d-edge d-edge--side" x1="550" y1="55" x2="576" y2="55" marker-end="url(#d-arr)"></line>
-          <line class="d-edge" x1="275" y1="80" x2="275" y2="136" marker-end="url(#d-arr)"></line>
-          <line class="d-edge" x1="350" y1="165" x2="376" y2="165" marker-end="url(#d-arr)"></line>
-        </svg>
-      </section>
-      <section class="sub-errors">
-        <h2>本子模組會拋出的錯誤</h2>
-        <table class="sub-io__inline">
-          <thead><tr><th>錯誤</th><th>觸發條件</th><th>後續責任</th></tr></thead>
-          <tbody>
-            <tr><td><code>ErrInvalidInput</code></td><td><code>validateInput</code> 失敗</td><td>呼叫端決定 HTTP 對映；本子模組不開交易。</td></tr>
-            <tr><td><code>ErrInviteInvalid</code></td><td><code>decideInviteValid</code> 為 false</td><td>呼叫端負責回滾交易並回應對外錯誤碼。</td></tr>
-            <tr><td><code>ErrTransient</code></td><td>外部 I/O 暫時失敗（例如 hash CPU 中斷、context 取消）</td><td>呼叫端決定是否重試；本子模組僅保證未提交。</td></tr>
-          </tbody>
-        </table>
-        <p class="atlas-meta">回滾／重試怎麼影響其他子模組的狀態，屬於跨界議題；請見<a href="../../index.html">宏觀架構圖</a>的 manifest 與資料行邊。</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>Invite-code registration · registration-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">← Invite-code registration</a></nav>
+    <h1>registration-service <small class="submodule-kind submodule-kind--service">Service</small></h1>
+    <p class="submodule-role">Owns the registration transaction (consumer side of the invite_codes data row).</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>RegisterWithInvite</td><td>ctx, RegisterInput</td><td>NewUserID | ErrInvalidCode | ErrEmailTaken</td><td>tx</td><td>Validates code, hashes password, inserts user, consumes invite.</td></tr>
+          <tr><td>decideInviteValid</td><td>row, now</td><td>true | ErrInvalidCode</td><td>pure</td><td>Checks existence, expiry, consumption state.</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>inviteRow</td><td>InviteCodeRow</td><td>tx</td><td>Row read with SELECT FOR UPDATE; gates the rest of the flow.</td></tr>
+          <tr><td>passwordHash</td><td>string</td><td>tx</td><td>bcrypt/argon2 hash of the submitted password; plaintext is discarded.</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 600" 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">Open transaction.</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">SELECT invite_codes FOR UPDATE WHERE code = ?</text>
+  </g>
+  <line class="sub-dataflow__arrow" x1="340" y1="226" x2="340" y2="256" marker-end="url(#sub-arrow)" />
+  <g class="sub-dataflow__step">
+    <circle class="sub-dataflow__badge" cx="42" cy="300" r="18" />
+    <text class="sub-dataflow__badge-text" x="42" y="305" text-anchor="middle">3</text>
+    <rect class="sub-dataflow__box" x="80" y="264" width="520" height="72" rx="14" ry="14" />
+    <text class="sub-dataflow__text" x="340" y="306" text-anchor="middle">decideInviteValid against current time.</text>
+  </g>
+  <line class="sub-dataflow__arrow" x1="340" y1="342" x2="340" y2="372" marker-end="url(#sub-arrow)" />
+  <g class="sub-dataflow__step">
+    <circle class="sub-dataflow__badge" cx="42" cy="416" r="18" />
+    <text class="sub-dataflow__badge-text" x="42" y="421" text-anchor="middle">4</text>
+    <rect class="sub-dataflow__box" x="80" y="380" width="520" height="72" rx="14" ry="14" />
+    <text class="sub-dataflow__text" x="340" y="422" text-anchor="middle">INSERT users row and UPDATE invite_codes.consumed_at.</text>
+  </g>
+  <line class="sub-dataflow__arrow" x1="340" y1="458" x2="340" y2="488" marker-end="url(#sub-arrow)" />
+  <g class="sub-dataflow__step">
+    <circle class="sub-dataflow__badge" cx="42" cy="532" r="18" />
+    <text class="sub-dataflow__badge-text" x="42" y="537" text-anchor="middle">5</text>
+    <rect class="sub-dataflow__box" x="80" y="496" width="520" height="72" rx="14" ry="14" />
+    <text class="sub-dataflow__text" x="340" y="538" text-anchor="middle">Commit and return NewUserID.</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>ErrInvalidCode</td><td>Row missing, expired, or already consumed.</td><td>422 response with `invite_code` reason.</td></tr>
+          <tr><td>ErrEmailTaken</td><td>Unique violation on users.email.</td><td>422 response with `email` reason.</td></tr>
+        </tbody>
+      </table>
+    </section>
+  </main>
+  <script src="../../assets/viewer.client.js" defer></script>
+</body>
 </html>

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

@@ -1,140 +1,85 @@
 <!DOCTYPE html>
-<html lang="zh-Hant">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>子模組 · web-register-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-register-ui</span>
-      </nav>
-      <header class="atlas-header">
-        <p class="atlas-kicker">Submodule · web-register-ui</p>
-        <h1 class="atlas-title">web-register-ui</h1>
-        <p class="atlas-meta">自身職責：渲染註冊表單、客戶端驗證、發出 HTTP 請求、把結果映射成 UI 狀態。本頁只談自身函式 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>useRegisterForm()</code></td>
-              <td class="sub-io__signature">
-                <strong>in:</strong> —<br>
-                <strong>out:</strong> <code>{values, errors, setField, submit}</code>
-              </td>
-              <td><span class="sub-io__side sub-io__side--io">state</span> React state hook</td>
-              <td>表單狀態容器。</td>
-            </tr>
-            <tr>
-              <td><code>validateClientSide</code></td>
-              <td class="sub-io__signature">
-                <strong>in:</strong> <code>FormValues</code><br>
-                <strong>out:</strong> <code>FieldErrors | null</code>
-              </td>
-              <td><span class="sub-io__side sub-io__side--pure">pure</span></td>
-              <td>必填、email 格式、密碼長度等規則。</td>
-            </tr>
-            <tr>
-              <td><code>submit</code></td>
-              <td class="sub-io__signature">
-                <strong>in:</strong> <code>FormValues</code><br>
-                <strong>out:</strong> <code>Result&lt;NewUserID, UiError&gt;</code>
-              </td>
-              <td><span class="sub-io__side sub-io__side--io">network</span> fetch POST</td>
-              <td>送出後驅動 loading / success / error UI。</td>
-            </tr>
-            <tr>
-              <td><code>mapApiError</code></td>
-              <td class="sub-io__signature">
-                <strong>in:</strong> <code>ApiError{code, message}</code><br>
-                <strong>out:</strong> <code>UiMessage{lang_tag, text}</code>
-              </td>
-              <td><span class="sub-io__side sub-io__side--pure">pure</span></td>
-              <td>機讀錯誤碼轉成本地化訊息。</td>
-            </tr>
-          </tbody>
-        </table>
-      </section>
-      <section class="sub-vars">
-        <h2>變數與業務用途</h2>
-        <p class="sub-vars__intro">本表盤點本子模組在記憶體中持有、決定 UI 行為的關鍵識別子。</p>
-        <table>
-          <thead><tr><th>變數</th><th>型別</th><th>作用域</th><th>業務用途</th></tr></thead>
-          <tbody>
-            <tr>
-              <td class="sub-vars__name">FormValues</td>
-              <td class="sub-vars__type">{email, password, inviteCode}</td>
-              <td><span class="sub-vars__scope sub-vars__scope--instance">instance</span></td>
-              <td>使用者目前打算送出的註冊資料；驅動所有後續驗證、按鈕可用性與請求 body。</td>
-            </tr>
-            <tr>
-              <td class="sub-vars__name">FieldErrors</td>
-              <td class="sub-vars__type">Record&lt;field,msg&gt; | null</td>
-              <td><span class="sub-vars__scope sub-vars__scope--call">call</span></td>
-              <td>客戶端驗證結果；非空時阻擋網路請求，避免明顯無效嘗試打到後端造成不必要負擔與錯誤訊息。</td>
-            </tr>
-            <tr>
-              <td class="sub-vars__name">UIState</td>
-              <td class="sub-vars__type">idle | loading | error | success</td>
-              <td><span class="sub-vars__scope sub-vars__scope--instance">instance</span></td>
-              <td>UI 機器狀態；<code>loading</code> 期間禁用送出按鈕避免重複提交；其他狀態決定要顯示哪個訊息／導向。</td>
-            </tr>
-            <tr>
-              <td class="sub-vars__name">Result</td>
-              <td class="sub-vars__type">{ok: NewUserID} | {err: UiError}</td>
-              <td><span class="sub-vars__scope sub-vars__scope--call">call</span></td>
-              <td>一次 <code>submit</code> 的最終回應；驅動「導向後續頁」或「停留修改再試」兩條業務分支。</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>setField</code> 改寫 <code>FormValues</code>。</li>
-          <li>送出時 <code>validateClientSide(FormValues)</code> 若回 <code>FieldErrors</code>，UI 設為 <code>error</code>，<strong>不</strong>觸發網路請求。</li>
-          <li>通過驗證後 <code>submit(FormValues)</code>：UI 轉 <code>loading</code>，等待 <code>Result</code>。</li>
-          <li><code>Result.ok</code> → UI 轉 <code>success</code>，呼叫導向；<code>Result.err</code> → 經 <code>mapApiError</code> 變 <code>UiMessage</code> 顯示。</li>
-          <li>失敗後 <code>FormValues</code> 保留，使用者可修正並再次 <code>submit</code>。</li>
-        </ol>
-      </section>
-      <section class="sub-errors">
-        <h2>本子模組可暴露的錯誤</h2>
-        <table>
-          <thead><tr><th>類型</th><th>來源</th><th>UI 行為</th></tr></thead>
-          <tbody>
-            <tr><td><code>FieldErrors</code></td><td><code>validateClientSide</code></td><td>就地紅字；無網路請求。</td></tr>
-            <tr><td><code>UiMessage</code></td><td><code>mapApiError</code></td><td>banner／toast；表單仍可編輯。</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 · web-register-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">← Invite-code registration</a></nav>
+    <h1>web-register-ui <small class="submodule-kind submodule-kind--ui">UI</small></h1>
+    <p class="submodule-role">React page that captures email, password, and 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>handleSubmit</td><td>FormEvent</td><td>void</td><td>io</td><td>POSTs the registration payload and routes the response.</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>email</td><td>string</td><td>call</td><td>Identity for the new account; required.</td></tr>
+          <tr><td>inviteCode</td><td>string</td><td>call</td><td>Token from the off-platform invite hand-off.</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 372" 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">Collect form fields.</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">POST /api/register with payload.</text>
+  </g>
+  <line class="sub-dataflow__arrow" x1="340" y1="226" x2="340" y2="256" marker-end="url(#sub-arrow)" />
+  <g class="sub-dataflow__step">
+    <circle class="sub-dataflow__badge" cx="42" cy="302" r="18" />
+    <text class="sub-dataflow__badge-text" x="42" y="307" text-anchor="middle">3</text>
+    <rect class="sub-dataflow__box" x="80" y="264" width="520" height="76" rx="14" ry="14" />
+    <text class="sub-dataflow__text" x="340" y="298" text-anchor="middle">On 2xx redirect to /welcome; otherwise surface field-level</text>
+    <text class="sub-dataflow__text" x="340" y="318" text-anchor="middle">errors.</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>ErrInvalidCode</td><td>API returns 422 with `invite_code` reason.</td><td>Highlight the invite-code field with the API message.</td></tr>
+        </tbody>
+      </table>
+    </section>
+  </main>
+  <script src="../../assets/viewer.client.js" defer></script>
+</body>
 </html>