012-kaopeilian/docs/规划/考陪练系统API对接规范.md

考陪练系统 API 对接规范

知识点智能推送功能需要考陪练系统提供的数据查询 API

---

概述

SCRM 系统的「知识点智能推送」功能需要调用考陪练系统的 API，仅用于数据查询（员工岗位、知识点、课程关系等）。

职责划分：

• 考陪练系统：提供数据查询 API（知识点库、岗位课程关系）
• SCRM AI功能：负责短板分析、知识点匹配、动态出题、效果追踪

对接模式

SCRM系统 ────REST API────▶ 考陪练系统
                │
                ├── 获取员工岗位
                ├── 获取岗位课程
                ├── 搜索知识点
                └── 获取知识点详情

认证方式

推荐：内部服务间调用，使用固定 API Key

Authorization: Bearer {INTERNAL_API_KEY}

或者使用 IP 白名单 + 固定 Token 方式。

---

API 接口列表（共6个）

所有 API 仅用于数据查询，不涉及业务逻辑处理

1. 获取员工岗位（通过企微userid）

根据企微 userid 查询员工在考陪练系统中的岗位信息。

请求

GET /api/scrm/employees/{userid}/position

参数	类型	必填	说明
userid	string	是	企微员工userid

响应

{
  "code": 0,
  "message": "success",
  "data": {
    "employee_id": 12345,
    "userid": "zhangxiaomei",
    "name": "张小美",
    "positions": [
      {
        "position_id": 5,
        "position_name": "美容顾问",
        "is_primary": true,
        "joined_at": "2025-06-01"
      }
    ]
  }
}

错误码

code	说明
0	成功
404	员工不存在
40001	userid 格式错误

---

1.1 获取员工岗位（通过姓名搜索）⭐ 推荐

根据员工姓名查询岗位信息，支持精确匹配和模糊匹配。适用于尚未配置企微userid的场景。

请求

GET /api/scrm/employees/search/by-name?name={姓名}

参数	类型	必填	说明
name	string	是	员工姓名（支持精确匹配和模糊匹配）

响应（单个匹配）

{
  "code": 0,
  "message": "success",
  "data": {
    "employee_id": 367,
    "userid": null,
    "name": "农俊",
    "positions": [
      {
        "position_id": 145,
        "position_name": "董事长",
        "is_primary": true,
        "joined_at": "2025-12-10"
      }
    ]
  }
}

响应（多个匹配）

当有多个同名或姓名相似的员工时，返回候选列表：

{
  "code": 0,
  "message": "找到 4 个匹配的员工，请确认后使用 employee_id 精确查询",
  "data": {
    "multiple_matches": true,
    "count": 4,
    "employees": [
      {
        "employee_id": 367,
        "userid": null,
        "name": "农俊",
        "phone": "5653"
      },
      {
        "employee_id": 368,
        "userid": null,
        "name": "农美平",
        "phone": "5078"
      }
    ]
  }
}

---

1.2 获取员工岗位（通过员工ID）

根据员工ID精确查询岗位信息，用于多个同名员工时的精确查询。

请求

GET /api/scrm/employees/by-id/{employee_id}/position

参数	类型	必填	说明
employee_id	int	是	员工ID（考陪练系统用户ID）

响应

与接口1相同。

---

2. 获取岗位课程列表

获取指定岗位的必修/选修课程列表。

请求

GET /api/scrm/positions/{position_id}/courses

参数	类型	必填	说明
position_id	int	是	岗位ID
course_type	string	否	课程类型：required/optional/all，默认all

响应

{
  "code": 0,
  "message": "success",
  "data": {
    "position_id": 5,
    "position_name": "美容顾问",
    "courses": [
      {
        "course_id": 101,
        "course_name": "医美产品知识",
        "course_type": "required",
        "priority": 1,
        "knowledge_point_count": 25
      },
      {
        "course_id": 102,
        "course_name": "销售技巧提升",
        "course_type": "required",
        "priority": 2,
        "knowledge_point_count": 18
      }
    ]
  }
}

---

3. 搜索知识点

根据关键词和岗位搜索匹配的知识点。

请求

POST /api/scrm/knowledge-points/search

请求体

{
  "keywords": ["玻尿酸", "成分", "功效"],
  "position_id": 5,
  "course_ids": [101, 102],
  "knowledge_type": "产品知识",
  "limit": 10
}

参数	类型	必填	说明
keywords	array	是	搜索关键词列表
position_id	int	否	岗位ID（用于优先排序）
course_ids	array	否	限定课程范围
knowledge_type	string	否	知识点类型筛选
limit	int	否	返回数量，默认10

