正式產品已經敲定的架構:總整理

耀達 Lite 雲端進銷存.說明文件.2026-11-19 整理.來源是 docs\architecture\ 的十個檔(以 2026-11-19 工作目錄裡的內容為準,含當天還沒 commit 的修改)

這一頁把 2026-11-17 到 2026-11-19 之間 Jesse 已經選定的架構決定放在一起看:先一張總圖、一張一覽表,再用一個請求(訂單結案)把各題串起來,接著每一題一張卡。 每張卡只寫「選了什麼、長什麼樣、為什麼、代價、沒選的、驗證到哪裡、出處」;當時的討論經過、查到的原文與網址、更細的代價,都在各主題的決策檔裡,這一頁不重抄。
怎麼讀標記: 實測過 後面會寫是在哪個環境、哪一天跑的; 沒實測 沒編譯 推論 照來源檔的字寫; 還沒裁 是 Claude 提過、Jesse 沒有裁的內容,放進來只是為了讓定案看得懂,不算定案。
頁面上的 SQL、C#、JSON 都是從決策檔原樣複製的(只拿掉 markdown 縮排),程式碼前面那一行寫的是來源檔自己的標示(示意、沒編譯、實測過)。 決策檔整份 SQL 的總標示是:「SQL 都是示意,表名、欄名還沒定」(data-model.md 開頭)。

1. 總圖

框裡每一行、每一支箭頭都在圖下的對照表裡找得到是哪一題定的。窄螢幕時這張圖可以左右滑。

A 瀏覽器:前端 TypeScript A1 原型的畫面程式搬成 TypeScript,寫法不變,不用框架 A2 金額自己算(BigInt+小數位數),存檔時後端重算 A3 AI 迴圈、對話紀錄、系統提示、畫面動作、先問再改的卡片 A4 Cookie(HttpOnly)裡只有一串亂碼 A5 「今天」與時間的字都由後端給 B1 ↓ POST /api/c/公司編號/動作(body 是 JSON,帶 Cookie) B2 ↑ 成功回 JSON;做不成回狀態碼+Problem Details C Amazon Cognito managed login 登入頁 登入、註冊、忘記密碼 LiteERP 不經手密碼 C1 整個導過去, 登入完導回來 C2 後端拿到這個人的 sub 與 e-mail,自己建登入紀錄 D OpenRouter LLM(定案) STT、TTS(首選, 實測過才定案) D1 轉送端點:確認登入、 加金鑰與模型、記用量 E 後端:一支 C#/.NET 10 程式(模組化單體) E1 一個動作一個端點、一律 POST,啟動時掃描掛上 E2 執行器統一包:身分、權限、交易與公司、操作紀錄 帳號與公司 進銷存本體 報表 操作紀錄 AI 助理 E3 五個模組,一個模組一個專案(DLL),模組之間直接呼叫 E4 AI 助理模組:轉送端點+「列出我能叫的動作」+記用量 E5 全部手寫 SQL+Dapper;SQL 照單據集中 E6 登入紀錄表+Cookie 認人;公司編號每個請求自己帶 E7 明細用一包 JSON 傳進 SQL E8 資料表升級的工具自己寫一小支 E9 交付的是一個容器映像檔,三個場景都跑它;雲端放 AWS F1 每次碰資料庫都在一筆交易裡,開頭 set_config 設公司 G PostgreSQL account 帳號與公司 core 進銷存本體 oplog 操作紀錄 G1 一個模組一個 schema;共用資料表+公司編號(主鍵最前面) G2 列層級安全性:每張帶公司編號的表 enable+force G3 三個角色:建表與升級/程式(讀寫)/報表(唯讀)
圖 1 總圖。框裡的字母數字對到下面的對照表
圖上內容哪一題
A1原型的畫面程式搬成 TypeScript、寫法不變;不用 React、Vue、Angular,不用現成元件庫;前端不放業務規則前端第 1 題
A2前端自己算金額、後端存檔時重算;不一樣就擋下來換成後端的數字;前端數字是大整數+小數位數前端第 2、3、4 題
A3對話的迴圈在瀏覽器;系統提示與動作清單前端組;畫面動作的定義在前端;目錄一直帶著、要用再載入AI 第 2、3、5、6 題
A4登入紀錄的亂碼放在 HttpOnly 的 Cookie後端第 8 題
A5後端排好時間的字、前端全站一個由後端給的「今天」資料模型第 11 題
B1一個動作一個端點、一律 POST、參數全在 body;公司編號每個請求自己帶,放在網址(/api/c/7/…,寫法是例子)後端第 4、9 題;Cookie 見第 8 題
B2狀態碼分大類+統一的 JSON(Problem Details)後端第 10 題
C、C1、C2登入與註冊整個導到 Cognito 的登入頁;導回來後我們拿到 sub 與 e-mail、建自己的登入紀錄後端第 7 題、第 8 題
DLLM 走 OpenRouter 是定案;STT、TTS 是首選、實測後才定案AI 第 4 題
D1轉送端點只做三件事:確認登入、加金鑰與模型、記用量AI 第 5 題(金鑰不進瀏覽器是第 2 題)
E模組化單體、C#/.NET、.NET 10整體形狀第 1 題、後端第 1、3 題
E1、E2一個動作一個類別+統一的執行器,啟動時掃描自動掛 Minimal API 端點;執行器與動作的框架放在 Shared,「問現在是誰、有沒有權限」「寫操作紀錄」在 Shared 只定介面、由帳號與公司、操作紀錄模組實作;讀 JSON 時嚴格檢查形狀;權限清單(功能項目+四種動作)在 Shared;操作紀錄的白話由後端在同一筆交易裡產生後端第 5 題、模組第 6 題、後端第 14、15、16 題
E3粗切五塊、直接呼叫、一個模組一個專案(專案名稱 LiteErp. 開頭)模組第 1、2、4、7 題
E4AI 助理模組剩轉送端點、列出動作的 API、記用量AI 第 5 題(modules.md 第 2 題後面的補記)
E5全部手寫 SQL+Dapper;SQL 照單據集中後端第 2、6 題
E6登入紀錄表+Cookie;「現在是哪一家公司」每個請求自己帶後端第 8、9 題
E7明細用一包 JSON(jsonb_to_recordset)後端第 11 題
E8升級工具自己寫一小支後端第 12 題
E9容器為準;雲端放 AWS部署第 1、2 題
F1每筆交易開頭 set_config 設公司編號資料庫第 2 題
GPostgreSQL資料庫第 1 題
G1一個模組一個 schema(員工表在 account、對照表跟著自己的模組);共用資料表+公司編號放主鍵最前面模組第 5、8、9 題、多家公司第 1 題
G2、G3列層級安全性的設法與三個角色;報表的角色唯讀資料庫第 2 題、模組第 3 題

2. 所有決定一覽 62 列

「—」是那一題本來就不是能實測的東西(選語言、選切法),或來源檔沒寫驗證。題號點下去跳到那一張卡。

主題題定了什麼哪一天驗證狀態
整體形狀第 1 題模組化單體:一支後端程式照業務分模組、配一個關聯式資料庫,前端另外一份;後端不記狀態2026-11-17沒實測(「一台資料庫每秒能處理幾千筆簡單交易」是一般經驗)
模組第 1 題粗切五塊:帳號與公司、進銷存本體、報表、操作紀錄、AI 助理2026-11-17—
模組第 2 題模組之間直接呼叫公開的 C# 介面,同一筆資料庫交易2026-11-17沒驗過(把同一條連線與交易傳過去的做法)
模組第 3 題報表自己寫 SQL 直接讀本體的表,資料庫帳號唯讀2026-11-17報表角色唯讀:實測過 2026-11-18(database.md 第 2 題)
模組第 4 題一個模組一個專案(一個 assembly DLL、public/internal、專案參考)2026-11-17—
模組第 5 題資料庫裡一個模組一個 schema(account、core、oplog),SQL 一律寫出 schema2026-11-19實測過 2026-11-19,PostgreSQL 17.12
模組第 6 題Shared 只放白名單(四類,加上後端第 15 題的權限清單是五類);不參考任何模組、不准有碰資料表的 SQL2026-11-19沒寫過
模組第 7 題專案與命名空間用 LiteErp 開頭2026-11-19—
模組第 8 題員工資料表歸帳號與公司模組,別的模組的 SQL 只能唯讀 join account.employee2026-11-19沒驗證(掃描的測試沒寫過)
模組第 9 題對照表跟著自己的模組放,操作紀錄的種類自己一張2026-11-19—
多家公司第 1 題共用資料表+公司編號,公司編號放每張表主鍵的最前面2026-11-17查官方文件
多家公司示範公司不存每人一家示範公司,改成初始盤點頁「載入示範資料」2026-11-17—
資料庫第 1 題PostgreSQL2026-11-17查官方文件
資料庫第 2 題列層級安全性:每張帶公司編號的表 enable+force、每筆交易開頭 set_config、三個角色2026-11-17實測過 2026-11-18,postgres:17(17.12)
資料模型第 1 題刪除時整筆存成 JSON 搬到一張共用的回收桶表、再從原表真的刪掉;過期的真的刪2026-11-18實測過 2026-11-18,PostgreSQL 17.12(刪了再復原)
資料模型第 2 題id 用 bigint generated by default as identity,主鍵(公司編號,id)2026-11-18沒有單獨的實測(檔尾實測的表照第 1~6 題的例子建)
資料模型第 3 題庫存用異動表+現有量表,存單時同一句 SQL 全刪重寫異動、照實際列數加減現有量2026-11-18實測過 2026-11-18,PostgreSQL 17.12(四個情境、同時存、1,500 次交易、60 萬列執行計畫)
資料模型第 4 題種類、狀態欄位用 smallint+C# enum+不分公司的對照表2026-11-18對照表只能讀:實測過 2026-11-18
資料模型第 5 題單頭版本欄位,後存的被擋2026-11-18實測過 2026-11-18
資料模型第 6 題別張單累計的數字存起來;存檔時先鎖被影響的那張單(版本加 1)再從來源重算2026-11-18實測過 2026-11-18
資料模型第 7 題每樣商品每個月的單位成本表,存單時同一筆交易往後重算2026-11-18實測過 2026-11-18(跟手算一樣);組合商品那一輪 沒跑
資料模型第 8 題金額、單價、數量、單位成本用 domain 自訂四個型別,位數多了報錯2026-11-18實測過 2026-11-18
資料模型第 9 題不分公司的表不加列層級安全性、壓到最少,SQL 只放帳號與公司模組,報表角色不給權限2026-11-18實測過 2026-11-18(database.md 第 2 題)
資料模型第 10 題單據日期 date、時間戳記 timestamptz,第一次啟動時指定時區(預設 Asia/Taipei)2026-11-18實測過 2026-11-18,PostgreSQL 17.12 官方容器
資料模型第 11 題後端排好時間的字,前端全站只有一個由後端給的「今天」2026-11-18實測過 2026-11-18,Node 26
資料模型第 12 題店的身分記在單據上,改設定不整批重算2026-11-18沒實測
資料模型第 13 題一種單據一組表(單頭表+明細表)2026-11-19沒實測
資料模型第 14 題改單時明細全部逐列比對(id 不變、多一欄 line_no,刪、改、加三句)2026-11-19實測過 2026-11-19 下午補跑
資料模型第 15 題有課稅別的 9 種單據,單頭存未稅、稅額、總金額2026-11-19對帳與算術:實測過 2026-11-19 下午補跑
資料模型第 16 題會進報表的 6 種單據,每一列分到的金額存在明細上2026-11-19建表與對帳:實測過 2026-11-19 下午補跑
資料模型第 17 題按兩下儲存、網路重送:新增時帶 create_token,單頭上設唯一2026-11-19沒跑過
資料模型第 18 題每張表只加 created_at timestamptz not null default now(),不加最後修改時間2026-11-19沒建過表、沒跑過
後端第 1 題C#/.NET2026-11-17—
後端第 2 題資料存取全部手寫 SQL+Dapper,不用 EF Core2026-11-17PREPARE 的做法沒跑過
後端第 3 題.NET 102026-11-19查官方支援頁
後端第 4 題API 全部照動作排、一律 POST,參數全在 body2026-11-19查微軟文件,沒實際跑過
後端第 5 題一個動作一個類別+統一的執行器,啟動時掃描掛 Minimal API 端點2026-11-19C# 沒編譯過
後端第 6 題SQL 照單據集中:一種單據一個 C# 檔,每句是有名字的常數2026-11-19沒編譯、SQL 沒跑過
後端第 7 題登入與註冊整個導到 Amazon Cognito 的登入頁2026-11-19全部是讀文件,沒開 user pool 試過
後端第 8 題登入狀態用登入紀錄表+Cookie2026-11-19SQL:實測過 2026-11-19 下午,PostgreSQL 17.12
後端第 9 題「現在是哪一家公司」每個請求自己帶,登入紀錄不記公司;補裁:公司編號放網址2026-11-19問的當下沒跑;同一天下午補跑了認人與查成員併成一句(腳本沒留,是不是原樣不確定)
後端第 10 題做不成時回狀態碼分大類+統一的 JSON(Problem Details)2026-11-19示意(代號、欄位名稱、狀態碼對照都還沒定)
後端第 11 題明細用一包 JSON 傳進 SQL(jsonb_to_recordset)2026-11-19SQL 這一邊:實測過 2026-11-19;C# 沒編譯
後端第 12 題資料表升級的工具自己寫一小支2026-11-19鎖、整支退回、換行:實測過 2026-11-19,PostgreSQL 17.12
後端第 13 題自動測試從 HTTP 打進去、接真的 PostgreSQL,每個測試一家新公司2026-11-19沒寫過、沒跑過(查微軟文件與 Context7 套件說明)
後端第 14 題請求的 JSON 形狀在讀取時嚴格檢查,業務規則寫在動作裡2026-11-19查微軟官方文件,沒寫過、沒跑過
後端第 15 題權限項目:一份清單放 Shared,功能項目+讀取/新增/修改/刪除2026-11-19沒寫過
後端第 16 題操作紀錄的「內容」由後端在存檔的同一筆交易裡產生白話、存成文字2026-11-19沒寫過
前端第 1 題把原型的畫面程式搬成 TypeScript、寫法不變;不用框架與現成元件庫;前端不放業務規則2026-11-17—
前端第 2 題畫面上的計算前端自己算,後端只在存檔時重算2026-11-17—
前端第 3 題存檔時兩邊算的不一樣:擋下來、畫面換成後端的數字、再按一次才存2026-11-17—
前端第 4 題前端的數字用大整數+小數位數,傳輸用字串,兩邊照同一組運算規則2026-11-17沒實測
AI 助理第 1 題畫面和 AI 共用同一批後端動作2026-11-17—
AI 助理第 2 題對話的迴圈由瀏覽器全權處理;問 LLM 一律經過後端的轉送端點2026-11-19—
AI 助理第 3 題「AI 叫之前要不要先問」在後端動作的定義上明寫,沒寫不能啟動;補裁:畫面動作的定義在前端2026-11-19—
AI 助理第 4 題LLM 走 OpenRouter;補裁:STT、TTS 以 OpenRouter 為首選,實測後才定案2026-11-19查官方文件;語音 沒實測
AI 助理第 5 題轉送端點只轉送;後端多一支「列出我能叫的動作」的 API,系統提示與動作清單由前端組2026-11-19沒實作、沒實測
AI 助理第 6 題幾百個動作:目錄一直帶著、要用再載入,前端自己做2026-11-19沒寫過、沒實測
AI 助理第 7 題不給 AI 通用查詢動作2026-11-19—
部署第 1 題容器為準:交付一個映像檔,三個場景都跑它2026-11-17實測過 2026-11-17,Jesse 的 PC 裝 Docker Desktop 4.99.0
部署第 2 題雲端放 AWS2026-11-17查 AWS 公開價目檔
紀錄放哪裡(README)架構決定放 docs\architecture\,一個主題一個檔+對照表2026-11-17—

3. 貫穿的原則

只收來源檔裡有明文的。每一條寫出它在哪裡講的,以及哪幾題明寫是從它出發或受它影響。

一、AI 一開始就要算進架構

Jesse 2026-11-17 的原話(ai-assistant.md「Jesse 的要求」):「AI 的支援一開始就要有,意思是說一開始就要考慮使用 LLM 對話的方式操控頁面,新增修改查詢各種單據,變更設定項等等。對話的方式可以是打字也可以是語音。這是一開始就要考慮進架構的事。」README.md 因此規定每一題都要把 AI 助理算進去。

