2026-03-31-report

#Insurance Expert 專案概況報告
**報告日期：** 2026-03-31
**資料來源：** master 主線（截至 2026-03-31 最新合併）
\

一、專案基本資訊

| 項目 | 說明 |
|------|------|
| **專案名稱** | Insurance Expert（河馬保險系統） |
| **程式碼託管** | GitLab (`gitlab.com/money-master-backend/insurance-expert`) |
| **專案起始** | 2017-11-27 |
| **技術棧** | Java (JDK 8) / Spring MVC / JSP / Vue.js |
| **資料庫** | SQL Server |
| **累計 commits** | ~6,340 筆 |
| **目前穩定版本** | **v1.70.0.0**（2026-03-31 合併至 master） |
\

二、專案架構

專案為多模組 Java Web 應用，位於 `source/trunk/` 下：

| 子模組 | 檔案數 | 說明 |
|--------|--------|------|
| **InsuranceExpert** | 2,758 | 前端網頁應用（Landing Page、客戶入口） |
| **InsuranceExpertAdmin** | 1,535 | 後台管理系統（Prompt 管理、會員管理等） |
| **InsuranceExpertAp** | ~401 | 排程 / 背景作業（Batch Jobs、OCR 服務、API 呼叫） |
| **InsuranceExpertApi** | ~964 | API 服務層（主要 REST API、AI 聊天、SSE 串流） |

主要 package 結構：`batch`、`config`、`dao`、`dto`、`model`、`service`（含 `service/ai`、`service/ocr`）、`util`
\

三、開發團隊

| 成員 | 主要貢獻領域 |
|------|-------------|
| **Kai Lee** | 架構主導、AI 多模型、OCR 系統、排程、前端任務、Landing Page） |
| **Kevin Lin** | 保單業務邏輯、DAO 層、AI 保費/保障表排程 |
| **Jeff** | LLM 工具服務、AI 額度查詢 API、訂單系統 |
| **Jason Ou** | AI功能增強|

歷史貢獻者還包括 ted_chu、frankwmm、charlotte.chung、denny.lin 等。
\

四、版本發佈歷程（近期）

| 版本 | 合併日期 | 主要內容 |
|------|---------|---------|
| **v1.68.0.0** | 2025-12-04 | OpenAI API 整合、AI metadata 追蹤 |
| **v1.68.1.0** | 2025-12-23 | AI metadata 完整收集、AI 功能強化 |
| **v1.69.0.0** | 2025-12-30 | AI Chat 優化、AI 使用額度系統、LLM 工具重構 |
| **v1.69.0.1** (hotfix) | 2026-01-27 | AI 保費/保障排程多執行緒、重試機制、NPE 修復 |
| **v1.69.x.x** (hotfix) | 2026-02-23 | 排程 timeout、執行緒安全、BatchJob 權限驗證 |
| **v1.69.2.0** | 2026-03-25 | Landing Page 粒子背景、企業夥伴新增、附件大小限制 |
| **v1.70.0.0** | **2026-03-31** | **多模型供應商支援、OCR API 完整實作、建置環境升級** |
\

五、v1.70.0.0 新版本重點（65 筆 commit）

1. 多模型供應商支援（feat/multi-model-provider）

AI 聊天系統從原本僅支援 OpenAI，擴展為**多模型架構**以便測試，但正式環境還是採單一模型架構：

• **新增模型**：Gemini 3 Flash Preview、Gemini 3.1 Flash-Lite Preview、GPT-5.4-mini、GPT-5.4-nano\
• **Gemini 原生 API**：完整支援 Function Calling 和推理模式（thinking_level 自動映射）
• **OpenAI Responses API**：新增 `OpenAiResponsesStreamingModel` 支援 GPT-5.4 推理+工具
• **架構重構**：抽取 `AbstractSseStreamingModel` 基底類別（Template Method 模式），模型判斷邏輯集中至 `ModelConfigService`
• **資源管理**：修復資源洩漏、OkHttpClient 共用、裸線程改為 ThreadPoolExecutor
• **Jackson 衝突修復**：移除類別載入衝突，修復 AI SSE 串流功能

