券商设置 Domain

概述

券商设置用于管理不同券商的配置信息，包括认证信息、API配置等，以便于后续拉取数据和交易时完成鉴权。每个用户可以有多个券商配置。

数据模型

Broker (券商)

class Broker(BaseModel):
    id: str                      # 券商ID
    name: str                    # 券商名称
    code: str                    # 券商代码
    type: BrokerType            # 券商类型 (longport | other)
    status: BrokerStatus        # 状态 (active | inactive)
    config: BrokerConfig        # 券商配置
    user_id: str                # 所属用户ID
    created_at: datetime        # 创建时间
    updated_at: datetime        # 更新时间

BrokerConfig (券商配置)

class BrokerConfig(BaseModel):
    config: dict                # 券商配置JSON（通用配置）
    fee_config: FeeConfig       # 交易费用配置

FeeConfig (交易费用配置)

class FeeConfig(BaseModel):
    us_fees: USFeeConfig        # 美股费用配置
    hk_fees: HKFeeConfig        # 港股费用配置

USFeeConfig (美股费用配置)

class USFeeConfig(BaseModel):
    # 平台费用
    platform_fee_per_share: Decimal = 0.005      # 平台费 0.005美元/股
    platform_fee_minimum: Decimal = 1.0          # 最低收取1美元
    
    # 交易活动费用 (仅在卖出时收取)
    activity_fee_per_share: Decimal = 0.000166   # 交易活动费用 0.000166美元/股
    activity_fee_maximum: Decimal = 8.3          # 最高8.3美元
    
    # 交收费
    clearing_fee_per_share: Decimal = 0.003      # 交收费 0.003美元/股
    clearing_fee_max_pct: Decimal = 0.07         # 最高收取交易额7%
    
    # 综合审计费
    audit_fee_per_share: Decimal = 0.000046      # 综合审计费 0.000046美元/股
    audit_fee_minimum: Decimal = 0.01            # 每笔订单最低0.01美元

HKFeeConfig (港股费用配置)

class HKFeeConfig(BaseModel):
    # 平台费用
    platform_fee_per_share: Decimal = 0.005      # 平台费 0.005港元/股
    platform_fee_minimum: Decimal = 1.0          # 最低收取1港元
    
    # 交易活动费用 (仅在卖出时收取)
    activity_fee_per_share: Decimal = 0.000166   # 交易活动费用 0.000166港元/股
    activity_fee_maximum: Decimal = 8.3          # 最高8.3港元
    
    # 交收费
    clearing_fee_per_share: Decimal = 0.003      # 交收费 0.003港元/股
    clearing_fee_max_pct: Decimal = 0.07         # 最高收取交易额7%
    
    # 综合审计费
    audit_fee_per_share: Decimal = 0.000046      # 综合审计费 0.000046港元/股
    audit_fee_minimum: Decimal = 0.01            # 每笔订单最低0.01港元

BrokerType (券商类型枚举)

class BrokerType(str, Enum):
    LONGPORT = "longport"        # 长桥券商
    OTHER = "other"             # 其他券商

BrokerStatus (券商状态枚举)

class BrokerStatus(str, Enum):
    ACTIVE = "active"           # 激活状态
    INACTIVE = "inactive"       # 非激活状态

DataSource (数据源)

class DataSource(BaseModel):
    id: str                      # 数据源ID
    name: str                    # 数据源名称
    type: DataSourceType         # 数据源类型 (longport | other)
    broker_id: str               # 关联券商ID
    status: DataSourceStatus     # 状态 (active | inactive)
    priority: int                # 优先级（数字越小优先级越高）
    created_at: datetime         # 创建时间
    updated_at: datetime         # 更新时间

DataSourceType (数据源类型枚举)

class DataSourceType(str, Enum):
    LONGPORT = "longport"        # 长桥数据源
    OTHER = "other"             # 其他数据源

DataSourceStatus (数据源状态枚举)

class DataSourceStatus(str, Enum):
    ACTIVE = "active"           # 激活状态
    INACTIVE = "inactive"       # 非激活状态

