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 请求参数

参数名类型必填默认值说明
pageint1页码
page_sizeint20每页条数
说明筛选参数后续补充

03 返回字段

基础信息

字段名类型说明数据来源
idint会员号m_client.id
usernamestring昵称m_client.username
headstring头像m_client.head
mobilestring电话(脱敏)m_client.mobile

平台/站点

字段名类型说明数据来源
sidint平台IDm_client.sid
platform_namestring平台名称m_compan.name
sub_group_idint平台分组IDm_compan.sub_group_id
sub_group_namestring平台分组名称m_company_sub_group.name
collage_id_namestring拼单站点名称m_collection_points.name

大区

字段名类型说明数据来源
region_idint大区IDm_client_detail.region_id
region_namestring大区名称m_regions.name

会员等级

字段名类型说明数据来源
level_idint会员等级IDm_client.level_id
level_namestring会员等级名称m_level.name

分组

字段名类型说明数据来源
group_idint运营分组IDm_client.group_id
group_namestring运营分组名称m_group.name
pre_sales_group_idint售前分组IDm_client.pre_sales_group_id
pre_sales_group_namestring售前分组名称admins_region_relations → admins.nickname

收货人/收货地址

字段名类型说明数据来源
last_usernamestring收货人姓名m_client.last_username
latest_addressstring最新收货地址latest_province + latest_city + latest_area

积分/余额/授信

字段名类型说明数据来源
pointsint积分m_client_detail.points
balancestring余额m_client.balance
creditstring授信额度m_client.credit

购买相关

字段名类型说明数据来源
order_goods_numberint购买扎数(累计)m_client.order_goods_number
order_countint订单数量m_client_detail.buy_count (预计算)
order_amount_totalstring交易总金额m_client.total_goods_fee (预计算)

本月数据

字段名类型说明数据来源
month_order_countint本月订单数量COUNT(m_order) 本月
month_order_goodsint本月购买扎数SUM(order_goods_num) 本月

今日数据

字段名类型说明数据来源
today_order_goodsint今日购买扎数m_client_detail.today_buy_num (预计算)

历史统计

字段名类型说明数据来源
history_order_countint历史订单数量m_client_detail.buy_count (预计算)

时间相关

字段名类型说明数据来源
register_timestring注册时间m_client.time
register_daysint入驻天数(now - time) / 86400
last_login_timestring最近登录时间m_client.login_time
last_order_timestring最近购买时间m_client.last_order_date
next_trace_timestring下次跟进时间m_client_crm_trace.tracetime (最早未处理)
no_order_daysint未下单天数(now - last_order_date) / 86400

客户状态/跟进

字段名类型说明数据来源
statusint账号状态m_client.status
status_namestring账号状态名称映射: 1→正常, 0→异常
hasorderint下单状态m_client.hasorder
hasorder_namestring下单状态名称映射: 0→未下单, 1→已下单
crmclienttraceint跟进状态m_client.crmclienttrace
crmclienttrace_namestring跟进状态名称映射表

允许下单

字段名类型说明数据来源
stop_orderint关闭下单权限m_client.stop_order
stop_order_namestring状态名称映射: 0→允许, 1→禁止

来源

字段名类型说明数据来源
reg_typeint注册来源m_client.reg_type
reg_type_namestring注册来源名称映射表

推荐人

字段名类型说明数据来源
shareidint推荐人IDm_client.shareid
share_namestring推荐人名称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)

说明
0异常
1正常

跟进状态 (crmclienttrace)

说明
0跟进中
1未跟进
2结束跟进

下单状态 (hasorder)

说明
0未下单
1已下单

注册来源 (reg_type)

说明
0自行注册
1后台创建
2微信注册
3H5注册
4小程序注册

06 客户详情接口 GET V1

项目说明
接口地址GET /admin/v1/client/detail
本地地址http://192.168.111.30/admin/v1/client/detail?id=1
是否需要登录
适用场景客户详情页展示

