foodie-server/specs/022-merchant-store-subaccounts/contracts/api.md

API 契约：商家门店分管账号

所有商家端接口使用 token 请求头；平台接口使用现有若依后台认证和权限注解。业务错误沿用 AjaxResult 与国际化消息。

商家端分管账号接口

基础路径：/merchant/subaccounts

GET /merchant/subaccounts

仅主账号可调用。返回所属分管账号及授权店铺。

{
  "code": 200,
  "data": [
    {
      "userId": 501,
      "name": "张三",
      "phone": "+886900000001",
      "ownerEnabled": true,
      "platformEnabled": true,
      "online": true,
      "lastLoginAt": "2026-08-28T10:30:00",
      "stores": [
        { "storeId": 101, "storeName": "店铺 A" },
        { "storeId": 102, "storeName": "店铺 B" }
      ]
    }
  ]
}

POST /merchant/subaccounts

仅主账号可调用。

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

规则：手机号和登录名使用规范化后的同一手机号；手机号全局唯一；storeIds 非空且全部属于当前主账号；账号创建和授权写入同一事务；不创建钱包。

PUT /merchant/subaccounts/{subaccountUserId}

仅所属主账号可调用，用于修改姓名和授权店铺。

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

PUT /merchant/subaccounts/{subaccountUserId}/password

仅所属主账号可调用。

{ "password": "前端RSA加密值" }

成功后撤销该分管账号现有商家 App/PC 会话，要求重新登录。

PUT /merchant/subaccounts/{subaccountUserId}/status

仅所属主账号可调用，只修改主账号控制状态。

{ "enabled": false }

停用时立即撤销该账号商家 App/PC 会话；启用不能覆盖平台停用状态。

平台端分管账号接口

基础路径：/infouser/merchant-subaccounts

GET /infouser/merchant-subaccounts?merchantUserId={id}

需要 infouser:user:list。merchantUserId 必须对应类型 1 主账号。响应结构与商家端列表一致，不返回密码、CID、Token 或商户敏感资料。

PUT /infouser/merchant-subaccounts/{subaccountUserId}/platform-status

需要 infouser:user:edit。

{ "enabled": false }

只修改平台控制状态。停用时撤销会话；恢复后如果主账号控制状态仍为停用，账号仍不可用。

平台不提供新增、密码重置或店铺授权修改接口。

登录与退出

POST /infouser/user/shanglodeing

现有接口扩展：允许 user_type=5。签发 Token 前校验平台状态、主账号控制状态和所属主账号状态；成功后更新 CID 与 lastLoginAt。类型 5 不执行商家资料审核或钱包逻辑。

POST /infouser/user/merchantLogout

请求头：token。删除当前 JWT 对应 Redis 会话。前端在清除本地 token 前调用；删除失败不返回 Token 内容。

店铺权限契约

以下有效商家端能力必须统一使用登录身份和实际门店归属校验：

能力	主账号	分管账号
店铺列表	全部自有店铺	全部授权店铺
店铺详情、基础资料、营业状态、营业时间	自有店铺	授权店铺
新增、删除店铺	允许	拒绝
商品、分类、规格查询与维护	自有店铺	授权店铺
订单列表、详情、商家状态操作、退款	自有店铺	授权店铺
分管账号管理	允许	拒绝
收款配置、提现、结算、跨店财务	允许	拒绝

所有写接口不得使用请求体中的 userId、shId 作为授权依据；订单、商品等先按 ID 查询实际 mdId 再校验。

通知路由契约

内部服务接口：

void sendStoreNotification(
    Long storeId,
    Long ownerUserId,
    String titleKey,
    String contentKey,
    String body,
    String orderNo
);

返回值不影响原订单事务。每个选中账号先生成自己的 push_message，再尝试外部推送；单个账号失败只记录日志。店铺无法解析时只向 ownerUserId 兜底。

2026-11-04 业务接口授权补齐

以下管理请求均须带 token 请求头，参数主体和响应字段沿用原接口。所有门店必须在登录账号实时授权范围内，账号或主账号停用、权限被撤销立即拒绝。

接口	调整
POST /hours/addHours、POST /hours/setHours、GET /hours/delHours	补充 token；按实际营业时间记录的 mdId 验证权限
/system/shPromotionCoupon、/system/shPromotionActivity 的列表、详情及增删改/结束/下架	所有类型统一校验 storeId，修改先验证旧记录，不能转移门店
/system/shQuanyi、/system/shSalesPromotion 的管理接口	旧字段 shId 在这里指门店 ID，不是商家 ID；创建优惠券时 merchantId 服务端根据门店确定
/system/shPosReview/list、详情、修改、删除	token 认证，按授权门店查询/操作；空授权返回空页
GET /index/getshindex	token 必填，旧 id 可不传；传入也不用于决定商家身份。分管按授权门店统计，ketixian 为 null，不代表可提现余额为零
/Billing/billing/storeBillingList、storeBillingSummary	分管可查询授权门店账单；不传 mdId 为全部授权门店，指定未授权 mdId 拒绝
/Billing/billing/getzddaylist、getzdmeeklist、getzdmatlist	分管使用主账号账单归属和授权门店集合；isCancel 及 cancelCount 使用相同范围

全量维护 GET /hours/setStoreHours 需要平台 system:hours:edit；GET /system/shQuanyi/setMerchatId 需要平台 system:quanyi:edit，商家 token 不可调用。

消费者查询营业时间/预约时间、getorderuzt 查询可用优惠及 getMyquanyi 查询个人权益沿用原用途。批量删除先检查全部记录，任一越权不会删除其他项。无新字段、无数据库迁移；提现和收款设置的既有权限不在本次变更范围内。