业务规则

券商管理

1. 每个券商有唯一的代码标识
2. 券商配置信息加密存储
3. 支持启用/禁用券商
4. 券商删除前需要检查是否有关联的数据源

交易费用管理

1. 每个券商配置包含美股和港股的费用配置
2. 费用配置在交易会话启动时传递给策略模块和模拟交易模块
3. 费用计算规则：
   • 平台费：按股数计算，有最低收费标准
   • 交易活动费：仅在卖出时收取，按股数计算，有最高收费上限
   • 交收费：按股数计算，最高收取交易额的一定百分比
   • 综合审计费：按股数计算，每笔订单有最低收费标准
4. 费用在订单成交时计算并从账户现金中扣除
5. 费用计算支持买入和卖出两种方向
6. 费用配置默认值为长桥券商的标准费率

数据源管理

1. 数据源必须关联到具体的券商
2. 支持多个数据源，按优先级排序
3. 数据源状态影响数据拉取功能
4. 默认数据源优先级为1

配置管理

1. 敏感信息（app_secret, access_token）需要加密存储
2. 配置变更需要记录操作日志
3. 支持配置验证功能
4. 支持配置导入/导出

费用计算公式

美股费用计算

def calculate_us_fees(quantity: Decimal, price: Decimal, side: str, fee_config: USFeeConfig) -> Decimal:
    """
    计算美股交易费用
    
    Args:
        quantity: 成交数量
        price: 成交价格
        side: 买卖方向 ('buy' | 'sell')
        fee_config: 美股费用配置
    
    Returns:
        总费用（美元）
    """
    total_fee = Decimal('0')
    trade_amount = quantity * price
    
    # 1. 平台费（买入和卖出都收取）
    platform_fee = max(
        quantity * fee_config.platform_fee_per_share,
        fee_config.platform_fee_minimum
    )
    total_fee += platform_fee
    
    # 2. 交易活动费（仅卖出收取）
    if side == 'sell':
        activity_fee = min(
            quantity * fee_config.activity_fee_per_share,
            fee_config.activity_fee_maximum
        )
        total_fee += activity_fee
    
    # 3. 交收费（买入和卖出都收取）
    clearing_fee = min(
        quantity * fee_config.clearing_fee_per_share,
        trade_amount * fee_config.clearing_fee_max_pct
    )
    total_fee += clearing_fee
    
    # 4. 综合审计费（买入和卖出都收取）
    audit_fee = max(
        quantity * fee_config.audit_fee_per_share,
        fee_config.audit_fee_minimum
    )
    total_fee += audit_fee
    
    return total_fee

港股费用计算

def calculate_hk_fees(quantity: Decimal, price: Decimal, side: str, fee_config: HKFeeConfig) -> Decimal:
    """
    计算港股交易费用（计算逻辑与美股相同）
    
    Args:
        quantity: 成交数量
        price: 成交价格
        side: 买卖方向 ('buy' | 'sell')
        fee_config: 港股费用配置
    
    Returns:
        总费用（港元）
    """
    # 计算逻辑与美股相同
    pass

API设计

券商管理

• GET /api/v1/brokers - 获取券商列表
• POST /api/v1/brokers - 创建券商
• GET /api/v1/brokers/{id} - 获取券商详情
• PUT /api/v1/brokers/{id} - 更新券商
• DELETE /api/v1/brokers/{id} - 删除券商
• POST /api/v1/brokers/{id}/test - 测试券商连接

券商费用配置管理

• GET /api/v1/brokers/{id}/fee-config - 获取券商费用配置
• PUT /api/v1/brokers/{id}/fee-config - 更新券商费用配置
• POST /api/v1/brokers/{id}/fee-config/calculate - 计算预估费用

数据源管理

• GET /api/v1/data-sources - 获取数据源列表
• POST /api/v1/data-sources - 创建数据源
• PUT /api/v1/data-sources/{id} - 更新数据源
• DELETE /api/v1/data-sources/{id} - 删除数据源
• POST /api/v1/data-sources/{id}/test - 测试数据源连接

