🌐【教學】把 Vue + Pinia 程式交付給甲方：用淺顯語言說明程式目的、結構與使用說明

-

 

為誰而寫（目標讀者）

這篇文章適合：

  • 非軟體背景的甲方／專案負責人，想快速理解前端程式在做什麼與如何部署或使用。

  • 需要審閱交付物（deliverables）的PM或驗收單位。

  • 初階工程師或新進同仁想學習如何撰寫清楚的程式說明以利交付。



概覽 — 這份程式在做什麼？

我們討論的是一個前端專案中，用來「管理全域版本與每個頁面狀態」的 Pinia Store（apsPlanStore），以及如何在檔案頂端加入專業的檔案說明（header comment），以利日後維護、交付與甲方驗收。

重點功能簡述（以非技術語言）：

  • 這個 Store（儲存區）主要保存「使用者在各頁面選的版本、查詢到的表頭與資料、以及頁面篩選條件」。

  • 有「全域版本」供所有頁面共用（例如：當你在某一頁選擇了 APS 版本，其他頁面可以同步使用）。

  • 支援把每一頁的狀態儲存起來（例如 page1...page6），切換頁面時不會遺失使用者設定。

  • 提供設定、清除與更新資料的幾個方法，以便前端元件呼叫。



為什麼在程式上方要寫註解（給甲方能看懂的理由）

想像一份工程交付物像一台機器，程式的上方註解就是操作說明書。甲方或未參與開發的人看這段文字可以快速知道：

  • 檔案用途：這個檔案是做什麼的？

  • 使用方式：要如何在專案中使用或呼叫？

  • 注意事項：部署、相依性、版本、誰負責、建立時間等。

  • 驗收準則：甲方在驗收時該看哪些行為是否正常（例如：切換版本後所有頁面同步、分頁資料保留）。

若沒有清楚註解，甲方在測試或上線時會花更多時間確認行為是否正確，甚至造成誤解或退工。



檔案頭註解範例（實務可直接貼在 .ts 檔最上方）

（這段要放在 apsPlanStore.ts 最上方）

/**
 * 檔案名稱  : apsPlanStore.ts
 * 功能說明  : Pinia Store，管理 APS 版本與每頁（page1~page6）之狀態：
 *               - 全域 APS 版本 (globalApsVersion)
 *               - 全域通用篩選 (globalCommonFilters)
 *               - 各頁面之 selectedVersion / tableHeaders / mappedTableData / filters
 * 使用方式  :
 *   1. 匯入： import { useApsPlanStore } from '@/stores/apsPlanStore'
 *   2. 取得 store： const store = useApsPlanStore()
 *   3. 設定頁面資料： store.setPageData(pageKey, version, headers, data, filters)
 *   4. 清除頁面資料： store.clearPageData(pageKey)
 * 注意事項  :
 *   - 若新增頁面（page7...），請同步在 pageStates 新增對應結構
 *   - 請先呼叫 setVersionMappings 以初始化 apsToDocMap / docToApsMap
 * 建議驗收項目 :
 *   - 切換版本後 globalApsVersion 正確更新
 *   - 每頁的資料能正確被 set / clear / preserve
 * 作者      : 開發者姓名
 * 建立日期  : YYYY-MM-DD
 * 版本      : 1.0.0
 */


把程式「講給不懂的人聽」：逐段說明（用生活化比喻）

  1. Store = 資料櫃
    想像前端有一個共用的資料櫃（store），所有頁面都可以把資料放進去或從裡面拿出來。這樣切換頁面時就不用重新查詢、也不會忘記使用者剛剛選的條件。

  2. globalApsVersion = 全站的版本開關
    就像你在一個專案中選了一份「報表版本」，希望所有頁面都看到同一個版本內容（避免前後不一致）。這個欄位就是做這件事的。

  3. pageStates = 每頁的小抽屜
    每個頁面（page1～page6）都有自己獨立的抽屜，裡面放選的版本、表格標題、查到的資料與該頁面的篩選條件。離開頁面再回來可以恢復原狀。

  4. apsToDocMap / docToApsMap = 版本對照表
    當系統中有兩種不同但可轉換的版本編號（例如 APS 版本 vs DOC_NO），這裡放的是對照表，方便程式互相轉換。

  5. actions（像 setPageData） = 操作說明書上的步驟
    這些方法是給 UI 呼叫的（例如搜尋完成後把資料存進 store，或用戶按清除時清空該頁資料）。