响应

{
  "code": 0,
  "message": "success",
  "data": {
    "total": 5,
    "items": [
      {
        "knowledge_point_id": 1001,
        "name": "玻尿酸分类与特性",
        "course_id": 101,
        "course_name": "医美产品知识",
        "type": "产品知识",
        "relevance_score": 0.95
      },
      {
        "knowledge_point_id": 1002,
        "name": "玻尿酸适用人群",
        "course_id": 101,
        "course_name": "医美产品知识",
        "type": "产品知识",
        "relevance_score": 0.82
      }
    ]
  }
}

---

4. 获取知识点详情

获取知识点的完整信息。

请求

GET /api/scrm/knowledge-points/{knowledge_point_id}

参数	类型	必填	说明
knowledge_point_id	int	是	知识点ID

响应

{
  "code": 0,
  "message": "success",
  "data": {
    "knowledge_point_id": 1001,
    "name": "玻尿酸分类与特性",
    "course_id": 101,
    "course_name": "医美产品知识",
    "type": "产品知识",
    "content": "玻尿酸（透明质酸，Hyaluronic Acid，简称HA）是一种天然存在于人体内的多糖类物质。按分子量可分为三类：大分子玻尿酸主要用于填充塑形，维持时间较长；中分子玻尿酸用于补水保湿，改善细纹；小分子玻尿酸可深层滋养，促进吸收。在实际应用中，需要根据客户的皮肤状况和需求，推荐合适的类型...",
    "material_id": 501,
    "material_type": "pdf",
    "material_url": "https://xxx/materials/501.pdf",
    "topic_relation": "医美产品基础知识",
    "source": 0,
    "created_at": "2025-06-01 10:00:00"
  }
}

字段说明

字段	说明
content	知识点完整内容
material_id	关联的课程资料ID（可选）
material_url	资料文件URL（可选）
topic_relation	与主题的关系描述
source	来源：0=手动创建，1=AI分析生成

注意：30秒精简版内容和测验题由 SCRM AI功能模块生成，考陪练只需提供原始知识点内容。

---

错误码规范

code	HTTP状态码	说明
0	200	成功
400	400	请求参数错误
401	401	认证失败
403	403	无权限
404	404	资源不存在
500	500	服务器内部错误
40001	400	userid 格式错误
40002	400	position_id 不存在
40003	400	knowledge_point_id 不存在

---

调用示例

Python 示例

import httpx
from typing import Optional, List, Dict

class KaoPeiLianClient:
    """考陪练系统API客户端（仅数据查询）"""
    
    def __init__(self, base_url: str, api_key: str):
        self.base_url = base_url.rstrip('/')
        self.api_key = api_key
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        }
    
    async def get_employee_position(self, userid: str) -> Optional[Dict]:
        """获取员工岗位"""
        async with httpx.AsyncClient() as client:
            response = await client.get(
                f"{self.base_url}/api/scrm/employees/{userid}/position",
                headers=self.headers
            )
            data = response.json()
            if data.get("code") == 0:
                return data.get("data")
            return None
    
    async def get_position_courses(self, position_id: int) -> List[Dict]:
        """获取岗位课程列表"""
        async with httpx.AsyncClient() as client:
            response = await client.get(
                f"{self.base_url}/api/scrm/positions/{position_id}/courses",
                headers=self.headers
            )
            data = response.json()
            if data.get("code") == 0:
                return data.get("data", {}).get("courses", [])
            return []
    
    async def search_knowledge_points(
        self, 
        keywords: List[str], 
        position_id: int = None,
        limit: int = 10
    ) -> List[Dict]:
        """搜索知识点"""
        payload = {
            "keywords": keywords,
            "limit": limit
        }
        if position_id:
            payload["position_id"] = position_id
        
        async with httpx.AsyncClient() as client:
            response = await client.post(
                f"{self.base_url}/api/scrm/knowledge-points/search",
                headers=self.headers,
                json=payload
            )
            data = response.json()
            if data.get("code") == 0:
                return data.get("data", {}).get("items", [])
            return []
    
    async def get_knowledge_point_detail(self, kp_id: int) -> Optional[Dict]:
        """获取知识点详情"""
        async with httpx.AsyncClient() as client:
            response = await client.get(
                f"{self.base_url}/api/scrm/knowledge-points/{kp_id}",
                headers=self.headers
            )
            data = response.json()
            if data.get("code") == 0:
                return data.get("data")
            return None


