RBAC 权限控制矩阵

36 个租户级权限 × 18 个资源分类 — 每个权限管什么、保护哪些 API

36
租户级权限
18
资源分类
3
权限等级
4
决策层级
0
角色绕过

权限决策流程（3 层 + 1 引擎）

HTTP 请求
→
JWT 认证
auth-middleware
→
路由规则匹配
explicitRouteGuard
→
Layer 1: 特殊拒绝
DENY → 直接 403
→
Layer 2: 特殊授予
GRANT → 直接放行
→
Layer 3: 岗位权限
job_title_permissions
→
Layer 4: 角色权限
role_permissions (兜底)
→
无匹配 → 403
view (1) — 只读 edit (2) — 编辑 manage (3) — 完全控制 special — 特殊动作

租户 RBAC 域

  • 所有 /api/* 业务端点
  • 3 层数据库权限查询（无角色绕过）
  • 角色：super_admin, admin, manager, employee
  • 支持门店级范围隔离（center_id scoping）

平台管理域

  • 仅 /api/platform/* 端点
  • 直接角色检查 role === 'platform_superadmin'
  • 不受任何租户权限表约束
  • 管理租户本身、全局配置

门店 Scope 分析（2026-02-17 定稿）

哪些权限需要按门店（center_id）隔离，哪些保持租户全局。当前系统 scope 仅在 Special Permissions 层生效，Role/Job Title 层尚未实现。

13 组 / 28 个
需要门店 scope
5 组 / 8 个
租户全局（不需要 scope）
权限组 Scope 业务理由
appointments:* 需要 A 店经理不应改 B 店预约，这是最核心的日常操作
schedules:* 需要 排班天然按门店，跨店排班会造成运营混乱
day_end_closeout:* 需要 日结对账严格按门店，A 店收银台 B 店经理不能碰
time_clock:* 需要 考勤按门店发生，经理只管自己门店的打卡记录
reports:* 需要 最敏感的数据——A 店经理不应看到 B 店营收
employees:* 需要 连锁场景下 A 店经理只管 A 店的人（跨店员工需额外处理）
tips:* 需要 小费按门店产生，经理只看自己门店
checkin:* 需要 每家店 Kiosk 配置独立（欢迎页、展示内容等）
pos_devices:* 需要 POS 设备物理绑定在特定门店
stores:* 需要 A 店经理可改 A 店营业时间/地址，不能碰 B 店
services:* 需要 门店可独立上架/下架服务项目，管理本店服务列表
roles:* 需要 A 店经理给 A 店员工调权限，不应能动 B 店的人
payroll:* 需要 经理只看自己门店的工资单，RBAC 层 scope 比纯数据过滤更安全
settings:* 全局 全局配置（功能开关、Guest App 外观等），按店切分会导致配置碎片化
marketing:* 全局 营销活动是品牌级策划（邮件、促销、忠诚度），店长不会独立搞营销
guests:* 全局 客人跨门店流动——隔离会丢失服务历史和过敏备注，影响服务连贯性
giftcards:* 全局 礼品卡跨店通用是核心卖点，隔离会导致核销失败
sync:* 全局 纯技术运维，同步操作天然是租户级别（不按店拆分）
当前实现状态：scope 仅在 employee_special_permissions 表中通过 center_id 过滤生效。 role_permissions 和 job_title_permissions 表虽有 scope 列，但查询未使用。 完整实现需修改 _checkRolePermission 和 _checkJobTitlePermission 的 SQL 查询，并为 13 组 scope-aware 权限的路由规则标注 scopeRequired: true。
📅
预约管理SCOPE
appointments:*
2 个权限 ▶
预约的查看、创建、修改、删除、状态变更，以及子预约（sub-appointments）、购物车预约和可用时段查询。
权限名等级保护的 API 路由
appointments:view
view
GET /api/appointments 预约列表
GET /api/appointments/:id 预约详情
GET /api/appointments/employee/:id 员工预约
GET /api/appointments/guest/:id 客人预约
GET /api/sub-appointments 子预约列表
GET /api/cart-appointment 购物车预约
GET /api/availability 可用时段
appointments:manage
manage
POST /api/appointments 创建预约
PUT /api/appointments/:id 修改预约
DEL /api/appointments/:id 删除预约
PUT /api/appointments/:id/status 状态变更
POSTPUTDEL /api/sub-appointments
POSTPUTDEL /api/cart-appointment
POSTPUTDEL /api/availability
⚙
系统设置GLOBAL
settings:*
2 个权限 ▶
全局"万能钥匙"——几乎所有受保护路由都将 settings:view / settings:manage 作为 OR 备选权限。适用于管理员需要跨模块巡检的场景。同时覆盖预约设置、租户功能开关、监控、调试等。
权限名等级保护的 API 路由
settings:view
view
GET /api/settings 全局设置
GET /api/booking-config 预约配置
GET /api/tenant-features 功能开关
GET /api/monitoring 系统监控
GET /api/admin/guest-app Guest App 设置
GET /api/admin/loyalty/tiers 忠诚度层级配置
作为 OR 备选出现在几乎所有 GET 路由中
settings:manage
manage
POSTPUTDEL 几乎所有 admin 写入端点的 OR 备选
POST /api/admin/guest-app Guest App 图片上传
PUT /api/settings 修改全局设置
PUT /api/booking-config 修改预约配置
🏪
门店管理SCOPE
stores:*
2 个权限 ▶
门店（Centers）的增删改查、营业时间管理、小费设置。
权限名等级保护的 API 路由
stores:view
view
GET /api/centers 门店列表
GET /api/centers/:id 门店详情
GET /api/centers/:id/hours 营业时间
stores:manage
manage
POSTPUTDEL /api/centers 门店 CRUD
PUT /api/centers/all/tip-settings 全局小费设置
PUT /api/centers/all/tip-settings/job-titles 按岗位小费配置
💅
服务项目SCOPE
services:*
2 个权限 ▶
美甲服务项目的目录管理（分类、价格、时长等）。
权限名等级保护的 API 路由
services:view
view
GET /api/services 服务列表
GET /api/admin/services 后台服务管理
GET /api/mobile/my-services 员工可做的服务
services:manage
manage
POSTPUTDEL /api/services
POSTPUTDEL /api/admin/services
👤
员工管理SCOPE
employees:*
2 个权限 ▶
员工档案、个人资料、偏好设置、岗位信息、团队查看、仪表盘、日志。
权限名等级保护的 API 路由
employees:view
view
GET /api/employees 员工列表
GET /api/admin/employees 后台员工管理
GET /api/job-titles 岗位列表
GET /api/mobile/team 团队成员
GET /api/user 个人资料/偏好
GET /api/dashboard 仪表盘数据
GET /api/logs 操作日志
GET /api/chat 聊天消息
employees:manage
manage
POSTPUTDEL /api/employees 员工 CRUD
PUT /api/user/preferences 修改偏好
PUT /api/user/profile 修改资料
POST /api/user/switch-store 切换门店
🔐
角色与权限SCOPE
roles:*
2 个权限 ▶
角色定义、权限分配、岗位权限、员工特殊权限（GRANT/DENY）、审计日志。这是 RBAC 系统的"自管理"入口。
权限名等级保护的 API 路由
roles:view
view
GET /api/admin/permissions 权限列表
GET /api/admin/permissions/roles 角色权限
GET /api/admin/permissions/users/:id 用户权限详情
GET /api/admin/audit 审计日志
GET /api/admin/job-titles 岗位列表
roles:manage
manage
PUT /api/admin/permissions/roles/:roleId 修改角色权限
POST /api/admin/permissions/users/:id/special-permissions 授予特殊权限
DEL /api/admin/permissions/users/:id/special-permissions/:spId 撤销特殊权限
PUT /api/admin/permissions/job-titles/:id 修改岗位权限
POSTPUTDEL /api/admin/job-titles 岗位 CRUD
📅
排班管理SCOPE
schedules:*
2 个权限 ▶
员工排班表、排班模板、每日可用时段管理。
权限名等级保护的 API 路由
schedules:view
view
GET /api/schedules 排班列表
GET /api/schedule-templates 排班模板
GET /api/daily-availability 每日可用时段
schedules:manage
manage
POSTPUTDEL /api/schedules
POSTPUTDEL /api/schedule-templates
POSTPUTDEL /api/daily-availability
🙋
客户管理GLOBAL
guests:*
2 个权限 ▶
客户档案、备注、客户关系。支持三级客户模型：匿名 → 已识别 → 注册用户。
权限名等级保护的 API 路由
guests:view
view
GET /api/guests 客户列表
GET /api/guests/:id/notes 客户备注
GET /api/guest-relationships 客户关系
guests:manage
manage
POSTPUTDEL /api/guests 客户 CRUD
POSTPUTDEL /api/guests/:id/notes
POSTPUTDEL /api/guest-relationships
📈
报表分析SCOPE
reports:*
2 个权限 ▶
业务 KPI、日/周/月报、员工排名、门店对比、收支记录、忠诚度统计。
权限名等级保护的 API 路由
reports:view
view
GET /api/reports/business/kpi 业务 KPI
GET /api/reports/daily /weekly /monthly 时段报表
GET /api/reports/ranking 员工排名
GET /api/reports/stores 门店对比
GET /api/income-expense 收支记录
GET /api/admin/loyalty-packages/stats 套餐统计
GET /api/admin/loyalty-subscriptions/stats 订阅统计
reports:manage
manage
POSTPUTDEL /api/reports 自定义报表管理
POSTPUTDEL /api/income-expense 收支编辑
📢
营销与忠诚度GLOBAL
marketing:*
2 个权限 ▶
最大的权限组。覆盖：营销活动、研究问卷、标签系统、邮件模板、促销、触发模板、iPad 展示、忠诚度体系（套餐/订阅/推荐）、邮件设计器、消息设置。
权限名等级保护的 API 路由
marketing:view
view
GET /api/marketing 营销活动
GET /api/research 研究问卷
GET /api/tags 标签系统
GET /api/email-templates 邮件模板
GET /api/promotion/email-templates 促销模板
GET /api/marketing/trigger-templates 触发模板
GET /api/admin/ipad-showcase iPad 展示
GET /api/admin/loyalty-packages 忠诚度套餐
GET /api/admin/loyalty-subscriptions 订阅计划
GET /api/admin/loyalty/referrals 推荐系统
GET /api/email-designs 邮件设计
GET /api/settings/messaging 消息设置
GET /api/discounts 折扣方案
marketing:manage
manage
POSTPUTDEL /api/marketing /api/tags /api/email-templates
POSTPUTDEL /api/promotion/* 促销管理
POSTPUTDEL /api/marketing/trigger-templates
POSTPUTDEL /api/admin/ipad-showcase
POSTPUTDEL /api/admin/loyalty-packages /loyalty-subscriptions /loyalty/referrals
POSTPUTDEL /api/email-designs 邮件设计器
POSTPUT /api/settings/messaging
🎁
礼品卡GLOBAL
giftcards:*
2 个权限 ▶
礼品卡的发放、核销、查询。
权限名等级保护的 API 路由
giftcards:view
view
GET /api/gift-cards 礼品卡列表
GET /api/admin/gift-cards 后台礼品卡管理
giftcards:manage
manage
POSTPUTDEL /api/gift-cards
POSTPUTDEL /api/admin/gift-cards
✅
签到/KioskSCOPE
checkin:*
2 个权限 ▶
客人自助签到配置、签到统计、今日签到数据。
权限名等级保护的 API 路由
checkin:view
view
GET /api/checkin-config 签到配置
GET /api/checkin/stats 签到统计
GET /api/checkin/today 今日签到
checkin:manage
manage
POSTPUTDEL /api/checkin-config 签到配置修改
💰
财务与日结SCOPE
day_end_closeout:*
3 个权限 ▶
支付、发票、收银台、日结对账、终端管理、收据。:unlock 是特殊动作级别，用于日结后的解锁操作。
权限名等级保护的 API 路由
day_end_closeout:view
view
GET /api/payment 支付记录
GET /api/invoices 发票列表
GET /api/cash-drawer 收银台状态
GET /api/day-end-closeout 日结报表
GET /api/terminals 终端列表
GET /api/receipts 收据查看
day_end_closeout:manage
manage
POST /api/payment 发起支付
POST /api/payment/calculate-total 计算总价
POST /api/payment/apply-discounts 应用折扣
POST /api/payment/split-payment 分账
POSTPUTDEL /api/terminals 终端管理
POSTPUT /api/day-end-closeout 日结操作
day_end_closeout:unlock
special
与 :manage 保护相同路由（OR 关系）
用途：日结后需要重新打开收银台或修改已对账数据时的解锁权限
⏱
考勤打卡SCOPE
time_clock:*
3 个权限 ▶
员工考勤记录、打卡操作、PIN 码管理。:punch 是 edit 级别的特殊动作，允许员工打卡但不能管理他人记录。
权限名等级保护的 API 路由
time_clock:view
view
GET /api/time-clock 考勤记录查看
time_clock:manage
manage
POSTPUTDEL /api/time-clock 考勤管理
包含：编辑他人记录、设置打卡规则、PIN 码重置
time_clock:punch
punch (edit)
POST /api/time-clock 自己的上下班打卡
等级为 edit，不含 manage 权限（不能编辑他人记录）
💵
薪资管理SCOPE
payroll:*
2 个权限 ▶
工资单生成、确认、导出。
权限名等级保护的 API 路由
payroll:view
view
GET /api/payroll 工资单查看
payroll:manage
manage
POST /api/payroll 生成工资单
PUT /api/payroll 确认/修改工资单
POST /api/payroll/export 导出工资单
💲
小费管理SCOPE
tips:*
2 个权限 ▶
员工小费查看、小费设置管理。
权限名等级保护的 API 路由
tips:view
view
GET /api/mobile/tips 我的小费
tips:manage
manage
POSTPUTDEL /api/mobile/tips 小费设置
🔄
数据同步GLOBAL
sync:*
2 个权限 ▶
数据同步任务管理（如 Zenoti 迁移时使用）、同步配置。
权限名等级保护的 API 路由
sync:view
view
GET /api/sync 同步状态
GET /api/sync-config 同步配置
sync:manage
manage
POSTPUTDEL /api/sync 执行同步
POSTPUTDEL /api/sync-config 同步配置修改
💳
POS 终端SCOPE
pos_devices:*
2 个权限 ▶
CodePay P5 POS 终端的设备列表、配对码生成、设备解绑。通过 migration 067-add-pos-permissions 添加。
权限名等级保护的 API 路由
pos_devices:view
view
GET /api/pos/devices POS 设备列表
pos_devices:manage
manage
POST /api/pos/pairing-code 生成配对码
DEL /api/pos/devices/:deviceId 解绑设备