AI 與資料科學 / ENGINEERING NOTES
從技術筆記到可追溯的研究平台:TY 市場研究室開發紀錄
整理近期的 Astro SSR、圖表時間窗、多市場資料識別、研究證據管理、排程補跑與 TDD,記錄架構選擇、實作方式與驗證限制。
背景:讓資料、判斷與開發成果留下依據
TY 市場研究室的方向,是彙整市場資料與他人觀點,把自己的判斷記成資料,再透過圖表比較條件。對工程而言,重點是資料期間、來源、單位與證據都能追溯,也能解釋畫面上的數字如何產生。
本文依 2026 年 10 月 25 至 26 日更新的專案文件,整理近期實作。下文的歷史測試數量是原文件當次執行的結果,並非本文重新執行的全站驗收。本產品目前不宣稱提供策略回測、自動下單或獲利保證。
決策一:以 Astro SSR 保留可讀內容,互動功能按需載入
首頁採用可索引的繁體中文正文,並保留使用者既有的中英文偏好。市場說明與文字訊號可保留在伺服器 HTML,較長的輔助摘要以 details 收合,兼顧閱讀與不執行 JavaScript 的讀取工具。
互動圖表仍由 React、TypeScript 與 D3 處理;技能泡泡圖放進可展開區域,使用 client:visible 在可見時才載入。這個分工讓內容的可讀性與互動功能的載入時機可以分別控制。
SSR 專案也必須檢查 hydration:先看到標題和空 SVG,不代表 React 已經啟動。先確認 island runtime、SSR 標記與實際 DOM,再排查圖表邏輯。共用樣式則由版型集中掛載,降低重新整理後樣式漏載的風險。
決策二:把畫圖之前的資料規則抽成可測試模組
圖表不只是折線。月增率與年增率要分開比較;人數與百分比不能共用格式;有相同走勢的數量和占比應在同一讀數裡說明,避免重複圖表讓讀者以為存在不同訊號。
前端以獨立模組處理期間計算、序列對齊、欄位識別與數字格式,再交給畫面渲染。多線圖的線條、座標軸與讀數採一致顏色;不同單位使用各自的縱軸。
共用時間窗模組 chartViewport.ts 提供近一日、七日、一月、一年、五年與全部資料。時間窗以最後一筆已存觀測為基準,避免延遲公布的數據因「今天沒有資料」而變成空圖。五年按鈕只篩選已有歷史,不代表自動補齊五年來源資料。
股價圖可搭配本益比、存貨天數或營業利益率。財務資料須從公布時間起對齊;沒有實際公布日而採估計時,畫面要標示估計。這種比較不能直接當成 point-in-time 歷史回測。
決策三:用市場與代碼共同識別標的
不同交易所可能出現相同數字代碼。資料管線與前端都必須帶著市場識別,防止日本標的誤用台灣的籌碼、財報或歷史資料。
海外資料整合涉及 IBKR 行情,以及 J-Quants、SEC、DART 等財務來源。資料抓取時間和財務公布期間是兩個不同欄位;剛更新快取,不代表內容就是最新季度。
同樣地,帳戶資料與行情 session 也有不同生命週期。帳戶 API 有回應,不代表行情通道仍然連線。排程必須分別檢查,再決定是否等待補資料。
決策四:研究內容以證據台帳與版本維護
10 月 25 日的研究更新保留既有 JSON schema,涵蓋 21 份研究;文章與圖形區分官方披露、公司規劃、聚合資料與分析推論。
產業架構圖的箭頭代表功能或需求傳導,不能直接解讀為已證實的客戶供貨。產品展示、客戶驗證、量產、營收與現金回收也分屬不同階段。Mermaid subgraph 用來呈現並行方案,避免把多條技術路線誤畫成唯一的線性流程。
研究內容加入替代方案、反方、bull/base/bear 條件與可觀察追蹤項目;證據不足仍標為研究草稿。沒有已讀文件支持的量產或性能聲明應撤回,不以看似完整的圖掩蓋缺口。
更新由後端既有 startup seed 機制產生新版,只更新最後編輯者仍為 seed 的紀錄,保護人工編輯。前次文件記錄的驗證結果為後端 18 項、前端 168 項通過,並檢查 42 張 Mermaid 圖的解析;這不等於所有圖已完成瀏覽器視覺驗收。
決策五:排程要記住失敗與補跑,而不是一直重複觸發
市場分析依資料公布與交易時段排程。海外行情若因登入失效而落後,先記錄該次排程漏資料,等待使用者登入及行情收集完成後,再判斷是否補跑。
補跑需具備每次 session 的去重紀錄、最小間隔、資料到齊條件與明確狀態,例如等待行情、未設定、已觸發或失敗。新增自選標的也先補資料,再觸發分析;失敗應能在下次操作重試。
這些路徑在文件中已有實作,但補跑仍依賴正式環境觸發憑證。10 月 23 日文件記錄該憑證尚未設定,不能把程式完成寫成正式環境已自動補跑。
決策六:讓錯誤成為測試案例
開發流程採「錯誤先重現、修正再轉綠」。外部資料保留裁切且不含機密的 fixture,測試缺值、重複發布、時區、不同單位與真實期間。
純運算從大型 UI 檔案抽出,測試資料轉換與格式判斷;畫面驗收再檢查滑鼠、觸控、鍵盤讀數與窄螢幕。近期元件測試也處理 Vite 的 JSX 轉換設定,將 automatic runtime 配到目前使用的解析器。
聯繫流程同樣遵循這個原則:mailto: 在未設定郵件程式的電腦可能沒有可見反應,因此提供 Gmail、Outlook 網頁撰寫與複製內容選項。信件地址、主旨與範本集中在單一模組,並測試 URI 編碼和語言切換。
下一步:文章也使用可管理的內容生命週期
知識庫本次改版將文章正文、資訊、修訂與向量保存在 PostgreSQL,由 API 處理 Markdown 上傳、剪貼簿貼上、草稿、發布、下架與復原,前端在請求時讀取公開版本。這樣後續發文不必重新部署前端。
發布交易直接更新 Maya Sawa 查詢使用的正文,並清除過期向量;背景工作重新向量化,失敗則保留重試狀態。bucket 可另作附件或備份用途,本次不參與文章讀寫。
這項遷移的程式完成、資料庫驗證與正式切換是不同里程碑。切換前須核對既有文章數量、正文雜湊與原網址,停用舊的前端批次同步,並驗證草稿無法被匿名讀取。尚未完成的正式環境驗證,不會以文章措辭當作已完成。
本文整理依據
- 首頁搜尋與產品定位、SSR 正文、按需載入與聯繫流程:
HOME_SEARCH_POSITIONING.md,2026-10-26。 - 研究資料結構、證據台帳、種子資料保護與測試結果:
RESEARCH_UPDATE_2026-10-25.md。 - 圖表時間窗、財務公布日對齊與歷史資料限制:
CHART_INTERACTION_PLAN.md,2026-10-23。 - 排程權限範圍、補跑狀態與觸發設定限制:市場分析排程維護文件,2026-10-26。
以上為專案內部文件名稱,本文未包含私人報告、帳戶資料、金鑰或部署識別資訊。