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/get-invite-codes/index.html ADDED Viewed

@@ -0,0 +1,54 @@
+<!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 · get-invite-codes</p>
+        <h1 class="atlas-title">獲取邀請碼</h1>
+        <p class="atlas-meta">對外能力：已登入使用者請求系統生成新的邀請碼（生產邀請碼）。</p>
+      </header>
+      <section class="feature-story">
+        <h2>使用者故事</h2>
+        <p>使用者進入「我的邀請碼」頁面 → 按生成 → 系統檢查額度與帳號狀態 → 產生密碼學隨機字串並寫入 <code>invite_codes</code>。</p>
+        <p class="atlas-meta">
+          <strong>跨子模組交互</strong>（含 generator 的多次重試呼叫、DB UNIQUE 衝突回傳、跨功能 <code>invite_codes</code> 行被「邀請碼註冊」消費）已在<a href="../../index.html">宏觀架構圖</a>內統一呈現，本頁不重述。
+        </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-get-invite-ui</code></td><td>登入後頁面、列表、生成按鈕</td><td><a href="web-get-invite-ui.html">web-get-invite-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>invite-issuance-service</code></td><td>額度、交易、碰撞重試策略</td><td><a href="invite-issuance-service.html">invite-issuance-service.html</a></td></tr>
+            <tr><td><code>invite-code-generator</code></td><td>純函式：熵 → 字串</td><td><a href="invite-code-generator.html">invite-code-generator.html</a></td></tr>
+            <tr><td><code>postgresql</code></td><td>SQL：計數、INSERT 新邀請碼列、讀帳號狀態</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/get-invite-codes/</code></p>
+      </footer>
+    </main>
+  </body>
+</html>

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

