天星银证概览
天星银证（Airstar Bank-Securities Transfer）是富途与天星银行合作的直连银证转账服务，属于"互信开户二期"核心功能。客户在 moomoo APP 内授权后，可实时从天星银行账户转入证券账户（入金），或反向转出（出金），全程免费，最快5分钟到账。
系统标识
BANK_ID = 55
TransType=304 · Method=10(bstAsb) · 银行代码008
支持币种
HKD / USD / CNH
CNH无限额是天星独家优势
到账时间
5 分钟
交易日服务时间内，单笔<1000万
卡号格式
12 位数字
非传统16-19位，天星银行特有
核心能力
| 能力 | 状态 | 说明 |
|---|---|---|
| BST 银证入金/出金 | 支持 | 双向发起（moomoo端 + 银行端） |
| Mandate 授权 | 支持 | 6状态机，一次授权覆盖HK/US/CN三市场 |
| 线上开户 | 支持 | 三合一：开户+授权+首笔入金 |
| CNH 全面支持 | 独家 | CNH无限额，招行/民生不支持或受限 |
| eDDA 代扣 | 支持 | 单笔HKD 200K，日5笔/HKD 1M |
| FPS 转数快 | 不支持 | |
| FUTU发起取消银证 | 接口已对接 | 本期不做 |
双向发起模型（天星独有）
| 操作 | FUTU→银行 | 银行→FUTU |
|---|---|---|
| 授权银证 | 支持 | 支持 |
| 取消银证 | 本期不做 | 支持 |
| 入金 | 支持 source=1 | 支持 source=2 |
| 出金 | 支持 | 支持 |
| 入金退款 | FUTU发起 | 不接受 |
| 出金退款 | 不发起 | 接受 |
系统架构
服务架构
| 组件 | 技术栈 | 职责 |
|---|---|---|
airstar_service | Go | 天星银证核心：授权、入金、出金、退款 |
bank-card | PHP | 银行卡管理，存储授权状态 |
cash_service | PHP | 资金服务（含HSBC eDDA参考） |
sba_deposit_system | Python | 入金流水处理 |
withdraw | PHP | 出金相关 |
队列驱动状态机
天星银证核心设计是队列驱动的异步状态机。每个操作通过队列推进：
授权队列 (queue_auth)
new→
set_card_processing→
send_bank_req→
query_bank→
update_card_result→
notice_user→
success/fail
入金队列 (queue_deposit)
new→
notify_bank_approval→
query_transfer→
write_flow→
success
出金队列 (queue_withdraw)
new→
notify_bank_approval→
query_transfer→
write_flow→
success
数据库关键表
| 表 | 用途 | 关键字段 |
|---|---|---|
auth_info | 授权最终结果 | cid, bank_card_number, mandate_id, auth_result |
auth_proc | 授权过程跟踪 | status, fail_code, fail_reason |
deposit_proc | 入金交易跟踪 | ref_id, bank_ref_id, amount, currency, status |
withdraw_proc | 出金交易跟踪 | ref_id, bank_ref_id, amount, currency, status |
bank_request | 银行来请求 | type(auth/cancel/deposit/withdraw), payload |
biz_log | 业务审计日志 | 所有状态变更的JSON记录 |
id_card_type 字段为 varchar，无需数据库迁移即可新增证件类型。
银行对比矩阵
BST 三家银行对比
| 维度 | 招行 CMB | 民生 MS | 天星 Airstar |
|---|---|---|---|
| 协议 | SM2加密 Socket二进制 | SM2加密 Socket XML | REST API + RSA-OAEP |
| 通信模式 | Socket推送(实时) | Socket推送(实时) | HTTP轮询(分钟级) |
| 核心标识 | 银行卡号 | 银行卡号 | mandate_id |
| 授权模型 | 银证签约(2状态) | 银证签约(2状态) | Mandate授权(6状态) |
| CNH支持 | 受限 | 无 | 全面支持(无限额) |
| 处理时段 | 08:40-15:59 | 08:40-15:59 | 08:30-15:59 |
| 退款机制 | 无 | 无 | REFUNDED状态 |
| 线上开户 | 不支持 | 不支持 | 三合一(开户+授权+入金) |
| 发起方 | 单向(FUTU发起) | 单向(FUTU发起) | 双向 |
| 代码语言 | Python | Python | Go |
13家银行能力矩阵
| 银行 | BST | eDDA | FPS | 网银 | 入金份额 |
|---|---|---|---|---|---|
| 汇丰 HSBC | - | ✓ | ✓ | ✓ | 72% |
| 天星 Airstar | ✓ | ✓ | - | - | - |
| 招行 CMB | ✓ | - | - | - | - |
| 民生 MS | ✓ | - | - | - | - |
| 恒生 HangSeng | - | ✓ | ✓ | ✓ | - |
| 中银 BOCHK | - | - | ✓ | ✓ | - |
| 渣打 SCB | - | - | ✓ | ✓ | - |
| 广发 CGB | - | - | ✓ | - | - |
| 工银 ICBC | - | - | - | ✓ | 12.3% |
授权流程
Mandate 6状态机
NEW→
PendingAuthorise→
Authorised→
Active (OPEN)
RejectAuthorise
Revoked
授权表单字段
| 字段 | 来源 | 编辑规则 |
|---|---|---|
| 银行 | 固定：天星银行 | 不可编辑 |
| 银行代码 | 固定：008 | 不可编辑 |
| 银行账户号码 | 读取当前银行卡号预填充 | 已授权eDDA→不可编辑；未授权→可编辑 |
| 账户姓名 | 取账户英文名 | 可选择姓名顺序 |
| 证件类型 | 优先级：HKID → CNID → MOID | 如有多套证件可切换 |
| 证件号码 | 从cert表预填充 | 有证件信息时不可编辑 |
| 手机号 | 预填充证券手机号 | 仅可选+852/+86，可编辑 |
授权结果处理
同一ID多UID规则：只允许1个UID存在银证授权关系。银行发起授权时若识别到多个账户，需客户选择1个。
银行卡管理页状态
| 状态 | 显示 | 可操作 |
|---|---|---|
| 未授权银证 + 未授权eDDA | 仅显示银行卡信息 | 可授权、可删除 |
| 银证授权中 | "授权处理中，约1-2个工作日通知" | 不可删除 |
| 银证已授权 | 显示"已开通"标签 | 可操作 |
| 银证授权失败 | 显示失败原因，支持重新授权 | 推送消息通知 |
| 银证+eDDA均已授权 | 双标签全开 | 可操作 |
对账
- 每日0点拉取天星的授权列表
- 任何状态 vs 银行返回"授权/未授权" → 按结果更新
- 任何状态 vs "客户不存在/卡号不存在" → 按未授权处理
入金流程
入金体验参数
| 参数 | 值 |
|---|---|
| 线上开户最低入金 | HKD 10,000 / USD 1,500 / CNH 10,000 |
| 普通入金最低 | 无最低要求（>0即可） |
| 前端最大输入 | 99,999,999,999（约千亿） |
| 费用 | 免费 |
| 通道限额 | 无上限（限额由银行侧控制） |
到账时效
| 场景 | 到账时间 |
|---|---|
| 交易日 08:00-18:15，单笔 < 1000万 | 5分钟 |
| 交易日 08:00-15:55，单笔 ≥ 1000万 | 2小时内 |
| 其他时段 | 下个交易日 08:10前 |
入金状态值
| 状态 | 终态 | 说明 |
|---|---|---|
| new | 否 | 新建 |
| pending | 否 | 处理中 |
| success | 是 | 入金成功 |
| failed | 是 | 入金失败（资金从未到账） |
| refunded | 是 | 已退款（天星独有，到账后被退回） |
入金前置校验
| 校验项 | 拦截文案 |
|---|---|
| 是否授权天星银证 | 弹窗：未授权银证，请授权成功后发起入金 |
| 是否被风控限制 | 弹窗：账户异常，无法发起入金 |
| 不动账户/休眠户 | 弹窗：休眠户,不支持入金 |
| 第三方存款检测 | 发现第三方存款退回至转出账户 |
15:55 分界点
结单规则：15:55前入金算当日结单，之后算下一个交易日。
计息规则：15:55前归还欠款当日停息。
入金切日：与综合账户切T时间对齐。
计息规则：15:55前归还欠款当日停息。
入金切日：与综合账户切T时间对齐。
出金流程
核心原则
先扣钱，后转账。三步模式：冻结 → 转账 → 释放（防负余额）
出金前置校验
| 校验项 | 拦截文案 |
|---|---|
| 是否授权天星银证 | 未授权银证，请授权成功后发起 |
| 风控限制 | 账户异常，无法发起出金 |
| 不动/休眠户 | 休眠户,不支持出金 |
| 银行账户未认证 | 银行账户还未通过认证 |
| 币种不匹配 | 币种不匹配 |
| Payoneer账户 | 暂不支持出金至Payoneer账户 |
| 波多黎各地区 | 暂不支持出金至高风险地区 |
| 账户穿仓 | 账户存在欠款,无法发起出金 |
| 未完成GDCA | 未完成GDCA,不支持发起出金 |
出金通道优先级
BST银证(推荐)→
网银/FPS→
手动通道
BST仅占9%出金量，但运营成本最低（全自动）。同行转账占73%。
退款与冲正
REFUNDED 状态（天星独有）
REFUNDED ≠ FAILED
FAILED：银行拒绝，资金从未到账。
REFUNDED：已到账后被退回，需执行冲正操作。
FAILED：银行拒绝，资金从未到账。
REFUNDED：已到账后被退回，需执行冲正操作。
触发场景
- 银行反欺诈检测
- 合规部门要求
- 用户投诉
- 系统错误
冲正流程
系统自动执行冲正。若用户已消费该资金导致余额不足，冲正失败需人工处理。
退款规则
| 类型 | FUTU发起 | 银行发起 |
|---|---|---|
| 入金退款 | FUTU发起 | 不接受 |
| 出金退款 | 不发起 | 接受 |
限额体系
出金三层限额
| 币种 | 单笔上限 | 累计报警 | 每日熔断 |
|---|---|---|---|
| HKD | 3,000,000 | 40,000,000 | 15,000,000 |
| USD | 500,000 | 10,000,000 | 3,000,000 |
| CNH | 无限制（天星独家优势） | ||
熔断触发时自动关闭当日该币种自动出金，需次日恢复或人工处理。
入金限额
| 场景 | HKD | USD | CNH |
|---|---|---|---|
| 线上开户最低入金 | 10,000 | 1,500 | 10,000 |
| 普通入金最低 | 无限制（>0即可） | ||
| 通道上限 | 无限额（银行侧控制） | ||
| 自动入金上限 | 2,000,000 | 300,000 | 2,000,000 |
eDDA限额（天星）
| 维度 | 限制 |
|---|---|
| 单笔 | HKD 200,000 |
| 日累计笔数 | 5笔 |
| 日累计金额 | HKD 1,000,000 |
新卡审核触发阈值
| 币种 | 阈值 | 说明 |
|---|---|---|
| HKD | 1,000,000 | 超过触发额外审核（非限额） |
| USD | 150,000 | 超过触发额外审核（非限额） |
| CNH | 1,000,000 | 超过触发额外审核（非限额） |
系统级BST上限
| 维度 | 值 |
|---|---|
| 全币种单笔上限 | 10,000,000,000（系统保护） |
| 每日最大笔数 | 50笔 |
| 每日自动入金 | 10笔/用户 |
处理时段
| 通道 | 开始 | 结束 | 备注 |
|---|---|---|---|
| 天星BST | 08:30 | 15:59 | 比招行/民生提前10分钟 |
| 招行/民生BST | 08:40 | 15:59 | |
| 标准HKD处理 | 07:00 | 次日04:00 | |
| USD处理 | 09:01 | - | 避免清算冲突 |
| 周末HKD | - | 09:55 |
暂停窗口：08:55~09:00 和 16:05~16:10（系统对账期间暂停处理）
到账时效矩阵
| 时段 | 金额 | 到账 |
|---|---|---|
| 交易日 08:00-18:15 | < 1000万 | 5分钟 |
| 交易日 08:00-15:55 | ≥ 1000万 | 2小时内 |
| 其他（非交易日/非服务时段） | 任意 | 下个交易日08:10前 |
自动出金条件
AUTO_SETTING_ID = 3，需同时满足以下全部条件：
| # | 条件 | 说明 |
|---|---|---|
| 1 | Mandate状态 = OPEN | 授权必须激活 |
| 2 | 账户正常 | 非冻结/销户 |
| 3 | 不在黑名单 | |
| 4 | 单笔不超限 | HKD≤300万 / USD≤50万 |
| 5 | 每日不熔断 | 当日累计未触发熔断线 |
| 6 | 交易时段内 | 08:30-15:59 |
| 7 | 风险等级 ≤ Level 2 | 天星侧风控通过 |
任一条件不满足则进入人工审批流程（confirm→remittance）。
风控等级
| 等级 | 动作 | 说明 |
|---|---|---|
| Level 0-2 | APPROVE | 低风险，自动放行 |
| Level 3 | MANUAL | 中风险，转人工审核 |
| Level 4 | REJECT | 高风险，自动拒绝 |
| 特殊 | VERIFY | 需额外身份验证 |
风险等级是自动出金的前置条件，由天星银行侧风控系统判定。
通信协议
| 属性 | 值 |
|---|---|
| 协议类型 | HTTP REST API |
| 数据格式 | JSON |
| 加密方式 | RSA-OAEP（SHA1，200字节分块，Base64编码） |
| 签名方式 | RSA/HMAC |
| 密钥格式 | PKCS8 |
| 通信模式 | 轮询（Polling）— 非推送 |
| 幂等性 | request_id（16-50字符）保证 |
银行侧接口清单（11个REST API）
| 分类 | 接口 | 路径 |
|---|---|---|
| 授权 | CreateAuth | /authorization/apply |
| QueryAuth | /authorization/status | |
| CancelAuth | /authorization/cancel | |
| NotifyAuthResult | /authorization/result | |
| 入金 | CreateTransfer | /transfer/init (direction=deposit) |
| QueryTransfer | /transfer/status (direction=deposit) | |
| 出金退款 | CreateWithdrawRefund | /transfer/withdraw/reversal |
| QueryRefund | /transfer/withdraw/reversal/status | |
| 账户 | QuerySecAccount | /account/info |
| NotifyDepositApproval | /transfer/approval |
轮询机制
| 场景 | Job名称 | 最大次数 | 超时处理 |
|---|---|---|---|
| 入金创建结果 | AsbBstCreateResultJob | 60次 | 人工确认银行状态 |
| 出金转账结果 | AsbBstTransfer | 10次 | 进入兜底流程 |
| 出金兜底同步 | SyncAsbBstWithdraw | 2小时窗口 | 人工处理 |
轮询超时 ≠ 交易失败，不可直接判定为失败，必须人工确认银行侧真实状态。
定时任务
| 任务 | 频率 | 职责 |
|---|---|---|
| TransferCheck | 每分钟 | 检查入金/出金是否超时，重新入队 |
| DailyAuthCheck | 每小时 | 检查授权任务是否卡住 |
| BalanceQuery | 每小时 | 查询银行账户余额 |
| DailyTransferCheck | 每小时 | 检查转账状态一致性 |
证件类型映射
当前支持（个人户）
| 证件 | Proto枚举 | 发给银行的编码 | 格式校验 |
|---|---|---|---|
| 香港身份证 | HKID (1) | HKID | ^[A-Za-z]{1,2}\d{6}[0-9A]$ + 括号格式 |
| 内地身份证 | CNID (2) | MCVID | 18位标准校验 |
待新增（扩展）
| 证件 | Proto枚举 | 发给银行的编码 | 格式校验 |
|---|---|---|---|
| 澳门身份证 | MOID (3) | BIR（待确认） | 8位数字 或 含括号10字符 |
| 商业登记证 BR | 待定 | 待定 | ^\d{8}$ |
| 注册成立证书 CR | 待定 | 待定 | ^\d{7,8}$ |
| 海外公司注册号 | 待定 | 待定 | ^[A-Za-z0-9\-/.]{1,30}$ |
统一证件枚举 (customer_enum.proto)
| 枚举值 | 名称 |
|---|---|
| 22 | MacauPermanentID（澳门永久身份证） |
| 23 | MacauID（澳门非永久身份证） |
| 1006 | MacauTravelDocument（澳门旅行证件） |
| 1013 | CompanyRegistrationCertificate（注册成立证书） |
| 1042 | BusinessRegistrationCert（商业登记证） |
| 1043 | OtherFormalRegistrationDoc（其他正式注册文件） |
代码结构
关键文件位置
| 文件 | 职责 |
|---|---|
proto/airstar_service.proto | IDCardType枚举、请求响应定义、白名单校验 |
internal/app/enum/idtype/idtype.go | CNID↔MCVID映射，ToBankIdType/ToFutuIdType |
internal/app/validate/validate.go | ValidateCreateAuth()、ValidateCreateDeposit() |
internal/app/utils/idcard/idcard.go | HKID括号格式化 |
internal/app/apis/asb/adapter/bankreq/auth.go | 银行请求适配，双证件处理 |
internal/app/biz/asb_biz/auth.go | 授权业务逻辑，ToFutuIdType调用 |
proto/bank_req.proto | 银行协议定义，id_type1/id_type2 |
internal/app/enum/constant.go | AsbBankID=55 |
doc/init-new.sql | DB schema，id_card_type varchar无需迁移 |
conf/conf.toml | 银行账号、代理、队列、定时任务配置 |
天星银行账号（SIT环境）
| 币种 | 银行账号 |
|---|---|
| HKD | 860000001150 |
| CNH | 867000001179 |
| USD | 861000001180 |
机构客户银证（进行中）
进度：约60%完成，等待天星银行产品反馈授权校验字段。
预期上线：待天星反馈后完成剩余授权模块。
预期上线：待天星反馈后完成剩余授权模块。
核心差异（vs 个人版）
| 维度 | 个人版 | 机构版 |
|---|---|---|
| 证件类型 | HKID / CNID | 商业登记证(BR) / 公司注册证(CI) |
| 同名校验 | 个人姓名匹配 | 企业名称匹配（中英文/繁简体容错） |
| 授权状态 | 5种 | 6种（新增"企业审批中"） |
| CRM | 现有tab | 新增"企业审批中"子tab |
已完成交付物
- PRD文档 V2（飞书 150 blocks）
- APP原型（12个交互页面）
- CRM原型（v2重写中）
澳门访港客户银证（PRD审查中）
目标上线：2026年7月初
当前状态：PRD v1.0已输出，两轮审查后仍有3个高优阻塞项
当前状态：PRD v1.0已输出，两轮审查后仍有3个高优阻塞项
关键改动
- Proto新增 MOID=3，白名单扩展为 {HKID, CNID, MOID}
- idtype.go 加 MOID常量，ToBankIdType映射 MOID→BIR
- validate.go 加澳门身份证校验（8位纯数字 或 含括号10字符）
- 手机号支持 +853 前缀
高优阻塞项（🔴）
| # | 问题 | 状态 |
|---|---|---|
| P1 | BIR类型银行侧未确认 | 阻塞 5月中旬前必须锁定 |
| P2 | "复用eDDA校验"约等于没有校验（仅长度≤10） | 需明确正则 |
| P3 | bank_req.proto双证件id_type1/id_type2逻辑未说明 | 需确认 |
证件预填充规则（6种组合）
| 富途开户证件 | 预填 |
|---|---|
| 内地身份证 + 澳门非永久ID | 内地身份证 |
| 内地护照&澳门签证 + 澳门非永久ID | 澳门身份证 |
| 香港永久ID + 澳门非永久ID | 香港身份证 |
| 澳门永久ID + 香港非永久ID | 香港身份证 |
| 澳门永久ID（单证件） | 澳门身份证 |
| 澳门非永久ID（单证件） | 澳门身份证 |
CRM操作
入口
银行账户 → 银行账户授权 → 天星香港银证转账
Tab结构
| Tab | 子Tab | 列 |
|---|---|---|
| 开通银证 | 处理中 | 客户姓名/牛牛号/银行名称/银行账号/授权协议号/银行证件资料/当前耗时/发起时间 |
| 已开通 | + 完成时间 + 处理结果 | |
| 开通失败 | + 完成时间 + 处理结果(红色) | |
| 关闭银证 | - | 客户姓名/牛牛号/银行名称/银行账号/授权协议号/总耗时/发起时间/完成时间 |
复用策略
复用招商银证现有任务流，新增字段"授权协议号"（仅授权成功时天星返回）。
异常处理
授权异常（5类）
| 异常 | 处理 |
|---|---|
| 授权停在PROCESSING | 等待银行审核（1-2个工作日） |
| 授权FAIL（姓名/证件不匹配） | 核实信息后重新授权 |
| 授权CANCEL（用户主动） | 正常流程 |
| 部分市场映射失败 | 人工排查 |
| CancelAuth失败 | 联系天星技术支持 |
入金异常（7类）
| 异常 | 严重程度 | 处理 |
|---|---|---|
| 创建失败 | 中 | 查fail_code |
| 轮询60次超时 | 中 | 人工确认银行状态 |
| 入金失败 | 中 | 查fail_code和fail_reason |
| 入金退款(REFUNDED) | 严重 | 立即冲正 |
| 冲正余额不足 | 严重 | 人工处理 |
| 银行端入金未同步 | 中 | 等SyncJob拉取 |
| 重复入金 | 中 | 幂等性保护(request_id) |
出金异常（5类）
| 异常 | 严重程度 | 处理 |
|---|---|---|
| 出金指令失败 | 中 | 释放冻结，通知用户 |
| 10次轮询超时 | 中 | 进入2h兜底 |
| 2h兜底超时 | 严重 | 人工确认银行状态 |
| 冻结未释放 | 严重 | 手动释放 |
| 银行端出金未同步 | 中 | SyncAsbBstWithdraw处理 |
常见客诉 Top 3
- "余额不足无法入金" → 核实天星银行账户余额
- "授权一直处理中" → 银行审核通常1-2个工作日
- "入金成功后资金被退回" → REFUNDED状态，解释银行合规原因
监控告警
最严重的4项告警
| 告警 | 级别 | 处理 |
|---|---|---|
| 入金退款(REFUNDED) | 严重 | 立即冲正 |
| 出金兜底超时 | 严重 | 人工确认银行状态 |
| 冻结未释放 | 严重 | 手动释放 |
| API连通性异常 | 严重 | 联系天星技术支持 |
错误码映射
| 错误码 | 含义 | 对客文案 |
|---|---|---|
| 140630003 | 超出银证转账额度 | 超出银行银证转账的额度，请联系银行调整限额 |
| 140630004 | 单笔超银行限额 | 单笔转账金额超过银行限额，请联系银行调整限额 |
| 140630005 | 余额不足 | 银行账户余额不足 |
| 140630006 | 金额有误 | 转账金额有误，请重新输入 |
| 140630007 | 卡号错误 | 银行账户号码错误，请联系在线客服了解详情 |
| 140630008 | 姓名不一致 | 账户姓名与银行登记的信息不一致 |
| 140670010 | 新卡入金不足 | 在线开户用户新绑卡，入金金额不能低于10000 HKD |
| 140670011 | 新卡出金条件 | 在线开户用户新绑卡，尚未入金超过10000 HKD |
数据来源：hk-funds-docs.pages.dev · airstar_service代码库 · 互信二期PRD · 项目审查记录
生成时间：2026-04-30 · 基于 Claude Opus 4.6