交付給甲方時建議的內容清單（Checklist）

把這些項目一併放到交付包會大幅提升甲方驗收速度與信任度

  1. 程式檔案（完整 .ts / .vue）與打包檔案（如果適用）

  2. 每個主要檔案的檔案頭註解（如上範例）

  3. README.md（說明如何啟動本地環境、環境變數、後端 API 位址）

  4. 測試手冊（至少包含 5~10 個驗收流程，例如：切換版本→檢查每頁資料）

  5. 專案架構圖（簡單的檔案/模組依賴圖）

  6. 版本說明（哪些檔案在這個版本被修改）

  7. 若有 mapping 資料：提供 CSV 或 JSON 作為初始資料範本



驗收範例測試流程（給非技術驗收人員）

  1. 前置：請工程師啟動系統或提供測試環境 URL。

  2. 測項 A：在 page1 選擇 APS 版本 v202507 → 確認右上顯示或頁面標題顯示該版本（或請工程師列出 globalApsVersion）。

  3. 測項 B：切到 page2，確認顯示內容是否以同一版本為基準。

  4. 測項 C：在 page3 做搜尋並套篩選條件 → 切回 page1 → 返回 page3，確認條件與結果仍存在。

  5. 測項 D：使用「清除」功能後，確認該頁面資料與篩選被重置。

  6. 測項 E（映射測試）：若系統有 doc ↔ aps 轉換，驗證轉換後的編號是否正確顯示。



常見 Q&A（設給甲方或專案管理者）

  • Q：沒有註解會怎樣？
    A：未來若要改需求或除錯，開發者需要花更多時間理解邏輯，導致維護成本提高，也可能影響上線時程。

  • Q：要不要把測試指令也放進 README？
    A：強烈建議，把如何啟動、環境變數、前後端連線方式與基本驗收流程寫清楚，能加速驗收與移交。

  • Q：如果新增頁面要怎麼做？
    A：工程師只需在 pageStates 加入對應 key（例如 page7）並在註解、README 更新使用說明；若涉及 mapping，還要更新映射表。



結語（簡短收尾）

把程式交付給甲方，不只是把 .ts 檔丟過去而已。清楚的檔案註解、README、驗收步驟與交付清單，能讓甲方快速驗收、減少來回溝通與修正。對工程團隊來說，這也降低未來維護成本，提升專案專業度與信任度。



建議後續動作（給開發者）

  1. 把上文的檔案頭註解加入每個主要 .ts / .vue 檔案。

  2. 撰寫 README 與簡短的驗收手冊（step-by-step）。

  3. 若要對外公開或作技術交接，將上述測試流程製成一頁 PDF 交付甲方。

留言

張貼留言

這個網誌中的熱門文章

🛠【ASP.NET Core + Oracle】解決 ORA-00904 "FALSE": 無效的 ID 錯誤與資料欄位動態插入顯示問題

-
  🔍 問題描述 在開發群創光電內部的 APS 排程系統（使用 ASP.NET Core + Vue 3 + Oracle），前端發生多筆錯誤訊息： Request failed with status code 500 Oracle.ManagedDataAccess.Client.OracleException: ORA-00904: "FALSE": 無效的 ID 這是 Oracle 資料庫對布林值處理不一致造成的錯誤，我們後端嘗試將某個欄位 .Where(x => x.FLAG == false) 寫法，經由 EF Core 轉成 SQL： SELECT * FROM TABLE WHERE FLAG = FALSE 而 Oracle 並不支援 FALSE 關鍵字作為布林值 → 導致查詢失敗。 🔧 解決方案 1：避免布林值直接進入 LINQ to SQL EF Core + Oracle 不支援下列語法： .Where(x => x.IsActive == false) // ❌ Oracle 無法解析 FALSE ✅ 解法 ：將布林判斷移至 .ToList() 之後，變成記憶體篩選： var list = await db.Table.Where(x => x.Version == ver).ToListAsync(); var filtered = list.Where(x => !x.IsActive).ToList(); // ✅ 在記憶體中比對布林 🔧 解決方案 2：安全轉換 SEQ_NO 為 Decimal 後端為了將前段表 APSZFRONT 的 SEQ_NO 與 APSZLCM 的 APS_PLAN_SEQ 對應，用到了這段程式碼： Convert.ToDecimal(front.SEQ_NO) 但一旦 SEQ_NO 含有英文字母（例如 GN140CHCAAE90S_20250811_1_531 ），就會丟出 FormatException → 造成 HTTP 500。 ✅ 正確寫法（TryParse 避免失敗） ： de...
