Skip to content

何博文 / hro_prd_dock

Go to a project
Commit 48bb8c66 by 王雷
Options

更新api-doc

parent 5319d412
Inline Side-by-side
Showing with 107 additions and 103 deletions
亲亲创客二期/文档/前端/api-doc.md
# partner-mp 接口说明文档
# partner-mp 接口说明文档
......@@ -14,17 +14,18 @@
本次是在已有页面级结论基础上做的**字段级复核**，以下是新增/修改的接口需求，需要后端重点关注：
| 类型 | 接口 | 内容 | 详情章节 |
| --- | --- | --- | --- |
| 🆕 新增接口 | `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 |
| ✅ 已对接 | `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` | 合伙人审核备注字段，随审核状态查询接口一起对接（该接口本身尚未接入，见 §4.3） | 见下方新增小节 |
| 类型 | 接口 | 内容 | 详情章节 |
| ------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------- |
| ✅ 已对接（详见下方 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 | 见下方新增小节 |
---
......@@ -32,17 +33,18 @@
后端已给出 `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 |
| ✅ 确认无需改动 | 介绍人身份判定收紧（"审核通过的合伙人"口径） | 后端明确纯后端口径调整，前端无需改动 | §一 |
| 类型 | 接口 | 内容 | 详情章节 |
| ------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
| ✏️ 已按后端口径改造 | `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 |
| ✅ 确认无需改动 | 介绍人身份判定收紧（"审核通过的合伙人"口径） | 后端明确纯后端口径调整，前端无需改动 | §一 |
---
......@@ -50,11 +52,12 @@
项目里有三种业务身份，彼此**独立、可叠加**，不是互斥的单选状态（除了下面标注的一组互斥关系）：
| 身份 | 判定方式 | 与其他身份的关系 |
| ---------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **普通用户** | 登录但不满足任何角色条件 | 基础态 |
| **合伙人**（`is_partner`） | 通过 P4 表单申请，后台审核通过 | 与"对接人"**互斥**：一个用户不会同时是合伙人又是对接人 |
| **对接人**（`is_contactor`） | 由后台/渠道管理员指派，员工身份 | 与"合伙人"**互斥**；对接人默认同时拥有"介绍人"资格（见下） |
| 身份 | 判定方式 | 与其他身份的关系 |
| ---------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **普通用户** | 登录但不满足任何角色条件 | 基础态 |
| **合伙人**（`is_partner`） | 通过 P4 表单申请，后台审核通过 | 与"对接人"**互斥**：一个用户不会同时是合伙人又是对接人 |
| **对接人**（`is_contactor`） | 由后台/渠道管理员指派，员工身份 | 与"合伙人"**互斥**；对接人默认同时拥有"介绍人"资格（见下） |
| **介绍人**（`isIntroducer`） | 推荐/邀请他人成为合伙人达成一定条件后自动获得 | **独立叠加**在"合伙人"或"对接人"之上，不互斥；也可能是仅有介绍人身份、既非合伙人也非对接人的用户（01 原型的 P3a→P3b） |
**⚠️ 需要后端确认的关键点**：介绍人判定条件在不同原型文件里描述不一致，见「五、待确认疑点清单」第 1 条。
......@@ -113,36 +116,40 @@ 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}` |
| `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`（账号封禁） |
| `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...`） |
| 接口名 | 形式 | 代码位置 | 用途 |
| ----------------------------------------------------- | -------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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`（账号封禁） |
| `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...`） |
**⚠️ 本次新需求是否需要改动**：`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/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) | — | 表单里的城市选择器数据源 |
| 接口名 | 形式 | 代码位置 | 请求字段 | 用途 |
| ------------------------------------------------ | -------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `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`）（**✅ 已支持 `total`/`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`（**✅ 已支持 `page, page_size`**） | `orders[]`（`order_amount, order_commission, order_fee_amount, product_type`）（**✅ 已支持 `total`/`rc_count` 总数字段**） | 客户详情页的订单明细 |
**⚠️ 本次新需求是否需要改动**：
......@@ -153,10 +160,11 @@ sdk.domainServicePost("接口名", { data, params }, isAnonymous, subProjectName
### 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}` | 提交线索时选择意向产品的分类树 |
| 接口名 | 形式 | 代码位置 | 请求字段 | 用途 |
| ------------------------------------------ | -------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| `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}` | 提交线索时选择意向产品的分类树 |
**⚠️ 本次新需求是否需要改动**：
......@@ -167,7 +175,7 @@ sdk.domainServicePost("接口名", { data, params }, isAnonymous, subProjectName
**✅ 已实现：合伙人线索列表 + 提交线索（对应后端「五、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`（[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`=当前登录用户）过滤。
- `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` 接口**保留代码但不再被任何入口引用**。
......@@ -175,16 +183,17 @@ sdk.domainServicePost("接口名", { data, params }, isAnonymous, subProjectName
统一定义在 [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` | — | 提现前的税额预检 |
| `apply` | `reward_amount, payee_type, payee_identity`（微信通道追加 `wx_app_id, wx_open_id`） | `order_id` | 提交提现申请 |
| `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`）（**✅ `list` 已分页返回，新增 `total`/`page`；金额统计字段仍按全量计算**） | 我的佣金余额+明细（02 原型 P4 的主要数据源） |
| 接口名 | 请求字段 | 响应字段 | 用途 |
| ----------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------- |
| `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` | — | 提现前的税额预检 |
| `apply` | `reward_amount, payee_type, payee_identity`（微信通道追加 `wx_app_id, wx_open_id`） | `order_id` | 提交提现申请 |
| `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`）（**✅ `list` 已分页返回，新增 `total`/`page`；金额统计字段仍按全量计算**） | 我的佣金余额+明细（02 原型 P4 的主要数据源） |
**⚠️ 本次新需求是否需要改动**：`get_deal_settlement` 的结构是"可提现余额"模型（合伙人专用），04 原型的对接人佣金是"次月工资发放，无提现"模型，字段维度也不同（对接人要看"已结算订单数"，合伙人模型里没有这个字段）。这两种模型是否共用一张结算表、只是展示口径不同，还是完全独立的两套逻辑，需要和后端确认（详见「四」中的商机/订单模块说明）。
......@@ -192,13 +201,14 @@ sdk.domainServicePost("接口名", { data, params }, isAnonymous, subProjectName
### 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` | 产品详情、海报生成的共用数据源 |
| `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 推广物料区） |
| 接口名 | 形式 | 代码位置 | 请求字段 | 响应字段 | 用途 |
| -------------------------------------- | --------------------------- | ------------------------------------------------------------------------------------- | --------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------- |
| `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` | 产品详情、海报生成的共用数据源 |
| `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 推广物料区） |
`productPredict` 完整字段（供参考现有产品模型有哪些字段）：
......@@ -219,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) | 生成海报二维码短码 |
......@@ -247,17 +258,17 @@ contactor_poster_template, partner_land_page, customer_land_page
- 用途：介绍人业务详情页（03 · P2）
- 参考 mock：[my-partners.vue:132](../src/pages/subpackages/customer/my-partners.vue#L132)
- 建议响应字段：
- 顶部汇总：`partner_count, deal_count, no_deal_count, reward_total, reward_pending, reward_pending_count`
- 列表项：`id, name, mobile, join_date, customer_count, deal_count, reward_status`（待发放/已发放/无奖励）
- 顶部汇总：`partner_count, deal_count, no_deal_count, reward_total, reward_pending, reward_pending_count`
- 列表项：`id, name, mobile, join_date, customer_count, deal_count, reward_status`（待发放/已发放/无奖励）
#### 【建议新增】合伙人详情（介绍人视角）
- 用途：合伙人详情页（03 · P3）
- 参考 mock：[partner-detail.vue:125](../src/pages/subpackages/customer/partner-detail.vue#L125)
- 建议响应字段：
- 头部：`name, mobile, join_date, join_days, customer_count, deal_count`
- 奖励：`reward_amount, reward_status, reward_trigger_customer, reward_date`
- 推荐企业列表：`customer_name, contact_name, contact_mobile, is_deal, invite_date, deal_date, settled_days`
- 头部：`name, mobile, join_date, join_days, customer_count, deal_count`
- 奖励：`reward_amount, reward_status, reward_trigger_customer, reward_date`
- 推荐企业列表：`customer_name, contact_name, contact_mobile, is_deal, invite_date, deal_date, settled_days`
**是否可复用现有结构**：奖励发放规则（¥50/人，首单成交即结算，渠道管理员线下审核发放）和「三、3.5 我的佣金」里的 `get_deal_settlement` 佣金结算逻辑是同一套"审核后发放"模式，建议复用同一套审核/发放机制，只是介绍人奖励是固定金额、合伙人佣金是比例/固定混合，可能是同一张结算表里的不同规则类型。
......@@ -276,9 +287,9 @@ contactor_poster_template, partner_land_page, customer_land_page
- 参考 mock：[opportunity-detail.vue:127](../src/pages/subpackages/opportunity/opportunity-detail.vue#L127)
- 建议响应字段：
- 客户信息：`customer_name, contact_name, contact_mobile, product_name, source`
- 关联干系人：介绍人/合伙人/渠道管理员/对接人四方的 `role, name, mobile`
- 状态流转记录：`time, title, desc` 数组
- 客户信息：`customer_name, contact_name, contact_mobile, product_name, source`
- 关联干系人：介绍人/合伙人/渠道管理员/对接人四方的 `role, name, mobile`
- 状态流转记录：`time, title, desc` 数组
#### 【建议新增】商机挂起 / 作废 / 标记成单（三个动作接口）
......@@ -311,21 +322,12 @@ 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` 字段，查询时直接读取
- **📝【待办】20260706 补充接口③**：`partner_info` 将新增 `review_remark`（合伙人审核备注）字段，随此接口一起返回。**本条待办不阻塞**——该查询接口本身仍未接入（[audit-pending.vue](../src/pages/subpackages/more/audit-pending.vue)、[audit-failed.vue](../src/pages/subpackages/more/audit-failed.vue) 目前仍是硬编码 mock），`review_remark` 留到该接口正式对接时一并处理，暂不单独动前端代码。
- **字段已由后端提供，直接读取现有 `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 数据，接入工作交由其他同事处理
#### ✅ 已实现：搜索合伙人列表
......@@ -339,20 +341,14 @@ contactor_poster_template, partner_land_page, customer_land_page
## 五、待确认疑点清单
1. **"介绍人"身份判定条件在不同原型文件里不一致**：
- 01 原型（P3a→P3b）：只要"曾推荐过至少 1 位合伙人（无论是否成单）"即可
- 02 原型（P1a→P1b）、03 原型：需要"下级合伙人已有企业客户产生订单"才算
- 需要和产品/后端确认哪个是最终口径，这直接决定 `isIntroducer` 后端判定逻辑。
- 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》
......
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