Skip to content

何博文 / hro_prd_dock

Go to a project
Commit 5dfdc094 by 王雷
Options

更新api-doc

parent c93ac586
Inline Side-by-side
Showing with 58 additions and 7 deletions
亲亲创客二期/文档/前端/api-doc.md
# partner-mp 接口说明文档 # partner-mp 接口说明文档
...@@ -4,6 +4,22 @@ ...@@ -4,6 +4,22 @@
> 依据：`design-export/01-登录及申请.dc.html`、`02-合伙人.dc.html`、`03-介绍人视图.dc.html`、`04-对接人视图.dc.html` 四份交互原型 + 现有前端代码（`packages/partner-mp/src`） > 依据：`design-export/01-登录及申请.dc.html`、`02-合伙人.dc.html`、`03-介绍人视图.dc.html`、`04-对接人视图.dc.html` 四份交互原型 + 现有前端代码（`packages/partner-mp/src`）
> 说明：四份原型是**交互原型**，不是视觉设计稿；本文档只关心页面需要什么数据、什么接口，不涉及颜色/间距等视觉内容。 > 说明：四份原型是**交互原型**，不是视觉设计稿；本文档只关心页面需要什么数据、什么接口，不涉及颜色/间距等视觉内容。
> 更新日期：2026-07-06（追加 P5-P8 审核流程接口、合伙人搜索接口） > 更新日期：2026-07-06（追加 P5-P8 审核流程接口、合伙人搜索接口）
> 更新日期：2026-07-07（02 原型 P8/P9 字段级复核，新增合伙人线索列表/提交接口，`customer_collect_list`/`get_deal_settlement` 新增字段与分页需求，详见下方【本次更新汇总】）
---
## 【本次更新汇总】2026-07-07
本次是在已有页面级结论基础上做的**字段级复核**，以下是新增/修改的接口需求，需要后端重点关注：
| 类型 | 接口 | 内容 | 详情章节 |
| --- | --- | --- | --- |
| 🆕 新增接口 | `partner_opportunity_list`（占位名） | 合伙人视角的线索/商机列表，按"我提交的"过滤，字段参考对接人 `opportunity_list` | §3.4 |
| 🆕 新增接口 | `partner_lead_create`（占位名） | 合伙人提交新线索，替代旧的 `create_lead_suggestion`，需实现去重检测 | §3.4 |
| ✏️ 修改接口 | `customer_collect_list` | 详情场景建议新增 `first_deal_status`（首次成单状态）字段 | §3.3 |
| ✏️ 修改接口 | `customer_order_list` | 需新增 `page`/`page_size` 分页支持 + 响应总数字段（单客户订单已超 200 条） | §3.3 |
| ✏️ 修改接口 | `get_deal_settlement` | 需新增 `page`/`page_size` 分页支持 + 响应总数字段（合伙人佣金明细已超 200 条） | §3.5 |
| ⚠️ 旧接口保留 | `create_lead_suggestion` / `referral-clue.vue` | 前端已不再引用此入口，但代码和接口暂不下线 | §3.4 |
--- ---
...@@ -102,27 +118,36 @@ sdk.domainServicePost("接口名", { data, params }, isAnonymous, subProjectName ...@@ -102,27 +118,36 @@ sdk.domainServicePost("接口名", { data, params }, isAnonymous, subProjectName
| 接口名 | 形式 | 代码位置 | 请求字段 | 响应字段 | 用途 | | 接口名 | 形式 | 代码位置 | 请求字段 | 响应字段 | 用途 |
| ----------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ----------------------------------- | | ----------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ----------------------------------- |
| `customer_collect_list` | domain service | [my-customers.vue:139](../src/pages/subpackages/customer/my-customers.vue#L139)、[customer-detail.vue:252](../src/pages/subpackages/customer/customer-detail.vue#L252) | `user_combo`（搜索）、`deal_date`（成交时间筛选）、`page`、`page_size` | `data_list[]`（含 `order_amount`, `order_commission`）、`rc_count` | 合伙人"我的客户"列表 + 客户详情汇总 | | `customer_collect_list` | domain service | [my-customers.vue:139](../src/pages/subpackages/customer/my-customers.vue#L139)、[customer-detail.vue:252](../src/pages/subpackages/customer/customer-detail.vue#L252) | `user_combo`（搜索）、`deal_date`（成交时间筛选）、`page`、`page_size` | `data_list[]`（含 `order_amount`, `order_commission`）、`rc_count`（**✏️修改：详情场景建议新增 `first_deal_status`**） | 合伙人"我的客户"列表 + 客户详情汇总 |
| `customer_order_list` | domain service | [customer-detail.vue:278](../src/pages/subpackages/customer/customer-detail.vue#L278) | `UserMemberId` | `orders[]`（`order_amount, order_commission, order_fee_amount, product_type`） | 客户详情页的订单明细 | | `customer_order_list` | domain service | [customer-detail.vue:278](../src/pages/subpackages/customer/customer-detail.vue#L278) | `UserMemberId`（**✏️修改：需新增 `page, page_size`**） | `orders[]`（`order_amount, order_commission, order_fee_amount, product_type`）（**✏️修改：需新增总数字段**） | 客户详情页的订单明细 |
**⚠️ 本次新需求是否需要改动**： **⚠️ 本次新需求是否需要改动**：
1. 02 原型 P2 逻辑注释要求客户列表能区分归属来源（本人直推成交 / 本人提交商机成单 / 落地页扫码绑定），当前响应字段里没有看到来源标记，建议补充 `source_type` 字段。 1. 02 原型 P2 逻辑注释要求客户列表能区分归属来源（本人直推成交 / 本人提交商机成单 / 落地页扫码绑定），当前响应字段里没有看到来源标记，建议补充 `source_type` 字段。
2. 02 原型 P3 客户详情要求展示"来源渠道"、"意向产品"、"首次成单"状态、"邀请合伙人"字段，当前 `customer_collect_list` 详情场景返回的字段需要核对是否已覆盖这些。 2. 02 原型 P3 客户详情要求展示"来源渠道"、"意向产品"、"首次成单"状态、"邀请合伙人"字段，当前 `customer_collect_list` 详情场景返回的字段需要核对是否已覆盖这些。
3. **【新增】`customer_collect_list` 详情场景（`UserMemberId` 精确查询）建议补充 `first_deal_status` 字段**（首次成单状态，如"已成单"/"待成单"），前端 [customer-detail.vue](../src/pages/subpackages/customer/customer-detail.vue) 头部卡片已加好展示位（`v-if="detail.first_deal_status"`），字段没有值时不显示，等接口补充后自动生效。
4. **【新增】`customer_order_list` 需要支持分页**：客户单个详情页订单已达 200+ 条，当前接口调用只传 `UserMemberId`，一次性拉全量；前端已按 `page`/`page_size` 参数传参（[customer-detail.vue:283](../src/pages/subpackages/customer/customer-detail.vue#L283)），需要后端确认接口是否已支持这两个参数、以及响应里是否有 `rc_count`/`total` 之类的总数字段供前端判断是否还有更多。
### 3.4 推荐线索 / 商机（对应 02 · P8/P9，合伙人视角） ### 3.4 推荐线索 / 商机（对应 02 · P8/P9，合伙人视角）
| 接口名 | 形式 | 代码位置 | 请求字段 | 用途 | | 接口名 | 形式 | 代码位置 | 请求字段 | 用途 |
| ------------------------------------------ | -------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- | ------------------------------------------------ | | ------------------------------------------ | -------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| `partner_users` / `create_lead_suggestion` | uniplat model action | [referral-clue.vue:249](../src/pages/subpackages/other/referral-clue.vue#L249) | `{suggestion_type, customer_name, customer_mobile, intention_products, partner_uid, firm_name}` | 提交客户推荐/线索（对应 02 原型 P9"提交新线索"） | | `partner_users` / `create_lead_suggestion` | uniplat model action | [referral-clue.vue:249](../src/pages/subpackages/other/referral-clue.vue#L249) | `{suggestion_type, customer_name, customer_mobile, intention_products, partner_uid, firm_name}` | ⚠️旧版提交表单接口，**保留但不再被入口引用** |
| `get_product_list` | domain service | [pop-tabs-select.vue:309](../src/components/common/pop-tabs-select.vue#L309) | `{category_type, load_product}` | 提交线索时选择意向产品的分类树 | | `get_product_list` | domain service | [pop-tabs-select.vue:309](../src/components/common/pop-tabs-select.vue#L309) | `{category_type, load_product}` | 提交线索时选择意向产品的分类树 |
**⚠️ 本次新需求是否需要改动**： **⚠️ 本次新需求是否需要改动**：
1. 02 原型 P8"推荐线索"列表（跟进中/已成单/已作废 tab，含合伙人/对接人/渠道管理员字段）**当前前端没有对应页面代码**，只有提交表单（`referral-clue.vue`）有接口，列表页本身还没实现，需要新增列表查询接口。 1. 02 原型 P8"推荐线索"列表（跟进中/已成单/已作废 tab，含合伙人/对接人/渠道管理员字段）**当前前端没有对应页面代码**，只有提交表单（`referral-clue.vue`）有接口，列表页本身还没实现，需要新增列表查询接口。—— **已按此新建前端页面，详见下方【新增】说明**。
2. 02 P9 逻辑注释要求的"去重检测"（同客户+同产品+进行中状态 → 不新建，只刷新更新时间并提示）需要后端在 `create_lead_suggestion` 里实现，或者前端调用前先查询判断。 2. 02 P9 逻辑注释要求的"去重检测"（同客户+同产品+进行中状态 → 不新建，只刷新更新时间并提示）需要后端在 `create_lead_suggestion` 里实现，或者前端调用前先查询判断。
3. **这里的"商机"和 04 对接人视角的"商机"是同一份数据的两个查看角度**，建议后端只建一套商机表，通过角色权限控制查询范围，具体见「四、当前完全没有的接口」的商机模块说明。 3. **这里的"商机"和 04 对接人视角的"商机"是同一份数据的两个查看角度**，建议后端只建一套商机表，通过角色权限控制查询范围，具体见「四、当前完全没有的接口」的商机模块说明。
**🆕【新增】合伙人线索列表 + 提交线索（前端已实现页面，等待后端接口）**
- 新增页面：[lead-list.vue](../src/pages/subpackages/other/lead-list.vue)（列表，tabs：跟进中/暂时挂起/已成单/已作废）、[lead-create.vue](../src/pages/subpackages/other/lead-create.vue)（提交表单：客户类型/企业名称/联系人/联系电话/可能的产品多选）。首页统计三宫格"推荐记录"入口、首页"推荐线索"banner 均已改为跳转 `lead-list.vue`。
- 新增接口（占位接口名 `partner_opportunity_list`，需后端确认最终命名）：请求字段 `status`（3跟进中/4暂时挂起/5已成单/6已作废）、`search_key`（客户/产品搜索）、`page`、`page_size`；响应字段参考对接人视角 `opportunity_list` 的结构（`opportunity_id, code, customer_name, product_name, contactor_name, channel_admin_name, source, create_time, update_time, status, status_code`），区别只是按"我提交的"（合伙人=当前登录用户）过滤，建议复用同一张商机表。
- 新增接口（占位接口名 `partner_lead_create`，需后端确认最终命名）：请求字段 `customer_type, customer_name, product_ids[], contact_name, contact_mobile`；用于替代旧的 `create_lead_suggestion`，需要实现「三、3.4」第2条提到的去重检测逻辑。
- 旧的 `referral-clue.vue` 页面和 `create_lead_suggestion` 接口**保留代码但不再被任何入口引用**，待新接口落地验证后再决定是否彻底下线。
### 3.5 我的佣金（对应 02 · P4） ### 3.5 我的佣金（对应 02 · P4）
统一定义在 [commission/request.ts](../src/pages/subpackages/commission/request.ts)，均为领域服务，`subProjectName` 主要是 `welfare_bean`/`reward_account_api`： 统一定义在 [commission/request.ts](../src/pages/subpackages/commission/request.ts)，均为领域服务，`subProjectName` 主要是 `welfare_bean`/`reward_account_api`：
...@@ -136,10 +161,12 @@ sdk.domainServicePost("接口名", { data, params }, isAnonymous, subProjectName ...@@ -136,10 +161,12 @@ sdk.domainServicePost("接口名", { data, params }, isAnonymous, subProjectName
| `apply_record_list` | `page_index, page_size` | `list[]`（`cash_type_name, amount, create_time`） | 提现记录列表 | | `apply_record_list` | `page_index, page_size` | `list[]`（`cash_type_name, amount, create_time`） | 提现记录列表 |
| `apply_payee_info` | — | — | 收款账户信息 | | `apply_payee_info` | — | — | 收款账户信息 |
| `apply_record_detail` | `id`（apply_id） | — | 提现记录详情 | | `apply_record_detail` | `id`（apply_id） | — | 提现记录详情 |
| `get_deal_settlement` | `status, type` | `balance, settled_commission, pending_commission, total_commission, list[]`（`ID, DocNo, ProductName, ServiceTypeName, UserName, CreateDate, CheckDate, Status, StatusName, Amount, Commission, RuleSnapshot`） | 我的佣金余额+明细（02 原型 P4 的主要数据源） | | `get_deal_settlement` | `status, type`（**【修改】需新增 `page, page_size`**） | `balance, settled_commission, pending_commission, total_commission, list[]`（`ID, DocNo, ProductName, ServiceTypeName, UserName, CreateDate, CheckDate, Status, StatusName, Amount, Commission, RuleSnapshot`）（**【修改】需新增总数字段如 `total`/`rc_count`**） | 我的佣金余额+明细（02 原型 P4 的主要数据源） |
**⚠️ 本次新需求是否需要改动**：`get_deal_settlement` 的结构是"可提现余额"模型（合伙人专用），04 原型的对接人佣金是"次月工资发放，无提现"模型，字段维度也不同（对接人要看"已结算订单数"，合伙人模型里没有这个字段）。这两种模型是否共用一张结算表、只是展示口径不同，还是完全独立的两套逻辑，需要和后端确认（详见「四」中的商机/订单模块说明）。 **⚠️ 本次新需求是否需要改动**：`get_deal_settlement` 的结构是"可提现余额"模型（合伙人专用），04 原型的对接人佣金是"次月工资发放，无提现"模型，字段维度也不同（对接人要看"已结算订单数"，合伙人模型里没有这个字段）。这两种模型是否共用一张结算表、只是展示口径不同，还是完全独立的两套逻辑，需要和后端确认（详见「四」中的商机/订单模块说明）。
**【修改】需要支持分页**：合伙人佣金明细已积累 200+ 条，当前接口一次性返回全量列表，前端已改造为按 `page`/`page_size` 分页加载（[commission/request.ts](../src/pages/subpackages/commission/request.ts)、[my-commission.vue](../src/pages/subpackages/commission/my-commission.vue)，滚动到底部触发加载下一页），需要后端确认接口支持这两个参数，并在响应里补充总数字段（`total` 或类似）供前端判断是否还有更多数据。
### 3.6 产品（对应 01 首页 + 02 · P5/P6） ### 3.6 产品（对应 01 首页 + 02 · P5/P6）
| 接口名 | 形式 | 代码位置 | 请求字段 | 响应字段 | 用途 | | 接口名 | 形式 | 代码位置 | 请求字段 | 响应字段 | 用途 |
......
亲亲创客二期/文档/联调记录.md
```markdown ```markdown
...@@ -158,4 +158,28 @@ api文档：《api-doc-第四点新增接口.md》 ...@@ -158,4 +158,28 @@ api文档：《api-doc-第四点新增接口.md》
描述：[services/type.ts](../../../packages/partner-mp/src/services/type.ts) 中 `isIntroducer` 已读取 `userInfo2.is_introducer` 作为真实字段（此前分配02已接入），无需改动，等待后端在 `user_info` 响应里补上该字段即可生效 描述：[services/type.ts](../../../packages/partner-mp/src/services/type.ts) 中 `isIntroducer` 已读取 `userInfo2.is_introducer` 作为真实字段（此前分配02已接入），无需改动，等待后端在 `user_info` 响应里补上该字段即可生效
### 🔴改动15（需后端配合，待跟进）
api文档：《api-doc.md》
接口：三、3.4 推荐线索/商机（对应 02·P8/P9，合伙人视角）—— 新增合伙人线索列表/提交接口
描述：针对 02-合伙人.dc.html 原型做字段级复核，发现合伙人角色一直缺"推荐线索"列表页（只有提交表单 `referral-clue.vue`，无跟进中/暂时挂起/已成单/已作废的列表和状态展示）。已新建 [lead-list.vue](../../../packages/partner-mp/src/pages/subpackages/other/lead-list.vue)（列表，参考 opportunity-list 结构）和 [lead-create.vue](../../../packages/partner-mp/src/pages/subpackages/other/lead-create.vue)（提交表单，结构与 opportunity-create 保持一致，后续可能随其调整），并在 pages.json 注册路由；首页统计三宫格"推荐记录"入口（[statistics.vue](../../../packages/partner-mp/src/pages/home/components/statistics.vue)）和首页"推荐线索"banner（[Banner.vue](../../../packages/partner-mp/src/pages/home/components/Banner.vue)）均改为跳转 `lead-list.vue`。旧的 `referral-record.vue`（调用废弃接口 `recommend_list`）和 `referral-clue.vue`（调用 `create_lead_suggestion`）保留代码但不再被任何入口引用。**缺后端新增两个接口**：合伙人线索列表（占位接口名 `partner_opportunity_list`）、合伙人提交线索（占位接口名 `partner_lead_create`，需实现同客户+同产品去重检测），已写入 api-doc.md「三、3.4」及文档顶部【本次更新汇总】。
### 🔴改动16（需后端配合，待跟进）
api文档：《api-doc.md》
接口：三、3.3 我的客户（对应 02·P2/P3）—— customer_collect_list 新增字段 / customer_order_list 分页
描述：[customer-detail.vue](../../../packages/partner-mp/src/pages/subpackages/customer/customer-detail.vue) 头部卡片新增"首次成单"展示位（`v-if="detail.first_deal_status"`），**缺后端在 `customer_collect_list` 详情场景补充 `first_deal_status` 字段**，字段没有值时不显示，不影响现有功能。另外客户详情订单列表 `customer_order_list` 已积累 200+ 条，前端已按 `page`/`page_size` 传参改造分页加载（[customer-detail.vue](../../../packages/partner-mp/src/pages/subpackages/customer/customer-detail.vue)），**缺后端确认接口是否已支持这两个参数、并补充响应总数字段**。
### 🔴改动17（需后端配合，待跟进）
api文档：《api-doc.md》
接口：三、3.5 我的佣金（对应 02·P4）—— get_deal_settlement 分页
描述：合伙人佣金明细已积累 200+ 条，`get_deal_settlement` 当前一次性返回全量列表，前端已改造为按 `page`/`page_size` 分页加载、滚动到底部触发下一页（[commission/request.ts](../../../packages/partner-mp/src/pages/subpackages/commission/request.ts)、[my-commission.vue](../../../packages/partner-mp/src/pages/subpackages/commission/my-commission.vue)），**缺后端确认接口支持这两个参数、并在响应里补充总数字段**。
# 后端 # 后端
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or sign in to comment