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

> 基于现有 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认证，敏感数据脱敏，不暴露数据库连接信息