freedak/SBrainCO

Fork 0

Files

T

freedakgmail a7874d79b5 初始化：连锁餐饮数字化运营管理平台

2026-07-26 22:48:08 +08:00

21 KiB

Raw Blame History

连锁餐饮数字化运营管理体系 — 技术架构方案与实施计划

基于现有 PostgreSQL 数据库、50+ 分析视图和 17 份分析报告，构建可落地的数字化运营管理平台目标：实现"数据发现问题 → 自动分级 → 生成门店任务 → 现场执行 → 周度检查 → 月度验收 → 有效经验标准化"闭环

一、现有资产盘点

1.1 数据库资产

资产	规模	说明
`public.bill_records`	1,677,990行	原始账单，196个文本字段(c001-c196)
`public.bill_columns`	—	字段映射字典
`public.dish_sales_details`	5,553,314行	菜品销售明细，91家门店
`public.inventory_cost_records`	54,973行	盘点倒挤成本，121个成本单位
`public.inventory_store_mapping`	—	成本单位→销售门店映射
`analytics` schema	3表+41视图+9物化视图	已建分析层

1.2 数据库连接

PostgreSQL 15（Homebrew），localhost:5432
数据库：bill_query
用户：freedak（trust认证，仅本机开发）
前端不直连数据库，通过后端API访问

二、技术选型

2.1 整体架构

┌─────────────────────────────────────────────────────┐
│                    前端 (React)                      │
│  管理驾驶舱 / 区域经理页面 / 店长页面 / 专业部门页面    │
│              TailwindCSS + shadcn/ui                 │
├─────────────────────────────────────────────────────┤
│                  后端 API (Node.js)                  │
│              Express + TypeScript                    │
│         RESTful API + WebSocket (实时推送)            │
├─────────────────────────────────────────────────────┤
│               数据层 (PostgreSQL 15)                 │
│  原始层 → 标准层 → 事实层 → 汇总层 → 应用层           │
│              bill_query @ localhost:5432             │
└─────────────────────────────────────────────────────┘

2.2 技术栈明细

层	技术	理由
前端框架	React 18 + TypeScript	组件化、类型安全、生态成熟
UI组件	TailwindCSS + shadcn/ui	快速构建高质量管理界面
图表	Recharts	React原生图表库，支持下钻交互
路由	React Router v6	多页面管理
状态管理	TanStack Query (React Query)	服务端状态管理，缓存/刷新/乐观更新
后端	Node.js + Express + TypeScript	轻量、快速开发、与前端同语言
数据库驱动	pg (node-postgres)	PostgreSQL原生驱动
API风格	RESTful	简单直观，适合管理后台
认证	JWT (json-webtoken)	轻量级角色权限控制
进程管理	tsx (开发) / pm2 (生产)	开发热重载，生产稳定

2.3 项目结构

