架構文件：讓客戶的 IT 團隊看得懂、你自己也好維護

說明書要分兩種讀者 比喻：一台機器的說明書。組裝的人要知道每個零件怎麼接；買的人只想知道它能做什麼、耗電多少、壞了找誰。同一份文件同時服務兩種人，結果是兩邊都不想讀。 架構文件也一樣，要分兩份：給客戶 IT 的技術版，和給決策者的一頁版。 先講一個判準，整集都圍著它：好的架構文件，是讓接手的人不需要打電話給你。 架構圖畫到什麼細節 分三層，但大部分客戶專案只需要前兩層。 第一層：系統跟外界 一張圖回答：誰在用這套系統？它跟哪些外部系統往來？ 第二層：盒子圖 系統內部分成幾塊、各自負責什麼、資料往哪個方向流。 這一張就能回答八成的問題：資料從哪來、AI 在哪一段介入、跟既有系統怎麼接、誰在用。 第三層：只在必要的地方 某一塊特別複雜、或特別容易出事（例如跟 ERP 的整合），才單獨畫細一層。不要每一塊都畫。 太細與太粗的症狀 症狀　·　後果 畫太細　·　每一個函式、每一張表都畫進去　·　沒有人讀，而且改一次程式圖就過期 畫太粗　·　三個方塊寫「前端、後端、資料庫」　·　讀了等於沒讀，接手的人還是要問你 剛好　·　看得出資料怎麼流、哪裡接外部系統、哪裡有 AI 與人工　·　接手的人能自己開始看程式 判斷標準很實際：這張圖在程式小改之後還成立嗎？ 每改一次程式就要重畫，代表畫太細了。 技術版的七個章節 章節　·　寫什麼 1 系統概觀　·　一段話加第一層圖 2 元件與職責　·　每一塊負責什麼、不負責什麼 3 資料流　·　主要流程各走一次（例如「開一張報價單」從頭到尾） 4 外部整合　·　對接哪些系統、用什麼介面、誰維護那一端 5 環境與部署　·　開發／測試／正式各在哪、怎麼上線（第 09 集） 6 權限與資安　·　誰能存取什麼、資料存在哪、保留多久 7 維運須知　·　誰、在什麼時候、該做什麼 第 7 章最常被省略，卻是「不用打電話給你」的關鍵。它要寫的是具體的事：每天要不要看什麼、備份多久跑一次、憑證什麼時候到期、出問題先看哪個紀錄。 給非技術決策者的那一頁 這不是技術版的簡化，是另一份東西。它只回答三題： 1. 這套系統碰到我們哪些資...