# 中台系统与Goldhorse Ewealth CRM系统API接口设计

## 🎯 API接口概览

### 基础信息
- **API版本**: v1.0
- **基础URL**: `https://api.pms.goldhorse.com/v1`
- **认证方式**: OAuth 2.0 + JWT Token
- **数据格式**: JSON
- **字符编码**: UTF-8

## 📋 核心API接口

### 1. 开户管理接口

#### 1.1 客户开户申请
```http
POST /api/v1/customers/application
Content-Type: application/json
Authorization: Bearer {jwt_token}
```

**请求体**:
```json
{
  "application_id": "APP_20250115_001",
  "customer_type": "INDIVIDUAL",
  "personal_info": {
    "name": "张伟",
    "name_en": "Zhang Wei",
    "id_type": "HK_ID",
    "id_number": "A123456789",
    "phone": "+852-1234-5678",
    "email": "zhangwei@email.com",
    "address": "香港中环金融街88号"
  },
  "kyc_documents": [
    {
      "type": "ID_CARD",
      "file_url": "https://storage.example.com/docs/id_card.pdf",
      "file_hash": "sha256:abc123...",
      "upload_time": "2025-01-15T10:30:00Z"
    }
  ],
  "risk_assessment": {
    "risk_level": "R3",
    "investment_experience": "INTERMEDIATE",
    "annual_income": 500000,
    "investment_objectives": ["CAPITAL_GROWTH", "INCOME"]
  }
}
```

**响应体**:
```json
{
  "status": "success",
  "data": {
    "application_id": "APP_20250115_001",
    "status": "PENDING",
    "estimated_processing_time": "3-5个工作日",
    "tracking_url": "https://crm.goldhorse.com/track/APP_20250115_001"
  },
  "message": "开户申请已提交，正在处理中"
}
```

#### 1.2 开户状态查询
```http
GET /api/v1/customers/application/{application_id}
Authorization: Bearer {jwt_token}
```

**响应体**:
```json
{
  "status": "success",
  "data": {
    "application_id": "APP_20250115_001",
    "status": "UNDER_REVIEW",
    "current_step": "KYC_VERIFICATION",
    "progress": 60,
    "timeline": [
      {
        "step": "SUBMITTED",
        "status": "COMPLETED",
        "timestamp": "2025-01-15T10:30:00Z",
        "description": "申请已提交"
      },
      {
        "step": "KYC_VERIFICATION",
        "status": "IN_PROGRESS",
        "timestamp": "2025-01-15T11:00:00Z",
        "description": "身份验证进行中"
      }
    ],
    "estimated_completion": "2025-01-18T17:00:00Z"
  }
}
```

### 2. 产品管理接口

#### 2.1 产品信息同步
```http
POST /api/v1/products/sync
Content-Type: application/json
Authorization: Bearer {jwt_token}
```

**请求体**:
```json
{
  "product_id": "BOW465",
  "product_name": "大成港元货币市场基金",
  "product_type": "FUND",
  "category": "MONEY_MARKET",
  "risk_level": "R1",
  "basic_info": {
    "issuer": "大成国际资产管理有限公司",
    "currency": "HKD",
    "nav": 1.0000,
    "nav_date": "2025-01-15",
    "management_fee": 0.60,
    "custodian": "中银国际英国保诚信托有限公司"
  },
  "trading_info": {
    "min_investment": 10000,
    "trading_hours": "09:00-17:00",
    "settlement": "T+1",
    "redemption_fee": 0.00,
    "subscription_fee": 0.00
  },
  "compliance": {
    "sfc_approved": true,
    "cross_border_eligible": true,
    "suitability_requirements": ["R1", "R2"],
    "regulatory_status": "ACTIVE"
  },
  "performance": {
    "ytd_return": 2.85,
    "one_year_return": 2.85,
    "three_year_return": 2.50,
    "volatility": 0.15
  }
}
```

#### 2.2 产品列表查询
```http
GET /api/v1/products?type=FUND&risk_level=R1&page=1&limit=20
Authorization: Bearer {jwt_token}
```

**响应体**:
```json
{
  "status": "success",
  "data": {
    "products": [
      {
        "product_id": "BOW465",
        "product_name": "大成港元货币市场基金",
        "product_type": "FUND",
        "risk_level": "R1",
        "nav": 1.0000,
        "daily_change": 0.0001,
        "ytd_return": 2.85,
        "min_investment": 10000,
        "status": "ACTIVE"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 156,
      "total_pages": 8
    }
  }
}
```

### 3. 订单风控接口

#### 3.1 订单风控检查
```http
POST /api/v1/orders/risk-check
Content-Type: application/json
Authorization: Bearer {jwt_token}
```

**请求体**:
```json
{
  "order_id": "ORD_20250115_001",
  "customer_id": "CRM_CUST_001",
  "product_id": "BOW465",
  "order_details": {
    "quantity": 100000,
    "price": 1.0000,
    "order_type": "MARKET_ORDER",
    "side": "BUY"
  },
  "customer_context": {
    "risk_level": "R1",
    "available_balance": 500000,
    "current_positions": {
      "BOW465": 50000
    }
  }
}
```

