Skip to content

何博文 / hro_prd_dock

Go to a project
Commit 2d29932c by 刘铭阳
Options

Merge remote-tracking branch 'origin/master'

parents c6056900 48bb8c66
Inline Side-by-side
Showing with 151 additions and 66 deletions
亲亲创客二期/文档/前端/api-doc.md
# partner-mp 接口说明文档
# partner-mp 接口说明文档
......@@ -5,6 +5,8 @@
> 说明：四份原型是**交互原型**，不是视觉设计稿；本文档只关心页面需要什么数据、什么接口，不涉及颜色/间距等视觉内容。
> 更新日期：2026-07-06（追加 P5-P8 审核流程接口、合伙人搜索接口）
> 更新日期：2026-07-07（02 原型 P8/P9 字段级复核，新增合伙人线索列表/提交接口，`customer_collect_list`/`get_deal_settlement` 新增字段与分页需求，详见下方【本次更新汇总】）
> 更新日期：2026-07-07（对接后端 `api-doc-第四点新增接口.md` 「四、20260706补充接口」，`get_partner_users`/`opportunity_create.user_type` 已接入前端，详见下方【本次更新汇总】）
> 更新日期：2026-07-07（对接后端 `api-doc-第四点新增接口.md` 「五、20260707补充接口」，`partner_opportunity_list`/`partner_lead_create` 按后端最终字段调整前端实现，详见下方【本次更新汇总】）
---
......@@ -12,14 +14,37 @@
本次是在已有页面级结论基础上做的**字段级复核**，以下是新增/修改的接口需求，需要后端重点关注：
| 类型 | 接口 | 内容 | 详情章节 |
| --- | --- | --- | --- |
| 🆕 新增接口 | `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 |
| ------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------- |
| ✅ 已对接（详见下方 07-07「五」汇总） | `partner_opportunity_list` | 合伙人视角的线索/商机列表，按"我提交的"过滤，字段已按后端口径接入（联系人字段仍缺，见 §3.4🔴待补充） | §3.4 |
| ✅ 已对接（详见下方 07-07「五」汇总） | `partner_lead_create` | 合伙人提交新线索，已替代旧的`create_lead_suggestion`，去重检测由后端实现 | §3.4 |
| ✅ 已对接（详见下方 07-07「五」汇总） | `customer_collect_list` | 详情场景新增`first_deal_status`（首次成单状态）字段 | §3.3 |
| ✅ 已对接（详见下方 07-07「五」汇总） | `customer_order_list` | 已新增`page`/`page_size` 分页支持 + 响应总数字段 `total`/`rc_count`（单客户订单已超 200 条） | §3.3 |
| ✅ 已对接（详见下方 07-07「五」汇总） | `get_deal_settlement` | 已新增`page`/`page_size` 分页支持 + 响应总数字段 `total`（合伙人佣金明细已超 200 条） | §3.5 |
| ⚠️ 旧接口保留 | `create_lead_suggestion` / `referral-clue.vue` | 前端已不再引用此入口，但代码和接口暂不下线 | §3.4 |
| ✅ 已对接 | `get_partner_users` | 04·P6b 关联合伙人搜索，`partner-drawer.vue` 已从 mock 切换为真实接口，固定传 `type:"all"` | 见下方新增小节 |
| ✅ 已对接 | `opportunity_create` 新增 `user_type` | 表单`customer_type`（企业客户/个人客户）已映射为 `user_type`(1/2) 随请求提交，`partner_id` 同步补提交（此前引入但漏提交） | 见下方新增小节 |
| 📝 待办（不阻塞，前端待对接） | `partner_info.review_remark` | 字段已具备，随 `user_info` 一起返回；前端页面尚未接入（`audit-pending.vue`/`audit-failed.vue`），见 §4.3 | 见下方新增小节 |
---
## 【本次更新汇总】2026-07-07（对接后端「五、20260707补充接口」）
后端已给出 `partner_opportunity_list`/`partner_lead_create` 正式字段（`api-doc-第四点新增接口.md` 「五」），与前端此前的占位实现有几处不一致，已按后端口径改造：
| 类型 | 接口 | 内容 | 详情章节 |
| ------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
| ✏️ 已按后端口径改造 | `partner_opportunity_list` | `status` 参数由前端占位的数字码（3/4/5/6，4 个 tab）改为后端要求的字符串（`""`/`"all"`全部、`in_progress`进行中=待审核+待分配+跟进中+暂时挂起合并、`"5"`已成单、`"6"`已作废），`lead-list.vue` tab 结构同步改为"全部/进行中/已成单/已作废" | §3.4 |
| ✏️ 已按后端口径改造 | `partner_opportunity_list` | 响应新增`partner_name`（=本人）字段，`LeadListItem` 类型定义同步补充 | §3.4 |
| ✏️ 已按后端口径改造 | `partner_lead_create` | `customer_type` 由前端占位的字符串改为后端要求的 `int`(1企业/2个人)，`lead-create.vue` 补充映射表后随请求提交（此前完全没做这层映射） | §3.4 |
| 📝 文档口径更新 | `partner_lead_create` 去重逻辑 | 去重维度由此前记录的"客户+产品"二维更新为后端明确的"客户名称+联系人手机号+产品"三维 | §3.4 |
| 📝 新增约束，前端暂不处理 | `partner_lead_create` | 后端明确"仅审核通过的合伙人可提交"，前端不加前置拦截，未通过时交给后端报错提示 | §3.4 |
| ✏️ 已优化（非阻塞） | `customer_order_list` | 分页`hasMore` 判断由 `data.length >= pageSize` 的近似判断改为读取响应 `total`/`rc_count` 精确判断，避免多翻一页空请求 | §3.3 |
| ✅ 确认无需改动 | `customer_collect_list.first_deal_status` | 后端补充取值口径（已成单/已注册/已创建/已留资），前端展示逻辑已就绪，无需改代码 | §3.3 |
| ✅ 确认无需改动 | `customer_order_list`/`get_deal_settlement` 分页 | 前端分页传参已与后端一致 | §3.3/§3.5 |
| ✅ 确认无需改动 | 介绍人身份判定收紧（"审核通过的合伙人"口径） | 后端明确纯后端口径调整，前端无需改动 | §一 |
---
......@@ -27,8 +52,9 @@
项目里有三种业务身份，彼此**独立、可叠加**，不是互斥的单选状态（除了下面标注的一组互斥关系）：
| 身份 | 判定方式 | 与其他身份的关系 |
| ---------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| ---------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **普通用户** | 登录但不满足任何角色条件 | 基础态 |
| **合伙人**（`is_partner`） | 通过 P4 表单申请，后台审核通过 | 与"对接人"**互斥**：一个用户不会同时是合伙人又是对接人 |
| **对接人**（`is_contactor`） | 由后台/渠道管理员指派，员工身份 | 与"合伙人"**互斥**；对接人默认同时拥有"介绍人"资格（见下） |
......@@ -90,48 +116,53 @@ sdk.domainServicePost("接口名", { data, params }, isAnonymous, subProjectName
### 3.1 登录鉴权（对应 01 · P1/P2）
| 接口名 | 形式 | 代码位置 | 用途 |
| ---------------------------------------------------- | -------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `loginWithWechat` | domain service | [wechat-login.ts:120](../src/modules/passport/wechat-login.ts#L120) | 微信授权登录，请求 `{code, appid, client_id}` |
| `check_miniapp_is_bind` | domain service | [wechat-login.ts:259](../src/modules/passport/wechat-login.ts#L259) | 判断当前小程序 openid 是否已绑定账号，响应 `{userid, username}` |
| `bind_phone` | domain service | [wechat-login.ts:281](../src/modules/passport/wechat-login.ts#L281) | 绑定手机号，请求 `{appid, code, client_id, encryptedData, iv}` |
| ----------------------------------------------------- | -------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `loginWithWechat` | domain service | [wechat-login.ts:120](../src/modules/passport/wechat-login.ts#L120) | 微信授权登录，请求`{code, appid, client_id}` |
| `check_miniapp_is_bind` | domain service | [wechat-login.ts:259](../src/modules/passport/wechat-login.ts#L259) | 判断当前小程序 openid 是否已绑定账号，响应`{userid, username}` |
| `bind_phone` | domain service | [wechat-login.ts:281](../src/modules/passport/wechat-login.ts#L281) | 绑定手机号，请求`{appid, code, client_id, encryptedData, iv}` |
| `bind_miniapp` / `bind` | domain service | [wechat-login.ts:166](../src/modules/passport/wechat-login.ts#L166) | 换绑小程序账号 |
| `user_info` | domain service | [services/common.ts:123](../src/services/common.ts#L123) | 登录后轮询获取用户信息，直到 `r.user_info` 存在或 `code===1099`（账号封禁） |
| `user_info` | domain service | [services/common.ts:123](../src/services/common.ts#L123) | 登录后轮询获取用户信息，直到`r.user_info` 存在或 `code===1099`（账号封禁） |
| `refresh_login` | domain service | [passport/login.ts:475](../src/modules/passport/login.ts#L475) | 刷新登录态 |
| `uniplat_base/system.user` → `info` / `citizen_info` | uniplat model | [store/user-info.ts:70](../src/store/user-info.ts#L70) | 获取用户信息 `UserInfo`（`sub, uid, name, realname, mobile, avatar...`）与实名信息 `UserVerifyInfo`（`citizen_no, citizen_verified, realname...`） |
| `uniplat_base/system.user` → `info` / `citizen_info` | uniplat model | [store/user-info.ts:70](../src/store/user-info.ts#L70) | 获取用户信息`UserInfo`（`sub, uid, name, realname, mobile, avatar...`）与实名信息 `UserVerifyInfo`（`citizen_no, citizen_verified, realname...`） |
**⚠️ 本次新需求是否需要改动**：`UserInfo` 需要补充/确认 `is_partner`、`is_contactor`、`is_introducer` 三个身份字段是否已在响应里返回（当前前端代码里 `isIntroducer` 是占位实现，见「五、待确认疑点」第 2 条）。
### 3.2 申请成为合伙人（对应 01 · P4）
| 接口名 | 形式 | 代码位置 | 请求字段 | 用途 |
| ------------------------------------------------ | -------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `partner_users` / `join_partner`（查询表单配置） | uniplat model action | [more/components/index.ts:65](../src/pages/subpackages/more/components/index.ts#L65) | — | 获取 `role_kind`（身份类别：HR/财务/老板/猎头/博主/其他）下拉选项 |
| ------------------------------------------------ | -------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `partner_users` / `join_partner`（查询表单配置） | uniplat model action | [more/components/index.ts:65](../src/pages/subpackages/more/components/index.ts#L65) | — | 获取`role_kind`（身份类别：HR/财务/老板/猎头/博主/其他）下拉选项 |
| `partner_users` / `join_partner`（提交） | uniplat model action | [more/join.vue:203](../src/pages/subpackages/more/join.vue#L203) | `{name, id_card, mobile, contactor_uniplat_uid, role_kind, city, create_type:"2"}` | 提交合伙人申请 |
| `city_list` | domain service | [more/components/index.ts:41](../src/pages/subpackages/more/components/index.ts#L41) | — | 表单里的城市选择器数据源 |
**⚠️ 本次新需求是否需要改动**：
1. 01 原型 P4 逻辑注释提到"介绍人"字段（选填，提交后由渠道管理员匹配绑定，或来自邀请链接自动带入并锁定）——当前 `join_partner` 提交参数里没有看到介绍人相关字段，需要确认是否要新增 `introducer_uid` 之类的参数。身份证号是否强制必填也有矛盾（见待确认疑点第 3 条）。
2. **2026-07-06 原型新增 P5-P8 审核流程**：`partner_users` 表需补充审核状态相关字段（`audit_status` / `audit_time` / `reject_reason`），详见「四、4.3 合伙人审核流程」。前端需新增"合伙人审核状态查询"接口。
### 3.3 我的客户（对应 02 · P2/P3）
| 接口名 | 形式 | 代码位置 | 请求字段 | 响应字段 | 用途 |
| ----------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ----------------------------------- |
| `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`（**✏️修改：需新增 `page, page_size`**） | `orders[]`（`order_amount, order_commission, order_fee_amount, product_type`）（**✏️修改：需新增总数字段**） | 客户详情页的订单明细 |
| ----------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| `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`（**✅ 已支持 `page, page_size`**） | `orders[]`（`order_amount, order_commission, order_fee_amount, product_type`）（**✅ 已支持 `total`/`rc_count` 总数字段**） | 客户详情页的订单明细 |
**⚠️ 本次新需求是否需要改动**：
1. 02 原型 P2 逻辑注释要求客户列表能区分归属来源（本人直推成交 / 本人提交商机成单 / 落地页扫码绑定），当前响应字段里没有看到来源标记，建议补充 `source_type` 字段。
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. **✅ 已实现：`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+ 条，前端已按 `page`/`page_size` 参数传参并读取响应 `total`/`rc_count` 精确判断是否还有更多（[customer-detail.vue:283](../src/pages/subpackages/customer/customer-detail.vue#L283)）。
### 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}` | ⚠️旧版提交表单接口，**保留但不再被入口引用** |
| `get_product_list` | domain service | [pop-tabs-select.vue:309](../src/components/common/pop-tabs-select.vue#L309) | `{category_type, load_product}` | 提交线索时选择意向产品的分类树 |
......@@ -141,19 +172,20 @@ sdk.domainServicePost("接口名", { data, params }, isAnonymous, subProjectName
2. 02 P9 逻辑注释要求的"去重检测"（同客户+同产品+进行中状态 → 不新建，只刷新更新时间并提示）需要后端在 `create_lead_suggestion` 里实现，或者前端调用前先查询判断。
3. **这里的"商机"和 04 对接人视角的"商机"是同一份数据的两个查看角度**，建议后端只建一套商机表，通过角色权限控制查询范围，具体见「四、当前完全没有的接口」的商机模块说明。
**🆕【新增】合伙人线索列表 + 提交线索（前端已实现页面，等待后端接口）**
**✅ 已实现：合伙人线索列表 + 提交线索（对应后端「五、20260707补充接口」①②）**
- 新增页面：[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` 接口**保留代码但不再被任何入口引用**，待新接口落地验证后再决定是否彻底下线。
- 页面：[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`（[lead-request.ts](../src/pages/subpackages/other/lead-request.ts)）：请求字段 `status`（字符串，`""`/`"all"`全部、`in_progress`进行中=待审核+待分配+跟进中+暂时挂起合并、`"5"`已成单、`"6"`已作废）、`search_key`（客户名称模糊搜索）、`page`、`page_size`；响应字段 `opportunity_id, code, customer_name, customer_attr, product_name, partner_name, contactor_name, channel_admin_name, source, source_code, create_time, update_time, status, status_code`，与对接人视角 `opportunity_list` 同一张商机表，按"我提交的"（`partner_id`=当前登录用户）过滤。**🔴待补充**：02·P8 原型卡片有"联系人：姓名+手机号"展示，当前反参未提供 `contact_name`/`contact_mobile` 字段，前端已在 `LeadListItem` 加了可选字段兜底（无值不显示该行），需后端补充。
- `partner_lead_create`（[lead-request.ts](../src/pages/subpackages/other/lead-request.ts)）：请求字段 `customer_type`(1企业/2个人，[lead-create.vue](../src/pages/subpackages/other/lead-create.vue) 已做文案→数字映射)、`customer_name, contact_name?, contact_mobile, product_ids[], description?`；替代旧的 `create_lead_suggestion`；去重口径为"客户名称+联系人手机号+产品+进行中"三维匹配；**仅审核通过的合伙人可提交**，前端不做前置拦截，交由后端报错提示。
- 旧的 `referral-clue.vue` 页面和 `create_lead_suggestion` 接口**保留代码但不再被任何入口引用**。
### 3.5 我的佣金（对应 02 · P4）
统一定义在 [commission/request.ts](../src/pages/subpackages/commission/request.ts)，均为领域服务，`subProjectName` 主要是 `welfare_bean`/`reward_account_api`：
| 接口名 | 请求字段 | 响应字段 | 用途 |
| ----------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| ----------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------- |
| `account_info` | — | `balance, will_overdue_amount, money, money_frozen, money_cash, month_tax_free, tax_free, tax_rate, award_money` | 账户余额总览 |
| `account_record_list` | `page_index, page_size, income_type` | `IncomeTypeName, OutcomeValue/IncomeValue, ActivityDescription, CreatedDate` | 收支流水 |
| `apply_tax_amount_info` | `reward_amount, payee_type` | — | 提现前的税额预检 |
......@@ -161,21 +193,22 @@ sdk.domainServicePost("接口名", { data, params }, isAnonymous, subProjectName
| `apply_record_list` | `page_index, page_size` | `list[]`（`cash_type_name, amount, create_time`） | 提现记录列表 |
| `apply_payee_info` | — | — | 收款账户信息 |
| `apply_record_detail` | `id`（apply_id） | — | 提现记录详情 |
| `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` | `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`）（**✅ `list` 已分页返回，新增 `total`/`page`；金额统计字段仍按全量计算**） | 我的佣金余额+明细（02 原型 P4 的主要数据源） |
**⚠️ 本次新需求是否需要改动**：`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` 或类似）供前端判断是否还有更多数据。
**✅ 已支持分页**：合伙人佣金明细已积累 200+ 条，前端已按 `page`/`page_size` 分页加载并读取响应 `total` 判断是否还有更多（[commission/request.ts](../src/pages/subpackages/commission/request.ts)、[my-commission.vue](../src/pages/subpackages/commission/my-commission.vue)，滚动到底部触发加载下一页）。
### 3.6 产品（对应 01 首页 + 02 · P5/P6）
| 接口名 | 形式 | 代码位置 | 请求字段 | 响应字段 | 用途 |
| -------------------------------------- | --------------------------- | ------------------------------------------------------------------------------------- | --------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------- |
| -------------------------------------- | --------------------------- | ------------------------------------------------------------------------------------- | --------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------- |
| `get_category_list` | domain service | [home/components/tools.ts:14](../src/pages/home/components/tools.ts#L14) | `category_type` | 分类树 | 首页/产品列表的分类 tab |
| `partner_product` / `client_main_list` | uniplat model（走 sdkList） | [main-service.vue:140](../src/pages/home/components/main-service.vue#L140) | — | 见下方 `productPredict` | 首页"主推服务"卡片 |
| `partner_product` / `client_detail` | uniplat model | [home/components/index.ts:67](../src/pages/home/components/index.ts#L67) | `id` | 见下方 `productPredict` | 产品详情、海报生成的共用数据源 |
| `partner_product` / `client_main_list` | uniplat model（走 sdkList） | [main-service.vue:140](../src/pages/home/components/main-service.vue#L140) | — | 见下方`productPredict` | 首页"主推服务"卡片 |
| `partner_product` / `client_detail` | uniplat model | [home/components/index.ts:67](../src/pages/home/components/index.ts#L67) | `id` | 见下方`productPredict` | 产品详情、海报生成的共用数据源 |
| `get_product_list` | domain service | [product-list.vue:230](../src/pages/subpackages/product/product-list.vue#L230) | `category_type, search_key` | 分类→标签→产品三层树 | 产品列表页（02 原型 P5） |
| `product_content_list` | domain service | [share-view.vue:171](../src/pages/subpackages/product/components/share-view.vue#L171) | `product_id` | 按类型分组（文案/海报/短视频/FAQ），字段 `content, content_type, description` | 产品分享物料 tab（02 原型 P6 推广物料区） |
| `product_content_list` | domain service | [share-view.vue:171](../src/pages/subpackages/product/components/share-view.vue#L171) | `product_id` | 按类型分组（文案/海报/短视频/FAQ），字段`content, content_type, description` | 产品分享物料 tab（02 原型 P6 推广物料区） |
`productPredict` 完整字段（供参考现有产品模型有哪些字段）：
......@@ -196,6 +229,7 @@ contactor_poster_template, partner_land_page, customer_land_page
复用产品模块的 `partner_product`/`client_detail`（拿 `partner_poster_template` / `contactor_poster_template` / `partner_land_page` / `customer_land_page`），加上以下几个二维码相关接口：
| 接口名 | 代码位置 | 用途 |
| -------------------------- | ---------------------------------------------------------- | ------------------------------- |
| `gen_qrcode_code` | [tools.ts:264](../src/pages/home/components/tools.ts#L264) | 生成海报二维码短码 |
......@@ -264,10 +298,11 @@ contactor_poster_template, partner_land_page, customer_land_page
- 作废：`{opportunity_id, reason, remark}`，reason 单选（客户已选择竞品/客户失联无意向/预算不足/客户资质不符/重复商机/无法提供对应服务/其他），选"其他"时 remark 必填
- 标记成单：`{opportunity_id}` → 生成对应订单记录（需要后端定义"商机成单"和"订单创建"的事务关系）
#### 【建议新增】新增商机（对接人代录入）
#### ✅ 已实现：新增商机（对接人代录入）
- 参考 mock：[opportunity-create.vue:118](../src/pages/subpackages/opportunity/opportunity-create.vue#L118)
- 建议请求字段：`customer_type, customer_name, contact_name, contact_mobile, product_names[], remark, partner_id?`
- 实现位置：[opportunity-create.vue](../src/pages/subpackages/opportunity/opportunity-create.vue)、[opportunity/request.ts](../src/pages/subpackages/opportunity/request.ts)
- 请求字段：`customer_name, product_ids[], contact_name?, contact_mobile?, partner_id?, description?`
- **✏️【修改】20260706 补充接口②**：新增 `user_type`（1企业、2个人），对应表单 `customer_type` 显示文案本地映射提交，已接入（[opportunity-create.vue](../src/pages/subpackages/opportunity/opportunity-create.vue)）
- **需要后端实现去重检测**：同客户+同产品已有进行中商机 → 不新建，只提示并刷新原商机更新时间（04 原型逻辑注释明确要求）
- 来源固定标记为"后台添加"，区别于合伙人小程序提交的"合伙人添加"
......@@ -287,47 +322,33 @@ contactor_poster_template, partner_land_page, customer_land_page
### 4.3 合伙人审核流程（对应 01 · P5-P8，2026-07-06 原型新增）
#### 【建议新增】合伙人审核状态查询
#### ⏳ 待对接：合伙人审核状态查询（复用 user_info，非新接口）
- 用途：P7 审核中页面、P8 审核未通过页面的数据源
- 建议请求字段：无（取当前登录用户）
- 建议响应字段：
- `status`：审核状态字符串，枚举 `"待审核"` / `"审核通过"` / `"审核不通过"`
- `submit_time`：提交时间 `yyyy-MM-dd HH:mm:ss`
- `audit_time`：审核时间（仅审核通过/不通过时有值）
- `name`：申请人姓名
- `mobile`：申请人手机号
- `id_card`：身份证号
- `role_kind`：身份类别（逗号分隔，如 `"HR,财务"`）
- `reject_reason`：驳回原因（仅审核不通过时有值，字符串或数组）
- **是否可复用**：与「三、3.2」`join_partner` 提交接口关联，建议在 `partner_users` 表上增加 `audit_status` / `audit_time` / `reject_reason` 字段，查询时直接读取
#### 【建议新增】搜索合伙人列表
- **字段已由后端提供，直接读取现有 `user_info`（`userInfo.value`）即可，不需要新增接口**
- 涉及字段：`status`（审核状态）、`submit_time`、`audit_time`、`name`、`mobile`、`id_card`、`role_kind`、`reject_reason`、`review_remark`（20260706 补充接口③新增）
- **当前状态**：前端尚未接入，[audit-pending.vue](../src/pages/subpackages/more/audit-pending.vue)、[audit-failed.vue](../src/pages/subpackages/more/audit-failed.vue) 仍是硬编码 mock 数据，接入工作交由其他同事处理
#### ✅ 已实现：搜索合伙人列表
- 用途：P6b 新增商机页面，关联合伙人搜索抽屉
- 建议请求字段：`search_key`（姓名/手机号模糊搜索）、`page`、`page_size`
- 建议响应字段：`partner_id, name, mobile, create_type`
- **是否可复用**：`partner_users` 表查询，过滤 `is_partner=true` 且 `create_type IN (1,2,3)` 的用户
- 实现位置：[partner-drawer.vue](../src/components/common/partner-drawer.vue)，已从 mock 切换为真实接口 `get_partner_users`
- 请求字段：`type`（前端固定传 `"all"`）、`partner_key`（姓名/手机号模糊搜索）
- 响应字段：`id`（字符串）、`name`、`mobile`（原"建议响应字段"里的 `partner_id`/`create_type` 未在实际接口中出现，`create_type` 暂未用到）
---
## 五、待确认疑点清单
1. **"介绍人"身份判定条件在不同原型文件里不一致**：
- 01 原型（P3a→P3b）：只要"曾推荐过至少 1 位合伙人（无论是否成单）"即可
- 02 原型（P1a→P1b）、03 原型：需要"下级合伙人已有企业客户产生订单"才算
- 需要和产品/后端确认哪个是最终口径，这直接决定 `isIntroducer` 后端判定逻辑。
2. **`isIntroducer` 当前是前端占位实现**（[services/type.ts:7](../src/services/type.ts#L7)），依赖 `userInfo2.is_introducer` 字段，需要确认后端 `user_info` 接口是否已返回或计划何时返回该字段，以及是实时计算字段还是落库字段。
3. **01 原型 P4 申请表单的"身份证号"必填性矛盾**：表单 UI 上没有标红色必填星号，但逻辑注释文字里把它列为必填校验项，需要产品确认。同时"手机号验证码"和"介绍人"两个输入控件在原型 HTML 里是空容器，没有具体 placeholder 文案，需要补充设计稿或确认字段细节。
4. **"对接人分配表"具体结构未知**：02、04 两份原型反复提到新增商机时要查这张表来自动匹配对接人/渠道管理员，但现有前端代码和数据库层面完全看不到这张表的痕迹，需要和后端确认是否已存在、由谁维护、维护入口在哪个后台。
5. **04 对接人版"我的佣金"页面的显示分支条件尚未最终确定**：讨论中曾出现"对接人显示新卡片"、"非合伙人非对接人显示新卡片"两种相反的说法，最终标记为"存疑，后续再定"，目前 [my-commission.vue](../src/pages/subpackages/commission/my-commission.vue) 未做改动（原文件已备份为 `my-commission.bak.vue`）。这部分接口需求要等业务分支定案后才能确定。
6. **04 P3"商机筛选"目前实现成独立页面**，产品方表示"UI 稿未出，后续可能改成弹窗"，如果改成弹窗，筛选参数的传递方式不受影响（都是查询参数），但如果后端有埋点/统计需求区分"进入筛选页"这个动作，需要提前告知。
7. **商机"逾期自动作废"规则**（04 原型：跟进中超期提醒、挂起状态"逾期 30 天自动作废"）是纯后端定时任务规则，前端不参与，仅供后端实现时参考，具体阈值天数需要产品最终确认（原型里的"30 天"是示例数字）。
8. **04 原型 P8"分佣干系人"展示口径**：对接人本人的佣金显示实际到手金额，其他三方（介绍人/合伙人/渠道管理员）只显示各自的分佣规则文案、不显示具体金额——这是一个权限/展示层面的要求，需要接口按角色返回不同粒度的数据，而不是前端拿到全部数据后自行隐藏（避免金额数据被绕过接口拿到）。
亲亲创客二期/文档/联调记录.md
```markdown
```markdown
......@@ -46,7 +46,15 @@ api文档：《api-doc-第三点改动.md》
## 王雷
### 🔴改动6（需后端配合，待跟进）【已处理，详见 亲亲创客二期\文档\api-doc-第四点新增接口.md 第四章】
### 🔴改动25（需后端配合，待跟进）
api文档：《api-doc-第四点新增接口.md》
接口：五、① partner_opportunity_list — 合伙人线索(商机)列表
描述：按 02-合伙人.dc.html P8 原型重新对齐 [lead-list.vue](../../../packages/partner-mp/src/pages/subpackages/other/lead-list.vue) 样式（顶部渐变 Hero 介绍条 + 4 tab + 卡片列表，替换掉之前占位的搜索栏+简易卡片结构），卡片按状态展示"联系人 / 意向服务或成交服务 / 提交或成交时间 / 更新时间 / 作废原因"等字段。其中原型卡片里的"联系人：姓名+手机号"一行，当前 `partner_opportunity_list` 反参没有对应字段（只有 `customer_name/customer_attr/product_name/partner_name/contactor_name/channel_admin_name/source/create_time/update_time/status`），已在 [lead-request.ts](../../../packages/partner-mp/src/pages/subpackages/other/lead-request.ts) 的 `LeadListItem` 里加了可选字段 `contact_name`/`contact_mobile` 兜底（无值时该行不显示），**缺后端在响应里补充这两个字段**。
### 改动6（需后端配合，待跟进）【已处理，详见 亲亲创客二期\文档\api-doc-第四点新增接口.md 第四章】
api文档：《api-doc-第四点新增接口.md》
......@@ -158,7 +166,7 @@ api文档：《api-doc-第四点新增接口.md》
描述：[services/type.ts](../../../packages/partner-mp/src/services/type.ts) 中 `isIntroducer` 已读取 `userInfo2.is_introducer` 作为真实字段（此前分配02已接入），无需改动，等待后端在 `user_info` 响应里补上该字段即可生效
### 🔴改动15（需后端配合，待跟进）
### 改动15【已处理，详见 api-doc-第四点新增接口.md 「五、①②」】
api文档：《api-doc.md》
......@@ -166,7 +174,7 @@ api文档：《api-doc.md》
描述：针对 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（需后端配合，待跟进）
### 改动16【已处理，详见 api-doc-第四点新增接口.md 「五、③④」】
api文档：《api-doc.md》
......@@ -174,7 +182,7 @@ api文档：《api-doc.md》
描述：[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（需后端配合，待跟进）
### 改动17【已处理，详见 api-doc-第四点新增接口.md 「五、⑤」】
api文档：《api-doc.md》
......@@ -182,4 +190,60 @@ api文档：《api-doc.md》
描述：合伙人佣金明细已积累 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)），**缺后端确认接口支持这两个参数、并在响应里补充总数字段**。
### 改动18
api文档：《api-doc-第四点新增接口.md》
接口：四、① get_partner_users — 根据手机号/姓名搜索合伙人
描述：[partner-drawer.vue](../../../packages/partner-mp/src/components/common/partner-drawer.vue)（04·P6b 新增商机页面"关联合伙人"抽屉）原为 `// TODO: 调用合伙人搜索 API` 的 mock 数据，已接入真实接口，`type` 固定传 `"all"`、`partner_key` 传搜索框内容；返参字段由 mock 的 `partner_id`(number) 改为接口实际返回的 `id`(string)，模板与选中态逻辑同步更新。
### 改动19
api文档：《api-doc-第四点新增接口.md》
接口：四、② 修改接口：opportunity_create（入参增加 user_type）
描述：[opportunity-create.vue](../../../packages/partner-mp/src/pages/subpackages/opportunity/opportunity-create.vue) 表单里原本就有的"客户类型"（企业客户/个人客户）字段此前只是本地 UI 状态、未随请求提交（见原代码注释"customer_type 字段接口文档未提供，暂保留 UI"）；现已映射为 `user_type`(1企业/2个人) 随 `createOpportunity` 提交。顺带修复了"关联合伙人"选中后 `partner_id` 一直没有被提交的遗留问题（[opportunity/request.ts](../../../packages/partner-mp/src/pages/subpackages/opportunity/request.ts) 补充 `user_type` 字段类型定义）。
### 改动20
api文档：《api-doc-第四点新增接口.md》
接口：四、③ 合伙人审核添加审核备注（partner_info 新增 review_remark）
描述：确认后不动代码——`review_remark` 是给"合伙人审核状态查询"接口新增的字段，但该接口本身仍未接入（[audit-pending.vue](../../../packages/partner-mp/src/pages/subpackages/more/audit-pending.vue)、[audit-failed.vue](../../../packages/partner-mp/src/pages/subpackages/more/audit-failed.vue) 目前仍是硬编码 mock，属于 api-doc.md「四、4.3」更早就存在的缺口）。已把 `review_remark` 记入 api-doc.md 对应待办小节，等该接口正式排期对接时一并处理。
### 改动21
api文档：《api-doc-第四点新增接口.md》
接口：五、① partner_opportunity_list — 合伙人线索(商机)列表【新增】
描述：改动15 新建 [lead-list.vue](../../../packages/partner-mp/src/pages/subpackages/other/lead-list.vue) 时 `status` 参数用的是前端占位的数字码（3跟进中/4暂时挂起/5已成单/6已作废，四个 tab）；后端正式给出的字段是字符串（`""`/`"all"`全部、`in_progress`进行中=待审核+待分配+跟进中+暂时挂起合并、`"5"`已成单、`"6"`已作废），已按此改造：[lead-list.vue](../../../packages/partner-mp/src/pages/subpackages/other/lead-list.vue) tab 结构改为"全部/进行中/已成单/已作废"，[lead-request.ts](../../../packages/partner-mp/src/pages/subpackages/other/lead-request.ts) 的 `LeadListParams.status` 类型同步更新；响应新增 `partner_name` 字段，`LeadListItem` 类型定义同步补充。
### 改动22
api文档：《api-doc-第四点新增接口.md》
接口：五、② partner_lead_create — 合伙人提交新线索【新增】
描述：改动15 新建 [lead-create.vue](../../../packages/partner-mp/src/pages/subpackages/other/lead-create.vue) 时 `customer_type` 是前端占位的字符串直传；后端正式给出的字段要求是 `int`(1企业/2个人)，已补充映射表（同 [opportunity-create.vue](../../../packages/partner-mp/src/pages/subpackages/opportunity/opportunity-create.vue) 的 `CUSTOMER_TYPE_CODE` 做法）后随请求提交。去重口径按后端明确改为"客户名称+联系人手机号+产品+进行中"三维（此前 api-doc.md 记录的是"客户+产品"二维，纯文档口径更新，逻辑在后端实现）。后端另说明"仅审核通过的合伙人可提交"，前端不做前置拦截，未通过时交给后端报错提示。
### 改动23
api文档：《api-doc-第四点新增接口.md》
接口：五、④⑤ customer_order_list / get_deal_settlement 分页确认 + hasMore 判断优化
描述：改动16、17 里 `customer_order_list`、`get_deal_settlement` 的分页传参已提前做好；后端正式确认接口已支持 `page`/`page_size` 并返回总数字段（`total`/`rc_count`）。顺带把 [customer-detail.vue](../../../packages/partner-mp/src/pages/subpackages/customer/customer-detail.vue) 里 `hasMore` 的判断从"本页返回条数是否达到 pageSize"的近似判断，改为直接读取响应 `total`/`rc_count` 精确判断，避免多翻一页空请求；`get_deal_settlement` 侧（[my-commission.vue](../../../packages/partner-mp/src/pages/subpackages/commission/my-commission.vue)）此前已经是用 `total` 判断，未改动。
### 改动24
api文档：《api-doc-第四点新增接口.md》
接口：五、③⑥ customer_collect_list.first_deal_status 取值口径 / 介绍人身份判定收紧
描述：均为确认无需改动——③ 后端补充了 `first_deal_status` 的取值口径说明（已成单/已注册/已创建/已留资），前端 [customer-detail.vue](../../../packages/partner-mp/src/pages/subpackages/customer/customer-detail.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