权限控制

• 券商和数据源管理需要用户认证
• 用户只能管理自己的券商配置
• 数据源管理需要管理员权限
• 配置信息对普通用户部分隐藏（敏感信息）

费用计算精度

精度标准

• 计算精度: 使用 Decimal 类型确保计算精度
• 显示精度: 所有费用数据统一保留2位小数
• 一致性: 与系统价格和资产数据精度保持一致
• 四舍五入: 费用计算完成后自动四舍五入到2位小数

精度示例

# 计算前: 1.239779483105691
# 计算后: 1.24 (四舍五入到2位小数)
fee.total_fee = fee.total_fee.quantize(Decimal('0.01'))

安全考虑

1. 数据加密存储

加密方案

系统使用 AES-256-GCM 加密算法保护敏感配置信息。详细实现参考：安全实现指南

快速示例：

from backend.core.security.encryption import ConfigEncryption

# 初始化加密器
encryptor = ConfigEncryption()

# 加密敏感信息
encrypted_secret = encryptor.encrypt("your_secret_key")

# 解密敏感信息
decrypted_secret = encryptor.decrypt(encrypted_secret)

敏感字段列表

字段名	说明	加密方法
app_secret	券商API密钥	AES-256-GCM
access_token	访问令牌	AES-256-GCM
refresh_token	刷新令牌	AES-256-GCM
password	用户密码	bcrypt哈希

2. 密钥管理

环境变量配置：

# .env 文件（不要提交到Git）
ENCRYPTION_MASTER_KEY=your-32-character-master-key-here
JWT_SECRET_KEY=your-jwt-secret-key-here

# 生成强密钥
python -c "import secrets; print(secrets.token_urlsafe(32))"

密钥轮换：建议每季度轮换一次加密密钥

3. API访问控制

JWT认证

所有API请求需要携带JWT令牌：

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

权限级别

权限级别	说明	允许操作
admin	管理员	所有操作
user	普通用户	查看和修改自己的数据
readonly	只读用户	仅查看数据

4. 配置变更审计

所有券商配置的创建、修改、删除操作都会记录审计日志：

class ConfigChangeLog:
    """配置变更审计日志"""

    timestamp: datetime      # 变更时间
    user_id: str            # 操作用户
    broker_id: str          # 券商ID
    action: str             # 操作类型：create/update/delete
    old_value: dict         # 旧配置（敏感信息已脱敏）
    new_value: dict         # 新配置（敏感信息已脱敏）
    ip_address: str         # 客户端IP
    user_agent: str         # 用户代理

5. 数据备份和恢复

自动备份

# 每日自动备份券商配置
python scripts/backup_broker_configs.py --output /backups/

恢复流程

# 从备份恢复配置
python scripts/restore_broker_configs.py --input backup.json.enc

6. 安全最佳实践

✅ 推荐做法

1. 永不硬编码密钥：所有密钥通过环境变量管理
2. 使用强密钥：至少32字符的随机密钥
3. 定期轮换密钥：每季度轮换一次加密密钥
4. 最小权限原则：用户只能访问自己的配置
5. 审计所有变更：记录所有配置修改操作
6. 加密备份：备份文件必须加密
7. HTTPS传输：生产环境强制使用HTTPS

❌ 避免做法

1. 在代码中硬编码密钥
2. 使用弱密钥（如”123456”）
3. 明文存储敏感信息
4. 将密钥提交到Git
5. 在日志中输出敏感信息

7. 生产环境部署检查清单

在生产环境部署前，请确认：

• 已设置强加密主密钥（ENCRYPTION_MASTER_KEY）
• 已设置强JWT密钥（JWT_SECRET_KEY）
• 已删除默认测试账户（test_for_dev）
• 已启用HTTPS
• 已配置防火墙规则
• 已设置审计日志
• 已配置自动备份
• 已测试恢复流程

8. 详细安全文档

更多安全实现细节，请参考：

• 安全实现指南
• 加密API文档
• 密钥管理指南
• 审计日志规范