咨询客服
可以。下面整理成一份可直接交给后端、前端联调和测试使用的 《API 接口文档》。其中 /mob/UCenter/sqsj_ck_save 和 /mob/UCenter/sqsj_ck_update 是目前检查到的现有接口；其余 /api/... 为建议的新版本接口规范。
会员推荐关系 + 新零售商城
API 接口文档
版本： V1.0
接口风格： RESTful JSON API
认证方式： Cookie Session / Token 二选一
数据格式： JSON
字符编码： UTF-8
基础路径：
/api1. 接口设计总览
API 按业务域拆分：
/api
├── auth
│ ├── 登录
│ ├── 注册
│ ├── 退出
│ └── 当前用户
│
├── member
│ ├── 会员信息
│ ├── 等级
│ ├── 邀请
│ └── 升级
│
├── team
│ └── 团队成员
│
├── catalog
│ ├── 首页
│ ├── 分类
│ ├── 专区
│ ├── 商品
│ └── 搜索
│
├── cart
│ └── 购物车
│
├── address
│ └── 收货地址
│
├── order
│ ├── 订单
│ └── 支付
│
├── asset
│ ├── 积分
│ ├── 流水
│ ├── 转账
│ └── 提现
│
├── account
│ ├── 资料
│ ├── 收藏
│ ├── 关注
│ └── 浏览记录
│
└── common
├── 上传
├── 配置
└── 字典2. 统一请求规范
2.1 HTTP Header
Content-Type: application/json
Accept: application/json如果使用 Token：
Authorization: Bearer {token}如果使用 Cookie Session，则无需前端手动传 user_id。
3. 统一响应结构
所有接口统一：
{
"code": 0,
"message": "success",
"data": {}
}成功：
{
"code": 0,
"message": "success",
"data": {}
}业务失败：
{
"code": 4001,
"message": "当前会员等级不允许升级",
"data": null
}系统异常：
{
"code": 5000,
"message": "系统繁忙，请稍后重试",
"data": null
}4. 统一错误码
| Code | 含义 |
|---|---|
| 0 | 成功 |
| 4000 | 参数错误 |
| 4001 | 业务校验失败 |
| 4002 | 状态冲突 |
| 4010 | 未登录 |
| 4030 | 无权限 |
| 4040 | 数据不存在 |
| 4090 | 重复操作 |
| 4220 | 数据验证失败 |
| 4290 | 请求过于频繁 |
| 5000 | 系统异常 |
| 5001 | 数据库异常 |
| 5002 | 第三方服务异常 |
5. 分页规范
列表接口统一：
GET /api/team/members?page=1&page_size=20返回：
{
"code": 0,
"message": "success",
"data": {
"items": [],
"page": 1,
"page_size": 20,
"total": 100,
"has_more": true
}
}最大：
page_size <= 1006. 日期时间规范
统一使用：
ISO 8601例如：
2026-09-21T10:30:00+08:00数据库可使用 UTC 存储，前端根据用户时区展示。
7. 用户认证 API
7.1 登录
POST /api/auth/loginRequest：
{
"mobile": "13800138000",
"password": "********"
}Response：
{
"code": 0,
"message": "登录成功",
"data": {
"user": {
"id": 10001,
"mobile": "13800138000",
"name": "张三",
"avatar": ""
}
}
}如果使用 Token：
{
"code": 0,
"message": "登录成功",
"data": {
"token": "xxx",
"expires_in": 7200,
"user": {}
}
}服务端处理
账号存在
↓
账号状态正常
↓
校验密码
↓
记录登录日志
↓
创建 Session/Token
↓
返回用户信息安全要求
必须：
- 限制连续失败次数
- 登录接口限流
- 密码不得记录日志
- HTTPS
- Session 安全配置
7.2 获取当前用户
GET /api/auth/meResponse：
{
"code": 0,
"message": "success",
"data": {
"id": 10001,
"mobile": "138****8000",
"name": "张三",
"avatar": "",
"member": {
"level_id": 1,
"level_name": "一星会员"
}
}
}7.3 退出登录
POST /api/auth/logoutResponse：
{
"code": 0,
"message": "退出成功",
"data": null
}8. 注册 API
8.1 获取推荐人
GET /api/auth/referrer?tid=10001Response：
{
"code": 0,
"message": "success",
"data": {
"id": 10001,
"name": "张三",
"level_name": "一星会员"
}
}服务端只能返回必要信息，不返回完整手机号等敏感字段。
8.2 注册
POST /api/auth/registerRequest：
{
"mobile": "13900139000",
"wechat": "wx_user",
"name": "李四",
"password": "********",
"password_confirm": "********",
"referrer_id": 10001
}服务端处理
校验手机号
↓
检查手机号是否已注册
↓
校验密码
↓
校验 referrer_id
↓
确认推荐人有效
↓
创建用户
↓
创建会员
↓
建立推荐关系
↓
提交事务注意
不允许：
{
"user_id": 10002,
"level_id": 5
}由客户端直接指定自己创建后的会员等级。
会员等级应由服务端决定。
9. 会员 API
9.1 获取会员信息
GET /api/member/profileResponse：
{
"code": 0,
"message": "success",
"data": {
"user_id": 10001,
"level": {
"id": 1,
"name": "一星会员",
"sort": 1
},
"invite_code": "ABC123",
"permissions": [
"member.upgrade.apply",
"member.team.view"
]
}
}9.2 获取会员工作台
GET /api/member/dashboardResponse：
{
"code": 0,
"message": "success",
"data": {
"member": {},
"announcement": {},
"statistics": {
"team_count": 12,
"pending_upgrade": 2
},
"shortcuts": [
{
"key": "invite",
"title": "邀请注册",
"enabled": true
},
{
"key": "upgrade",
"title": "申请升级",
"enabled": true
},
{
"key": "review",
"title": "下级审核",
"enabled": false
}
]
}
}10. 邀请 API
10.1 获取邀请信息
GET /api/member/inviteResponse：
{
"code": 0,
"message": "success",
"data": {
"invite_code": "ABC123",
"invite_url": "https://example.com/register?tid=10001"
}
}二维码可以由：
- 服务端生成
- 前端根据 invite_url 生成
二选一。
11. 会员升级 API
11.1 获取升级资格
GET /api/member/upgrade/eligibilityResponse：
{
"code": 0,
"message": "success",
"data": {
"current_level": {
"id": 1,
"name": "一星会员"
},
"next_level": {
"id": 2,
"name": "二星会员"
},
"can_apply": true,
"reason": ""
}
}不能申请：
{
"code": 0,
"message": "success",
"data": {
"can_apply": false,
"reason": "已有待审核申请"
}
}11.2 提交升级申请
现有接口
当前前端检查到：
POST /mob/UCenter/sqsj_ck_save其请求结构和权限机制需要后端进一步确认。
新版推荐接口
POST /api/member/upgrade/applyRequest：
{
"remark": ""
}不需要客户端提交：
user_id
current_level
target_level服务端自行读取。
服务端处理
当前用户
↓
读取当前等级
↓
查询下一等级
↓
检查升级条件
↓
检查是否存在待审核记录
↓
创建 upgrade_request
↓
返回申请记录Response：
{
"code": 0,
"message": "申请已提交",
"data": {
"request_id": 90001,
"status": "pending",
"from_level": "一星会员",
"to_level": "二星会员",
"created_at": "2026-09-21T10:30:00+08:00"
}
}11.3 升级记录
GET /api/member/upgrade/requests?page=1&page_size=20Response：
{
"code": 0,
"message": "success",
"data": {
"items": [
{
"id": 90001,
"from_level": "一星会员",
"to_level": "二星会员",
"status": "pending",
"created_at": "2026-09-21T10:30:00+08:00",
"reviewed_at": null
}
],
"page": 1,
"page_size": 20,
"total": 1,
"has_more": false
}
}12. 下级升级审核 API
12.1 待审核列表
GET /api/member/upgrade/review/list?page=1&page_size=20服务端必须根据当前登录用户自动过滤其有权审核的申请。
禁止：
GET /api/member/upgrade/review/list?user_id=xxx然后直接返回全部数据。
12.2 审核详情
GET /api/member/upgrade/review/{request_id}Response：
{
"code": 0,
"message": "success",
"data": {
"request_id": 90001,
"applicant": {
"id": 10002,
"name": "李四",
"mobile": "139****9000",
"wechat": "wx****"
},
"from_level": {
"id": 1,
"name": "一星会员"
},
"to_level": {
"id": 2,
"name": "二星会员"
},
"status": "pending",
"created_at": "2026-09-21T10:30:00+08:00"
}
}12.3 审核申请
现有接口
当前前端检查到：
POST /mob/UCenter/sqsj_ck_update当前动作码：
90 = 同意
30 = 拒绝新版推荐
POST /api/member/upgrade/reviewRequest：
{
"request_id": 90001,
"action": "approve",
"remark": ""
}或者：
{
"request_id": 90001,
"action": "reject",
"remark": "暂不符合升级条件"
}approve 业务流程
检查 request_id
↓
检查状态 = pending
↓
检查审核人权限
↓
检查申请人属于审核范围
↓
再次校验升级条件
↓
更新会员等级
↓
更新申请状态
↓
写审核日志
↓
事务提交reject
检查权限
↓
检查状态
↓
记录拒绝原因
↓
更新申请状态
↓
写日志13. 团队 API
13.1 团队概览
GET /api/team/summaryResponse：
{
"code": 0,
"message": "success",
"data": {
"direct_count": 12,
"total_count": 12,
"levels": [
{
"level_name": "一星会员",
"count": 8
},
{
"level_name": "二星会员",
"count": 3
},
{
"level_name": "三星会员",
"count": 1
}
]
}
}13.2 团队成员
GET /api/team/members?page=1&page_size=20Response：
{
"code": 0,
"message": "success",
"data": {
"items": [
{
"id": 10002,
"name": "李四",
"mobile": "139****9000",
"level_name": "一星会员",
"created_at": "2026-09-20T10:00:00+08:00"
}
],
"page": 1,
"page_size": 20,
"total": 1,
"has_more": false
}
}14. 商品 API
14.1 商城首页
GET /api/catalog/homeResponse：
{
"code": 0,
"message": "success",
"data": {
"banners": [],
"categories": [],
"zones": [],
"recommended_products": []
}
}14.2 分类列表
GET /api/catalog/categoriesResponse：
{
"code": 0,
"message": "success",
"data": [
{
"id": 1,
"name": "食品",
"children": []
}
]
}14.3 商品列表
GET /api/catalog/products参数：
category_id
zone_id
keyword
sort
page
page_size示例：
GET /api/catalog/products?category_id=1&sort=latest&page=1&page_size=2014.4 商品详情
GET /api/catalog/products/{product_id}Response：
{
"code": 0,
"message": "success",
"data": {
"id": 10001,
"name": "商品名称",
"cover": "",
"images": [],
"description": "",
"price": 199,
"points_discount_enabled": true,
"points_rate": 100,
"stock": 100,
"skus": []
}
}15. SKU API
商品有规格时：
GET /api/catalog/products/{product_id}/skus返回：
{
"code": 0,
"message": "success",
"data": [
{
"id": 100001,
"sku_code": "SKU001",
"name": "红色",
"price": 199,
"stock": 20
}
]
}16. 购物车 API
16.1 查询购物车
GET /api/cart16.2 加入购物车
POST /api/cart/itemsRequest：
{
"sku_id": 100001,
"quantity": 1
}服务端重新检查：
SKU 是否存在
↓
商品是否上架
↓
库存是否足够
↓
数量是否合法16.3 修改数量
PUT /api/cart/items/{item_id}Request：
{
"quantity": 3
}16.4 删除购物车商品
DELETE /api/cart/items/{item_id}16.5 全选/取消选择
可以由前端维护选择状态，也可以由 API 保存。
推荐：
选择状态只作为前端结算状态结算接口提交选中的 item_id。
17. 地址 API
17.1 地址列表
GET /api/account/addresses17.2 地址详情
GET /api/account/addresses/{address_id}17.3 新增地址
POST /api/account/addressesRequest：
{
"receiver": "张三",
"mobile": "13800138000",
"province": "广东省",
"city": "深圳市",
"district": "南山区",
"detail": "科技园 XX 路 XX 号",
"is_default": true
}17.4 修改地址
PUT /api/account/addresses/{address_id}17.5 删除地址
DELETE /api/account/addresses/{address_id}17.6 设置默认地址
POST /api/account/addresses/{address_id}/default服务端事务：
旧默认地址 false
↓
新地址 true18. 订单 API
18.1 订单预览
这是订单创建之前非常重要的接口。
POST /api/order/previewRequest：
{
"items": [
{
"sku_id": 100001,
"quantity": 2
}
],
"address_id": 30001,
"use_points": 1000
}服务端重新计算：
商品
↓
SKU
↓
库存
↓
实时价格
↓
优惠
↓
积分抵扣
↓
运费
↓
最终应付金额Response：
{
"code": 0,
"message": "success",
"data": {
"items": [],
"product_amount": 398,
"discount_amount": 20,
"freight_amount": 0,
"points_discount": 10,
"payable_amount": 368
}
}18.2 创建订单
POST /api/ordersRequest：
{
"items": [
{
"sku_id": 100001,
"quantity": 2
}
],
"address_id": 30001,
"use_points": 1000
}不要从前端接收：
price
subtotal
discount
total
payable_amount这些必须由服务端重新计算。
Response：
{
"code": 0,
"message": "订单创建成功",
"data": {
"order_id": 500001,
"order_no": "202609210001",
"status": "pending_payment",
"payable_amount": 368
}
}18.3 订单列表
GET /api/orders参数：
status
page
page_size状态：
all
pending_payment
pending_shipment
shipped
completed
cancelled
refund18.4 订单详情
GET /api/orders/{order_id}服务端必须验证：
当前用户 == 订单用户否则返回：
403018.5 取消订单
POST /api/orders/{order_id}/cancel服务端检查：
订单状态是否 = pending_payment18.6 确认收货
POST /api/orders/{order_id}/confirm-receipt检查：
订单状态 == shipped19. 支付 API
19.1 获取支付方式
GET /api/orders/{order_id}/payment-methods19.2 创建支付
POST /api/orders/{order_id}/paymentRequest：
{
"method": "wechat"
}Response：
{
"code": 0,
"message": "success",
"data": {
"payment_id": 80001,
"method": "wechat",
"payment_data": {}
}
}支付数据由具体支付平台决定。
19.3 查询支付状态
GET /api/orders/{order_id}/payment-status返回：
{
"code": 0,
"message": "success",
"data": {
"status": "paid",
"paid_at": "2026-09-21T10:40:00+08:00"
}
}19.4 支付回调
支付网关：
POST /api/payment/callback/{provider}回调处理必须：
验签
↓
验证订单
↓
验证金额
↓
验证支付状态
↓
幂等处理
↓
更新订单
↓
写支付流水绝不能仅根据前端：
/payment/success判断用户已经支付。
20. 资产 API
20.1 当前积分
GET /api/asset/pointsResponse：
{
"code": 0,
"message": "success",
"data": {
"available_points": 12580,
"frozen_points": 1000,
"total_points": 13580,
"exchange_rate": {
"points": 100,
"amount": 1
}
}
}20.2 积分流水
GET /api/asset/points/transactions参数：
type
start_date
end_date
page
page_size返回：
{
"code": 0,
"message": "success",
"data": {
"items": [
{
"id": 70001,
"type": "transfer_in",
"amount": 500,
"balance_before": 12080,
"balance_after": 12580,
"reference_id": "TX001",
"created_at": "2026-09-21T10:00:00+08:00"
}
]
}
}21. 积分转账 API
21.1 查询目标用户
GET /api/asset/transfer/recipient?account=13800138000Response：
{
"code": 0,
"message": "success",
"data": {
"user_id": 10002,
"name": "李四",
"mobile": "139****9000"
}
}21.2 创建转账
POST /api/asset/transferRequest：
{
"recipient_user_id": 10002,
"points": 500
}服务端必须验证：
points > 0
↓
不是负数
↓
不是超过余额
↓
目标用户存在
↓
目标用户状态正常
↓
是否允许自己转给自己
↓
是否达到限额21.3 转账确认
推荐增加幂等机制。
例如客户端生成：
Idempotency-Key请求：
POST /api/asset/transfer
Idempotency-Key: 7e6b...防止用户连续点击造成重复转账。
22. 提现 API
22.1 提现资格
GET /api/asset/withdraw/eligibilityResponse：
{
"code": 0,
"message": "success",
"data": {
"can_withdraw": false,
"available_points": 12580,
"real_name_verified": true,
"bank_account_configured": false,
"reason": "请先完善银行卡信息"
}
}22.2 提交提现申请
POST /api/asset/withdrawRequest：
{
"points": 1000
}服务端自行读取：
user_id
实名状态
银行卡
当前余额
提现规则不能由客户端提交银行账号作为最终依据。
22.3 提现记录
GET /api/asset/withdraw/requests?page=1&page_size=2023. 账户资料 API
23.1 获取资料
GET /api/account/profile23.2 修改基础资料
PUT /api/account/profileRequest：
{
"name": "张三",
"wechat": "wx_user",
"avatar": "https://..."
}手机号是否允许直接修改，应单独设计验证流程。
24. 实名资料 API
24.1 获取实名认证状态
GET /api/account/identityResponse：
{
"code": 0,
"message": "success",
"data": {
"status": "verified",
"real_name": "张*",
"id_card": "****************1234"
}
}24.2 提交实名认证
POST /api/account/identity请求字段需要根据实际实名服务确定。
敏感字段必须：
- HTTPS
- 加密传输
- 权限隔离
- 脱敏返回
- 审计
25. 银行账户 API
25.1 获取银行账户
GET /api/account/bank-accounts返回：
{
"code": 0,
"message": "success",
"data": [
{
"id": 50001,
"bank_name": "中国银行",
"card_no": "****1234",
"holder_name": "张*"
}
]
}25.2 新增银行账户
POST /api/account/bank-accountsRequest：
{
"bank_name": "中国银行",
"card_no": "6222xxxxxxxx1234"
}服务端进一步校验实名关系。
26. 收藏 API
26.1 添加收藏
POST /api/account/favoritesRequest：
{
"product_id": 10001
}26.2 取消收藏
DELETE /api/account/favorites/{product_id}26.3 收藏列表
GET /api/account/favorites?page=1&page_size=2027. 关注 API
由于现有系统无法完全确认“关注”的具体对象，新版本建议接口先抽象：
POST /api/account/followsRequest：
{
"target_type": "shop",
"target_id": 10001
}取消：
DELETE /api/account/follows/{target_type}/{target_id}列表：
GET /api/account/follows28. 浏览记录 API
28.1 写入浏览记录
POST /api/account/historyRequest：
{
"product_id": 10001
}后端建议按：
user_id + product_id合并记录。
28.2 浏览记录
GET /api/account/history?page=1&page_size=2028.3 清空
DELETE /api/account/history29. 公告 API
GET /api/member/announcements详情：
GET /api/member/announcements/{id}建议后台配置：
标题
内容
发布时间
是否置顶
开始时间
结束时间
状态30. 客服 API
GET /api/common/service返回：
{
"code": 0,
"message": "success",
"data": {
"phone": "400-xxxx-xxxx",
"wechat": "xxxx",
"online_service_enabled": true,
"service_hours": "09:00-18:00"
}
}31. 系统配置 API
GET /api/common/config可以返回：
{
"code": 0,
"message": "success",
"data": {
"points_to_money_rate": 100,
"default_page_size": 20,
"mall_enabled": true,
"withdraw_enabled": true
}
}敏感配置不能通过该接口返回。
32. 文件上传 API
商品图片、头像等上传：
POST /api/common/upload建议使用：
multipart/form-data返回：
{
"code": 0,
"message": "上传成功",
"data": {
"url": "https://cdn.example.com/xxx.jpg",
"file_id": "file_123"
}
}必须校验：
文件类型
文件大小
扩展名
MIME
图片实际内容
文件名不能仅依赖扩展名判断。
33. 权限 API
前端工作台可能需要知道用户拥有的功能。
GET /api/auth/permissions返回：
{
"code": 0,
"message": "success",
"data": {
"permissions": [
"member.upgrade.apply",
"member.team.view",
"member.upgrade.review",
"asset.transfer",
"asset.withdraw"
]
}
}注意：
这个接口只用于前端显示。
真正的权限检查必须在业务接口内部再次执行。
34. 权限矩阵
| API | 游客 | 普通会员 | 审核会员 | 管理员 |
|---|---|---|---|---|
| 登录 | ✓ | ✓ | ✓ | ✓ |
| 注册 | ✓ | ✓ | ✓ | ✓ |
| 当前用户 | - | ✓ | ✓ | ✓ |
| 会员信息 | - | ✓ | ✓ | ✓ |
| 邀请 | - | ✓ | ✓ | ✓ |
| 申请升级 | - | ✓ | ✓ | ✓ |
| 查看自己的升级记录 | - | ✓ | ✓ | ✓ |
| 查看升级审核 | - | - | ✓ | ✓ |
| 审核升级 | - | - | ✓ | ✓ |
| 查看团队 | - | ✓ | ✓ | ✓ |
| 浏览商城 | 可配置 | ✓ | ✓ | ✓ |
| 创建订单 | - | ✓ | ✓ | ✓ |
| 查看自己的订单 | - | ✓ | ✓ | ✓ |
| 资产 | - | ✓ | ✓ | ✓ |
| 积分转账 | - | ✓ | ✓ | ✓ |
| 提现 | - | ✓ | ✓ | ✓ |
| 后台管理 | - | - | - | ✓ |
35. 关键接口安全规则
以下参数不得作为可信权限依据：
user_id
member_id
level_id
reviewer_id
order_id
request_id
points
price
discount
payable_amount例如：
错误：
POST /api/member/upgrade/apply{
"user_id": 10001,
"target_level": 5
}正确：
POST /api/member/upgrade/apply{
"remark": ""
}服务端：
Session
↓
当前用户
↓
查询会员等级
↓
计算允许升级的目标等级36. 防越权要求
以下接口必须检查资源所有权或业务数据范围：
订单详情
地址详情
升级申请详情
审核详情
积分流水
提现记录
收藏
浏览记录
个人资料例如：
GET /api/orders/500001不能因为知道订单 ID 就可以读取别人的订单。
37. 幂等接口
以下操作必须考虑幂等：
创建订单
支付
积分转账
提现
会员升级审核
确认收货
设置默认地址推荐使用：
Idempotency-Key: UUID或者服务端基于：
业务单号
+ 用户
+ 操作类型建立唯一约束。
38. 订单状态机 API 约束
允许：
pending_payment
↓
paid
↓
pending_shipment
↓
shipped
↓
completed取消：
pending_payment
↓
cancelled不能：
completed → pending_payment任何非法状态转移都返回：
{
"code": 4002,
"message": "当前订单状态不允许执行该操作"
}39. 会员升级状态机
pending
├── approve → approved
└── reject → rejected已处理：
approved → 不允许再次审核
rejected → 不允许再次审核40. 提现状态机
pending
↓
reviewing
├── rejected
│
└── approved
↓
paid所有状态转变写入：
withdrawal_audit_log41. 积分账本规则
积分不是简单修改余额字段。
推荐：
points_account
+
points_transaction每次变动：
读取余额
↓
加锁
↓
检查余额
↓
计算新余额
↓
修改余额
↓
生成流水
↓
COMMIT避免并发导致：
余额变负数
重复扣款
重复转账42. 数据快照规则
订单创建时必须保存：
商品名称
商品图片
SKU 名称
规格
单价
数量
折扣
积分抵扣
运费
最终金额
收货地址即便商品后来：
改名
改价
下架
删除历史订单也不能变化。
43. 敏感数据接口规则
敏感字段包括：
身份证号
银行卡号
真实姓名
手机号
微信号列表接口必须脱敏：
138****8000**** **** **** 1234张*原则：
最小化返回前端页面需要什么，接口只返回什么。
44. 日志规范
禁止写入日志：
密码
完整身份证号
完整银行卡号
Token
Cookie
完整支付敏感参数业务日志保留：
request_id
user_id
operation
resource_id
result
created_at45. API 请求链路
标准业务请求：
Browser
↓
HTTPS
↓
Nginx
↓
Application
↓
Authentication
↓
Authorization
↓
Parameter Validation
↓
Business Logic
↓
Transaction
↓
Database
↓
Audit Log
↓
JSON Response46. 接口文档实现建议
正式开发建议使用 OpenAPI 3.1。
示例：
paths:
/api/member/upgrade/apply:
post:
summary: 提交会员升级申请
security:
- sessionAuth: []
requestBody:
required: true
responses:
"200":
description: success
"401":
description: unauthenticated
"403":
description: forbidden
"422":
description: validation error最终生成：
Swagger UI
Redoc
Postman Collection供前后端联调。
47. 推荐接口目录
正式项目可按照以下目录建立：
docs/api/
├── auth.md
├── member.md
├── upgrade.md
├── team.md
├── catalog.md
├── cart.md
├── address.md
├── order.md
├── payment.md
├── asset.md
├── transfer.md
├── withdraw.md
├── account.md
└── common.md48. 前端页面与接口对应关系
| 页面 | 主要接口 |
|---|---|
| 登录 | POST /api/auth/login |
| 注册 | GET /api/auth/referrer、POST /api/auth/register |
| 工作台 | GET /api/member/dashboard |
| 邀请 | GET /api/member/invite |
| 升级 | GET /api/member/upgrade/eligibility、POST /api/member/upgrade/apply |
| 升级记录 | GET /api/member/upgrade/requests |
| 升级审核 | GET /api/member/upgrade/review/list |
| 审核详情 | GET /api/member/upgrade/review/{id} |
| 审核操作 | POST /api/member/upgrade/review |
| 团队 | GET /api/team/summary、GET /api/team/members |
| 商城首页 | GET /api/catalog/home |
| 分类 | GET /api/catalog/categories |
| 商品列表 | GET /api/catalog/products |
| 商品详情 | GET /api/catalog/products/{id} |
| 购物车 | GET/POST/PUT/DELETE /api/cart/... |
| 地址 | /api/account/addresses/... |
| 确认订单 | POST /api/order/preview |
| 创建订单 | POST /api/orders |
| 订单列表 | GET /api/orders |
| 订单详情 | GET /api/orders/{id} |
| 支付 | POST /api/orders/{id}/payment |
| 资产 | GET /api/asset/points |
| 积分流水 | GET /api/asset/points/transactions |
| 转账 | POST /api/asset/transfer |
| 提现 | GET/POST /api/asset/withdraw/... |
| 个人资料 | GET/PUT /api/account/profile |
| 收藏 | /api/account/favorites/... |
| 浏览记录 | /api/account/history/... |
| 客服 | GET /api/common/service |
49. 第一阶段接口开发顺序
Phase 1：账户和会员
/auth/login
/auth/register
/auth/logout
/auth/me
/member/dashboard
/member/profile
/member/invite
/member/upgrade/eligibility
/member/upgrade/apply
/member/upgrade/requests
/member/upgrade/review/list
/member/upgrade/review/{id}
/member/upgrade/review
/team/summary
/team/membersPhase 2：商城
/catalog/home
/catalog/categories
/catalog/products
/catalog/products/{id}
/cart
/cart/items
/account/addressesPhase 3：交易
/order/preview
/orders
/orders/{id}
/orders/{id}/payment
/payment/callbackPhase 4：资产
/asset/points
/asset/points/transactions
/asset/transfer
/asset/withdrawPhase 5：账户扩展
/account/profile
/account/identity
/account/bank-accounts
/account/favorites
/account/follows
/account/history50. 当前旧接口迁移对应关系
现有接口：
/mob/UCenter/sqsj_ck_save建议迁移：
POST /api/member/upgrade/apply现有接口：
/mob/UCenter/sqsj_ck_update建议迁移：
POST /api/member/upgrade/review旧版：
90 = 同意
30 = 拒绝新版：
approve
reject避免魔法数字。
51. 联调要求
前后端联调前必须确定：
API Base URL
认证方式
统一错误码
分页规范
时间格式
金额精度
积分精度
文件上传方式
接口幂等方案
权限模型52. 金额与积分精度
金额接口不要使用浮点计算。
推荐：
金额：整数分例如：
199.99 元
↓
19999 分积分：
整数数据库：
amount_cent BIGINT
points BIGINT避免：
0.1 + 0.2 != 0.3类似浮点精度问题。
53. API 验收标准
每个接口至少验证：
正常请求
空参数
非法参数
未登录
无权限
资源不存在
资源不属于当前用户
重复请求
并发请求
超限请求
异常状态涉及资金/等级的接口还必须验证：
参数篡改
ID 越权
状态篡改
重复提交
并发操作54. 最终接口架构
最终形成：
API Gateway
│
┌──────────────┼──────────────┐
│ │ │
Auth域 Member域 Mall域
│ │ │
User Upgrade/Team Catalog
│
Cart/Order
│
Asset域
│
Points/Transfer/Withdraw
│
Account域
│
Profile/Address/Favorite这样会员系统和商城可以继续保持业务域独立，同时共享统一用户身份、权限、审计和安全体系。
55. API 开发原则
原则 1：服务端永远是最终权威
前端传递的信息只作为“请求”，不能作为最终业务事实。
原则 2：所有敏感业务必须验证身份 + 权限 + 数据归属
尤其是：
升级
审核
订单
积分
提现
个人资料原则 3：资产类操作必须幂等 + 事务 + 流水
原则 4：订单价格、库存和积分抵扣全部由服务端最终计算
原则 5：接口返回最小化
尤其是：
手机号
微信
身份证
银行卡56. 待后端确认的接口问题
正式开始开发前，需要从现有系统接口抓包或源码中进一步确认：
1. 当前登录接口名称和参数
2. 当前注册接口名称和参数
3. 现有会员等级接口
4. 现有团队接口
5. 现有商品接口
6. 当前购物车接口
7. 当前订单接口
8. 当前支付接口
9. 当前积分接口
10. 当前提现接口
11. 当前地址接口
12. 当前资料接口
13. 是否存在 CSRF Token
14. Session 具体实现
15. 后端权限校验方式
16. 数据库字段与真实 API 参数对应关系这些信息确认后，可以再建立：
旧 API
↓
新 API
↓
字段映射
↓
数据库字段完整迁移表。
这份已经可以作为后端的 V1 接口基线。尤其建议把“现有接口”和“新接口”分开，不要直接照着旧 /mob/UCenter/... 接口继续扩展，否则现有的参数、权限和魔法数字问题会继续带到新版本里。
