# API 接口调用示例

本文档提供常见业务场景的 API 调用示例。

## 前置说明

所有需要认证的接口都需要在 Header 中携带 JWT Token：
```
Authorization: Bearer {your_token}
```

基础 URL：`http://localhost:3000/api`

## 场景 1：用户登录并查看仪表盘

### 1.1 用户登录

```bash
curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "admin123"
  }'
```

**响应示例**：
```json
{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "username": "admin",
      "real_name": "系统管理员",
      "role": "admin",
      "department": "管理部",
      "team": null
    }
  }
}
```

### 1.2 查看个人仪表盘

```bash
# 使用上一步获得的 token
TOKEN="your_token_here"

curl -X GET http://localhost:3000/api/stats/dashboard \
  -H "Authorization: Bearer $TOKEN"
```

**响应示例**：
```json
{
  "success": true,
  "data": {
    "summary": {
      "total": 15,
      "following": 10,
      "won": 3,
      "lost": 2,
      "conversion_rate": "60.00%",
      "month_reports": 8,
      "week_followups": 12
    },
    "expiring_customers": [
      {
        "id": "...",
        "customer_name": "XX科技有限公司",
        "protected_end_date": "2024-01-23 10:30:00",
        "industry": "互联网/软件",
        "region": "北京"
      }
    ]
  }
}
```

## 场景 2：报备新客户

### 2.1 查重检查

```bash
curl -X GET "http://localhost:3000/api/customers/check-duplicate?customer_name=腾讯科技" \
  -H "Authorization: Bearer $TOKEN"
```

**响应示例（无冲突）**：
```json
{
  "success": true,
  "has_conflict": false,
  "message": "未发现重复客户，可以报备"
}
```

**响应示例（有冲突）**：
```json
{
  "success": true,
  "has_conflict": true,
  "conflict_type": "exact",
  "data": {
    "id": "...",
    "customer_name": "腾讯科技",
    "owner_name": "张三",
    "team": "华北团队",
    "report_time": "2024-01-15 09:30:00"
  },
  "message": "发现完全重复的客户"
}
```

### 2.2 创建客户报备

```bash
curl -X POST http://localhost:3000/api/customers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_name": "阿里云计算有限公司",
    "industry": "互联网/软件",
    "region": "杭州",
    "contact_person": "李先生",
    "contact_phone": "13800138000",
    "demand_description": "需要企业级CRM系统，预计预算50万元，决策周期2个月",
    "source": "展会"
  }'
```

**响应示例**：
```json
{
  "success": true,
  "message": "客户报备成功",
  "data": {
    "id": "customer-uuid-here",
    "customer_name": "阿里云计算有限公司",
    "protected_end_date": "2024-02-20 10:30:00"
  }
}
```

## 场景 3：客户跟进

### 3.1 查看客户列表

```bash
# 查看我的跟进中客户
curl -X GET "http://localhost:3000/api/customers?status=following&page=1&limit=10" \
  -H "Authorization: Bearer $TOKEN"

# 搜索特定客户
curl -X GET "http://localhost:3000/api/customers?keyword=阿里&page=1&limit=10" \
  -H "Authorization: Bearer $TOKEN"
```

**响应示例**：
```json
{
  "success": true,
  "data": {
    "customers": [
      {
        "id": "...",
        "customer_name": "阿里云计算有限公司",
        "industry": "互联网/软件",
        "region": "杭州",
        "contact_person": "李先生",
        "contact_phone": "13800138000",
        "status": "following",
        "owner_name": "系统管理员",
        "protected_end_date": "2024-02-20 10:30:00",
        "is_expired": 0,
        "report_time": "2024-01-20 10:30:00"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 15,
      "total_pages": 2
    }
  }
}
```

### 3.2 查看客户详情

```bash
CUSTOMER_ID="customer-uuid-here"

curl -X GET "http://localhost:3000/api/customers/$CUSTOMER_ID" \
  -H "Authorization: Bearer $TOKEN"
```

**响应示例**：
```json
{
  "success": true,
  "data": {
    "customer": {
      "id": "...",
      "customer_name": "阿里云计算有限公司",
      "industry": "互联网/软件",
      "region": "杭州",
      "contact_person": "李先生",
      "contact_phone": "13800138000",
      "demand_description": "需要企业级CRM系统...",
      "source": "展会",
      "status": "following",
      "owner_name": "系统管理员",
      "protected_end_date": "2024-02-20 10:30:00",
      "last_followup": "2024-01-19 15:00:00"
    },
    "followups": [
      {
        "id": "...",
        "followup_type": "call",
        "content": "电话沟通，客户表示有兴趣",
        "next_plan": "下周上门拜访",
        "user_name": "系统管理员",
        "created_at": "2024-01-19 15:00:00"
      }
    ],
    "attachments": []
  }
}
```