# 使用示例
async def main():
    client = KaoPeiLianClient(
        base_url="https://kaopeilian.example.com",
        api_key="your_api_key"
    )
    
    # 1. 获取员工岗位
    position = await client.get_employee_position("zhangxiaomei")
    print(f"岗位: {position['positions'][0]['position_name']}")
    
    # 2. 获取岗位课程
    courses = await client.get_position_courses(position['positions'][0]['position_id'])
    print(f"该岗位有 {len(courses)} 门课程")
    
    # 3. 搜索知识点
    knowledge_points = await client.search_knowledge_points(
        keywords=["玻尿酸", "成分"],
        position_id=position['positions'][0]['position_id']
    )
    print(f"找到 {len(knowledge_points)} 个知识点")
    
    # 4. 获取知识点详情
    kp = await client.get_knowledge_point_detail(knowledge_points[0]['knowledge_point_id'])
    print(f"知识点内容: {kp['content'][:100]}...")
    
    # 5. 后续由 SCRM AI功能模块处理：
    #    - AI生成30秒精简版
    #    - AI动态生成测验题

---

部署建议

网络连通性

SCRM 系统与考陪练系统部署在不同服务器，需确保：

1. 网络互通：SCRM 服务器可访问考陪练 API 地址
2. 防火墙放行：考陪练 API 端口对 SCRM 服务器 IP 开放
3. 超时设置：建议 API 超时时间设为 10 秒

接口地址配置

SCRM 系统通过环境变量配置考陪练 API 地址：

# .env
KAOPEILIAN_API_BASE_URL=https://kaopeilian.example.com
KAOPEILIAN_API_KEY=your_internal_api_key

---

联调清单

序号	接口	SCRM侧	考陪练侧	状态
1	获取员工岗位（userid）	调用方	提供方	✅ 考陪练侧已完成
1.1	获取员工岗位（姓名搜索）⭐	调用方	提供方	✅ 考陪练侧已完成
1.2	获取员工岗位（员工ID）	调用方	提供方	✅ 考陪练侧已完成
2	获取岗位课程	调用方	提供方	✅ 考陪练侧已完成
3	搜索知识点	调用方	提供方	✅ 考陪练侧已完成
4	获取知识点详情	调用方	提供方	✅ 考陪练侧已完成

API 接入信息（瑞小美自用）

项目	值
API 基础地址	https://aiedu.ireborn.com.cn/api/v1/scrm
认证方式	Bearer Token
API Key	scrm-kpl-api-key-2026-ruixiaomei
请求头格式	Authorization: Bearer {API_KEY}

快速测试

# ⭐ 推荐：通过姓名搜索员工岗位（适用于未配置企微userid的场景）
curl -X GET "https://aiedu.ireborn.com.cn/api/v1/scrm/employees/search/by-name?name=余丹丹" \
  -H "Authorization: Bearer scrm-kpl-api-key-2026-ruixiaomei"

# 通过企微userid获取员工岗位
curl -X GET "https://aiedu.ireborn.com.cn/api/v1/scrm/employees/zhangxiaomei_001/position" \
  -H "Authorization: Bearer scrm-kpl-api-key-2026-ruixiaomei"

# 通过员工ID精确查询（用于多个同名员工时）
curl -X GET "https://aiedu.ireborn.com.cn/api/v1/scrm/employees/by-id/367/position" \
  -H "Authorization: Bearer scrm-kpl-api-key-2026-ruixiaomei"

# 搜索知识点
curl -X POST "https://aiedu.ireborn.com.cn/api/v1/scrm/knowledge-points/search" \
  -H "Authorization: Bearer scrm-kpl-api-key-2026-ruixiaomei" \
  -H "Content-Type: application/json" \
  -d '{"keywords": ["热玛吉"], "limit": 5}'

---

职责边界说明

功能	负责方	说明
知识点数据存储	考陪练	知识点、课程、岗位关系
数据查询API	考陪练	本文档定义的4个API
短板分析	SCRM AI功能	三维度分析模型
知识点匹配	SCRM AI功能	根据短板匹配知识点
30秒精简版生成	SCRM AI功能	AI从原始内容提炼
动态出题	SCRM AI功能	AI根据知识点生成测验题
企微推送	SCRM AI功能	发送卡片消息
效果追踪	SCRM AI功能	应用检测、分数对比
管理后台	SCRM 门户	知识点推送模块

---

创建于 2026-01-17 更新于 2026-01-17 - 简化为纯数据查询API，动态出题由SCRM完成 更新于 2026-01-17 - 考陪练侧4个API已开发完成并测试通过