API 接口调用示例

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

前置说明

所有需要认证的接口都需要在 Header 中携带 JWT Token：

Authorization: Bearer {your_token}

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

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

1.1 用户登录

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

响应示例：

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

1.2 查看个人仪表盘

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

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

响应示例：

{
  "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 查重检查

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

响应示例（无冲突）：

{
  "success": true,
  "has_conflict": false,
  "message": "未发现重复客户，可以报备"
}

响应示例（有冲突）：

{
  "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 创建客户报备

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": "展会"
  }'

响应示例：

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

场景 3：客户跟进

3.1 查看客户列表

# 查看我的跟进中客户
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"

响应示例：

{
  "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 查看客户详情

CUSTOMER_ID="customer-uuid-here"

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

响应示例：

{
  "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 添加跟进记录

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": "下周提交方案和报价"
  }'

响应示例：

{
  "success": true,
  "message": "跟进记录添加成功",
  "data": {
    "id": "followup-uuid-here"
  }
}

3.4 更新客户状态

# 标记为已成交
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 查看公海池客户

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"

响应示例：

{
  "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 领取客户

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"
  }'

响应示例：

{
  "success": true,
  "message": "客户领取成功",
  "data": {
    "customer_id": "...",
    "protected_end_date": "2024-02-20 10:30:00"
  }
}

4.3 释放客户到公海池

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 查看我的领取记录

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

场景 5：审批流程

5.1 提交延期申请

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
  }'

响应示例：

{
  "success": true,
  "message": "审批申请已提交",
  "data": {
    "id": "approval-uuid-here"
  }
}

5.2 查看我的审批申请

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

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

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

响应示例：

{
  "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 处理审批（经理权限）

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 团队统计（经理权限）

# 按天统计
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"

响应示例：

{
  "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 客户来源分析

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

响应示例：

{
  "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 行业分布分析

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

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

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

响应示例：

{
  "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 创建新用户（管理员权限）

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 修改密码

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"
  }'

错误处理示例

未认证

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

权限不足

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

业务错误

{
  "success": false,
  "message": "今日领取次数已达上限(5次)"
}

使用 JavaScript fetch

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 文档。

API_EXAMPLES.md 14 KB Permalink History Raw

API 接口调用示例

前置说明

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

1.1 用户登录

1.2 查看个人仪表盘

场景 2：报备新客户

2.1 查重检查

2.2 创建客户报备

场景 3：客户跟进

3.1 查看客户列表

3.2 查看客户详情

3.3 添加跟进记录

3.4 更新客户状态

场景 4：公海池管理

4.1 查看公海池客户

4.2 领取客户

4.3 释放客户到公海池

4.4 查看我的领取记录

场景 5：审批流程

5.1 提交延期申请

5.2 查看我的审批申请

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

5.4 处理审批（经理权限）

场景 6：统计报表

6.1 团队统计（经理权限）

6.2 客户来源分析

6.3 行业分布分析

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

场景 7：用户管理

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

7.2 修改密码

错误处理示例

未认证

权限不足

业务错误

使用 JavaScript fetch

API_EXAMPLES.md 14 KB

Permalink History Raw