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

@laitszkin/apollo-toolkit 3.10.0 → 3.11.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (47) hide show

package/init-project-html/sample-demo/resources/project-architecture/features/get-invite-codes/web-get-invite-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-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>
+      <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 368" role="img" aria-label="Internal dataflow">
+  <defs>
+    <marker id="sub-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="9" markerHeight="9" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 Z" /></marker>
+  </defs>
+  <g class="sub-dataflow__step">
+    <circle class="sub-dataflow__badge" cx="42" cy="68" r="18" />
+    <text class="sub-dataflow__badge-text" x="42" y="73" text-anchor="middle">1</text>
+    <rect class="sub-dataflow__box" x="80" y="32" width="520" height="72" rx="14" ry="14" />
+    <text class="sub-dataflow__text" x="340" y="74" text-anchor="middle">Read userId from auth context.</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/invites with userId.</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">Render returned code or surface error.</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>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>
+  <script src="../../assets/viewer.client.js" defer></script>
+</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>