@@ -0,0 +1,165 @@
+<!DOCTYPE html>
+<html lang="zh-Hant">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>子模組 · invite-code-generator — 獲取邀請碼</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>invite-code-generator</span>
+      </nav>
+      <header class="atlas-header">
+        <p class="atlas-kicker">Submodule · invite-code-generator</p>
+        <h1 class="atlas-title">invite-code-generator</h1>
+        <p class="atlas-meta">自身職責：把熵編碼成符合產品規格的可讀字串。<strong>無 I/O 副作用</strong>（除讀取隨機源）。本頁只列自身函式 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>NewGenerator</code></td>
+              <td class="sub-io__signature">
+                <strong>in:</strong> <code>Config{bits, alphabet, groupSize}</code><br>
+                <strong>out:</strong> <code>Generator</code>
+              </td>
+              <td><span class="sub-io__side sub-io__side--pure">pure</span></td>
+              <td>建構，驗證 <code>bits &gt;= 64</code>、字元表非空且不含易混字。</td>
+            </tr>
+            <tr>
+              <td><code>Generator.Next</code></td>
+              <td class="sub-io__signature">
+                <strong>in:</strong> —<br>
+                <strong>out:</strong> <code>string</code> | <code>ErrEntropy</code>
+              </td>
+              <td><span class="sub-io__side sub-io__side--io">io</span> 讀 <code>crypto/rand</code></td>
+              <td>單次抽碼。</td>
+            </tr>
+            <tr>
+              <td><code>encode</code></td>
+              <td class="sub-io__signature">
+                <strong>in:</strong> <code>bytes</code>, <code>alphabet</code><br>
+                <strong>out:</strong> <code>string</code>
+              </td>
+              <td><span class="sub-io__side sub-io__side--pure">pure</span></td>
+              <td>把位元組以 Crockford Base32（或同類）映射成字元。</td>
+            </tr>
+            <tr>
+              <td><code>group</code></td>
+              <td class="sub-io__signature">
+                <strong>in:</strong> <code>string</code>, <code>groupSize</code><br>
+                <strong>out:</strong> <code>string</code>
+              </td>
+              <td><span class="sub-io__side sub-io__side--pure">pure</span></td>
+              <td>每 N 位插入 <code>-</code>，便於人讀。</td>
+            </tr>
+          </tbody>
+        </table>
+      </section>
+      <section class="sub-vars">
+        <h2>變數與業務用途</h2>
+        <p class="sub-vars__intro">本子模組屬於純函式工具；下表分兩段：上半為建構時固定的設定，下半為單次 <code>Next</code> 期間的臨時值。</p>
+        <table>
+          <thead><tr><th>變數</th><th>型別</th><th>作用域</th><th>業務用途</th></tr></thead>
+          <tbody>
+            <tr>
+              <td class="sub-vars__name">Config</td>
+              <td class="sub-vars__type">{bits, alphabet, groupSize}</td>
+              <td><span class="sub-vars__scope sub-vars__scope--instance">instance</span></td>
+              <td>整個 Generator 生命週期固定；決定碼強度（bits）、可讀性（alphabet）、人讀分組（groupSize）。</td>
+            </tr>
+            <tr>
+              <td class="sub-vars__name">bits</td>
+              <td class="sub-vars__type">int</td>
+              <td><span class="sub-vars__scope sub-vars__scope--instance">instance</span></td>
+              <td>熵預算；決定隨機字串對 UNIQUE 碰撞的容忍度；過低會推高呼叫端的重試次數與失敗率。</td>
+            </tr>
+            <tr>
+              <td class="sub-vars__name">alphabet</td>
+              <td class="sub-vars__type">string</td>
+              <td><span class="sub-vars__scope sub-vars__scope--instance">instance</span></td>
+              <td>字元表；剃除 0/O、1/I/l 等易混字，業務上降低使用者抄錄錯誤率，間接提高分享成功率。</td>
+            </tr>
+            <tr>
+              <td class="sub-vars__name">groupSize</td>
+              <td class="sub-vars__type">int</td>
+              <td><span class="sub-vars__scope sub-vars__scope--instance">instance</span></td>
+              <td>每幾個字元插入連字號；只影響顯示／輸入體驗，不影響熵或唯一性。</td>
+            </tr>
+            <tr>
+              <td class="sub-vars__name">bytes / buf</td>
+              <td class="sub-vars__type">[]byte</td>
+              <td><span class="sub-vars__scope sub-vars__scope--call">call</span></td>
+              <td>從 <code>crypto/rand</code> 讀出的原始熵；只在單次 <code>Next</code> 期間活著，不持久化、不外傳，避免被推測下一次值。</td>
+            </tr>
+            <tr>
+              <td class="sub-vars__name">raw</td>
+              <td class="sub-vars__type">string</td>
+              <td><span class="sub-vars__scope sub-vars__scope--call">call</span></td>
+              <td>經 base32 編碼後尚未分組的中介字串；只是內部步驟，不對外。</td>
+            </tr>
+            <tr>
+              <td class="sub-vars__name">out / candidate</td>
+              <td class="sub-vars__type">string</td>
+              <td><span class="sub-vars__scope sub-vars__scope--call">call</span></td>
+              <td>最終回傳的候選碼；本子模組不快取、不記錄；唯一性由呼叫端結合 DB UNIQUE 保證。</td>
+            </tr>
+          </tbody>
+        </table>
+      </section>
+      <section class="sub-dataflow">
+        <h2>內部資料流（單次 Next）</h2>
+        <ol>
+          <li>從 <code>crypto/rand</code> 讀 <code>bytes[ceil(bits/8)]</code>。</li>
+          <li><code>bytes</code> → <code>encode(bytes, alphabet)</code> → <code>raw: string</code>。</li>
+          <li><code>raw</code> → <code>group(raw, groupSize)</code> → 最終字串。</li>
+          <li>內部不持有狀態（除設定）；多次呼叫互相獨立，無快取無記錄。</li>
+        </ol>
+        <svg class="sub-dataflow__svg" viewBox="0 0 720 110" role="img" aria-label="生成器資料流">
+          <defs>
+            <marker id="d-arr3" 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="50" text-anchor="middle">crypto/rand</text><text x="95" y="68" text-anchor="middle" class="d-label">→ bytes</text></g>
+          <g class="d-node"><rect x="220" y="30" width="150" height="50" rx="8"></rect><text x="295" y="50" text-anchor="middle">encode</text><text x="295" y="68" text-anchor="middle" class="d-label">bytes → raw</text></g>
+          <g class="d-node"><rect x="420" y="30" width="150" height="50" rx="8"></rect><text x="495" y="50" text-anchor="middle">group</text><text x="495" y="68" text-anchor="middle" class="d-label">raw → 字串</text></g>
+          <g class="d-node"><rect x="600" y="30" width="100" height="50" rx="8"></rect><text x="650" y="58" text-anchor="middle">candidate</text></g>
+          <line class="d-edge" x1="170" y1="55" x2="216" y2="55" marker-end="url(#d-arr3)"></line>
+          <line class="d-edge" x1="370" y1="55" x2="416" y2="55" marker-end="url(#d-arr3)"></line>
+          <line class="d-edge" x1="570" y1="55" x2="596" y2="55" marker-end="url(#d-arr3)"></line>
+        </svg>
+      </section>
+      <section class="sub-errors">
+        <h2>本子模組會拋出的錯誤</h2>
+        <table>
+          <thead><tr><th>錯誤</th><th>條件</th></tr></thead>
+          <tbody>
+            <tr><td><code>ErrEntropy</code></td><td><code>crypto/rand.Read</code> 短讀／失敗（罕見）。</td></tr>
+            <tr><td><code>ErrConfig</code></td><td><code>NewGenerator</code> 收到非法 <code>Config</code>。</td></tr>
+          </tbody>
+        </table>
+        <p class="atlas-meta">注意：「唯一性」<strong>不在本子模組</strong>；DB UNIQUE 違例由呼叫端處理（重新呼叫 <code>Next</code>）。</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/get-invite-codes/invite-issuance-service.html ADDED Viewed

