From 9f515e3998f2d927907d5a67c9e267a2680e7e37 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=8D=A1=E8=8B=A5?= <karuo@MacBook-Pro.local>
Date: Sun, 8 Mar 2026 10:34:54 +0800
Subject: [PATCH] =?UTF-8?q?sync:=20=E5=BC=80=E5=8F=91=E6=96=87=E6=A1=A3=20?=
 =?UTF-8?q?=E9=9C=80=E6=B1=82=20|=20=E5=8E=9F=E5=9B=A0:=20=E9=9C=80?=
 =?UTF-8?q?=E6=B1=82=E6=96=87=E6=A1=A3=E6=9B=B4=E6=96=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 开发文档/10、项目管理/存客宝协作需求.md | 78 +++++++++++++++++++++++++
 1 file changed, 78 insertions(+)
 create mode 100644 开发文档/10、项目管理/存客宝协作需求.md

diff --git a/开发文档/10、项目管理/存客宝协作需求.md b/开发文档/10、项目管理/存客宝协作需求.md
new file mode 100644
index 00000000..d51629f1
--- /dev/null
+++ b/开发文档/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 }
+      ]
+    }
+  }
+  ```
+
+---
+
+## 发送方式
+
+将本文档发给存客宝技术团队（或神射手），确认排期后更新状态。