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

2026-07-26 22:48:08 +08:00
commit a7874d79b5
67 changed files with 14391 additions and 0 deletions
@@ -0,0 +1,521 @@
+# 连锁餐饮数字化运营管理体系 — 技术架构方案与实施计划
+
+> 基于现有 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 需新建的表和视图
+
+#### 任务闭环表（第一阶段核心）
+
+```sql
+-- 门店整改任务表
+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` 固定视图）
+
+```sql
+-- 门店月度汇总（按 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 响应格式
+
+```typescript
+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 | 店长页面、任务管理页面 | 任务自动生成并关联门店 |
+
+**第一阶段交付物**：
+1. 总部驾驶舱（公司概览 + 门店分级 + 下钻）
+2. 区域经理页面（门店红黄绿 + 任务跟进）
+3. 店长页面（昨日经营卡 + 今日待办）
+4. 任务闭环系统（自动分级 → 生成任务 → 状态更新 → 验收）
+5. 门店详情页（全维度指标下钻）
+
+**验收标准**：
+- 门店任务有责任人、有截止日、有结果
+- P0/P1门店问题可以下钻到具体指标和原始明细
+- 所有指标可按月份、门店筛选
+
+### 第二阶段：31-90天 — 补齐成本和利润主链路
+
+| 模块 | 任务 |
+|---|---|
+| 数据层 | 建设标准主数据(dim_store/dim_sku/dim_material等) |
+| 数据层 | 将 `_april` 固定视图改为通用月度模型 |
+| 数据层 | 建立周趋势、同比、环比和整改前后对照 |
+| 后端 | 通用月度参数化API |
+| 前端 | 趋势对比页面、整改前后对照 |
+| 前端 | 专业部门页面（商品/会员/财务/供应链/信息） |
+| 前端 | 标杆分析页面与经验推广跟踪 |
+
+**第二阶段交付物**：
+1. 商品部页面（SKU ABC + 长尾治理 + 搭售分析）
+2. 会员部页面（复购漏斗 + 沉睡召回 + 活动贡献）
+3. 财务页面（理论vs实际成本 + 平台损益 + 异常优惠）
+4. 供应链页面（库存效率 + 异常货品 + 成本对标）
+5. 信息部页面（数据质量监控）
+6. 月度参数化模型（支持任意月份切换）
+7. 趋势对比和整改前后对照
+
+### 第三阶段：3-6个月 — 预测和精细化运营
+
+- 餐段销量预测、备货建议
+- 排班建议
+- 会员分层、流失预警、自动召回
+- SKU新品准入和旧品退出机制
+- 供应商评价
+
+---
+
+## 八、开发环境与启动命令
+
+### 8.1 环境要求
+
+- Node.js >= 18
+- PostgreSQL 15（已有）
+- npm 或 pnpm
+
+### 8.2 环境变量
+
+```env
+# 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 启动命令
+
+```bash
+# 安装依赖
+cd server && npm install
+cd ../client && npm install
+
+# 开发模式启动
+cd server && npm run dev    # 后端 http://localhost:3001
+cd client && npm run dev    # 前端 http://localhost:5173
+```
+
+---
+
+## 九、关键约束与注意事项
+
+1. **不修改现有SQL和视图**：所有现有分析视图保持不动，后端API直接查询
+2. **不修改原始数据表**：`bill_records`、`dish_sales_details`等保持原样
+3. **新增表放在 `analytics` schema**：与现有分析对象统一管理
+4. **API不暴露SQL**：后端封装查询逻辑，前端只消费RESTful API
+5. **月份参数化**：所有API支持 `month` 参数，默认 `2026-04`
+6. **角色权限**：总部/区域/店长/专业部门看到不同页面和数据范围
+7. **移动端适配**：店长页面优先移动端，其他页面桌面端为主
+8. **数据安全**：JWT认证，敏感数据脱敏，不暴露数据库连接信息