@@ -0,0 +1,198 @@
+<!DOCTYPE html>
+<html lang="zh-Hant">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>子模組 · invite-issuance-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>invite-issuance-service</span>
+      </nav>
+      <header class="atlas-header">
+        <p class="atlas-kicker">Submodule · invite-issuance-service</p>
+        <h1 class="atlas-title">invite-issuance-service</h1>
+        <p class="atlas-meta">自身職責：在同一交易內判斷使用者額度、組裝待寫入列、處理 UNIQUE 碰撞重試。本頁只列自身函式 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>IssueInviteCode</code></td>
+              <td class="sub-io__signature">
+                <strong>in:</strong> <code>ctx</code>, <code>userID</code><br>
+                <strong>out:</strong> <code>InviteCodeRecord</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> 條件成立時寫入新行</td>
+              <td>對外唯一入口。</td>
+            </tr>
+            <tr>
+              <td><code>checkQuota</code></td>
+              <td class="sub-io__signature">
+                <strong>in:</strong> <code>used</code>, <code>limit</code>, <code>userStatus</code><br>
+                <strong>out:</strong> <code>true | ErrQuotaExceeded | ErrForbidden</code>
+              </td>
+              <td><span class="sub-io__side sub-io__side--pure">pure</span></td>
+              <td>窗口計數 + 帳號狀態合法性判斷。</td>
+            </tr>
+            <tr>
+              <td><code>buildRecord</code></td>
+              <td class="sub-io__signature">
+                <strong>in:</strong> <code>userID</code>, <code>code: string</code>, <code>now</code><br>
+                <strong>out:</strong> <code>InviteCodeRecord</code>
+              </td>
+              <td><span class="sub-io__side sub-io__side--pure">pure</span></td>
+              <td>組裝待寫入承載：<code>owner_user_id</code>、<code>allowed_registration=true</code>、<code>created_at=now</code>。</td>
+            </tr>
+            <tr>
+              <td><code>shouldRetryOnCollision</code></td>
+              <td class="sub-io__signature">
+                <strong>in:</strong> <code>err</code>, <code>attempt: int</code>, <code>max: int</code><br>
+                <strong>out:</strong> <code>bool</code>
+              </td>
+              <td><span class="sub-io__side sub-io__side--pure">pure</span></td>
+              <td><code>err</code> 為 UNIQUE 違例且 <code>attempt &lt; max</code> 才回 <code>true</code>。</td>
+            </tr>
+          </tbody>
+        </table>
+      </section>
+      <section class="sub-vars">
+        <h2>變數與業務用途</h2>
+        <p class="sub-vars__intro">本表盤點額度判定、寫入承載組裝、與 UNIQUE 碰撞重試所依賴的識別子。</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">userID</td>
+              <td class="sub-vars__type">UUID</td>
+              <td><span class="sub-vars__scope sub-vars__scope--call">call</span></td>
+              <td>本次發放歸屬；同時也是額度視窗的主鍵；由 <code>public-api</code> 從可信來源（Principal）注入。</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>把「額度檢查 + 帳號狀態檢查 + 寫入」綁成原子單元；避免在檢查與寫入之間出現空隙造成雙倍超發。</td>
+            </tr>
+            <tr>
+              <td class="sub-vars__name">used</td>
+              <td class="sub-vars__type">int64</td>
+              <td><span class="sub-vars__scope sub-vars__scope--call">call</span></td>
+              <td>當前滑動視窗已發放數；額度判定的「左值」；錯算即可能放行超額或誤拒。</td>
+            </tr>
+            <tr>
+              <td class="sub-vars__name">limit</td>
+              <td class="sub-vars__type">int</td>
+              <td><span class="sub-vars__scope sub-vars__scope--instance">instance</span></td>
+              <td>滑動視窗額度上限；產品設定，跨呼叫不變；改值代表產品策略改變，需配套更新文案。</td>
+            </tr>
+            <tr>
+              <td class="sub-vars__name">userStatus</td>
+              <td class="sub-vars__type">active | banned | suspended</td>
+              <td><span class="sub-vars__scope sub-vars__scope--call">call</span></td>
+              <td>帳號是否處於可發放狀態；停權或暫停狀態下立即拒絕，不浪費 generator/DB 資源。</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>created_at</code> 的基準；測試可注入。</td>
+            </tr>
+            <tr>
+              <td class="sub-vars__name">attempt</td>
+              <td class="sub-vars__type">int</td>
+              <td><span class="sub-vars__scope sub-vars__scope--loop">loop</span></td>
+              <td>UNIQUE 碰撞重試計數；搭配 <code>max</code> 限制最壞情況避免無限循環。</td>
+            </tr>
+            <tr>
+              <td class="sub-vars__name">max</td>
+              <td class="sub-vars__type">int</td>
+              <td><span class="sub-vars__scope sub-vars__scope--instance">instance</span></td>
+              <td>重試上限；超出即拋 <code>ErrCollisionExhausted</code>；上限與 generator 的熵預算共同決定罕見失敗率。</td>
+            </tr>
+            <tr>
+              <td class="sub-vars__name">candidate</td>
+              <td class="sub-vars__type">string</td>
+              <td><span class="sub-vars__scope sub-vars__scope--loop">loop</span></td>
+              <td>一輪重試取得的候選碼；尚未確定唯一；UNIQUE 違例即丟棄並重抽，不會被使用者看到。</td>
+            </tr>
+            <tr>
+              <td class="sub-vars__name">InviteCodeRecord</td>
+              <td class="sub-vars__type">{code, owner_user_id, allowed_registration, created_at}</td>
+              <td><span class="sub-vars__scope sub-vars__scope--loop">loop</span></td>
+              <td>寫入 DB 的承載；<code>allowed_registration=true</code> 是「邀請碼註冊」功能消費的關鍵旗標——關閉此值代表暫停發放但保留歷史紀錄。</td>
+            </tr>
+          </tbody>
+        </table>
+      </section>
+      <section class="sub-dataflow">
+        <h2>內部資料流</h2>
+        <ol>
+          <li>取得 <code>userID</code> + 開 <code>tx</code> → 讀<code>{used, userStatus}</code>（透過 DB 子模組；其 SQL 介面見宏觀圖邊 <code>e-B-...</code>）。</li>
+          <li><code>checkQuota</code> 不通過 → 拋 <code>ErrQuotaExceeded</code>／<code>ErrForbidden</code>；本函式直接結束（呼叫端負責回滾）。</li>
+          <li><code>candidate</code> ← 生成器產出的字串。</li>
+          <li><code>buildRecord(userID, candidate, now)</code> → <code>InviteCodeRecord</code>。</li>
+          <li>嘗試寫入；若 <code>err</code> 與 <code>shouldRetryOnCollision(err, attempt, max)</code> 為 <code>true</code>，<code>attempt+=1</code>，回到步驟 3。</li>
+          <li>寫入成功 → 提交 → 回傳 <code>InviteCodeRecord</code>。</li>
+        </ol>
+        <svg class="sub-dataflow__svg" viewBox="0 0 720 220" role="img" aria-label="內部資料流">
+          <defs>
+            <marker id="d-arr2" 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">userID</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">checkQuota</text><text x="275" y="68" text-anchor="middle" class="d-label">→ true | err</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">candidate</text><text x="465" y="68" text-anchor="middle" class="d-label">← Generator.Next()</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">buildRecord</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">shouldRetryOnCollision</text><text x="465" y="178" text-anchor="middle" class="d-label">err+attempt → bool</text></g>
+          <g class="d-node"><rect x="580" y="140" width="120" height="50" rx="8"></rect><text x="640" y="168" text-anchor="middle">InviteCodeRecord</text></g>
+          <line class="d-edge" x1="170" y1="55" x2="196" y2="55" marker-end="url(#d-arr2)"></line>
+          <line class="d-edge" x1="350" y1="55" x2="376" y2="55" marker-end="url(#d-arr2)"></line>
+          <line class="d-edge" x1="550" y1="55" x2="576" y2="55" marker-end="url(#d-arr2)"></line>
+          <line class="d-edge" x1="640" y1="80" x2="640" y2="136" marker-end="url(#d-arr2)"></line>
+          <line class="d-edge d-edge--side" x1="465" y1="190" x2="465" y2="80" marker-end="url(#d-arr2)"></line>
+        </svg>
+      </section>
+      <section class="sub-errors">
+        <h2>本子模組會拋出的錯誤</h2>
+        <table>
+          <thead><tr><th>錯誤</th><th>條件</th></tr></thead>
+          <tbody>
+            <tr><td><code>ErrQuotaExceeded</code></td><td><code>checkQuota</code> 失敗（含 <code>retryAfter</code>）</td></tr>
+            <tr><td><code>ErrForbidden</code></td><td>帳號停用</td></tr>
+            <tr><td><code>ErrCollisionExhausted</code></td><td>重試次數用盡；極罕見，視熵設計。</td></tr>
+            <tr><td><code>ErrTransient</code></td><td>連線中斷／<code>ctx</code> 取消</td></tr>
+          </tbody>
+        </table>
+      </section>
+      <footer class="atlas-meta" style="margin-top: 2rem">
+        <p><a href="../../index.html">← 宏觀架構</a> · <a href="./index.html">← 功能總覽</a></p>
+      </footer>
+    </main>
+  </body>
+</html>

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

