chore(repo): 建立專案骨架與治理文件

納入分支策略、模組註冊表與更新日誌；建立 src 模組骨架供分支推演使用

.ai/history/release-notes.md

@@ -0,0 +1,10 @@
+# 版本分支更新日誌（對外公告用）
+
+推送遠端版本分支前，於本檔追加一節，不覆寫既有節次。每節至少包含：版本分支名與推送日期、更新項清單、影響範圍、可直接對外公告的短文。
+
+## 2.0.0.0（初始線，未推送遠端版本分支）
+
+- 推送日期：不適用
+- 更新項：無
+- 影響範圍：無
+- 公告短文：不適用

.ai/module-registry.md

@@ -0,0 +1,8 @@
+# 模組註冊表
+
+模組與菜單結構變更時，必須同步本表。
+
+| 模組 | 路徑 | 狀態 |
+| --- | --- | --- |
+| cash-sale | src/modules/cash-sale.ts | 已註冊 |
+| pickup-point | src/modules/pickup-point.ts | 已註冊 |

git-branching.md

@@ -0,0 +1,101 @@
+# Git Branching（分支策略）
+
+本文件定義本專案的分支層級、本地與遠端的一致性、版本分支的誕生、合併流向與分支刪除機制。所有功能開發與版本演進一律遵循。
+
+## 分支層級
+
+```text
+功能分支（feature/<scope>）
+    ↓ 先合併
+版本分支（x.y.z.n，例如 2.0.0.2）
+    ↓ 再合併
+整合版-dev（主分支）
+```
+
+- **功能分支**：一個功能一個分支，可依需要獨立開；日常開發與驗證都在此進行。
+- **版本分支**：承接該版本的全部功能分支，是版本驗收與回歸的基準。
+- **整合版-dev**：主分支，只接受來自版本分支的合併。
+
+## 本地與遠端的一致性
+
+- **主分支（`整合版-dev`）與版本分支（`x.y.z.n`）必須與遠端同名分支保持一致**：本地不得長期領先或落後；收斂與推送要在同一輪完成。
+- **其餘本地分支預設不推遠端**：功能分支刻意留在本地，遠端不建立對應引用，遠端倉庫只保留主分支與版本分支，提交歷史因此保持乾淨。
+- 所以「功能分支不在遠端」是策略，不是缺失；但功能分支的內容必須經由版本分支流向主分支，才會落到遠端。
+
+## 版本分支的誕生與編號
+
+- 新版本分支從**最新的已驗收版本分支**切出（例如 `2.0.0.5` 自 `origin/2.0.0.4`），不從主分支或更舊的版本切。
+- 編號遞增，跳號不補（`2.0.0.3` 缺號是歷史事實，不回填）。
+- **建立時必須明確 upstream**：`git branch <新版本> origin/<舊版本>` 會讓新分支自動追蹤舊版本分支，直接推送就會把新版本內容推進舊版本分支。建立後立即改成追蹤遠端同名分支；同名遠端分支尚未存在時，先 `--unset-upstream`，待首推送後再設定。
+- 版本分支**統一保留**，不刪除，作為歷史演進留檔。
+
+## 功能分支的起點與位置
+
+- 功能分支**從目標版本分支切出**，不要從其他版本線或主分支切：切錯起點會把別條版本線的內容一起帶進目標版本（例：從 `2.0.0.2` 線切，併入 `2.0.0.5` 時連帶把 `docs/permissions-inventory.md` 帶上）。
+- 功能分支**留在本地、不推遠端**（見「本地與遠端的一致性」）。
+- 分支命名 `feature/<scope>`；需長期保留者加 `keep/` 前綴。
+
+## 合併流向
+
+1. 新功能開發從**目標版本分支**獨立開功能分支。
+2. 功能分支**先合併入版本分支**，**再由版本分支合併入整合版-dev**。
+3. 功能分支不得直接合併進整合版-dev；版本分支不得跳過驗收直接改動。
+4. **落到版本分支一律用 merge，不得用 cherry-pick**：cherry-pick 會為同一份改動造出第二個 SHA（本專案已發生：`0076dc0b` 與 `9748463e` 同一份改動），之後的合併會讓兩個 SHA 同時進入歷史，形成疊影與後續撞點。
+5. 合併前先算兩側改動的交集做衝突預檢；合併後對自動合併檔**逐側比對**，確認雙方業務改動都保留（禁止盲目 `--ours`／`--theirs`）。
+
+### 例外（可直接進主分支）
+
+- 極小改動（例如文案錯字、單行修正）。
+- 上線後需要調整的參數配置（例如環境位址、開關預設值）。
+
+例外情況才可直接進整合版-dev；其餘一律走「功能分支 → 版本分支 → 整合版-dev」。
+
+## 驗收與收斂
+
+- 版本分支是該版本的驗收基準；**驗收通過後才把版本分支合併進 `整合版-dev`**。
+- 尚未驗收的版本分支不得進主分支；主分支落後於版本分支，即視為待辦的收斂項。
+
+## 推送版本分支的更新日誌（公告用）
+
+推送遠端版本分支（`x.y.z.n`）前，必須先寫好本次的更新日誌，內容用於對外公告；日誌未寫不得推送。
+
+- 落點：`.ai/history/release-notes.md`，每次推送版本分支追加一節，不覆寫既有節次。
+- 時機：推送**前**完成，內容與該次推送的實際提交一致；推送後補寫不算。
+- 每節至少寫四項：
+  - 版本分支名與推送日期；
+  - 更新項清單（只寫使用者能感受到的行為變化，不逐條抄提交訊息）；
+  - 影響範圍（涉及哪些模塊／頁面、是否需後端同步、是否含破壞性變更）；
+  - 可直接對外公告的短文（一至兩句）。
+- 含破壞性變更或需後端同步時，另在 `.ai/history/breaking-changes.md` 或對接文檔留痕，細節不在此展開。
+- 建立版本分支時的**首次推送**（分支上尚無內容）不強制寫日誌；其後每次帶內容的推送都必須先寫。
+- 版本分支以外的推送（功能分支、整合版-dev）不強制；但合併進版本分支的那一次仍照上辦理。
+
+## 分支命名
+
+- 版本分支：`x.y.z.n`，如 `2.0.0.2`；與遠端同名分支保持同步。
+- 功能分支：`feature/<scope>`，`scope` 用變更主題的小寫英文短語，如 `feature/pickup-point-setting`。
+- 需長期保留的功能分支：以 `keep/` 前綴標註（例如 `keep/<scope>`），使其不被刪除機制回收。
+
+## 刪除機制
+
+**本機分支**符合下列任一情況時應刪除：
+
+- **落後於版本分支 3 個版本以上**。
+- **已建立新的對應功能分支**（舊分支被取代）。
+- **內容已完整落在版本分支或主分支**（含以 merge 承接），本機已無獨有提交。
+
+可額外保留的分支：
+
+- 尚未併入版本分支的功能分支。
+- 已標註需長期保留的功能分支（`keep/` 前綴）。
+
+**遠端分支**：
+
+- 遠端只保留主分支與版本分支；功能分支不推遠端。
+- 版本分支**統一保留**，不刪除，作為歷史演進留檔。
+
+## 與其他規則的關係
+
+- 提交訊息格式見 `git-commit-message.md`。
+- 迭代完成後，被新實作取代的舊實作須移除，見 `legacy-removal.md`。
+- 模組與菜單結構的變更需同步 `.ai/module-registry.md`。

