基金五線譜投資管理平台 — 功能增修與系統優化 交付成果報告書

---

1. 摘要（Executive Summary）

本期工作以「讓網頁系統忠實對應原始 Excel 投資管理邏輯、並擴充其能力」為核心，完成兩大方向的交付：

• 新功能：

1. 贖回損益管理與 Excel 一鍵匯入——提供完整的贖回明細、幣別彙總與新增／編輯能力，並可一鍵將原始 Excel 的贖回紀錄與個股要點摘要匯入系統。
2. 基富通全基金總覽與前端自訂篩選——將基金清單由原本固定的「不配息＋成立三年」子集，擴充為全市場 4,788 檔基金，並提供前端多維度自訂篩選，保留原有排序、視覺化圖表與 Excel 匯出能力；該頁正式定名為「基金篩選器」。
3. 我的最愛（基金收藏）——可於基金篩選器一鍵收藏基金，並於專屬的「我的最愛」頁面集中檢視與管理；收藏資料持久化於系統資料庫。
4. 基金對應（基富通 ↔ Yahoo）——以可搜尋下拉建立基富通基金與 Yahoo 基金的對應關係，串接平台的兩個資料來源，並提供已對應清單管理。
5. 基金詳情線圖增強——線圖顯示全部歷史、五線譜實線／價格虛線、四條均線各自獨立開關，並提供 TradingView 式的每線顏色／粗細／線型自訂。

• 系統優化：

1. 五線譜技術指標與 Excel 規格對齊——精準校準標準分數、乖離率、移動平均、市場狀態判定與回歸視窗，使系統計算結果與客戶長期沿用的 Excel 一致。
2. 持倉、同步、API、快取與介面資料真實性的全面精進。
3. 效能優化——「個股要點」清單端點消除重複查詢與過量傳輸；資料庫啟用並行模式。

同時，以程式化方式（而非人工抄錄）完整記錄四個原始 Excel 工作簿的欄位、公式、巨集與業務邏輯，交付 8 份技術文件與可長期維護的任務清單。所有變更均通過自動化測試與真實資料驗證，並完整保存於版本控制。

---

2. 專案背景與系統定位

本系統是一套「基金五線譜投資管理平台」的網頁化實作，其業務邏輯源自客戶長期使用的一套 Excel 工作簿（基富投資1.xlsx，含 69 張工作表）。該 Excel 以「五線譜（曾氏通道）」為核心方法，對每一檔基金的歷史淨值做線性回歸與常態分配分析，輔以移動平均、乖離率、技術指標與一套人工決策規則（加碼／贖回／轉換），管理一個含 56 檔在投基金、260 筆贖回紀錄的實際投資組合。

系統採前後端分離架構：

• 後端：Python（FastAPI）+ SQLite，負責淨值抓取（台灣 Yahoo 股市）、五線譜指標計算、基金與快照儲存、基富通基金清單查詢。
• 前端：React + TypeScript，呈現個股要點總表、基金詳情五線譜圖、贖回損益、市場指數、基金篩選器等。

本期工作的訴求為「完整對應 Excel 業務邏輯、擴充基金總覽能力、並提升系統效能與資料真實性」。

---

3. 工作範圍與作業方法

3.1 範圍

3.2 作業方法

• Excel 邏輯抽取（程式化，非人工）：撰寫專用解析腳本，直接讀取工作表 XML，還原每一欄的公式（含 shared formula 的列／欄平移、陣列公式）、條件格式、資料驗證下拉字彙、圖表系列與 VBA 巨集；對 57 張個別基金表逐欄比對，確保無遺漏、無抄錄誤差。兩個原已損壞的 Excel 檔另以還原程序救回可讀副本。

• 程式碼對照：逐檔閱讀後端與前端原始碼，建立 schema、公式、資料流的精確對照，並與 Excel 抽取結果交叉驗證。

• 實作與驗證：每項交付皆以後端單元測試（27 項）、前端正式版建置、以及對真實 Excel 工作簿與真實資料庫副本的實測，確認正確性與不破壞既有資料。

---

4. 交付成果總覽

---

5. 新功能

5.1 贖回損益管理與 Excel 一鍵匯入

