存量用户套餐推荐系统

基于用户画像的智能套餐推荐系统，助力精准营销。

系统概述

本系统是一个本地前后端一体的应用，支持在网页中维护套餐目录，用户上传Excel清单后端分析并返回推荐结果，在页面展示并支持导出。通过基于多维度画像的简化规则，实现"价格档位优先 + 资源匹配约束"的套餐推荐。

核心功能

• 套餐管理：在网页中新增、编辑、删除套餐信息，实时更新套餐目录数据库
• 推荐计算：上传用户清单Excel文件，系统根据ARPU和资源需求自动推荐最优套餐
• 结果导出：推荐完成后，可将结果导出为CSV文件，方便后续分析和使用

技术栈

组件	技术	说明
前端	React 19 + Tailwind CSS 4	现代化UI框架
后端	Express 4 + tRPC 11	类型安全的API
数据库	MySQL/TiDB + Drizzle ORM	关系型数据库
数据处理	xlsx库	Excel文件解析
测试	Vitest	单元测试框架

系统架构

数据库模型

plans表：存储套餐目录信息

字段	类型	说明
id	INT	主键，自增
name	VARCHAR	套餐名称
price	INT	资费（元/月）
dataGb	INT	包含流量（GB）
voiceMin	INT	包含通话（分钟）
broadband	VARCHAR	宽带速率
benefits	TEXT	附加权益
onShelf	INT	是否在售（1=是，0=否）
createdAt	TIMESTAMP	创建时间
updatedAt	TIMESTAMP	更新时间

recommendations表：存储推荐历史（可选）

API接口

套餐管理API

获取所有套餐

GET /api/trpc/plans.list

新增套餐

POST /api/trpc/plans.create
Content-Type: application/json

{
  "name": "5G畅享套餐",
  "price": 99,
  "dataGb": 30,
  "voiceMin": 500,
  "broadband": "300M",
  "benefits": "视频会员",
  "onShelf": 1
}

更新套餐

POST /api/trpc/plans.update
Content-Type: application/json

{
  "id": 1,
  "name": "5G畅享套餐",
  "price": 99,
  ...
}

删除套餐

POST /api/trpc/plans.delete
Content-Type: application/json

{
  "id": 1
}

推荐API

批量推荐

POST /api/trpc/recommend.batch
Content-Type: application/json

{
  "users": [
    {
      "phone": "13800000001",
      "location": "北京",
      "mainPlan": "标准套餐",
      "currentPrice": 79,
      "arpu": 120,
      "dataGb": 20,
      "voiceMin": 400
    }
  ]
}

响应示例

{
  "count": 1,
  "items": [
    {
      "phone": "13800000001",
      "location": "北京",
      "mainPlan": "标准套餐",
      "currentPrice": 79,
      "arpu": 120,
      "dataGb": 20,
      "voiceMin": 400,
      "recommendedPlanId": 3,
      "recommendedPlanName": "高级套餐",
      "recommendedPrice": 129,
      "recommendedDataGb": 30,
      "recommendedVoiceMin": 500,
      "recommendedBroadband": "300M",
      "recommendedBenefits": "视频会员+音乐会员",
      "targetPrice": 129,
      "diff": 41,
      "reason": "高一档 + 资源匹配",
      "resourceRisk": false
    }
  ]
}

推荐规则

系统采用基于价格档位和资源匹配的推荐算法：

价格档位规则

根据用户ARPU与当前套餐价格的差值（diff = ARPU - 当前价格）选择目标价位：

条件	推荐策略
diff ≤ 10	推荐相近档位（优先同价位；无同价则选最接近价位）
10 < diff ≤ 50	推荐比当前档位高一档的套餐
diff > 50	先定位到"不高于ARPU"的价位，再向下偏移3档作为目标价位

资源匹配规则

在目标价位内选择最优套餐：

1. 资源满足集：优先选择同时满足"套餐流量 ≥ 用户流量 且 套餐通话 ≥ 用户通话"的套餐
2. 排序策略：按剩余资源分数排序，分数越低越优先（资源越接近）
3. 资源不足：若无完全满足的套餐，选择拟合分数最低的方案，并标记"资源风险=是"

使用指南

1. 启动系统

系统已部署在云端，访问以下URL即可使用：

https://3000-i79lf25b4a6vfwxg61uu8-e4c0f111.manus-asia.computer

2. 套餐管理

步骤1：进入套餐管理页面

• 点击首页的"管理套餐"按钮

步骤2：添加套餐

• 在左侧表单中填写套餐信息
• 点击"添加套餐"按钮
• 系统会自动保存到数据库

步骤3：查看套餐列表

• 右侧表格显示所有套餐
• 显示在售套餐统计数量
• 可删除不需要的套餐

3. 推荐计算

步骤1：准备Excel文件

Excel文件格式要求：

