軟體專案文件清單：業主該拿到哪些文件、每份怎麼驗收

系統上線半年，原本的工程師離職了，新來的維護廠商第一句話是：「請問有部署文件嗎？」你翻遍信箱，只找到一份開案時的報價需求表、幾張設計稿截圖，和一個不知道密碼還對不對的主機帳號。接下來的幾週，新團隊只能一邊讀程式一邊猜，原本一天能完成的小修改拖成一週。

軟體專案文件的價值，通常要到這種時刻才被看見。文件不是給廠商交差用的附件，而是讓系統可以被理解、被維護、被交接的說明書。業主沒有拿到文件，等於買了一台沒有操作手冊、也沒有維修圖的機器。

這篇列出業主應該拿到的七類文件，說明每一份該寫到什麼程度、什麼時候交、怎麼驗收。原始碼與帳號所有權的移交流程，則在原始碼所有權與專案交接另外說明，兩篇可以搭配看。

為什麼業主要在意文件

很多業主覺得文件是工程師之間的事，自己看不懂也用不到。但文件影響的其實是業主的三件事：

• 換人的成本：沒有文件，任何新團隊接手都要先花時間「考古」。這段時間的工作量最後還是由業主負擔。
• 溝通的依據：需求與範圍文件是驗收與變更爭議時唯一的共同基準。沒有它，雙方只能各說各話。
• 營運的安全：主機到期、憑證過期、資料要還原時，能不能在不找原廠商的情況下處理，取決於維運手冊與帳號清單寫得夠不夠清楚。

換句話說，文件是業主對系統保有掌控權的方式。它應該寫進合約的交付項目，而不是靠廠商自發。

業主應該拿到的七類文件

以下依專案進行的順序排列。不同規模的專案可以合併或簡化，但每一類的內容都應該在某份文件裡找得到。

一、需求與範圍文件

說明系統要做什麼、不做什麼。內容至少包含：功能清單、每個功能的使用者與操作流程、商業規則（例如什麼條件可以退貨）、角色與權限、明確排除的項目，以及之後所有變更的紀錄。

這份文件是整個專案的地基，驗收時就是拿它逐項比對。寫法可以參考軟體需求怎麼寫；範圍確定之後的每一次調整，都要用需求變更管理的方式補記進去，否則文件很快就和實際系統脫節。

二、設計稿與設計規範

最終定版的畫面設計檔（原始設計檔，不只是截圖或 PDF），加上元件與樣式規範：顏色、字級、按鈕與表單的狀態、各種螢幕尺寸的版面。

原始檔的重要性在於：日後要新增頁面或改版，設計師可以直接沿用，而不是從截圖重畫。設計審查的重點可以看UI/UX 設計稿審查指南。

三、系統架構說明

用一張圖加幾頁文字，說明系統由哪些部分組成、彼此怎麼連接。內容包含：前端、後端、資料庫、檔案儲存、排程工作分別放在哪裡；串接了哪些第三方服務（金流、簡訊、地圖、寄信）；資料大致怎麼流動；使用了哪些主要技術與版本。

這份文件不需要很長，但接手的工程師讀完要能回答「這個系統長什麼樣子」。

四、API 文件

如果系統有提供介面給 App、其他系統或合作夥伴呼叫，就需要 API 文件：每支介面的用途、網址、需要帶的參數、回傳的資料格式、錯誤代碼、認證方式。

API 文件最好能從程式自動產生或至少與程式一起維護，否則改了介面忘了改文件，下一個串接的人就會照錯的說明做。

五、帳號與服務清單

列出系統運作所需的所有外部帳號與服務：網域註冊商、主機或雲端平台、資料庫、寄信服務、金流、簡訊、App 開發者帳號、分析工具、原始碼儲存庫。每一項記錄用途、登入帳號（不含密碼）、所有權人、到期日與續約方式、負責人。

密碼本身放在密碼管理工具或另外安全交付，不要寫在一般文件裡。最重要的檢查點是所有權人是不是你的公司，而不是廠商或某個員工的個人帳號。

六、部署與維運手冊

說明系統怎麼從原始碼變成線上服務，以及上線後怎麼照顧它。至少包含：

• 環境說明：開發、測試、正式環境各在哪裡，差異是什麼。環境的概念可以先看開發、測試、正式環境與部署白話解說。
• 部署步驟：怎麼把新版本上線、怎麼退回上一版。
• 設定與環境變數清單：有哪些設定、各自的用途（不含實際密鑰）。
• 備份與還原：備份什麼、多久一次、存在哪、怎麼還原。
• 監控與警報：監看哪些指標、警報寄給誰、常見狀況的處理步驟。
• 定期維護事項：憑證更新、套件與作業系統更新、資料清理。

七、測試紀錄與使用手冊

測試紀錄包含測試案例、每次測試的結果、已知但決定暫不修的問題。它證明系統在交付時被驗證過哪些情境，也讓未來改版時知道該重測什麼。驗收測試的安排方式在軟體驗收測試（UAT）指南。