閱讀完整內容

🛠【實戰排除教學】從 VS Code 的 _logger 錯誤，到 PowerShell 找不到 npm/serve，再到 Oracle ORA-03135 連線中斷——一次搞懂！

-
  前言 這篇文章把你在實務中 可能一次遇到的三類問題 整合成一篇易懂、可照做的排錯筆記： C# / EF Core ：VS Code 顯示 CS0103: The name '_logger' does not exist 前端部署預覽 ：PowerShell 說找不到 serve 、更慘的是連 npm 、 node 也找不到 Oracle 連線中斷 ：API 查詢跑一陣子後直接噴 ORA-03135: connection lost contact 我會用工程師口吻、但寫給不熟悉的人也看得懂的方式，帶你一步步修好。 一、VS Code： _logger 不存在（CS0103） 問題現象 在 catch 裡面呼叫 _logger.LogError(...) ，卻出現： CS0103: The name '_logger' does not exist in the current context 代表 類別裡沒有宣告或注入 _logger 。 正確作法：在類別中注入 Logger 類別欄位 using Microsoft.Extensions.Logging; public class ApsDataProcessor { private readonly AppDbContext _context; private readonly ILogger _logger; public ApsDataProcessor(AppDbContext context, ILogger logger) { _context = context; _logger = logger; } public async Task > GetDataByVersionA(string version) { try ...
閱讀完整內容

🔎如何在 Oracle PL/SQL 儲存過程中為文字欄位加入換行符號（CHR(10)）——以 Updlcmremark 為例

-
  前言 在企業級系統開發中，我們常會將複雜的商業邏輯封裝成 Oracle PL/SQL 的儲存過程（Stored Procedure），以便重複使用並確保邏輯一致性。 這次的案例是 修改 Updlcmremark 儲存過程 ，目的是讓產出的 REMARK 欄位在資料庫中具有「換行」格式，而不只是用逗號分隔，方便報表與前端顯示。 問題背景 原本的 Updlcmremark 過程中，對於某些資料（例如來自 APS_Z_LCM_CHECK 的 process_step 與 eq ），是直接用字串拼接的方式： v_remark := NVL(v_process_step, '') || '' || NVL(v_eq, ''); 這種寫法的缺點是： 資料之間沒有任何分隔符號，閱讀性差。 若要在前端或報表中換行，必須額外處理，不方便。 如果一個 SEQ_NO 有多筆資料，這種寫法只會取到第一筆（ FETCH 單筆），其他資料會被忽略。 改進需求 參考同系統的另一支儲存過程 Updmremark ，該過程在拼接文字時不僅使用逗號分隔，還加上換行符號： || ' ,' || CHR(10) 這樣在資料庫中儲存的內容，就會自帶換行，即使直接查詢或匯出到 Excel 報表，也能保有可讀性。 解決方案 方案一：簡單版（單筆取值加換行） 如果 unknown 游標一次只需要取一筆資料，可以直接在原本字串後加上逗號與換行符號： v_remark := NVL(v_process_step, '') || ' ' || NVL(v_eq, '') || ' ,' || CHR(10); 這樣每筆 remark 都會以「逗號 + 換行」結尾。 方案二：完整版（多筆累加加換行） 如果 unknown 游標可能有多筆資料，則應該使用 FOR rec_...
閱讀完整內容