01 客户列表接口 GET V1
| 项目 | 说明 |
| 接口地址 | GET /admin/v1/client/client-list |
| 本地地址 | http://192.168.111.30/admin/v1/client/client-list |
| 所属模块 | 客户管理 |
| 架构 | 三层架构 (Controller → Service → Model) |
| 控制器 | App\Http\Controllers\V1\ClientController |
| 服务层 | App\Services\V1\ClientService |
02 请求参数
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
| page | int | 否 | 1 | 页码 |
| page_size | int | 否 | 20 | 每页条数 |
说明筛选参数后续补充
03 返回字段
基础信息
| 字段名 | 类型 | 说明 | 数据来源 |
| id | int | 会员号 | m_client.id |
| username | string | 昵称 | m_client.username |
| head | string | 头像 | m_client.head |
| mobile | string | 电话(脱敏) | m_client.mobile |
平台/站点
| 字段名 | 类型 | 说明 | 数据来源 |
| sid | int | 平台ID | m_client.sid |
| platform_name | string | 平台名称 | m_compan.name |
| sub_group_id | int | 平台分组ID | m_compan.sub_group_id |
| sub_group_name | string | 平台分组名称 | m_company_sub_group.name |
| collage_id_name | string | 拼单站点名称 | m_collection_points.name |
大区
| 字段名 | 类型 | 说明 | 数据来源 |
| region_id | int | 大区ID | m_client_detail.region_id |
| region_name | string | 大区名称 | m_regions.name |
会员等级
| 字段名 | 类型 | 说明 | 数据来源 |
| level_id | int | 会员等级ID | m_client.level_id |
| level_name | string | 会员等级名称 | m_level.name |
分组
| 字段名 | 类型 | 说明 | 数据来源 |
| group_id | int | 运营分组ID | m_client.group_id |
| group_name | string | 运营分组名称 | m_group.name |
| pre_sales_group_id | int | 售前分组ID | m_client.pre_sales_group_id |
| pre_sales_group_name | string | 售前分组名称 | admins_region_relations → admins.nickname |
收货人/收货地址
| 字段名 | 类型 | 说明 | 数据来源 |
| last_username | string | 收货人姓名 | m_client.last_username |
| latest_address | string | 最新收货地址 | latest_province + latest_city + latest_area |
积分/余额/授信
| 字段名 | 类型 | 说明 | 数据来源 |
| points | int | 积分 | m_client_detail.points |
| balance | string | 余额 | m_client.balance |
| credit | string | 授信额度 | m_client.credit |
购买相关
| 字段名 | 类型 | 说明 | 数据来源 |
| order_goods_number | int | 购买扎数(累计) | m_client.order_goods_number |
| order_count | int | 订单数量 | m_client_detail.buy_count (预计算) |
| order_amount_total | string | 交易总金额 | m_client.total_goods_fee (预计算) |
本月数据
| 字段名 | 类型 | 说明 | 数据来源 |
| month_order_count | int | 本月订单数量 | COUNT(m_order) 本月 |
| month_order_goods | int | 本月购买扎数 | SUM(order_goods_num) 本月 |
今日数据
| 字段名 | 类型 | 说明 | 数据来源 |
| today_order_goods | int | 今日购买扎数 | m_client_detail.today_buy_num (预计算) |
历史统计
| 字段名 | 类型 | 说明 | 数据来源 |
| history_order_count | int | 历史订单数量 | m_client_detail.buy_count (预计算) |
时间相关
| 字段名 | 类型 | 说明 | 数据来源 |
| register_time | string | 注册时间 | m_client.time |
| register_days | int | 入驻天数 | (now - time) / 86400 |
| last_login_time | string | 最近登录时间 | m_client.login_time |
| last_order_time | string | 最近购买时间 | m_client.last_order_date |
| next_trace_time | string | 下次跟进时间 | m_client_crm_trace.tracetime (最早未处理) |
| no_order_days | int | 未下单天数 | (now - last_order_date) / 86400 |
客户状态/跟进
| 字段名 | 类型 | 说明 | 数据来源 |
| status | int | 账号状态 | m_client.status |
| status_name | string | 账号状态名称 | 映射: 1→正常, 0→异常 |
| hasorder | int | 下单状态 | m_client.hasorder |
| hasorder_name | string | 下单状态名称 | 映射: 0→未下单, 1→已下单 |
| crmclienttrace | int | 跟进状态 | m_client.crmclienttrace |
| crmclienttrace_name | string | 跟进状态名称 | 映射表 |
允许下单
| 字段名 | 类型 | 说明 | 数据来源 |
| stop_order | int | 关闭下单权限 | m_client.stop_order |
| stop_order_name | string | 状态名称 | 映射: 0→允许, 1→禁止 |
来源
| 字段名 | 类型 | 说明 | 数据来源 |
| reg_type | int | 注册来源 | m_client.reg_type |
| reg_type_name | string | 注册来源名称 | 映射表 |
推荐人
| 字段名 | 类型 | 说明 | 数据来源 |
| shareid | int | 推荐人ID | m_client.shareid |
| share_name | string | 推荐人名称 | m_client.username (自关联) |
04 关联数据库表
| 表名 | 说明 | 关联方式 |
| m_client | 客户主表 | 主表 |
| m_client_detail | 客户详情表 | LEFT JOIN ON uid = id |
| m_compan | 平台表 | sid → id |
| m_company_sub_group | 平台分组表 | m_compan.sub_group_id → id |
| m_level | 会员等级表 | level_id → id |
| m_group | 分组表 | group_id → id |
| m_collection_points | 集货点表 | collage_id → id |
| m_regions | 大区表 | region_id → id |
| m_client (自关联) | 推荐人 | shareid → id |
| m_order | 订单表(本月统计) | uid = client_id |
| m_client_crm_trace | 客户跟进表 | uid = client_id |
05 状态枚举映射
客户状态 (status)
跟进状态 (crmclienttrace)
下单状态 (hasorder)
注册来源 (reg_type)
| 值 | 说明 |
| 0 | 自行注册 |
| 1 | 后台创建 |
| 2 | 微信注册 |
| 3 | H5注册 |
| 4 | 小程序注册 |
06 客户详情接口 GET V1
| 项目 | 说明 |
| 接口地址 | GET /admin/v1/client/detail |
| 本地地址 | http://192.168.111.30/admin/v1/client/detail?id=1 |
| 是否需要登录 | 是 |
| 适用场景 | 客户详情页展示 |
08 返回字段
基本信息
| 字段名 | 类型 | 说明 | 数据来源 |
| id | int | 客户ID(会员号) | m_client.id |
| username | string | 用户名/昵称 | m_client.username |
| mobile | string | 电话号码(不脱敏) | m_client.mobile |
| head | string | 头像 | m_client.head |
| emergency_contact | string | 紧急联系人 | m_client_urgent_mobile_record.urgent_mobile |
| last_username | string | 收货人 | m_client.last_username |
| address | string | 所在地 | province + city + area |
等级/分组/站点
| 字段名 | 类型 | 说明 | 数据来源 |
| level_id | int | 会员等级ID | m_client.level_id |
| level_name | string | 会员等级名称 | m_level.name |
| group_id | int | 运营分组ID | m_client.group_id |
| group_name | string | 运营分组名称 | m_group.name |
| pre_sales_group_id | int | 售前分组ID | m_client.pre_sales_group_id |
| pre_sales_group_name | string | 售前分组名称 | admins_region_relations → admins.nickname |
| collage_id | int | 所属站点ID | m_client.collage_id |
| collage_name | string | 所属站点名称 | m_collection_points.name |
推荐人
| 字段名 | 类型 | 说明 | 数据来源 |
| shareid | int | 推荐人ID | m_client.shareid |
| share_name | string | 推荐人名称 | m_client.username (自关联) |
订单/交易
| 字段名 | 类型 | 说明 | 数据来源 |
| order_amount_total | string | 交易总金额 | m_client.total_goods_fee (预计算) |
| today_order_status | int | 今日下单状态 | m_client_detail.today_buy_num > 0 |
时间信息
| 字段名 | 类型 | 说明 | 数据来源 |
| register_time | string | 注册时间 | m_client.time |
| last_login_time | string | 最近登录时间 | m_client.login_time |
| last_order_time | string | 最近购买时间 | m_client.last_order_date |
| next_trace_time | string | 下次跟进时间 | m_client_crm_trace (最早未处理) |
| no_order_days | int | 未下单天数 | (now - last_order_date) / 86400 |
账号信息
| 字段名 | 类型 | 说明 | 数据来源 |
| points | int | 积分 | m_client_detail.points |
| growth_value | int | 成长值 | m_member_level_history.score (最新一条) |
| balance | string | 余额 | m_client.balance |
| credit | string | 授信额 | m_client.credit |
| order_goods_number | int | 购买量(扎) | m_client.order_goods_number |
状态/来源/备注
| 字段名 | 类型 | 说明 | 数据来源 |
| hasorder | int | 下单状态 | m_client.hasorder |
| hasorder_name | string | 下单状态名称 | 已下单 / 未下单 |
| reg_type | int | 来源类型 | m_client.reg_type |
| reg_type_name | string | 来源名称 | 后台创建 / 微信注册 |
| remark | string | 备注 | m_client.remark |
10 数据表清单总览
| # | 表名 | 中文名 | Model | 使用场景 |
| 1 | m_client | 客户主表 | ClientModel | 列表/详情 |
| 2 | m_client_detail | 客户明细表 | ClientDetailModel | 列表/详情 |
| 3 | m_client_crm_trace | 客户跟进表 | ClientCrmTraceModel | 列表/详情 |
| 4 | m_client_urgent_mobile_record | 紧急联系人表 | ClientUrgentMobileRecordModel | 详情 |
| 5 | m_member_level_history | 会员等级历史表 | MemberLevelHistoryModel | 详情 |
| 6 | m_level | 会员等级表 | LevelModel | 列表/详情 |
| 7 | m_group | 运营分组表 | GroupModel | 列表/详情 |
| 8 | m_collection_points | 集货点/站点表 | CollectionPointsModel | 列表/详情 |
| 9 | m_regions | 大区表 | RegionsModel | 列表 |
| 10 | m_compan | 平台表 | CompanModel | 列表 |
| 11 | m_company_sub_group | 平台分组表 | CompanySubGroupModel | 列表 |
| 12 | m_admins | 管理员表 | AdminsModel | 列表/详情 |
| 13 | m_admins_region_relations | 售前分组关系表 | AdminsRegionRelationsModel | 列表/详情 |
| 14 | m_order | 订单表 | OrderModel | 列表 |
| 15 | m_tags | 标签表 | TagsModel | 已移除 |
11 核心表关系图
关系图
m_compan (平台)
│
├── sub_group_id ──→ m_company_sub_group (平台分组)
│
↓ sid
m_client (客户主表)
│
├── id ←── m_client_detail.uid (客户明细, 1:1)
│ ├── region_id ──→ m_regions (大区)
│ ├── today_buy_num (今日购买扎数)
│ ├── buy_count (购买频次/订单数量)
│ └── points (积分)
│
├── level_id ──→ m_level (会员等级)
│
├── group_id ──→ m_group (运营分组)
│
├── collage_id ──→ m_collection_points (站点)
│
├── pre_sales_group_id ──→ m_admins_region_relations
│ │
│ └── pid ──→ m_admins (管理员)
│
├── shareid ──→ m_client (自关联, 推荐人)
│
├── id ←── m_client_crm_trace.uid (跟进记录, 1:N)
│
├── id ←── m_client_urgent_mobile_record.user_id (紧急联系人, 1:N)
│
├── id ←── m_member_level_history.uid (会员等级历史, 1:N)
│
└── id ←── m_order.uid (订单, 1:N)
12 关联关系详表
| # | 主表 | 主表字段 | 关系 | 关联表 | 关联表字段 | 查询方式 |
| 1 | m_client | id | 1:1 | m_client_detail | uid | LEFT JOIN |
| 2 | m_client | level_id | N:1 | m_level | id | 批量 whereIn |
| 3 | m_client | group_id | N:1 | m_group | id | 批量 whereIn |
| 4 | m_client | collage_id | N:1 | m_collection_points | id | 批量 whereIn |
| 5 | m_client | shareid | N:1 | m_client | id | 批量 whereIn |
| 6 | m_client | sid | N:1 | m_compan | id | 批量 whereIn |
| 7 | m_compan | sub_group_id | N:1 | m_company_sub_group | id | 批量 whereIn |
| 8 | m_client | pre_sales_group_id | N:1 | m_admins_region_relations | id | whereIn |
| 9 | m_admins_region_relations | pid | N:1 | m_admins | id | whereIn |
| 10 | m_client_detail | region_id | N:1 | m_regions | id | 批量 whereIn |
| 11 | m_client | id | 1:N | m_client_crm_trace | uid | whereIn + MIN |
| 12 | m_client | id | 1:N | m_client_urgent_mobile_record | user_id | LIMIT 1 |
| 13 | m_client | id | 1:N | m_member_level_history | uid | LIMIT 1 |
| 14 | m_client | id | 1:N | m_order | uid | whereIn + groupBy |
13 字段来源速查表
客户列表返回字段
| 返回字段 | 数据源表 | 数据源字段 | 说明 |
| id | m_client | id | - |
| username | m_client | username | - |
| head | m_client | head | - |
| mobile | m_client | mobile | 脱敏 |
| sid | m_client | sid | - |
| sub_group_id | m_compan→m_company_sub_group | sub_group_id→id | 两跳 |
| sub_group_name | m_compan→m_company_sub_group | sub_group_id→name | 两跳 |
| platform_name | m_compan | name | - |
| collage_id_name | m_collection_points | name | - |
| region_id | m_client_detail | region_id | - |
| region_name | m_regions | name | - |
| level_id | m_client | level_id | - |
| level_name | m_level | name | - |
| group_id | m_client | group_id | - |
| group_name | m_group | name | - |
| pre_sales_group_id | m_client | pre_sales_group_id | - |
| pre_sales_group_name | m_admins_region_relations→m_admins | pid→nickname | 两跳 |
| last_username | m_client | last_username | - |
| latest_address | m_client | latest_province+city+area | 拼接 |
| points | m_client_detail | points | - |
| balance | m_client | balance | - |
| credit | m_client | credit | - |
| order_goods_number | m_client | order_goods_number | - |
| order_count | m_client_detail | buy_count | 预计算 |
| order_amount_total | m_client | total_goods_fee | 预计算 |
| month_order_count | m_order | COUNT(*) 本月 | 实时 |
| month_order_goods | m_order | SUM(order_goods_num) 本月 | 实时 |
| today_order_goods | m_client_detail | today_buy_num | 预计算 |
| history_order_count | m_client_detail | buy_count | 预计算 |
| register_time | m_client | time | 格式化 |
| register_days | m_client | time | 计算 |
| last_login_time | m_client | login_time | 格式化 |
| last_order_time | m_client | last_order_date | 格式化 |
| next_trace_time | m_client_crm_trace | MIN(tracetime) WHERE status=0 | 实时 |
| no_order_days | m_client | last_order_date / time | 计算 |
| status | m_client | status | - |
| status_name | m_client | status | 映射 |
| hasorder | m_client | hasorder | - |
| hasorder_name | m_client | hasorder | 映射 |
| crmclienttrace | m_client | crmclienttrace | - |
| crmclienttrace_name | m_client | crmclienttrace | 映射 |
| stop_order | m_client | stop_order | - |
| stop_order_name | m_client | stop_order | 映射 |
| reg_type | m_client | reg_type | - |
| reg_type_name | m_client | reg_type | 映射 |
| shareid | m_client | shareid | - |
| share_name | m_client (自关联) | username | - |
客户详情返回字段
| 返回字段 | 数据源表 | 数据源字段 | 说明 |
| id | m_client | id | - |
| username | m_client | username | - |
| mobile | m_client | mobile | 不脱敏 |
| head | m_client | head | - |
| level_id | m_client | level_id | - |
| level_name | m_level | name | - |
| group_id | m_client | group_id | - |
| group_name | m_group | name | - |
| pre_sales_group_id | m_client | pre_sales_group_id | - |
| pre_sales_group_name | m_admins_region_relations→m_admins | pid→nickname | 两跳 |
| collage_id | m_client | collage_id | - |
| collage_name | m_collection_points | name | - |
| shareid | m_client | shareid | - |
| share_name | m_client (自关联) | username | - |
| emergency_contact | m_client_urgent_mobile_record | urgent_mobile | 最新一条 |
| last_username | m_client | last_username | - |
| address | m_client | province+city+area | 拼接 |
| order_amount_total | m_client | total_goods_fee | 预计算 |
| today_order_status | m_client_detail | today_buy_num > 0 | 计算 |
| register_time | m_client | time | 格式化 |
| last_login_time | m_client | login_time | 格式化 |
| last_order_time | m_client | last_order_date | 格式化 |
| next_trace_time | m_client_crm_trace | MIN(tracetime) WHERE status=0 | 实时 |
| no_order_days | m_client | last_order_date / time | 计算 |
| points | m_client_detail | points | - |
| growth_value | m_member_level_history | score | 最新一条 |
| balance | m_client | balance | - |
| credit | m_client | credit | - |
| order_goods_number | m_client | order_goods_number | - |
| hasorder | m_client | hasorder | - |
| hasorder_name | m_client | hasorder | 映射 |
| reg_type | m_client | reg_type | - |
| reg_type_name | m_client | reg_type | 映射 |
| remark | m_client | remark | - |
14 个人交易数据接口 GET V1
| 项目 | 说明 |
| 接口地址 | GET /admin/v1/client/transaction-stats |
| 本地地址 | http://192.168.111.30/admin/v1/client/transaction-stats?id=1 |
| 所属模块 | 客户管理 - 客户详情页板块 |
| 适用场景 | 客户详情页中的「个人交易数据」板块展示 |
| 是否需要登录 | 是 |
15 请求参数
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
| id | int | 是 | - | 客户ID |
| time_type | string | 否 | 空 | 时间快捷类型(优先于 start_time/end_time):
today:今日
week:本周(周一至周日)
month:本月
year:本年
all:全部 |
| start_time | string | 否 | 空 | 开始时间(格式:Y-m-d,如 2026-01-01) |
| end_time | string | 否 | 空 | 结束时间(格式:Y-m-d,如 2026-12-31) |
时间筛选规则
- 若传入
time_type,则忽略 start_time/end_time
- 若未传入
time_type,但传入了 start_time 或 end_time,则使用自定义时间范围
- 若都未传入,则返回全部累计数据
16 返回字段
| 字段名 | 类型 | 说明 | 数据来源 |
| order_goods_number | int | 购买扎数(订单商品数量合计) | SUM(m_order.order_goods_num) |
| order_count | int | 下单次数(有效订单数) | COUNT(m_order.id) |
| order_amount | string | 交易金额(订单总金额合计,保留2位小数) | SUM(m_order.total_price) |
| time_type | string | 时间快捷类型(回传,便于前端展示) | 请求参数原样返回 |
| start_time | string | 实际生效的开始日期(Y-m-d) | 解析后的时间范围 |
| end_time | string | 实际生效的结束日期(Y-m-d) | 解析后的时间范围 |
返回示例
示例
{
"code": 200,
"message": "获取成功",
"data": {
"order_goods_number": 120,
"order_count": 35,
"order_amount": "8256.23",
"time_type": "month",
"start_time": "2026-08-01",
"end_time": "2026-08-31"
}
}
17 查询逻辑说明
有效订单条件
| 条件 | 说明 |
| uid = 客户ID | 指定客户的订单 |
| status < 4 | 有效订单(排除已取消、已退款等状态) |
| isshow = 1 | 显示中的订单 |
| date >= start_time | 订单时间大于等于开始时间(时间戳) |
| date <= end_time | 订单时间小于等于结束时间(时间戳) |
聚合统计
单次 SQL 完成
使用
selectRaw 一次性完成三个聚合统计,无 N+1 问题:
SELECT
IFNULL(SUM(order_goods_num), 0) AS order_goods_number,
COUNT(*) AS order_count,
IFNULL(SUM(total_price), 0) AS order_amount
FROM m_order
WHERE uid = ? AND status < 4 AND isshow = 1
AND date >= ? AND date <= ?
时间快捷类型对照
| time_type | 说明 | 开始时间 | 结束时间 |
| today | 今日 | 当日 00:00:00 | 当日 23:59:59 |
| week | 本周 | 周一 00:00:00 | 周日 23:59:59 |
| month | 本月 | 1日 00:00:00 | 月末 23:59:59 |
| year | 本年 | 1月1日 00:00:00 | 12月31日 23:59:59 |
| all | 全部 | null | null |
05 会员成长统计接口 GET V1
| 项目 | 说明 |
| 接口地址 | GET /admin/v1/client/member-growth-stats |
| 本地地址 | http://192.168.111.30/admin/v1/client/member-growth-stats |
| 所属模块 | 客户管理 |
| 接口用途 | 客户详情页面 - 会员成长板块 |
07 返回字段
等级信息
| 字段名 | 类型 | 说明 | 数据来源 |
| yesterday_level_id | int | 会员昨日等级ID | m_member_level_history.member_level |
| yesterday_level_name | string | 会员昨日等级名称 | m_member_level.name |
| last_week_level_id | int | 上周等级ID | m_member_level_history.member_level |
| last_week_level_name | string | 上周等级名称 | m_member_level.name |
| last_month_level_id | int | 上月等级ID | m_member_level_history.member_level |
| last_month_level_name | string | 上月等级名称 | m_member_level.name |
保级期信息
| 字段名 | 类型 | 说明 | 数据来源 |
| has_relegation | int | 是否有保级期(0:无, 1:有) | m_member_level.is_relegation |
| relegation_days | int | 保级期天数 | 待确认 计算逻辑待业务确认 |
| relegation_cnt | int | 已保级次数 | m_member_level_history.relegation_cnt |
待确认relegation_days 保级期天数的具体计算逻辑尚未明确,待业务方确认保级周期、降级触发条件等规则后再补充实现。当前默认返回 0。
基本信息
| 字段名 | 类型 | 说明 | 数据来源 |
| register_time | string | 注册时间 | m_client.time |
采购统计(近30天)
| 字段名 | 类型 | 说明 | 数据来源 |
| thirty_day_goods_num | int | 累计采购扎数 | SUM(m_order.order_goods_num) WHERE date >= 30天前 |
| thirty_day_order_count | int | 累计采购次数 | COUNT(*) FROM m_order WHERE date >= 30天前 |
综合评分
| 字段名 | 类型 | 说明 | 数据来源 |
| score | int | 综合价值评分 | m_member_level_history.score(最新记录) |
08 关联数据表
| 表名 | 用途 | 关联方式 |
| m_client | 客户基本信息 | id = 客户ID |
| m_member_level_history | 会员等级历史记录 | uid = 客户ID,每每日一条记录 |
| m_member_level | 会员等级配置 | id = member_level,存储等级名称和配置 |
| m_order | 订单表 | uid = 客户ID,统计近30天采购数据 |
09 待确认事项
| 字段 | 问题描述 | 影响 |
| relegation_days | 保级期天数的具体计算逻辑未明确 | 当前返回 0,待业务确认后补充 |
| relegation_days | 保级周期是多长?降级触发条件是什么? | 需业务方提供完整规则 |