可以。下面整理成一份可直接交给后端、前端联调和测试使用的 《API 接口文档》。其中 /mob/UCenter/sqsj_ck_save 和 /mob/UCenter/sqsj_ck_update 是目前检查到的现有接口；其余 /api/... 为建议的新版本接口规范。

会员推荐关系 + 新零售商城

API 接口文档

版本： V1.0
接口风格： RESTful JSON API
认证方式： Cookie Session / Token 二选一
数据格式： JSON
字符编码： UTF-8
基础路径：

纯文本复制⌃/api

1. 接口设计总览

API 按业务域拆分：

纯文本复制⌃/api
├── auth
│   ├── 登录
│   ├── 注册
│   ├── 退出
│   └── 当前用户
│
├── member
│   ├── 会员信息
│   ├── 等级
│   ├── 邀请
│   └── 升级
│
├── team
│   └── 团队成员
│
├── catalog
│   ├── 首页
│   ├── 分类
│   ├── 专区
│   ├── 商品
│   └── 搜索
│
├── cart
│   └── 购物车
│
├── address
│   └── 收货地址
│
├── order
│   ├── 订单
│   └── 支付
│
├── asset
│   ├── 积分
│   ├── 流水
│   ├── 转账
│   └── 提现
│
├── account
│   ├── 资料
│   ├── 收藏
│   ├── 关注
│   └── 浏览记录
│
└── common
    ├── 上传
    ├── 配置
    └── 字典

2. 统一请求规范

2.1 HTTP Header

http复制⌃Content-Type: application/json
Accept: application/json

如果使用 Token：

http复制⌃Authorization: Bearer {token}

如果使用 Cookie Session，则无需前端手动传 user_id。

3. 统一响应结构

所有接口统一：

json复制⌃{
  "code": 0,
  "message": "success",
  "data": {}
}

成功：

json复制⌃{
  "code": 0,
  "message": "success",
  "data": {}
}

业务失败：

json复制⌃{
  "code": 4001,
  "message": "当前会员等级不允许升级",
  "data": null
}

系统异常：

json复制⌃{
  "code": 5000,
  "message": "系统繁忙，请稍后重试",
  "data": null
}

4. 统一错误码

5. 分页规范

列表接口统一：

http复制⌃GET /api/team/members?page=1&page_size=20

返回：

json复制⌃{
  "code": 0,
  "message": "success",
  "data": {
    "items": [],
    "page": 1,
    "page_size": 20,
    "total": 100,
    "has_more": true
  }
}

最大：

纯文本复制⌃page_size <= 100

6. 日期时间规范

统一使用：

纯文本复制⌃ISO 8601

例如：

纯文本复制⌃2026-09-21T10:30:00+08:00

数据库可使用 UTC 存储，前端根据用户时区展示。

7. 用户认证 API

7.1 登录

http复制⌃POST /api/auth/login

Request：

json复制⌃{
  "mobile": "13800138000",
  "password": "********"
}

Response：

json复制⌃{
  "code": 0,
  "message": "登录成功",
  "data": {
    "user": {
      "id": 10001,
      "mobile": "13800138000",
      "name": "张三",
      "avatar": ""
    }
  }
}

如果使用 Token：

json复制⌃{
  "code": 0,
  "message": "登录成功",
  "data": {
    "token": "xxx",
    "expires_in": 7200,
    "user": {}
  }
}

服务端处理

纯文本复制⌃账号存在
↓
账号状态正常
↓
校验密码
↓
记录登录日志
↓
创建 Session/Token
↓
返回用户信息

安全要求

必须：

• 限制连续失败次数
• 登录接口限流
• 密码不得记录日志
• HTTPS
• Session 安全配置

7.2 获取当前用户

http复制⌃GET /api/auth/me

Response：

json复制⌃{
  "code": 0,
  "message": "success",
  "data": {
    "id": 10001,
    "mobile": "138****8000",
    "name": "张三",
    "avatar": "",
    "member": {
      "level_id": 1,
      "level_name": "一星会员"
    }
  }
}

7.3 退出登录

http复制⌃POST /api/auth/logout

Response：

json复制⌃{
  "code": 0,
  "message": "退出成功",
  "data": null
}

8. 注册 API

8.1 获取推荐人

http复制⌃GET /api/auth/referrer?tid=10001

Response：