@@ -0,0 +1,165 @@
+<!DOCTYPE html>
+<html lang="zh-Hant">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>子模組 · postgresql — 獲取邀請碼（iss 視角）</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（iss 視角）</p>
+        <h1 class="atlas-title">postgresql — 發放側操作</h1>
+        <p class="atlas-meta">
+          自身職責：對 <code>invite_codes</code> 表執行<strong>計數</strong>與<strong>插入</strong>。寫入的列會在「邀請碼註冊」功能裡被另一個視角讀取（跨功能資料流見<a href="../../index.html">宏觀架構圖</a>）。本頁只列自身 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>CountInvitesSince</code></td>
+              <td class="sub-io__signature">
+                <strong>in:</strong> <code>tx</code>, <code>userID</code>, <code>since</code><br>
+                <strong>out:</strong> <code>int64</code><br>
+                SQL: <code>SELECT count(*) FROM invite_codes WHERE owner_user_id=$1 AND created_at &gt; $2</code>
+              </td>
+              <td><span class="sub-io__side sub-io__side--io">read</span></td>
+              <td>滑動視窗計數，給呼叫端做額度判斷。</td>
+            </tr>
+            <tr>
+              <td><code>InsertInviteCode</code></td>
+              <td class="sub-io__signature">
+                <strong>in:</strong> <code>tx</code>, <code>InviteCodeRecord</code><br>
+                <strong>out:</strong> <code>InviteID</code> | <code>UniqueViolation</code><br>
+                SQL: <code>INSERT INTO invite_codes (code, owner_user_id, allowed_registration, ...) VALUES (...) RETURNING id</code>
+              </td>
+              <td><span class="sub-io__side sub-io__side--write">write</span> 新列（待 commit）</td>
+              <td><code>invite_codes.code UNIQUE</code>；衝突時呼叫端負責換碼重試。</td>
+            </tr>
+            <tr>
+              <td><code>GetUserStatus</code></td>
+              <td class="sub-io__signature">
+                <strong>in:</strong> <code>tx</code>, <code>userID</code><br>
+                <strong>out:</strong> <code>UserStatus</code> | <code>NotFound</code><br>
+                SQL: <code>SELECT status, banned_at FROM users WHERE id=$1</code>
+              </td>
+              <td><span class="sub-io__side sub-io__side--io">read</span></td>
+              <td>給呼叫端做帳號狀態檢查。</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> 上以保證原子寫入。</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--call">call</span></td>
+              <td>SQL 參數；標記新邀請碼擁有者，也是計數視窗鍵；錯誤帶入會把額度算到別人頭上。</td>
+            </tr>
+            <tr>
+              <td class="sub-vars__name">since</td>
+              <td class="sub-vars__type">timestamp</td>
+              <td><span class="sub-vars__scope sub-vars__scope--call">call</span></td>
+              <td>滑動視窗起點；決定 <code>count(*)</code> 的時段；起點漂移會讓額度執行不準。</td>
+            </tr>
+            <tr>
+              <td class="sub-vars__name">InviteCodeRecord</td>
+              <td class="sub-vars__type">{code, owner_user_id, allowed_registration, ...}</td>
+              <td><span class="sub-vars__scope sub-vars__scope--call">call</span></td>
+              <td>待插入的邀請碼資料；其欄位直接落在 <code>invite_codes</code> 列上。</td>
+            </tr>
+            <tr>
+              <td class="sub-vars__name">UserStatus</td>
+              <td class="sub-vars__type">{status, banned_at}</td>
+              <td><span class="sub-vars__scope sub-vars__scope--call">call</span></td>
+              <td><code>GetUserStatus</code> 的回傳；給呼叫端判定是否准予發放。</td>
+            </tr>
+            <tr>
+              <td class="sub-vars__name">invite_codes.code</td>
+              <td class="sub-vars__type">text UNIQUE</td>
+              <td><span class="sub-vars__scope sub-vars__scope--persist">persist</span></td>
+              <td>列上欄位；UNIQUE 約束在本子模組是「衝突信號源」，呼叫端據此換碼重試。</td>
+            </tr>
+            <tr>
+              <td class="sub-vars__name">invite_codes.owner_user_id</td>
+              <td class="sub-vars__type">FK → users.id</td>
+              <td><span class="sub-vars__scope sub-vars__scope--persist">persist</span></td>
+              <td>列上欄位；建立「誰擁有這張邀請」的關聯；額度查詢與後續審計都依此欄。</td>
+            </tr>
+            <tr>
+              <td class="sub-vars__name">invite_codes.allowed_registration</td>
+              <td class="sub-vars__type">boolean</td>
+              <td><span class="sub-vars__scope sub-vars__scope--persist">persist</span></td>
+              <td>列上欄位；發放時寫 <code>true</code>；「邀請碼註冊」功能在判定時讀此欄，<code>false</code> 即拒絕該邀請可用。</td>
+            </tr>
+            <tr>
+              <td class="sub-vars__name">invite_codes.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>NULL</code>；之後由「邀請碼註冊」標記消費，是橋接兩個功能模組的關鍵欄位。</td>
+            </tr>
+            <tr>
+              <td class="sub-vars__name">invite_codes.created_at</td>
+              <td class="sub-vars__type">timestamp</td>
+              <td><span class="sub-vars__scope sub-vars__scope--persist">persist</span></td>
+              <td>列上欄位；額度的滑動視窗計數憑此欄位，業務上要與 <code>now</code> 同步以免漂移。</td>
+            </tr>
+          </tbody>
+        </table>
+      </section>
+      <section class="sub-dataflow">
+        <h2>內部資料流（單一交易視角）</h2>
+        <ol>
+          <li>呼叫端開 <code>tx</code> → 本子模組以該 <code>tx</code> 執行 SQL；交易控制不在本子模組內。</li>
+          <li><code>CountInvitesSince</code> 與 <code>GetUserStatus</code> 為純讀；不變動列。</li>
+          <li><code>InsertInviteCode</code>：寫入後回傳 <code>InviteID</code> 或 <code>UniqueViolation</code>；<strong>無</strong> partial row。</li>
+          <li>所有寫入皆在 <code>tx</code> 內；本子模組對外只報告每個 SQL 結果。</li>
+        </ol>
+      </section>
+      <section class="sub-errors">
+        <h2>本子模組會回傳的錯誤</h2>
+        <table>
+          <thead><tr><th>錯誤</th><th>觸發 SQL</th></tr></thead>
+          <tbody>
+            <tr><td><code>UniqueViolation</code></td><td><code>InsertInviteCode</code>（<code>code</code> 已存在）</td></tr>
+            <tr><td><code>NotFound</code></td><td><code>GetUserStatus</code></td></tr>
+            <tr><td><code>ConnTransient</code></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>