173 lines
6.7 KiB
Markdown
173 lines
6.7 KiB
Markdown
# 小程序端修改文档（门店端）
|
||
|
||
> 版本：2026-08-17
|
||
> 后端变更：用户表与门店表合并（一个用户就是一个门店），门店登录由「微信静默登录」改为「账号 + 密码登录」。
|
||
> 本文档面向小程序（门店端）开发者，说明需要配合修改的内容。**未列出的接口均无变化**。
|
||
|
||
---
|
||
|
||
## 一、变更总览
|
||
|
||
| 事项 | 旧 | 新 |
|
||
|------|-----|-----|
|
||
| 登录方式 | `wx.login` 拿 code，调 `/mini/auth/login` 静默登录 | 账号 + 密码登录（账号由商家后台分配） |
|
||
| 注册 | `POST /mini/auth/register`（微信 code + 手机号 + 门店编码） | **接口下线**，门店账号由商家在 PC 后台创建 |
|
||
| 登录主体 | 微信用户（user），再绑定门店（store） | **门店即用户**：登录成功返回的就是门店本身 |
|
||
| 修改密码 | 无 | 新增 `PUT /mini/auth/password` |
|
||
| Token 鉴权 | Bearer Token | **不变** |
|
||
| 其他业务接口 | 购物车 / 订单 / 账单 / 支付 / 通知 / 商品 / 首页 | **全部不变**（路径、入参、出参） |
|
||
|
||
### 需要小程序端配合的改动
|
||
|
||
1. **重做登录页**：去掉 `wx.login` 流程，改为账号 + 密码表单（账号密码由商家线下告知门店）。
|
||
2. **删除注册页/绑定门店页**：注册接口已下线，「尚未绑定门店」的场景已不存在。
|
||
3. **用户信息结构调整**：登录与 `auth/info` 返回的对象字段变化（见下文）。
|
||
4. **新增「修改密码」入口**（建议放在「我的」页面）。
|
||
5. **重新登录**：旧 token 全部失效，需引导用户用账号密码重新登录一次。
|
||
|
||
---
|
||
|
||
## 二、登录接口（变更）
|
||
|
||
### `POST /mini/auth/login`
|
||
|
||
**请求参数（变更）：**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| username | string | 是 | 登录账号（商家后台分配，4~20 位） |
|
||
| password | string | 是 | 登录密码 |
|
||
|
||
> 旧参数 `code`（wx.login 凭证）已废弃，无需再传，也无需调用 `wx.login`。
|
||
|
||
**成功响应：**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"msg": "登录成功",
|
||
"data": {
|
||
"token": "1|xxxxxxxxxxxxxxxx",
|
||
"user": {
|
||
"id": 3,
|
||
"name": "好又多超市",
|
||
"code": "S000003",
|
||
"username": "hyd001",
|
||
"avatar": "",
|
||
"level_id": 1,
|
||
"level": { "id": 1, "name": "一级客户" },
|
||
"contact": "张三",
|
||
"phone": "13800000000",
|
||
"address": "xx路 1 号",
|
||
"payment_cycle_days": 2,
|
||
"status": 1,
|
||
"last_login_at": "2026-08-17 10:00:00",
|
||
"created_at": "2026-08-01 09:00:00"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**user 字段变化要点：**
|
||
|
||
- `user` 现在**就是门店对象**（扁平结构），不再有 `user.store` 嵌套，也不再有 `openid`、`unionid`、`nickname`、`email`、`store_id` 字段。
|
||
- 门店名称取 `user.name`（原 `user.store.name`）；客户等级取 `user.level`。
|
||
- `password` 字段永不返回。
|
||
|
||
**失败响应（`success: false`，`msg` 提示）：**
|
||
|
||
| 场景 | msg |
|
||
|------|-----|
|
||
| 账号不存在或密码错误 | 账号或密码错误 |
|
||
| 门店已停用 | 账号已被停用，请联系客服处理 |
|
||
| 参数缺失 | 请输入登录账号 / 请输入登录密码 |
|
||
|
||
**Token 使用（不变）：** 后续所有请求携带请求头 `Authorization: Bearer {token}`。
|
||
|
||
---
|
||
|
||
## 三、注册接口（下线）
|
||
|
||
### ~~`POST /mini/auth/register`~~ —— 已删除
|
||
|
||
- 门店账号全部由商家在 PC 后台「客户管理 → 门店管理」创建并分配（含登录账号、初始密码）。
|
||
- 小程序端请移除注册页、「输入门店编码绑定」页及相关逻辑。
|
||
- 同步移除 `wx.getPhoneNumber` 手机号授权流程（后端已不再使用）。
|
||
|
||
---
|
||
|
||
## 四、当前用户信息（结构变化）
|
||
|
||
### `GET /mini/auth/info`（需登录）
|
||
|
||
返回当前登录门店完整信息（含 `level` 等级嵌套），字段与登录接口的 `user` 一致（见上文示例）。原来读取 `info.store.xxx` 的地方改为直接读 `info.xxx`。
|
||
|
||
---
|
||
|
||
## 五、修改密码（新增）
|
||
|
||
### `PUT /mini/auth/password`（需登录）
|
||
|
||
**请求参数：**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| oldPassword | string | 是 | 原密码 |
|
||
| newPassword | string | 是 | 新密码（6~20 位） |
|
||
| rePassword | string | 是 | 确认新密码（须与 newPassword 一致） |
|
||
|
||
**失败场景：** 原密码不正确 / 两次输入的密码不一致 / 新密码至少 6 位。
|
||
|
||
> 修改密码成功后现有 token 仍然有效，无需强制重新登录。
|
||
|
||
---
|
||
|
||
## 六、门店信息（不变）
|
||
|
||
### `GET /mini/store/info`（需登录）
|
||
|
||
返回：`{ id, name, code, contact, phone, address, payment_cycle_days }`（门店名称/编码/回款周期只读，由后台维护）。
|
||
|
||
### `PUT /mini/store/info`（需登录）
|
||
|
||
可改字段不变：`contact`（联系人）、`phone`（联系电话）、`address`（地址）。
|
||
|
||
---
|
||
|
||
## 七、以下接口完全不变
|
||
|
||
路径、入参、出参均无变化，仅内部归属从「用户」变为「门店」（对小程序透明）：
|
||
|
||
| 模块 | 接口 |
|
||
|------|------|
|
||
| 首页 | `GET /mini/home/*`（轮播/导航/促销） |
|
||
| 商品 | `GET /mini/product/categories`、`GET /mini/product/list`、`GET /mini/product/{id}`（登录后按本店等级显示价格） |
|
||
| 购物车 | `POST /mini/cart`、`GET /mini/cart`、`PUT /mini/cart/{id}`、`DELETE /mini/cart/{id}`、`DELETE /mini/cart` |
|
||
| 订单 | `POST /mini/order`、`GET /mini/order`、`GET /mini/order/summary`、`GET /mini/order/{id}`、`PUT /mini/order/{id}/cancel` |
|
||
| 账单 | `GET /mini/bill`、`GET /mini/bill/{id}`、`GET /mini/bill/export` |
|
||
| 支付 | `GET /mini/payment/config`、`GET /mini/payment`、`POST /mini/payment`、`GET /mini/payment/{id}` |
|
||
| 通知 | `GET /mini/notice`、`PUT /mini/notice/{id}/read` |
|
||
| 上传 | `POST /mini/upload` |
|
||
|
||
> 唯一语义差异：数据隔离现在天然按门店划分（一个门店一个账号），原「同一门店多个微信账号各自购物车」的合并场景不再存在。
|
||
|
||
---
|
||
|
||
## 八、错误语义（不变）
|
||
|
||
- 未携带/无效 token：HTTP `401`。
|
||
- 业务错误：HTTP `200` + `{ success: false, msg: "..." }`，直接 toast `msg` 即可。
|
||
- 「门店未设置客户等级，无法加购/下单，请联系客服」等提示文案不变。
|
||
- 「尚未绑定门店」提示已移除（该场景不存在）。
|
||
|
||
---
|
||
|
||
## 九、上线 Checklist（小程序端）
|
||
|
||
- [ ] 登录页改为账号 + 密码表单，移除 `wx.login` / `wx.getPhoneNumber` 调用
|
||
- [ ] 移除注册页、门店绑定页及路由
|
||
- [ ] 全局用户信息读取点从 `user.store.*` 调整为 `user.*`（门店名、等级、回款周期等）
|
||
- [ ] 「我的」页面新增修改密码入口
|
||
- [ ] 旧版本缓存的 token 失效处理：401 时引导重新登录
|
||
- [ ] 等级价格展示逻辑不变（接口返回的 `price` 字段含义不变）
|