主题
管理后台 Web
负责人：前端程序员
运行环境：浏览器（内部使用，不对外公开）；需同时支持 PC 与移动端适配（响应式布局或等效方案，见下）
核心职责：为运营人员、门店店长、客服、老板/财务提供数据查看与系统管理界面
职责边界
管理后台是面向内部运营人员的 Web 应用，通过调用云端 API 实现所有功能，本身不包含业务逻辑。
核心系统（云端）持久化业务原始数据（订单流水、核销、进出事件、设备日志、配置变更等）；管理后台只做展示、筛选、配置与导出，不替代账套；财务侧报表在后台基于原始数据与分润规则、成本配置等派生计算后导出，供导入第三方专业财务系统。
管理后台负责：
- 门店、用户、订单、产品的增删改查界面
- 数据分析图表展示
- 硬件状态监控与远程控制操作
- 外部券码管理
- 多角色权限（
owner/finance/manager/support/ops）及门店上下文切换
管理后台不负责：
- 直接操作硬件（通过云端 API 下指令）
- 用户端功能（由小程序负责）
终端与移动端适配
| 要求 | 说明 |
|---|---|
| 布局 | 断点适配窄屏；表格在移动端优先「卡片列表 + 横向滑动」或「关键列 + 详情抽屉」 |
| 交互 | 触控热区足够大；远程开门等高危操作需二次确认 |
| 门店切换 | 小屏下切换器支持全屏搜索、最近使用门店、与 门店管理 — 多维度快速搜索 相同维度的快速定位 |
| 性能 | 列表虚拟滚动或分页；弱网下列表骨架屏与失败重试 |
权限与使用视角
设计权限时与 门店上下文（全体店 / 单店） 配合：manager（店长） 以「先选定门店，再操作本店数据」为主路径；support（客服） 以「先定位问题对象（人或店/设备）」为主路径；finance（财务） 以「规则配置 + 期间汇总 + 标准导出」为主路径。
管理人员统一存储于 staff 表，角色定义见 用户体系 — 管理人员角色。
1. manager（店长）
- 切换门店：通过顶部（或移动端首屏）门店切换器进入单店视角；切换器须支持多种快速搜索方式定位门店，规则与 门店管理 中「多维度快速搜索」一致（关键词、状态、类型、区域、渠道、设备/设施等，可组合）。
- 数据范围：登录后默认仅绑定门店；仅可查看与操作本店数据；会员列表仅展示归属本店的会员（由云端按
staff_store关联表鉴权与筛选，见 会员管理）。 - 全体店模式：
manager默认为单店视角，无全体店选项。
2. support（客服）
- 视角：处理「某消费者」或「某门店设备/履约」问题，需少步数定位。
- 能力建议：全局搜索（消费者 ID、手机号、微信昵称、订单号）；门店搜索（与店长相同维度）；从消费者/订单/设备告警一键跳转到关联门店上下文与硬件面板；操作留痕，敏感能力（如删人脸）按角色收敛。
3. finance（财务）
- 配置：门店分润设置（规则、比例、参与主体、生效区间、例外门店等）；店铺成本配置（固定成本、分摊规则、科目映射等与产品细化）。
- 报表：按会计期间生成可导入第三方财务系统的导出文件（列名、币种、税率、门店维度、科目代码等与目标系统模板对齐；格式如 CSV/Excel，具体模板在实施阶段锁定）。
- 数据依据：以核心系统原始流水为准；报表为派生结果，需支持核对明细钻取（跳转订单/核销列表）。
功能页面清单（索引）
| 模块 | 文档 |
|---|---|
| 门店管理（列表、多维度搜索、子模块字段） | 门店管理 |
| 用户 / 会员管理（列表、编辑信息、店长数据范围） | 会员管理 |
| 订单管理（列表、详情、退款流程、数据导出） | 订单管理 |
| 产品管理（CRUD、上架下架、价格变更） | 产品管理 |
| 硬件控制面板（设备状态、远程操作、告警中心） | 硬件控制面板 |
| 数据分析（仪表盘、营收/用户/运营报表） | 数据分析 |
| 财务管理（分润配置、成本配置、期间报表） | 财务管理 |
| 外部券码管理（批次管理、导出、核销记录） | 外部券码管理 |
模块优先级（开发顺序建议）：
| 优先级 | 模块 | 理由 |
|---|---|---|
| P0 | 门店管理 + 会员管理 | 基础数据管理，其他模块依赖 |
| P0 | 订单管理 + 产品管理 | 核心业务闭环（购买 → 查询） |
| P1 | 外部券码管理 | 营销推广能力 |
| P1 | 硬件控制面板 | 门店日常运维必备 |
| P2 | 数据分析 | 经营决策支撑 |
| P2 | 财务管理 | 财务对账与分润 |
多语言内容录入
管理后台界面可保持中文，但面向用户展示的业务内容，后台录入时必须支持多语言输入。
录入规则
- 支持
zh、en，两种语言均必填 - 后台提交格式统一为多语言对象：
{ "zh": "...", "en": "..." } - 表单保存前校验每个必填语言是否有值
- 列表页默认显示中文，可切换预览英文
涉及页面
| 页面 | 可译字段 |
|---|---|
| 产品管理 | 产品名称、产品描述 |
| 门店管理 | 门店名称、地址、门店简介 |
| 活动/Banner（如有） | 标题、文案内容 |
前端组件建议
为避免重复开发，建议抽象 LocalizedInput 组件，按语言 Tab 编辑同一字段不同语言值，统一用于产品、门店等表单。
角色权限矩阵
| 功能模块 | owner | finance | manager（本店） | support | ops |
|---|---|---|---|---|---|
| 查看所有门店数据 | ✅ | ✅ | ❌ | 按策略 | ✅ |
| 门店切换 / 快速搜索定位 | ✅ | ✅ | ✅（仅绑定店） | ✅ | ✅ |
| 本店消费者与订单 | ✅ | ✅ | ✅（仅本店归属） | ✅（处理问题时） | ✅ |
| 产品/价格管理 | ✅ | ❌ | ❌ | ❌ | ✅ |
| 订单退款 | ✅ | ✅ | ❌ | 按策略 | ✅ |
| 外部券码管理 | ✅ | ✅ | ❌ | 按策略 | ✅ |
| 硬件远程控制 | ✅ | ❌ | ✅ | 按策略 | ✅ |
| 消费者人脸数据管理 | ✅ | ❌ | ✅ | 按策略 | ❌ |
| 分润 / 成本配置 | ✅ | ✅ | ❌ | ❌ | ❌ |
| 财务导出（第三方导入） | ✅ | ✅ | ❌ | ❌ | ❌ |
| 数据分析查看 | ✅ | ✅ | ✅（本店） | 按策略 | ✅ |
详情页 Tab 权限分层策略
详情页（门店、会员、订单等）普遍采用多级 Tab 组织功能。不同角色能看到的 Tab 集合不同，遵循以下设计原则：
核心原则：总部配置集中制
- 平台级配置集中到专属 Tab：渠道绑定、设备增删、权限分配、账号绑定/解绑等「平台侧」管理能力，集中在总部专属 Tab 中，分店视角不可见。避免将总部专属字段零散地混在分店也能看到的 Tab 里。
- 共享 Tab 内按角色收敛可编辑范围：分店店长与总部都能看到的 Tab（如「基本信息」），在字段粒度上区分可编辑性 — 店长只能编辑营业时间、联系电话、门店简介等运营字段，门店名称、类型、面积等结构性字段仅总部可改。
- 分店视角保持简洁：店长只看到与日常运营直接相关的 Tab，减少认知负担，也减少误操作风险。
Tab 可见性规则
| 标记 | 含义 |
|---|---|
| 全角色 | 所有角色均可见（数据范围受门店上下文约束） |
| 总部 | 仅老板、财务等全局角色可见；分店店长不可见 |
| 按策略 | 由管理员在角色权限配置中决定是否开放 |
各详情页 Tab 权限设计
详见各子模块文档中的 Tab 权限矩阵：
前端实现
权限判断统一由 composables/usePermission.ts 提供：
isHQ：当前用户是否为总部视角（owner/finance/ops角色，或处于全体店模式）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 # 产品管理列表
/products/new # 新增产品
/products/:id/edit # 编辑产品
/hardware # 硬件总览面板
/hardware/:storeId # 单店硬件面板
/hardware/alerts # 告警中心
/analytics # 数据分析（默认营收分析）
/analytics/revenue # 营收分析
/analytics/users # 用户分析
/analytics/operations # 运营分析
/analytics/feishu # 飞书同步管理
/finance/profit-sharing # 分润配置
/finance/costs # 成本配置
/finance/reports # 财务报表
/voucher-batches # 外部券码批次列表
/voucher-batches/new # 新建券码批次
/voucher-batches/:id # 批次详情
/voucher-batches/:id/records # 核销记录
/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 定时轮询）
- [ ] 第三方财务系统导入模板字段清单（与实施财务软件对齐）
- [ ] 客服角色默认是否全门店可读、是否需工单系统承接
扩展范围：营销中心
营销中心用于建立用户画像 → 人群圈选 → 精准触达 → 效果追踪的闭环营销能力，未纳入当前后台核心交付范围。
核心能力
| 能力 | 说明 | 依赖 |
|---|---|---|
| 用户画像分析 | 基于用户标签、消费行为、到访数据自动生成用户画像 | 用户标签体系（已在会员管理中设计） |
| 人群圈选 | 根据画像维度、标签、行为数据组合筛选目标用户群 | 用户标签体系 |
| 微信模板消息推送 | 对圈选用户群发送微信订阅消息 / 模板消息 | 微信小程序订阅消息能力 |
| 定向产品推荐 | 对特定用户群推送定制化产品或优惠 | 产品管理系统 |
| 定向活动投放 | 创建营销活动，定向投放给特定用户群 | 产品管理 + 券码系统 |
用户画像分析
画像维度
| 维度 | 数据来源 | 说明 |
|---|---|---|
| 基础属性 | 用户资料 | 性别、年龄段、城市、来源渠道 |
| 消费特征 | 订单系统 | 累计消费、客单价、购买频次、偏好产品类型、首次/最近购买时间 |
| 到访行为 | 进出记录 | 到访频次、偏好时段（晨练/午间/晚间）、偏好门店、平均停留时长 |
| 会员状态 | 会员系统 | 当前是否有效卡、卡类型、即将到期（7天内）、已过期 |
| 标签画像 | 标签系统 | 手动标签 + 自动标签（参见会员管理 — 用户标签体系） |
画像分析页面
| 功能 | 说明 |
|---|---|
| 用户画像总览 | 全量用户的画像分布（性别、年龄段、消费层级、活跃度分布图） |
| 单用户画像 | 会员详情页中展示该用户的完整画像雷达图 |
| 画像趋势 | 按月查看用户画像分布的变化趋势 |
人群圈选
圈选条件
| 条件类别 | 可选条件 | 组合逻辑 |
|---|---|---|
| 基础属性 | 性别、年龄段、城市、来源渠道 | AND / OR |
| 标签 | 用户标签（多选） | AND / OR |
| 消费行为 | 累计消费范围、购买次数范围、偏好产品类型 | AND / OR |
| 到访行为 | 到访频次范围、偏好时段、偏好门店、最近到访时间 | AND / OR |
| 会员状态 | 是否有效卡、卡类型、即将到期、已过期 | AND / OR |
| 风险等级 | 低/中/高/黑名单 | AND / OR |
多个条件类别之间为 AND 关系，同一类别内多条件为 OR 关系。圈选结果实时预览命中用户数。
人群管理
| 功能 | 说明 |
|---|---|
| 保存人群 | 将圈选条件保存为命名人群，如「即将到期的月卡用户」 |
| 人群列表 | 查看已保存的人群，展示命中用户数、上次更新时间 |
| 动态更新 | 人群用户列表每日凌晨自动刷新（基于最新数据） |
| 人群导出 | 导出人群用户列表为 Excel |
Push 推送（微信订阅消息）
推送能力
| 功能 | 说明 |
|---|---|
| 模板消息推送 | 对圈选用户群或指定人群发送微信小程序订阅消息 |
| 推送模板管理 | 管理可用的消息模板（标题、内容、跳转页面） |
| 推送记录 | 查看历史推送任务的状态和效果数据 |
推送流程
- 选择目标用户：从保存的人群中选择，或即时圈选
- 选择消息模板：从模板库中选择（如「续费提醒」「新品上线」「活动通知」）
- 编辑推送内容：模板变量填充（如用户名、卡类型、到期日期等）
- 选择跳转页面：推送后点击跳转的小程序页面（如产品详情、活动页）
- 设置推送时间：立即推送 / 定时推送
- 预览 & 确认：预览推送内容，确认后发送
- 效果追踪：推送后查看送达率、打开率、转化率
推送限制
| 限制 | [建议值] | 说明 |
|---|---|---|
| 同一用户推送频率 | 每日最多 1 条 | 避免打扰 |
| 单次推送上限 | 10,000 人 | 微信接口限制 |
| 推送时段 | 08:00 - 21:00 | 非营业时间不推送 |
| 订阅状态检查 | 仅推送给已订阅用户 | 微信订阅消息需要用户主动授权 |
推送效果数据
| 指标 | 说明 |
|---|---|
| 目标用户数 | 圈选命中用户数 |
| 可推送用户数 | 已订阅消息的用户数 |
| 实际推送数 | 成功调用微信 API 发送的数量 |
| 送达率 | 实际推送数 / 目标用户数 |
| 打开率 | 点击消息跳转小程序的用户数 / 实际推送数 |
| 转化率 | 产生购买/续费等目标行为的用户数 / 打开数 |
定向产品推荐
| 功能 | 说明 |
|---|---|
| 定价策略 | 为特定人群设置专属价格或优惠（如即将到期用户续费 8 折） |
| 推荐展示 | 小程序端为匹配用户群的用户展示定向推荐产品 |
| 推荐记录 | 查看定向推荐的历史配置和效果 |
定向活动投放
活动管理
| 功能 | 说明 |
|---|---|
| 创建活动 | 设置活动名称、时间、目标人群、活动产品/优惠 |
| 活动类型 | 限时优惠 / 续费促销 / 新品体验 / 节日活动 |
| 活动追踪 | 实时查看活动参与人数、转化率、GMV |
| 活动复盘 | 活动结束后生成效果报告 |
营销中心页面路由（规划）
/marketing # 营销中心首页（数据概览）
/marketing/portraits # 用户画像分析
/marketing/audiences # 人群管理
/marketing/audiences/new # 新建人群圈选
/marketing/audiences/:id # 人群详情
/marketing/push # Push 推送管理
/marketing/push/new # 新建推送任务
/marketing/push/:id # 推送详情（效果数据）
/marketing/promotions # 定向产品推荐
/marketing/campaigns # 活动管理
/marketing/campaigns/new # 新建活动
/marketing/campaigns/:id # 活动详情（数据追踪）营销中心权限（规划）
| 功能 | owner | ops | finance | manager | support |
|---|---|---|---|---|---|
| 用户画像查看 | ✅ 全店 | ✅ 全店 | ✅ 全店 | ✅ 本店 | ❌ |
| 人群圈选 | ✅ | ✅ | ✅ | ❌ | ❌ |
| Push 推送 | ✅ | ✅ | ❌ | ❌ | ❌ |
| 定向产品推荐 | ✅ | ✅ | ❌ | ❌ | ❌ |
| 活动管理 | ✅ | ✅ | ✅（查看） | ❌ | ❌ |
设计说明：营销中心涉及定价策略和用户触达，属于总部运营策略级能力，
manager和support不开放操作权限。manager可通过「门店概览」Tab 查看本店用户画像数据。