CL3 開發週記｜v1.4.x 走向 v1.5.1：從功能堆疊，走向可維護的平台工程

 


CL3 開發週記｜v1.4.x 走向 v1.5.1：從功能堆疊，走向可維護的平台工程

發布日期：2026-03-14
作者：Michael
專案：CL3 Platform

這一週，CL3 的開發重點，不只是新增功能，而是更明確地把整個系統往「平台化、工程化、可維護化」推進。

若說前一階段的核心，是讓 CL3 能夠完成資料抓取、快照寫入、API 輸出與 Dashboard 呈現；那麼這一週更重要的任務，則是讓系統從「已經能運作」，進一步提升為「可以長期維護、可以穩定交付、可以逐步擴張」。

本週的工作，橫跨了幾個核心面向：

  • Dashboard UI 與資訊顯示優化

  • 中英文 / 多語系架構落地

  • Admin 資產管理流程強化

  • ALLIANZ 與 YFINANCE driver 防呆方向明確化

  • DEV 到 STG 的部署與交付流程整理

  • 版本、模組資訊與工程文件持續補強

表面上看，這些工作有些像是修正細節、補文件、調整欄位、優化畫面；但從系統發展的角度來看，這些事情都指向同一個目標：

讓 CL3 從一套功能集合，逐步成長為一個真正可持續演進的平台。

一、本週的核心意義：讓 CL3 更像一個真正可維運的系統

CL3 目前的架構方向已經相當明確：

  • Core：負責資料抓取、計算、市場狀態判斷與快照寫入

  • PostgreSQL：作為單一資料真實來源（SSOT）

  • API / Dashboard：專注讀取與呈現，不直接改寫核心決策資料

  • Admin：負責標的管理、資料來源設定與維護流程

這個架構本身，不只是技術拆分，而是一種治理方式。

因為只要系統未來要持續擴張，不論是增加更多標的、更多 driver、更多說明頁、更多管理功能，最後都會回到兩個根本問題：

第一，資料是否可信。
第二，維護是否可控。

這一週的很多工作，正是在補這兩個基礎。

二、Dashboard 進展：從能顯示，到更清楚、更一致、更易理解

1. Telemetry 卡片切換功能完成

本週完成了 Dashboard 上 Telemetry 區塊的顯示開關功能，並加入 localStorage 持久化。

這代表使用者可以依自身偏好，決定是否顯示特定資訊卡片，而且重新整理頁面後仍能保留上次的選擇。
這是一個很實際的使用體驗升級。

對一個持續成長中的系統來說，畫面資訊只會越來越多。若沒有適當的資訊管理機制，介面就會逐漸失去可讀性。這次的調整，雖然規模不大，但本質上是在為未來的資訊擴充預留空間。

2. Header 顯示資訊更清楚

本週也針對 Dashboard Header 做了優化，包括：

  • Build 資訊顯示

  • 時區標示調整

  • 模組版本與更新資訊呈現

原先偏技術式、較不直觀的內容，逐步轉成更適合長期維護與判讀的形式。例如時區不再只是固定顯示 UTC，而是優先顯示實際後端帶入的時區，如 Asia/Taipei。

這類細節在一般網站中也許不是關鍵，但在金融與監控型系統中，時間資訊的表達是否清楚，會直接影響資料判讀與追蹤能力。

3. /explain 與 Dashboard 版型一致化方向持續推進

本週也開始處理說明頁與主 Dashboard 的版型一致性問題。

過去隨著迭代速度提高，不同頁面之間難免形成設計語言不一致的狀況。這並不稀奇，但若要往產品化前進，就必須逐步統一。

因此，本週已朝向下列方向收斂：

  • 統一主題樣式

  • 統一頁面結構

  • 統一語言切換邏輯

  • 讓 Help Center / Explain 頁更像整體產品的一部分

這種整理，不一定會立即增加功能數量，但會顯著提升整體感與專業感。

三、多語系架構開始落地：這不只是翻譯，而是產品邏輯的一部分

這週一個很重要的里程碑，是 CL3 不再只是停留在「未來要支援多語系」的概念，而是開始實際朝多語系架構推進。

