体培通三方知识库对接 API

1. 鉴权

X-Knowledge-Integration-Key: <your_api_key>
X-Tenant-Id: 1                 # 可选；若你的 Key 已绑定租户可省略

2. Endpoint 速查

3. 教案包（lesson-pack）

一次提交多个教案，每个教案会同步落到 KB 文章 + 教案模板 + 视频库三张表。

请求示例

POST /api/v1/qx/tpt/integration/v1/lesson-pack
X-Knowledge-Integration-Key: ckp_xxx
Content-Type: application/json

{
  "batch_no": "AC-2026Q2-FOOTBALL-U12",
  "items": [
    {
      "external_id": "ac-2026-001",
      "title": "U12 1v1 突破：左路 step-over",
      "category_id": 1,
      "corner_focus": ["technical"],
      "age_range": [10, 14],
      "duration_min": 60,
      "rpe_target": 6,
      "body_md": "# 教练说明\n...",
      "drills": { "warmup":[...], "main":[...], "cooldown":[...] },
      "evaluation_schema": { ... },
      "equipment": ["cone", "ball"],
      "videos": [
        {"external_id":"ac-vid-1","kind":"demo","cos_url":"https://...","duration_sec":120}
      ],
      "tags": ["method:coerver","sport:football"]
    }
  ]
}

响应

{
  "code": 200,
  "data": {
    "batch_no": "AC-2026Q2-FOOTBALL-U12",
    "status": "success",
    "success": 1,
    "failed": 0,
    "result_map": {
      "ac-2026-001": {
        "article_id": 9831,
        "lesson_template_id": 552,
        "video_ids": [3120]
      }
    }
  }
}

4. 视频包（video-pack）

纯视频批量入库，可选关联 corner 标签便于后续按四角检索。

POST /api/v1/qx/tpt/integration/v1/video-pack
{ "batch_no": "AC-VID-2026Q2", "items": [
  { "external_id":"v1","kind":"demo","title":"...","cos_url":"...","corner_focus":["technical"] }
] }

5. 教练培训课程包（coach-course-pack）

一次提交 1 个 进阶通道 + N 个课程，自动绑定。

POST /api/v1/qx/tpt/integration/v1/coach-course-pack
{
  "batch_no": "AC-COACH-2026Q2",
  "track": {
    "code": "academy-coerver-l2",
    "name": "Coerver L2 高级控球",
    "sport": "football",
    "level": "L2"
  },
  "courses": [
    { "external_id":"c1","title":"控球大师 · 8 字绕桩","difficulty":"intermediate","credits":2,"duration_min":45 },
    { "external_id":"c2","title":"1v1 防守反应","difficulty":"intermediate","credits":2 }
  ]
}

6. 幂等性与状态查询

• 幂等：(partner_id, batch_no) 是唯一键。重复 POST 同 batch_no 直接返回首次结果，不会重复入库。
• 原子性：单批 ≤ 500 条。批次内部失败逐项标错，整体不回滚（结果中 failed 字段会标明数量）。
• 状态查询：GET /api/v1/qx/tpt/integration/v1/status?batch_no=xxx

7. 命名空间与标签

所有写入的内容会自动附加以下标签便于审计与版权追踪：

tags: [
  "partner:<your_partner_code>",
  "purchased_pack:<batch_no>",
  // ...你传入的自定义标签
]

8. 配额与速率

默认配额（可按合作协议调整）：

• 每月文章配额：10,000 条
• 每月视频配额：5,000 条
• 每分钟速率：60 次

超出时返回 HTTP 429 quota exceeded。

可通过 GET /api/v1/qx/tpt/integration/v1/partner/me 查询当前用量。

9. 错误码