商户（商家）独立管理后台 — 设计开发规划

本文档聚焦商家自运营后台：商家（亦称"商户"，与代码中 merchant 实体同义）使用独立账号登录后，管理自己名下的门店、供应商、团队、商品、订单、营销与财务对账。

它与《管理后台规划.md》中的平台运营后台（六大平台角色、商家入驻审核、让利配置等）是平行的两套后台：平台后台由平台运营人员使用、看全局；商家后台由商家员工使用、只能看自己。本规划补齐后者，不重复前者。

一、定位与边界

1.1 两套后台对比

维度	平台运营后台	商家自运营后台（本规划）
使用对象	平台运营/财务/物流/数据人员	商家及其员工（店长、运营、财务、客服）
登录入口	`/login`（admin 账号）	`/merchant/login`（merchant_staff 账号）
数据范围	全平台跨商家	仅当前商家（按 `merchant_id` 强制隔离）
核心职责	审核入驻、全局配置、资金结算、对账	管自己的门店/团队/商品/订单/营销/对账
代码前缀	`/api/admin/`、`/api/`	`/api/merchant/*`
鉴权令牌	AdminToken / JWT	MerchantToken（HMAC，独立键 `xshop_merchant_token`）

1.2 术语统一

商家 = 商户：组织根节点，对应 merchant 表。
门店 / 供应商 / 管理团队：均挂在商家之下，对应 merchant_store / supplier(加 merchant_id) / merchant_staff。
平台公共供应商：supplier.merchant_id = 0，由平台维护，商家只读可见、不可改。

1.3 在系统全景中的位置