這個轉折點，來自很真實的使用者反饋：
當介面逐步對外展示時，單語系的限制會立刻浮現。若未來 CL3 不只是自己用，而是需要給夥伴、團隊成員、投資人或合作方理解，那麼語言層就不能再是後補項目。

因此，本週開始整理：

  • Dashboard 主要欄位文字

  • Explain / Help Center 文案

  • Admin 的部分操作用語

  • 多語切換的基礎邏輯

這件事的價值，不只是「有中文、有英文」，而是讓系統未來具備更好的擴展性。

因為真正成熟的多語系，不是到處手動改字，而是從一開始就把文字層抽離、規則化、可維護化。這週雖然仍在初步推進階段，但方向已經很清楚，而且是正確的。

四、Admin 系統本週的關鍵推進：降低錯誤輸入，提升維護可控性

對 CL3 而言，Admin 並不只是後台頁面。
它本質上是整個資產治理與資料來源治理的入口。

如果 Admin 層沒有足夠的防呆與資訊透明，那麼後面的 Core、API、Dashboard 即使做得再完整，也仍然會因為錯誤主檔而失去可信度。

1. Driver / Source 資訊透明化

本週持續補強 Admin 資產編輯頁的資訊顯示，讓使用者不只是填寫欄位，而能更清楚理解：

  • 目前使用的是哪一個 driver

  • 這個標的來自哪個資料來源

  • 哪些欄位應該可改

  • 哪些欄位不應該任意修改

  • 模組與 driver 的資訊來自何處

這是一個很重要的轉變。
因為當管理介面從「單純表單」提升到「具備上下文的維護介面」，錯誤率就會明顯下降。

2. ALLIANZ create flow 問題持續修補

本週也針對 ALLIANZ 的建立流程持續修補，包括 catalog 匯入後 is_active=true 的一致性問題。

這類問題如果不處理，表面上看起來只是資料表中一個欄位狀態，但實際上會造成以下連鎖影響：

  • 新增後不顯示

  • 使用者誤以為新增失敗

  • 後續快照流程與前台顯示不一致

  • 維護信任感下降

所以這不是單純的資料修補，而是在處理整個系統的操作可信度。

3. 特殊 driver 專用 Picker 的方向確立

這週另一個重要決策，是更明確地確認：

像 ALLIANZ 這類特殊資料源，不應該依賴人工自由輸入 symbol 與 URL。

因此接下來的方向已經很清楚：

這是一個很關鍵的產品判斷。
因為自由輸入雖然彈性高，但長期來看，錯誤率也高；而受控輸入雖然前期需要多做一些設計，卻能大幅降低維護成本。

對 CL3 這種需要穩定、可信、可持續演進的系統而言，這條路是值得的。

五、資料來源治理開始成形：Driver 不再只是抓資料，而是一套規則

本週一個很深的體會是：
當 CL3 持續擴張之後，driver 已經不能只被視為「某段抓資料的程式」。

它其實是一套規則，一層治理邏輯。

例如：

ALLIANZ 類型標的的特性

  • 商品名稱長

  • share class 複雜

  • symbol 不適合靠人工自由命名

  • URL 與 source URL 概念容易混淆

  • 若沒有 catalog 支援，維護成本高、錯誤機率也高

YFINANCE 類型標的的特性

  • ticker 必須正確

  • 同名商品可能跨市場

  • symbol 格式需要驗證

  • 若查不到資料，不能只是默默接受，而應該給出明確錯誤

因此，本週已經把 driver 防呆這件事，從零散修補提升到結構化任務的層次。
這非常重要，因為這代表 CL3 正在從「資料抓得到就好」，進入「資料來源要能被治理」的階段。

六、版本管理與工程文件：這週不是只在寫功能，也在補未來的可追溯性

這週也持續強化版本管理、模組資訊顯示與文件紀律，包括：

  • App / Module / Driver 版本資訊呈現

  • Build / Updated metadata 顯示

  • CHANGELOG 補齊

  • 工作紀錄整理

  • VERSIONING 規範持續明確化

  • 模組或檔案 header 補上版本資訊

