管理后台 Web

负责人：前端程序员
运行环境：浏览器（内部使用，不对外公开）；需同时支持 PC 与移动端适配（响应式布局或等效方案，见下）
核心职责：为运营人员、门店店长、客服、老板/财务提供数据查看与系统管理界面

职责边界

管理后台是面向内部运营人员的 Web 应用，通过调用云端 API 实现所有功能，本身不包含业务逻辑。

核心系统（云端）持久化业务原始数据（订单流水、核销、进出事件、设备日志、配置变更等）；管理后台只做展示、筛选、配置与导出，不替代账套；财务侧报表在后台基于原始数据与分润规则、成本配置等派生计算后导出，供导入第三方专业财务系统。

管理后台负责：

门店、用户、订单、产品的增删改查界面
数据分析图表展示
硬件状态监控与远程控制操作
优惠券和核销记录管理
多角色权限（老板 / 财务 / 店长 / 客服等）及门店上下文切换

管理后台不负责：

直接操作硬件（通过云端 API 下指令）
用户端功能（由小程序负责）

终端与移动端适配

要求	说明
布局	断点适配窄屏；表格在移动端优先「卡片列表 + 横向滑动」或「关键列 + 详情抽屉」
交互	触控热区足够大；远程开门等高危操作需二次确认
门店切换	小屏下切换器支持全屏搜索、最近使用门店、与门店管理 — 多维度快速搜索相同维度的快速定位
性能	列表虚拟滚动或分页；弱网下列表骨架屏与失败重试

权限与使用视角

设计权限时与 门店上下文（全体店 / 单店） 配合：店长以「先选定门店，再操作本店数据」为主路径；客服以「先定位问题对象（人或店/设备）」为主路径；财务以「规则配置 + 期间汇总 + 标准导出」为主路径。

1. 店长（门店管理员）

切换门店：通过顶部（或移动端首屏）门店切换器进入单店视角；切换器须支持多种快速搜索方式定位门店，规则与门店管理中「多维度快速搜索」一致（关键词、状态、类型、区域、渠道、设备/设施等，可组合）。
数据范围：登录后默认仅绑定门店；仅可查看与操作本店数据；会员列表仅展示归属本店的会员（由云端按「门店—会员归属」鉴权与筛选，见会员管理）。
全体店模式：若账号绑定多店，是否允许切换「全体店」由角色策略决定；默认店长为单店视角。

2. 客服

视角：处理「某用户」或「某门店设备/履约」问题，需少步数定位。
能力建议：全局搜索（会员 ID、手机号、微信昵称、订单号）；门店搜索（与店长相同维度）；从会员/订单/设备告警一键跳转到关联门店上下文与硬件面板；操作留痕，敏感能力（如删人脸）按角色收敛。

3. 财务

配置：门店分润设置（规则、比例、参与主体、生效区间、例外门店等）；店铺成本配置（固定成本、分摊规则、科目映射等与产品细化）。
报表：按会计期间生成可导入第三方财务系统的导出文件（列名、币种、税率、门店维度、科目代码等与目标系统模板对齐；格式如 CSV/Excel，具体模板在实施阶段锁定）。
数据依据：以核心系统原始流水为准；报表为派生结果，需支持核对明细钻取（跳转订单/核销列表）。

功能页面清单（索引）

模块	文档
门店管理（列表、多维度搜索、子模块字段）	门店管理
用户 / 会员管理（列表、编辑信息、店长数据范围）	会员管理

其他模块（简述）

订单管理

订单列表（多维度筛选：时间、门店、用户、产品、状态）
订单详情
核销记录查看
退款操作

产品管理

产品套餐列表（月卡、次卡、体验卡等）
新增/编辑/下架产品
优惠券管理（创建批次、发放、查看核销情况）

硬件控制

各门店工控机在线状态（心跳监控）
AB 门实时状态展示（锁定/解锁/门磁状态）
远程开门操作（带权限控制和操作日志）
灯光远程控制
UPS 电量状态告警展示

数据分析

进出人次统计（日/周/月）
营收趋势（按门店/产品类型）
会员留存率
热门时段分析
数据导出（Excel/CSV）
飞书多维表格同步状态

财务与经营配置（财务角色）

门店分润设置、店铺成本配置
对接第三方财务系统的期间报表导出（见「权限与使用视角 — 财务」）

多语言内容录入（新增）

管理后台界面可保持中文，但面向用户展示的业务内容，后台录入时必须支持多语言输入。

录入规则

第一期支持 zh、en，两种语言均必填
后台提交格式统一为多语言对象：{ "zh": "...", "en": "..." }
表单保存前校验每个必填语言是否有值
列表页默认显示中文，可切换预览英文

涉及页面

页面	可译字段
产品管理	产品名称、产品描述
门店管理	门店名称、地址、门店简介
优惠券管理	优惠券名称、使用说明
活动/Banner（如有）	标题、文案内容

前端组件建议

为避免重复开发，建议抽象 LocalizedInput 组件，按语言 Tab 编辑同一字段不同语言值，统一用于产品、门店、优惠券等表单。

角色权限矩阵

功能模块	老板	财务	店长（本店）	客服
查看所有门店数据	✅	✅	❌	按策略（通常需跨店查询时授权）
门店切换 / 快速搜索定位	✅	✅	✅（仅绑定店）	✅
本店会员与订单	✅	✅	✅（仅本店归属会员）	✅（处理问题时）
产品/价格管理	✅	❌	❌	❌
订单退款	✅	✅	❌	按策略
优惠券创建	✅	✅	❌	按策略
硬件远程控制	✅	❌	✅	按策略
用户人脸数据管理	✅	❌	✅	按策略
分润 / 成本配置	✅	✅	❌	❌
财务导出（第三方导入）	✅	✅	❌	❌
数据分析查看	✅	✅	✅（本店）	按策略