07 请求参数

参数名类型必填说明
idint客户ID

08 返回字段

基本信息

字段名类型说明数据来源
idint客户ID(会员号)m_client.id
usernamestring用户名/昵称m_client.username
mobilestring电话号码(不脱敏)m_client.mobile
headstring头像m_client.head
emergency_contactstring紧急联系人m_client_urgent_mobile_record.urgent_mobile
last_usernamestring收货人m_client.last_username
addressstring所在地province + city + area

等级/分组/站点

字段名类型说明数据来源
level_idint会员等级IDm_client.level_id
level_namestring会员等级名称m_level.name
group_idint运营分组IDm_client.group_id
group_namestring运营分组名称m_group.name
pre_sales_group_idint售前分组IDm_client.pre_sales_group_id
pre_sales_group_namestring售前分组名称admins_region_relations → admins.nickname
collage_idint所属站点IDm_client.collage_id
collage_namestring所属站点名称m_collection_points.name

推荐人

字段名类型说明数据来源
shareidint推荐人IDm_client.shareid
share_namestring推荐人名称m_client.username (自关联)

订单/交易

字段名类型说明数据来源
order_amount_totalstring交易总金额m_client.total_goods_fee (预计算)
today_order_statusint今日下单状态m_client_detail.today_buy_num > 0

时间信息

字段名类型说明数据来源
register_timestring注册时间m_client.time
last_login_timestring最近登录时间m_client.login_time
last_order_timestring最近购买时间m_client.last_order_date
next_trace_timestring下次跟进时间m_client_crm_trace (最早未处理)
no_order_daysint未下单天数(now - last_order_date) / 86400

账号信息

字段名类型说明数据来源
pointsint积分m_client_detail.points
growth_valueint成长值m_member_level_history.score (最新一条)
balancestring余额m_client.balance
creditstring授信额m_client.credit
order_goods_numberint购买量(扎)m_client.order_goods_number

状态/来源/备注

字段名类型说明数据来源
hasorderint下单状态m_client.hasorder
hasorder_namestring下单状态名称已下单 / 未下单
reg_typeint来源类型m_client.reg_type
reg_type_namestring来源名称后台创建 / 微信注册
remarkstring备注m_client.remark

09 性能说明

SQL 次数(固定,不随数据量增长)

#查询说明
1主查询m_client LEFT JOIN m_client_detail
2level_nameWHERE id = level_id
3group_nameWHERE id = group_id
4collage_nameWHERE id = collage_id
5share_nameWHERE id = shareid
6-7pre_sales_group_name两跳查询
8order_amount_totalm_client.total_goods_fee (无额外 SQL)
9next_trace_timeMIN(m_client_crm_trace.tracetime)
10emergency_contactm_client_urgent_mobile_record (LIMIT 1)
11growth_valuem_member_level_history (LIMIT 1)

总计:约 8-9 次 SQL(单次详情查询)

10 数据表清单总览

#表名中文名Model使用场景
1m_client客户主表ClientModel列表/详情
2m_client_detail客户明细表ClientDetailModel列表/详情
3m_client_crm_trace客户跟进表ClientCrmTraceModel列表/详情
4m_client_urgent_mobile_record紧急联系人表ClientUrgentMobileRecordModel详情
5m_member_level_history会员等级历史表MemberLevelHistoryModel详情
6m_level会员等级表LevelModel列表/详情
7m_group运营分组表GroupModel列表/详情
8m_collection_points集货点/站点表CollectionPointsModel列表/详情
9m_regions大区表RegionsModel列表
10m_compan平台表CompanModel列表
11m_company_sub_group平台分组表CompanySubGroupModel列表
12m_admins管理员表AdminsModel列表/详情
13m_admins_region_relations售前分组关系表AdminsRegionRelationsModel列表/详情
14m_order订单表OrderModel列表
15m_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 关联关系详表