2. OCR API 完整實作（feat/ocr-api-implement）

保單 OCR 辨識系統從原型到完整上線：

• **IE_S_103**：OCR 原始值轉換為系統單位 mappedFields（欄位對應）
• **IE_S_105**：回傳 errorCode 供前端判斷 OCR 失敗類型
• **IE_S_108**：切換商品後重新計算 mappedFields API
• **非同步流程**：對齊新版 OCR API，原生非同步、即時進度追蹤、錯誤碼映射
• **效能優化**：快取 DB/API 查詢、enrichContractMappedFields 移至儲存時執行
• **中文數字對照**：支援壹貳參…拾等大寫中文數字寫法變體

• **錯誤處理強化**：FAILED 狀態正確標記、業務錯誤捕獲、JWT/登入/上傳防護
  \

六、近期重大功能總覽（2025-08 ~ 2026-03）

| 功能 | 時間 | 狀態 |
|------|------|------|
| AI 智能助理（SSE 聊天 + Function Calling） | 2025-08 ~ 持續 | ✅ 已上線，持續迭代 |
| Prompt 管理後台（DB 驅動 + 版本控管） | 2025-09 | ✅ 已上線 |
| AI Testing Dashboard | 2025-08 ~ 09 | ✅ 已上線 |
| AI 使用額度限制（日/月週期） | 2025-12 | ✅ 已上線 |
| 訂單 API（IE_S_99/100/101） | 2025-11 ~ 12 | ✅ 已上線 |
| AI 保費/保障表排程（多執行緒） | 2026-01 | ✅ 已上線 |
| Landing Page 粒子動態背景 | 2026-02 ~ 03 | ✅ 已上線 |
| **多模型供應商（Gemini + GPT-5.4 系列）** | **2026-03** | **✅ v1.70 上線** |
| **OCR 保單辨識 API（IE_S_102~108）** | **2026-02 ~ 03** | **✅ v1.70 上線** |
| 信安商品 LLM 配對 | 進行中 | 🔧 開發中 |
\

七、進行中的工作（尚未合併至 master）

| 分支 | 說明 |
|------|------|
| **feat/shinAn-llm-matching** | 信安商品 LLM 配對功能（目前開發中） |
| feat/change-plan-update | 方案變更功能更新 |
| feat/llm-as-judge-evaluation | LLM-as-Judge 評估機制 |
\

八、近半年開發節奏

| 月份 | Commits | 備註 |
|------|---------|------|
| 2025-08 | 33 | AI Testing Dashboard、監控系統 |
| 2025-09 | 62 | Prompt 管理系統、推理模式架構 |
| 2025-10 | 6 | 穩定維護期 |
| 2025-11 | 23 | 訂單 API、AI metadata 追蹤 |
| 2025-12 | 44 | AI 額度系統、v1.68/v1.69 發佈 |
| 2026-01 | 20 | AI 排程系統（保費/保障表） |
| 2026-02 | 9 | Landing Page 改版、OCR 開發啟動 |
| **2026-03** | **52** | **v1.70 發佈（多模型 + OCR），本月最活躍** |
\

九、技術債與值得注意的項目

1. **多處 NPE 已修復**：1 月密集修復了 PolicyService、AttachService 等空指標例外
2. **執行緒安全**：SimpleDateFormat 共用問題已修、裸線程已改 ThreadPoolExecutor
3. **精度問題**：Float 計算保費已改為 BigDecimal
4. **Jackson 衝突**：v1.70 修復了類別載入衝突問題
5. **JDK 8 限定**：專案仍限定 JDK 8，無法使用較新 Java 語法
6. **測試基礎設施**：v1.70 進行了 JUnit 5 遷移，測試環境改善中
7. **SQL Server**：migration 腳本分散在多處，尚無統一的 migration 框架