SBrainCO/
├── package.json              # 根工作区配置
├── run.md                    # 数据库连接信息
├── 技术架构方案与实施计划.md   # 本文档
├── 马兰拉面数据分析/          # 现有分析文档和SQL（保留不动）
│
├── server/                   # 后端
│   ├── package.json
│   ├── tsconfig.json
│   ├── src/
│   │   ├── index.ts          # 入口
│   │   ├── config/
│   │   │   └── database.ts   # PostgreSQL连接池配置
│   │   ├── middleware/
│   │   │   ├── auth.ts       # JWT认证中间件
│   │   │   └── error.ts      # 统一错误处理
│   │   ├── routes/
│   │   │   ├── overview.ts   # 公司概览API
│   │   │   ├── stores.ts     # 门店管理API
│   │   │   ├── cost.ts       # 成本管理API
│   │   │   ├── platform.ts   # 平台经济性API
│   │   │   ├── member.ts     # 会员复购API
│   │   │   ├── sku.ts        # 商品SKU API
│   │   │   ├── risk.ts       # 风险内控API
│   │   │   ├── tasks.ts      # 任务闭环API
│   │   │   └── benchmark.ts  # 标杆分析API
│   │   ├── services/
│   │   │   ├── queryService.ts    # 通用查询服务
│   │   │   ├── taskService.ts     # 任务生成与跟进
│   │   │   └── gradingService.ts  # 门店自动分级
│   │   └── types/
│   │       └── index.ts      # 共享类型定义
│   └── .env                  # 环境变量
│
├── client/                   # 前端
│   ├── package.json
│   ├── tsconfig.json
│   ├── vite.config.ts
│   ├── index.html
│   ├── src/
│   │   ├── main.tsx
│   │   ├── App.tsx           # 路由配置
│   │   ├── api/
│   │   │   └── client.ts     # API客户端
│   │   ├── components/
│   │   │   ├── ui/           # shadcn/ui基础组件
│   │   │   ├── charts/       # 图表组件
│   │   │   ├── layout/       # 布局组件
│   │   │   └── common/       # 通用组件
│   │   ├── pages/
│   │   │   ├── HeadquartersDashboard.tsx   # 总部驾驶舱
│   │   │   ├── RegionalManager.tsx         # 区域经理页面
│   │   │   ├── StoreManager.tsx            # 店长页面
│   │   │   ├── ProductDept.tsx             # 商品部页面
│   │   │   ├── MemberDept.tsx              # 会员部页面
│   │   │   ├── FinanceDept.tsx             # 财务页面
│   │   │   ├── SupplyChainDept.tsx         # 供应链页面
│   │   │   ├── ITDept.tsx                  # 信息部页面
│   │   │   └── StoreDetail.tsx             # 门店详情(下钻)
│   │   ├── hooks/
│   │   │   └── useApi.ts    # 数据查询hooks
│   │   └── lib/
│   │       └── utils.ts     # 工具函数
│   └── tailwind.config.ts
│
└── shared/                   # 前后端共享类型
    └── types.ts

三、数据层设计

3.1 现有视图直接复用

以下视图已有且可直接作为API数据源：

API模块	数据源视图	说明
公司概览	`v_overview_daily`	日度实收/账单/客单/优惠率/毛利率
门店记分卡	`v_store_scorecard`	门店核心指标
门店风险分级	`v_store_risk_rating`	红黄绿分级
门店经营象限	`v_store_benchmark`	明星/规模承压/高效潜力/重点改善
门店行动清单	`v_store_action_list`	含品类结构和平台成本
门店执行优先级	`v_store_execution_priority`	含餐段/会员/零实收机会
平台经济性	`v_store_platform_economics`	三平台收入/折扣/佣金/成本率
会员对比	`v_member_comparison`	会员vs非会员
会员复购	`v_store_repeat_summary_monthly`	门店复购率
餐段机会	`v_store_meal_opportunity`	餐段平均单价提升空间
会员渗透	`v_store_member_opportunity`	会员转化空间
零实收	`v_zero_received_detail` / `v_zero_received_store_summary`	零实收归因
异常账单	`v_anomaly_bills` / `v_anomaly_summary`	异常明细和汇总
营销方案	`v_marketing_plan_summary`	各营销方案效果
收银员风险	`v_cashier_risk`	收银员异常率
星期/小时	`v_weekday_summary` / `v_hourly_summary`	时间规律
渠道	`v_channel_daily`	支付渠道结构
品类	`category_summary` / `v_store_category_mix`	品类贡献和门店结构
优惠	`discount_summary`	优惠项目汇总
深入诊断	`v_store_deep_diagnosis_april`	门店综合诊断
整改优先级	`v_store_action_priority_deep_april`	P0/P1/P2分级
成本对比	`v_store_theoretical_actual_cost_april`	理论vs实际
分类成本	`v_store_category_cost_benchmark_april`	同类对标
库存效率	`v_store_inventory_efficiency_april`	库存天数/异常
标杆	`v_store_benchmark_composite`	综合标杆
任务计划	`store_monthly_action_plan`	门店月度计划(表)
任务跟进	`v_store_monthly_followup`	计划vs实际
SKU ABC	`v_dish_sku_abc_april`	SKU分级
菜品销售	`dish_sales_april` / `dish_sku_summary_april`	菜品分析
搭售	`dish_pair_summary_april` / `dish_basket_april`	购物篮分析
重点改进	`v_priority_store_improvement`	重点改进门店

3.2 需新建的表和视图

任务闭环表（第一阶段核心）