這些事情常常最容易被忽略，因為它們不會像新功能一樣立刻被看見。
但真正長期的系統，成本最高的往往不是「開發新功能」，而是「幾週後沒有人知道這個功能是何時、為何、在哪一版進來的」。

所以這週持續做的這些工程紀律工作，本質上是在保護未來的維護成本。

這不只是文件整理，而是在建立系統的歷史可追溯性。

七、DEV 到 STG 的交付流程：開始更清楚地把「開發完成」與「可交付」分開

本週也花了不少力氣處理 DEV 與 STG 間的同步、tag、patch、git apply、git restore、git pull 衝突等實務問題。

這些事情通常不會出現在產品展示裡，但對工程現場來說，它們非常真實。

因為一旦系統開始進入跨環境驗證，便會很清楚地發現：

  • 程式寫完，不等於功能真正完成

  • 功能完成，不等於可以穩定部署

  • 可以部署，不等於 STG 一定能順利同步

因此，本週也逐步整理出更清楚的交付意識：

  • 哪些步驟應在 DEV 執行

  • 哪些動作應在 STG 執行

  • 何時應 commit

  • 何時適合打 tag

  • 哪些本地修改必須先清掉

  • 哪些環境差異不能靠臨時手動修補來掩蓋

這些經驗雖然帶有不少摩擦成本，但它們其實是平台走向成熟必經的路。

八、本週遇到的真實挑戰

這一週的開發，不是單純一路往前衝，也同步暴露了一些很值得重視的現實問題。

1. 樣式層的歷史累積開始需要整理

隨著多輪快速迭代，像 admin.css、共用 layout、Dashboard / Explain 相關樣式，開始出現較高的維護壓力。

這並不代表前面的做法錯，而是系統已經走到需要「收斂樣式治理」的階段。

2. 模板路徑並存，容易誤改非實際生效檔案