• 完整贖回損益管理：提供贖回明細表（依序號、可搜尋、可篩幣別）、幣別彙總卡（累計贖回金額／損益、筆數），以及新增與編輯能力；資料持久化於資料庫，呈現結果與原始 Excel「贖回損益」工作表一致。
• Excel 一鍵匯入：於介面點選即可讀取原始 基富投資1 工作簿，將贖回紀錄與個股要點的成本／市值摘要匯入系統（符合客戶「以介面操作、不需命令列」之偏好）。匯入機制針對實務情況強化：支援複雜與重複的表頭、簡體欄名（「单位成本」「收益率 %」）、以無評等記號表示的星數，以及大型工作簿的高速處理（實測約 4.4 秒）。
• 資料來源透明：後端可用時以資料庫為準；後端離線時退回示範資料並明確標示「唯讀」，避免使用者誤判。
• 驗證：對真實工作簿匯入 260 筆贖回紀錄、56 檔基金摘要；幣別彙總（台幣累計贖回 24,180,695、美金 2,179,686.69、台幣損益 3,647,386、美金損益 29,645.4）與 Excel 原表彙總區逐一數值一致。

5.2 基富通全基金總覽與前端自訂篩選

• 背景與需求：原系統僅抓取「不配息且成立滿三年」之固定子集；本期擴充為「抓取全市場全部基金、把資訊一次取齊，由前端自行篩選」。
• 後端：新增基金總覽抓取模組，以無篩選方式分頁掃完基富通全部基金、去重後存入資料庫；抓取以背景作業進行並回報進度（全市場約 240 頁、耗時約 1 至 2 分鐘）。新增「取得全清單／觸發更新／查詢進度」三個端點。資料儲存於資料庫，兼顧效能與部署穩定。
• 前端：將清單頁定名為「基金篩選器」，新增篩選列——配息（全部／不配息／配息）、計價幣別、風險評等 RR、晨星星等、基金公司、成立年數、近一年報酬門檻；原有的排序、統計卡、多種視覺化圖表與 Excel 匯出能力全部保留，並內建「不配息·3 年」一鍵還原舊視圖。
• 外部來源穩定性：基富通官網偶發的暫時性連線問題，已加入自動重試機制因應（維持憑證驗證，不降低安全性）。
• 驗證：全市場實測抓取——基富通宣告 4,788 檔，去重後入庫 4,787 檔，耗時約 72 秒，自資料庫回讀正確；幣別與配息分布合理（美元 2,094、新台幣 1,020、歐元 597…；不配息 2,819、配息／其他 1,968）。

5.3 我的最愛（基金收藏）

• 收藏與取消收藏：在「基金篩選器」的基金清單中，每一列右側提供星號按鈕；點選即可將該基金加入「我的最愛」，再次點選則移除。操作即時反映（樂觀更新），並同步寫入後端。
• 我的最愛專屬頁面：新增「我的最愛」頁，集中列出所有已收藏的基金，呈現基金名稱、代碼、基金公司、配息資訊、近一年／三年／五年報酬、夏普值、晨星評等、風險評等與計價幣別；支援關鍵字搜尋、可於頁面內直接移除，並於主導覽列新增入口。
• 資料持久化：收藏清單儲存於系統資料庫（以基金代碼為唯一鍵、重複加入自動去重），重新整理或更換瀏覽器後仍保留。
• 驗證：收藏 API 實測（加入、列出、移除、去重）皆正確；收藏清單依加入時間新到舊呈現。

5.4 基金對應（基富通 ↔ Yahoo）

• 需求背景：平台同時使用兩個基金資料來源——Yahoo（提供已追蹤基金的淨值與五線譜）與基富通（提供全市場基金清單）。為串接兩者，需建立「哪一檔基富通基金對應哪一檔 Yahoo 基金」的對應關係。
• 新增對應：於「基金對應」頁，分別以可搜尋下拉選取一檔基富通基金與一檔 Yahoo 基金，按「建立對應」即完成；基富通端為伺服端即時搜尋（代碼／名稱／公司），Yahoo 端則於已追蹤基金清單中過濾。
• 已對應清單：頁面下方即時列出所有已建立的對應（基富通基金 → Yahoo 基金，含名稱與代碼），可隨時移除。
• 資料持久化：對應關係儲存於系統資料庫，以基富通代號為主鍵（同一檔基富通基金重新對應時自動更新）。
• 驗證：對應 API 實測（搜尋、建立、覆蓋更新、移除、欄位檢核）皆正確。

5.5 基金詳情線圖增強（彈性自訂）

