395 lines
9.2 KiB
Markdown
395 lines
9.2 KiB
Markdown
# API 分析总结报告
|
||
|
||
> **分析日期**: 2025-11-08
|
||
> **数据源**: webman-2025-11-03.log (446,330 行日志)
|
||
> **前端文件**: static/js/*.js (48 个编译文件)
|
||
|
||
---
|
||
|
||
## 📊 分析统计
|
||
|
||
### 接口统计
|
||
|
||
| 项目 | 数量 |
|
||
|------|------|
|
||
| **API接口总数** | 33 个 |
|
||
| **数据库表** | 9 个主要表 |
|
||
| **分析日志行数** | 446,330 行 |
|
||
| **JS文件数** | 48 个 |
|
||
|
||
### 接口分布
|
||
|
||
```
|
||
用户认证接口: 5 个 (15.2%)
|
||
├── 登录、注册、信息查询、修改密码、修改昵称
|
||
|
||
商品相关接口: 3 个 (9.1%)
|
||
├── 分类、列表、详情
|
||
|
||
订单相关接口: 9 个 (27.3%)
|
||
├── 首页、商品列表、购买、支付、确认、取消、转卖、订单列表、订单详情
|
||
|
||
地址管理接口: 5 个 (15.2%)
|
||
├── 列表、新增、修改、删除、默认地址
|
||
|
||
财务相关接口: 3 个 (9.1%)
|
||
├── 明细列表、提现记录、申请提现
|
||
|
||
支付相关接口: 3 个 (9.1%)
|
||
├── 支付宝信息、绑定支付宝、银行卡信息
|
||
|
||
分享推广接口: 2 个 (6.1%)
|
||
├── 分享数据、粉丝列表
|
||
|
||
首页相关接口: 2 个 (6.1%)
|
||
├── 轮播图、配置数据
|
||
|
||
短信相关接口: 1 个 (3.0%)
|
||
├── 发送验证码
|
||
|
||
其他接口: 1 个 (3.0%)
|
||
├── 签名回调
|
||
```
|
||
|
||
---
|
||
|
||
## 🔍 关键发现
|
||
|
||
### 1. 非标准认证头
|
||
|
||
**发现**: 认证头使用 `Authori-zation` 而非标准的 `Authorization`
|
||
|
||
**影响**: 需要在前端和测试工具中特别注意此配置
|
||
|
||
**位置**: 所有需要登录的接口
|
||
|
||
---
|
||
|
||
### 2. POST 方法用于查询
|
||
|
||
**发现**: 部分查询接口使用 POST 方法而非 GET
|
||
|
||
**接口列表**:
|
||
- `/api/user/info` - 获取用户信息
|
||
- `/api/index/get` - 获取首页配置
|
||
- `/api/order/index` - 获取订单首页
|
||
- `/api/address/default` - 获取默认地址
|
||
|
||
**原因**: 可能出于安全考虑或框架设计
|
||
|
||
---
|
||
|
||
### 3. 复杂的订单系统
|
||
|
||
**发现**: 订单系统采用寄卖模式，有独特的业务逻辑
|
||
|
||
**特点**:
|
||
- 双仓库设计（买方仓库、卖方仓库）
|
||
- 三状态流转（待支付→已支付→已完成）
|
||
- 抢单机制（使用 Redis 防止重复购买）
|
||
- 支持转卖功能
|
||
|
||
**核心表**:
|
||
- `wa_merchandise` - 寄卖商品表
|
||
- `wa_order` - 订单表
|
||
- 两表通过 UNION 查询实现仓库视图
|
||
|
||
---
|
||
|
||
### 4. 分红系统
|
||
|
||
**发现**: 三级分红体系
|
||
|
||
**分类**:
|
||
1. **自购分红** (self_bonus) - 存储在 `wa_selfbonus_log`
|
||
2. **推广分红** (share_bonus) - 存储在 `wa_sharebonus_log`
|
||
3. **优惠券** (coupon) - 存储在 `wa_coupon_log`
|
||
|
||
**触发时机**: 订单确认发货后自动计算分红
|
||
|
||
**比例配置**:
|
||
- `self_ratio` - 自购分红比例
|
||
- `share_ratio` - 推广分红比例
|
||
- `up_ratio` - 加价比例
|
||
|
||
---
|
||
|
||
### 5. 限流机制
|
||
|
||
**发现**: 关键操作使用 Redis 实现限流和防重复
|
||
|
||
**实现方式**:
|
||
```php
|
||
// 限流 key 格式
|
||
rate-limiter-{date}:rate-limiter-{controller}-{action}-ip-{ip}-{timestamp}-1
|
||
|
||
// 防重复 key 格式
|
||
buy_id_{merchandise_id} // 购买操作，10秒锁
|
||
confirm_id_{order_id} // 确认操作，10秒锁
|
||
```
|
||
|
||
**保护接口**:
|
||
- `/api/order/buy` - 购买商品
|
||
- `/api/order/pay` - 支付订单
|
||
- `/api/order/confirm` - 确认订单
|
||
|
||
---
|
||
|
||
### 6. 营业时间控制
|
||
|
||
**发现**: 系统有营业时间限制
|
||
|
||
**配置字段**:
|
||
- `open_week` - 开放星期，如 "1,2,3,4,5"
|
||
- `start_time` - 开始时间，如 "09:00"
|
||
- `end_time` - 结束时间，如 "21:00"
|
||
|
||
**影响**: 非营业时间无法购买商品
|
||
|
||
---
|
||
|
||
## 📋 数据库表结构
|
||
|
||
### 主要数据表
|
||
|
||
| 表名 | 说明 | 关键字段 |
|
||
|------|------|---------|
|
||
| **wa_users** | 用户表 | id, mobile, nickname, share_bonus, self_bonus, coupon, pid(上级ID) |
|
||
| **wa_banner** | 轮播图表 | id, image, url, weight |
|
||
| **wa_category** | 商品分类表 | id, name, status, weight |
|
||
| **wa_goods** | 商品表 | id, title, images, price, line_price, sales_volume, status |
|
||
| **wa_merchandise** | 寄卖商品表 | id, user_id, price, status, is_show, created_at |
|
||
| **wa_order** | 订单表 | id, seller_id, buyer_id, merchandise_id, order_sn, total_money, status, consignee, phone, province, city, area, address |
|
||
| **wa_address** | 收货地址表 | id, user_id, consignee, phone, province, city, area, address, is_default |
|
||
| **wa_sharebonus_log** | 推广分红日志 | id, user_id, type, money, before, after, memo, created_at |
|
||
| **wa_selfbonus_log** | 自购分红日志 | id, user_id, type, money, before, after, memo, created_at |
|
||
| **wa_coupon_log** | 优惠券日志 | id, user_id, type, money, before, after, memo, created_at |
|
||
| **wa_sms** | 短信验证码表 | id, mobile, event, code, ip, created_at |
|
||
| **wa_setting** | 系统配置表 | id, name, title, value |
|
||
| **wa_bank** | 银行卡表 | id, user_id, bank_name, bank_account, account_name |
|
||
|
||
---
|
||
|
||
## 🔐 安全机制
|
||
|
||
### 1. Token 认证
|
||
|
||
- 使用 JWT Token
|
||
- Header: `Authori-zation: Bearer {token}`
|
||
- 所有需要用户身份的接口都需要携带
|
||
|
||
### 2. 短信验证
|
||
|
||
- 事件类型: register, resetpwd, changepwd
|
||
- IP 限制: 每天每 IP 有发送次数限制
|
||
- 验证码存储在 `wa_sms` 表
|
||
|
||
### 3. 限流保护
|
||
|
||
- 使用 Redis 实现
|
||
- 关键操作有频率限制
|
||
- 防止恶意刷单
|
||
|
||
### 4. 防重复提交
|
||
|
||
- 使用 Redis 锁机制
|
||
- 关键操作 10 秒内只能提交一次
|
||
- 购买、支付、确认等操作受保护
|
||
|
||
---
|
||
|
||
## 📈 业务流程
|
||
|
||
### 订单完整流程
|
||
|
||
```
|
||
1. 用户寄卖商品
|
||
└─> 插入 wa_merchandise (status=1, is_show=1)
|
||
|
||
2. 买家浏览商品
|
||
└─> GET /api/order/goods
|
||
|
||
3. 买家抢单
|
||
└─> POST /api/order/buy
|
||
├─> 检查营业时间
|
||
├─> 检查购买次数限制
|
||
├─> Redis 加锁防重复
|
||
├─> 插入订单 wa_order (status=0)
|
||
└─> 更新寄卖商品状态 (status=0)
|
||
|
||
4. 买家支付
|
||
└─> POST /api/order/pay
|
||
├─> 选择收货地址
|
||
├─> 更新订单状态 (status=1)
|
||
└─> 填充收货信息
|
||
|
||
5. 卖家确认发货
|
||
└─> POST /api/order/confirm
|
||
├─> 更新订单状态 (status=2)
|
||
├─> 计算自购分红 (self_bonus)
|
||
├─> 计算推广分红 (share_bonus)
|
||
├─> 插入分红日志
|
||
└─> 更新用户余额
|
||
|
||
6. 订单完成
|
||
└─> 可以在列表中查看 (type=2)
|
||
```
|
||
|
||
### 分红计算流程
|
||
|
||
```
|
||
订单确认后触发:
|
||
|
||
1. 计算买家自购分红
|
||
└─> self_bonus += order_money * self_ratio
|
||
|
||
2. 计算卖家上级推广分红
|
||
└─> share_bonus += order_money * share_ratio
|
||
|
||
3. 递归查询上级团队
|
||
└─> 记录团队层级关系
|
||
|
||
4. 写入分红日志
|
||
└─> 记录 before, after, money
|
||
```
|
||
|
||
---
|
||
|
||
## 🧪 测试建议
|
||
|
||
### 1. 基础功能测试
|
||
|
||
```bash
|
||
# 1. 登录获取 Token
|
||
TOKEN=$(curl -X POST http://miao1admin.suzhouyuqi.com/api/user/login \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"account":"18379637515","password":"123456"}' \
|
||
| jq -r '.data.token')
|
||
|
||
# 2. 获取用户信息
|
||
curl -X POST http://miao1admin.suzhouyuqi.com/api/user/info \
|
||
-H "Authori-zation: Bearer $TOKEN"
|
||
|
||
# 3. 获取商品列表
|
||
curl "http://miao1admin.suzhouyuqi.com/api/order/goods?page=1&limit=20" \
|
||
-H "Authori-zation: Bearer $TOKEN"
|
||
|
||
# 4. 查看订单列表
|
||
curl "http://miao1admin.suzhouyuqi.com/api/order/list?cate=2&type=1&page=1&limit=10" \
|
||
-H "Authori-zation: Bearer $TOKEN"
|
||
```
|
||
|
||
### 2. 压力测试要点
|
||
|
||
- **抢单接口**: 测试并发购买同一商品
|
||
- **支付接口**: 测试重复支付同一订单
|
||
- **短信接口**: 测试频繁发送验证码
|
||
|
||
### 3. 边界条件测试
|
||
|
||
- 营业时间外购买
|
||
- 超过每日购买限制
|
||
- 余额不足提现
|
||
- 地址信息校验
|
||
|
||
---
|
||
|
||
## 📝 改进建议
|
||
|
||
### 1. API 设计
|
||
|
||
**建议**: 统一查询接口使用 GET 方法
|
||
|
||
**当前**: `/api/user/info` 使用 POST 方法查询用户信息
|
||
|
||
**改进**: 改为 GET 方法，符合 RESTful 规范
|
||
|
||
---
|
||
|
||
### 2. 认证头标准化
|
||
|
||
**建议**: 使用标准的 `Authorization` 头
|
||
|
||
**当前**: `Authori-zation` (拼写错误)
|
||
|
||
**改进**: 改为 `Authorization`，提升兼容性
|
||
|
||
---
|
||
|
||
### 3. 错误码规范
|
||
|
||
**建议**: 建立完整的错误码体系
|
||
|
||
**当前**: 只有 `code: 0` 表示成功
|
||
|
||
**改进**: 定义标准错误码，如：
|
||
- 1000-1999: 参数错误
|
||
- 2000-2999: 业务错误
|
||
- 3000-3999: 系统错误
|
||
|
||
---
|
||
|
||
### 4. 接口文档
|
||
|
||
**建议**: 使用 OpenAPI/Swagger 规范
|
||
|
||
**当前**: Markdown 文档
|
||
|
||
**改进**: 生成可交互的 API 文档，支持在线测试
|
||
|
||
---
|
||
|
||
### 5. 日志优化
|
||
|
||
**建议**: 增加结构化日志
|
||
|
||
**当前**: 混合格式日志
|
||
|
||
**改进**: 统一日志格式，便于分析和监控
|
||
|
||
---
|
||
|
||
## 📦 交付物清单
|
||
|
||
1. ✅ **后端API接口文档.md** - 完整的 33 个接口文档
|
||
2. ✅ **API分析总结-2025-11-08.md** - 本分析报告
|
||
3. ✅ **服务器日志API分析.md** - 原有日志分析文档（已存在）
|
||
|
||
---
|
||
|
||
## 🎯 后续工作建议
|
||
|
||
### 短期 (1-2 周)
|
||
|
||
1. 完善接口单元测试
|
||
2. 补充接口返回示例（真实数据）
|
||
3. 编写前端 API SDK
|
||
4. 配置 API 监控告警
|
||
|
||
### 中期 (1-2 月)
|
||
|
||
1. 接口性能优化
|
||
2. 迁移到 OpenAPI 规范
|
||
3. 增加接口版本控制
|
||
4. 完善错误处理机制
|
||
|
||
### 长期 (3-6 月)
|
||
|
||
1. 微服务化改造
|
||
2. 引入 API 网关
|
||
3. 实现接口灰度发布
|
||
4. 建立 API 生命周期管理
|
||
|
||
---
|
||
|
||
## 📞 联系方式
|
||
|
||
如有疑问或需要进一步分析，请联系开发团队。
|
||
|
||
---
|
||
|
||
**文档生成时间**: 2025-11-08
|
||
**文档版本**: v1.0
|
||
**分析工具**: Cursor AI + 日志分析
|
||
|