像 api/templates/* 與 admin/templates/* 並存的情況，在快速開發中很常見。但一旦沒有先確認 route 實際掛載的是哪一份模板，就很容易出現「改了卻沒生效」的情況。

這提醒我們，未來在模板與前端資源治理上，還需要更進一步收斂。

3. STG 與 DEV 狀態不一致

這是本週最典型的現實問題之一。
尤其當某些問題曾在 STG 上做過手動修補、DB insert 或 update 時，如果源頭沒有回到 DEV 真正修正，後續就會反覆出現類似問題。

這也再次說明：臨時修復可以救急，但真正能降低成本的，永遠是源頭修正。

4. 功能若沒有同步補文件，很快就失去可追溯性

本週的工作再次證明，文件與版本並不是可有可無的附屬品。
只要變更沒有即時寫進 CHANGELOG、工作紀錄或版本資訊，幾天後就很容易失去脈絡。

九、本週的整體收穫：CL3 正從功能集合，逐步走向平台產品

若只看局部，本週好像做了很多「不夠炫」的事情：

  • 補翻譯

  • 改 Header

  • 補版本資訊

  • 修 Admin 流程

  • 調整樣式

  • 處理部署與同步問題

但若從系統發展的視角來看，本週真正重要的收穫其實是：

CL3 正在逐步具備平台產品該有的樣子。

一個真正可長期演進的系統，不是靠堆很多功能，而是靠這些更本質的能力：

  • 架構清楚

  • 資料可信

  • 介面可理解

  • 維護流程可複製

  • 錯誤不容易被悄悄掩蓋

  • 版本與歷史可追蹤

這一週做的事情，正是在打這些基礎。

十、下週方向

接下來，CL3 的下一步可以更聚焦在以下幾個方向：

1. 完成 Admin driver 防呆體驗

優先推進：

  • ALLIANZ catalog picker

  • YFINANCE ticker search / validate picker

讓資產建立流程從人工自由輸入，逐步轉向受控且可驗證的輸入方式。

2. 持續補齊多語系

先優先處理高頻區塊：

  • Dashboard 主要卡片與欄位

  • Assets 區塊

  • Admin 常用操作文案

  • Help Center / Explain 頁面內容

3. 強化 Help Center 與系統說明層

讓 CL3 不只是能跑，也能更清楚地對外說明：

  • 這套系統是什麼

  • 它如何運作

  • 它如何支援決策

  • 它與一般看盤工具的差異

4. 持續收斂 DEV → STG 交付流程

把版本、tag、更新步驟與驗證節點持續整理清楚，逐步降低交付摩擦成本。

結語：值得做的事，就值得把基礎打穩

這一週，不一定是最亮眼的一週，
但從 CL3 的長期發展來看，我認為這是一週很有價值的累積。

因為平台真正的力量，不是來自某個單一華麗功能，
而是來自每一次願意把基礎做對、把細節做穩、把結構拉直的選擇。

CL3 還在路上。
還有很多地方要補、要修、要整理、要升級。

但至少這一週，我們清楚地往前走了一步：

從能跑，走向可信；
從可用，走向可維護；
從工具，走向平台。

這條路不一定快，
但它會越走越穩。


留言

張貼留言

這個網誌中的熱門文章

戰未來十年！我的新家 3 層樓 10G 影音內網 + 全屋 Wi-Fi 7 實戰紀實《序章》

圖片
序章：為什麼我需要「 10G 」？ 當我拿到新家鑰匙的那一刻，我看著這棟三層樓的「中古屋」，心中浮現的不是沙發要擺哪裡，也不是牆要漆什麼顏色，而是一張巨大的網路拓樸圖。 搬新家，在 IT 術語中稱為「 Greenfield ( 綠地 ) 佈署 」。這是一張完美的白紙，是身為一個 Prosumer ( 專業消費者 ) 夢寐以求的「黃金施工期」。 這是我 唯一 的機會，可以在水泥封上之前，把未來 10 年的基礎建設一次到位。我知道，如果我現在妥協，未來 10 年的每一天，我都會活在「早知道 ... 」的悔恨中。 但真正的問題來了： 我真的需要「 10G 」嗎？ 迷思： 10G 網路 ＝ 10G 網際網路？ 在開始之前，我們必須釐清一個最大的迷思：我談的「 10G 」，指的 不是 向中華電信申請的「對外 (WAN) 網際網路」，而是指我家中設備互連的「 內部區域網路 (LAN) 」。 就算我申請了 2G/1G 的光世代，如果我的內網只有 1G (1Gbps) ，那就像是擁有一條 8 線道的高速公路，但終點卻是一個單線道的收費站。 而這個 1G 的收費站，就是我決心剷除的瓶頸。 1Gbps (110MB/s) 的天花板，我受夠了 1Gbps (Gigabit) 網路，換算成我們熟悉的下載速度，理論極限大約是 110-120 MB/s 。 這在 10 年前很夠用，但在 2025 年的今天，它代表什麼？ 代表我從主力電腦備份 500GB 的資料到 NAS ，需要 75 分鐘 。 代表我想在 QNAP TVS-h674 上剪輯 4K (ProRes) 影片，素材讀取會卡頓到讓我放棄。 代表我的 Plex 或 Jellyfin 媒體庫在同時應付 2-3 個 4K 藍光原盤 (Remux) 串流時，會開始緩衝。 代表我未來安裝的 Wi-Fi 7 AP (U7 Pro) ，它那 2.5G 的網路埠，會被 1G 的交換器活活掐死在 1G 。 1G 內網，已經從「基礎建設」淪為「效能枷鎖」。 驅動我的「 10G 之魂」：三大核心需求 我的需求不是「上上網、看看 Netflix 」而已，我追求的是一個高效、穩定、且安...
閱讀完整內容

Building CL3 — From Manual Trading to a Decision Engine

圖片
  Building CL3 為什麼我決定建立自己的 Investment Decision Engine 每一個投資人，最終都會面對同一個問題。 市場充滿不確定性、資訊噪音，以及難以預測的變化。 但隨著時間，我逐漸意識到一件更重要的事情： 真正困難的不是市場，而是決策。 多年以來，我和大多數投資人一樣參與市場。 看圖表（Charts） 閱讀新聞（News） 觀察價格變動（Price Movements） 然後依靠經驗做出投資判斷。 有時候這些判斷很成功。 但有時候並不如此。 慢慢地，我發現一個現象： 人的判斷其實並不穩定。 有些時候，我們可以非常理性與紀律。 但在其他時候，情緒（Emotion）、恐懼（Fear）、或市場壓力會干擾決策。 同一個投資人，在不同時間點，可能會做出完全不同的投資行為。 這讓我開始思考一個問題： 如果投資決策可以被系統化（Systematized），會是什麼樣子？ 不是一個黑箱的 Trading Bot 。 而是一個更有意義的東西： Investment Decision Engine 這個想法，就是 CL3 的起點 。 Why CL3? 有趣的是， CL3 這個名字並不是一開始就精心設計的品牌。 它其實來自一次意外。 當時我正在和 AI 討論投資相關的想法，在回覆訊息時，我忘記把鍵盤從 Zhuyin Input Method（中文注音輸入法） 切換回中文。 我敲下了三個鍵： C(ㄏ) L(ㄠ) 3(ˇ) 在注音輸入法中，這三個鍵其實會輸入一個中文字： 「好」 但在當時的對話情境中，AI 看到的只是： CL3 有趣的是，AI 並沒有把它當作錯字。 反而開始回應一段關於 CL3 系統架構與投資方法 的說明。 那一刻我突然覺得： 也許這不只是一次打錯字。 也許這可以成為一個專案名稱。 於是 CL3 就成為了我開始撰寫這個投資系統時使用的專案代號。 What CL3 Means 隨著系統逐漸發展，我發現這三個字母其實也可以代表整個系統的核心理念： CL3 = Cycle · Logic · Layer Cycle 市場總是在循環（Market Cycle）。 牛市（Bull Market）、修正（Correction）、風險收縮（Risk...
閱讀完整內容

戰未來十年！《第二章》魔鬼在細節 - 核心設備選型 (血淚史)

圖片
  這一章是 90% 的人（包含我）花費最多時間、也最容易後悔的地方。每一個決策都像是在十字路口，選錯了，未來的 10 年都會充滿遺憾。 這就是我的「選型血淚史」。 第二章：魔鬼在細節 - 核心設備選型 ( 血淚史 ) 如果「架構藍圖」是理想，那麼「設備選型」就是殘酷的現實。這是在「預算」、「效能」和「功能」之間進行的痛苦拔河。我的每一分錢都要花在刀口上，而這刀口，必須能劃開 10G 的頻寬。 ( 路由 ) 靈魂： UDM-SE (Dream Machine Special Edition) 網路的靈魂，就是路由器。它決定了你的網路有多穩、有多安全、有多「聰明」。 我的選擇是 UniFi Dream Machine Special Edition (UDM-SE) 。 為什麼是它？ UDM-SE 是一台「 All-in-One 」的怪物。在 1U 的機身裡，它整合了： 高效能路由器 (Router) ： 支援 10G 路由效能， VLAN 防火牆規則再多也不怕。 2.5G WAN 埠： 這是關鍵！它能 跑滿 中華電信 2G/1G 光世代。 10G SFP+ LAN 埠： 這是我的「 10G 骨幹」與核心交換器 (QSW-M2116P) 連接的命脈。 PoE+ 交換器： 內建 8 個 PoE 埠，其中 2 個還是 2.5G PoE+ ！ UniFi 控制器： 無需額外主機 (Cloud Key 或 N100 VM) ，它本身就是 UniFi 生態系的大腦。 【血淚史】 UDM-SE vs. UDM-Pro ：差點選錯的致命妥協 新手最常問：「 UDM-SE 和 UDM-Pro 到底差在哪？」 UDM-Pro (2019 年產品 ) 看似便宜了 $4,000 多元，但這 $4,000 是我認為「 最划算的升級 」，因為 Pro 版有兩個致命缺陷： WAN 瓶頸： UDM-Pro 的 WAN 埠只有 1G ！ 在 2025 年的今天，當中華電信 2G 方案已是常態，你買一台 1G WAN 的旗艦路由器？這等於是「 落地即過時 」。 UDM-SE...
閱讀完整內容