src/main.ts

@@ -0,0 +1,13 @@
+/**
+ * 沙盤推演的應用入口
+ * 僅用於演示分支流向，不承載真實業務
+ */
+
+/** 應用名稱 */
+export const APP_NAME = "game-admin";
+
+/** 目前對外公告的版本號 */
+export const APP_VERSION = "2.0.0.0";
+
+/** 匯出服務端點（示範例外直進主分支的參數配置） */
+export const EXPORT_ENDPOINT = "https://api.example.com/export";

src/modules/cash-sale.ts

@@ -0,0 +1,21 @@
+/**
+ * 現金銷貨模組（沙盤推演示意）
+ */
+
+/** 模組識別碼 */
+export const CASH_SALE_MODULE = "cash-sale";
+
+/** 提交出口模式 */
+export type SubmitMode = "draft" | "final";
+
+/**
+ * 統一提交出口，集中處理防重入與未完成條件
+ * @param mode - 提交模式（草稿或正式送出）
+ * @returns 是否送出成功
+ */
+export const submit = (mode: SubmitMode): boolean => {
+  // 草稿模式不做未完成條件阻擋
+  if (mode === "draft") return true;
+  // 正式送出需通過 blockers 清單
+  return true;
+};

src/modules/pickup-point.ts

@@ -0,0 +1,14 @@
+/**
+ * 取貨點倉庫設定模組（沙盤推演示意）
+ */
+
+/** 取貨點預設出庫倉綁定 */
+export interface PickupPointPreset {
+  /** 取貨點唯一識別碼 */
+  pickupPointId: string;
+  /** 綁定的倉庫組合識別碼，未綁定為 null */
+  warehouseSettingsSalesMaterialsGroupId: string | null;
+}
+
+/** 查詢取貨點預設綁定 */
+export const listPreset = (): PickupPointPreset[] => [];