json复制⌃{
  "code": 0,
  "message": "success",
  "data": {
    "id": 10001,
    "name": "张三",
    "level_name": "一星会员"
  }
}

服务端只能返回必要信息，不返回完整手机号等敏感字段。

8.2 注册

http复制⌃POST /api/auth/register

Request：

json复制⌃{
  "mobile": "13900139000",
  "wechat": "wx_user",
  "name": "李四",
  "password": "********",
  "password_confirm": "********",
  "referrer_id": 10001
}

服务端处理

纯文本复制⌃校验手机号
↓
检查手机号是否已注册
↓
校验密码
↓
校验 referrer_id
↓
确认推荐人有效
↓
创建用户
↓
创建会员
↓
建立推荐关系
↓
提交事务

注意

不允许：

json复制⌃{
  "user_id": 10002,
  "level_id": 5
}

由客户端直接指定自己创建后的会员等级。

会员等级应由服务端决定。

9. 会员 API

9.1 获取会员信息

http复制⌃GET /api/member/profile

Response：

json复制⌃{
  "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 获取会员工作台

http复制⌃GET /api/member/dashboard

Response：

json复制⌃{
  "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 获取邀请信息

http复制⌃GET /api/member/invite

Response：

json复制⌃{
  "code": 0,
  "message": "success",
  "data": {
    "invite_code": "ABC123",
    "invite_url": "https://example.com/register?tid=10001"
  }
}

二维码可以由：

• 服务端生成
• 前端根据 invite_url 生成

二选一。

11. 会员升级 API

11.1 获取升级资格

http复制⌃GET /api/member/upgrade/eligibility

Response：

json复制⌃{
  "code": 0,
  "message": "success",
  "data": {
    "current_level": {
      "id": 1,
      "name": "一星会员"
    },
    "next_level": {
      "id": 2,
      "name": "二星会员"
    },
    "can_apply": true,
    "reason": ""
  }
}

不能申请：

json复制⌃{
  "code": 0,
  "message": "success",
  "data": {
    "can_apply": false,
    "reason": "已有待审核申请"
  }
}

11.2 提交升级申请

现有接口

当前前端检查到：

http复制⌃POST /mob/UCenter/sqsj_ck_save

其请求结构和权限机制需要后端进一步确认。

新版推荐接口

http复制⌃POST /api/member/upgrade/apply

Request：

json复制⌃{
  "remark": ""
}

不需要客户端提交：

纯文本复制⌃user_id
current_level
target_level

服务端自行读取。

服务端处理

纯文本复制⌃当前用户
↓
读取当前等级
↓
查询下一等级
↓
检查升级条件
↓
检查是否存在待审核记录
↓
创建 upgrade_request
↓
返回申请记录

Response：

json复制⌃{
  "code": 0,
  "message": "申请已提交",
  "data": {
    "request_id": 90001,
    "status": "pending",
    "from_level": "一星会员",
    "to_level": "二星会员",
    "created_at": "2026-09-21T10:30:00+08:00"
  }
}

11.3 升级记录

http复制⌃GET /api/member/upgrade/requests?page=1&page_size=20

Response：

json复制⌃{
  "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 待审核列表

http复制⌃GET /api/member/upgrade/review/list?page=1&page_size=20

服务端必须根据当前登录用户自动过滤其有权审核的申请。

禁止：

http复制⌃GET /api/member/upgrade/review/list?user_id=xxx

然后直接返回全部数据。

12.2 审核详情

http复制⌃GET /api/member/upgrade/review/{request_id}

Response：

json复制⌃{
  "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 审核申请

现有接口

当前前端检查到：

http复制⌃POST /mob/UCenter/sqsj_ck_update

当前动作码：

纯文本复制⌃90 = 同意
30 = 拒绝

新版推荐

http复制⌃POST /api/member/upgrade/review

Request：

json复制⌃{
  "request_id": 90001,
  "action": "approve",
  "remark": ""
}

或者：

json复制⌃{
  "request_id": 90001,
  "action": "reject",
  "remark": "暂不符合升级条件"
}

approve 业务流程

纯文本复制⌃检查 request_id
↓
检查状态 = pending
↓
检查审核人权限
↓
检查申请人属于审核范围
↓
再次校验升级条件
↓
更新会员等级
↓
更新申请状态
↓
写审核日志
↓
事务提交

reject

纯文本复制⌃检查权限
↓
检查状态
↓
记录拒绝原因
↓
更新申请状态
↓
写日志

13. 团队 API

13.1 团队概览

http复制⌃GET /api/team/summary

Response：

json复制⌃{
  "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 团队成员

http复制⌃GET /api/team/members?page=1&page_size=20

Response：

json复制⌃{
  "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 商城首页

http复制⌃GET /api/catalog/home

Response：

json复制⌃{
  "code": 0,
  "message": "success",
  "data": {
    "banners": [],
    "categories": [],
    "zones": [],
    "recommended_products": []
  }
}

14.2 分类列表

http复制⌃GET /api/catalog/categories

Response：

json复制⌃{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": 1,
      "name": "食品",
      "children": []
    }
  ]
}

14.3 商品列表

http复制⌃GET /api/catalog/products

参数：

纯文本复制⌃category_id
zone_id
keyword
sort
page
page_size

示例：

http复制⌃GET /api/catalog/products?category_id=1&sort=latest&page=1&page_size=20

14.4 商品详情

http复制⌃GET /api/catalog/products/{product_id}

Response：

json复制⌃{
  "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

商品有规格时：

http复制⌃GET /api/catalog/products/{product_id}/skus

返回：

json复制⌃{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": 100001,
      "sku_code": "SKU001",
      "name": "红色",
      "price": 199,
      "stock": 20
    }
  ]
}

16. 购物车 API

16.1 查询购物车

http复制⌃GET /api/cart

16.2 加入购物车

http复制⌃POST /api/cart/items

Request：

json复制⌃{
  "sku_id": 100001,
  "quantity": 1
}

服务端重新检查：

纯文本复制⌃SKU 是否存在
↓
商品是否上架
↓
库存是否足够
↓
数量是否合法

16.3 修改数量

http复制⌃PUT /api/cart/items/{item_id}

Request：

json复制⌃{
  "quantity": 3
}

16.4 删除购物车商品

http复制⌃DELETE /api/cart/items/{item_id}

16.5 全选/取消选择

可以由前端维护选择状态，也可以由 API 保存。

推荐：

纯文本复制⌃选择状态只作为前端结算状态

结算接口提交选中的 item_id。

17. 地址 API

17.1 地址列表

http复制⌃GET /api/account/addresses

17.2 地址详情

http复制⌃GET /api/account/addresses/{address_id}

17.3 新增地址

http复制⌃POST /api/account/addresses

Request：

json复制⌃{
  "receiver": "张三",
  "mobile": "13800138000",
  "province": "广东省",
  "city": "深圳市",
  "district": "南山区",
  "detail": "科技园 XX 路 XX 号",
  "is_default": true
}

17.4 修改地址

http复制⌃PUT /api/account/addresses/{address_id}

17.5 删除地址

http复制⌃DELETE /api/account/addresses/{address_id}

17.6 设置默认地址

http复制⌃POST /api/account/addresses/{address_id}/default

服务端事务：

纯文本复制⌃旧默认地址 false
↓
新地址 true

18. 订单 API

18.1 订单预览

这是订单创建之前非常重要的接口。

http复制⌃POST /api/order/preview

Request：

json复制⌃{
  "items": [
    {
      "sku_id": 100001,
      "quantity": 2
    }
  ],
  "address_id": 30001,
  "use_points": 1000
}

服务端重新计算：

纯文本复制⌃商品
↓
SKU
↓
库存
↓
实时价格
↓
优惠
↓
积分抵扣
↓
运费
↓
最终应付金额

Response：

json复制⌃{
  "code": 0,
  "message": "success",
  "data": {
    "items": [],
    "product_amount": 398,
    "discount_amount": 20,
    "freight_amount": 0,
    "points_discount": 10,
    "payable_amount": 368
  }
}

18.2 创建订单

http复制⌃POST /api/orders

Request：

json复制⌃{
  "items": [
    {
      "sku_id": 100001,
      "quantity": 2
    }
  ],
  "address_id": 30001,
  "use_points": 1000
}

不要从前端接收：

纯文本复制⌃price
subtotal
discount
total
payable_amount

这些必须由服务端重新计算。

Response：

json复制⌃{
  "code": 0,
  "message": "订单创建成功",
  "data": {
    "order_id": 500001,
    "order_no": "202609210001",
    "status": "pending_payment",
    "payable_amount": 368
  }
}

18.3 订单列表

http复制⌃GET /api/orders

参数：

纯文本复制⌃status
page
page_size

状态：

纯文本复制⌃all
pending_payment
pending_shipment
shipped
completed
cancelled
refund

18.4 订单详情

http复制⌃GET /api/orders/{order_id}

服务端必须验证：

纯文本复制⌃当前用户 == 订单用户

否则返回：

纯文本复制⌃4030

18.5 取消订单

http复制⌃POST /api/orders/{order_id}/cancel

服务端检查：

纯文本复制⌃订单状态是否 = pending_payment

18.6 确认收货

http复制⌃POST /api/orders/{order_id}/confirm-receipt

检查：

纯文本复制⌃订单状态 == shipped

19. 支付 API

19.1 获取支付方式

http复制⌃GET /api/orders/{order_id}/payment-methods

19.2 创建支付

http复制⌃POST /api/orders/{order_id}/payment

Request：

json复制⌃{
  "method": "wechat"
}

Response：

json复制⌃{
  "code": 0,
  "message": "success",
  "data": {
    "payment_id": 80001,
    "method": "wechat",
    "payment_data": {}
  }
}

支付数据由具体支付平台决定。

19.3 查询支付状态

http复制⌃GET /api/orders/{order_id}/payment-status

返回：

json复制⌃{
  "code": 0,
  "message": "success",
  "data": {
    "status": "paid",
    "paid_at": "2026-09-21T10:40:00+08:00"
  }
}

19.4 支付回调

支付网关：

http复制⌃POST /api/payment/callback/{provider}

回调处理必须：

纯文本复制⌃验签
↓
验证订单
↓
验证金额
↓
验证支付状态
↓
幂等处理
↓
更新订单
↓
写支付流水

绝不能仅根据前端：

纯文本复制⌃/payment/success

判断用户已经支付。

20. 资产 API

20.1 当前积分

http复制⌃GET /api/asset/points

Response：

json复制⌃{
  "code": 0,
  "message": "success",
  "data": {
    "available_points": 12580,
    "frozen_points": 1000,
    "total_points": 13580,
    "exchange_rate": {
      "points": 100,
      "amount": 1
    }
  }
}

20.2 积分流水

http复制⌃GET /api/asset/points/transactions

参数：

纯文本复制⌃type
start_date
end_date
page
page_size

返回：

json复制⌃{
  "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 查询目标用户

http复制⌃GET /api/asset/transfer/recipient?account=13800138000

Response：

json复制⌃{
  "code": 0,
  "message": "success",
  "data": {
    "user_id": 10002,
    "name": "李四",
    "mobile": "139****9000"
  }
}

21.2 创建转账

http复制⌃POST /api/asset/transfer

Request：

json复制⌃{
  "recipient_user_id": 10002,
  "points": 500
}

服务端必须验证：

纯文本复制⌃points > 0
↓
不是负数
↓
不是超过余额
↓
目标用户存在
↓
目标用户状态正常
↓
是否允许自己转给自己
↓
是否达到限额

21.3 转账确认

推荐增加幂等机制。

例如客户端生成：

纯文本复制⌃Idempotency-Key

请求：

http复制⌃POST /api/asset/transfer
Idempotency-Key: 7e6b...

防止用户连续点击造成重复转账。

22. 提现 API

22.1 提现资格

http复制⌃GET /api/asset/withdraw/eligibility

Response：

json复制⌃{
  "code": 0,
  "message": "success",
  "data": {
    "can_withdraw": false,
    "available_points": 12580,
    "real_name_verified": true,
    "bank_account_configured": false,
    "reason": "请先完善银行卡信息"
  }
}

22.2 提交提现申请

http复制⌃POST /api/asset/withdraw

Request：

json复制⌃{
  "points": 1000
}

服务端自行读取：

纯文本复制⌃user_id
实名状态
银行卡
当前余额
提现规则

不能由客户端提交银行账号作为最终依据。

22.3 提现记录

http复制⌃GET /api/asset/withdraw/requests?page=1&page_size=20

23. 账户资料 API

23.1 获取资料

http复制⌃GET /api/account/profile

23.2 修改基础资料

http复制⌃PUT /api/account/profile

Request：

json复制⌃{
  "name": "张三",
  "wechat": "wx_user",
  "avatar": "https://..."
}

手机号是否允许直接修改，应单独设计验证流程。

24. 实名资料 API

24.1 获取实名认证状态

http复制⌃GET /api/account/identity

Response：

json复制⌃{
  "code": 0,
  "message": "success",
  "data": {
    "status": "verified",
    "real_name": "张*",
    "id_card": "****************1234"
  }
}

24.2 提交实名认证

http复制⌃POST /api/account/identity

请求字段需要根据实际实名服务确定。

敏感字段必须：

• HTTPS
• 加密传输
• 权限隔离
• 脱敏返回
• 审计

25. 银行账户 API

25.1 获取银行账户

http复制⌃GET /api/account/bank-accounts

返回：

json复制⌃{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": 50001,
      "bank_name": "中国银行",
      "card_no": "****1234",
      "holder_name": "张*"
    }
  ]
}

25.2 新增银行账户

http复制⌃POST /api/account/bank-accounts

Request：

json复制⌃{
  "bank_name": "中国银行",
  "card_no": "6222xxxxxxxx1234"
}

服务端进一步校验实名关系。

26. 收藏 API

26.1 添加收藏

http复制⌃POST /api/account/favorites

Request：

json复制⌃{
  "product_id": 10001
}

26.2 取消收藏

http复制⌃DELETE /api/account/favorites/{product_id}

26.3 收藏列表

http复制⌃GET /api/account/favorites?page=1&page_size=20

27. 关注 API

由于现有系统无法完全确认“关注”的具体对象，新版本建议接口先抽象：

http复制⌃POST /api/account/follows

Request：

json复制⌃{
  "target_type": "shop",
  "target_id": 10001
}

取消：

http复制⌃DELETE /api/account/follows/{target_type}/{target_id}

列表：

http复制⌃GET /api/account/follows

28. 浏览记录 API

28.1 写入浏览记录

http复制⌃POST /api/account/history

Request：

json复制⌃{
  "product_id": 10001
}

后端建议按：

纯文本复制⌃user_id + product_id

合并记录。

28.2 浏览记录

http复制⌃GET /api/account/history?page=1&page_size=20

28.3 清空

http复制⌃DELETE /api/account/history

29. 公告 API

http复制⌃GET /api/member/announcements

详情：

http复制⌃GET /api/member/announcements/{id}

建议后台配置：

纯文本复制⌃标题
内容
发布时间
是否置顶
开始时间
结束时间
状态

30. 客服 API

http复制⌃GET /api/common/service

返回：

json复制⌃{
  "code": 0,
  "message": "success",
  "data": {
    "phone": "400-xxxx-xxxx",
    "wechat": "xxxx",
    "online_service_enabled": true,
    "service_hours": "09:00-18:00"
  }
}

31. 系统配置 API

http复制⌃GET /api/common/config

可以返回：

json复制⌃{
  "code": 0,
  "message": "success",
  "data": {
    "points_to_money_rate": 100,
    "default_page_size": 20,
    "mall_enabled": true,
    "withdraw_enabled": true
  }
}

敏感配置不能通过该接口返回。

32. 文件上传 API

商品图片、头像等上传：

http复制⌃POST /api/common/upload

建议使用：

纯文本复制⌃multipart/form-data

返回：

json复制⌃{
  "code": 0,
  "message": "上传成功",
  "data": {
    "url": "https://cdn.example.com/xxx.jpg",
    "file_id": "file_123"
  }
}

必须校验：

纯文本复制⌃文件类型
文件大小
扩展名
MIME
图片实际内容
文件名

不能仅依赖扩展名判断。

33. 权限 API

前端工作台可能需要知道用户拥有的功能。

http复制⌃GET /api/auth/permissions

返回：

json复制⌃{
  "code": 0,
  "message": "success",
  "data": {
    "permissions": [
      "member.upgrade.apply",
      "member.team.view",
      "member.upgrade.review",
      "asset.transfer",
      "asset.withdraw"
    ]
  }
}

注意：

这个接口只用于前端显示。

真正的权限检查必须在业务接口内部再次执行。

34. 权限矩阵

35. 关键接口安全规则

以下参数不得作为可信权限依据：

纯文本复制⌃user_id
member_id
level_id
reviewer_id
order_id
request_id
points
price
discount
payable_amount

例如：

错误：

http复制⌃POST /api/member/upgrade/apply

json复制⌃{
  "user_id": 10001,
  "target_level": 5
}

正确：

http复制⌃POST /api/member/upgrade/apply

json复制⌃{
  "remark": ""
}

服务端：

纯文本复制⌃Session
↓
当前用户
↓
查询会员等级
↓
计算允许升级的目标等级

36. 防越权要求

以下接口必须检查资源所有权或业务数据范围：

纯文本复制⌃订单详情
地址详情
升级申请详情
审核详情
积分流水
提现记录
收藏
浏览记录
个人资料

例如：

http复制⌃GET /api/orders/500001

不能因为知道订单 ID 就可以读取别人的订单。

37. 幂等接口

以下操作必须考虑幂等：

纯文本复制⌃创建订单
支付
积分转账
提现
会员升级审核
确认收货
设置默认地址

推荐使用：

http复制⌃Idempotency-Key: UUID

或者服务端基于：

纯文本复制⌃业务单号
+ 用户
+ 操作类型

建立唯一约束。

38. 订单状态机 API 约束

允许：

纯文本复制⌃pending_payment
    ↓
paid
    ↓
pending_shipment
    ↓
shipped
    ↓
completed

取消：

纯文本复制⌃pending_payment
    ↓
cancelled

不能：

纯文本复制⌃completed → pending_payment

任何非法状态转移都返回：

json复制⌃{
  "code": 4002,
  "message": "当前订单状态不允许执行该操作"
}

39. 会员升级状态机

纯文本复制⌃pending
   ├── approve → approved
   └── reject  → rejected

已处理：

纯文本复制⌃approved → 不允许再次审核
rejected → 不允许再次审核

40. 提现状态机

纯文本复制⌃pending
   ↓
reviewing
   ├── rejected
   │
   └── approved
          ↓
       paid

所有状态转变写入：

纯文本复制⌃withdrawal_audit_log

41. 积分账本规则

积分不是简单修改余额字段。

推荐：

纯文本复制⌃points_account
+
points_transaction

每次变动：

纯文本复制⌃读取余额
↓
加锁
↓
检查余额
↓
计算新余额
↓
修改余额
↓
生成流水
↓
COMMIT

避免并发导致：

纯文本复制⌃余额变负数
重复扣款
重复转账

42. 数据快照规则

订单创建时必须保存：

纯文本复制⌃商品名称
商品图片
SKU 名称
规格
单价
数量
折扣
积分抵扣
运费
最终金额
收货地址

即便商品后来：

纯文本复制⌃改名
改价
下架
删除

历史订单也不能变化。

43. 敏感数据接口规则

敏感字段包括：

纯文本复制⌃身份证号
银行卡号
真实姓名
手机号
微信号

列表接口必须脱敏：

纯文本复制⌃138****8000

纯文本复制⌃**** **** **** 1234

纯文本复制⌃张*

原则：

纯文本复制⌃最小化返回

前端页面需要什么，接口只返回什么。

44. 日志规范

禁止写入日志：

纯文本复制⌃密码
完整身份证号
完整银行卡号
Token
Cookie
完整支付敏感参数

业务日志保留：

纯文本复制⌃request_id
user_id
operation
resource_id
result
created_at

45. API 请求链路

标准业务请求：

纯文本复制⌃Browser
  ↓
HTTPS
  ↓
Nginx
  ↓
Application
  ↓
Authentication
  ↓
Authorization
  ↓
Parameter Validation
  ↓
Business Logic
  ↓
Transaction
  ↓
Database
  ↓
Audit Log
  ↓
JSON Response

46. 接口文档实现建议

正式开发建议使用 OpenAPI 3.1。

示例：

YAML复制⌃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.md

48. 前端页面与接口对应关系

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/members

Phase 2：商城

纯文本复制⌃/catalog/home
/catalog/categories
/catalog/products
/catalog/products/{id}

/cart
/cart/items

/account/addresses

Phase 3：交易

纯文本复制⌃/order/preview
/orders
/orders/{id}
/orders/{id}/payment
/payment/callback

Phase 4：资产

纯文本复制⌃/asset/points
/asset/points/transactions
/asset/transfer
/asset/withdraw

Phase 5：账户扩展

纯文本复制⌃/account/profile
/account/identity
/account/bank-accounts
/account/favorites
/account/follows
/account/history

50. 当前旧接口迁移对应关系

现有接口：

纯文本复制⌃/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/... 接口继续扩展，否则现有的参数、权限和魔法数字问题会继续带到新版本里。