-- 门店整改任务表
CREATE TABLE analytics.store_task (
  task_id SERIAL PRIMARY KEY,
  plan_month DATE NOT NULL,
  store_code TEXT NOT NULL,
  store_name TEXT NOT NULL,
  priority TEXT NOT NULL,          -- P0/P1/P2/P3
  problem_indicator TEXT NOT NULL, -- 问题指标
  current_value NUMERIC,
  benchmark_value NUMERIC,
  target_value NUMERIC,
  problem_description TEXT,
  action_required TEXT,            -- 具体行动，不允许只写"加强管理"
  owner TEXT NOT NULL,             -- 责任人
  collaborators TEXT,             -- 协同人
  deadline DATE NOT NULL,
  status TEXT DEFAULT '待启动',    -- 待启动/进行中/已完成/已验收/已回滚
  process_evidence TEXT,           -- 过程证据（照片URL、文档链接）
  verification_indicator TEXT,     -- 验收指标
  verification_result TEXT,        -- 验收结果
  incomplete_reason TEXT,          -- 未完成原因
  next_step TEXT,                  -- 下一步
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- 任务状态变更日志
CREATE TABLE analytics.store_task_log (
  log_id SERIAL PRIMARY KEY,
  task_id INT REFERENCES analytics.store_task(task_id),
  action TEXT NOT NULL,            -- 创建/更新/完成/验收/回滚
  old_status TEXT,
  new_status TEXT,
  operator TEXT NOT NULL,
  comment TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

通用月度汇总视图（替代 `_april` 固定视图）

-- 门店月度汇总（按 report_month 参数化）
CREATE OR REPLACE FUNCTION analytics.f_store_monthly_summary(p_month DATE)
RETURNS TABLE(...) AS $$
  SELECT ... FROM analytics.bill_fact
  WHERE date_trunc('month', closed_at) = p_month
  GROUP BY store_code, store_name;
$$ LANGUAGE sql STABLE;

四、API设计

4.1 API路由总览

方法	路径	说明	对应视图
GET	`/api/overview`	公司概览	`v_overview_daily`
GET	`/api/overview/daily`	日度趋势	`v_overview_daily`
GET	`/api/stores`	门店列表	`v_store_scorecard`
GET	`/api/stores/:code`	门店详情	多视图联查
GET	`/api/stores/:code/daily`	门店日度	`v_store_daily`
GET	`/api/stores/risk`	门店风险分级	`v_store_risk_rating`
GET	`/api/stores/quadrant`	经营象限	`v_store_benchmark`
GET	`/api/stores/priority`	整改优先级	`v_store_action_priority_deep_april`
GET	`/api/stores/:code/cost`	门店成本	`v_store_theoretical_actual_cost_april`
GET	`/api/stores/:code/platform`	门店平台	`v_store_platform_economics`
GET	`/api/stores/:code/meal`	门店餐段	`v_store_meal_opportunity`
GET	`/api/stores/:code/member`	门店会员	`v_store_member_opportunity`
GET	`/api/cost/comparison`	成本对比	`v_store_theoretical_actual_cost_april`
GET	`/api/cost/category-benchmark`	分类成本对标	`v_store_category_cost_benchmark_april`
GET	`/api/cost/inventory`	库存效率	`v_store_inventory_efficiency_april`
GET	`/api/platform/economics`	平台经济性	`v_store_platform_economics`
GET	`/api/member/comparison`	会员对比	`v_member_comparison`
GET	`/api/member/repeat`	复购分析	`v_store_repeat_summary_monthly`
GET	`/api/sku/abc`	SKU ABC分析	`v_dish_sku_abc_april`
GET	`/api/sku/category`	品类结构	`category_summary`
GET	`/api/sku/attach`	搭售分析	`dish_pair_summary_april`
GET	`/api/risk/anomaly`	异常账单	`v_anomaly_bills`
GET	`/api/risk/cashier`	收银员风险	`v_cashier_risk`
GET	`/api/risk/zero-received`	零实收	`v_zero_received_detail`
GET	`/api/marketing/plans`	营销方案	`v_marketing_plan_summary`
GET	`/api/benchmark/composite`	标杆分析	`v_store_benchmark_composite`
GET	`/api/tasks`	任务列表	`store_monthly_action_plan`
GET	`/api/tasks/:id`	任务详情	`store_task`
POST	`/api/tasks`	创建任务	`store_task`
PUT	`/api/tasks/:id`	更新任务	`store_task`
PUT	`/api/tasks/:id/verify`	验收任务	`store_task`
GET	`/api/tasks/followup`	任务跟进	`v_store_monthly_followup`
GET	`/api/time/weekday`	星期规律	`v_weekday_summary`
GET	`/api/time/hourly`	小时规律	`v_hourly_summary`
GET	`/api/channel`	渠道结构	`v_channel_daily`

4.2 查询参数支持

month: 月份筛选（默认2026-04）
store_code: 门店筛选
priority: 优先级筛选（P0/P1/P2/P3）
risk_level: 风险等级（红/黄/绿）
quadrant: 经营象限
page + page_size: 分页
sort_by + sort_order: 排序

4.3 响应格式

interface ApiResponse<T> {
  success: boolean;
  data: T;
  meta?: {
    total?: number;
    page?: number;
    page_size?: number;
  };
  error?: string;
}

五、前端页面设计

5.1 页面与角色映射

页面	角色	核心内容	对应文档章节
总部驾驶舱	总经理/经营班子	公司利润桥、P0/P1门店、重大风险	§9.1
区域经理	区域经理	门店红黄绿、任务完成、周度改善	§9.2
店长页面	店长	昨日异常、今日待办、核心指标	§9.3 / §6.1
商品部	商品负责人	SKU ABC、长尾、搭售、缺货	§9.4
会员部	会员负责人	首购、复购、沉睡、召回	§9.4
财务部	财务负责人	理论vs实际成本、平台费用、异常优惠	§9.4
供应链	供应链负责人	采购价格、库存、调拨、损耗	§9.4
信息部	信息负责人	数据更新状态、映射失败、接口异常	§9.4
门店详情	所有角色	门店全维度下钻	下钻页

5.2 总部驾驶舱详细设计

首页指标卡（对应 §9.1）：

实收金额 + 环比
账单数 + 环比
平均客单价 + 环比
理论成本率
实际成本率
成本差异率
平台合并加权成本率
会员30日复购率
P0/P1门店数 + 实收覆盖

图表区：

日度实收趋势折线图（可切换日/周/月）
门店风险分级分布（红黄绿堆叠图）
门店经营象限散点图（日均实收 × 毛利率）
平台成本率分布柱状图
P0/P1门店实收覆盖瀑布图

下钻能力：

公司 → 区域 → 门店 → 餐段 → 渠道 → SKU → 原料 → 任务

5.3 店长页面设计（对应 §6.1 / §9.3）

昨日经营卡（6个模块，每模块3个异常上限）：

收入：实收/账单/客单 vs 最近4个同星期
商品：核心SKU销量/缺货/搭售率
优惠：优惠率/异常优惠/平台活动
会员：新会员/二次到店/待召回
成本：高价值原料领用/报损/盘点异常
风险：零实收/撤单/退款/异常操作

今日待办（最多3项）：

系统自动生成的任务
可标记完成/填写原因/上传凭证

本周进度：

核心指标 vs 目标的进度条
任务完成率

5.4 区域经理页面设计（对应 §6.3 / §9.2）

门店红黄绿列表/地图
本周需到店检查的门店
各店核心指标（最多2个）
任务责任人/截止日/状态
同类门店基准对比
最近4周趋势

六、任务闭环系统设计

6.1 自动分级逻辑（对应 §7.1）

P0: 数据失真 / 重大风险 / 四项以上综合问题
    → 当日确认、7天内形成方案
P1: 对利润或顾客持续产生明显影响
    → 48小时确认、当月整改
P2: 单项指标偏弱但总体可控
    → 一周内纳入计划
P3: 正常波动或观察项
    → 持续监控

6.2 任务自动生成规则

基于 v_store_action_priority_deep_april 和 store_monthly_action_plan：

高优惠(>23%) → 拆解平台折扣任务
低毛利(<70%) → SKU成本分析任务
高异常(>1.5%) → 全额优惠治理任务
低复购(<25%) → 会员触达任务
低客单(<33.63) → 餐段组合优化任务
标杆门店 → 经验输出任务

6.3 任务字段（对应 §7.2）

每个任务必须包含：

问题门店、问题指标、发生日期
当前值、同类基准、目标值
问题说明及可能原因
具体行动（不允许只写"加强管理"）
责任人、协同人、截止日期
过程证据
验收指标和验收结果
未完成原因及下一步

6.4 验收规则（对应 §6.4 / §7.3）

每家门店每月最多两个核心改进指标
连续两周不改善 → 重新判断原因
指标改善但顾客/收入恶化 → 回滚
验收标准：收入稳定 + 毛利改善 + 客户指标稳定 + 异常率下降

七、实施路线图

第一阶段：0-30天 — 基础平台 + 管理驾驶舱

目标：让现有分析真正进入管理，实现可视化驾驶舱和任务闭环

周次	后端任务	前端任务	数据层任务
W1	项目搭建、DB连接池、基础API框架	项目搭建、UI框架、布局组件	创建 `store_task` 表
W2	概览API、门店API、风险API	总部驾驶舱首页	创建任务自动生成函数
W3	成本API、平台API、会员API、SKU API	区域经理页面、门店详情页	—
W4	任务API（CRUD+验收）、标杆API	店长页面、任务管理页面	任务自动生成并关联门店

第一阶段交付物：

总部驾驶舱（公司概览 + 门店分级 + 下钻）
区域经理页面（门店红黄绿 + 任务跟进）
店长页面（昨日经营卡 + 今日待办）
任务闭环系统（自动分级 → 生成任务 → 状态更新 → 验收）
门店详情页（全维度指标下钻）

验收标准：

门店任务有责任人、有截止日、有结果
P0/P1门店问题可以下钻到具体指标和原始明细
所有指标可按月份、门店筛选

第二阶段：31-90天 — 补齐成本和利润主链路

模块	任务
数据层	建设标准主数据(dim_store/dim_sku/dim_material等)
数据层	将 `_april` 固定视图改为通用月度模型
数据层	建立周趋势、同比、环比和整改前后对照
后端	通用月度参数化API
前端	趋势对比页面、整改前后对照
前端	专业部门页面（商品/会员/财务/供应链/信息）
前端	标杆分析页面与经验推广跟踪

第二阶段交付物：

商品部页面（SKU ABC + 长尾治理 + 搭售分析）
会员部页面（复购漏斗 + 沉睡召回 + 活动贡献）
财务页面（理论vs实际成本 + 平台损益 + 异常优惠）
供应链页面（库存效率 + 异常货品 + 成本对标）
信息部页面（数据质量监控）
月度参数化模型（支持任意月份切换）
趋势对比和整改前后对照

第三阶段：3-6个月 — 预测和精细化运营

餐段销量预测、备货建议
排班建议
会员分层、流失预警、自动召回
SKU新品准入和旧品退出机制
供应商评价

八、开发环境与启动命令

8.1 环境要求

Node.js >= 18
PostgreSQL 15（已有）
npm 或 pnpm

8.2 环境变量

# server/.env
DB_HOST=localhost
DB_PORT=5432
DB_NAME=bill_query
DB_USER=freedak
DB_PASSWORD=
PORT=3001
JWT_SECRET=your-secret-key
CLIENT_URL=http://localhost:5173

8.3 启动命令

# 安装依赖
cd server && npm install
cd ../client && npm install

# 开发模式启动
cd server && npm run dev    # 后端 http://localhost:3001
cd client && npm run dev    # 前端 http://localhost:5173

九、关键约束与注意事项

不修改现有SQL和视图：所有现有分析视图保持不动，后端API直接查询
不修改原始数据表：bill_records、dish_sales_details等保持原样
新增表放在 analytics schema：与现有分析对象统一管理
API不暴露SQL：后端封装查询逻辑，前端只消费RESTful API
月份参数化：所有API支持 month 参数，默认 2026-04
角色权限：总部/区域/店长/专业部门看到不同页面和数据范围
移动端适配：店长页面优先移动端，其他页面桌面端为主
数据安全：JWT认证，敏感数据脱敏，不暴露数据库连接信息

21 KiB Raw Blame History Unescape Escape