影響到的:後端第 1 題(一份 C# 型別同時產生 API 與給 AI 的動作說明)、資料庫第 2 題(AI 照叫它做的那個人、那家公司走同一套交易開頭的設定)、資料模型第 5 題(AI 改單走同一批動作、規則一樣)、部署第 1 題(AI 跟著同一包走)、第 2 題(不管放哪個雲,這一題不卡它),以及整個 AI 助理那一章。

二、畫面和 AI 共用同一批後端動作

AI 第 1 題(2026-11-17):每個操作在後端都是一個有名字、有參數格式的「動作」,畫面的按鈕叫它,AI 也叫它。

影響到的:後端第 4 題(「已經定的」就是這一條,一個 C# 請求型別同時是 API 的格式與給 AI 的動作說明)、第 5 題(HTTP 與 AI 都只經過同一個執行器)、AI 第 2 題(AI 叫後端動作時,瀏覽器打跟按鈕一樣的 /api/...)、第 7 題(只叫現有的查詢與報表動作)、資料模型第 5 題。

三、後端提供 Web API 就好,前端長什麼樣子後端不管

Jesse 2026-11-19 的原話(ai-assistant.md 第 2 題「理由」):「我的意思是說, 後端提供 WEB API 就好, 前端長甚麼樣子後端不 CARE, 如果是這樣 AI 邏輯跟著前端跑比較適合」;前一句是「我將來可能會有十種 UI, 後端不可能都知道這些 UI 長甚麼樣子吧」。來源檔接著寫:「之後「放前端還是放後端」的題目都從這個原則出發。」(十種 UI 是只換外觀、還是連頁面與功能都不同,他沒回答。)

影響到的:AI 第 2 題、第 3 題的補裁(畫面動作的定義放前端)、第 5 題(系統提示與動作清單由前端組)、第 6 題(找動作完全在前端)、第 7 題(理由 2:後端不用為 AI 多做任何東西)、前端「AI 帶進前端的」。

四、前端的程式 Jesse 不審,只審後端;成品要跟原型高度一致

Jesse 2026-11-17 的原話(frontend.md):「基本上前端的程式碼我不 review,我只會 review 後端的程式碼。所以我不太 care 前端是用甚麼寫的。再者,我要求成品的網頁看起來跟使用起來的感覺要跟目前的 prototype 高度一致」。

影響到的:前端第 1 題(搬原型的畫面程式;隨這題一起定了前端不放業務規則、不用現成的元件庫)、第 2 題(前端能算的只有金額)、後端第 2 題(理由第一條:Jesse 審得到每一句 SQL)、資料模型第 11 題(理由:時區整個留在後端,前端沒有地方會寫錯)、AI 第 5 題(代價:系統提示在前端,Jesse 審不到)。

五、LiteERP 不需要知道使用者的密碼

Jesse 2026-11-19 的原話(backend.md 第 7 題):「我以為是把整個登入過程導入到認證商, 認證商確認是這個人無誤後給我們這個人的代碼」「prototype 中登入與註冊的畫面可以打掉重來. 然後我的要求不是使用者有沒有密碼, 而是 LiteERP 不需要知道使用者的密碼」。

影響到的:後端第 7 題(定案:整個導到 Cognito;自己做與 Keycloak 因此排除)、第 8 題(不管誰確認身分,導回來之後的登入狀態還是我們記)、資料模型第 9 題(密碼與驗證碼的表不需要了,login_session 成為第四張不分公司的表)。

六、算出來的數字全站只能有一個來源

模組第 3 題(2026-11-17,寫在題目裡、Jesse 選的時候看得到):「凡是靠業務規則算出來的數字,全站只能有一個來源,報表不自己再算一次。」

影響到的:資料模型第 3 題(「已經定的」第一項)、第 7 題(理由:全站只有這一個來源)、AI 第 7 題(理由 1:AI 講的每個數字都跟報表同一個來源)。

七、單據自己帶著事實:只看單據、不整批重算

資料模型第 12 題(2026-11-18,做法是 Jesse 自己提的):「這張單的稅拿不拿得回來只看單據上的欄位,存單時算好。公司那一欄改了只影響之後開的單,沒有「設定改了全部重算」這個動作。」理由寫的是「存起來的衍生資料(value、每月成本)只會因為單據存檔而變,跟第 3、6、7 題同一個路子」。

影響到的:資料模型第 7 題(代價裡「店的預設發票別改了要全部重算」不再成立)、第 15 題(理由:舊單的數字不動,「跟第 12 題「單據自己帶著事實」同一個方向」)。

八、列層級安全性是唯一一道自動的鎖

database.md 第 2 題的起因:後端定了全部手寫 SQL+Dapper、不用 EF Core,「沒有工具自動加公司編號的條件,這一道變成唯一一道自動的鎖」。backend.md 第 2 題的代價第一條也是這句。

影響到的:資料庫第 2 題、後端第 5 題(每次碰資料庫都要在交易裡並設公司編號,所以共同步驟只能有一份)、資料模型第 9 題(不分公司的表沒有這道保險,所以壓到最少)。

4. 一個請求從頭到尾:訂單結案

例子是 後端第 5 題問的時候用的:訂單結案從按鈕到資料庫的八步,「讀 JSON、確認身分與公司、檢查權限、開交易設公司、動作自己的事、寫操作紀錄、提交、回 JSON」,只有「動作自己的事」每個動作不一樣。下表每一步只寫來源檔有的內容,右欄是哪一題定的。

執行器在 Shared;第 2、3 步「問現在是誰、是不是成員、有沒有權限」與第 6 步「寫操作紀錄」,在 Shared 只定介面,由帳號與公司模組、操作紀錄模組實作;權限項目的清單也在 Shared(模組第 6 題、後端第 15 題)。自動測試也是從這八步的入口打進去(後端第 13 題)。
AI 叫動作時也是這八步:2026-11-19 AI 第 2 題定了迴圈在瀏覽器之後,AI 叫動作時瀏覽器打跟按鈕一樣的端點,執行器的入口只剩 HTTP 一個(backend.md 第 5 題最後一段)。
步做什麼實際長怎樣哪一題
0(之前)登入瀏覽器整個導到 Cognito 的登入頁,登入成功導回來;後端拿到 sub 與 e-mail,在 login_session 寫一列(一台裝置一列),亂碼只放在瀏覽器的 HttpOnly Cookie,表裡只存雜湊。後端 7、8
1讀 JSONPOST /api/c/7/sales-order/close,body 是 { "id": 7, "version": 3 },只有動作自己的參數。公司編號放在網址(c/7 這個寫法是例子;後端第 9 題同一天補裁);沒有公司的動作網址沒有 c/7 那一段。sales-order/close 這種名稱的寫法也是例子(第 4 題)。讀 JSON 與驗證由執行器自己做,不靠 Minimal API 內建的參數繫結;讀的時候嚴格檢查形狀(少欄位、型別不對或是空的、多了不認得的欄位),內容合不合規則留給動作。後端 4、9、5、14
2確認身分與公司Cookie 裡的亂碼取雜湊,跟請求帶的公司編號一起查一句:login_session join company_member(SQL 見後端第 8 題)。查不到列=沒登入,或不是這家公司的成員,一起擋。沒登入回 401、不是成員回 403(對照表是示意)。後端 8、9、10
3檢查權限動作類別上標「哪一個功能項目的哪一種動作」,例子是 [Action("sales-order/close", "把訂單結案", Feature.SalesOrder, Act.Edit, Ai = AiUse.Confirm)](示意;權限清單在 Shared,跟權限設定頁的列一一對應);上一步那句 SQL 一起拿回成員的 m.role_id(示意,成員與權限的表還沒設計)。沒權限回 403。後端 5、15、8、10
4開交易、設公司begin; 然後 select set_config('app.company_id', '42', true);(true=只在這筆交易有效)。之後每張帶公司編號的表都被列層級安全性的規則管著(SQL 見資料庫第 2 題):讀不到、也寫不進別家的列。資料庫 2、後端 5
5動作自己的事CloseSalesOrder.RunAsync 用名字引用 SalesOrderSql.Close(C# 與 SQL 見後端第 5 題、第 6 題):版本對得上才改、版本加 1、回傳新的版本。影響 0 列=被改過或被刪了,丟 StaleVersionException,整筆退回;對照表裡「版本對不上」是 409。SQL 實作時要寫出 schema(例子沒寫)。後端 5、6、資料模型 5、模組 5、後端 10
6寫操作紀錄ctx.Log("訂單結案", req.Id)(第 5 題的示意),跟存檔同一筆交易(模組之間直接呼叫、同一筆交易)。「內容」那一段白話由後端產生:存完再讀一次這一筆(含客戶、商品的名稱)、排成字、存成文字;前端不產生、也不傳。程式的角色對 oplog 只有 select、insert,改、刪都 permission denied(2026-11-19 實測)。AI 叫的動作,請求上的「(AI 助理)」由瀏覽器標,後端照記。後端 5、16、模組 2、5、AI 2
7提交commit; 之後 set_config(..., true) 設的公司編號就失效。同一條連線的下一筆交易如果忘了設,current_setting 拿到空字串、轉 bigint 時報錯(2026-11-18 實測),不會悄悄查到別家。資料庫 2
8回 JSON成功 → 200 { "version": 4 }。做不成時是狀態碼分大類+application/problem+json,內容有固定的代號與一句說明。後端 4、10

5. 三個部署場景與整體形狀

Jesse 2026-11-17 定的三個場景(README.md):

  1. 在某台本地端的 PC 上架設,供內部測試。
  2. 架設在雲端,同時服務幾十個 user。
  3. 架設在雲端,同時服務幾萬個 user。
還沒確認:「幾萬個 user」到底是同時在線還是註冊數。Claude 先當成最嚴格的讀法(幾萬人同時在線,粗估每秒 1,000~3,000 個請求,估的、沒實測),Jesse 沒有糾正也沒有確認(overall-shape.md「開談前的事實」與「選完之後還開著的」)。

整體形狀第 1 題模組化單體 2026-11-17

選的:一支後端程式,裡面照業務分模組,配一個關聯式資料庫,前端另外一份。後端不記狀態,可以開很多份。(Claude 推薦,Jesse「我選 A」)

白話與例子
三個場景怎麼放:① 一台 PC 裝程式+資料庫;② 雲端一台小主機+資料庫;③ 同一支程式開很多份+負載平衡,資料庫加大。三個場景是同一份程式,差別在開幾份、機器多大。開談前的事實:存一張銷貨單,庫存、應收、成本、操作紀錄要一起變,而且要全部成功或全部沒發生;報表都是跨單據算的。
理由
  • 連動在同一個資料庫交易裡完成,失敗整個退回,資料庫本來就會做。
  • 報表直接用 SQL 把好幾種單據合起來算。
  • 場景 ① 測到的跟場景 ③ 線上跑的是同一支程式。
  • Jesse 一個人開發,一支程式最好懂、最好除錯;模組邊界先切乾淨,以後某一塊太忙再單獨搬出去。
  • 場景 ③:後端不記狀態就能一直加開,瓶頸會在資料庫,到時候有唯讀複本、照公司分庫這些路。
代價
  • 模組邊界靠紀律維持;直接讀別的模組的資料表,就開始變成一團。
  • 一次部署是全部一起上線,一處出錯整支受影響;要有自動測試、要能很快退回上一版。
  • 整支用同一種語言與框架。
  • 某個模組特別吃資源時不能只加開它,要整支加開。
  • 資料庫只有一個,它停了全部停,要有備份與備援。
  • (這幾條是寫說明頁時補上的,選的時候沒有逐條講。)
沒選的
  • B 微服務:一張單連動四個地方會變成跨服務的分散式交易,要自己寫補償;報表要跨服務拿資料;它的好處是各團隊能獨立上線,一個人開發用不到。
  • C 無伺服器平台(例如 Cloudflare Workers+D1):程式綁在一家平台;D1 的 10 GB 與單執行緒會逼成一家公司一個資料庫;場景 ① 只能用開發工具模擬。
  • D 後端即服務(Supabase、Firebase 這類):成本計算、沖帳這類複雜規則散在資料庫權限規則與雲端函式裡,很難測試;Firebase 是文件型資料庫,不適合跨單據的報表。
  • E 本機優先(每台裝置自己有一份資料庫、背景同步):離線時兩台各賣掉最後一件的庫存衝突、單號與「被用到就不能刪」都要重新設計;五個裡面最難做。
驗證
沒實測。「一台資料庫每秒能處理幾千筆簡單交易」是一般經驗;C 的「128 MB 對大報表偏緊」是推論。Cloudflare 的上限是 2026-11-17 查官方文件。
出處
overall-shape.md 第 1 題;說明頁 docs\explains\modular-monolith.html

紀錄放哪裡架構決定放 docs\architecture\,一個主題一個檔 2026-11-17

選的:新資料夾 docs\architecture\,一個主題一個檔,加一份對照表(README.md)。(Claude 推薦,Jesse「照推薦」)

理由
架構的題目會一個主題連著談好幾題,一個主題一檔讀起來最順;格式沿用決策檔;架構與業務規則分開放。
代價
多一個資料夾要記得讀。
沒選的
  • 放進 docs\decisions\、檔名加 arch-:56 個檔的對照表會混進不同性質的東西。
  • 單一檔 docs\architecture.md:題目多了會很長。
  • 業界的 ADR 格式、一個決定一個編號檔:同一個主題的決定會散在好幾個檔。
驗證
—
出處
README.md「這份紀錄放哪裡」

6. 模組(含 schema)

模組第 1 題粗切:五個模組 2026-11-17

選的:只在很少跨過去的地方切,五個模組:帳號與公司(註冊、登入、公司、成員與權限);進銷存本體(基本資料、所有單據、庫存、成本、帳款、資金、票據);報表(財務報表、進銷存報表、首頁、營運總覽、行事曆,只讀);操作紀錄;AI 助理。以後要加的雲端會計、電子發票,各新增一塊。(Claude 推薦,Jesse 選推薦的)

白話與例子
存一張銷貨單,進銷存本體自己做完銷貨單、庫存、應收、成本,再叫操作紀錄記一筆;跨模組呼叫 1 次。
AI 助理這一塊的內容已經被後來的決定改掉:2026-11-19 AI 第 2、5 題之後,AI 助理模組剩轉送端點(只加金鑰與模型、記用量)與一支「列出我能叫的動作」的 API,見 AI 第 5 題。
理由
  • 邊界要切在本來就很少跨過去的地方。銷售、採購、庫存、帳款每次存檔都要互相碰到,硬切開只是多一層轉手,交易還是同一筆。
  • 一個程式模組對上一個賣得出去的產品模組,以後加會計、電子發票是新增一塊,不用動舊的。
  • 真正可能單獨搬出去的就是那幾塊:報表可以接唯讀複本、AI 助理可以獨立加開。
  • 模組之間的介面只有幾條,Jesse 要審的少。
代價
  • 進銷存本體是最大的一塊,大部分程式都在裡面;它裡面還是要有規矩(還沒談)。
  • 同時派好幾個 Opus 寫的時候,多半都在同一個模組裡動,比較容易互相踩到。
沒選的
  • 中切(約 9 塊):存一張銷貨單要跨 3 次以上,介面很多、要審的也多;互抵、自動組裝這類跨兩塊的規則要決定放哪一邊。
  • 細切(30 個以上):幾乎每個動作都要跨好幾個模組,介面比程式還多;單據共用的規則沒地方放。Claude 不建議。
  • 不切模組、只照技術分層:任何程式都能讀寫任何資料表,以後會計、電子發票會跟舊的纏在一起,也沒有哪一塊能單獨搬出去。
驗證
—
出處
modules.md 第 1 題

模組第 2 題模組之間直接呼叫 2026-11-17

選的:呼叫對方公開的 C# 介面,兩邊在同一筆資料庫交易裡,失敗整個退回。(Claude 推薦,Jesse 選推薦的)

白話與例子
粗切之後跨模組的來往只剩幾條:本體與帳號 → 操作紀錄(每次存檔記一筆);本體、報表 → 帳號與公司(現在是誰、哪家公司、有沒有權限);報表 → 本體(讀資料)。資料存取定了手寫 SQL+Dapper,所以做法是把同一條連線與交易明確傳給被呼叫的模組。
還沒裁 依賴方向定死(大家都能呼叫操作紀錄與帳號;報表與 AI 能呼叫本體;反過來不行)是 Claude 講的,Jesse 沒另外裁。2026-11-19 之後 AI 助理模組不再直接呼叫其他模組的動作,它對帳號與公司的依賴還在(Claude 整理,Jesse 沒另外裁)。
理由
  • 粗切之後只剩幾條,不值得多架一套事件的機制。
  • 操作紀錄是事後查帳用的,「單存了但紀錄沒寫到」等於那一筆永遠查不到;同一筆交易由資料庫保證。(「操作紀錄要跟存檔同一筆交易」是 Claude 的推論,oplog.md 沒有這一題。)
  • 呼叫寫在程式裡,審的時候一路點得進去、編譯器會檢查;事件的連動在呼叫的地方看不到。
代價
  • 以後加雲端會計這種附加模組,照直接呼叫得回頭改本體去呼叫它,方向是反的,到時候要在本體開一個「存檔後通知」的掛點。所以選的是「現在不做事件,等有附加模組再加」,不是永遠不用。
  • 同一筆交易跨兩個模組怎麼寫:把同一條連線與交易明確傳過去。
沒選的
  • 事件、同一筆交易:存檔之後還會發生什麼在呼叫的地方看不到;訂閱的先後要另外規定;現在只有操作紀錄一個訂閱者。
  • 事件、存完才處理(待辦表+背景):操作紀錄會晚一點才出現;背景處理失敗要重試與監控;開很多份時要防重複處理。
  • 走網路呼叫(HTTP 或 gRPC):跨模組沒辦法同一筆交易、要自己寫補償。Claude 不建議。
驗證
沒驗過(同一條連線與交易傳給被呼叫的模組)
出處
modules.md 第 2 題與同題最後「2026-11-19 AI 助理第 2 題之後」

模組第 3 題報表直接讀本體的資料表(唯讀) 2026-11-17

選的:報表自己寫 SQL 讀進銷存本體的資料表,資料庫帳號只有讀的權限。跟著講明的規矩:凡是靠業務規則算出來的數字,全站只能有一個來源,報表不自己再算一次。(Claude 推薦,Jesse 選推薦的)

白話與例子
例子是每月加權平均的成本、每張單還欠多少、庫存。這些要嘛由本體算好存下來、要嘛由本體提供唯一的那一份;存還是當場算,後來在資料模型第 3、6、7 題逐項定了。AI 查資料是呼叫報表與本體公開的動作,不自己讀表。
理由
  • 選模組化單體的理由之一就是報表直接用 SQL 把好幾種單據合起來算;透過介面拿等於丟掉這個好處。
  • 二十幾張報表與看法,每張要的欄位組合都不同,透過介面的話介面比報表還多。
  • 唯讀由資料庫權限保證;以後場景 ③ 接唯讀複本只改連線字串。
  • Jesse 看得懂 SQL,算法攤在 SQL 裡最好審。
代價
本體的資料表結構變成兩個模組之間的約定,本體改欄位報表可能跟著壞,要靠測試抓;這是唯一一條不走介面的來往。
沒選的
  • 透過檢視讀:多一層要維護、報表要新欄位得先改檢視、檢視疊太多層效能不好調。
  • 透過介面拿(在 C# 裡加總):資料要全部搬進記憶體、量大會慢,介面比報表還多。
  • 另存報表專用的資料:每種單據存檔都要多寫一份,兩份可能對不起來;現在沒有效能問題,可以等某張報表真的慢了再單獨做。
驗證
報表的角色:設了公司讀得到、寫入 permission denied、帳號類的表 permission denied,實測過 2026-11-18,PostgreSQL 17.12(database.md 第 2 題)。
出處
modules.md 第 3 題

模組第 4 題一個模組一個專案 2026-11-17

選的:每個模組一個 .csproj、編成一個 assembly DLL;公開的標 public、其餘 internal;誰能呼叫誰由專案參考決定(不能循環,違規的程式編譯不過)。(Claude 推薦,Jesse 選推薦的)

白話與例子
Jesse 問:「一個模組一個專案,意思是一個模組編出來是一個 .net assembly dll?」答:對。但只是編譯時分開,執行時由進入點一次載入到同一個行程,模組之間是一般的 C# 方法呼叫(所以第 2 題的同一筆交易做得到),部署還是一個映像檔、一個容器,沒有哪個 DLL 可以單獨上線。來源檔畫了 Host、Ai、Reports、Core、Account、OpLog、Shared 七個專案的示意(名稱是 Claude 的示意;正式名稱 2026-11-19 在第 7 題定了 LiteErp 開頭)。來源檔在圖上方的 2026-11-19 補記:「名稱定了用 LiteErp. 開頭,第 7 題;Ai 那一列是 AI 助理第 2、5 題之前畫的,現在 AI 助理模組只剩轉送端點、列出動作的 API、記用量,它要參考誰沒重談」。Shared 那一列的內容,後來由第 6 題的白名單取代。

來源檔的示意(名稱是 Claude 的示意;見上面的補記)

Host      進入點,可執行的那一個   → 參考下面全部
Ai        AI 助理                 → Core、Reports、Account、OpLog
Reports   報表                    → Core、Account、OpLog
Core      進銷存本體              → Account、OpLog
Account   帳號與公司              → OpLog
OpLog     操作紀錄
Shared    共用的小東西(金額運算、目前是哪家公司)
理由
  • 違規的程式編譯不過,Opus 寫錯當場知道。
  • 依賴方向寫在專案參考裡,打開 .csproj 就看得到。
  • 每個模組 public 的東西剛好是它的「動作」與參數型別;產生 API 文件與給 AI 的動作說明,掃 public 那一層就好。
  • 多個 Opus 同時寫時各自在不同專案裡。
代價
專案七、八個再加測試專案,建置慢一點;Shared 容易變成雜物間,要規定只能放哪幾類(同一天在第 6 題定了);類別放錯模組要搬比較費事;測試要看到 internal 得另外開權限。
沒選的
  • 一個專案、用測試檢查:違規要等測試跑了才知道、漏寫一條規則就漏檢查、要多一個第三方套件、internal 擋不住同一個 DLL 裡的程式。
  • 一個專案、靠審查:沒有東西自動擋,程式是 AI 寫的、量又大。Claude 不建議。
驗證
—
出處
modules.md 第 4 題

模組第 5 題資料庫裡一個模組一個 schema 2026-11-19

選的:擁有資料表的模組各一個 schema:帳號與公司(account)、進銷存本體(core)、操作紀錄(oplog),名稱是例子。SQL 一律寫出 schema(core.sale)。報表與 AI 助理沒有自己的表,之後有再開。(Claude 略推薦,Jesse 選這個)

來源檔的 SQL(2026-11-19 實測過,結果在下面「驗證」)

create schema account;   -- app_user、company、company_member、login_session、員工…
create schema core;      -- 單據、商品、客戶、庫存、成本…
create schema oplog;     -- 操作紀錄

grant usage on schema core to app_report;
grant select on all tables in schema core to app_report;
alter default privileges in schema core grant select on tables to app_report;
-- app_report 沒有 account 的 usage,整個 schema 碰不到

grant usage on schema oplog to app_rw;
grant select, insert on all tables in schema oplog to app_rw;   -- 不給 update、delete
白話與例子
Jesse 取消視窗後問的三句:「schema 其實就是 MariaDB 裡面的資料庫的概念對吧?」對,MariaDB 的 CREATE SCHEMA 就是 CREATE DATABASE;PostgreSQL 多一層,一條連線只能存取一個資料庫,所以要「分開但還能互相 join、同一筆交易」在 PostgreSQL 要用 schema。「不同 schema 的 table 不能互相設為外鍵嗎?」可以,建外鍵的角色要有對方表的 REFERENCES 與對方 schema 的 USAGE。「那 schema 區隔了甚麼?」只有名字與「權限可以一整包給」兩樣;join、交易、外鍵、列層級安全性、效能、儲存都沒有隔開。Claude 講了這題接近五五波。
理由
  • 從表名就知道碰的是哪個模組。
  • 權限一整包給,而且不會包到帳號類的表。
  • 「帳號類的 SQL 只能放在帳號與公司模組」(資料模型第 9 題)可以寫成自動的測試。
代價
每一句 SQL 的表名都長一截;漏寫 schema 當場報找不到表;前面各題實測過的 SQL 例子都沒有 schema,實作時要補上。
沒選的
  • 不分 schema、表名加字頭(core_sale):權限一張一張表設;有人把 public 全部的表給報表角色時帳號類的表會一起出去;表名更長。
  • 不分 schema、表名不加字頭:看不出表是哪個模組的;那條規矩只能靠審查或另外維護清單。
驗證
實測過 2026-11-19,PostgreSQL 17.12:core.sale 的外鍵指到 account.employee 正常;填不存在的員工報 is not present in table "employee"、刪還被指著的員工報 is still referenced from table "sale";報表的角色讀 core.sale 可以、讀 account.employee 報 permission denied for schema account;之後才建的 core.customer 沒另外設也讀得到;程式的角色對 oplog.entry 新增可以、修改刪除報 permission denied for table entry;SQL 沒寫 schema 報 relation "sale" does not exist。沒測:開了列層級安全性之後的跨 schema 外鍵。
出處
modules.md 第 5 題
還沒裁、選完之後還開著的:
  • 還沒裁 跨 schema 的外鍵方向跟模組的依賴一樣,本體的程式不自己查帳號、公司、成員那幾張表(Claude 順著講的)。
  • schema 的正式名稱;搜尋路徑要不要設成空的來強迫每一句都寫 schema。(員工資料表歸哪個模組、對照表放哪個 schema 同一天定了,見第 8 題、第 9 題。)

模組第 6 題Shared 只能放哪幾類:白名單(原本四類,加上權限清單是五類)+兩條自動檢查的規矩 2026-11-19

選的:① 一個 Shared,只准放四類:動作的框架(IAction、[Action]、執行器、錯誤的種類)、資料庫的共用步驟(開交易並設公司編號)、金額與數量的運算、時間與「今天」。同一天後端第 15 題定了權限項目的清單也放 Shared,是白名單的第五類(後端第 15 題),所以現在是五類。② 規矩一:Shared 不參考任何模組專案(寫錯編譯不過)。③ 規矩二:Shared 裡不能有任何碰資料表的 SQL(寫一個測試檢查)。④ 執行器要「問現在是誰、是不是成員、有沒有權限」與「寫操作紀錄」,這兩件事在 Shared 只定介面,由帳號與公司模組、操作紀錄模組實作,Host 啟動時接起來。(Claude 推薦,Jesse「照推薦」)

白話與例子
第 4 題的代價寫過 Shared 容易變成雜物間。它是所有模組都參考的最底層專案:每個模組的動作都要實作 IAction、標 [Action],金額運算與時間也是每個模組都用。所以一個請求從頭到尾那八步的框架(執行器)在 Shared,第 2、3、6 步實際查資料庫與寫紀錄的,是帳號與公司、操作紀錄兩個模組照介面實作的。
理由
規矩一由編譯器擋、規矩二由測試擋,不靠審查;白名單讓「這個該不該進 Shared」有答案。
代價
多兩個介面要繞一層;白名單以外的東西想共用時要先回來問放哪。
沒選的
  • 拆成兩個專案(動作的框架一個、純工具一個):專案多一個,兩個專案的界線又要另外定規矩。
  • 不立規矩、靠審查:程式是 Opus 寫的、量大,有人把一句訂單的 SQL 放進 Shared 只有審到才擋得住。
驗證
沒寫過。規矩二的測試怎麼認「碰資料表的 SQL」沒定。
出處
modules.md 第 6 題
還沒裁、選完之後還開著的:
  • 還沒裁 規矩二的測試:Shared 的 assembly 裡不准有 *Sql 類別、設公司編號的那一句 set_config 不算(Claude 的想法)。
  • 還沒裁 同一次 Claude 講了照例子走、Jesse 沒另外裁的:一種單據一個資料夾放動作(Core/SalesOrder/CloseSalesOrder.cs)、請求與回應型別跟動作寫在同一個檔、SQL 集中在 Core/Sql/;網址 sales-order/close、給 AI 的名稱 sales_order_close、資料表 sales_order。

模組第 7 題專案的正式名稱:LiteErp 開頭 2026-11-19

選的:專案與命名空間用 LiteErp 開頭:LiteErp.Host、LiteErp.Core、LiteErp.Account、LiteErp.Reports、LiteErp.OpLog、LiteErp.Ai、LiteErp.Shared。模組的名字照第 4 題的示意(Claude 說打算照用、請他想改就講,Jesse 沒另外講)。(Claude 推薦,Jesse「照推薦」)

理由
跟資料夾名稱、原型程式的 LiteErp.roundHalfUp、決策檔的稱呼一致,Jesse 自己也這樣叫(「LiteERP 不需要知道使用者的密碼」);這個名字只有寫程式的人看得到,內部名稱不必跟著對外的產品名走。
代價
名字裡有 Lite,以後 Pro 版如果共用同一套程式碼會名不副實;到時候改命名空間是機械性的工作。
沒選的
  • YouStar.Lite:一樣有 Lite 的問題,比較長。
  • YouStar.Erp:跟現在所有文件、原型的叫法都不一樣;Pro 會不會共用程式碼還沒談,等於為了還沒決定的事先改名。
驗證
—
出處
modules.md 第 7 題

模組第 8 題員工資料表歸帳號與公司,別的模組的 SQL 只能唯讀 join 它 2026-11-19

選的:員工表在 account schema、歸帳號與公司模組。本體與報表的 SQL 可以 join account.employee 讀名字,只能讀。規矩一句話:別的模組的 SQL 碰得到的帳號類資料表只有 account.employee,而且只能出現在查詢裡;寫一個測試掃。(Claude 推薦,Jesse「照推薦」)

白話與例子
員工這張表兩邊都要用:帳號與公司模組管它(邀請、權限、離職);進銷存本體每張單的經辦人外鍵要指到它,清單與單據要顯示經辦人的名字。第 5 題的實測用的就是 account.employee,core.sale 的外鍵指過去是通的;資料模型第 9 題那三張不分公司的表不包含員工表(它帶公司編號、有列層級安全性)。
理由
清單要顯示經辦人,一句 SQL join 就拿到;照實測過的樣子。
代價
這是模組邊界上開的一個口;資料庫的角色分不出是哪個模組在讀,只能靠那個測試守。
沒選的
  • 歸帳號模組、本體完全不碰、要名字就呼叫帳號模組的方法:一頁清單 50 列要另外再問一次經辦人叫什麼,每個清單與報表多一段拼名字的程式。
  • 歸進銷存本體:帳號模組的成員表得反過來指到本體,專案參考變成循環、做不出來,除非把邀請與權限也搬進本體。
驗證
沒驗證:那個測試怎麼掃沒寫過;報表的角色現在沒有 account 的 usage,報表要 join 員工表就得另外只給這一張的讀取權限,沒試。
出處
modules.md 第 8 題

模組第 9 題對照表跟著自己的模組放,操作紀錄的種類自己一張 2026-11-19

選的:對照表跟著定義它的模組放:core.doc_kind、core.tax_type 這些放本體;操作紀錄的種類放 oplog,內容是「所有會存的東西」。C# 的 enum 各自定義在自己的模組。不另外開放對照表的 schema。(Claude 推薦,Jesse「照推薦」)

白話與例子
資料模型第 4 題定了程式定死的值各有一張不分公司的對照表,當時還沒分 schema。「種類」本體(庫存異動表、回收桶、單號計數表)與操作紀錄都要記,而操作紀錄模組在最底層、不能反過來指到本體的表。操作紀錄的「種類」範圍比單據大,除了 19 種單據還有商品、組合商品、客戶、廠商、通訊錄、公司資料與設定項目各頁,跟本體的單據種類是兩份不同的清單。
理由
不用多開 schema;外鍵的方向跟模組的依賴一致;兩份清單本來就不一樣,硬合成一份要把業務的詞搬進 Shared(第 6 題)。
代價
19 種單據在兩張表各出現一次;本體寫操作紀錄時要把自己的單據種類對到操作紀錄的種類,這個對照要有測試守。
沒選的
  • 多開一個 schema 專門放對照表(例如 ref):對應的 C# enum 得放 Shared,白名單要多開一類。
  • 共用的那幾張放在最底層的模組(oplog):core.stock_move 的外鍵指到 oplog.doc_kind,名字與歸屬很怪。
驗證
—(來源檔沒寫驗證)
出處
modules.md 第 9 題
還沒裁、選完之後還開著的:
  • 兩份清單裡 19 種單據的數字要不要編成一樣;帳號與公司模組自己的對照表(如果有)照同一條放 account。
  • 還沒裁 schema 的名稱 account、core、oplog 是 Claude 講了照例子用、Jesse 沒另外講的;搜尋路徑要不要設成空的(Claude 的看法是不用另外設,沒問)。

7. 多家公司與資料庫

多家公司第 1 題共用資料表+公司編號 2026-11-17

選的:全部公司共用同一套資料表,每一列都帶公司編號,每個查詢都只看這一家。公司編號放在每張表主鍵的最前面。(Claude 推薦,Jesse「我的想法也是 共用資料表+公司編號」)

白話與例子
開談前的事實:帳號不屬於任何一家公司(一個 e-mail 多家公司,權限跟著公司走),所以不管選哪個,都有一塊全平台共用的資料(帳號、公司清單、誰在哪家公司是什麼權限);報表都只算自己這一家,沒有跨公司的查詢。主鍵長什麼樣見資料模型第 2 題。
理由
  • 跟整體形狀一致:一支程式、一個資料庫、改版只升級一次。
  • 公司都很小,為每一家開一個資料庫,管理成本比資料本身重。
  • 公司編號放主鍵最前面,資料庫撐不住時可以照公司搬到別的資料庫(走到「分片」那一格);反過來從一家一個資料庫合併回來很難。
  • 漏寫條件的風險可以用資料庫的列層級安全性當第二道鎖(同一天在資料庫第 2 題定了要用)。
代價
  • 隔離靠程式,漏寫一個條件就是 A 公司看到 B 公司的資料。
  • 單獨還原一家、整家刪除,都要一張表一張表處理;「初始盤點誤按清掉怎麼救」沒辦法靠把一家公司倒回昨天。
  • 一家跑大報表會拖慢別家。
  • 每人一份示範資料全塞進共用表不可行(見下一張卡)。
沒選的
  • 一家公司一個 schema:幾萬家就是幾萬套資料表,每次改版要升級幾萬次,中途失敗會新舊版混在一起。
  • 一家公司一個資料庫:隔離最強、單獨還原一家最簡單;但幾萬個資料庫、改版要升級幾萬次、帳號與公司清單要另外放一個共用資料庫。
  • 一開始就分片:場景 ①、② 用不到卻要先做目錄與搬移公司的工具。
驗證
選的時候查了微軟的多租戶設計文件、PostgreSQL 的列層級安全性、SET LOCAL、schema、PgBouncer 文件(2026-11-17,網址在來源檔)。
出處
multi-tenancy.md 第 1 題;說明頁 docs\explains\multi-tenancy.html
還沒裁、選完之後還開著的:
  • 單獨一家公司的還原(初始盤點誤按、客服救資料)怎麼做。
  • 以後真的要分片時,目錄放哪、怎麼搬一家公司。

多家公司示範公司不存,改成「載入示範資料」 2026-11-17

選的:拿掉每人一家示範公司,改成初始盤點頁「載入示範資料」,把這家公司的資料清掉換成示範資料;只有空的公司或現在裝的是示範資料的公司才看得到。(Jesse 提,Claude 同意;不在 Claude 列的八種裡)

白話與例子
起因:每人一家示範公司時,現在的示範資料 19 種單據共 17,916 張,3 萬個使用者就是 5 億多張示範單(17,916 × 30,000 = 537,480,000)。Jesse 看到這個數字說「這個聽起來是個大問題,討論一下解決辦法」。示範資料改成跨兩年、越近越密,照比例估約 1,700 張。
理由
Claude 同意的理由:比推薦的做法 1(用到才複製、沒用就清掉)單純,不用範本公司、複製、清理,也沒有特別的公司種類。
代價
業務規則面的代價與連帶過期的舊決定在 docs\decisions\account.md「2026-11-17 示範公司拿掉」,這頁不展開。對架構的影響:共用表裡不再有每人一份的假資料;「複製一家公司」不是必要的功能了。
沒選的
  • Claude 列的八種(用到才複製、註冊就複製、動手才複製、共用底稿+差異、縮小示範資料、放另一個資料庫、大家共用一家只能看、放在瀏覽器裡),都沒選。
驗證
5 億張是照實測的 17,916 張直接乘;放進資料庫的大小沒有實測。
出處
multi-tenancy.md「示範公司怎麼存」

資料庫第 1 題PostgreSQL 2026-11-17

選的:PostgreSQL。(Claude 推薦,Jesse「我選 PostgreSQL」)

白話與例子
挑的條件來自前兩題:共用資料表最怕漏寫條件,要看有沒有內建的列層級安全性;改版只升級一次,要看升級到一半失敗能不能整批退回;三個場景同一份程式,本機要裝得起來、雲端要有代管、幾萬人不能撞到上限或授權費。
理由
  • 共用資料表最大的風險(漏寫條件)靠列層級安全性補;五套裡只有 PostgreSQL 和 SQL Server 有,其中只有 PostgreSQL 沒有授權費。
  • 一個人維護,資料表升級失敗要能整批退回,不會卡在半新半舊。
  • 三個場景都不用換:本機裝得起來,幾萬人不會撞到版本上限。
代價
Jesse 如果沒用過要學它的維運;幾萬人時前面要加連線池(一般經驗,沒實測)。問的時候 Claude 講了:不知道 Jesse 平常最熟哪一套,最熟的那套是選它的正當理由;他沒有多說,直接選 PostgreSQL。
沒選的
  • SQL Server:場景 ③ 一定超過 Express 的上限要付授權費;會把後端語言往 .NET 推。
  • MariaDB:沒有列層級安全性,隔離只剩程式那一道;雲端代管的選擇比較少。
  • MySQL:沒有原生的列層級安全性;資料表升級不能整批退回。
  • SQLite:場景 ②③ 撐不了後端開很多份,等於本機一套、雲端另一套。
  • 先不綁定、只寫各家都通的 SQL:用不到列層級安全性這類各家不同的功能,每個功能要在兩套上測。
驗證
比較表是 2026-11-17 查官方文件(有幾格標了「Claude 的印象」「沒查」,在來源檔)。
出處
database.md 第 1 題
還沒裁、選完之後還開著的:
  • PostgreSQL 用哪一版、本機 Windows 怎麼裝、雲端用哪家的代管;連線池(場景 ③ 要不要、用哪個)。

資料庫第 2 題列層級安全性:每筆交易設公司 2026-11-17

選的:四個部分是一套:① 規則:一條 using 同時管讀與寫;② 每筆交易開頭 set_config(..., true),交易結束就失效,忘了設 current_setting 直接報錯;③ 三個資料庫角色:建表與升級用的(擁有資料表)、程式平常用的(讀寫,不是擁有者、沒有 BYPASSRLS)、報表用的(唯讀);④ 加 force,連擁有者都受限。(Claude 推薦,Jesse 選推薦的)

來源檔的 SQL(表名、設定名稱 app.company_id、規則名稱都是示意;2026-11-18 整套實測過)

-- 每張帶公司編號的表
alter table sales enable row level security;
alter table sales force  row level security;
create policy tenant on sales
  using (company_id = current_setting('app.company_id')::bigint);

-- 每一筆交易的開頭,由程式統一做
begin;
select set_config('app.company_id', '42', true);   -- true = 只在這筆交易有效
commit;
白話與例子
另外一個測試:掃每一張有 company_id 欄位的表,確認有開、有 force、有規則。外鍵檢查不受規則管,所以外鍵一律要把公司編號包進去。AI 助理照叫它做的那個人、那家公司,走同一套交易開頭的設定。
理由
  • 連線放在池子裡重複用,設在連線上萬一沒清乾淨,下一個請求會帶著上一家的編號;設在交易上由資料庫自己清。
  • 場景 ③ 前面多半要加連線池,transaction 模式下同一條連線的設定帶不到下一句。
  • 忘了設是報錯,不是悄悄回傳空的或別家的。
代價
  • 每一次碰資料庫都要在明確的交易裡,連查一筆也是;每個請求多出開交易、設公司、結束交易。對效能的影響沒量過。
  • 不分公司的表要另外定規則(後來在資料模型第 9 題定了)。
  • 跨公司的背景工作要有繞過的路(另一個有特權的角色);AWS 代管的資料庫上能不能設 BYPASSRLS 沒查。
  • 每一句 SQL 還是照樣自己寫 company_id = ...,資料庫那道當保險。
  • 開了列層級安全性的表不能用 COPY 寫入,示範資料與 Excel 匯入要用一次多列的 INSERT。
沒選的
  • 每條連線設公司:靠連線池歸還時會重設;場景 ③ 加 transaction 模式的連線池時這種設法會失效,要整個改寫。
  • 不開、只靠 SQL 與測試:漏寫一句就是別家的資料外洩、沒有第二道防線;當初選 PostgreSQL 的第一個理由就是要用這道鎖。
  • 一家公司一個資料庫角色:幾萬家就是幾萬個角色,連線池照角色分會把連線數撐爆。Claude 不建議。
驗證
實測過 2026-11-18,postgres:17 容器(PostgreSQL 17.12),三個角色照上面建,公司 7、8 各 10 萬列異動:
  • 全新的連線沒設公司就查:ERROR: unrecognized configuration parameter "app.company_id"。
  • 設成公司 7:只看得到公司 7 的 10 萬列;寫一列公司 8 的資料:ERROR: new row violates row-level security policy。
  • 同一條連線的下一筆交易沒設:拿到空字串,轉 bigint 時報 invalid input syntax for type bigint: ""。會失敗、不會悄悄查到東西,但錯誤訊息跟第一種不同。
  • 擁有者因為 force 也受規則管。
  • 規則不會讓索引失效:查詢自己有寫 company_id = 7 時規則變成 One-Time Filter;沒寫時規則直接變成 Index Cond。兩種都是 Index Only Scan。
  • 對照表只給 select:寫入 permission denied。報表的角色設了公司讀得到、寫入與帳號類的表 permission denied。
  • 沒測的:透過連線池的情況;C#+Dapper 實際呼叫;大量資料下規則多出來的時間。
出處
database.md 第 2 題
還沒裁、選完之後還開著的:
  • 跨公司的背景工作用哪個角色。

8. 資料模型第 1 到 18 題

第 1~12 題 2026-11-18 定、第 13~18 題 2026-11-19 定。來源檔開頭寫「SQL 都是示意,表名、欄名還沒定」;第 8 題之後,前面例子裡寫成 numeric 的數量與金額,實作時換成第 8 題的四個型別。實測環境除非另外寫,都是 postgres:17 容器(PostgreSQL 17.12),在 Jesse 的開發 PC 上跑,不是雲端主機的數字;腳本沒有留在 repo。

資料模型第 1 題被刪掉的東西:搬到回收桶表 2026-11-18

選的:刪除時在同一筆交易裡,把整筆存成 JSON 寫進一張回收桶表,再從原本的表真的刪掉;復原是寫回去。過期的回收桶資料真的刪掉。(Jesse 選「搬到回收桶表」,照推薦;過期就真的刪是 Jesse 提的)

來源檔的 SQL(2026-11-18 跑過:刪進回收桶再復原,單頭與明細跟刪之前一模一樣)

-- 刪單(同一筆交易)
insert into recycle_bin
  (company_id, kind, row_id, doc_no, deleted_at, deleted_by, body)
select s.company_id, 'sale', s.id, s.doc_no, now(), @UserId,
       to_jsonb(s) || jsonb_build_object('lines',
         (select jsonb_agg(to_jsonb(l))
            from sale_line l
           where l.company_id = s.company_id and l.sale_id = s.id))
  from sale s
 where s.company_id = @CompanyId and s.id = @Id;

delete from sale where company_id = @CompanyId and id = @Id;

-- 清理
delete from recycle_bin where deleted_at < now() - @Keep;
白話與例子
一張表裝全部種類:用一欄分種類,內容整筆是 JSON,單據的明細包在裡面,一張單一列(Jesse 問「你是想把所有不同的表的被刪除資料通通丟到同一張 recycle_bin 資料表裡面?」,Claude 答對,他回「我覺得你的想法不錯」)。這改掉了 2026-11-13「單據不會從資料庫裡消失,頂多被標記為已刪除」:刪掉的單在回收桶留一段時間,過期後資料庫裡只剩操作紀錄「刪除」那列的白話全文。
理由
  • 原本的表只有活著的資料。讀單據的 SQL 有上百句,刪除與復原只有幾十句,風險放在少的那一邊。
  • 清理只要一句、一張表,沒有外鍵順序的問題。
  • 「被用到就不能刪」不用多定規則:已刪除的單不再用外鍵指著客戶與商品。
  • 編號不會撞:刪掉商品 A001 之後可以馬上新增另一個 A001。
  • 新增一種單據不用多建表;原本的表改欄位也不用跟著改回收桶。
  • 一次刪除連帶刪掉的可以放在一起、一起寫回去。
代價
  • 不是字面上的「標記」。
  • JSON 沒有型別、沒有外鍵,資料庫不會檢查裡面對不對。
  • 復原會失敗的兩種情況要另外處理:指到的客戶或商品已經真的刪掉;這段期間原本的表加了不能空的欄位。
  • 用 SQL 查已刪除的資料要從 JSON 把欄位拿出來。
  • 刪除與復原每種單據各要寫一句。
沒選的
  • 同一張表加刪除標記(Jesse 的提案「在每一個 table 上都加上一個有上索引的 is_deleted 旗標, 以及 deleted_at…」):每一句讀取的 SQL 都要帶條件,漏一句數字默默算錯;已刪除的單還用外鍵指著客戶商品;清理要照外鍵順序一張一張表做。is_deleted 上的一般索引幫不上忙。
  • 加標記+程式一律讀檢視表:每張有標記的表多一個檢視表;外鍵、撞號、清理順序跟上一個一樣。
  • 真的刪掉、只靠操作紀錄的白話:白話還原不成資料,關掉分頁就救不回來。
  • 每張表各配一張「已刪除」表:表的數量變兩倍。
  • 併進操作紀錄:操作紀錄誰都不能改刪,回收桶要過期清掉,放不進同一張表。
驗證
實測過 2026-11-18:to_jsonb+jsonb_agg 寫進回收桶、刪單,再用 jsonb_populate_record(單頭)、jsonb_populate_recordset(明細)寫回去;逐欄比對完全一樣,庫存也對。沒量:初始盤點按開始會清上萬張單,一次全部進回收桶要多久、佔多少空間。
出處
data-model.md 第 1 題、檔尾「實測紀錄」第 5 項
還沒裁、選完之後還開著的:
  • 留多久(Jesse 舉的例子是兩星期,還沒定;Claude 的看法是上線前再定);誰來清;復原失敗時畫面上怎麼講;過了底部的「復原」之後店家還能不能自己救回來;初始盤點的清除要不要也走回收桶。
  • 還沒裁 範圍包含設定清單、改單時拿掉的明細不進回收桶,是 Claude 的解讀;回收桶表照樣帶公司編號、開列層級安全性,一次刪除連帶刪掉的用同一個動作編號綁在一起,是 Claude 的想法。

資料模型第 2 題id:bigint、資料庫發號 2026-11-18

選的:每張表的主鍵是(公司編號,id),id 是 bigint generated by default as identity,新增時資料庫給號、用 returning id 拿回來。外鍵一律(公司編號,對方的 id)。(Jesse 選「bigint 資料庫發號」,照推薦)

來源檔的 SQL

create table sale (
  company_id bigint not null,
  id         bigint generated by default as identity,
  doc_no     text   not null,
  primary key (company_id, id)
);

create table sale_line (
  company_id bigint not null,
  id         bigint generated by default as identity,
  sale_id    bigint not null,
  primary key (company_id, id),
  foreign key (company_id, sale_id) references sale (company_id, id) on delete cascade
);
白話與例子
用 by default 不用 always:回收桶復原時要照原本的 id 寫回去(第 1 題)。公司編號在 database.md 的例子裡是 bigint,沒有另外問過。
理由
8 bytes,主鍵、外鍵、索引最小,join 最快;查問題時 where id = 1203 好讀好打。
代價
號碼是全站一起數的,網址上的 id 看得出全站大約有幾筆(別家的資料照樣看不到);存單要先拿到單頭的 id 才能寫明細;按兩下儲存要另外擋。
沒選的
  • UUID 第 7 版、程式發號:16 bytes(加公司編號 24 bytes),每個外鍵與索引跟著變大;查問題時要貼一長串。
  • 每家公司的每張表各自從 1 數:每張表新增都要先取號、同時新增要排隊;換來的只有號碼好看。
  • 先不定:後面談外鍵、鎖、API 都會碰到 id。
驗證
沒有單獨的實測;檔尾「實測紀錄」的資料表是照第 1~6 題的例子建的。
出處
data-model.md 第 2 題
還沒裁、選完之後還開著的:
  • 按兩下儲存、網路重送怎麼擋(2026-11-19 在第 17 題定了);on delete cascade 要不要當成明細表的規矩(例子裡這樣寫,Claude 的想法,沒問)。

資料模型第 3 題庫存數量:異動表+現有量表 2026-11-18

選的:兩張表:庫存異動表(每一列進出一筆)與現有量表(每樣商品每個倉庫一列)。存單時同一筆交易、同一句 SQL:把這張單舊的異動全部刪掉、照現在的明細重寫,再照實際刪掉與寫入的列算出差額、加減現有量表。(Jesse 選「異動表+現有量表」;Claude 第一次推薦的是只有異動表,被他問到改口)

來源檔的 SQL(2026-11-18 整句跑過,結果在下面「驗證」)

create table stock_move (
  company_id   bigint   not null,
  id           bigint   generated by default as identity,
  product_id   bigint   not null,
  warehouse_id bigint   not null,
  move_date    date     not null,
  qty          numeric  not null,         -- 進是正、出是負;型別還沒定
  doc_kind     smallint not null,         -- 哪一種單據;型別還沒定(見下面)
  doc_id       bigint   not null,
  primary key (company_id, id)
);
create index on stock_move (company_id, doc_kind, doc_id);
create index on stock_move (company_id, product_id, warehouse_id, move_date) include (qty);

create table stock_now (
  company_id   bigint  not null,
  product_id   bigint  not null,
  warehouse_id bigint  not null,
  qty          numeric not null,
  primary key (company_id, product_id, warehouse_id)
);

-- 單頭與明細先存好,同一筆交易裡接著跑(銷貨單的例子)
with gone as (        -- ① 刪掉這張單舊的異動,吐出「還回去多少」
  delete from stock_move
   where company_id = @CompanyId and doc_kind = @DocKind and doc_id = @DocId
  returning product_id, warehouse_id, -qty as d
),
came as (             -- ② 照剛存好的明細寫新的異動,吐出「這次進出多少」
  insert into stock_move
    (company_id, product_id, warehouse_id, move_date, qty, doc_kind, doc_id)
  select s.company_id, l.product_id, s.warehouse_id, s.doc_date, -l.qty, @DocKind, s.id
    from sale s
    join sale_line l on l.company_id = s.company_id and l.sale_id = s.id
   where s.company_id = @CompanyId and s.id = @DocId
  returning product_id, warehouse_id, qty as d
),
delta as (            -- ③ 每樣商品每個倉庫淨差多少
  select product_id, warehouse_id, sum(d) as d
    from (select * from gone union all select * from came) x
   group by product_id, warehouse_id
  having sum(d) <> 0
)
insert into stock_now (company_id, product_id, warehouse_id, qty)   -- ④ 加到現有量
select @CompanyId, product_id, warehouse_id, d
  from delta
 order by product_id, warehouse_id
on conflict (company_id, product_id, warehouse_id)
do update set qty = stock_now.qty + excluded.qty;

-- 對帳:查出來有列就是兩邊對不起來
select product_id, warehouse_id,
       coalesce(m.qty, 0) as from_moves, coalesce(n.qty, 0) as stored
  from (select product_id, warehouse_id, sum(qty) as qty
          from stock_move where company_id = @CompanyId
         group by product_id, warehouse_id) m
  full join (select product_id, warehouse_id, qty
               from stock_now where company_id = @CompanyId) n
       using (product_id, warehouse_id)
 where coalesce(m.qty, 0) <> coalesce(n.qty, 0);
白話與例子
走一遍(台中倉原本餅乾 100、可樂 50、泡麵 30):第一次存餅乾 12、可樂 5 → 現有量 88、45。改成餅乾 10、拿掉可樂、加泡麵 3 → ① 吐 +12、+5,② 吐 −10、−3,③ 是餅乾 +2、可樂 +5、泡麵 −3 → 現有量 90、50、27。只改日期 → ③ 沒有列,現有量表不碰。刪單 → ② 查不到東西,① 全部還回去。8 種會動庫存的單據只差 ② 的 select。誰讀哪一張:現有庫存頁、補貨頁、今天開新單的「現有」讀現有量表;舊單那天的量、庫存進出表、成本讀異動表。
理由
  • 舊單不鎖、沒有關帳,只靠異動表加總的話沒有可以切掉不算的點,現有庫存頁、補貨頁只會越用越慢。
  • 差額是資料庫照實際刪掉與寫入的列吐出來的,不是程式另外算的,每種單據都走這一句就不會有「寫了異動忘了加減」。
  • 異動表一張表、兩個索引,慢了好調。
代價
  • 同一件事存三份(單據、異動、現有量),靠共用的那一句與對帳的 SQL 守著。
  • 異動的 id 每存一次都換新的,不能被別的東西指著。
  • 同一家兩個人同時賣同一樣商品,後存的要等前一個交易結束;order by 是讓每個交易照同樣順序鎖現有量的列。
  • 同一張單被兩個人同時存,這一句自己擋不住(後來由第 5 題的版本欄位擋)。
  • 異動表用(種類,單據 id)指回單據,沒有外鍵保證那張單存在。
沒選的
  • 只有異動表(Claude 第一次的推薦):現有量每次當場加總。Jesse 問「照你的建議, 每次想得知最新的現有量, 都要重算一次?」,再問「如果再多一張表, 紀錄當前每一個庫存每一個商品的數量, 單據變更時就去加減那個數量, 這樣額外的負擔是可以接受的嗎?」,Claude 改口。
  • 檢視表合併 8 種單據:每次查詢 8 段加 join,慢了要一段一段調。
  • 只存現有量、過去的量往回推(原型的做法):查過去要合併 8 種單據往回算,等於兩種算法;沒有異動表可以對帳。
  • 異動逐列比對:那一句要處理三種情況,複雜不少。
驗證
實測過 2026-11-18
  • 四個情境:現有量依序 88/45/30 → 90/50/27 → 不變 → 100/50/30,跟「走一遍」一樣;對帳每次 0 列。
  • 不同的單同時賣同樣的商品:乙等了約 3 秒才完成,數字正確,沒有卡死。
  • 壓力測試:5 個行程各 300 次交易,共 1,500 次,約 4 秒跑完;有 order by 0 次卡死、0 個錯誤;換成亂序,5 個行程裡 4 個遇到 deadlock detected。
  • 執行計畫(公司 7 有 60 萬列異動):全部商品的現有量,加總異動表 89 ms、讀現有量表 1.4 ms;一樣商品一個倉庫照日期排前 50 筆 0.07 ms(Index Only Scan,沒有 Sort)。
  • 庫存那一句在列層級安全性底下、用程式的角色跑,結果正確(database.md 第 2 題)。同時存、壓力測試沒有在規則底下重跑。
出處
data-model.md 第 3 題、檔尾「實測紀錄」第 1~4、6 項
還沒裁、選完之後還開著的:
  • 要不要一張照商品查的修改紀錄表(Jesse 問「我想知道某商品庫存變更的歷史怎麼辦?」,Claude 反問他要的是哪一種,他沒回答這一句);初始盤點的開帳數量怎麼進異動表。

資料模型第 4 題種類、狀態欄位:smallint+enum+對照表 2026-11-18

選的:值是程式定死的欄位(單據種類、課稅別、發票別、收款方式、單據狀態這類),資料庫存 smallint,C# 用每個值寫死數字的 enum,SQL 一律用參數傳;每一類另有一張不分公司的對照表(數字、代碼、中文名稱),欄位用外鍵指過去。(Jesse 選「smallint+enum+對照表」,照推薦)

來源檔的 SQL

create table doc_kind (          -- 不分公司,資料表升級時寫入
  id   smallint primary key,
  code text not null unique,
  name text not null
);
insert into doc_kind values (1, 'sale', '銷貨單'), (2, 'receive', '進貨單');

create table stock_move (
  doc_kind smallint not null references doc_kind (id)
);

-- 查問題時
select m.*, k.name
  from stock_move m
  join doc_kind k on k.id = m.doc_kind
 where m.company_id = 7 and m.product_id = 101;

來源檔的 C#

public enum DocKind : short { Sale = 1, Receive = 2 }
白話與例子
起因:Jesse 在第 3 題問「doc_kind 為什麼要是字串而不是常數?」。回收桶的 kind、單號計數表的 doc_type、異動表的 doc_kind、操作紀錄的種類都照這題。使用者自己維護的清單(商品類別、倉庫)是資料表加 id,不在這題。
理由
程式有型別、SQL 用參數傳,打不錯;不認得的數字資料庫會擋(包括手動修資料、升級腳本);查問題時 join 就看得到名稱;2 bytes。
代價
直接下 SQL 看到的是數字,要 join 才知道是哪一種;對照表與 C# 的 enum 是兩份,要有一個測試比對;數字定了就不能重編;寫入多的表每寫一列多檢查一次外鍵(沒量過)。
沒選的
  • smallint+enum、不建對照表:程式以外的寫入寫進不存在的數字資料庫不會擋。
  • PostgreSQL 的 enum 型別:Dapper 預設把 C# 的 enum 當整數傳;值只能加、不能刪也不好改名(Claude 記得的,沒查原文)。
  • 字串+檢查限制:最佔空間;每加一種要改每個用到的欄位的檢查限制;SQL 裡寫死的字打錯只會查不到、不會報錯。
驗證
對照表只給 select、程式的角色寫入 permission denied:實測過 2026-11-18(database.md 第 2 題)。這一題本身沒寫其他實測。
出處
data-model.md 第 4 題
還沒裁、選完之後還開著的:
  • 中文名稱放資料庫之後,畫面上的字要不要從這裡讀(Claude 的想法是不要,沒問)。

資料模型第 5 題兩個人同時改同一張單:版本欄位,後存的被擋 2026-11-18

選的:每張單的單頭多一個版本欄位,每存一次加 1;畫面打開時記住版本,儲存與刪除時帶著比對。版本對不上就影響 0 列,整筆交易退回,回報給畫面。AI 助理改單走同一批動作,規則一樣。(Jesse 選「版本欄位,後存的被擋」,照推薦)

來源檔的 SQL

create table sale (
  company_id bigint not null,
  id         bigint generated by default as identity,
  version    int    not null default 1,
  primary key (company_id, id)
);

update sale
   set customer_id = @CustomerId, version = version + 1
 where company_id = @CompanyId and id = @Id and version = @Version;
-- 影響 0 列=被改過或被刪了 → 整筆交易退回

delete from sale
 where company_id = @CompanyId and id = @Id and version = @Version;
白話與例子
美玉姐和阿豪都打開同一張銷貨單,美玉姐把餅乾改成 10 包存了,阿豪的畫面還是舊的、加了一列泡麵也按儲存 → 阿豪被擋。兩個人同時按的話,後到的先等前一個交易結束、再比一次版本,這時已經對不上。決策檔沒談過;A1 的實測紀錄裡沒找到 A1 怎麼處理。
理由
沒有人的修改會被悄悄蓋掉;第 3 題那句庫存的 SQL 擋不住同一張單同時存,靠這一句先擋。
代價
被擋的人剛打的東西要重來或另外想辦法留住;每一句更新、刪除單頭的 SQL 都要記得帶版本;系統自己回寫別張單時要不要動版本(第 6 題定了:要)。
沒選的
  • 後存的蓋掉先存的(select ... for update 排隊、不比版本):先存的修改會被後存的畫面上的舊資料蓋回去,兩個人都不知道。
  • 打開要改時就佔住:沒關分頁就走掉的人會一直佔著;放掉之後還是要版本欄位擋,等於兩套都做;原型沒有這個畫面。
驗證
實測過 2026-11-18:不帶版本時同一張單兩邊同時存,異動寫了兩份、現有量多扣一次(洞是真的);帶版本時後到的那句等了約 3 秒、回報 UPDATE 0,異動只有一份。
出處
data-model.md 第 5 題、檔尾「實測紀錄」第 4 項
還沒裁、選完之後還開著的:
  • 被擋之後畫面怎麼讓他處理(Claude 的看法:可以等做單據頁時再問);客戶商品這類資料與設定清單要不要也有版本欄位。

資料模型第 6 題別張單累計出來的數字:存起來,鎖住後重算 2026-11-18

選的:訂單的已交、採購單的已進、銷貨單與進貨單的已退、已收與已付金額,都存在被影響的那一列(或那張單)上。造成它的那張單存檔時,同一筆交易裡先更新被影響那張單的單頭(版本加 1,同時鎖住它),再用一句 SQL 從來源明細整個重算。(Jesse 選「存起來,鎖住後重算」,照推薦)

來源檔的 SQL

-- 銷貨單的單頭與明細存好之後,同一筆交易:

-- (a) 鎖住來源訂單,版本加 1
update sales_order
   set version = version + 1
 where company_id = @CompanyId and id = @OrderId;

-- (b) 新的一句:這張訂單每一列的已交整個重算
update sales_order_line ol
   set shipped_qty = coalesce((
         select sum(sl.qty)
           from sale_line sl
          where sl.company_id = ol.company_id
            and sl.order_line_id = ol.id), 0)
 where ol.company_id = @CompanyId and ol.order_id = @OrderId;

-- 訂單清單「還沒交完」:直接比
select o.*
  from sales_order o
 where o.company_id = @CompanyId
   and o.closed_at is null
   and exists (select 1 from sales_order_line ol
                where ol.company_id = o.company_id
                  and ol.order_id = o.id
                  and ol.qty > ol.shipped_qty);
白話與例子
為什麼分成 (a)(b) 兩句:(a) 讓對同一張訂單出貨的交易排隊;(b) 是排到之後才開始的新的一句,看得到前一個交易剛提交的銷貨明細。寫成一句的話,等完之後加總用的還是等之前看到的資料。順便定了第 5 題留下的:系統回寫別張單時要把那張單的版本加 1。
理由
跟第 3 題同一個教訓,舊單不鎖、每次當場加總只會越用越慢;是重算不是加減,錯了下次存檔會自己修正,新增、修改、刪除、復原四條路走的是同一句。
代價
同一件事存兩份,每一種累計數字要一句重算與一句對帳的 SQL;兩個人同時對同一張訂單出貨要排隊;正開著那張訂單在改的人會被擋;「截至某一天還欠多少」這種照日期的還是要讀沖帳明細。
沒選的
  • 存起來、加減差額(原型的做法):差額是程式算的,算錯或漏一次就一直錯下去。
  • 不存、每次加總:訂單清單每開一次都要把所有訂單的每一列對銷貨明細加總,越用越慢。
驗證
實測過 2026-11-18:訂單一列訂 10,兩邊同時各出 3 與 4。兩句的寫法已交是 7、訂單版本變 3;只跑重算那一句的已交是 4(實際 7,漏掉對方的)。
出處
data-model.md 第 6 題、檔尾「實測紀錄」第 4 項
還沒裁、選完之後還開著的:
  • 每一種累計數字各自的來源與重算的那一句(已進、已退、已收、已付、訂金還剩多少);對帳的 SQL。

資料模型第 7 題成本:存一張每月單位成本表,存單時往後重算 2026-11-18

選的:一張「每樣商品每個月的單位成本」表,只存有進貨、進貨退出、組裝的月份。存單的同一筆交易裡,把這張單碰到的商品從單據那個月往後重算,有進來的月份一個月跑一句 SQL。報表 join「這個月或之前最近的一筆」。(Jesse 選「存起來,存單時重算」,照推薦)

來源檔的 SQL(2026-11-18 跑過,跟手算一樣;組合商品那一輪沒跑)

-- 異動表多一欄:只有進貨(正)、進貨退出(負)這類的列有金額
alter table stock_move add column value numeric;

create table product_cost_month (
  company_id bigint  not null,
  product_id bigint  not null,
  month      date    not null,             -- 每月 1 號
  beg_qty    numeric not null,             -- 月初帳面數量(各倉合計,可能是負的)
  in_qty     numeric not null,             -- 本月進來的數量
  in_value   numeric not null,             -- 本月進來的金額
  unit_cost  numeric(18,2),
  primary key (company_id, product_id, month)
);

-- 重算之前:把這幾樣商品從 @Month 起的舊結果刪掉
delete from product_cost_month
 where company_id = @CompanyId and product_id = any(@ProductIds) and month >= @Month;

-- 要跑哪幾個月
select distinct date_trunc('month', move_date)::date as month
  from stock_move
 where company_id = @CompanyId and product_id = any(@ProductIds)
   and value is not null and move_date >= @Month
 order by 1;

-- 每個月跑一次(舊的月份在前)
insert into product_cost_month (company_id, product_id, month, beg_qty, in_qty, in_value, unit_cost)
select @CompanyId, f.product_id, @Month, b.beg_qty, f.in_qty, f.in_value,
       case when u.beg_used + f.in_qty > 0
             and u.beg_used * coalesce(p.unit_cost, 0) + f.in_value >= 0
            then round((u.beg_used * coalesce(p.unit_cost, 0) + f.in_value) / (u.beg_used + f.in_qty), 2)
            else p.unit_cost end
  from (select product_id, sum(qty) as in_qty, sum(value) as in_value
          from stock_move
         where company_id = @CompanyId and product_id = any(@ProductIds) and value is not null
           and move_date >= @Month and move_date < @Month + interval '1 month'
         group by product_id) f
  cross join lateral (select coalesce(sum(m.qty), 0) as beg_qty
                        from stock_move m
                       where m.company_id = @CompanyId and m.product_id = f.product_id
                         and m.move_date < @Month) b
  left join lateral (select c.unit_cost
                       from product_cost_month c
                      where c.company_id = @CompanyId and c.product_id = f.product_id and c.month < @Month
                      order by c.month desc limit 1) p on true
  cross join lateral (select case when b.beg_qty > 0 and p.unit_cost is not null
                                  then b.beg_qty else 0 end as beg_used) u
on conflict (company_id, product_id, month) do update
   set beg_qty = excluded.beg_qty, in_qty = excluded.in_qty,
       in_value = excluded.in_value, unit_cost = excluded.unit_cost;

-- 報表:這個月或之前最近的一筆
left join lateral (
  select unit_cost from product_cost_month c
   where c.company_id = l.company_id and c.product_id = l.product_id and c.month <= s.doc_date
   order by c.month desc limit 1) c on true
白話與例子
什麼時候要跑:進貨類的單從單據那個月起;其他會動庫存的單從單據的下個月起;後面沒有任何有進來的月份就不用跑,所以今天開的銷貨單不用重算任何東西。業務規則(每月加權平均、全公司一個成本、月初是負的不算等)在 docs\decisions\cost.md。
理由
報表是自己寫 SQL 讀表的,成本存成表才 join 得到,銷售分析表的成本、毛利、照毛利排名都能留在 SQL 裡;全站只有這一個來源;存完馬上是對的;舊單不鎖,不存的話每次都要從開帳算到現在。
代價
異動表多一欄金額;補登很久以前的單,存檔要多跑幾十句;要先鎖住那幾樣商品再算,同時進同一樣商品的兩張單要排隊;組合商品要在子件算完之後再算一輪;初始盤點改了要全部重算(「店的預設發票別改了要全部重算」在第 12 題之後不再成立)。
沒選的
  • 存起來、背景工作重算:算完之前報表看到的是舊成本;要多一套背景工作,場景 ① 的測試機也要跑著它。
  • 存起來、要看時才算:報表模組的帳號只有讀的權限,每個用到成本的頁都要先繞回本體去重算,漏一頁就看到舊的;「讀」會寫資料庫。
  • 不存、每次從頭算(原型的做法):越用越慢;成本在 C# 裡算,報表的 SQL join 不到。
驗證
實測過 2026-11-18,一樣商品、起點成本 100:8 月 → 110;9 月 → 107.5;11 月月初 −8 不算 → 120;12 月沿用 120;補登 9 月進 10 件 900 元往後重算 → 9 月 104、11 月 117.33、12 月 115.42,都跟手算一樣。報表那種 join 走主鍵索引倒著找(Index Scan Backward),沒有排序。沒跑:組合商品那一輪;先鎖商品再算、兩邊同時存;大量資料的速度。起點的成本存成起算月前一個月的一列,是 Claude 測試時的做法,沒問。
出處
data-model.md 第 7 題
還沒裁、選完之後還開著的:
  • 鎖哪一列(商品那一列,還是另外一張表);內部多留幾位小數。

資料模型第 8 題金額、單價、數量、單位成本:domain 自訂型別,位數多了報錯 2026-11-18

選的:用 domain 定四個型別,底下是 numeric 加檢查;小數位數超過或數字太大就報錯、整筆交易退回。欄位直接寫型別名稱。(Jesse 選「自訂型別,多了報錯」,照推薦)

來源檔的 SQL(2026-11-18 實測過)

create domain amount as numeric      -- 金額:整數
  check (value = round(value, 0) and abs(value) < 1e14);
create domain price as numeric       -- 單價:最多 2 位
  check (value = round(value, 2) and abs(value) < 1e12);
create domain qty as numeric         -- 數量:最多 4 位
  check (value = round(value, 4) and abs(value) < 1e10);
create domain unit_cost as numeric   -- 單位成本:最多 2 位
  check (value = round(value, 2) and abs(value) < 1e12);

create table sale_line (
  qty    qty    not null,
  price  price  not null,
  amount amount not null
);
白話與例子
Jesse 第一次取消視窗時說「你詳細解釋一下這題再問甚麼」。Claude 用一列銷貨明細(1.5 公斤 × 35.50=53.25 → 53)講三種數字的位數、四個選項在「程式忘了進位、送來 12.345」時各自的反應,他看完說再問一次。
理由
程式忘了進位時資料庫大聲報錯,測試當場就爆,不會悄悄存進跟 C# 手上不一樣的數字;位數的規定只寫在一個地方;看表時一眼知道是金額、單價還是數量。
代價
domain 比較少見;以後改位數時,改 domain 的檢查會把所有用到的欄位重新驗一遍;數量統一最多 4 位,個別商品單位是 0 位還是 2 位由程式管;從 C#+Dapper 傳參數進來還沒實測。
沒選的
  • numeric(14,2) 這種固定位數:多出來的小數不會報錯、會悄悄四捨五入。
  • 放大成整數存 bigint:直接下 SQL 看到的是 3550、15000,要自己換算;SQL 裡相乘之後要記得除回來再進位。
  • 不限位數的 numeric:程式忘了進位時照存,不報錯也不修正。
驗證
實測過 2026-11-18:numeric(14,2) 寫進 12.345 存成 12.35、numeric(14,0) 寫進 609.5 存成 610;domain 對單價 12.345、數量 1.23456、金額 0.5 都報 value for domain ... violates check constraint;jsonb_populate_record(回收桶復原)遇到位數不對也報錯。
出處
data-model.md 第 8 題
還沒裁、選完之後還開著的:
  • 稅額、折扣率、稅率要不要另外的型別;單位成本內部要不要多留幾位。

資料模型第 9 題不分公司的表:壓到最少+權限 2026-11-18

選的:帳號類的表不加列層級安全性。不分公司的只留三張:帳號、公司、誰能進哪幾家;員工資料、邀請都帶公司編號、照舊有規則。碰這三張表的 SQL 只放在「帳號與公司」模組;報表的角色完全沒有權限。參考資料(銀行分行代碼、第 4 題的對照表)程式的角色只給讀的權限。(Jesse 選「表壓到最少+權限」,照推薦)

來源檔 SQL 的節錄。同一段前面的建表那幾行沒有收:來源檔 2026-11-19 補記寫,建表例子的 password_hash 與以「我們存密碼雜湊」為前提的代價、沒選的方案,「都是登入交給 Cognito(backend.md 第 7 題)之前寫的。現在 LiteERP 不存密碼,這一欄不會有」

grant select, insert, update, delete on app_user, company, company_member to app_rw;
-- app_report:不給
grant select on doc_kind to app_rw, app_report;   -- 參考資料:程式只能讀

-- 登入後列出我能進的公司
select c.id, c.name
  from company_member m
  join company c on c.id = m.company_id
 where m.user_id = @UserId;
白話與例子
為什麼這幾張不能帶公司編號:一個 e-mail 可以進好幾家店;登入之後、選公司之前,程式就要讀帳號、列出能進哪幾家,這時候還沒有「現在是哪一家」可以設。2026-11-19 之後:登入交給 Cognito、登入狀態用自己的登入紀錄表,login_session 是跟著人、不跟著公司的第四張表,密碼與驗證碼的表則不需要了;「不分公司的只留三張」要改寫成四張,沒有另外問。
理由
會碰這幾張表的 SQL 大約二十句(Claude 的估計),集中在一個模組、逐句審得完;登入、檢查 e-mail 重複、邀請已經有帳號的人都不用繞路;把能帶公司編號的都帶上,沒有規則擋著的資料就只剩這幾張。
代價
這幾張表沒有資料庫這道保險,那二十句裡有一句漏了條件就會讀到別人的帳號;其他模組用的是同一個資料庫角色,「只有帳號模組能碰」靠的是程式的結構與審查,不是資料庫。
沒選的
  • 再加一道照使用者的列層級安全性:登入、檢查 e-mail 重複、邀請已有帳號的人,每一個都要另外開一個繞過規則的函式,每個都是要審的洞;沒有實測過。
  • 照選的做、再加密碼那一欄只有登入專用的角色讀得到:多一個角色、多一組連線與密碼,三個部署場景都要設;欄位層級的權限沒有實測過。(來源檔 2026-11-19 補記:這一條以「我們存密碼雜湊」為前提,是登入交給 Cognito 之前寫的;現在 LiteERP 不存密碼。)
驗證
實測過 2026-11-18(database.md 第 2 題):列層級安全性整套、對照表只能讀、報表的角色碰不到帳號類的表。
出處
data-model.md 第 9 題
還沒裁、選完之後還開著的:
  • company_member 與帶公司編號的員工資料怎麼對起來,以及邀請還沒接受的人放哪裡;公司這張表的到期日、試用、鎖住狀態。

資料模型第 10 題日期與時間:date、timestamptz、第一次啟動時指定時區 2026-11-18

選的:單據日期、發票日期用 date。時間戳記(建立、修改、刪除的時間,操作紀錄的時間)用帶時區的 timestamptz。第一次啟動時用環境變數這類方式指定時區(沒指定就是 Asia/Taipei),設成資料庫的預設時區,並記在一張表裡。(Jesse 選「佈署時指定時區」;這個做法是他自己提的)

來源檔的 SQL

-- 第一次啟動
alter database liteerp set timezone = 'Asia/Taipei';
insert into system_setting (key, value) values ('timezone', 'Asia/Taipei');

create table recycle_bin (
  deleted_at timestamptz not null
);

-- SQL 裡直接就是當地時間
select deleted_at, deleted_at::date, current_date from recycle_bin;

-- 每次啟動都比對,不一致就不啟動
show timezone;
select value from system_setting where key = 'timezone';
白話與例子
Jesse 的原話:「系統第一次啟動的時候用某種方式指定時區 (例如環境變數之類的), 然後用該時區建立所有的資料表, 並且把時區記錄在資料庫的某個資料表內. 若未指定則用預設值 Asia/Taipei. 這個新想法推翻了我之前的想法, 他讓資料庫使用時區而不是 utc.」Claude 答這個更適合這個產品,前提是欄位用 timestamptz。成本看單據日期、營業稅看發票日期,都是 date,不受時區影響。
理由
SQL 最自然,::date、current_date、照日期分組都直接是對的;直接下 SQL 看到的就是當地時間;存的還是絕對的時刻,機器放哪裡、哪台機器時區設錯都不影響;一個部署只有一種算法。
代價
一個部署裡所有的店都是同一個時區;以後要改成每家店自己的時區,用到 ::date、current_date 的 SQL 都要找出來改;啟動時要比對資料庫實際的時區、表裡記的、這次指定的,不一致就不啟動;第一次之後不給改。
沒選的
  • 維持 UTC、時區是設定值由 C# 換算:SQL 裡不能把時間換成日期、不能用 current_date,違反了不報錯、台灣早上 8 點以前的會悄悄算成前一天。
  • 不帶時區的 timestamp 存當地的牆上時間:每個寫入的地方都要保證用對時區;欄位不知道自己是哪個時區。
驗證
實測過 2026-11-18,PostgreSQL 17.12 官方容器:預設時區是 Etc/UTC;同一個 now() 寫進 timestamp 存的是 05:23(當下台灣 13:23),沒有報錯;連線設成 Asia/Taipei 後 timestamptz 顯示 13:23+08;alter database ... set timezone 之後新的連線 show timezone 是 Asia/Taipei。
出處
data-model.md 第 10 題
還沒裁、選完之後還開著的:
  • 他說的北美是機器還是客人(Claude 問了,他沒有回答這一句);system_setting 這張表還放什麼、是不是不分公司的表;還沒裁 Claude 列的七條注意事項(用時區名稱不存 +8、設在資料庫上、啟動要比對等),Jesse 選的時候看過,沒有逐條問。

資料模型第 11 題時間與「今天」怎麼交給前端:後端排好字+給今天 2026-11-18

選的:後端照佈署的時區把時間排成畫面要的字再回傳。前端全站只有一個「今天」,值由後端給:登入時給、每個回應順便帶、跨過半夜或分頁切回來時再要一次。日期欄位的值是字串。前端沒有任何時區的程式。(Jesse 選「後端排好字+給今天」,照推薦)

來源檔的 JSON

{
  "today": "2026-11-18",
  "secondsToMidnight": 38196,
  "createdAt": "2026/11/18 13:23:24",
  "docDate": "2026-11-18"
}
白話與例子
操作紀錄有一筆是台灣 11/18 13:23:24 建立的,老闆人在紐約用筆電打開、要開一張新單:他看到的是 13:23:24,新單預設的日期是店裡的今天。Jesse 取消視窗時問:「後端排好字讓前端顯示的部分自然是沒問題, 但是前端有些功能必須選日期, 前端也必須顯示當前日期, 這時候即使人在紐約也需要用台灣時區的當前日期, 這段你怎麼處理?」做法:後端同時給「離下一個半夜還有幾秒」,前端計時到了再要一次;日期字串不要丟進 Date;原型的「今天」本來就是一個固定值,39 個檔、55 個地方讀它,所以正式產品只要把那一個值的來源換成後端。這題是前端與 API 的事,因為是第 10 題帶出來的所以記在資料模型。
理由
Jesse 只審後端,這樣時區整個留在後端,前端沒有地方會寫錯;原型本來就是全站共用一個今天。
代價
時間的格式由後端決定;前端不能自己照時間排序或算「幾分鐘前」;瀏覽器內建日期欄位點開的小月曆,圈「今天」用的是裝置的日期、程式改不了(存進去的值不受影響;要連這個也對得自己做月曆元件,Claude 判斷不值得,Jesse 沒有另外表示)。
沒選的
  • 後端給絕對的時刻+時區名稱,前端用 Intl.DateTimeFormat 指定時區排:每個顯示時間的地方都要帶時區,漏一處就變回裝置的時區,在台灣測不出來,前端沒有人審。
  • 照瀏覽器的時區:人在紐約會看到 00:23:24;開新單預設的是紐約的今天。
驗證
實測過 2026-11-18,Node 26,這台電腦是台北時區、假裝店在紐約:同一個時刻照裝置排是 13:23:24、指定 America/New_York 是 00:23:24;new Date('2026-11-18') 再照紐約排出來是 2026-11-17(差一天)。
出處
data-model.md 第 11 題
還沒裁、選完之後還開著的:
  • AI 助理拿到的時間也是排好的字,它要不要另外拿精確的時刻(Claude 沒想清楚,沒問)。

資料模型第 12 題店的身分改了,舊進貨的成本不跟著變:身分記在單據上 2026-11-18

選的:公司多一欄「統一發票」(使用統一發票/免用統一發票)。進貨單、進貨退出單、其他支出單的單頭各多兩欄:開單時公司的身分(畫面上叫「公司當時」)、不計入進項稅額。這張單的稅拿不拿得回來只看單據上的欄位,存單時算好。公司那一欄改了只影響之後開的單,沒有「設定改了全部重算」這個動作。(做法是 Jesse 自己提的)

白話與例子
欄位:公司表一欄;三種單據的單頭各兩欄。身分那一欄的型別照第 4 題(smallint+C# enum+對照表),公司與單據用同一個 enum;不計入進項稅額是布林值;欄名沒定。對第 7 題的影響:異動表的 value 在存單時照單頭這四件事算,之後只有那張單再存一次才會變。業務規則全部在 docs\decisions\cost.md「2026-11-18 第三輪」。
理由
存起來的衍生資料(value、每月成本)只會因為單據存檔而變,跟第 3、6、7 題同一個路子;少一種「改設定觸發整批重算」的動作,也就少一段要鎖住全部商品的時間。
代價
設錯了要一張一張改、補打舊單要手動改這一欄(業務上的代價,Jesse 接受)。資料上,「公司當時」幾乎每一列都跟公司現在的值一樣。
沒選的
  • Claude 第一次推薦的:一張「從哪一天起、使用或免用」的小表,存單時照單據日期查身分,身分改了重算那天之後的單。多一張表、多一個整批重算的動作、報表要照日期問身分。
驗證
沒實測:這一題沒有跑任何東西。
出處
data-model.md 第 12 題
還沒裁、選完之後還開著的:
  • 還沒裁 寫後端時要守的四條(「稅拿不拿得回來」只有一個地方判斷;公司那一欄只用在三件事;轉單帶原單的值;切換身分時同一筆交易改預設發票別),Claude 寫的,Jesse 沒有逐條裁。

資料模型第 13 題19 種單據的資料表怎麼切:一種單據一組表 2026-11-19

選的:每一種單據有自己的單頭表與明細表(訂單是 sales_order、sales_order_line,銷貨單是 sale、sale_line,以此類推)。不照家族共用、不做共同的單頭表、不放 JSON。(Jesse 選「一種單據一組表」,照推薦)

來源檔的 SQL(建表的寫法,沒有跑過)

-- 其餘欄位省略;表名是例子,正式名稱還沒定
create table sales_order (                 -- 訂單
  company_id    bigint not null,
  id            bigint generated by default as identity,
  doc_no        text   not null,
  doc_date      date   not null,
  customer_id   bigint,                    -- 沒建檔的客戶是空的
  customer_name text,
  delivery_date date,
  closed_at     timestamptz,
  version       int    not null default 1,
  primary key (company_id, id),
  foreign key (company_id, customer_id)
    references customer (company_id, id)
);

create table sale (                        -- 銷貨單
  company_id    bigint not null,
  id            bigint generated by default as identity,
  doc_no        text   not null,
  doc_date      date   not null,
  customer_id   bigint,
  customer_name text,
  warehouse_id  bigint not null,           -- 銷貨單一定有倉庫
  order_id      bigint,                    -- 只能指到訂單
  version       int    not null default 1,
  primary key (company_id, id),
  foreign key (company_id, customer_id)
    references customer (company_id, id),
  foreign key (company_id, warehouse_id)
    references warehouse (company_id, id),
  foreign key (company_id, order_id)
    references sales_order (company_id, id)
);
白話與例子
問之前數的事實(從原型畫面上每種單據的空白單數的):單據 19 種,17 種有明細,存提轉帳單與資金異動單只有單頭;買賣 7 種共同的單頭欄位 9 個;19 種全部都有的只有單號、日期、經辦人。共 36 張左右(README.md)。起因:第 1 到 12 題的例子都寫成一種單據一組表,但那是 Claude 自己的假設,沒有問過。
理由
「銷貨單一定有倉庫」「銷貨單只能指到訂單」這類規則資料庫直接擋(not null、外鍵);SQL 讀起來就是那張單;改一種不會碰到別種;前十二題已經實測過的 SQL 都是這個寫法。
代價
  • 買賣 7 種的建表與存檔 SQL 會有七份長得很像的,Jesse 要審七次;一個共同的欄位要改就是改好幾張表。
  • 庫存異動表、回收桶、操作紀錄指回單據用的是「種類+id」,加不了外鍵,只能靠程式與對帳的 SQL。
  • 跨 19 種的清單(行事曆「開過的單」)要 union all。
沒選的
  • 照家族共用(6 組約 11 張):每一句讀取都要帶種類,漏一句數字默默算錯;資料庫擋不了銷貨單指到報價單。
  • 共同單頭+各自延伸(共 37 張):每讀一張單要接兩張表、每存一張單要寫兩張表;共同的欄位只有四五個。
  • 一張表+JSON:第 8 題的四個自訂型別、「被用到就不能刪」都管不到;從資料表審不出欄位。Claude 不推薦,列出來是因為做得出來。
驗證
沒實測:建表的寫法沒有跑過,也沒有效能上的主張。(2026-11-19 補跑時只建了訂單與銷貨單用到的欄位。)
出處
data-model.md 第 13 題
還沒裁、選完之後還開著的:
  • 七份很像的存檔 SQL 怎麼組織;指回單據的「種類+id」要一句對帳的 SQL;跨 19 種的清單怎麼讀(可以等做到行事曆那一頁再定);表的正式名稱。

資料模型第 14 題改單時明細怎麼存:全部逐列比對 2026-11-19

選的:17 種有明細的單據都一樣:明細有自己的 id,改單之後不變,另外一欄 line_no 記畫面上第幾列。前端送回來的每一列,舊的帶 id、新加的 id 是空的;存檔時同一筆交易跑三句:刪掉畫面上拿掉的、改內容有變的、加新的。沒動的列不碰。(Jesse 選「全部逐列比對」,照推薦)

來源檔的 SQL(2026-11-19 下午補跑,三句都對)

-- @Lines 是一包 JSON,只是先這樣寫;明細怎麼從 C# 傳進 SQL 是另一題
-- ① 刪掉畫面上已經拿掉的列(已交過的列有銷貨明細用外鍵指著,資料庫會擋)
delete from sales_order_line l
 where l.company_id = @CompanyId
   and l.order_id = @Id
   and not exists (
         select 1
           from jsonb_to_recordset(@Lines::jsonb) as x(id bigint)
          where x.id = l.id);

-- ② 改還在的列;內容沒變的列不寫
update sales_order_line l
   set line_no = x.line_no, product_id = x.product_id,
       qty = x.qty, price = x.price, amount = x.amount, note = x.note
  from jsonb_to_recordset(@Lines::jsonb)
       as x(id bigint, line_no int, product_id bigint,
            qty qty, price price, amount amount, note text)
 where l.company_id = @CompanyId
   and l.order_id = @Id
   and l.id = x.id
   and (l.line_no, l.product_id, l.qty, l.price, l.amount, l.note)
       is distinct from
       (x.line_no, x.product_id, x.qty, x.price, x.amount, x.note);

-- ③ 加新的列
insert into sales_order_line
  (company_id, order_id, line_no, product_id, qty, price, amount, note)
select @CompanyId, @Id, x.line_no, x.product_id,
       x.qty, x.price, x.amount, x.note
  from jsonb_to_recordset(@Lines::jsonb)
       as x(id bigint, line_no int, product_id bigint,
            qty qty, price price, amount amount, note text)
 where x.id is null;
白話與例子
訂單 3 列,蘇打餅乾 10(id 101,已交 4,銷貨明細 501 指著它)、牛奶糖 5(102)、原子筆 20(103)。改單:牛奶糖改 8、原子筆刪掉、加洋芋片 6。結果:101 沒碰、已交 4 還在;102 數量改成 8;103 刪掉;洋芋片新增拿到 104。為什麼庫存異動表可以全刪重寫、明細不行:異動表的列沒有任何人指著;單據的明細有人指(訂單、採購單、銷貨單、進貨單 4 種)。Jesse 第一次取消視窗時說「你可能要解釋的詳細一點我才知道妳在說甚麼」,Claude 改從資料表上的列講起,他看完說再問一次。
理由
4 種被指到的本來就非這樣不可;其他 13 種用同一種寫法,審的時候只要認得一種;別張單指著的列刪不掉,資料庫當場擋;已交、已退留在原本那一列;幾百列的盤點單改一列只寫一列;AI 助理說「改第 3 列」有固定的 id 可以指。
代價
每種單的存檔是三句不是兩句;前端每一列要帶著 id 送回來;多一欄 line_no;17 種都要寫這三句。
沒選的
  • 全刪重寫+用項次當身分:別張單指到明細不能加外鍵;已交每次被清成 0、要重算;幾百列的盤點單每次全部重寫。
  • 混用(被指到的 4 種逐列比對,其他 13 種全刪重寫):全站兩種寫法;哪天有一種單的明細開始被指到要整個改寫法。
  • 全刪重寫+id 照舊寫回(外鍵 deferrable initially deferred):刪到已交過的列要到提交那一刻才報錯;已交照樣被清成 0;id 是前端送來的,程式要自己擋亂填。
驗證
實測過 2026-11-19 下午補跑,表建在 core、account schema,金額單價數量用第 8 題的 domain:刪 1、改 1、新增 1(拿到 104),101 的列版本(xmin)沒變;送回的清單沒有 101 時報 violates foreign key constraint ... is still referenced from table "sale_line";可以空的欄位鍵名打錯(delivery_date 打成 delivry_date)不會報錯、悄悄存成空的;送回一個不屬於這張單的 id(999)改到 0 列、不報錯,程式要自己比對筆數。
出處
data-model.md 第 14 題、檔尾「2026-11-19 補跑」第 1 項
還沒裁、選完之後還開著的:
  • line_no 要不要加唯一限制(Claude 的想法是不加,沒問);「商品與單價不能改、數量不能比已交少」外鍵擋不到,還是程式的規則。

資料模型第 15 題單頭存未稅、稅額、總金額:三個都存 2026-11-19

選的:有課稅別的 9 種單據(買賣 7 種+其他收入單、其他支出單),單頭存未稅、稅額、總金額三個數字,存檔時由後端 C# 算好寫進去。清單、帳款表、營業稅申報表直接讀單頭,SQL 裡不算稅。(Jesse 選「三個都存」,照推薦)

來源檔的 SQL(對帳那一句 2026-11-19 下午補跑過)

-- 其餘欄位省略
create table sale (
  company_id   bigint   not null,
  id           bigint   generated by default as identity,
  doc_no       text     not null,
  doc_date     date     not null,
  tax_type     smallint references tax_type (id),  -- 免用統一發票的店是空的
  net_amount   amount   not null,                  -- 未稅
  tax_amount   amount   not null,                  -- 稅額
  total_amount amount   not null,                  -- 總金額
  version      int      not null default 1,
  primary key (company_id, id)
);

-- 對帳:查出來有列就是單頭跟明細對不起來
select s.id
  from sale s
  join lateral (
         select coalesce(sum(l.amount), 0) as lines
           from sale_line l
          where l.company_id = s.company_id
            and l.sale_id = s.id) x on true
 where s.company_id = @CompanyId
   and x.lines <> case when s.tax_type = @TaxInclusive
                       then s.total_amount
                       else s.net_amount end;
白話與例子
應稅外加,明細 53+120+77=250,稅額 12.5 → 13,總金額 263。會讀這三個數字的地方:9 種單據清單的總金額欄、應收應付帳款表、銷售分析表與進貨分析表、營業稅申報表、損益表。
理由
算稅的算術已經有 C# 與 TypeScript 兩份,不存的話 SQL 是第三份、散在每一張報表裡,題庫管不到;存檔時後端本來就要重算一次,數字是現成的;以後算稅的規則改了,舊單的數字不動(跟第 12 題「單據自己帶著事實」同一個方向)。
代價
同一件事存兩份,明細改了單頭忘了跟著改就會錯,要一句對帳的 SQL;以後發現算錯,要補一支更新舊單的腳本。
沒選的
  • 只存稅額:清單每張單都要加明細;「外加要加稅額、內含不用」的判斷每一句用到的 SQL 都要寫。
  • 只存總金額:營業稅申報表、分析表、損益表還是要在 SQL 算稅;規則改了之後兩個數字對不起來。
  • 都不存:算稅的算術在 SQL 是第三份;規則改了舊單全部跟著變。
驗證
實測過 2026-11-19 下午補跑:內含 53+120+77、單頭未稅 238、稅額 12、總金額 250,對帳回 0 列,改掉一列的金額後查到那張單;round(250 * 0.05) 是 13、250 - round(250 / 1.05) 是 12、round(12.5) 是 13、round(-12.5) 是 −13。沒量過「不存」到底慢多少,推薦的理由是算術只留兩份、不是效能。對帳只比了明細合計,稅額本身對不對還沒寫。
出處
data-model.md 第 15 題、檔尾「2026-11-19 補跑」第 3、4 項
還沒裁、選完之後還開著的:
  • 其他 10 種單據單頭要存哪些合計;稅率要不要記在單據上。

資料模型第 16 題每一列分到的金額:存在明細上 2026-11-19

選的:會進報表的 6 種單據(銷貨、銷貨退回、進貨、進貨退出、其他收入、其他支出),明細多一欄存「這一列分到的金額」,存檔時由後端 C# 分好寫進去。客戶那一邊存分到的未稅金額(net_amount),廠商那一邊存算進成本的金額(cost_amount)。報表的 SQL 只做加總;第 7 題寫庫存異動金額(stock_move.value)的那一句直接抄這一欄。(Jesse 選「存在明細上」,照推薦)

來源檔的 SQL(建表與對帳 2026-11-19 下午補跑過)

-- 其餘欄位省略
create table sale_line (
  company_id bigint not null,
  id         bigint generated by default as identity,
  sale_id    bigint not null,
  line_no    int    not null,
  product_id bigint not null,
  qty        qty    not null,
  price      price  not null,
  amount     amount not null,   -- 數量 × 單價
  net_amount amount not null,   -- 分到的未稅金額
  primary key (company_id, id)
);

-- 對帳:查出來有列就是每列加起來不等於單頭
select s.id
  from sale s
  join sale_line l on l.company_id = s.company_id and l.sale_id = s.id
 where s.company_id = @CompanyId
 group by s.id, s.net_amount
having sum(l.net_amount) <> s.net_amount;
白話與例子
應稅內含,明細 53+120+77=250,單頭未稅 238、稅額 12。照比例是 50.456、114.24、73.304,四捨五入 50、114、73 合計 237,零頭 1 給最大的 120 那一列,結果 50、115、73。分法(照比例、四捨五入到整數、零頭放在金額最大的那一列)是業務規則已經定的(sales-analysis.md 第 2 題)。
理由
跟第 15 題同一個,分法只留在 C# 與題庫,SQL 只做加總;兩張報表不可能對同一張單分出不同的數字;以後分法改了舊單不動;順便補上第 7 題「沒跑的」那一項(進貨單每一列算進成本的金額怎麼來)。
代價
又多一份存起來的數字,改了一列忘了重分就會錯,要一句對帳(每列加起來等於單頭);6 種明細表各多一欄。
沒選的
  • 每句 SQL 當場分(視窗函式):二十幾行的 SQL 要出現在每一句用到的報表裡,寫法稍有不同兩張報表就對不起來。
  • 做成檢視表:跟 C# 的分法還是兩份;6 種各一張檢視表;每次查還是整段重分。
  • 只有進貨類存、銷貨當場分:兩邊做法不一樣;銷貨那邊有「每句當場分」全部的代價。
驗證
實測過 2026-11-19 下午補跑:明細分到 50、115、73 時對帳回 0 列;改掉一列的金額後查到那張單。238 照比例分合計 237、差的 1 要另外補到最大那一列,這一步在 C#,SQL 沒做。
出處
data-model.md 第 16 題、檔尾「2026-11-19 補跑」第 3、4 項
還沒裁、選完之後還開著的:
  • 其他收入單、其他支出單的明細那一欄叫什麼、分的是什麼;廠商那一邊的單頭要不要另外存「這張的稅拿不拿得回來」的結果。

資料模型第 17 題按兩下儲存、網路重送:新增時帶 create_token、存在單頭上設唯一 2026-11-19

選的:能新增的表多一欄 create_token(uuid,可以空)加唯一條件(公司編號,create_token)。畫面開新單時產生一個隨機代碼、存檔時帶上來;同一個代碼只存得進一次,第二次不再寫明細與庫存,直接把第一次那張的 id 回給畫面。改單與刪單照第 5 題的版本欄位擋。(Jesse 選「新增時帶代碼、存在單頭上」,照推薦)

來源檔的 SQL(示意:欄位名稱沒定、沒跑過)

-- 示意:欄位名稱沒定、沒跑過
create_token uuid null,
unique (company_id, create_token)

insert into sale (company_id, create_token, …)
values (@CompanyId, @CreateToken, …)
on conflict (company_id, create_token) do nothing
returning id;
-- 沒有回傳列=這個代碼存過了,讀出原本那張的 id 回去,明細與庫存都不再做
白話與例子
阿豪開一張新的銷貨單按儲存,網路卡住沒回應,他又按了一次;第一次其實存成功了。不擋的話 sale 多出 1203、1204 兩列一模一樣的單,庫存少兩次、應收多兩次。第 2 題選 bigint、資料庫發號時就寫了「按兩下儲存要另外擋」。跟著定的(選項上寫的):系統自己產生的單(例如自動產生的組裝單)沒有代碼、欄位留空,唯一條件允許多筆空值;按下去就鎖住按鈕這件事前端照樣做。
理由
會出大事的只有新增,就只在新增多做一件事;SQL 寫在審得到的地方;不用多一張要清的表。
代價
  • 每一張能新增的表多一個 16 bytes 的欄位和一個唯一索引,每次新增多寫一筆索引。
  • 改單重送時第二次會被版本擋下來,畫面顯示「被改過了」,其實是他自己第一次存成功;資料沒錯,訊息會嚇到人。
沒選的
  • 執行器統一擋(一張「處理過的請求」表):每一次寫入都多寫一列,這張表要定期清、誰來清又是一題。
  • 只靠前端鎖按鈕:擋不住回應沒回來、重新整理後再按一次的情況。
  • id 改用 UUID、瀏覽器先產生:要推翻第 2 題,主鍵、外鍵、索引都變大。
  • 後端比內容:真的要開兩張一樣的單會被誤擋,幾秒要多長沒有正確答案。
驗證
沒跑過:SQL;兩個一樣的請求同時到時第二個會等第一個交易結束再判定衝突,是 Claude 對 on conflict do nothing 的理解,沒實測;瀏覽器的 crypto.randomUUID() 只有 https 與 localhost 能用,是 Claude 記得的、沒查。
出處
data-model.md 第 17 題
還沒裁、選完之後還開著的:
  • 哪些表算「能新增的」(客戶、商品這類基本資料要不要也加);第二次回去的內容要不要跟第一次一模一樣;舊的代碼要不要過一段時間清成空的;改單重送那個嚇人的訊息前端要不要另外處理。

資料模型第 18 題每張表只加建立時間,不加最後修改時間 2026-11-19

選的:每一張表(單頭、明細、基本資料、設定都算)多一欄 created_at timestamptz not null default now(),不由任何一句 SQL 管。不加最後修改時間;要知道什麼時候改的、誰改的,查操作紀錄。(Jesse 選「只加建立時間,每張表都加」)

白話與例子
出題前查到的:原型沒有任何畫面顯示建立時間或最後修改時間;操作紀錄定了「會存的都記」,每一筆有時間、操作者、哪一筆、內容,所以這兩欄沒有畫面要用,差別只在直接用 SQL 看資料表的時候。
經過:① Claude 第一次推薦不加,理由是時間只有一個來源、不會「資料表寫 13:05、操作紀錄寫 13:06」。② Jesse 問:「加這個成本應該很低吧?」Claude 答對,並更正自己:timestamptz 一欄 8 bytes、不用索引、跟著同一列寫;PostgreSQL 的 now() 是交易開始的時間,存單與寫操作紀錄在同一筆交易,兩邊的時間會一樣,「對不起來」不成立。Claude 改推薦加(單頭與基本資料加兩欄、明細不加)。③ Jesse 選「只加建立時間,修改時間不加」;Claude 再問範圍,他選每一張表都加。
理由
(選項上寫的)靠預設值,沒有 SQL 要管、不可能寫錯;規則只有一句「每張表都有」,可以寫一個測試自動檢查;載入示範資料、升級腳本補的列也有;明細的建立時間看得出哪幾列是後來才加的(第 14 題逐列比對、id 不變)。
代價
每列多 8 bytes(一百萬列多 8 MB);直接看表不知道最後什麼時候改的,要查操作紀錄;操作紀錄以後如果清舊的,修改的時間跟著沒了。
沒選的
  • 不加:直接看表查不到,不經過操作紀錄進來的列完全沒有時間。
  • 兩欄都加、修改時間每一句更新自己寫:漏寫一句就是舊的,要靠測試擋。
  • 兩欄都加、修改時間用觸發程序:每張表掛一個觸發程序,是 SQL 檔上看不到的邏輯。
  • 只加在單頭與基本資料、明細不加:要多一條規則講哪些表不用加。
驗證
沒建過表、沒跑過。「每張表都有」的測試怎麼寫沒定。
出處
data-model.md 第 18 題
還沒裁、選完之後還開著的:
  • 回收桶復原時這一欄照原本的值寫回去還是變成復原的時間,沒談(Claude 的想法:照原本的,跟 id 一樣)。

9. 後端第 1 到 16 題

第 1、2 題 2026-11-17 定,第 3 到 16 題 2026-11-19 定。來源檔寫「第 3 到 6 題的 C# 都沒編譯過」(README.md)。

後端第 1 題C#/.NET 2026-11-17

選的:C#/.NET。(Claude 推薦,Jesse「照推薦,C#/.NET 我很熟悉,review 起來比較快」)

白話與例子
前面的決定對語言的要求:一份定義要產生給畫面用的 API 和給 AI 讀的動作說明;算錢不能有誤差;動作會有幾百個,改一個欄位要有東西告訴我們哪裡跟著壞了;接 PostgreSQL;本機 Windows 跑得起來、雲端能開很多份;Jesse 要看得懂。
理由
  • 算錢是進銷存的本體,decimal 是語言內建的。
  • 一份 C# 型別加上說明文字,同時是 API 的格式和 AI 讀的動作說明,產生的功能都是內建的。
  • 編譯時檢查型別,幾百個動作改欄位會直接報錯;程式是 Opus 寫的,編譯過不了當場知道。
  • Jesse 很熟 C#/.NET,檢查起來比較快(他自己說的)。
代價
前端如果是 TypeScript,型別要從 API 文件再產生一份;AI 相關的新工具通常先出 Python 與 TypeScript 版(一般經驗)。
沒選的
  • TypeScript/Node.js:沒有內建的十進位數字,算錢要靠紀律;型別只在編譯時檢查。Claude 講了這個選項也說得通。
  • Python:型別檢查是選配,執行比較慢(一般經驗)。
  • Go:沒有內建的十進位型別,寫大量商業規則比較囉嗦。
  • Java 或 Kotlin:整套比較重。
  • PHP 或 Ruby 的全包式框架:型別最弱,AI 的動作說明要另外手寫。
驗證
decimal、JsonSchemaExporter、OpenAPI、.NET 版本是 2026-11-17 查微軟文件;Python、Go、Java、PHP、Ruby 的特性是 Claude 的印象,沒有逐一查證。
出處
backend.md 第 1 題

後端第 2 題資料存取:全部手寫 SQL+Dapper 2026-11-17

選的:後端讀寫 PostgreSQL 一律手寫 SQL,Dapper 只負責把結果裝進 C# 型別。不用 EF Core。Jesse 的原話就是選項名稱:「全部手寫 SQL+Dapper」。(Claude 一開始推薦混用,討論後改口推薦這一項)

白話與例子
經過:Claude 第一次問時推薦混用(存單用 EF Core、報表手寫)。Jesse 取消選項,說「這題先停下來,我跟你討論一些事情」,問了四件事:「每一個店家的每一種單,單號都是各自累加的,這件事你打算怎麼做?」「EF Core 能處理這種狀況嗎?」「跟完全手寫 SQL 比有什麼好處?」以及「況且效能優化也是個問題。使用 EF Core 效能優化的能力就變差了。」Claude 重新衡量後改推薦這一項,他照選。單號的做法(Claude 的做法):一張計數表 (company_id, doc_type, doc_date) → last_no,存單的同一筆交易裡用 insert ... on conflict (...) do update set last_no = doc_counter.last_no + 1 returning last_no 取號,單據表另加(公司+單號)的唯一限制當保險。
理由
  • 最重:Jesse 審得到。程式是 AI 寫的、出事查的是他,每一句 SQL 都在程式裡。
  • 最重:場景 ③ 的瓶頸在資料庫,慢的那一句直接改,不用隔著 LINQ 猜。
  • 取號、已交量、沖帳、二十幾張報表、大量寫入,不管選哪個都是手寫;EF Core 實際只管得到一般存單與基本資料。
  • 程式只有一種寫法;公司編號在主鍵最前面的複合主鍵就是普通的 SQL。
  • EF Core 佔優的幾項都找得到補法,它的代價(隔一層看、隔一層調)沒有東西補得回來。
代價
  • 列層級安全性變成唯一一道自動的鎖。
  • 靠測試取代編譯器,從第一天就要有。
  • 幾十種基本資料要審的 SQL 量比 EF Core 多。
  • C# 類別與資料表是兩份,要到測試才發現對不上。
  • 樂觀鎖的版本欄位每一句更新都要記得帶。
沒選的
  • 混用(Claude 第一次的推薦):手寫的 SQL 不會自動帶公司編號的條件;EF Core 實際送出的 SQL 不在程式裡;程式裡有兩種寫法。
  • 全部 EF Core:二十幾張跨單據的報表用 LINQ,產生的 SQL 難預料、慢了難調。
  • 直接用 ADO.NET:手寫 SQL 的代價全部都有,還要自己寫把每一欄裝進物件的程式。Claude 不建議。
驗證
沒跑過:用 PREPARE 補編譯器的做法。Dapper 的 DateOnly:2026-11-18 查發行紀錄,2.1.86 重新開啟、所以用 2.1.86 以上;實際用 Dapper+Npgsql 讀寫 date 欄位還沒跑過。
出處
backend.md 第 2 題
還沒裁、選完之後還開著的:
  • 還沒裁 跟著這一題要定的五條規矩(每一句 SQL 都要有測試對著 PostgreSQL 跑過;用 PREPARE 補編譯器;SQL 集中放;共用的小工具審一次;資料表升級的工具),Claude 提的,Jesse 選的時候看過、沒有逐條裁。其中「SQL 放哪」後來是第 6 題、「升級工具」後來是第 12 題。
  • 測試怎麼組織;單號一天超過 9999 張怎麼辦(決策檔沒寫,要當成一題問)。

後端第 3 題.NET 10 2026-11-19

選的:.NET 10。(Claude 推薦,Jesse 選推薦的)

白話與例子
查到的(2026-11-19,微軟支援頁):.NET 10 是 LTS,2025-11-11 發行,最新修補版 10.0.15,支援到 2028-11-14;.NET 11 是 STS,2026-11-10 發行,也支援到 2028-11-14。Jesse 的 PC 是 SDK 9.0.316,.NET 9 已經不在支援清單上,要裝新的 SDK;容器的基礎映像換成 mcr.microsoft.com/dotnet/aspnet:10.0。
理由
出了一年、第三方套件都跟上了;寫程式的 Opus 與檢查的 Fable 知識截止在 2026 年 6 月,那時 .NET 11 還在預覽版,對 10 最熟、不容易寫出不存在的 API;之後從 10 直接升 12 是 LTS 對 LTS 的路。
代價
用不到 .NET 11 的新功能;升 12 時一次跨兩版。
沒選的
  • .NET 11:才出 9 天;Npgsql、Dapper 的支援狀況沒查;Opus 與 Fable 對正式版的細節沒把握。
  • 先 10、等 .NET 11 穩了再換:多一次升級的工;如果反正要等 .NET 12,這一次等於白做。
驗證
查官方支援頁;沒查 Npgsql、Dapper 對 .NET 11 的支援。下一個 LTS 是 .NET 12、照節奏是 2027 年 11 月,日期是推的。
出處
backend.md 第 3 題

後端第 4 題API 的端點:全部照動作、一律 POST 2026-11-19

選的:一個動作一個端點,讀取也是 POST,參數全部放在 body 的 JSON。動作的名字就是網址,一個 C# 請求型別同時是 API 的格式與給 AI 的動作說明。(Claude 推薦,Jesse 選推薦的)

來源檔的例子(網址與名稱的寫法 sales-order、sales_order_close 是例子,還沒定)

POST /api/sales-order/close
{ "id": 7, "version": 3 }
→ 200 { "version": 4 }

POST /api/sales-order/list
{ "from": "2026-11-01", "to": "2026-11-30", "status": "open", "customerId": 12, "page": 1 }
→ 200 { "rows": [ … ], "total": 37 }

# 給 AI 的動作說明,從同一個 C# 型別產生
name: sales_order_close
description: 把訂單結案
parameters: { id: integer, version: integer }
白話與例子
問的時候用的例子:訂單的查清單、讀一張、新增、修改、刪除、復原、結案、取消結案八件事,照資源排時復原、結案、取消結案套不進 GET/POST/PUT/DELETE,要自己加。
理由
全站一條規則(動作的名字 → 網址、請求型別 → body、回應型別 → 結果);結案、復原、退票、完成盤點、轉單跟存檔是同一種寫法;刪除要帶版本這類事不用想放標頭還是問號後面;給 AI 的說明不用多一層把參數攤平。
代價
跟教科書的 Web API 不一樣,審的時候看到的全是 POST;讀取不能把網址貼到瀏覽器直接測,要用工具送 JSON;以後開放給別人串接,對方會覺得不像一般的 REST。
沒選的
  • 照資源排(REST):參數分散在網址、問號後面、標頭、body;套不進四個動詞的操作要自己加;給 AI 的說明要多寫一層攤平。
  • 讀取用 GET、寫入照動作:全站兩種寫法;清單的條件要寫成問號後面的參數;AI 的動作說明有兩種來源。
  • 只有一個端點(POST /api/action):ASP.NET Core 的 OpenAPI 文件、權限、驗證、紀錄都是照端點掛的,全部要自己照動作名稱分。
驗證
查微軟官方文件(AIFunctionFactory 從 [Description] 推導 JSON Schema、內建 OpenAPI),沒有實際跑過。
出處
backend.md 第 4 題
還沒裁、選完之後還開著的:
  • 網址與動作名稱的命名。還沒裁 前端的靜態檔、給 AI 對話用的串流連線、檔案下載不是「動作」,不照這條(Claude 的想法,沒問)。

後端第 5 題一個動作一個類別+統一的執行器 2026-11-19

選的:每個動作是一個小類別,只寫它自己那一步。確認身分、檢查權限、開交易並設公司編號、寫操作紀錄、提交,由一個執行器統一包;HTTP 與 AI 助理都只經過這個執行器。啟動時掃描每個模組的動作,自動掛成端點(Minimal API)與給 AI 的動作說明。(Claude 推薦,Jesse 選推薦的)

來源檔的 C#(示意:名稱沒定、沒有編譯過)

// 示意:名稱沒定、沒有編譯過
// Core 專案(進銷存本體):一個動作一個檔
public sealed record CloseSalesOrderRequest(long Id, int Version);
public sealed record CloseSalesOrderResponse(int Version);

[Action("sales-order/close", "把訂單結案", Permission.SalesOrderEdit)]
public sealed class CloseSalesOrder
    : IAction<CloseSalesOrderRequest, CloseSalesOrderResponse>
{
    // 進來的時候,ctx 裡的連線已經開好交易、設好公司編號
    public async Task<CloseSalesOrderResponse> RunAsync(
        CloseSalesOrderRequest req, ActionContext ctx, CancellationToken ct)
    {
        var version = await ctx.Connection.QuerySingleOrDefaultAsync<int?>(
            new CommandDefinition(SalesOrderSql.Close,
                new { ctx.CompanyId, req.Id, req.Version },
                ctx.Transaction, cancellationToken: ct));

        if (version is null) throw new StaleVersionException();   // 影響 0 列
        ctx.Log("訂單結案", req.Id);                              // 操作紀錄
        return new(version.Value);
    }
}

// Shared:執行器,HTTP 與 AI 都只走這裡
//   確認身分 → 檢查權限 → 開交易設公司 → RunAsync → 寫操作紀錄 → 提交
public sealed class ActionRunner { /* … */ }

// Host:啟動時掃描每個模組,一個動作掛一個端點
foreach (var a in ActionCatalog.Scan(moduleAssemblies))
    app.MapPost("/api/" + a.Name,
            (HttpContext http, ActionRunner runner) => runner.RunHttpAsync(a, http))
       .Accepts(a.RequestType, "application/json")
       .Produces(200, a.ResponseType);
白話與例子
問的時候用的例子是訂單結案從按鈕到資料庫的八步,見上面第 4 節。2026-11-19 AI 第 2 題改了這一題的一個前提:AI 叫動作時瀏覽器打跟按鈕一樣的端點,不再「同一支程式裡直接呼叫」;執行器不用改,入口只剩 HTTP 一個,原本例子裡「AI 不經過讀 JSON 與回 JSON」那段已經不成立。同一天 AI 第 3 題又在 [Action] 上多了一個必寫的值(AI 叫的時候怎麼做),沒寫啟動時擋下來。
理由
共同的步驟只有一份,新動作不可能漏掉權限或交易;加一個動作就是加一個檔,畫面與 AI 自動都叫得到;一次審一個檔、一件事;多個 Opus 同時寫不會改到同一個檔。
代價
類別會有幾百個;端點是掃描出來的,從 Host 看不到一行一行的清單,要靠 OpenAPI 文件或一個測試列出來;用不到 Minimal API 內建的參數繫結與驗證,讀 JSON 與驗證要在執行器自己做。
沒選的
  • 一種單據一個類別、一個方法一個動作:動作多的類別會上千行;多個 Opus 同時寫同一種單據會改到同一個檔;簽章寫錯要到啟動時才知道。
  • Controller+過濾器:每個動作兩層,Controller 那層只是轉手;當時的理由還包括 AI 直接呼叫服務時過濾器不會跑。
  • 手寫登記:忘了包共同步驟或忘了檢查權限沒有東西擋;同一個動作登記兩次,幾百個會漏、會對不上。
驗證
沒編譯過:上面的 C#;Accepts(Type, string)、Produces(int, Type) 這兩個非泛型的寫法是 Claude 記得的,沒查原文;掃描出來的端點在內建的 OpenAPI 文件裡長得對不對沒試;啟動時用反射掃描幾百個動作要多久沒量。查到的:微軟「For new projects, we recommend using Minimal APIs」;.NET 10 的 AddValidation 只找同一個 assembly 裡的型別,所以不靠它。
出處
backend.md 第 5 題,含同題最後「2026-11-19 AI 助理第 2 題改了這一題的一個前提」
還沒裁、選完之後還開著的:
  • 還沒裁 模組公開的東西分「動作」與「給別的模組在同一筆交易裡呼叫的方法」兩種;一個動作要做另一個動作的事時呼叫模組裡共用的程式、不再跑一次執行器;沒標權限項目的動作啟動時就擋下來(Claude 順著講的)。
  • 動作的類別、請求與回應型別、SQL 各放在專案的哪個資料夾;查詢類的動作的唯讀交易寫法。(操作紀錄的白話內容由誰產生,同一天在第 16 題定了。)

後端第 6 題SQL 放在哪裡:照單據集中 2026-11-19

選的:一種單據(或一種基本資料)一個 C# 檔,每一句 SQL 是一個有名字、有一行說明的常數;動作用名字引用。好幾種單據共用的 SQL(庫存異動、取號、成本)另外各一個類別。(Claude 推薦,Jesse 選推薦的)

來源檔的 C#(示意:沒有編譯、SQL 沒有跑過)

// 示意:沒有編譯、SQL 沒有跑過
// Core/Sql/SalesOrderSql.cs:訂單的 SQL 都在這個檔
internal static class SalesOrderSql
{
    /// 結案:版本對得上才改,回傳新的版本。影響 0 列=被改過或被刪了
    public const string Close = """
        update sales_order
           set closed_at = now(), version = version + 1
         where company_id = @CompanyId and id = @Id and version = @Version
        returning version
        """;
}

// Core/SalesOrder/CloseSalesOrder.cs:動作用名字引用
var version = await ctx.Connection.QuerySingleOrDefaultAsync<int?>(
    new CommandDefinition(SalesOrderSql.Close,
        new { ctx.CompanyId, req.Id, req.Version },
        ctx.Transaction, cancellationToken: ct));
白話與例子
訂單加一個欄位「交貨時段」,存檔、讀一張、查清單三句都要改,分屬三個動作。照單據集中是改 1 個檔、三句上下排著。
理由
手寫 SQL 最怕改了資料表、漏改某一句;碰同一張表的 SQL 在同一個檔,改欄位時一眼掃完;從資料庫的角度看「這張表被怎麼讀寫」只要開一個檔;名字打錯編譯不過;PREPARE 的測試用反射找出每個 *Sql 類別的每個常數。
代價
看一個動作要跳到另一個檔才看得到它的 SQL;多個 Opus 同時寫同一種單據會改到同一個 SQL 檔;C# 字串裡的 SQL 編輯器不一定有語法上色。
沒選的
  • 一句一個 .sql 檔:名字打錯要到啟動或測試才知道;改欄位要一個一個檔打開。
  • 跟動作放一起:同一張表的 SQL 散在十幾個檔,改欄位時漏一句編譯器不會講。
  • 資料庫的函式:改一句 SQL 就是一份升級腳本,程式與資料庫要一起上線、一起退版。
驗證
沒驗證:PREPARE 補編譯器的做法還是沒有實際跑過;Dapper 的 @CompanyId 要換成 PREPARE 認得的 $1 才能測,怎麼換沒談。
出處
backend.md 第 6 題
還沒裁、選完之後還開著的:
  • 報表的 SQL 怎麼分檔(一張報表一個檔是 Claude 的想法,沒問);一句 SQL 被兩種單據用到時放哪一邊。

後端第 7 題登入誰做:整個導到 Amazon Cognito 的登入頁 2026-11-19

選的:登入、註冊、忘記密碼都在 Cognito 的 managed login 頁面做(OpenID Connect,authorization code flow)。Cognito 確認是這個人之後把瀏覽器導回來,我們的後端拿到這個人的代碼(sub)與 e-mail,在自己的資料庫找到這個人、建立自己的登入紀錄。LiteERP 的程式與資料庫不經手、不保存密碼。(Claude 推薦,Jesse 選推薦的)

白話與例子
經過:同一天先選過「自己做」(帳號、密碼、驗證碼、登入紀錄都在自己的資料庫),選完大約十分鐘後 Jesse 撤回:「這個決定我撤回, 重新討論. 自己做的話我們就要保障使用者的帳密, 不如丟給外包商, 反正人數少的時候免費?」中間還有一輪 Claude 把「LiteERP 這邊完全把密碼移除」問成「使用者有沒有密碼」,那一輪的前提不對、結論不算數。Jesse 講清楚的要求:「我以為是把整個登入過程導入到認證商, 認證商確認是這個人無誤後給我們這個人的代碼」「prototype 中登入與註冊的畫面可以打掉重來. 然後我的要求不是使用者有沒有密碼, 而是 LiteERP 不需要知道使用者的密碼」。
理由
  • 合 Jesse 的要求(LiteERP 不需要知道使用者的密碼;整個登入過程導到認證商)。
  • 跟其他東西同在 AWS,一家廠商、一張帳單,資料在台北。
  • 登入頁現成有繁體中文(lang=zh-TW)。
  • 每月活躍 1 萬人內免費、之後每人 0.015 美元,算得出來。
  • 之後可以在它底下加 Google、LINE 登入。
  • 我們這一邊只要確認它回來的結果,用的是 ASP.NET Core 內建的 OpenID Connect 處理(這一句是 Claude 的說法,沒有另外查原文)。
代價
  • 登入、註冊、忘記密碼是 Cognito 的頁面,上面的字是它翻好的繁體中文、一個字都不能改;外觀只能換標誌、背景、顏色。原型那幾頁打掉重來(Jesse 同意)。
  • 註冊時使用者一定要設密碼,密碼存在 Cognito。
  • 沒有現成的「我的帳號」自助頁,換 e-mail、管理通行金鑰要我們呼叫它的 API 或導到它的頁面。
  • 登入頁的網址預設在 amazoncognito.com 底下;換成自己的網域不另外收費,但台北能不能換官方沒明寫。
  • 本機測試要連網,每個部署場景各要一個 user pool;帳號綁區域,搬到別區密碼搬不走。
沒選的
  • Auth0:超過 2.5 萬人之後照級距跳;多一家廠商;資料最近在日本。
  • Microsoft Entra External ID:語言清單沒有台灣的繁體中文;要另開 Azure 帳號;通行金鑰限制多;超過 5 萬人的單價沒查清楚。
  • 只用 Google、LINE 登入:沒有這兩種帳號的人進不來;LINE 要另外申請才拿得到 e-mail;之後可以掛在 Cognito 底下當成多一個選擇。
  • 自己架 Keycloak:密碼雜湊在我們自己的機器上,不合要求。
  • 自己做(撤回之前選的)、用我們自己的畫面去呼叫 Cognito:都被 Jesse 講清楚的要求排除了。
驗證
沒驗證:全部是讀文件,沒有實際開一個 user pool 試過。各家的事實是 2026-11-19 三個 Sonnet 助手查官方頁面,Claude 沒有逐頁重開。
出處
backend.md 第 7 題「定案(2026-11-19)」;業務規則那一面在 docs\decisions\account.md「2026-11-19 LiteERP 不需要知道使用者的密碼」
還沒裁、選完之後還開著的:
  • account.md 那 21 題有 6 項要對 Cognito 重新裁,都還沒問(Claude 的想法是等做到帳號模組再一題一題問):擋外洩過的密碼(要 Plus 等級,每人 0.020 美元、沒有免費額度)做不做;新裝置登入收 e-mail 驗證碼、同一台 30 天不再問;備用 e-mail 或手機收驗證碼;改密碼後其他裝置自動登出;變更密碼;user pool 開在哪一區(台北,或 Jesse 提過的北美)、登入頁用不用自己的網域(要在建立 user pool 之前定)。

後端第 8 題登入狀態怎麼記:登入紀錄表+Cookie 2026-11-19

選的:做法一,登入紀錄表+Cookie。伺服器一張表、一台裝置一列,瀏覽器只拿一串亂碼,放在 HttpOnly 的 Cookie。(Claude 推薦,Jesse 選推薦的;第一次問時 Jesse 說「我其實聽不太懂. 你可以把這四種作法寫成詳細的 html 讓我看嗎?」,做了說明頁,看完重問才選)

來源檔的 SQL(問的當下沒跑;同一天下午在 PostgreSQL 17.12 跑過。m.role_id 只是示意,成員與權限的表還沒設計;「順延 30 天」那句是 Claude 的想法,沒定)

create table login_session (                 -- 不分公司,跟著人
  id           bigint generated by default as identity primary key,
  user_id      bigint      not null references app_user (id),
  token_hash   bytea       not null unique,  -- 只存雜湊;亂碼本身只在瀏覽器
  device_name  text        not null,
  created_at   timestamptz not null,
  last_seen_at timestamptz not null,
  expires_at   timestamptz not null          -- 最後一次使用 + 30 天
);

-- 認人與查成員資料併成一句(每個請求查一次)
select s.id, s.user_id, m.role_id
  from login_session s
  join company_member m
    on m.user_id = s.user_id and m.company_id = @CompanyId
 where s.token_hash = @TokenHash
   and s.expires_at > now();

-- 順延 30 天:超過一天沒更新才寫(Claude 的想法,沒定)
update login_session
   set last_seen_at = now(), expires_at = now() + interval '30 days'
 where id = @Id and last_seen_at < now() - interval '1 day';

-- 登出其他裝置
delete from login_session where user_id = @UserId and id <> @CurrentId;
白話與例子
Jesse 看完說明頁之後又問了三件事才說再問一次。「交給 Cognito 後,Cognito 未必會回傳該使用者的 email 給我們對吧?…」答:回不回傳是我們設定的,scope=openid+email 的 ID token 有 sub、email、email_verified;認人用 sub,我們的帳號表兩個都存。「瀏覽器好像可以設定成一律不吃 cookie?」答:可以,但四種做法都會登不進來,Cognito 自己的登入頁也要 Cookie,所以不影響怎麼選。「因為我們的 server 是 stateless 的, 無論如何要驗證這個請求是誰發的最後還是需要去查資料庫?」答:對;權限四種都要查(離職立刻生效),認人與查成員資料併成同一句,所以做法一每個請求查一次,跟 JWT 一樣多。
理由
「登入中的裝置」「登出其他裝置」就是這張表的查與刪,下一次按就生效;亂碼在程式讀不到的 Cookie 裡,偷不走;程式開很多份時大家讀同一個資料庫;以後做手機 App 用同一張表、把亂碼放標頭送。
代價
要另外防別的網站冒用 Cookie;這張表不分公司、沒有列層級安全性,SQL 要審嚴;本機測試機沒有 HTTPS 時 Cookie 的設定要另外處理。
沒選的
  • JWT:登出其他裝置有空窗、權限每次還是要查、通行證與換發憑證會被惡意程式偷走、多一套換發流程。
  • 登入紀錄表+標頭:亂碼存在程式讀得到的地方。
  • 加密的 Cookie(伺服器不存登入紀錄):伺服器不知道有哪幾台,裝置清單要另外加表,加了就是這一個做法。
驗證
實測過 2026-11-19 下午,PostgreSQL 17.12:認人與查成員併成一句,是公司 7 的成員回 1 列;不是公司 8 的成員、亂碼不對、登入紀錄過期都回 0 列;順延那一句第一次改 1 列、馬上再跑改 0 列;登出其他裝置刪 2 列;執行計畫是 Index Scan using login_session_token_hash_key 接 Index Scan using company_member_pkey。資料只有三列,沒有量時間。
出處
backend.md 第 8 題、data-model.md 檔尾「2026-11-19 補跑」第 5 項;說明頁 docs\explains\login-session.html
還沒裁、選完之後還開著的:
  • 還沒裁 防別的網站冒用打算疊三層(SameSite、只收 JSON、要求一個自訂的標頭),Claude 的想法。
  • 裝置名稱怎麼來;過期的列多久清;自己寫還是用 ASP.NET Core 的 Cookie 驗證加 SessionStore;登出時要不要連 Cognito 那邊一起登出;微軟建議「關掉瀏覽器還保持登入」要使用者同意,跟 account.md 第 11 題(一律保持 30 天)不同,要不要回頭看,還沒問 Jesse。

後端第 9 題「現在是哪一家公司」:每個請求自己帶 2026-11-19

選的:登入紀錄不記公司。每個請求帶著公司編號(例如放在網址 /api/c/7/sales-order/close,放哪裡是例子、還沒定),伺服器每次用同一句 SQL 確認這個人是不是那家公司的成員。換公司就是前端換一個編號,伺服器什麼都不用改。(Claude 推薦,Jesse 選推薦的)
同一天補裁:公司編號放網址(Claude 推薦,Jesse「照推薦」):POST /api/c/7/sales-order/close,body 照舊只有動作自己的參數。沒有公司的動作(列出我能進的公司、建立新公司)網址沒有 c/7 那一段,兩種動作從網址就分得開。

白話與例子
美玉姐在公司 7 是店員、在公司 9 是老闆,同一個瀏覽器開兩個分頁。分頁甲在公司 7 打訂單打到一半,分頁乙換到公司 9,再回分頁甲按儲存。記在登入紀錄上的話,伺服器會以為是公司 9;每個請求自己帶的話照樣存進公司 7。確認成員的那一句跟第 8 題的認人併成同一句(見上一張卡),查不到列=沒登入,或不是這家公司的成員,一起擋。
理由
兩個分頁可以各開一家公司、互不影響;伺服器不用多記一個會變的狀態;網址本身就說明是哪一家;查詢次數跟另一種做法一樣(都要查成員資料)。補裁放網址的理由:伺服器的存取紀錄每一行都看得出是哪一家;動作的名稱與請求型別不受影響,給 AI 的動作說明裡不會出現公司編號。
代價
前端每個請求都要帶公司編號,漏帶就錯;網址上看得到公司編號這個數字;「上次用的是哪一家」要另外記,記在哪還沒定。
沒選的
  • 記在登入紀錄上(多一欄現在的公司):一個瀏覽器同一時間只能在一家;別的分頁不知道換了公司。
  • (補裁沒選的)放標頭 X-Company-Id: 7:存取紀錄預設不記自訂標頭、前端漏帶時網址看起來是對的。
  • (補裁沒選的)放 body 的 JSON:幾百個請求型別各多一個 CompanyId,給 AI 的說明裡也會出現、AI 可能自己填。
  • 一家公司一個子網域:要萬用字元的 DNS 與憑證、Cognito 導回來的網址要另外處理、本機測試機沒有網域、公司要多取一個網址用的名稱。
驗證
來源檔 2026-11-19 補記:SQL 標「沒有跑過」是問的當下。同一天下午補跑了「認人與查成員併成一句」(data-model.md 檔尾「2026-11-19 補跑」第 5 項:是成員回 1 列;不是成員、亂碼不對、登入紀錄過期都回 0 列);腳本沒留,跑的是不是這一句的原樣不確定。
出處
backend.md 第 9 題
還沒裁、選完之後還開著的:
  • 還沒裁 使用者亂改請求裡的公司編號時,查成員資料那一句查不到列就擋;執行器把請求帶的公司編號設進交易(Claude 順著講的,沒另外問)。
  • 選公司之前的動作(列出我能進的公司、建立新公司)沒有公司編號,執行器要分兩種動作;啟動時掃描出來的端點怎麼分成有公司、沒公司兩種路由,沒寫過(c/7 這個寫法是例子);「上次用的是哪一家」記在哪。

後端第 10 題動作做不成時:狀態碼分大類+統一的 JSON 2026-11-19

選的:用 HTTP 狀態碼分大類,內容是全站同一種 JSON(Problem Details,RFC 9457 的格式):固定的代號、一句說明,需要時多帶資料。沒登入、不是成員、沒權限、程式出錯由執行器統一回;動作裡只要丟出「是哪一種」。(Claude 推薦,Jesse 選推薦的)
來源檔的粗體句最後還有一句「AI 助理在同一支程式裡呼叫動作時拿到的是同一份內容」。來源檔 2026-11-19 補記:「粗體最後一句是 AI 助理第 2 題之前的前提。現在 AI 跟按鈕一樣走 HTTP,拿到的就是同一個回應。」

來源檔的例子(示意:代號、欄位名稱、哪一種配哪個狀態碼都還沒定)

# 示意:代號、欄位名稱、哪一種配哪個狀態碼都還沒定
HTTP/1.1 409 Conflict
Content-Type: application/problem+json
{
  "type":   "amount_mismatch",
  "title":  "金額跟系統算的不一樣",
  "detail": "總計從 315 改成 314,請確認後再存一次",
  "status": 409,
  "server": { "net": "299", "tax": "15", "total": "314" }
}

沒登入 401|不是成員、沒權限 403|跟現況衝突(版本對不上、金額不一樣)409|不合規則 422|程式出錯 500
白話與例子
已經定的、會做不成的情況:沒登入或 30 天到了回登入頁;被改成已離職寫「你已經不能使用 ○○」帶回選公司;沒權限;不合規則(例如出過貨的訂單不能刪);版本對不上;金額不一樣要把後端的數字帶回去(前端第 3 題);試用到期整家鎖住。
理由
失敗在伺服器紀錄與監控上看得出來;共通的幾種由執行器統一處理;格式是業界標準、ASP.NET Core 內建(AddProblemDetails);AI 讀代號就知道怎麼跟使用者講。
代價
前端要看兩層(狀態碼與代號);哪一種情況配哪個狀態碼要訂一張表、全站照著走。
沒選的
  • 一律回 200、成敗寫在 ok 欄位:紀錄與監控看到的全部是成功;程式真的掛掉時還是 500。
  • 每個動作自己定義所有可能的結果:幾百個動作各寫一次「版本不對」「規則不符」;沒登入、沒權限、程式出錯還是要另外一套。
驗證
查 ASP.NET Core 文件(含 Minimal API 遇到 JSON 格式不對時正式環境預設直接回 400 這個坑);上面的例子是 示意。
出處
backend.md 第 10 題
還沒裁、選完之後還開著的:
  • 還沒裁 說明的那一句中文由後端產生(原型裡這些句子寫在前端,搬的時候要搬到後端);程式出錯時只回一個可以對紀錄的編號(Claude 順著講的)。
  • 代號的清單與命名;狀態碼對照表;一次有好幾條規則不符時回一條還是全部;錯誤的那一句要不要分「給使用者看的」與「給 AI 看的」。

後端第 11 題明細怎麼從 C# 傳進 SQL:一包 JSON 2026-11-19

選的:明細清單轉成一包 JSON 當一個參數,SQL 用 jsonb_to_recordset(@Lines::jsonb) as x(欄位 型別, …) 攤成一列一列。data-model.md 第 14 題的刪、改、新增三句都這樣接;17 種有明細的單同一種寫法。(Claude 推薦,Jesse 選推薦的)

來源檔的 C#(示意,沒有編譯過;SQL 這一邊 2026-11-19 實測過。SQL 見資料模型第 14 題)

// 示意,沒有編譯過;SQL 這一邊 2026-11-19 實測過
var lines = JsonSerializer.Serialize(order.Lines, SnakeCaseJson.Options);
await ctx.Connection.ExecuteAsync(new CommandDefinition(
    SalesOrderSql.UpdateLines,
    new { ctx.CompanyId, order.Id, Lines = lines },
    ctx.Transaction, cancellationToken: ct));
理由
只有一個參數,照名稱對,不會放反;JSON 是從 C# 的類別自動轉的,名稱不是手打的;回收桶本來就用同一批 JSON 的函式;出事時把那一包印出來就看得到送了什麼;幾百列也是一句送完。
代價
可以空的欄位名稱對不上時不會報錯、悄悄變成空的,每一句都要有測試確認每個欄位真的寫進去了;欄位名稱與型別在三句 SQL 裡各要寫一份。
沒選的
  • 每一欄一個陣列(unnest(@Ids, @LineNos, …)):同型別的陣列放反悄悄存錯(實測:數量與單價放反不報錯);C# 每一句要手排七八個陣列。
  • 一列一句:幾百列的盤點單每存一次要送幾百句(沒量過);新增的列要一句一句拿回 id。
  • 自訂的列型別:17 種明細各要一個型別、明細表加欄位時要跟著改;沒有實測。
驗證
SQL 這一邊 實測過 2026-11-19,PostgreSQL 17.12:欄位定義直接寫 domain 可以;數字用字串可以;單價多一位小數被 domain 擋;不能空的欄位少了鍵會報 not-null;可以空的欄位鍵名打錯悄悄存成空的。沒跑過:從 C# 經過 Dapper+Npgsql 把這個參數送進去;C# 的 decimal 轉成 JSON 是數字還是字串沒定;SnakeCaseJson.Options 是示意的名字。
出處
backend.md 第 11 題、data-model.md 檔尾「2026-11-19 補跑」第 1、2 項
還沒裁、選完之後還開著的:
  • x(欄位 型別, …) 那一段三句各寫一份,要不要有辦法只寫一次;「每個欄位真的寫進去了」的測試怎麼寫才不會漏欄位。

後端第 12 題資料表升級的工具:自己寫一小支 2026-11-19

選的:Jesse 2026-11-19「自己寫吧」。升級工具不用現成的,自己寫一小支(大約一百多行 C#),照順序執行手寫的 SQL 腳本。(Jesse 定;Claude 推薦的是 Flyway)

白話與例子
經過:Claude 推薦 Flyway。Jesse 取消視窗,連問三句:「你這種做法我要升級資料庫需要把正在跑的 server 停掉嗎?」(停不停跟選哪個工具無關,看腳本改了什麼);「用別人寫的跟自己寫的差別在哪?」(Claude 補了一點:用 Flyway 的話升級那一步是另一個映像檔,跟「三個部署場景都跑同一個映像檔」不合;Claude 說了仍略偏 Flyway、但他選自己寫不會勸);「Flyway opensource 嗎?」(開源的是 GitHub flyway/flyway,Apache License 2.0;Redgate 另有自己的版本)。
這一小支要做到的(Claude 列的,實作時照這張單):① 一張記錄表記得跑過哪幾支;② 先拿 pg_advisory_lock 再查記錄表,同時只讓一個在跑;③ 一支腳本一筆交易,失敗整支退回,可以個別標成「不包交易」;④ 比對檢查碼發現跑過的腳本被改,算之前先把換行統一;⑤ 做成我們那支程式的一個指令(例如 migrate),用建表與升級的角色連線,跟程式是同一個映像檔;⑥ 測試裡可以直接呼叫它來建一個空的資料庫。
理由
來源檔寫「Jesse 定」,他沒另外說理由。
沒選的
  • Flyway(Claude 推薦的):四件事預設都做到、用的人最多。是 Java 的獨立工具,升級那一步多一個映像檔;擁有它的是一家公司,哪些功能留在開源版由它決定。
  • grate:同時升級的鎖沒查到,交易要自己開。
  • DbUp(2026-11-17 原本提的候選):鎖沒有、腳本被改不會發現、失敗預設不退回。
  • Evolve:穩定版停在 2023 年。
驗證
實測過 2026-11-19,PostgreSQL 17.12
  • 鎖:甲拿了 pg_advisory_lock 後 3 秒才結束連線,乙在第 1 秒要同一把鎖,等了 1.98 秒;連線結束自動放。
  • 整支退回:一筆交易裡建表、加欄位、再除以零,結束後那張表不存在。
  • 換行:同一句 SQL 結尾是 \n 與 \r\n 的 SHA-256 不一樣。
  • 邊跑邊升級:加不能空又沒有預設值的欄位,舊程式一新增就報 not-null;改欄位名稱舊程式報 column "doc_no" does not exist;改表要獨占那張表,加欄位前先 set lock_timeout = '500ms' 時 0.5 秒後放棄,別人的讀取只等 0.29 秒。
出處
backend.md 第 12 題
還沒裁、選完之後還開著的:
  • 要不要做到不停機、「這一版只加、下一版才刪」要不要當成規矩,Jesse 還沒裁;接在換版流程的哪一步還沒裁(deployment.md「還沒談的」)。還沒裁 Claude 的看法:場景 ① 先停再升級,場景 ② 半夜停幾分鐘也可以,場景 ③ 幾乎一定要邊跑邊升級。

後端第 13 題自動測試:從 HTTP 打進去、接真的 PostgreSQL 2026-11-19

選的:測試把整支後端程式開在測試行程裡,資料庫用拋棄式的 PostgreSQL 容器。每個測試先建一家新公司,再像畫面一樣叫動作,最後用查詢的動作確認結果。另外配兩種小測試:金額運算的題庫(跟前端共用同一份,frontend.md 第 4 題)、把每一句 SQL 都 PREPARE 一次(第 2、6 題講過的規矩)。(Claude 推薦,Jesse「照推薦」)

白話與例子
「存一張銷貨單」之後,庫存要少 10、應收要多 452、成本表要更新、操作紀錄要多一筆,別家公司完全看不到。跟著定的(選項上寫的):登入不經過 Cognito,測試直接在登入紀錄表建一筆(第 8 題)。
理由
規則幾乎都寫在手寫的 SQL 裡,真的把 SQL 跑過才算測過;第 5 題的八個步驟全部經過;每個測試一家公司,靠公司編號天生隔開,可以平行跑。
代價
跑測試要有 Docker;比純 C# 的測試慢(多慢沒量);失敗時只知道哪個動作的結果不對,要自己往下找是哪一句。
沒選的
  • 跳過 HTTP、直接呼叫動作類別:讀 JSON、登入與權限那幾步不會經過,要另外測。
  • 用假的資料庫做單元測試:規則在 SQL 裡,等於沒測到;列層級安全性也測不到。
  • 不寫自動測試、靠審查與手動點:Opus 改了一句 SQL,沒有東西會自動講別的地方壞了。
驗證
沒寫過、沒跑過;一個容器跑完全部測試要多久、平行跑會不會互相卡沒量。查到的(2026-11-19):WebApplicationFactory<TEntryPoint>(Microsoft.AspNetCore.Mvc.Testing)可以把程式開在測試行程裡,Minimal API 的 Program 預設是 internal,官方做法是加 public partial class Program { } 或用 InternalsVisibleTo(微軟文件);Testcontainers for .NET 有 Testcontainers.PostgreSql 模組(Context7 的套件說明,沒有開官網核對版本與授權)。
出處
backend.md 第 13 題
還沒裁、選完之後還開著的:
  • 測試框架(Claude 說打算用 xUnit、請他習慣別的就講,Jesse 沒另外講);測試專案一個還是一個模組一個;測試要對的數字從哪裡來;模組的 internal 要不要開給測試專案看;CI 上怎麼跑。

後端第 14 題請求的 JSON:形狀在讀取時嚴格檢查,業務規則寫在動作裡 2026-11-19

選的:形狀(少欄位、型別不對或是空的、多了不認得的欄位)由執行器讀 JSON 時統一擋,設定只寫一次;請求型別照第 5 題的寫法,動作裡不為形狀寫任何程式。內容合不合規則(數量是負的、未付款卻沒選建檔的客戶)在動作裡用 if 判斷,丟出帶中文說明的錯誤(第 10 題)。(Claude 推薦,Jesse「照推薦」)

白話與例子
存銷貨單的請求沒帶 version、customerId 送了 null、多送一個後端沒有的 discount2,這三種是形狀不對(前端的 bug);數量 -3、未付款卻沒選建檔的客戶是業務規則。這就是一個請求從頭到尾第 1 步「讀 JSON」做的事。
理由
請求型別就是唯一的格式定義,跟第 4 題「同一個型別產生 API 與 AI 的動作說明」一致;動作裡剩下的每一個 if 都是業務,審的時候好看。
代價
  • 這個檢查管不到集合裡的元素,明細陣列裡夾一個 null 要另外擋,執行器補一段共用的檢查。
  • 前端版本跟後端不一致、多送或少送欄位時會直接被擋,換版那幾分鐘會有人存不了。
沒選的
  • 在請求型別上標屬性、執行器統一檢查:規則分兩個地方;內建的檢查會不會一層一層檢查到明細,沒查到明文。
  • 第三方的驗證套件、每個請求一個驗證類別:多一個第三方套件,幾百個動作各多一個類別。
  • 全部在動作裡手寫:每個動作重複寫「不能是空的」,漏一個就是執行到 SQL 才出錯。
驗證
查微軟官方文件(2026-11-19):JsonSerializerOptions.RespectNullableAnnotations、RespectRequiredConstructorParameters、UnmappedMemberHandling = JsonUnmappedMemberHandling.Disallow(.NET 8 起);前者「cannot be used to enforce nullability annotations of root-level types, collection elements, or generic parameters」。沒寫過、沒跑過:這三個設定配上 record 的建構子參數實際擋不擋得到每一種情況沒試;形狀不對時回給前端的訊息長怎樣沒談。
出處
backend.md 第 14 題
還沒裁、選完之後還開著的:
  • 數量、金額這類範圍由動作擋、還是靠資料庫的自訂型別報錯再翻成中文;一次有好幾條規則不符時回一條還是全部。

後端第 15 題權限項目:一份清單放 Shared,功能項目+四種動作 2026-11-19

選的:權限項目是兩段:功能項目(跟「權限設定」頁的列一一對應)與動作種類(讀取、新增、修改、刪除)。清單定義在 Shared,每個後端動作標「哪一項的哪一種」;「只有老闆」與「不用權限」也是明寫的值,不能留空(沒標啟動時擋下來,第 5 題)。(Claude 推薦,Jesse「照推薦」)

來源檔的 C#(示意:名稱沒定、沒編譯)

// 示意:名稱沒定、沒編譯
[Action("sales-order/close", "把訂單結案", Feature.SalesOrder, Act.Edit, Ai = AiUse.Confirm)]
白話與例子
已經定的業務規則:老闆固定全部能用,主管、店員照權限設定頁;粒度只跟著主選單項目走,現在 32 項,每項最多讀取、新增、修改、刪除四格;員工資料與權限設定只有老闆能進。Jesse 2026-11-10 否決過比選單更細的權限。第 5 題例子裡的 Permission.SalesOrderEdit 在這一題變成 Feature.SalesOrder, Act.Edit 兩段。
理由
業務規則已經是「32 項乘四格」,程式長同一個樣子,權限設定頁有幾列、程式裡就有幾項;五個模組的動作都要用同一份清單,操作紀錄模組在最底層、不參考帳號模組,所以只能放 Shared。
代價
Shared 的白名單多開第五類「權限項目的清單」(模組第 6 題),裡面有訂單、銷貨這些業務的詞,只有名字、沒有邏輯。
沒選的
  • 各模組各自定義、執行器只認數字:權限設定頁要的整份清單得在啟動時向各模組收集,數字要另外想辦法不撞號,操作紀錄模組自己那一頁的權限沒有地方對照。
  • 一個動作一個權限、不對應選單:推翻「權限只跟著選單項目走」,權限設定頁從 32 列變成幾百列。
驗證
沒寫過。[Action] 現在有名稱、說明、功能項目、動作種類、AI 值五樣,參數怎麼排沒定。
出處
backend.md 第 15 題
還沒裁、選完之後還開著的:
  • 還沒裁 每個動作算哪一格(結案算修改、轉單看目標那種單的新增)照原型 access.js 現有的做法,做到哪個動作有疑問再問(Claude 講了、Jesse 沒另外裁)。
  • 權限設定存在資料庫的樣子;群組能不能改名、能不能多於三個;一個動作需要兩項權限時怎麼標;行事曆、首頁這種每件事另外跟著別項讀取權的頁怎麼擋。

後端第 16 題操作紀錄的「內容」:後端在存檔的同一筆交易裡產生白話、存成文字 2026-11-19

選的:每一種單據、每一種資料在 C# 有一段「把這一筆寫成白話」的程式,由存檔的動作在同一筆交易裡呼叫:存完再讀一次這一筆(含客戶、商品的名稱),排成字,交給執行器寫進操作紀錄。前端不產生、也不傳操作紀錄的內容。(Claude 推薦,Jesse「照推薦」)

白話與例子
已經定的業務規則:一次變更一列,「內容」是那一筆在操作之後的白話全文(刪除那一列是刪掉當下的樣子),例如「客戶 好鄰居咖啡|2026/09/15|台中倉|蔥油餅乾 12 包 × 40.00=480;可樂 5 罐 × 20.00=100|稅 29|總計 609|備註 週六送」。原型是前端在存檔前後比對、自己寫(oplog.js)。問的時候攤的後端負擔:這個做法每次存檔多讀一次自己剛存的那張單、用 C# 排字、寫一列。
理由
操作紀錄是拿來查「誰改了什麼」的,寫的一定要是真的存進去的樣子;存成文字,客戶之後改名,舊紀錄還是當時的名字。Claude 講了知道 Jesse 偏好後端輕,但這一塊認為該由後端自己寫。
代價
每次存檔多讀一次;39 種左右的東西(19 種單據+資料與設定各頁)各要一段排字的程式,等於把原型 oplog.js 那一份搬到後端。
沒選的
  • 後端存整筆的 JSON、要看的時候才排成白話:現在沒有定案的畫面需要;列印與匯出要全文,排字的程式還是得有一份。
  • 照原型由前端產生、跟著請求送上來:內容由瀏覽器說了算,寫的跟實際存進去的不一樣時沒有東西會發現,Jesse 也審不到那段程式。
  • 資料庫的觸發程序自動記:記到的是一列一列的原始資料,只有編號沒有名稱,湊不成「一次變更一列、整筆的白話」。
驗證
沒寫過;多讀的那一次能不能直接用「讀一張」那個動作的 SQL、多花多少時間沒量。
出處
backend.md 第 16 題
還沒裁、選完之後還開著的:
  • 「沒改內容的存檔不記」在後端怎麼判斷(Claude 的想法:排出來的白話跟這一筆上一列一樣就不記,沒問);連帶修改、自動建立那幾列由誰呼叫;排字的程式放動作旁邊還是一種單據一個檔;操作紀錄表的欄位與索引;AI 助理的標記怎麼進來。

10. 前端第 1 到 4 題

Jesse 2026-11-17 給的兩個條件:前端的程式 Jesse 不審,只審後端;成品看起來、用起來要跟現在的原型高度一致(原話見第 3 節第四條)。Claude 第一次問這題時推薦 Blazor,那一輪的選項與推薦已經作廢。

前端第 1 題把原型的畫面程式搬成 TypeScript,寫法不變 2026-11-17

選的:原型的 CSS 原封不動。畫面與互動的程式照原本的寫法搬過來、加上型別。業務規則全部拿掉,改成向後端要。不用 React、Vue、Angular 這類框架,也不用現成的元件庫。(Claude 推薦,Jesse「照推薦」)

白話與例子
Jesse 的原話:「照推薦,把原型的畫面程式搬成 TypeScript,寫法不變。在 AI 的時代我相信你寫出來的前端程式碼,我相信 REACT/VUE/Angular 是舊時代的產物,太笨重了,會漸漸被淘汰的。」來源檔寫明之後不要再推薦這三個;Claude 回答時講了「會被淘汰」它沒有把握,不當成事實寫。原型現況(2026-11-17 量的):JavaScript 99 個檔、35,452 行,沒有用任何第三方套件;store. 開頭的同步讀取有 950 處,正式產品要改成向後端要、要等回應。隨這題一起定的:前端不放業務規則;不用現成的元件庫。
理由
  • 「高度一致」最可靠的做法是搬,不是照著重做;原型的互動細節是 Jesse 一題一題裁過的,搬的話細節跟著程式走;中文輸入、鍵盤、焦點這些手感也跟著過來。
  • 比「原型直接接後端」多做的都是不做不行的:加型別、把規則搬去後端、把讀資料改成等回應、讓每一頁的內容變成 AI 讀得到的資料。
  • 原型的寫法單純,沒有套件,過去一個月幾十個 AI 接手都改得動。
代價
這套寫法是自己的,沒有社群資源;要加原型沒有的新畫面時沒有現成的可以拿;每個 AI 開工都要先讀懂它;每一頁讀資料的流程都要改(950 處同步讀取)。
沒選的
  • 原型直接接上後端、連 JavaScript 都不改寫:沒有型別、沒有測試、沒人審,三萬多行靠 AI 改;AI 助理要讀寫畫面上的單,接不上。
  • React+TypeScript 重寫、CSS 照搬:幾百個互動細節重寫一遍,每一個都可能有落差。
  • Blazor:同上的落差,加上拖拉、量版面要繞過 JavaScript 轉接,第一次載入慢。
  • 框架+現成元件庫:不像原型,違反第二個條件。
驗證
—
出處
frontend.md 第 1 題
還沒裁、選完之後還開著的:
  • 還沒裁 「原型是驗收標準、用自動比對」是 Claude 提的做法,Jesse 沒有反對也沒有確認。
  • 用什麼建置工具、TypeScript 的型別怎麼從後端的 C# 型別產生;自動比對怎麼做;原型裡哪些檔是畫面、哪些是規則,搬之前要逐檔分。

前端第 2 題畫面上的計算:前端自己算,後端只在存檔時重算 2026-11-17

選的:前端自己算、馬上顯示;後端在存檔(確認變更)時重算一次,不過就回失敗與原因;後端不會每改一格就算。(Jesse 提,Claude 同意;Claude 原本推薦的是「每改完一格請後端試算」)

白話與例子
Jesse 的原話:「我認為後端只有在前端送確認變更例如存檔時才試算,試算失敗就告訴前端變更失敗並且提供原因。前端要具備自己算的能力,大部分的情況下前端算出來的東西都會是對的,而且使用者看到的反應速度也都很快,後端也不必每個動作都審核,可以減少後端算力的開支。你覺得如何?如果有意見或不妥請儘量提出。」Claude 提的四點裡,第 1~3 點 Jesse 沒有反對:前端能算的只有金額(帶出單價、每列金額、稅、總計、四捨五入),能不能刪、權限、成本、沖帳餘額、單號仍然只在後端;兩份算法用同一份題庫把關(Jesse 審 C# 與題庫);四捨五入與小數要先定死。第 4 點是下一題。
理由
Claude 同意的理由:反應速度跟原型一樣,符合「用起來的感覺高度一致」;網路卡的時候畫面照樣會算;請求少很多。
驗證
查到的(2026-11-17):原型的 LiteErp.roundHalfUp 五就進位、負數照絕對值算;C# 的 Math.Round 預設 ToEven(2.5 是 2),後端要明寫 MidpointRounding.AwayFromZero;JavaScript 的 Math.round 剛好一半時往正無限大進。
出處
frontend.md 第 2 題

前端第 3 題存檔時前後端算的不一樣:擋下來、換成後端的數字、再按一次才存 2026-11-17

選的:後端回「金額不一樣」和它算的數字;畫面把數字換掉、標出哪裡變了(「總計從 315 改成 314,請確認後再存一次」);使用者看過再按儲存才存。這種事件要記錄下來,才知道前端有 bug。(Claude 推薦,Jesse「照推薦」)

白話與例子
畫面顯示總計 315 元,按儲存,後端算出來是 314 元。正常不會發生,發生就是前端有 bug 或瀏覽器跑的是舊版程式。回傳的格式後來在後端第 10 題有一個示意(amount_mismatch、409)。
理由
錯的是我們的程式,不該讓使用者卡住;金額變了一定要讓他看到、點過頭,符合「動到資料前要使用者點頭」。
代價
要做「標出哪裡變了」的畫面與事件紀錄。
沒選的
  • 擋下來不給存:最接近 Jesse 的原話、最單純;但使用者自己修不了,櫃台前客人在等。
  • 不擋、直接照後端的數字存:使用者可能已經照 315 收錢,事後才發現單上是 314。
驗證
—
出處
frontend.md 第 3 題

前端第 4 題前端的數字:大整數+小數位數,兩邊照同一組運算規則 2026-11-17

選的:前端的數字做成「一個大整數+小數位數」,用瀏覽器內建的 BigInt;前後端之間傳金額、數量、單價一律用字串("105.50");不追求跟 C# 的 decimal 型別行為一模一樣,追求的是同一組運算規則兩邊各自照做;後端照樣用 decimal,每個除法與進位都透過同一個小函式做;前端的金額是專用的型別,TypeScript 不允許對它直接寫 a * b。(Jesse 問,Claude 提,Jesse「你說的很棒喔,就照你說的辦」)

白話與例子
Jesse 的問題:「前端難道不能自己實作一個跟後端一模一樣的 decimal 嗎?把字串當數字處理做加減乘除。」運算規則:加、減、乘一律精確,不進位;除法不單獨存在,一定是「除完四捨五入到第幾位」一個動作;四捨五入只有一種:五就進位,負數照絕對值算;每個欄位的小數位數固定(金額 0 位、單價 2 位、數量照商品設定)。題庫要特別放剛好一半(2.5、0.005)、負數、除不盡。
理由
這跟 C# decimal 的構造相同(96 位元整數+小數位數),加減乘在整數上算,沒有浮點誤差;照一般 JSON 數字傳,瀏覽器一讀進來就變成浮點數。
沒選的
  • 字串逐位運算(Jesse 原本的想法):加減乘除的進位借位全部自己寫,程式多、容易藏 bug。
  • 全部換成「分」用一般整數:單價 2 位、數量也有小數,乘起來位數不固定。
  • 照原型用浮點數加補償:就是現在的坑。
驗證
BigInt 查 MDN(「It's been available across browsers since September 2020」)。沒實測:後端 decimal 的除法先算到 28 位再進位,理論上跟「精確除完再進位」在極端數字上可能差一點,這是推算,要放進題庫驗;效能沒量。
出處
frontend.md 第 4 題;後端那一面在 backend.md「前端那邊定了、後端要照做的」

AI 助理第 2 題帶進前端的(2026-11-19)

對話的迴圈由瀏覽器全權處理(AI 第 2 題),前端因此多了:問 LLM(經過後端的轉送端點)、照 LLM 說的去叫後端動作或做畫面動作、把結果接回對話紀錄;資料頁與設定頁「先問再改」的確認卡片;請求上「(AI 助理)」的標記。「前端不放業務規則」在「先問再改」這一條有例外;「哪些動作要先問」寫在後端的動作定義上、前端只用一段共用程式照做(AI 第 3 題)。同一天補裁:這句只管後端動作;畫面動作的定義(名稱、參數、說明、要不要先問)也放前端,每種 UI 各帶各的,後端不知道有哪些。

出處:frontend.md「AI 助理第 2 題帶進前端的」

還開著的:每一頁的內容怎麼變成 AI 讀得出、寫得回的資料(AI 第 1 題的要求)。

11. AI 助理第 1 到 7 題

Jesse 2026-11-17 的要求:AI 一開始就要算進架構,用對話(打字、語音)新增、修改、查詢各種單據,變更設定項目(原話見第 3 節第一條)。已經定過、架構要照著走的業務規則(docs\decisions\ai-assistant.md):AI 動到資料前一定要使用者點頭;查詢在對話裡回答、不自動換頁;AI 照叫它做的那個人的權限;操作紀錄寫「某人(AI 助理)」;關掉再打開,對話清空。

送給 LLM 的五塊東西各由誰負責

每一圈送給 LLM 的東西有五塊(AI 第 5 題的題目):

哪一塊誰負責哪一題定的
金鑰與模型與用量上限後端(轉送端點加上去;用哪個模型、用量上限由後端定,因為錢是後端在付;金鑰不進瀏覽器)第 5 題、第 2 題
系統提示前端組(每種 UI 可以有自己的系統提示)第 5 題
後端動作的清單前端組;內容來自後端那支「列出我能叫的動作」的 API(從 C# 的動作定義自動產生、照叫的人的權限過濾、標了「不給 AI」的不列)第 5 題;每一圈帶目錄、要用再載入是第 6 題
畫面動作的清單前端(每種 UI 把自己的畫面動作寫在自己的程式裡,後端不知道有哪些)第 3 題的補裁
對話紀錄前端(只放在瀏覽器分頁裡,後端不記,關掉就沒了)第 2 題

後端為 AI 要做的只有哪幾樣,其餘都在前端

後端(C#,Jesse 審得到)

  • 轉送端點:確認登入、加金鑰與模型、記用量(第 5 題)
  • 一支「列出我能叫的動作」的 API(第 5 題)
  • 每個後端動作的 [Action] 上明寫 AI 叫的時候怎麼做:直接做/對話裡確認/頁面確認視窗/不給 AI,沒寫啟動時擋下來(第 3 題)
  • 動作本身照常走執行器,跟按鈕同一條 HTTP(後端第 5 題)
  • 不為 AI 做通用查詢(第 7 題)

前端(TypeScript,Jesse 不審)

  • 對話的迴圈:問 LLM、讀它要做什麼、真的去做、把結果接回對話紀錄(第 2 題)
  • 對話紀錄(第 2 題)
  • 組系統提示與整份動作清單(第 5 題)
  • 目錄一直帶著、要用再載入(第 6 題)
  • 畫面動作的定義與實作(第 3 題補裁)
  • 「先問再改」的確認卡片,照後端給的值用一段共用程式做(第 2、3 題)
  • 請求上的「(AI 助理)」標記(第 2 題)

一句話從頭到尾

照第 2、3、5、6 題現在的定案畫。第 2 題寫這個例子「要繞四圈:找客戶、找商品、打開新訂單並填入、回一句話」;第 6 題定了之後,第一次用到某個動作要多繞一圈(圖上 ⑥)。動作的名字是第 1 題例子裡的叫法。

使用者 瀏覽器前端 TypeScript 後端轉送端點 OpenRouter背後的 LLM 後端動作 /api/… ① 「列出我能叫的動作」(照權限過濾,不列「不給 AI」的) 名稱、參數格式、說明、「先問」值 ② 打字或說話 ③ 前端組:系統提示+目錄(後端動作與畫面 動作,一個一行)+對話紀錄 ④ 問 LLM 加金鑰與模型、記用量 ⑤ 從目錄挑名字:要用「找客戶」 ⑥ 第一次用到這個動作:把完整說明(參數 格式)交給它,再問一次(多繞一圈) 再問一次(每一圈都經過轉送端點) ⑦ 叫「找客戶」(直接做) ⑧ POST /api/…(跟按鈕同一個端點,請求上標「(AI 助理)」) 執行器:身分、公司、權限、 交易、操作紀錄(第 4 節) 結果 ⑨ 結果接到對話紀錄後面,帶著整段再問; 「找商品」同樣走一遍 ⑩ 叫畫面動作「打開新訂單並填入」(直接做) 瀏覽器自己做:換到新訂單、填好,還沒存 ⑪ 回一句話給使用者 顯示(語音模式用語音) ⑫ 按「儲存」 儲存訂單(跟平常一樣的動作,再走一次執行器) 也可以跟 AI 說「存起來」:這是「對話裡確認」的動作,AI 先講重點, 使用者說「對」或按「確定」才存。LLM 每一圈都經過轉送端點,圖上第 2 圈以後畫成直接連到 OpenRouter
圖 2 「幫好鄰居咖啡開一張訂單,蔥油餅乾 10 包」。① 的清單什麼時候拿、要不要快取還沒定

AI 第 1 題AI 透過什麼動手:畫面和 AI 共用同一批後端動作 2026-11-17

選的:每個操作在後端都是一個有名字、有參數格式的「動作」(找客戶、查售價、建立訂單草稿、儲存訂單)。畫面的按鈕叫它,AI 也叫它。另外給 AI 少數幾個「畫面動作」:打開某一頁、把內容填進畫面上的單。(Claude 推薦,Jesse「照推薦」)

白話與例子
「幫好鄰居咖啡開一張訂單,蔥油餅乾 10 包。」AI 叫「找客戶」「查商品」,再叫「打開新訂單並填入這些內容」;使用者按儲存時走的是跟平常一樣的「儲存訂單」。
理由
  • 規則只寫一次,AI 開的單和人開的單走同一個儲存,庫存連動、權限、操作紀錄自然一致。
  • 跟 2026-10-30 定的互動規則對得上:「AI 填好、使用者按儲存」就是 AI 叫畫面動作、人叫儲存動作。
  • 跟模組化單體是同一件事:模組的入口就是動作,只是要寫得清楚到 AI 讀得懂。
  • 權限與公司隔離不用另外做,AI 用的是登入那個人的身分。
代價
  • 每個功能都要先定義成動作(名字、參數、說明)才能做畫面,前期比較慢。
  • 前端每一頁要能把內容當成資料讀出來、寫回去。
  • 動作會有幾百個,不能每次對話都把全部的說明送給 AI(後來是第 6 題)。
  • 查詢的彈性比直接下 SQL 差,要有對應的報表動作才答得出來(通用查詢後來是第 7 題)。
沒選的
  • AI 像人一樣操作畫面(看截圖、移滑鼠):每一步都要截圖再判斷,很慢、很貴,畫面一改版就可能點錯(一般經驗,沒實測)。
  • 另外寫一套 AI 專用的 API:同一條規則寫兩次,改了一邊忘了另一邊。
  • AI 直接對資料庫下 SQL:寫入會繞過所有規則,查詢也只剩列層級安全性一道防線。
驗證
—
出處
ai-assistant.md 第 1 題

AI 第 2 題對話的迴圈:瀏覽器全權處理 2026-11-19

選的:① 迴圈在瀏覽器(前端 TypeScript)。② 對話紀錄只放在瀏覽器分頁裡,後端不記,關掉就沒了。③ 問 LLM 一律經過後端的轉送端點,金鑰不進瀏覽器(轉送端點做什麼,第 5 題改過,見下一張以後)。④ AI 要叫後端動作時,瀏覽器打跟按鈕一樣的 /api/...;畫面動作(打開某一頁、填打到一半的單)瀏覽器自己做。⑤ 「先問再改」的確認卡片、操作紀錄上的「(AI 助理)」標記,由瀏覽器負責。(Claude 推薦後端跑,Jesse 選瀏覽器)

白話與例子
「迴圈」=問 LLM → 讀它要執行什麼 → 真的去做 → 把結果接到對話紀錄後面 → 帶著整段紀錄再問,一直到 LLM 回一句給使用者的話。Jesse 的原話:「我打算讓瀏覽器全權處理」,Claude 照他的字複述後,他回:「對,就是做法 B」。他選之前問了三件事,其中一句是「如果是由後端處理的話,表示後端要記住對話的狀態,後端的 loading 會變重」。
理由
Jesse 下一段對話自己講的:「我的意思是說, 後端提供 WEB API 就好, 前端長甚麼樣子後端不 CARE, 如果是這樣 AI 邏輯跟著前端跑比較適合」;前一句是「我將來可能會有十種 UI, 後端不可能都知道這些 UI 長甚麼樣子吧」。所以每種 UI 各自帶 AI 邏輯是他要的,不是漏掉的代價。說明頁列的好處:後端最簡單;後端不存對話,場景 ③ 好幾台容器也沒差;畫面動作不用停下來等;AI 叫的後端動作跟按鈕走完全同一條 HTTP。
代價
  • 資料頁、設定頁的「先問再改」在前端,預設是會做:前端哪個動作忘了先問就直接改,權限照樣擋,但後端看不出來。
  • 「(AI 助理)」靠瀏覽器自己在請求上標,後端只能照記;使用者可以把自己改的標成 AI 改的,反過來也行。
  • 整段紀錄由瀏覽器送,使用者改得到,只會騙到他自己這段對話的 AI,真的動作照樣過權限。
  • 每一圈都要從瀏覽器上傳整段紀錄,對話長、手機網路慢時會比較慢(推論,沒量)。
沒選的
  • 後端跑(Claude 推薦):資料頁的「先問再改」預設擋住;代價是畫面動作要「先停、等瀏覽器回報、再接著跑」,對話紀錄要存在後端。
  • 交給 AI 廠商代管(Anthropic Managed Agents):還在 beta;Amazon Bedrock 沒有;綁死一家;對話紀錄存在 Anthropic 到刪掉為止;畫面動作照樣要停下來等。
驗證
—(來源檔查到的 .NET 10 TypedResults.ServerSentEvents 是回答 Jesse 第三個問題時講的做法,不是這題定的)
出處
ai-assistant.md 第 2 題;說明頁 docs\explains\ai-loop.html
還沒裁、選完之後還開著的:
  • 還沒裁 轉送端點用 SSE 回傳、LLM 沒吐字時送心跳、使用者關掉對話欄時停止生字、呼叫 LLM 時手上沒有資料庫交易;對話紀錄裡 LLM 回的內容要原封不動送回去(Claude 順著講的)。
  • 「(AI 助理)」的標頭名稱;用量怎麼算、上限多少;對話很長時上傳的大小要不要設上限;轉送端點要不要記下每一圈。

AI 第 3 題「AI 叫之前要不要先問」:後端動作定義上明寫,沒寫不能啟動;畫面動作的定義在前端 2026-11-19

選的:每個後端動作的定義上都要明寫 AI 叫的時候怎麼做,四種值:直接做(找客戶、查庫存、打開新訂單並填入)、對話裡確認(存起來、改客戶折扣,按確定才做)、頁面確認視窗(刪掉這張,跳頁面自己的 🗑 確認視窗)、不給 AI(不放進交給 AI 的動作清單)。沒寫的動作程式啟動時就擋下來。
同一天補裁(Claude 推薦,Jesse「照推薦」):畫面動作的定義改放前端。每種 UI 把自己的畫面動作(名稱、參數、說明、四種值裡的哪一種、實作)寫在自己的程式裡,問 LLM 時一起帶上去;後端不知道有哪些畫面動作。「沒寫不能啟動」只管後端動作。(Claude 推薦,Jesse 選推薦的)

白話與例子
示意(名稱沒定、沒編譯):[Action("customer/update-discount", "改客戶折扣", Permission.CustomerEdit, Ai = AiUse.Confirm)];動作清單裡是 "ai": "confirm"。對話裡確認的例子:AI 先講重點「好鄰居咖啡的訂單,2 項,452 元,要存嗎?」、改客戶折扣列出「好鄰居咖啡 折扣 95 → 90」。這一題是把第 2 題放在前端的「哪些動作要先問」拿回後端;值後來由那支「列出我能叫的動作」的 API 帶給前端(第 5 題)。
理由
哪些要先問全部寫在 C#,Jesse 審得到;新動作不用改前端;動作清單與「要先問的清單」是同一份,不會對不上。補裁的理由:第 2 題 Jesse 補講的原則(後端提供 Web API 就好,前端長什麼樣子後端不管);定義跟實作在同一個地方;某種 UI 多一個畫面動作只改那種 UI。
代價
幾百個動作每個都要多寫一個值(大多照抄);前端那段共用程式寫錯,還是會全部一起不問。補裁的代價:畫面動作的「先問」值不在 C#,Jesse 審不到(這兩個確認本來就在瀏覽器做);轉送端點要收瀏覽器送來的動作清單,使用者改得到,只騙得到他自己那段對話。
沒選的
  • 後端標、寫資料的預設要確認:寫資料的動作被誤標成「讀」就悄悄變成直接做,沒有東西擋。
  • 前端自己決定:全在不審的那一邊,加動作忘了改前端就不問直接做。
  • (補裁沒選的)後端定一份固定的介面、每種 UI 照著實作:後端還是在規定 UI 要會做什麼。
  • (補裁沒選的)維持後端逐一宣告畫面動作:UI 的畫面動作一變就要改後端,十種 UI 不一樣時後端要有十份。
驗證
—(畫面動作那一邊用 TypeScript 必填欄位擋,是 Claude 提的做法,沒寫過)
出處
ai-assistant.md 第 3 題(含「同一天補裁」)
還沒裁、選完之後還開著的:
  • 哪些動作是「不給 AI」(業務規則,之後談);後端要不要另外擋「標了不給 AI 的動作,請求上卻帶著(AI 助理)標記」。

AI 第 4 題用哪一家、經過哪一條路:LLM 走 OpenRouter;語音以 OpenRouter 為首選 2026-11-19

選的:後端的轉送端點把請求轉給 OpenRouter,由它轉給背後的模型廠商。一把金鑰、一張帳單(預付點數);LLM、STT、TTS 都是同一種格式,換模型只改一個名字。(Claude 推薦正式走 Bedrock、開發用 OpenRouter,Jesse 選全部走 OpenRouter)
同一天補裁(Claude 提,Jesse「照推薦」):LLM 走 OpenRouter 照舊是定案。STT、TTS 改讀成「OpenRouter 是首選」,等語音那一題實測過中文、台灣口音與台語才算定案;不過關就在轉送端點多接一家,前端不用改(Claude 的推論,沒實測)。

白話與例子
經過:Claude 第一次出題時漏列 OpenRouter,Jesse 取消選項後問「為什麼不選 openrouter?」,Claude 承認是漏掉。他接著問了「是不是不管接甚麼 LLM 跑的都是同一個 API?」(是,官方「OpenRouter normalizes the schema across models and providers so you only need to learn one」,但換了模型要重新實測)、「有提供 tts, stt 模型嗎?」(有)、「有哪些 tts, stt 支援語氣跟情緒描述詞?」。Jesse 說「討論完畢了」之後重問,選了「全部走 OpenRouter」。他沒另外說理由。用哪個模型、哪個等級、誰付費這一題不定。
理由
選項上寫的好處:LLM、STT、TTS 同一種格式、同一把金鑰、同一張帳單;換模型只改一個名字,某家掛了可以改走另一家;Jesse 已經有帳號。補裁的理由:語音是跟 LLM 綁在同一題定的,當時中文好不好用沒查,台語與口音也沒實測;OpenRouter 上沒有一個過關的話,「全部」守不住。
代價
營業資料至少經過 OpenRouter 與背後的模型廠商兩家;儲值多付 5.5%;多轉一手(延遲沒量);預付點數,帳單跟 AWS 分開。另外:OpenRouter 本身當機時所有模型一起停(推論)。
沒選的
  • 正式走 Claude 經 Amazon Bedrock、開發用 OpenRouter(Claude 推薦):正式版讀 Claude 的格式,換廠商要改程式;測試與正式兩條路。
  • Claude 經 Anthropic 自家:營業資料多交給 Anthropic,多一份合約、一把金鑰。
  • OpenAI(自家或 Azure 日本東部):多交給一家或多一朵雲。
  • (補裁沒選的)維持「全部」:實測不過關時要回頭推翻一個寫成已定的決定。
驗證
OpenRouter 的價格與資料政策是 2026-11-19 Claude 自己抓官方頁面(「OpenRouter does not store your prompts or responses, unless you opt in」;儲值費「5.5% on Standard」);其他廠商是三個 Sonnet 助手查的。語音的中文、口音、台語 沒實測。
出處
ai-assistant.md 第 4 題(含「同一天補裁」)
還沒裁、選完之後還開著的:
  • 還沒裁 前端讀 OpenRouter 的統一格式、換模型不用改程式(Claude 整理的「改到已經定的」)。
  • 用 Chat Completions 還是 Responses;要不要只用完全不留存的廠商、要不要固定背後的廠商;OpenRouter 掛掉時怎麼辦;用量與點數怎麼管;STT、TTS 選哪個模型;營業資料經過兩家的個資交代。

AI 第 5 題轉送端點只轉送;系統提示與動作清單都由前端組 2026-11-19

選的:① 後端多提供一支普通的 API「列出我能叫的動作」:內容從 C# 的動作定義自動產生(名稱、參數格式、說明、第 3 題的「先問」值),照叫的人的權限過濾,標了「不給 AI」的不列。② 前端拿到後自己組系統提示與整份動作清單(後端動作+自己的畫面動作),連同對話紀錄送給轉送端點。③ 轉送端點只做三件事:確認登入、加金鑰與模型、記用量。用哪個模型、用量上限由後端定,因為錢是後端在付。(Claude 推薦,Jesse「照推薦」)

白話與例子
出題時從 Jesse 的原則出發(後端提供 Web API 就好,前端長什麼樣子後端不管)。這一題改掉了第 2 題「選的」第 3 點(後端加系統提示、動作清單)與第 2 題 Claude 順著講的「轉送端點不收瀏覽器送來的系統提示與動作清單」;modules.md 的 AI 助理模組因此剩轉送端點、那支列出動作的 API、記用量。
理由
照 Jesse 的原則,後端只多一支 API;每種 UI 可以有自己的系統提示(收銀畫面的 AI 跟後台的 AI 講話方式可以不同);系統提示裡很多是畫面的規矩(查詢在對話裡回答、不自動換頁;語音只講摘要),放前端才對得上。
代價
  • 系統提示在前端,Jesse 審不到;他審得到的只剩每個後端動作的說明文字與「先問」值。
  • 登入的人可以拿轉送端點問任何事,用量上限一定要做。
  • 「不給 AI」只是不列進那支 API;瀏覽器硬要叫,動作照樣過權限,後端分不出來。
沒選的
  • 後端加後端動作的清單、系統提示前端帶:「幾百個動作怎麼找」的邏輯就得放後端。
  • 兩塊都由後端加(第 2 題原本記的):後端要懂畫面的規矩,UI 不一樣時後端要有好幾份,跟原則衝突。
  • 系統提示拆兩半:一份提示兩個地方拼,出問題要查兩邊。
驗證
沒實作、沒實測
出處
ai-assistant.md 第 5 題
還沒裁、選完之後還開著的:
  • 那支 API 的名稱與回傳格式;清單要不要讓瀏覽器快取、權限變了怎麼更新;用量上限怎麼算;前端要不要能在後端允許的幾個模型裡面選。

AI 第 6 題幾百個動作怎麼讓 AI 找得到:目錄一直帶著、要用再載入,前端自己做 2026-11-19

選的:每一圈都帶一份短目錄,一個動作一行(名稱+一句話)。AI 從目錄挑名字,前端再把那幾個動作的完整說明(參數格式)給它,它才叫得到。不靠任何廠商的「先找再載入」功能。(Claude 推薦,Jesse「照推薦」)

白話與例子
第 5 題之後整份動作清單在前端手上,每一圈送哪些由前端決定;除了「後端提供搜尋動作的 API」那個選項,每個選項對後端都一樣。出題時 Claude 講了這題不裁也可以、等有真的動作清單再實測;Jesse 選了推薦的。
理由
完全在前端(第 2 題 Jesse 的原則);不綁廠商,換模型不受影響;用名字精確指定,沒有搜尋找不到的問題;不用賭一個 Beta 功能。
代價
第一次用到某個動作要多繞一圈、多等幾秒;目錄本身每一圈都佔幾千 token(Claude 推估約 200 個動作,沒數過、沒量)。
沒選的
  • 用 OpenRouter 的 tool search:Beta、行為可能變;整份清單每一圈都要從瀏覽器上傳;只有正規表示式比對,中文說明比對不比對得到沒實測。
  • 只送目前這一頁相關的動作:在訂單頁問「可樂還有幾罐」就答不出來。
  • 每次全部都送、靠提示快取省錢:每一圈上傳整份;動作越多 AI 越容易挑錯。
  • 後端提供一支「搜尋動作」的 API:後端要懂「AI 現在想找什麼」,是 AI 邏輯,跟原則衝突。
驗證
OpenRouter 的 tool search 是 2026-11-19 Claude 用 curl 抓官方文件原文(「Server tools are currently in beta. The API and behavior may change.」「Only the regex variant is implemented」)。選的做法 沒寫過、沒實測。
出處
ai-assistant.md 第 6 題
還沒裁、選完之後還開著的:
  • 完整說明用什麼方式交給 AI;哪幾個常用動作一開始就整個帶著;目錄要不要照模組分段;動作多到目錄也太長時怎麼辦。

AI 第 7 題不給 AI 通用查詢動作 2026-11-19

選的:不給。AI 只叫現有的查詢與報表動作;報表沒有的看法,AI 回答查不到,頂多指路到最接近的報表。(Claude 推薦,Jesse「照推薦」)

白話與例子
老闆問「上個月賣給好鄰居咖啡的毛利多少」,銷售分析表本來就有,AI 叫那個動作就答得出來。這一題談的是報表沒有的看法。
理由
  • AI 講的每個數字都跟報表同一個來源(modules.md 第 3 題)。
  • 後端不用為 AI 多做任何東西(第 2 題 Jesse 的原則)。
  • 以後真的常被問倒再加,是多一個動作,前面寫的程式不用改。
代價
報表沒有的看法答不出來;現在不知道使用者會問什麼,被問倒的頻率沒有數字。
沒選的
  • AI 自己寫 SQL、後端用唯讀的報表角色執行:毛利、成本、還欠多少 AI 會用自己的算法,可能跟報表不一樣;資料庫分不出誰在問,不能看現有庫存的店員問 AI 就看得到;SQL Jesse 審不到。
  • 後端做一個有限度的通用查詢:等於自己做小型的報表引擎,是只有 AI 會用的後端 API。
驗證
—
出處
ai-assistant.md 第 7 題
還沒裁、選完之後還開著的:
  • AI 把幾個報表動作的結果自己再加減,算錯怎麼辦;要不要記下 AI 答不出來的問題。

12. 部署第 1、2 題

部署只有這兩題是定案。Claude 問第 3 題(AWS 上用哪種服務)時,Jesse 問:「話說現在需要決定這些嗎?這個是不是可以等寫完再決定?」Claude 同意可以等,他回「okay, 繼續」。所以第 3 題以後都延到要上雲端之前;「開發期間放上 AWS 給公司同事測的最省方案」是 Claude 的設計、他還沒回;CI/CD 只討論過、沒裁。

部署第 1 題程式交到三個場景的形式:容器為準 2026-11-17

選的:容器為準。交付的東西就是一個映像檔,三個場景都跑它;本機一個指令同時起程式與 PostgreSQL 兩個容器。(Claude 推薦,Jesse 選)

白話與例子
經過:第一次問完,Jesse 說「先停下來,我有用過 docker,但用的很少,所以針對這題我有很多衍生的問題想先釐清。之後我會請你重問」,問了衍生問題、看了 docker.html,說「docker 我看完了」之後從頭重問,選了推薦的這一項。包映像檔是 .NET 內建的(dotnet publish /t:PublishContainer),不用寫 Dockerfile。
理由
場景 ① 是上雲端之前的內部測試,測的應該就是會上線的那一包;AI 交付前可以在本機把整包跑起來打一遍;包映像檔是 .NET 內建的、開發時照舊直接跑;換版、退版、設定怎麼給三個場景同一套。AI 助理是後端裡的程式、跟著同一包走,只多一組要保管的 API 金鑰。
代價
測試的 PC 要裝容器執行環境。Claude 重問時講明的條件:定案前要在這台 PC 實際裝一次,裝不起來就退到「混合」;2026-11-17 Jesse 說「現在先裝吧」,三項驗證都過,條件解除。
沒選的
  • 混合(雲端用容器、本機直接跑程式):本機測的是 Windows 版、上線的是 Linux 版,本機與雲端的換版做法是兩套。
  • 執行檔為準:每台環境自己顧、場景 ③ 每多一台都要重裝、ECS/Fargate 用不上。
驗證
實測過 2026-11-17,Jesse 的 Windows 10 Pro 10.0.19045 PC,Docker Desktop 4.99.0(install --user,不用系統管理員),引擎 29.9.3、Compose v5.7.0:hello-world 正常;postgres:17(17.12)約 3 秒就緒、刪掉容器用同一個 volume 起新容器資料還在;dotnet new web(SDK 9.0.316)包成映像檔 34 秒、331 MB,跑起來回 200。沒驗:從辦公室另一台電腦連進來;長時間跑穩不穩;Compose 檔沒有實際跑。
出處
deployment.md 第 1 題與「實際試裝」;說明頁 docs\explains\docker.html
還沒裁、選完之後還開著的:
  • 場景 ① 的 PC 是不是 Jesse 這一台,沒問過。

部署第 2 題雲端放哪一家:AWS 2026-11-17

選的:AWS。(Claude 推薦,Jesse 選)

白話與例子
場景 ② 每月試算(美元;程式 1 份 0.5 核心+1 GB 全天開、資料庫 2 GB 等級、硬碟 20 GB;免費額度沒扣):AWS 約 72(資料庫用 db.t4g.micro 約 56)、Google 約 61 或 85、Azure 日本東部約 61。場景 ③ 的費用三家都給不出可靠數字。
理由
Jesse 有 AWS 的經驗(EC2、IAM、Security Group 用得上);要的服務都在;docker.html 整份照 AWS 寫;場景 ② 三家每月差 10 美元上下,比不上重新學一家;選了容器為準,映像檔哪一家都能跑,以後要搬難的只有資料庫。
代價
場景 ② 三家裡最貴(負載平衡器就佔 16 美元);設定最囉嗦(工作定義、服務、目標群組);App Runner 台北沒有。
沒選的
  • Google Cloud:帳號與權限要從頭學;掛自己的網域,內建的 domain mapping 官方寫「At the moment, this option is not recommended for production services」;說明頁的 AWS 部分要重寫。
  • Azure:Taiwan North 在官方區域清單標為 preview;PostgreSQL flexible server 的區域表沒有台灣,現在只能放日本東部或香港。
  • 先不定:後面幾題都跟廠商綁在一起,只能談到原則。
驗證
價格出自 AWS Price List 公開 JSON、Google 價目頁原始 HTML、Azure Retail Prices API(2026-11-17,助手解析);沒有實際在雲端開過。
出處
deployment.md 第 2 題

13. 還沒定的

這個分三堆的分法是 Claude 2026-11-19 整理這一頁時的判斷,Jesse 沒裁。題目本身都是從各檔的「還沒談的」「選完之後還開著的」取的,只列標題,不展開;每一題的細節在上面那張卡的虛線框,或決策檔裡。

一、寫第一行後端程式之前要定的

二、寫到那一塊再定的

三、上雲端之前再定的

這一頁的來源只有 docs\architecture\ 的十個檔;業務規則與沒選的方案的完整理由在那裡與 docs\decisions\。