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

@laitszkin/apollo-toolkit 3.9.6 → 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 (46) hide show

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

@@ -0,0 +1,145 @@
+<!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（reg）</h1>
+        <p class="atlas-meta">自身職責：HTTP 邊界。處理綁定、輸入 schema 檢查、把網域結果映射為狀態碼／錯誤 payload。</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>RegisterHandler</code></td>
+              <td class="sub-io__signature">
+                <strong>in:</strong> <code>http.Request</code><br>
+                <strong>out:</strong> <code>http.Response</code>
+              </td>
+              <td><span class="sub-io__side sub-io__side--io">io</span> 讀／寫 socket</td>
+              <td>路由綁定的對外入口。</td>
+            </tr>
+            <tr>
+              <td><code>decodeRegisterInput</code></td>
+              <td class="sub-io__signature">
+                <strong>in:</strong> <code>io.Reader</code><br>
+                <strong>out:</strong> <code>RegisterInput</code> | <code>ErrBadRequest</code>
+              </td>
+              <td><span class="sub-io__side sub-io__side--io">io</span> 讀 body</td>
+              <td>JSON 解碼 + 基本 schema 校驗。</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>網域 error → HTTP 對映表。</td>
+            </tr>
+            <tr>
+              <td><code>writeSuccess</code></td>
+              <td class="sub-io__signature">
+                <strong>in:</strong> <code>NewUserID</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>序列化 user id + 必要 header。</td>
+            </tr>
+          </tbody>
+        </table>
+      </section>
+      <section class="sub-vars">
+        <h2>變數與業務用途</h2>
+        <p class="sub-vars__intro">HTTP 邊界子模組持有的識別子，幾乎全在單次 handler 呼叫中存活。</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 期間有效，handler 結束後資源歸還，不可在背景任務繼續使用。</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>HTTP body 解碼後的網域層承載；schema 校驗通過代表「結構面可進入業務」，避免錯誤輸入觸發無謂的 DB 開銷。</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> 的輸出之一；業務面決定協議語意（409 與 503 不可混用，前者要使用者改、後者要使用者稍後再試）。</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 對映本地化文字，<code>message</code> 僅供開發者排錯。</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>http.Request.Body</code> → <code>decodeRegisterInput</code> → <code>RegisterInput</code>（失敗 → <code>ErrBadRequest</code>）。</li>
+          <li><code>RegisterInput</code> 作為傳入網域層的參數；本子模組<strong>不</strong>持有交易、密碼明文也只在這一函式內存在。</li>
+          <li>從網域層拿到 <code>NewUserID | error</code>：
+            <ul>
+              <li><code>NewUserID</code> → <code>writeSuccess</code>。</li>
+              <li><code>error</code> → <code>mapDomainError</code> → 對應 HTTP 狀態 + JSON。</li>
+            </ul>
+          </li>
+          <li>處理結束 / response 完成寫入後生命週期終止。</li>
+        </ol>
+      </section>
+      <section class="sub-errors">
+        <h2>本子模組會回應／轉化的錯誤</h2>
+        <table>
+          <thead><tr><th>條件</th><th>HTTP</th></tr></thead>
+          <tbody>
+            <tr><td>schema 失敗</td><td><code>400 BAD_REQUEST</code></td></tr>
+            <tr><td>網域回 <code>ErrInviteInvalid</code></td><td><code>409 INVITE_INVALID</code></td></tr>
+            <tr><td>網域回 <code>ErrTransient</code></td><td><code>503 SERVICE_UNAVAILABLE</code></td></tr>
+            <tr><td>panic 或未分類</td><td><code>500 INTERNAL</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/invite-code-registration/registration-service.html ADDED Viewed

@@ -0,0 +1,190 @@
+<!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>

package/init-project-html/sample-demo/resources/project-architecture/features/invite-code-registration/web-register-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-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>