列号	字段名	说明	示例
1	联系电话	用户电话	13800000001
2	归属地	用户所在地	北京
3	主套餐	用户当前套餐	标准套餐
4	档位	当前套餐价格	79
5	流量饱和度	流量使用率	85%
6	语音饱和度	通话使用率	75%
7	近三个月ARPU	平均收入	120
8	流量	用户流量需求(GB)	20
9	通话	用户通话需求(分钟)	400
10	超套金额	超出套餐金额	50
11	超套比例	超出套餐比例	10%
12	备注	其他信息	备注

步骤2：上传文件

• 进入推荐计算页面
• 点击上传区域或拖拽Excel文件
• 选择.xlsx或.xls格式的文件

步骤3：查看推荐结果

• 系统自动计算推荐结果
• 表格显示每个用户的推荐套餐和推荐理由
• 资源风险列显示是否存在资源不足

步骤4：导出结果

• 点击"导出CSV"按钮
• 系统生成包含完整推荐信息的CSV文件
• 可在Excel中打开进一步分析

数据清洗规则

系统自动处理以下特殊值：

特殊值	处理方式
"不限"或"∞"	视作极大值（1e9）
"85%"	自动转换为0.85
"1,000"	移除千分位逗号
空值	按0处理

推荐示例

示例1：相近档位推荐

• 用户档位：79元
• 用户ARPU：85元
• 差值：6元（≤10）
• 推荐：相近档位套餐（优先选择79元套餐）

示例2：高一档推荐

• 用户档位：79元
• 用户ARPU：120元
• 差值：41元（10-50）
• 推荐：高一档套餐（129元档位）

示例3：低于ARPU三档推荐

• 用户档位：39元
• 用户ARPU：128元
• 差值：89元（>50）
• 价阶序列：[39, 79, 129, 199]
• 不高于128的最大价位：129元（索引2）
• 向下偏移3档：索引2-3=-1，取0，即39元档位
• 推荐：39元档位套餐

故障排查

问题	解决方案
无法访问系统	确认网络连接，检查URL是否正确
添加套餐失败	确保所有必填项已填写，刷新页面重试
上传Excel失败	确认文件格式为.xlsx或.xls，文件未被其他程序打开
推荐结果为空	确认数据库中存在"在售"套餐，Excel中关键字段有值
导出CSV失败	检查浏览器下载权限，尝试清空缓存

性能指标

• 处理速度：单批次用户清单1万级以内可在数十秒内完成
• 支持规模：取决于硬件配置和网络速度
• 优化建议：按需分批上传；结果分页展示

测试覆盖

系统包含完整的单元测试，覆盖以下场景：

• 价格档位选择算法（diff=10、diff=50、diff>50）
• 资源匹配和候选套餐排序
• 数据清洗规则
• 边界值处理
• 错误处理和异常情况

运行测试：

pnpm test

开发指南

项目结构

package_recommendation_system/
├── client/                    # 前端应用
│   ├── src/
│   │   ├── pages/            # 页面组件
│   │   │   ├── Home.tsx      # 首页
│   │   │   ├── PlanManagement.tsx  # 套餐管理
│   │   │   └── Recommendation.tsx  # 推荐计算
│   │   ├── components/       # 可复用组件
│   │   ├── lib/trpc.ts       # tRPC客户端
│   │   └── App.tsx           # 应用入口
│   └── public/               # 静态资源
├── server/                    # 后端应用
│   ├── routers.ts            # API路由定义
│   ├── db.ts                 # 数据库查询函数
│   ├── recommendation-engine.ts  # 推荐引擎核心逻辑
│   ├── recommendation-engine.test.ts  # 推荐引擎测试
│   ├── excel-parser.ts       # Excel解析工具
│   └── _core/                # 框架核心代码
├── drizzle/                  # 数据库schema和迁移
│   └── schema.ts             # 表定义
└── README.md                 # 本文件

添加新功能

1. 更新数据库schema：修改drizzle/schema.ts
2. 运行迁移：pnpm db:push
3. 添加查询函数：在server/db.ts中添加
4. 创建API路由：在server/routers.ts中添加
5. 开发前端UI：在client/src/pages/中创建新页面
6. 编写测试：创建.test.ts文件
7. 保存检查点：pnpm checkpoint

常见问题

Q：系统支持多用户吗？ A：当前版本不支持用户登录和多租户，所有数据共享。如需支持，可通过添加用户认证模块扩展。

Q：能否修改推荐规则？ A：可以。推荐规则在server/recommendation-engine.ts中定义，修改后需重新部署。

Q：推荐结果如何保存？ A：推荐结果可导出为CSV文件。如需持久化存储，可在server/db.ts中添加saveRecommendation函数。

Q：系统支持哪些Excel格式？ A：支持.xlsx和.xls格式。其他格式（如.csv）需先转换。

许可证

本项目为内部使用系统，仅供授权用户使用。

联系方式

如有问题或建议，请联系系统管理员。