入金變更指南
本頁說明
講什麼：PM 最常見的 10 種入金變更需求——每種告訴你改什麼、在哪改、影響什麼、找誰審批 適合誰：需要推動入金相關需求變更的產品經理 前置閱讀：入金方式總覽預計閱讀：5 分鐘 負責人：入金產品經理
核心要點：入金變更分為代碼常量、配置文件、資料庫、運營後台四類，不同類型的改動週期和影響鏈差異很大——改代碼需發版，改配置可能即時生效。
怎麼用這頁
當你有一個入金相關的需求變更時：
- 在下面找到對應的變更場景
- 看「配置類型」判斷改動難度和週期
- 看「影響鏈」評估風險
- 看「審批要求」確認找誰簽字
- 看「驗證方法」確認怎麼驗收
配置類型速查
| 類型 | 含義 | 生效方式 | 改動週期 |
|---|---|---|---|
| 代碼常量 | 寫死在 PHP/Go/Python 代碼中 | 需走發佈流程 | 1~3 天（含開發+測試+發佈） |
| 配置文件 | config/*.php 或 .env | 需走發佈流程 | 1~2 天 |
| 資料庫配置 | 存在 DB 配置表中 | 改完即時生效 | 當天 |
| 運營後台 | OA/CRM 後台可調 | 運營自行操作 | 即時 |
| Cron 配置 | 定時任務表達式 | 需運維部署 | 0.5~1 天 |
| 銀行側 | 需要銀行配合 | 走商務+技術對接 | 數週~數月 |
變更審批流程
無論哪種變更場景，都應遵循以下通用流程：
Staging 驗證通用指南
所有需要發佈的變更（代碼常量、配置文件類）都應在 Staging 環境驗證後再上線。
分步指南：如何在 Staging 驗證入金變更
前置條件：Staging 環境已部署最新代碼（含變更）
Step 1 — 準備測試數據
- 在 Staging 創建測試用戶（或使用現有測試帳號）
- 確認 Staging 的銀行 Mock 服務正常運行（Staging 不連真實銀行，用 Mock 模擬流水）
Step 2 — 觸發測試場景 3. 按變更類型準備不同的測試：
- 容差變更：構造差額恰好在新舊容差邊界的流水，驗證匹配行為變化
- 限額變更：構造金額恰好在新舊限額邊界的申請，驗證自動入賬判定
- 超時變更：創建申請後快進時間（修改 DB 時間），驗證通知和駁回觸發
- 風控變更：加/移黑名單後觸發入金，驗證 DepositType 標記
- 新銀行：端到端測試完整鏈路（Mock 流水 → 匹配 → 入賬）
Step 3 — 驗證結果 4. 檢查 DB 狀態（Apply/Flow/Task/Match 表）是否符合預期 5. 檢查通知是否正確觸發（Push/站內信） 6. 檢查對賬報告是否無異常
Step 4 — 記錄 7. 截圖/錄屏驗證結果 8. 在需求文檔中標註「Staging 已驗證」
場景一：調整某銀行的匹配容差
例：把匯豐的自動入賬容差從 HKD 65 調到 HKD 100
| 維度 | 說明 |
|---|---|
| 改什麼 | 對應銀行 Matcher 類中的容差常量 |
| 在哪改 | deposit/src/app/Business/Match/HsbcMatch.php（匯豐）、BocMatch.php（中銀）、HangSengMatch.php（恒生）、IcbcNewMatch.php（工銀）、DbsMatch.php（星展）、EwbMatch.php（東亞） |
| 配置類型 | 代碼常量 — 需發佈 |
| 影響鏈 | 容差放寬 → 更多流水進入自動匹配 → 誤匹配風險上升（金額相近的不同申請可能被錯配）→ 可能出現入錯賬。容差收緊 → 更多流水降級為輔助匹配 → 運營人工確認工作量增加 |
| 驗證方法 | 發佈前：拉 1 週該銀行的歷史流水，用新容差模擬回測匹配結果。發佈後：觀察該銀行的「自動匹配率」和「輔助匹配量」變化 |
| 審批要求 | 產品確認 + 運營知曉（工作量可能變化） |
| 回滾 | 1. 恢復原容差常量 → 重新發佈（~1小時） 2. 已經被新容差錯誤匹配的入金需逐筆檢查 3. 如發現誤匹配 → 走沖正流程（沖正指引） |
容差調整的核心風險
容差每放寬 1 元，理論上都會增加「金額相近的不同申請被錯配」的概率。尤其當同一銀行有多個用戶同時申請相近金額時。必須先用歷史數據回測再上線。
當前各銀行容差 → 入金規則速查 § 匹配容差
場景二：調整自動入賬限額
例：把 HKD 自動入賬上限從 200 萬調到 500 萬
| 維度 | 說明 |
|---|---|
| 改什麼 | DepositConfigNew 中的幣種限額常量 |
| 在哪改 | deposit/src/app/Business/DepositConfigNew.php |
| 配置類型 | 代碼常量 — 需發佈 |
| 影響鏈 | 限額調高 → 更多大額入金走自動通道 → 減少運營工作量，但大額異常入金也可能自動放行。限額調低 → 更多入金需人工確認 → 運營工作量增加，但安全性更高 |
| 驗證方法 | 發佈後觀察「需人工確認的入金佔比」變化 |
| 審批要求 | 風控團隊簽字（必須）+ 產品確認 + 運營知曉 |
| 回滾 | 1. 恢復原限額常量 → 重新發佈（~1小時） 2. 檢查變更期間是否有超原限額的入金被自動處理 3. 如有異常大額 → 聯合風控團隊逐筆審核 |
當前限額
HKD 2,000,000 / USD 300,000 / CNH 2,000,000 / JPY 40,000,000 / SGD 350,000。 完整表 → 入金規則速查 § 幣種限額
場景三：修改超時天數
例：把 FPS 的通知天數從 1 天改為 2 天
| 維度 | 說明 |
|---|---|
| 改什麼 | 超時配置（通知天數、駁回天數） |
| 在哪改 | deposit/src/app/Business/DepositConfigNew.php — 超時配置區 |
| 配置類型 | 代碼常量 — 需發佈 |
| 影響鏈 | 通知天數延長 → 用戶等待更久才收到提醒 → 可能導致更多「錢沒到」投訴。通知天數縮短 → 正常但較慢的銀行轉賬可能被過早通知 → 用戶困惑 |
| 特殊注意 | 天數按 HKEX 交易日計算（排除週末和公眾假期）。修改只影響新申請，不影響已有申請的超時計算 |
| 驗證方法 | 發佈後創建測試申請，等待超時通知觸發 |
| 審批要求 | 產品確認 |
| 回滾 | 恢復原天數，重新發佈 |
當前超時配置 → 入金規則速查 § 超時配置
場景四：調整 2412 暫停窗口
例：把 16:05~16:10 的暫停窗口改為 16:00~16:15
| 維度 | 說明 |
|---|---|
| 改什麼 | 2412 暫停窗口的起止時間 |
| 在哪改 | deposit/src/app/Business/DepositConfigNew.php:603-641 |
| 配置類型 | 代碼常量 — 需發佈 |
| 影響鏈 | 窗口擴大 → 更多入金在暫停期間降級為輔助匹配 → 運營工作量增加，但對賬安全性更高。窗口縮小 → 對賬期間可能有自動入金在執行 → 可能導致帳戶餘額不一致 |
| 為什麼不能隨便改 | 2412 窗口是為了確保港股開盤/收盤時的帳戶對賬不被資金變動干擾。窗口起止時間與交易所的開盤前結算和收盤後結算時間對齊。如果縮短窗口，可能出現「對賬瞬間帳戶餘額被入金改變」的情況，導致賬務不平 |
| 驗證方法 | 聯合清算團隊驗證對賬報告無差異 |
| 審批要求 | 清算團隊簽字（必須）+ 產品確認 |
| 回滾 | 恢復原窗口，重新發佈 |
場景五：修改風控規則
例：把某用戶加入/移出黑名單
| 維度 | 說明 |
|---|---|
| 改什麼 | 黑名單/白名單數據 |
| 在哪改 | hk-deposit-blacklist-go / hk-deposit-whitelist-go 服務的管理介面 |
| 配置類型 | 資料庫配置 — 改完即時生效 |
| 影響鏈 | 加入黑名單 → 該用戶所有後續入金自動標記為 HIGH_RISK(5) → 需人工審核才能入賬。移出黑名單 → 該用戶恢復正常自動入賬。黑名單支持設置過期時間（臨時觀察） |
| 特殊注意 | 黑名單影響入金環節。如果用戶已有申請正在匹配中，黑名單在下一個匹配週期（3 分鐘內）生效。已經完成入賬的不受影響 |
| 驗證方法 | 加入後觸發一筆測試入金，確認 deposit_type 被標記為 5 |
| 審批要求 | 風控團隊簽字（必須） |
| 回滾 | 從黑名單移除，即時生效 |
場景六：調整匹配引擎頻率
例：把匹配引擎從每 3 分鐘改為每 1 分鐘
| 維度 | 說明 |
|---|---|
| 改什麼 | 匹配 Cron 任務的執行頻率 |
| 在哪改 | deposit/doc/crontab.sh 中各 match:* 任務的 cron 表達式 |
| 配置類型 | Cron 配置 — 需運維部署 |
| 影響鏈 | 頻率提高 → 用戶感知的入金速度更快。但資料庫查詢頻率成比例增加 → 可能影響 DB 性能，尤其是流水量大的銀行（中銀、匯豐） |
| 為什麼當前是 3 分鐘 | 在當前日均流水量下，3 分鐘是「用戶體驗」和「資料庫負載」的平衡點。匹配引擎每次運行需掃描 flows 和 applys 表中所有待處理記錄（status=0），頻率越高掃描越頻繁。如果某銀行日均只有幾十條流水，提頻意義不大；如果日均數千條，提頻會帶來顯著的 DB 壓力 |
| 驗證方法 | 先在壓測環境驗證 DB 負載變化；灰度期間監控 DB 慢查詢告警 |
| 審批要求 | 技術負責人確認（DB 負載評估）+ 產品確認 |
| 回滾 | 恢復原 cron 表達式，重新部署 |
場景七：新增銀行入金通道
例：接入一家新銀行（如大新銀行）的 Push 模式入金
這是最複雜的變更場景，涉及多個服務和配置。
開發清單
| 步驟 | 工作內容 | 涉及服務/文件 |
|---|---|---|
| 1 | 分配 TransType 代碼 | deposit/proto/server/cash_deposit.proto — 在枚舉中加新值 |
| 2 | 開發流水採集服務 | 新建 Go/Python 服務（參考 dbs_service 或 icbc_be_relay） |
| 3 | 實現 Matcher 類 | deposit/src/app/Business/Match/ 下新建 XxxMatch.php，繼承 MatchBase |
| 4 | 配置匹配 Cron 任務 | deposit/doc/crontab.sh 加 match:xxx 每 3 分鐘 |
| 5 | 配置容差和時間窗口 | 在 Matcher 類中定義（參考同類銀行） |
| 6 | 配置超時天數 | DepositConfigNew.php 按入金方式設置 |
| 7 | 前端入金方式展示 | App 入金頁面配置新方式可見性 |
| 8 | 對賬配置 | bank_reconciliation 任務中加新銀行 |
| 9 | 聯調測試 | 端到端測試：流水採集 → 匹配 → 入賬 → 對賬 |
前置條件
| 條件 | 說明 | 負責方 |
|---|---|---|
| 銀行技術對接協議 | 確定流水獲取方式（API/文件/Webhook） | 商務 + 技術 |
| 公司收款帳戶 | 在該銀行開設企業收款帳戶 | 財務 |
| 銀行卡識別規則 | BIN 號段識別，用於前端展示和匹配 | bankcard_service |
審批要求
商務團隊（銀行合作）+ 技術負責人 + 產品確認
參考工期
| 流水接入方式 | 參考工期 | 參考 |
|---|---|---|
| API 即時推送 | 3~4 週 | 參考渣打 scb_service |
| API 定時拉取 | 2~3 週 | 參考工銀 icbc_be_relay |
| 文件批量拉取 | 4~6 週 | 參考中銀 bochk_flow_go（最複雜） |
任務依賴與並行度
新銀行接入的 9 個步驟並非全部串行。以下是依賴關係和可並行的工作：
可並行的工作（綠色標註）：
- 步驟 2（流水採集）、3（Matcher）、6（超時配置）、7（前端展示）可以同時進行
- 步驟 4（Cron）和 5（容差/窗口）依賴 2 和 3，但可以在 2/3 完成後並行
- 步驟 9（聯調）是最終匯合點，依賴所有其他步驟
關鍵路徑：前置條件 → TransType → 流水採集服務 → 聯調測試。流水採集服務的開發通常是耗時最長的環節。
回滾策略
新銀行上線後如需回滾：
- 關閉前端展示（用戶看不到該銀行入金方式）→ 立即生效
- 停止
match:{bank}Cron 任務 → 新流水不再匹配 - 停止流水採集服務 → 不再接收新流水
- 已經入金的不受影響，無需沖正
場景八：新增 eDDA 支持銀行
例：想讓星展銀行也支持 eDDA 入金
結論：短期不可行，需評估銀行側支持情況。
| 前置條件 | 說明 | 可控性 |
|---|---|---|
| 銀行支持 eDDA 協議 | 銀行需在 HKMA 的 FPS 體系中實現 eDDA 功能 | 完全取決於銀行 |
| 商務合作簽約 | 銀行同意為 moomoo 開通 eDDA 代扣權限 | 需商務談判 |
| 技術對接 | 對接銀行的 eDDA/eDDI API（每家實現不同） | 預計 4~8 週 |
| SBA 編排服務 | 新建 sba_xxx_eddi 編排服務 | 參考 sba_hsbc_eddi |
| deposit 服務適配 | Eddi.php 中加新銀行分支 | 1~2 週 |
為什麼當前只有匯豐和恒生？ eDDA 是 HKMA（香港金管局）FPS 體系的一部分。雖然技術標準是統一的，但每家銀行的 API 實現、審核流程、商務條件各不相同。當前只有匯豐和恒生完成了全部對接（商務簽約 + 技術聯調 + 生產上線）。
如果真的要推進：第一步是聯繫銀行關係團隊，確認目標銀行是否支持 eDDA 協議，再評估商務和技術工作量。
場景九：新增幣種支持
例：新增 GBP（英鎊）入金
| 步驟 | 工作內容 | 涉及文件 |
|---|---|---|
| 1 | Proto 定義 | deposit/proto/server/cash_deposit.proto — 加 Currency 枚舉 |
| 2 | 容差配置 | 各 Matcher 類中加 GBP 容差（參考與 HKD 的匯率折算） |
| 3 | 限額配置 | DepositConfigNew.php — 加 GBP 自動入賬限額 |
| 4 | 超時配置 | DepositConfigNew.php — 加 GBP 超時天數 |
| 5 | 前端展示 | 入金頁面幣種選擇器加 GBP |
| 6 | SBA 配置 | SBA 系統支持 GBP 餘額帳戶 |
| 7 | 對賬 | 新增 GBP 對賬任務 |
前置條件：公司在收款銀行需有 GBP 帳戶。並非所有銀行都支持所有幣種——需先確認哪些銀行可收 GBP。
審批要求：產品確認 + 清算團隊確認 + 技術負責人
場景十：修改入金通知邏輯
例：入金成功後的推送通知文案要改
| 維度 | 說明 |
|---|---|
| 改什麼 | 通知文案和觸發邏輯 |
| 在哪改 | 通知服務配置（非 deposit 服務管轄，deposit 只負責發通知事件） |
| 配置類型 | 取決於通知服務的實現——通常是配置文件或資料庫 |
| 影響鏈 | 文案修改僅影響用戶端展示；觸發邏輯修改可能影響通知時機和頻率 |
| 特殊注意 | 入金系統定義了 4 種通知類型碼（普通入金=1、線上開戶綁卡=2、綁卡後入金=3、大陸預開戶=4），通知的具體文案和渠道（Push/SMS/站內信）由通知服務控制 |
| 驗證方法 | 測試環境觸發一筆入金，確認通知內容和渠道 |
| 審批要求 | 產品確認 |
場景十一：修改沖正流程
例：沖正前增加二次審批 / 沖正後不自動解綁銀行卡
| 維度 | 說明 |
|---|---|
| 改什麼 | 入金沖正的執行邏輯、前置校驗、後置操作 |
| 在哪改 | deposit/src/app/Business/Deposit.php:877-935（入金沖正 reverse() 方法） |
| 配置類型 | 代碼常量 — 需發佈 |
| 影響鏈 | 沖正流程修改直接影響已完成入金的資金撤回能力。修改前置校驗可能導致應沖的沖不了；修改後置操作可能遺漏解綁/通知步驟 |
| 驗證方法 | Staging 環境創建測試入金 → 完成入賬 → 執行沖正 → 驗證 Apply.status=5、SBA Procedure 成功、銀行卡解綁狀態、通知觸發 |
| 審批要求 | 風控團隊簽字（必須）+ 產品確認 + 運營知曉 |
| 回滾 | 恢復原代碼 → 重新發佈。已被新邏輯處理的沖正不受影響（沖正不可撤銷） |
常見變更場景：
| 變更 | 改動位置 | 注意事項 |
|---|---|---|
| 沖正前增加審批步驟 | reverse() 方法入口處添加審批檢查 | 當前沖正是直接執行、無二次審批。增加審批會延長沖正時效 |
| 沖正後不自動解綁銀行卡 | reverse() 中的解綁邏輯 | 不解綁可能導致下次入金仍然走綁卡通道 |
| 增加沖正金額上限 | reverse() 前置校驗 | 超限的沖正需升級審批（如大額走主管審批） |
| 修改沖正通知模板 | 通知服務消息模板配置 | 不在 deposit 服務管轄內 |
| 批量沖正限制 | /deposit/batch 介面 | 當前無批量數量限制，可加上防誤操作 |
相關代碼位置
- 入金沖正：
deposit/src/app/Business/Deposit.php:877-935—reverse()核心邏輯 - SBA 反向：
deposit/src/app/Business/SOA/SBA/Deposit.php:309—turnAround('CashDepositReverse') - 沖正中間件：
deposit/src/app/Business/Tasks/Deposit.php:276-287 - 出金沖正（參考）：
withdraw/src/app/Business/Tasks/Handler/Reverse.php
退款機制產品說明 → 退款與沖正 運營沖正操作手冊 → 沖正/退款指引
變更風險矩陣
| 變更 | 技術風險 | 業務風險 | 改動週期 | 建議灰度方式 |
|---|---|---|---|---|
| 調整容差 | 低 | 高（誤匹配） | 1~3 天 | 先用歷史數據回測 |
| 調整限額 | 低 | 高（大額異常） | 1~3 天 | 按銀行分批調整 |
| 修改超時 | 低 | 中 | 1~3 天 | 按銀行分批調整 |
| 調整 2412 | 低 | 高（對賬異常） | 1~3 天 | 不建議灰度，必須全量驗證 |
| 風控規則 | 低 | 中 | 即時 | 按用戶粒度操作 |
| 匹配頻率 | 中（DB 負載） | 低 | 0.5~1 天 | 按銀行逐步提頻 |
| 新增銀行 | 高 | 中 | 3~6 週 | 新銀行獨立上線 |
| 新增 eDDA | 高 | 低 | 數月 | 新銀行獨立上線 |
| 新增幣種 | 中 | 低 | 2~3 週 | 按幣種逐步開放 |
| 修改通知 | 低 | 低 | 1~2 天 | 灰度推送 |
| 修改沖正流程 | 中 | 高（資金安全） | 1~3 天 | 必須全量驗證 |
讀完之後
| 我想... | 去看 |
|---|---|
| 理解 10 種入金方式的全景 | 入金方式總覽 |
| 看匹配容差和限額的詳細規則 | 匹配與自動入賬 |
| 查某個參數的具體數值 | 入金規則速查 |
| 了解 eDDA 協議和錯誤碼 | eDDA 代扣入金 |
| 看出金側有什麼變更場景 | 出金變更指南 |
| 了解退款和沖正機制 | 退款與沖正 |