使用手冊是給實際操作系統的同仁看的：怎麼登入、主要功能怎麼操作、常見問題怎麼處理。後台系統尤其需要，否則一換人，操作知識就跟著流失。可以是文件、截圖教學或短片，形式不拘，重點是新同仁照著做得出來。

每類文件什麼時候交：建議的交付時程

文件分批交，比結案時一次補齊可靠得多。可以把下面這張表放進合約或專案計畫：

文件	建議交付時點	誰主要負責
需求與範圍文件	開發開始前確認，之後隨變更更新	PM
設計稿與規範	設計階段結束時定版	設計師
系統架構說明	開發初期提出，各期結束時更新	後端或技術負責人
API 文件	隨各期功能交付	後端
帳號與服務清單	第一個帳號開通時就建立，持續更新	PM 與維運
部署與維運手冊	第一次正式上線前	維運
測試紀錄	每次驗收時	QA
使用手冊	驗收前提供初版，上線前定版	PM 或設計師

表中的分工是常見安排，精簡團隊可能由同一人兼任多項；不論誰寫，業主端都要有一位窗口負責確認每份文件已交付並放在公司有權限的位置。

怎麼驗收文件：業主不懂技術也能做的檢查

業主看不懂 API 文件很正常，但仍然可以檢查文件是否「能用」。以下這份清單可以直接拿去用：

完整性檢查

• 上面七類文件都找得到，或明確說明合併在哪一份裡。
• 每份文件都有版本或更新日期。
• 文件放在公司有存取權限的位置，不是只寄一份附件。

一致性檢查

• 隨機挑幾個功能，需求文件裡的描述與實際系統行為一致。
• 帳號清單裡的每一個服務，都能用公司的身分登入看到。
• 帳號清單的所有權人欄位都是公司，沒有廠商或個人名義。

可操作性檢查

• 請廠商照部署手冊，在你面前或錄影示範部署一次測試環境。
• 請廠商照還原步驟，示範從備份還原一份資料到測試環境。
• 請一位沒參與專案的同仁，照使用手冊完成一項日常操作。

第三方檢查（選擇性）

• 請另一位工程師或技術顧問花一點時間閱讀架構說明與部署手冊，回答「如果明天由你接手，還缺什麼」。

最後一項特別有效。文件是不是夠用，最好的判斷者就是將來要接手的人；如果內部沒有技術人員，可以考慮兼任技術長服務這類外部協助來做這次檢查。

常見的文件問題與對策

文件寫完就沒人更新。對策是把「更新相關文件」寫進每次變更與每期驗收的完成條件，沒更新就不算完成。

只有截圖、沒有原始檔。設計稿只有 PDF、架構圖只有圖片，日後無法修改。驗收時直接要求原始檔。

帳號掛在廠商名下。網域、主機、App 開發者帳號用廠商的帳號開，結案後才發現搬不走。對策是一開始就由業主開立帳號，再授權給廠商使用。

密碼寫在文件裡四處傳。交付文件時把密碼一起寫進去，結果在信件與通訊軟體裡散落各處。對策是用密碼管理工具分享，交接後全面更換。

文件只有「是什麼」，沒有「怎麼做」。架構說明寫得很漂亮，但沒有任何操作步驟。對策是驗收時用前面的可操作性檢查，讓對方實際照著做一次。

文件與交接的分工

這篇談的是專案過程中與結案時「該有哪些文件、內容是否夠用」。當你要換廠商、或專案結束要把系統完整移交到自己手上時，還需要處理原始碼與儲存庫權限、帳號移轉、密碼更換、知識轉移會議等步驟，那些流程整理在原始碼所有權與專案交接。

兩者的關係是：文件是交接的材料，交接是把材料連同控制權一起拿回來的程序。文件做得好，交接會順很多；文件沒有，交接就只是一場考古。

結語：把文件當成交付物，而不是附贈品

業主能做的最重要一件事，是在合約與每個里程碑裡把文件明確列為交付項目，並在驗收時實際檢查。文件分批產出、隨系統更新、放在你掌控的地方，三件事做到，系統就不會被綁在任何一個人身上。

NETVANA 承接軟體專案時，會在開案就和業主約定各階段要交付的文件與存放位置，並在驗收時示範部署與還原流程；如果你手上已經有一套缺文件的系統，我們也可以協助盤點現況、補齊架構說明與維運手冊。軟體服務一律採詢問報價制，會先了解系統現況與文件缺口再提出建議，歡迎與我們聯絡，服務範圍請見軟體服務介紹。

延伸閱讀：結案與換廠商時的完整移交步驟，看原始碼所有權與專案交接；需求文件的寫法，看軟體需求怎麼寫；測試紀錄與驗收怎麼安排，看軟體驗收測試（UAT）指南；部署手冊會用到的環境概念，看開發、測試、正式環境與部署白話解說；開案前該約定的事項，看軟體專案啟動前業主檢查清單。