### 3.3 添加跟进记录

```bash
curl -X POST http://localhost:3000/api/customers/followup \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "customer-uuid-here",
    "followup_type": "visit",
    "content": "上门拜访，与技术负责人进行了深入沟通，客户对产品功能很满意",
    "next_plan": "下周提交方案和报价"
  }'
```

**响应示例**：
```json
{
  "success": true,
  "message": "跟进记录添加成功",
  "data": {
    "id": "followup-uuid-here"
  }
}
```

### 3.4 更新客户状态

```bash
# 标记为已成交
curl -X PATCH "http://localhost:3000/api/customers/$CUSTOMER_ID/status" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "won"
  }'

# 标记为已丢单
curl -X PATCH "http://localhost:3000/api/customers/$CUSTOMER_ID/status" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "lost"
  }'
```

## 场景 4：公海池管理

### 4.1 查看公海池客户

```bash
curl -X GET "http://localhost:3000/api/pool/customers?page=1&limit=20" \
  -H "Authorization: Bearer $TOKEN"

# 按行业筛选
curl -X GET "http://localhost:3000/api/pool/customers?industry=互联网/软件" \
  -H "Authorization: Bearer $TOKEN"
```

**响应示例**：
```json
{
  "success": true,
  "data": {
    "customers": [
      {
        "id": "...",
        "customer_name": "公海客户001有限公司",
        "industry": "制造业",
        "region": "上海",
        "last_owner_name": "张三",
        "claim_count": 2,
        "release_reason": "保护期自动到期",
        "updated_at": "2024-01-20 10:00:00"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 5,
      "total_pages": 1
    }
  }
}
```

### 4.2 领取客户

```bash
curl -X POST http://localhost:3000/api/pool/claim \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "pool-customer-uuid-here"
  }'
```

**响应示例**：
```json
{
  "success": true,
  "message": "客户领取成功",
  "data": {
    "customer_id": "...",
    "protected_end_date": "2024-02-20 10:30:00"
  }
}
```

### 4.3 释放客户到公海池

```bash
curl -X POST http://localhost:3000/api/pool/release \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "customer-uuid-here",
    "release_reason": "客户暂时没有采购计划，延期到明年"
  }'
```

### 4.4 查看我的领取记录

```bash
curl -X GET "http://localhost:3000/api/pool/my-claims?page=1&limit=20" \
  -H "Authorization: Bearer $TOKEN"
```

## 场景 5：审批流程

### 5.1 提交延期申请

```bash
curl -X POST http://localhost:3000/api/approvals \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "extension",
    "customer_id": "customer-uuid-here",
    "reason": "客户决策流程较长，需要经过董事会审批，希望延长保护期",
    "extension_days": 15
  }'
```

**响应示例**：
```json
{
  "success": true,
  "message": "审批申请已提交",
  "data": {
    "id": "approval-uuid-here"
  }
}
```

### 5.2 查看我的审批申请

```bash
curl -X GET "http://localhost:3000/api/approvals/my?page=1&limit=20" \
  -H "Authorization: Bearer $TOKEN"
```

### 5.3 查看待审批列表（经理权限）

```bash
curl -X GET "http://localhost:3000/api/approvals/pending?page=1&limit=20" \
  -H "Authorization: Bearer $TOKEN"
```

**响应示例**：
```json
{
  "success": true,
  "data": {
    "approvals": [
      {
        "id": "...",
        "type": "extension",
        "applicant_name": "张三",
        "applicant_team": "华北团队",
        "customer_name": "阿里云计算有限公司",
        "reason": "客户决策流程较长...",
        "extension_days": 15,
        "status": "pending",
        "created_at": "2024-01-20 10:00:00"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 3,
      "total_pages": 1
    }
  }
}
```

### 5.4 处理审批（经理权限）

```bash
APPROVAL_ID="approval-uuid-here"

# 批准
curl -X POST "http://localhost:3000/api/approvals/$APPROVAL_ID/process" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "approved",
    "result_comment": "同意延期15天，请继续跟进"
  }'

# 拒绝
curl -X POST "http://localhost:3000/api/approvals/$APPROVAL_ID/process" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "rejected",
    "result_comment": "已经延期过一次，建议尽快推进或释放"
  }'
```

