收录商家门店分管账号接口文档

docs/merchant-subaccount-api.md

@@ -0,0 +1,501 @@
+# 商家门店管理账号 API 接口文档
+
+> 更新时间：2026-08-31
+> 适用范围：商家端门店分管账号管理、分管账号登录，以及平台端查看和强制启停分管账号。
+> 本文档以当前后端实现为准。
+
+## 1. 公共约定
+
+### 1.1 账号类型
+
+| `userType` | 含义 |
+|---|---|
+| `1` | 商家主账号 |
+| `5` | 商家门店分管账号 |
+
+只有 `userType = 1` 的商家主账号可以新增、编辑、重置密码和启停分管账号。分管账号不能调用账号管理接口。
+
+### 1.2 请求格式
+
+- 商家端接口使用 `Content-Type: application/json`。
+- 除登录接口外，请求头必须携带商家端登录返回的 `token`。
+- `token` 直接放在请求头中，不添加 `Bearer` 前缀。
+
+```http
+token: 登录接口返回的 token
+Content-Type: application/json
+```
+
+平台端接口沿用若依后台现有认证方式。
+
+### 1.3 通用响应
+
+成功响应：
+
+```json
+{
+  "code": 200,
+  "msg": "操作成功",
+  "data": {}
+}
+```
+
+没有返回数据的成功响应不包含 `data`：
+
+```json
+{
+  "code": 200,
+  "msg": "操作成功"
+}
+```
+
+业务失败响应：
+
+```json
+{
+  "code": 500,
+  "msg": "具体错误信息"
+}
+```
+
+前端应以响应体中的 `code === 200` 判断业务是否成功，不要只依赖 HTTP 状态码。
+
+### 1.4 分管账号返回对象
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `userId` | `number` | 分管账号用户 ID |
+| `name` | `string` | 姓名 |
+| `phone` | `string` | 登录手机号，同时也是登录账号 |
+| `merchantOwnerId` | `number` | 所属商家主账号用户 ID |
+| `ownerEnabled` | `boolean` | 主账号控制状态，`true` 为启用 |
+| `platformEnabled` | `boolean` | 平台控制状态，`true` 为启用 |
+| `online` | `boolean` | 当前是否存在有效商家端登录会话 |
+| `lastLoginAt` | `string \| null` | 最后登录时间，未登录过时可能为 `null` |
+| `createdAt` | `string \| null` | 创建时间 |
+| `stores` | `array` | 当前负责的门店列表 |
+| `stores[].storeId` | `number` | 门店 ID |
+| `stores[].storeName` | `string` | 门店名称 |
+
+账号实际可用条件：
+
+```text
+ownerEnabled === true && platformEnabled === true
+```
+
+## 2. 商家端接口汇总
+
+基础路径：`/merchant/subaccounts`
+
+| 功能 | 方法 | 地址 | 调用方 |
+|---|---|---|---|
+| 查询分管账号列表 | `GET` | `/merchant/subaccounts` | 商家主账号 |
+| 创建分管账号 | `POST` | `/merchant/subaccounts` | 商家主账号 |
+| 编辑姓名和负责门店 | `PUT` | `/merchant/subaccounts/{subaccountUserId}` | 所属商家主账号 |
+| 重置密码 | `PUT` | `/merchant/subaccounts/{subaccountUserId}/password` | 所属商家主账号 |
+| 启用或停用账号 | `PUT` | `/merchant/subaccounts/{subaccountUserId}/status` | 所属商家主账号 |
+
+## 3. 获取可分配门店
+
+创建或编辑分管账号前，可调用现有“我的门店”接口取得门店选择数据。
+
+### `GET /chanting/store/getmystorelist`
+
+请求头：
+
+```http
+token: 商家主账号 token
+```
+
+请求参数：无。
+
+成功响应示例：
+
+```json
+{
+  "code": 200,
+  "msg": "操作成功",
+  "data": [
+    {
+      "id": 101,
+      "posName": "台北一店"
+    },
+    {
+      "id": 102,
+      "posName": "台北二店"
+    }
+  ]
+}
+```
+
+该接口实际会返回完整门店对象。账号管理页面至少使用以下两个字段：
+
+| 门店字段 | 用途 |
+|---|---|
+| `id` | 提交到账号接口的 `storeIds` |
+| `posName` | 门店名称展示 |
+
+## 4. 查询分管账号列表
+
+### `GET /merchant/subaccounts`
+
+仅商家主账号可调用。接口不分页，返回当前主账号名下全部未删除的分管账号。
+
+请求头：
+
+```http
+token: 商家主账号 token
+```
+
+请求参数：无。
+
+成功响应示例：
+
+```json
+{
+  "code": 200,
+  "msg": "操作成功",
+  "data": [
+    {
+      "userId": 501,
+      "name": "张三",
+      "phone": "+886900000001",
+      "merchantOwnerId": 10001,
+      "ownerEnabled": true,
+      "platformEnabled": true,
+      "online": true,
+      "lastLoginAt": "2026-08-28T10:30:00",
+      "createdAt": "2026-08-20T09:00:00",
+      "stores": [
+        {
+          "storeId": 101,
+          "storeName": "台北一店"
+        },
+        {
+          "storeId": 102,
+          "storeName": "台北二店"
+        }
+      ]
+    }
+  ]
+}
+```
+
+## 5. 创建分管账号
+
+### `POST /merchant/subaccounts`
+
+仅商家主账号可调用。
+
+请求头：
+
+```http
+token: 商家主账号 token
+Content-Type: application/json
+```
+
+请求体：
+
+```json
+{
+  "phone": "+886900000001",
+  "name": "张三",
+  "password": "前端 RSA 加密后的密码",
+  "storeIds": [101, 102]
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `phone` | `string` | 是 | 登录手机号，同时作为登录账号；服务端会移除其中的空白字符；最长 32 个字符；全局不可重复 |
+| `name` | `string` | 是 | 分管账号姓名，不能只包含空白字符 |
+| `password` | `string` | 是 | 使用商家端现有登录密码相同的 RSA 加密方式提交 |
+| `storeIds` | `number[]` | 是 | 至少一个门店 ID；所有门店必须属于当前主账号；重复 ID 会被去重 |
+
+成功响应的 `data` 为完整的分管账号对象：
+
+```json
+{
+  "code": 200,
+  "msg": "操作成功",
+  "data": {
+    "userId": 501,
+    "name": "张三",
+    "phone": "+886900000001",
+    "merchantOwnerId": 10001,
+    "ownerEnabled": true,
+    "platformEnabled": true,
+    "online": false,
+    "lastLoginAt": null,
+    "createdAt": "2026-08-31T11:00:00",
+    "stores": [
+      {
+        "storeId": 101,
+        "storeName": "台北一店"
+      },
+      {
+        "storeId": 102,
+        "storeName": "台北二店"
+      }
+    ]
+  }
+}
+```
+
+## 6. 编辑姓名和负责门店
+
+### `PUT /merchant/subaccounts/{subaccountUserId}`
+
+只能修改当前主账号所属的分管账号。
+
+路径参数：
+
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `subaccountUserId` | `number` | 是 | 分管账号的 `userId` |
+
+请求体：
+
+```json
+{
+  "name": "张三",
+  "storeIds": [102, 103]
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `name` | `string` | 是 | 修改后的姓名 |
+| `storeIds` | `number[]` | 是 | 修改后的完整门店 ID 集合，至少一个；不是增量添加 |
+
+成功响应的 `data` 为修改后的完整分管账号对象。
+
+注意：当前接口不支持修改手机号。`storeIds` 会整体覆盖原门店授权，提交前必须传入希望保留的全部门店 ID。
+
+## 7. 重置密码
+
+### `PUT /merchant/subaccounts/{subaccountUserId}/password`
+
+只能重置当前主账号所属分管账号的密码。
+
+请求体：
+
+```json
+{
+  "password": "前端 RSA 加密后的新密码"
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `password` | `string` | 是 | 使用商家端现有登录密码相同的 RSA 加密方式提交 |
+
+成功响应：
+
+```json
+{
+  "code": 200,
+  "msg": "操作成功"
+}
+```
+
+密码重置成功后，后端会立即撤销该分管账号已有的 App 和 PC 会话，账号需要使用新密码重新登录。
+
+## 8. 启用或停用账号
+
+### `PUT /merchant/subaccounts/{subaccountUserId}/status`
+
+该接口只修改主账号控制状态，即返回对象中的 `ownerEnabled`。
+
+请求体：
+
+```json
+{
+  "enabled": false
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `enabled` | `boolean` | 是 | `true` 启用，`false` 停用 |
+
+成功响应：
+
+```json
+{
+  "code": 200,
+  "msg": "操作成功"
+}
+```
+
+- 停用后，后端会立即撤销该分管账号已有的 App 和 PC 会话。
+- 主账号重新启用账号时，只能把 `ownerEnabled` 改为 `true`，不能覆盖平台的 `platformEnabled` 状态。
+- 如果 `platformEnabled === false`，即使主账号已启用，该账号仍然不可登录和使用。
+
+## 9. 分管账号登录
+
+分管账号复用现有商家登录接口，不使用单独的登录地址。
+
+### `POST /infouser/user/shanglodeing`
+
+该接口不需要 `token`。
+
+请求体示例：
+
+```json
+{
+  "userName": "+886900000001",
+  "password": "前端 RSA 加密后的密码",
+  "cid": "推送客户端标识",
+  "cidType": "ios",
+  "deviceToken": "设备推送 token",
+  "voIPToken": "iOS VoIP token"
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `userName` | `string` | 是 | 创建分管账号时提交的手机号 |
+| `password` | `string` | 是 | RSA 加密后的密码 |
+| `cid` | `string` | 否 | 当前商家端使用的推送客户端标识 |
+| `cidType` | `string` | 否 | 设备类型，例如 `ios`、`android` |
+| `deviceToken` | `string` | 否 | 普通设备推送 token |
+| `voIPToken` | `string` | 否 | iOS VoIP 推送 token |
+
+分管账号登录成功响应示例：
+
+```json
+{
+  "code": 200,
+  "msg": "登录成功",
+  "token": "登录 token",
+  "data": {
+    "userId": 501,
+    "userName": "+886900000001",
+    "nickName": "张三",
+    "userType": "5",
+    "storeId": null,
+    "merchantOwnerId": 10001,
+    "status": "0",
+    "subaccountStatus": "0",
+    "lastLoginAt": "2026-08-31T11:30:00"
+  }
+}
+```
+
+前端可使用 `data.userType === "5"` 识别分管账号。分管账号只能访问其被授权的门店；门店权限由后端校验，前端不能通过修改门店 ID 扩大权限。
+
+登录时以下任一情况都会失败：
+
+- 分管账号被主账号停用；
+- 分管账号被平台停用；
+- 所属商家主账号不可用；
+- 账号或密码错误。
+
+## 10. 退出登录
+
+### `POST /infouser/user/merchantLogout`
+
+请求头：
+
+```http
+token: 当前商家端 token
+```
+
+请求体：无。
+
+成功响应：
+
+```json
+{
+  "code": 200,
+  "msg": "操作成功"
+}
+```
+
+前端应先调用退出接口，再清除本地 token。
+
+## 11. 平台端接口
+
+平台端只允许查看分管账号以及强制启用或停用。平台不能新增分管账号、重置密码或修改门店授权。
+
+### 11.1 查询指定商家的分管账号
+
+#### `GET /infouser/merchant-subaccounts?merchantUserId={id}`
+
+权限标识：`infouser:user:list`
+
+查询参数：
+
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `merchantUserId` | `number` | 是 | 商家主账号用户 ID，必须是 `userType = 1` 的有效账号 |
+
+成功响应的 `data` 与商家端“查询分管账号列表”一致。
+
+### 11.2 平台强制启用或停用
+
+#### `PUT /infouser/merchant-subaccounts/{subaccountUserId}/platform-status`
+
+权限标识：`infouser:user:edit`
+
+请求体：
+
+```json
+{
+  "enabled": false
+}
+```
+
+该接口只修改返回对象中的 `platformEnabled`。平台停用账号后会立即撤销该账号已有的 App 和 PC 会话。
+
+成功响应：
+
+```json
+{
+  "code": 200,
+  "msg": "操作成功"
+}
+```
+
+## 12. 常见业务错误
+
+错误消息会根据服务端当前语言返回对应的简体中文、繁体中文、英文或越南语。以下为简体中文示例：
+
+| `msg` 示例 | 触发情况 |
+|---|---|
+| `仅商家主账号可执行此操作` | 分管账号或非商家主账号调用账号管理接口 |
+| `商家主账号不存在` | 平台查询的 `merchantUserId` 不是有效商家主账号 |
+| `请求数据不能为空` | 创建或编辑请求体为空 |
+| `分管账号姓名不能为空` | `name` 为空或只有空白字符 |
+| `分管账号手机号不能为空` | `phone` 为空 |
+| `分管账号手机号格式无效` | 去除空白后的手机号长度超过 32 个字符 |
+| `该手机号已被使用` | 手机号或同名登录账号已存在 |
+| `分管账号密码不能为空` | `password` 为空或只有空白字符 |
+| `请至少选择一个负责店铺` | `storeIds` 为空数组或未提交 |
+| `无权访问该店铺` | `storeIds` 包含不属于当前主账号的门店 |
+| `分管账号状态不能为空` | `enabled` 未提交或为 `null` |
+| `分管账号不存在` | 目标 ID 不是有效分管账号 |
+| `无权管理该分管账号` | 主账号尝试修改其他商家的分管账号 |
+| `商家账号不可用` | 账号被平台停用 |
+| `所属商家主账号不可用` | 分管账号所属主账号不可用 |
+
+## 13. 前端调用顺序
+
+```text
+进入账号管理页
+  -> GET /chanting/store/getmystorelist
+  -> GET /merchant/subaccounts
+
+创建账号
+  -> POST /merchant/subaccounts
+  -> 成功后使用响应 data 更新列表，或重新查询列表
+
+编辑账号
+  -> PUT /merchant/subaccounts/{userId}
+  -> 成功后使用响应 data 更新列表
+
+重置密码或启停账号
+  -> 调用对应 PUT 接口
+  -> 成功后重新查询列表，刷新 online 和状态字段
+```