用户触点层
 ├── C 端小程序 / H5
 └── 商家端后台（本规划）  ← 与下方"平台运营后台"平行
        │  /merchant/*  (MerchantToken, merchant_id 隔离)
基础支撑层
 ├── 平台运营后台  /admin/*  (AdminToken, RBAC 六角色)
 └── 系统配置域 / 接口网关域

二、总体设计原则

原则	说明
商家数据隔离	所有商家侧查询/写入强制 `WHERE merchant_id = 当前商家`，越权返回 `1004 不存在`
独立登录态	商家与平台登录态互相隔离，互不可代登；商家令牌泄露不影响平台
角色内部分权	商家内部按店长/运营/财务/客服划分，数据权限可细化到门店维度
操作可溯	资金、权限类操作强制留痕；商家侧高危操作同样需二次验证
配置即生效	业务参数（如让利率）由平台统配，商家侧只读展示
异常可干预	提供订单异常处理、退款审核等人工补偿入口

三、架构与鉴权设计（阶段0 已落地）

3.1 部署形态：同应用路由隔离

后端在同一 ThinkPHP 应用内新增 route/merchant.php，统一前缀 /merchant：

/merchant/login         公开，发放 MerchantToken
/merchant/auth/info     当前商家+员工信息
/merchant/store/*       门店管理（需登录）
/merchant/supplier/*    供应商管理（需登录）
/merchant/staff/*       管理团队（需登录）

前端 admin-web 新增独立路由区与布局 MerchantLayout，与平台 BasicLayout 平行；通过 router.beforeEach 区分 /merchant/* 与 / 两套守卫。

3.2 鉴权链路

商家员工登录
  └─ Auth.login 校验 merchant_staff 密码(bcrypt)
       └─ MerchantToken::encode({sid, mid, iat, exp})  ← HMAC-SHA256
            └─ 返回 token，前端存 xshop_merchant_token
后续请求
  └─ MerchantAuthMiddleware 校验 Bearer
       ├─ 失败 → 401
       └─ 成功 → 注入 request->merchantInfo {merchant_id, staff_id}
            └─ 各控制器用 $this->merchantId() 取当前商家，强制隔离

密钥/有效期：config('settlement.merchant_token_secret') / merchant_token_ttl（当前 604800 = 7 天）。
与 MemberToken 同源思路（HMAC 无状态），但作用域独立。

3.3 数据隔离模型（核心约束）

铁律：任何商家侧接口，凡涉及 merchant_store / supplier / merchant_staff / 未来 goods(store_id) / order 等，必须 where('merchant_id', $this->merchantId())。
越权访问他人数据 = 查不到 = 返回 1004，绝不能因"查不到"而返回空列表后误判为"无数据"导致横向越权。

已验证：merchant_id=1 与 merchant_id=2 互不可见，越权访问/删除均被 1004 拦截，无 token 返回 401。

3.4 阶段0 已落地代码清单

层	文件	说明
迁移	`backend/database/migrate_merchant_backend.sql`	幂等新增 `merchant_store`/`merchant_staff`，`supplier`/`goods` 加 `merchant_id`/`store_id`
鉴权	`app/common/lib/MerchantToken.php`、`app/middleware/MerchantAuthMiddleware.php`	HMAC 令牌 + 中间件
控制器	`app/controller/merchant/{BaseMerchant,Auth,Store,Supplier,Staff}.php`	登录/门店/供应商/团队
路由	`backend/route/merchant.php`	`/merchant` 前缀，login 公开
配置	`config/settlement.php`（merchant_token_secret/ttl）、`config/middleware.php`	注册中间件
前端	`utils/merchantRequest.js`、`api/merchant.js`、`store/merchantUser.js`	独立 request / API / Pinia
前端	`router/index.js`（`/merchant` 区）、`layouts/MerchantLayout.vue`	路由与布局
前端	`views/merchant/{login,store,supplier,staff}.vue`	登录 + 三张管理页
演示	种子账号 `m1`/`Merchant@123`(merchant_id=1)、`m2`/`Merchant@123`(merchant_id=2)	隔离验证用

四、商家内部角色与权限（规划）

4.1 商家子角色

平台侧已有六角色（SUPER_ADMIN…DATA_VIEWER）。商家侧不复用平台角色，而是在 merchant_staff.role_id 上挂商家内部角色：

角色	定位	可管范围
店长	商家最高权限	全模块可读写，含团队管理、财务对账
运营	日常经营	门店、商品、订单、营销
财务	资金对账	财务对账、提现/结算明细（只读+核对），不可改商品
客服	履约支持	订单查询、售后处理，不可改财务
只读	数据查看	仅看板与报表，无写权限

4.2 权限落地方式

复用平台 admin_role / admin_permission 表（新增商家侧 perm_code 段，如 merchant:goods:edit）。
前端 merchantUser.store 拉取权限集，菜单与按钮按权限渲染（与平台 v-permission 同思路）。
数据权限扩展到门店：merchant_staff 可绑定 store_id 列表，订单/商品查询按"本员工负责门店"过滤（阶段2 细化）。

4.3 商家侧菜单级权限矩阵（规划）

菜单	店长	运营	财务	客服	只读
工作台	●	●	●	●	●
门店管理	●	●	○	○	○
供应商管理	●	●	○	○	○
管理团队	●	○	○	○	○
商品管理	●	●	○	○	○
订单管理	●	●	○	●	○
营销/核销	●	●	○	●	○
数据看板	●	●	●	●	●
财务对账	●	○	●	○	○
消息公告	●	●	○	●	○

● 全部 ○ 部分（按钮级控制）

五、功能模块规划

5.1 规划版菜单树

├── 📊 工作台
│   ├── 经营总览（今日订单/销售额/待办）
│   └── 核心指标卡（门店数/商品数/团队数）
├── 🏪 门店管理            [已落地]
│   ├── 门店列表（增删改、启禁用）
│   └── 门店详情（绑定商品/订单）
├── 🔗 供应商管理          [已落地]
│   ├── 私有供应商（增删改）
│   └── 平台公共供应商（只读）
├── 👥 管理团队            [已落地]
│   ├── 员工列表（增改、重置密码、启禁用）
│   └── 角色与数据权限
├── 📦 商品管理            [已落地]
│   ├── 商品列表（绑定门店/供应商）
│   ├── 新增/编辑/上下架
│   └── 库存与分类
├── 📋 订单管理            [已落地]
│   ├── 订单列表（本商家）
│   ├── 订单详情/发货
│   └── 售后处理
├── 🎯 营销/核销           [规划]
│   ├── 线下核销记录
│   ├── 让利与积分发放明细
│   └── 优惠券/活动
├── 📈 数据看板            [规划]
│   ├── 销售趋势
│   ├── 各门店业绩对比
│   └── 团队业绩
├── 💰 财务对账            [规划]
│   ├── 红包/余额明细
│   ├── 结算与提现记录
│   └── 对账报表导出
└── 🔔 消息公告            [规划]

5.2 模块详表

模块	状态	核心功能	关键实体
门店管理	✅ 已落地	列表/增/删/改/启禁用，按商家隔离	`merchant_store`
供应商管理	✅ 已落地	私有供应商 CRUD；平台公共只读	`supplier(merchant_id)`
管理团队	✅ 已落地	员工 CRUD、重置密码、启禁用（删除用禁用替代）	`merchant_staff`
商品管理	✅ 已落地	商品绑定门店/供应商，上下架、库存、删除	`goods(store_id/supplier_id)`
订单管理	✅ 已落地	本商家订单查询、详情、发货、售后	`sales_order`/`order_item`
营销/核销	🔜 规划	线下核销记录、让利/积分明细、活动	`verify_order` 等
数据看板	🔜 规划	销售趋势、门店对比、团队业绩	统计视图
财务对账	🔜 规划	红包/结算/提现明细、导出	`red_packet_ledger` 等
消息公告	🔜 规划	平台公告接收、站内消息	`announcement`

六、技术实现要点

6.1 前端

项	方案
布局	`MerchantLayout`（深色侧栏，与平台 `BasicLayout` 视觉区分）
路由	`/merchant/login`(public) + `/merchant` 子路由；守卫区分两套登录态
请求层	`merchantRequest.js` 复用 `request` 拦截器，token 键 `xshop_merchant_token`
状态	`store/merchantUser.js`（Pinia）持有 token/merchant/staff
权限	菜单与按钮按 `merchantUser.permissions` 渲染
隔离	前端仅展示"本商家"数据；越权由后端 `1004` 兜底

6.2 后端

项	方案
基类	`BaseMerchant` 提供 `success()/fail()/merchantId()/staffId()`
隔离	每个控制器方法首行取 `merchantId()` 并 `where`；越权=1004
分页	统一 `paginate`，返回 `{list,total,page,page_size}`
中间件	`MerchantAuthMiddleware` 失败 401，成功注入上下文
令牌	`MerchantToken` HMAC，secret/ttl 走 config，便于轮换

6.3 数据字典

docs/generate_data_dictionary.py 已纳入 merchant_store/merchant_staff/supplier.merchant_id/goods.store_id 等（现 46 表）。后续新增商家侧表/列须重跑保持同步。

七、开发与落地路线图

阶段0 — 基础设施与组织模型（✅ 已交付）

迁移、鉴权层、门店/供应商/团队 CRUD、前端布局与三页、数据隔离联调。
验收：m1/m2 互不可见；越权 1004；无 token 401；build 通过。

阶段1 — 商品与订单（✅ 已交付，2026-08-08）

后端：Goods/Order 控制器，所有查询强制 where merchant_id（与 store_id/supplier_id 归属本商家门店/供应商校验）；订单按 order_no 优先、id 兜底解析。
前端：goods.vue / order.vue，商品表单含"归属门店/供应商"下拉（含平台公共供应商）；订单含详情抽屉、发货、售后。
接口：goods/list|detail|stores|suppliers|create|update|status|delete、order/list|detail|ship|refund，均挂 MerchantAuthMiddleware。
验收：商家只能看到/操作本商家商品与订单（m1/m2 互不可见、越权 1004、无 token 401）；商品绑定门店/供应商生效。

阶段2 — 营销核销与数据看板

线下核销记录查询、让利/积分发放明细；销售趋势、门店业绩对比图。
商家内部数据权限细化到门店（staff→store_id 列表）。

阶段3 — 财务对账与消息

商家侧红包/结算/提现明细（数据来自平台结算链路，商家只读核对）；对账报表 Excel 导出。
平台公告接收、站内消息。

优先级建议

商品 + 订单（商家经营核心闭环）
数据看板（经营决策）
营销核销（线下联盟落地）
财务对账 + 消息（收尾）

八、风险与约定

风险/约定	说明
强制隔离	任何新增商家侧接口必须带 `merchant_id` 过滤，代码评审必查；否则横向越权
越权语义	查不到即 `1004`，禁止返回空列表冒充"无数据"
删除策略	门店/供应商用硬删（已加二次确认）；团队用"禁用"替代删除，保留审计
平台 vs 商家	平台"商家入驻审核/让利配置"仍是平台后台职责；商家后台只消费这些配置
令牌安全	MerchantToken 7 天有效期，secret 走 config；如需吊销可加 `jti` 黑名单
热更新	后端改 controller/route 后须重启 `php think run`；前端 dev 走 vite 代理
术语一致性	代码/文档统一"商家"，对外表述"商户"时等同；避免与"平台运营后台"混淆

九、与既有文档衔接

既有文档	关系
管理后台规划.md	平台运营后台（六大角色），本规划为其平行补充
功能模块规划.md（模块6 线下联盟·商家端管理）	商家端 104-108（登录/核销/积分/销售/奖励），本规划将其扩展为完整后台
后台权限设计方案.md	平台 RBAC+数据权限+V6隔离；商家侧复用同一套 RBAC 机制、独立权限段
数据字典	商家侧表已纳入，持续同步
商品管理模块设计方案.md	阶段1 商品管理的详细依据

文档生成时间：2026-08-07（阶段0 落地）；2026-08-08 更新阶段1 商品与订单已交付。阶段2–3 为规划路线，待排期实施。

本文档由 Markdown 自动转换生成，与 商家管理后台设计开发规划.md 内容一致。生成时间：2026-08-07。