详情页 Tab 权限分层策略

详情页（门店、会员、订单等）普遍采用多级 Tab 组织功能。不同角色能看到的 Tab 集合不同，遵循以下设计原则：

核心原则：总部配置集中制

平台级配置集中到专属 Tab：渠道绑定、设备增删、权限分配、账号绑定/解绑等「平台侧」管理能力，集中在总部专属 Tab 中，分店视角不可见。避免将总部专属字段零散地混在分店也能看到的 Tab 里。
共享 Tab 内按角色收敛可编辑范围：分店店长与总部都能看到的 Tab（如「基本信息」），在字段粒度上区分可编辑性 — 店长只能编辑营业时间、联系电话、门店简介等运营字段，门店名称、类型、面积等结构性字段仅总部可改。
分店视角保持简洁：店长只看到与日常运营直接相关的 Tab，减少认知负担，也减少误操作风险。

Tab 可见性规则

标记	含义
全角色	所有角色均可见（数据范围受门店上下文约束）
总部	仅老板、财务等全局角色可见；分店店长不可见
按策略	由管理员在角色权限配置中决定是否开放

各详情页 Tab 权限设计

详见各子模块文档中的 Tab 权限矩阵：

前端实现

权限判断统一由 composables/usePermission.ts 提供：

isHQ：当前用户是否为总部视角（boss / finance 角色，或处于全体店模式）
isBranch：当前用户是否为分店视角（manager 角色，单店模式）
can(action)：细粒度能力检查，action 格式为 domain:action（如 store:channels、member:binding）

Tab 定义中使用 requireHQ: true 标记总部专属 Tab，组件层自动过滤不可见的 Tab。共享 Tab 内部的字段级权限控制也通过 isHQ / can() 实现。

页面结构（路由规划）

/login                         # 登录页
/dashboard                     # 仪表盘（当日数据概览）
/stores                        # 门店列表
/stores/:id                    # 门店详情
/users                         # 用户列表
/users/:id                     # 用户详情
/orders                        # 订单列表
/orders/:id                    # 订单详情
/products                      # 产品管理
/coupons                       # 优惠券管理
/hardware                      # 硬件控制面板
/analytics                     # 数据分析
/finance                       # 财务：分润、成本、报表导出（占位）
/settings                      # 系统设置（账号、门店配置）

技术选型建议（Nuxt UI）

管理台希望视觉与交互更现代、且兼顾 PC + 移动端，建议采用 Nuxt 3 + Nuxt UI 作为主栈；文档站仍可为 VitePress，二者同属 Vue 生态，组件不强制复用。官方文档：Nuxt UI。

组件	建议方案	备注
框架	Nuxt 3 + TypeScript	约定式路由、布局、中间件，适合后台多模块；内部使用可按需关闭 SSR（如仅 `ssr: false` 或按路由规则），便于对接浏览器端 WS、长连接与纯前端会话
UI 与样式	Nuxt UI（`@nuxt/ui`）+ Tailwind CSS	设计语言统一、默认观感优于传统企业组件库；内置响应式、暗色模式、无障碍基础；复杂表格用 UTable 或 TanStack Table + Nuxt UI 原子组件拼装
状态管理	Pinia（`@pinia/nuxt`）	门店上下文、用户信息、筛选条件；持久化策略与门店上下文系统一致
数据请求	`$fetch` / `useFetch`（ofetch）	Nuxt 内置，可封装统一 baseURL、JWT 注入、错误与 401 处理；若团队更熟 Axios 也可并存
表单与校验	Zod + Nuxt UI 表单模式	与 TypeScript 类型对齐，减少手写校验分支
图表	ECharts + vue-echarts（或等价封装）	数据分析页；移动端减少系列数量、优先单图单指标
图标	Nuxt Icon（Iconify）	与 Nuxt UI 搭配成本低
构建	Vite（Nuxt 内置）	—
实时状态	WebSocket 或 SSE	硬件状态推送；注意与 SSR 关闭策略、断线重连与页面可见性
质量与体验	ESLint + Prettier、Vitest（可选）	表格/财务导出等关键路径可补 e2e（Playwright）

为何不优先 Ant Design Vue / Element Plus：二者偏「传统企业后台」视觉路径，定制主题后仍易同质化；Nuxt UI + Tailwind 更易做出品牌一致、信息密度可控的界面，且移动端断点下用同一套 token 收敛样式成本更低。

待确认事项

[ ] 飞书数据同步的展示形式（直接跳转飞书 vs 内嵌展示）
[ ] 硬件状态实时刷新方式（WebSocket vs 定时轮询）
[ ] 第三方财务系统导入模板字段清单（与实施财务软件对齐）
[ ] 客服角色默认是否全门店可读、是否需工单系统承接

管理后台 Web ​

职责边界 ​

终端与移动端适配 ​

权限与使用视角 ​

1. 店长（门店管理员） ​

2. 客服 ​

3. 财务 ​

功能页面清单（索引） ​

订单管理 ​

产品管理 ​

硬件控制 ​

数据分析 ​

财务与经营配置（财务角色） ​

多语言内容录入（新增） ​

录入规则 ​

涉及页面 ​

前端组件建议 ​

角色权限矩阵 ​

详情页 Tab 权限分层策略 ​

核心原则：总部配置集中制 ​

Tab 可见性规则 ​

各详情页 Tab 权限设计 ​

前端实现 ​

页面结构（路由规划） ​

技术选型建议（Nuxt UI） ​

待确认事项 ​