foodie-server/docs/merchant-subaccount-api.md

商家门店管理账号 API 接口文档

更新时间：2026-08-31 适用范围：商家端门店分管账号管理、分管账号登录，以及平台端查看和强制启停分管账号。 本文档以当前后端实现为准。

1. 公共约定

1.1 账号类型

userType	含义
1	商家主账号
5	商家门店分管账号

只有 userType = 1 的商家主账号可以新增、编辑、重置密码和启停分管账号。分管账号不能调用账号管理接口。

1.2 请求格式

• 商家端接口使用 Content-Type: application/json。
• 除登录接口外，请求头必须携带商家端登录返回的 token。

• token 直接放在请求头中，不添加 Bearer 前缀。

  token: 登录接口返回的 token
  Content-Type: application/json
  

平台端接口沿用若依后台现有认证方式。

1.3 通用响应

成功响应：

{
  "code": 200,
  "msg": "操作成功",
  "data": {}
}

没有返回数据的成功响应不包含 data：

{
  "code": 200,
  "msg": "操作成功"
}

业务失败响应：

{
  "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	门店名称

账号实际可用条件：

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

请求头：

token: 商家主账号 token

请求参数：无。

成功响应示例：

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "id": 101,
      "posName": "台北一店"
    },
    {
      "id": 102,
      "posName": "台北二店"
    }
  ]
}

该接口实际会返回完整门店对象。账号管理页面至少使用以下两个字段：

门店字段	用途
id	提交到账号接口的 storeIds
posName	门店名称展示

4. 查询分管账号列表

GET /merchant/subaccounts

仅商家主账号可调用。接口不分页，返回当前主账号名下全部未删除的分管账号。

请求头：

token: 商家主账号 token

请求参数：无。

成功响应示例：

{
  "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

仅商家主账号可调用。

请求头：

token: 商家主账号 token
Content-Type: application/json

请求体：

{
  "phone": "+886900000001",
  "name": "张三",
  "password": "前端 RSA 加密后的密码",
  "storeIds": [101, 102]
}

字段	类型	必填	说明
phone	string	是	登录手机号，同时作为登录账号；服务端会移除其中的空白字符；最长 32 个字符；全局不可重复
name	string	是	分管账号姓名，不能只包含空白字符
password	string	是	使用商家端现有登录密码相同的 RSA 加密方式提交
storeIds	number[]	是	至少一个门店 ID；所有门店必须属于当前主账号；重复 ID 会被去重

成功响应的 data 为完整的分管账号对象：

{
  "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

请求体：

{
  "name": "张三",
  "storeIds": [102, 103]
}

字段	类型	必填	说明
name	string	是	修改后的姓名
storeIds	number[]	是	修改后的完整门店 ID 集合，至少一个；不是增量添加

成功响应的 data 为修改后的完整分管账号对象。

注意：当前接口不支持修改手机号。storeIds 会整体覆盖原门店授权，提交前必须传入希望保留的全部门店 ID。

7. 重置密码

PUT /merchant/subaccounts/{subaccountUserId}/password

只能重置当前主账号所属分管账号的密码。

请求体：

{
  "password": "前端 RSA 加密后的新密码"
}

字段	类型	必填	说明
password	string	是	使用商家端现有登录密码相同的 RSA 加密方式提交

成功响应：

{
  "code": 200,
  "msg": "操作成功"
}

密码重置成功后，后端会立即撤销该分管账号已有的 App 和 PC 会话，账号需要使用新密码重新登录。

8. 启用或停用账号

PUT /merchant/subaccounts/{subaccountUserId}/status

该接口只修改主账号控制状态，即返回对象中的 ownerEnabled。

请求体：

{
  "enabled": false
}

字段	类型	必填	说明
enabled	boolean	是	true 启用，false 停用

成功响应：

{
  "code": 200,
  "msg": "操作成功"
}

• 停用后，后端会立即撤销该分管账号已有的 App 和 PC 会话。
• 主账号重新启用账号时，只能把 ownerEnabled 改为 true，不能覆盖平台的 platformEnabled 状态。
• 如果 platformEnabled === false，即使主账号已启用，该账号仍然不可登录和使用。

9. 分管账号登录

分管账号复用现有商家登录接口，不使用单独的登录地址。

POST /infouser/user/shanglodeing

该接口不需要 token。

请求体示例：

{
  "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

分管账号登录成功响应示例：

{
  "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

请求头：

token: 当前商家端 token

请求体：无。

成功响应：

{
  "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

请求体：

{
  "enabled": false
}

该接口只修改返回对象中的 platformEnabled。平台停用账号后会立即撤销该账号已有的 App 和 PC 会话。

成功响应：

{
  "code": 200,
  "msg": "操作成功"
}

12. 常见业务错误

错误消息会根据服务端当前语言返回对应的简体中文、繁体中文、英文或越南语。以下为简体中文示例：

msg 示例	触发情况
仅商家主账号可执行此操作	分管账号或非商家主账号调用账号管理接口
商家主账号不存在	平台查询的 merchantUserId 不是有效商家主账号
请求数据不能为空	创建或编辑请求体为空
分管账号姓名不能为空	name 为空或只有空白字符
分管账号手机号不能为空	phone 为空
分管账号手机号格式无效	去除空白后的手机号长度超过 32 个字符
该手机号已被使用	手机号或同名登录账号已存在
分管账号密码不能为空	password 为空或只有空白字符
请至少选择一个负责店铺	storeIds 为空数组或未提交
无权访问该店铺	storeIds 包含不属于当前主账号的门店
分管账号状态不能为空	enabled 未提交或为 null
分管账号不存在	目标 ID 不是有效分管账号
无权管理该分管账号	主账号尝试修改其他商家的分管账号
商家账号不可用	账号被平台停用
所属商家主账号不可用	分管账号所属主账号不可用

13. 前端调用顺序

进入账号管理页
  -> GET /chanting/store/getmystorelist
  -> GET /merchant/subaccounts

创建账号
  -> POST /merchant/subaccounts
  -> 成功后使用响应 data 更新列表，或重新查询列表

编辑账号
  -> PUT /merchant/subaccounts/{userId}
  -> 成功后使用响应 data 更新列表

重置密码或启停账号
  -> 调用对应 PUT 接口
  -> 成功后重新查询列表，刷新 online 和状态字段