#主表主表字段关系关联表关联表字段查询方式
1m_clientid1:1m_client_detailuidLEFT JOIN
2m_clientlevel_idN:1m_levelid批量 whereIn
3m_clientgroup_idN:1m_groupid批量 whereIn
4m_clientcollage_idN:1m_collection_pointsid批量 whereIn
5m_clientshareidN:1m_clientid批量 whereIn
6m_clientsidN:1m_companid批量 whereIn
7m_compansub_group_idN:1m_company_sub_groupid批量 whereIn
8m_clientpre_sales_group_idN:1m_admins_region_relationsidwhereIn
9m_admins_region_relationspidN:1m_adminsidwhereIn
10m_client_detailregion_idN:1m_regionsid批量 whereIn
11m_clientid1:Nm_client_crm_traceuidwhereIn + MIN
12m_clientid1:Nm_client_urgent_mobile_recorduser_idLIMIT 1
13m_clientid1:Nm_member_level_historyuidLIMIT 1
14m_clientid1:Nm_orderuidwhereIn + groupBy

13 字段来源速查表

客户列表返回字段

返回字段数据源表数据源字段说明
idm_clientid-
usernamem_clientusername-
headm_clienthead-
mobilem_clientmobile脱敏
sidm_clientsid-
sub_group_idm_compan→m_company_sub_groupsub_group_id→id两跳
sub_group_namem_compan→m_company_sub_groupsub_group_id→name两跳
platform_namem_companname-
collage_id_namem_collection_pointsname-
region_idm_client_detailregion_id-
region_namem_regionsname-
level_idm_clientlevel_id-
level_namem_levelname-
group_idm_clientgroup_id-
group_namem_groupname-
pre_sales_group_idm_clientpre_sales_group_id-
pre_sales_group_namem_admins_region_relations→m_adminspid→nickname两跳
last_usernamem_clientlast_username-
latest_addressm_clientlatest_province+city+area拼接
pointsm_client_detailpoints-
balancem_clientbalance-
creditm_clientcredit-
order_goods_numberm_clientorder_goods_number-
order_countm_client_detailbuy_count预计算
order_amount_totalm_clienttotal_goods_fee预计算
month_order_countm_orderCOUNT(*) 本月实时
month_order_goodsm_orderSUM(order_goods_num) 本月实时
today_order_goodsm_client_detailtoday_buy_num预计算
history_order_countm_client_detailbuy_count预计算
register_timem_clienttime格式化
register_daysm_clienttime计算
last_login_timem_clientlogin_time格式化
last_order_timem_clientlast_order_date格式化
next_trace_timem_client_crm_traceMIN(tracetime) WHERE status=0实时
no_order_daysm_clientlast_order_date / time计算
statusm_clientstatus-
status_namem_clientstatus映射
hasorderm_clienthasorder-
hasorder_namem_clienthasorder映射
crmclienttracem_clientcrmclienttrace-
crmclienttrace_namem_clientcrmclienttrace映射
stop_orderm_clientstop_order-
stop_order_namem_clientstop_order映射
reg_typem_clientreg_type-
reg_type_namem_clientreg_type映射
shareidm_clientshareid-
share_namem_client (自关联)username-

客户详情返回字段

返回字段数据源表数据源字段说明
idm_clientid-
usernamem_clientusername-
mobilem_clientmobile不脱敏
headm_clienthead-
level_idm_clientlevel_id-
level_namem_levelname-
group_idm_clientgroup_id-
group_namem_groupname-
pre_sales_group_idm_clientpre_sales_group_id-
pre_sales_group_namem_admins_region_relations→m_adminspid→nickname两跳
collage_idm_clientcollage_id-
collage_namem_collection_pointsname-
shareidm_clientshareid-
share_namem_client (自关联)username-
emergency_contactm_client_urgent_mobile_recordurgent_mobile最新一条
last_usernamem_clientlast_username-
addressm_clientprovince+city+area拼接
order_amount_totalm_clienttotal_goods_fee预计算
today_order_statusm_client_detailtoday_buy_num > 0计算
register_timem_clienttime格式化
last_login_timem_clientlogin_time格式化
last_order_timem_clientlast_order_date格式化
next_trace_timem_client_crm_traceMIN(tracetime) WHERE status=0实时
no_order_daysm_clientlast_order_date / time计算
pointsm_client_detailpoints-
growth_valuem_member_level_historyscore最新一条
balancem_clientbalance-
creditm_clientcredit-
order_goods_numberm_clientorder_goods_number-
hasorderm_clienthasorder-
hasorder_namem_clienthasorder映射
reg_typem_clientreg_type-
reg_type_namem_clientreg_type映射
remarkm_clientremark-