• 顯示全部歷史：移除原本的時間區間切換（90 日／半年／1 年／2 年），線圖一律顯示全部可用歷史（最多為同步抓取的 900 筆，與 Excel 主圖一致）。
• 線型對齊習慣：五線譜五條界線改為實線、價格線改為黑色粗虛線，貼近客戶於 Excel 的視覺習慣。
• 各均線獨立開關：EMA5、EMA20、MA50、MA120 改為各自獨立的顯示開關（不再 EMA 一組、MA 一組）。
• TradingView 式自訂：新增「線圖設定」彈出視窗，每一條線皆可自訂顏色、粗細、線型（實線／虛線／點線）與顯示與否，並提供「還原預設」；設定記憶於瀏覽器，下次開啟沿用。圖例亦可一鍵快速開關各線。
• 驗證：前端正式版建置通過。

---

6. 系統優化

6.1 五線譜技術指標與 Excel 規格對齊（精準度）

精準校準下列指標，使系統計算與客戶長期沿用的 Excel 結果一致：

• SD 落點值：採用 (現價 − 趨勢線) / 標準差 的標準分數（z 值）定義。
• 乖離率：採 (現價 − EMA20) / 現價 之定義與方向。
• 移動平均種子：EMA5、EMA20 之起算採 Excel 規則（EMA5 取前 6 筆平均、EMA20 取前 20 筆平均後再遞迴）。
• 市場狀態判定：納入 EMA20 修正盤整狀態（多頭但 EMA20 跌破 MA50 → 多-橫向整理；空頭但 EMA20 站上 MA50 → 空-橫向整理）。
• 回歸視窗筆數：依 Excel「基金程式規格」採 900 筆（新基金取全部）。

上述對齊確保「落區、SD 落點、市場現狀、加減碼判斷」與 Excel 一致。並以客戶 Excel 的實際淨值序列回測驗證：趨勢線、標準差與四條樂觀／悲觀界線與 Excel 計算值一致到小數第 8 位（差異約 1e-8，僅為常態分配反函數的近似誤差）。

6.2 持倉與損益呈現（資料真實性）

• 以真實資料為準的三級呈現：有真實單位數時計算市值；否則採 Excel 匯入之市值摘要；皆無則明確標示為未知，避免以推估值充當真實持倉。
• 成本口徑明確：在尚無逐筆交易帳本前，庫存成本以投入本金為基礎；單位成本優先採用 Excel 匯入值，呈現結果貼近實務帳務。

6.3 資料同步穩定性

• 既有資料保護：外部淨值來源暫時不可用時，保留既有快照與圖表資料、僅記錄狀態，使單次失敗不影響已同步內容。
• 自動重試：對外部來源加入指數退避重試，提升大批抓取的成功率。
• 視窗對齊：背景同步之淨值視窗對齊 Excel 規格（900 筆）。

6.4 API 與快取機制

• 查詢式端點：新增 GET /api/funds/by-yahoo?code=...，妥善支援含冒號的基金代碼。
• 快取新鮮度：調整磁碟快取為 10 分鐘新鮮度、逾時自動重抓，並保留前次結果作為來源失敗時的備援。
• 資料一致性：啟用資料庫外鍵約束，維持基金與快照的關聯完整。

6.5 個股要點清單效能

• 單次查詢取代逐筆查詢：清單端點改為單次 JOIN 一次取回（原本對每檔基金各發一次查詢）。
• 回應輕量化：清單回應不再附帶完整的五線譜序列（完整序列改於進入「基金詳情」時才載入），大幅降低資料庫解析量與網路傳輸量。
• 驗證：功能實測各欄數值正確（如參考市值＝單位數×淨值），完整序列已不再隨清單傳輸。

6.6 資料庫並行（WAL）

資料庫連線啟用 WAL 並行模式並設定鎖等待，使「讀不擋寫、寫不擋讀」；背景同步在寫入時，前端讀取不再受阻。

6.7 介面資料真實性

• 帳戶總覽與贖回彙總改由實際資料庫資料呈現；移除與帳戶無關的裝飾性數據。
• 市場指數模組於介面明確標示資料性質，避免被誤認為即時行情。

關於資料庫選型的專業意見

針對客戶詢問「是否改用 PostgreSQL 以提升速度」，已提供評估：以目前資料規模（數千列）而言，SQLite 並非效能瓶頸，真正的延遲來自外部 API 抓取與清單查詢方式（皆已優化）。PostgreSQL 真正值得導入的時機是「多實例並行寫入」與「雲端部署資料持久化」，屬部署架構決策，與速度無關，建議依實際部署規劃再評估。

---

7. 品質保證與驗證紀錄

---

本報告基於 commit 1b3b257、bfcda7f、fe2c727、bcc81ba 之實際內容撰寫，所載驗證數據均為本期實測結果。