**响应体**:
```json
{
  "status": "success",
  "data": {
    "order_id": "ORD_20250115_001",
    "risk_check_result": "APPROVED",
    "checks": {
      "affordability_check": {
        "status": "PASSED",
        "required_amount": 100000,
        "available_balance": 500000,
        "remaining_balance": 400000
      },
      "suitability_check": {
        "status": "PASSED",
        "customer_risk_level": "R1",
        "product_risk_level": "R1",
        "match_score": 100
      },
      "price_check": {
        "status": "PASSED",
        "market_price": 1.0000,
        "order_price": 1.0000,
        "deviation_percentage": 0.00
      },
      "concentration_check": {
        "status": "PASSED",
        "current_exposure": 10.0,
        "max_allowed": 20.0
      }
    },
    "warnings": [],
    "approval_time": "2025-01-15T14:30:00Z"
  }
}
```

#### 3.2 订单执行确认
```http
POST /api/v1/orders/execute
Content-Type: application/json
Authorization: Bearer {jwt_token}
```

**请求体**:
```json
{
  "order_id": "ORD_20250115_001",
  "execution_details": {
    "executed_quantity": 100000,
    "executed_price": 1.0000,
    "execution_time": "2025-01-15T14:35:00Z",
    "commission": 150.00,
    "total_amount": 100150.00
  }
}
```

### 4. EAM管理接口

#### 4.1 EAM信息同步
```http
POST /api/v1/eam/sync
Content-Type: application/json
Authorization: Bearer {jwt_token}
```

**请求体**:
```json
{
  "eam_id": "EAM001",
  "eam_name": "华泰资产管理",
  "contact_info": {
    "contact_person": "张经理",
    "phone": "138-0000-0000",
    "email": "zhang@huatai.com"
  },
  "permissions": {
    "product_access": ["BOND", "FUND", "STRUCTURED"],
    "customer_access": ["VIP", "PREMIUM"],
    "trading_limits": {
      "max_order_size": 1000000,
      "daily_limit": 5000000,
      "monthly_limit": 100000000
    }
  },
  "commission_settings": {
    "bond_commission": 0.25,
    "fund_commission": 0.30,
    "structured_commission": 0.35,
    "fx_commission": 0.20
  },
  "status": "ACTIVE"
}
```

#### 4.2 EAM客户关联
```http
POST /api/v1/eam/customer-association
Content-Type: application/json
Authorization: Bearer {jwt_token}
```

**请求体**:
```json
{
  "eam_id": "EAM001",
  "customer_id": "CRM_CUST_001",
  "association_type": "PRIMARY",
  "start_date": "2025-01-15",
  "commission_override": {
    "bond_commission": 0.30,
    "fund_commission": 0.35
  }
}
```

## 🔐 认证与安全

### 1. JWT Token结构
```json
{
  "header": {
    "alg": "RS256",
    "typ": "JWT"
  },
  "payload": {
    "iss": "pms.goldhorse.com",
    "sub": "crm_system",
    "aud": "goldhorse_ewealth",
    "exp": 1640995200,
    "iat": 1640908800,
    "permissions": ["read:customers", "write:orders", "read:products"]
  }
}
```

### 2. API限流规则
- **开户接口**: 100次/分钟
- **产品查询**: 1000次/分钟
- **风控检查**: 500次/分钟
- **EAM管理**: 50次/分钟

### 3. 错误码定义
```json
{
  "1000": "成功",
  "2001": "认证失败",
  "2002": "权限不足",
  "3001": "参数错误",
  "3002": "数据格式错误",
  "4001": "客户不存在",
  "4002": "产品不存在",
  "5001": "风控检查失败",
  "5002": "余额不足",
  "5003": "适合性检查失败",
  "9001": "系统内部错误"
}
```

## 📊 监控与日志

### 1. API监控指标
- **响应时间**: 平均响应时间 < 200ms
- **成功率**: API调用成功率 > 99.5%
- **并发数**: 支持1000并发请求
- **错误率**: 错误率 < 0.5%

### 2. 业务监控指标
- **开户处理量**: 每日开户申请数量
- **风控通过率**: 订单风控检查通过率
- **产品同步延迟**: 产品信息同步时间
- **EAM活跃度**: EAM系统使用情况

### 3. 日志记录
```json
{
  "timestamp": "2025-01-15T14:30:00Z",
  "level": "INFO",
  "service": "pms-api",
  "request_id": "req_123456789",
  "method": "POST",
  "path": "/api/v1/orders/risk-check",
  "status_code": 200,
  "response_time": 150,
  "user_id": "crm_system",
  "ip_address": "192.168.1.100",
  "user_agent": "Goldhorse-CRM/1.0"
}
```

## 🚀 部署与运维

### 1. 环境配置
- **开发环境**: `https://api-dev.pms.goldhorse.com`
- **测试环境**: `https://api-test.pms.goldhorse.com`
- **生产环境**: `https://api.pms.goldhorse.com`

### 2. 健康检查
```http
GET /api/v1/health
```

**响应体**:
```json
{
  "status": "healthy",
  "timestamp": "2025-01-15T14:30:00Z",
  "version": "1.0.0",
  "services": {
    "database": "healthy",
    "redis": "healthy",
    "message_queue": "healthy"
  }
}
```

### 3. 版本管理
- **API版本**: 通过URL路径管理 (`/api/v1/`)
- **向后兼容**: 保持3个版本的向后兼容
- **废弃通知**: 提前6个月通知API废弃

---

*本API接口设计文档提供了中台系统与Goldhorse Ewealth CRM系统集成的完整技术方案，确保系统间的高效、安全、可靠的数据交互。*