## 场景 6：统计报表

### 6.1 团队统计（经理权限）

```bash
# 按天统计
curl -X GET "http://localhost:3000/api/stats/team?start_date=2024-01-01&end_date=2024-01-31&period=day" \
  -H "Authorization: Bearer $TOKEN"

# 按周统计
curl -X GET "http://localhost:3000/api/stats/team?period=week" \
  -H "Authorization: Bearer $TOKEN"

# 按月统计
curl -X GET "http://localhost:3000/api/stats/team?period=month" \
  -H "Authorization: Bearer $TOKEN"
```

**响应示例**：
```json
{
  "success": true,
  "data": {
    "team_summary": {
      "total": 45,
      "following": 30,
      "won": 10,
      "lost": 5
    },
    "member_stats": [
      {
        "id": "...",
        "real_name": "张三",
        "total_customers": 20,
        "following": 15,
        "won": 4,
        "lost": 1,
        "active_days": 22,
        "conversion_rate": "80.00%"
      },
      {
        "id": "...",
        "real_name": "李四",
        "total_customers": 15,
        "following": 10,
        "won": 3,
        "lost": 2,
        "active_days": 18,
        "conversion_rate": "60.00%"
      }
    ],
    "timeline": [
      {
        "period": "2024-01-01",
        "count": 5,
        "won_count": 2
      },
      {
        "period": "2024-01-02",
        "count": 3,
        "won_count": 1
      }
    ]
  }
}
```

### 6.2 客户来源分析

```bash
curl -X GET "http://localhost:3000/api/stats/source-analysis?start_date=2024-01-01&end_date=2024-01-31" \
  -H "Authorization: Bearer $TOKEN"
```

**响应示例**：
```json
{
  "success": true,
  "data": [
    {
      "source": "转介绍",
      "count": 15,
      "won_count": 8,
      "lost_count": 2,
      "conversion_rate": "80.00%"
    },
    {
      "source": "展会",
      "count": 10,
      "won_count": 3,
      "lost_count": 3,
      "conversion_rate": "50.00%"
    }
  ]
}
```

### 6.3 行业分布分析

```bash
curl -X GET "http://localhost:3000/api/stats/industry-analysis" \
  -H "Authorization: Bearer $TOKEN"
```

### 6.4 公海池利用情况（经理权限）

```bash
curl -X GET "http://localhost:3000/api/stats/pool-utilization" \
  -H "Authorization: Bearer $TOKEN"
```

**响应示例**：
```json
{
  "success": true,
  "data": {
    "pool_total": 25,
    "week_claims": 8,
    "month_claims": 32,
    "top_claimers": [
      {
        "real_name": "张三",
        "claim_count": 12
      },
      {
        "real_name": "李四",
        "claim_count": 10
      }
    ]
  }
}
```

## 场景 7：用户管理

### 7.1 创建新用户（管理员权限）

```bash
curl -X POST http://localhost:3000/api/auth/register \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "sales003",
    "password": "123456",
    "real_name": "王五",
    "email": "wangwu@example.com",
    "phone": "13800138003",
    "role": "sales",
    "department": "销售部",
    "team": "华南团队"
  }'
```

### 7.2 修改密码

```bash
curl -X POST http://localhost:3000/api/auth/change-password \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "old_password": "admin123",
    "new_password": "newpassword123"
  }'
```

## 错误处理示例

### 未认证
```json
{
  "success": false,
  "message": "未提供认证令牌"
}
```

### 权限不足
```json
{
  "success": false,
  "message": "权限不足，需要以下角色之一: sales_manager, admin"
}
```

### 业务错误
```json
{
  "success": false,
  "message": "今日领取次数已达上限(5次)"
}
```

## 使用 JavaScript fetch

```javascript
const API_BASE = 'http://localhost:3000/api';
const token = 'your_token_here';

// 登录
async function login(username, password) {
  const response = await fetch(`${API_BASE}/auth/login`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ username, password })
  });
  return await response.json();
}

// 创建客户报备
async function createCustomer(data) {
  const response = await fetch(`${API_BASE}/customers`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify(data)
  });
  return await response.json();
}

// 获取客户列表
async function getCustomers(params = {}) {
  const queryString = new URLSearchParams(params).toString();
  const response = await fetch(`${API_BASE}/customers?${queryString}`, {
    headers: { 'Authorization': `Bearer ${token}` }
  });
  return await response.json();
}
```

---

更多接口详情请参考 `README.md` 文档。