sync: 开发文档 需求 | 原因: 需求文档更新

开发文档/10、项目管理/存客宝协作需求.md

@@ -0,0 +1,78 @@
+# 存客宝协作需求（待发给存客宝 / 神射手团队）
+
+> 更新时间：2026-03-08
+> 来源：找伙伴功能开发中，需要存客宝方配合开发/开放的接口
+
+---
+
+## 需求一：场景获客接口回馈 — 添加好友成功率反馈
+
+**状态**：待开发
+
+**背景**：当前 scenarios API（`POST https://ckbapi.quwanzhi.com/v1/api/scenarios`）上报线索后只返回「新增成功 / 已存在」，无法知道该线索是否已被微信添加好友。
+
+**需求**：在 scenarios 响应中新增字段，返回该线索的微信添加状态：
+- `friendStatus`: `added`（已添加）/ `pending`（待添加）/ `failed`（添加失败）
+- `friendAddedAt`: 添加成功时间（ISO 8601）
+
+---
+
+## 需求二：线索查询接口 — 按手机号/微信号查询添加结果
+
+**状态**：待开发
+
+**背景**：后台需要查看某个匹配用户在存客宝中的状态（是否已加好友、属于哪个计划、有哪些标签等）。
+
+**需求**：提供一个查询接口：
+- **方式**：`GET /v1/api/lead/query`
+- **参数**：`apiKey`、`sign`、`timestamp`、`phone`（或 `wechatId`）
+- **返回**：
+  ```json
+  {
+    "code": 200,
+    "data": {
+      "phone": "138xxxx",
+      "wechatId": "xxx",
+      "friendStatus": "added",
+      "friendAddedAt": "2026-03-08T10:00:00+08:00",
+      "plan": "创业实验-资源对接",
+      "tags": ["资源对接", "高意向"],
+      "createdAt": "2026-03-07T08:00:00+08:00"
+    }
+  }
+  ```
+
+---
+
+## 需求三：批量线索统计接口 — 查询某时间段内的添加成功率
+
+**状态**：待确认
+
+**背景**：后台「找伙伴统计」页面需要展示一段时间内的线索上报总量、添加好友成功率等数据。
+
+**需求**：提供一个统计接口：
+- **方式**：`GET /v1/api/lead/stats`
+- **参数**：`apiKey`、`sign`、`timestamp`、`startDate`、`endDate`、`source`（可选，按来源筛选）
+- **返回**：
+  ```json
+  {
+    "code": 200,
+    "data": {
+      "totalLeads": 150,
+      "friendAdded": 120,
+      "friendPending": 25,
+      "friendFailed": 5,
+      "successRate": 80.0,
+      "byPlan": [
+        { "plan": "创业实验-创业合伙", "total": 50, "added": 42 },
+        { "plan": "创业实验-资源对接", "total": 40, "added": 35 }
+      ]
+    }
+  }
+  ```
+
+---
+
+## 发送方式
+
+将本文档发给存客宝技术团队（或神射手），确认排期后更新状态。