integral-shop-mgtv1/crmeb_22miao/docs/API分析总结-2025-11-08.md

# 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 + 日志分析