"Architecture"
- Riverpod 的 reactive 邊界
頁面用了 Riverpod 卻對某些變化沒反應、或 reactive 行為在特定時機炸掉時使用。Riverpod 的 reactive 保證只覆蓋 provider 圖的內部——排查沿著圖的邊界走：變化在圖上嗎、在哪個容器的圖上、節點還活著嗎。
- Collector 架構
HTTP endpoint → JSON Schema 驗證 → 儲存 → 查詢 → rule engine 的五段式處理鏈路
- 10.1 服務拆分與邊界判讀
整理 monolith vs microservice 取捨、服務邊界判讀訊號、拆分時機與回退路徑
- Deterministic vs Fuzzy engineering
LLM 軟體 vs 傳統軟體在資料 / 邏輯 / 行為一致性 / 實驗成本四維度的典範差異、決定哪段該包 guardrail
- Guardrail
在 LLM fuzzy 行為外層加上 schema、validator、policy、human review 與 monitoring 的控制設計
- Local vs Cloud LLM
用隱私、成本、延遲、能力與維運責任判斷任務該跑本地模型還是雲端模型
- Multi-agent system
多個 LLM agent 協作的系統、跟 multi-call workflow 的差異在控制流跟責任邊界、三種拓樸 flat / hierarchical / agent-as-tool
- Three-Layer Architecture
把本地 LLM 工具拆成介面層、推論伺服器層、模型權重層的基礎心智模型
- Activation Function
在 linear layer 之間插入的非線性函數、讓神經網路能表達非線性關係
- Attention
Transformer 內部讓每個 token 對其他 token 加權平均的核心機制、形成 KV cache 跟 context window 的計算基礎
- Causal Mask
在 self-attention 裡擋掉「未來位置」的遮罩、讓 LLM 自回歸生成在訓練時也成立
- Embedding Layer
Transformer 第一層的查表結構、把整數 token ID 轉成可運算的向量
- FFN（Feed-Forward Network）
Transformer block 內部的兩層 linear + activation、佔模型參數量的多數
- Layer Normalization
在每個 token 的 hidden state 上做正規化（減 mean、除 std）、穩定深層網路訓練
- Multi-Head Attention
把 attention 切成多個 head 並行計算、讓模型能同時注意多種模式
- Multimodal Fusion
VLM 把 vision encoder 跟 LLM 結合的方式：early fusion / cross-attention / native multimodal 三條路線
- Residual Connection
把 layer 的輸入直接加到輸出上的「跳接」、讓深層網路的梯度能穩定回流
- RoPE（Rotary Position Embedding）
用旋轉矩陣把位置資訊直接旋轉進 Q/K 向量、現代 LLM 主流的位置編碼方式
- Scaffold vs Harness
Coding agent 的兩個工程層次：scaffold 是建構時靜態結構、harness 是 runtime 的 tool dispatch + context management + safety
- Self-Attention
Q / K / V 都從同一個 sequence 投影出來的 attention、Transformer 的標誌性設計
- Vision Encoder
VLM 內部負責把圖片轉成可進 Transformer 的向量序列的模組、ViT / CLIP encoder 為主流
- 4.1 事件來源、處理流程與狀態邊界
分辨事件來源、事件融合、處理流程、狀態真相與推送邊界
- 7.1 資料庫 transaction 與 schema migration
把 repository 邊界延伸到資料庫交易、migration 與一致性語意
- 0.2 介面 / 伺服器 / 模型三層架構
把任何本地 LLM 工具放回正確的層級，用三層心智模型看懂工具關係
- 0.2 組合優先：小介面與明確依賴
用小介面與 struct 組合取代大型繼承結構
- 4.2 事件去重與語義鍵設計
用 entity ID、event type、來源語意與時間窗口建立去重鍵
- 6.2 如何新增一種 domain event
擴展事件常數、輸入驗證與處理流程
- 7.2 Durable queue、outbox 與 idempotency
設計跨 process 事件傳遞的可靠性與去重邊界
- 2.3 訂閱模型與訊息路由
將 client action 對應到主題訂閱狀態
- 4.3 Source of Truth：狀態邊界
集中狀態更新、保護可變資料、設計查詢 projection
- 6.3 如何擴展狀態投影欄位
更新狀態模型、repository 與 API 輸出
- 7.3 事件去重邏輯的重構策略
保留語義鍵並降低重複流程
- 規模分級應對表
自用級 → 中型 → 大型 → 商業網站級的四級應對方案 — 每級的觸發條件、架構組成和成本
- 0.4 什麼時候選 Go
用選型條件判斷 Go 是否適合高併發服務、背景工作與長連線場景
- 1.4 package、檔案與可見性
看懂 package main、檔案切分與大小寫可見性
- 4.4 多來源 event 融合
合併 HTTP、queue、timer 與外部事件來源
- 1.5 從單檔到多檔案
理解 Go 程式如何從 main.go 長成多檔案與多 package
- 7.5 以 domain 重新整理 package
讓 account、job、event、workflow 這類領域邊界在目錄中可見
- 功能分層與 Backend 選擇
SQLite 層和 PostgreSQL 層各自承載哪些功能 — 分界線是查詢模式而非資料量、觸發升級的是功能需求而非規模成長
- 2.6 struct embedding 與組合式設計
理解 Go 的 embedding、方法提升與組合邊界
- 6.6 如何新增 repository port
先建立儲存邊界，再決定 memory、SQLite 或外部資料庫實作
- 7.6 逐步遷移到 ports/adapters 架構
用 ports 與 adapters 控制 Go 服務的依賴方向
- 6.7 Go 常見服務場景總覽
整理 Go 最常落地的服務情境：即時、背景、事件、通知與 API 聚合
- 1.7 從入口程式看應用啟動流程
用入口程式建立 Go 程式的啟動與資料流模型
- 7.7 composition root 與依賴組裝
把具體 adapter、config 與 usecase wiring 留在應用入口層
- 讀模型的升級判準
repository 開始長出畫面專用查詢方法、或有人提議「上 CQRS」時使用。讀側是一道階梯而不是開關：訊號決定該爬到哪一階，自檢問句是「這個查詢回傳的是讀的形狀、還是 aggregate 的形狀」。
- 0.8 Deterministic vs Fuzzy Engineering：軟體設計典範的位移
傳統 deterministic 軟體跟 fuzzy LLM 軟體在資料、邏輯、分解、實驗成本四個維度的根本差異、以及哪段該 deterministic、哪段該 fuzzy 的決策框架
- 4.8 Multi-Agent 拓樸：flat / hierarchical / agent-as-tool
從 multi-call workflow 走到 multi-agent system 的判讀、flat vs hierarchical 拓樸、agent-as-tool 的 MCP 視角、specialization 跟 orchestration overhead 的取捨
- 6.8 高併發下的 Redis 與 SQL 使用原則
從 Go 服務角度整理 Redis 與 SQL 的高併發存取邊界
- domain event 與狀態流
為了讓某個畫面刷新而補發事件、或監聽端掛著全事件過濾器時使用。事件記錄離散事實、狀態流發布連續觀測——判準是消費者問「發生了什麼」還是「現在是什麼」；載體借用的代價是涵蓋面靠枚舉維持。
- domain event 與命令、查詢的分界
事件類別以動詞開頭、或事件成對出現 Requested/Provided 帶 correlation id 時使用。事件只承載已發生的事實——命令有唯一處理者與成敗、查詢是一問一答的對話；把意圖或對話裝進事件通道、責任結構會跟著錯位。
- 3.10 標準庫如何支撐服務型 Go
把 context、net/http、log/slog、defer 與 time 連成服務底座
- DragonflyDB shared-nothing 多核架構：用 scale-up 取代 Redis Cluster
Redis 要靠 Cluster 分片才能用滿一台多核機器，DragonflyDB 賭的是相反方向——單一進程 thread-per-core、shared-nothing、把單機推到 Redis 要好幾個 shard 才達到的規模。本文展開 thread-per-core 與 dashtable 的架構、fork-less snapshot、5 個把架構假設寫成 production 事故的踩坑，以及 scale-up 撞牆該回 Cluster 的邊界
- 系統架構
要決定整個系統該長什麼形狀、或已經在拆分而每個選項都有代價時的選讀
- Filter 與 Source 的抽象層錯位
Filter 必須跟它過濾的資料源在同一層運作。視覺層的 filter 套在資料層分批產出的 source 上、會在「一筆」的定義上產生語意縫 — 使用者要的「全部符合」變成「目前載入的符合」、然後 silent 失敗。本文展開層錯位的識別與糾正。
- Filter × Source 的合成策略五選一
Filter 跟 paginated / streaming source 合成的五種策略、各自機會成本不同：A 推進 query / B 自動續抓 / C 預先 index / D 誠實 UX / E 接受語意縮小。沒有絕對最佳、看 source capabilities、match 密度、UX 容忍度而定。
- 資料源的形狀決定 feature 的形狀
Feature 設計要服從資料源的形狀（一次性 / 分批 / streaming / cached）— 不能憑 UI 想要的形狀去倒推資料層。憑 UI 倒推 = 在錯誤的層解錯誤的問題、產生 #55 層錯位類 bug。
- Feature 操作要跟 Source 同層合成
Filter / sort / count / transform / search 是 stream 操作、必須跟 stream 的 materialization 同層或更上游合成。在下游做 = 操作 subset 不是 stream。本原則跨前端 UI、後端 API、演算法管線通用、不只是視覺層 vs 資料層。
- URL 是 stateful UI 的儲存層 — 哪些 state 該寫進 URL
互動式 UI 的 state 散落在多層（in-memory / URL / localStorage / server / index）、每層有不同特性。可分享 / 可恢復 / 可導航的 state 該寫進 URL — 不寫進 = silent 把這些特性犧牲掉。本文展開「state 的儲存層選擇」協議與 URL 的具體位置。
- 搜尋引擎的匹配模式跟使用者預期的對齊
搜尋引擎的匹配模式（prefix / substring / fuzzy / semantic）各有不同。預設多半是 prefix（為了 index size）、但使用者被 Google 訓練成預期 substring。沒對齊 = silent 失敗：搜「pre」找不到 backpressure。本卡展開五種匹配模式、跟使用者意圖的對齊協議、五個合成策略。
- Build-time 預處理 vs Runtime 計算的光譜：何時把成本前置
計算可放 build-time（預處理一次、runtime 0）或 runtime（per query 算）— 兩極之間有 hybrid 段（hot path 預算、cold path runtime）。判準四軸：query 頻率 / dataset 大小 / freshness 需求 / build pipeline 複雜度。Build-time 不是「永遠較好」、freshness / 多樣性高時 runtime 反而對。本卡把 #59 五策略中「query-side pushdown vs client-side fallback」的取捨抽象化、跨領域適用。
- Engine 不可調時、把 transformation 移到外層
當底層 engine 沒開放某能力的客製 API、不該硬戳 engine 內部、改在 engine 的「輸入層」做 transformation。Search engine 不支援 substring → build-time 加 suffix tokens；LLM 不支援某 reasoning → prompt 層做 chain-of-thought；DB 不支援某 query → 預先 denormalize column；compiler 不可調 → source-level macro。本卡是 #45 外部組件合作四層 + #87 build-time vs runtime 的具體實作 pattern。
- 7.21 資安如何成為服務設計輸入
新服務或大改版要進設計評審時，判斷資安輸入齊不齊；也用於事後才發現資產分母或證據來源缺席的場景
- 7.24 資安事故如何回寫產品與架構
把事故教訓回寫到產品決策、架構控制與知識網，建立持續改進閉環
- Go 教材核心術語
整理 Go 入門與進階篇共用的架構、事件、狀態與邊界詞彙
- Event Log
說明事件歷史如何保存、重播與支援跨服務資料重建
- Read Model
說明為查詢場景建立的讀取模型，與正式狀態的責任分離
- Projection
說明從事件流或資料變更推算出查詢用讀取視圖的轉換機制
- CQRS
說明讀寫不對稱時為何需要分離查詢與寫入責任、分離的判準與代價
- Event Sourcing
說明用 append-only 事件流取代 mutable state 作為正式紀錄的設計模式、需求判準與代價
- 加書後統計不刷新 — ref.watch 觀察的是 provider 圖、不是資料庫
頁面用了 Riverpod 卻在資料寫入後不更新、或發現自己在導航返回點補 loadData()、用 EventBus 事件觸發 reload 時使用。ref.watch 的 reactive 範圍是 provider 圖上的狀態變化；資料庫寫入不在圖上，補償刷新的出現就是這個缺口的訊號。
- 用事件做同步查詢、等於手工重建 RPC — 跨 domain 解耦的完整帳單
domain 直接查另一個 domain 的 repository 違反依賴方向；改事件驅動的 request/response 解了耦、但帳單具體：correlation id 配對並發、timeout 機制、三條錯誤路徑——都是同步呼叫免費附贈的東西。判準是需要解耦「依賴方向」還是「時間與部署」：前者用消費端 Port 就夠、後者才值得付事件的價。
- Dart StreamController：single-subscription vs broadcast 的設計選型問題
Dart `Bad state: Stream has already been listened to.` 的根因：預設單訂閱在第二個訂閱者出現時才爆。StreamController vs .broadcast() 修復決策、與 Rx / .obs 的比較。
- YAGNI 的真實適用條件：成本對稱性、可逆性、領域先驗劃出邊界
YAGNI 不是「永遠選最受限選項」、是「不為未來投入額外成本」的原則。用成本對稱性、可逆性、領域先驗三軸框架釐清「該選通用 default」與「該避免過度設計」的邊界、並補上 review checklist、架構規範、領域先驗清單三層制度補強。
- Data Flow and Filter Composition — Filter × Source 層錯位與五策略
frontend-with-playwright reference：Filter / sort / count / transform stream 操作的層錯位識別 + 五策略合成。原則跨前端 / 後端 / 演算法 / DB 通用、playwright 驗證模板。