14 个人交易数据接口 GET V1

项目说明
接口地址GET /admin/v1/client/transaction-stats
本地地址http://192.168.111.30/admin/v1/client/transaction-stats?id=1
所属模块客户管理 - 客户详情页板块
适用场景客户详情页中的「个人交易数据」板块展示
是否需要登录

15 请求参数

参数名类型必填默认值说明
idint-客户ID
time_typestring时间快捷类型(优先于 start_time/end_time):
today:今日
week:本周(周一至周日)
month:本月
year:本年
all:全部
start_timestring开始时间(格式:Y-m-d,如 2026-01-01)
end_timestring结束时间(格式:Y-m-d,如 2026-12-31)
时间筛选规则
  1. 若传入 time_type,则忽略 start_time/end_time
  2. 若未传入 time_type,但传入了 start_timeend_time,则使用自定义时间范围
  3. 若都未传入,则返回全部累计数据

16 返回字段

字段名类型说明数据来源
order_goods_numberint购买扎数(订单商品数量合计)SUM(m_order.order_goods_num)
order_countint下单次数(有效订单数)COUNT(m_order.id)
order_amountstring交易金额(订单总金额合计,保留2位小数)SUM(m_order.total_price)
time_typestring时间快捷类型(回传,便于前端展示)请求参数原样返回
start_timestring实际生效的开始日期(Y-m-d)解析后的时间范围
end_timestring实际生效的结束日期(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:0012月31日 23:59:59
all全部nullnull

05 会员成长统计接口 GET V1

项目说明
接口地址GET /admin/v1/client/member-growth-stats
本地地址http://192.168.111.30/admin/v1/client/member-growth-stats
所属模块客户管理
接口用途客户详情页面 - 会员成长板块

06 请求参数

参数名类型必填说明
idint客户ID

07 返回字段

等级信息

字段名类型说明数据来源
yesterday_level_idint会员昨日等级IDm_member_level_history.member_level
yesterday_level_namestring会员昨日等级名称m_member_level.name
last_week_level_idint上周等级IDm_member_level_history.member_level
last_week_level_namestring上周等级名称m_member_level.name
last_month_level_idint上月等级IDm_member_level_history.member_level
last_month_level_namestring上月等级名称m_member_level.name

保级期信息

字段名类型说明数据来源
has_relegationint是否有保级期(0:无, 1:有)m_member_level.is_relegation
relegation_daysint保级期天数待确认 计算逻辑待业务确认
relegation_cntint已保级次数m_member_level_history.relegation_cnt
待确认relegation_days 保级期天数的具体计算逻辑尚未明确,待业务方确认保级周期、降级触发条件等规则后再补充实现。当前默认返回 0。

基本信息

字段名类型说明数据来源
register_timestring注册时间m_client.time

采购统计(近30天)

字段名类型说明数据来源
thirty_day_goods_numint累计采购扎数SUM(m_order.order_goods_num) WHERE date >= 30天前
thirty_day_order_countint累计采购次数COUNT(*) FROM m_order WHERE date >= 30天前

综合评分

字段名类型说明数据来源
scoreint综合价值评分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保级周期是多长?降级触发条件是什么?需业务方提供完整规则