scottpan/integral-shop
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
integral-shop/backend/docs/API分析总结-2025-11-08.md
apple 5432904bcb Initial commit: 单商户积分商城 - 管理后台前端 + CRMEB 后端 
Made-with: Cursor
2026-03-08 18:35:11 +08:00

9.2 KiB
Raw Permalink Blame History

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 实现限流和防重复

实现方式:

// 限流 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. 基础功能测试

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

Reference in New Issue View Git Blame Copy Permalink