# 10 · 技术参考：项目概述与架构

## 1. 项目背景

为连锁经营企业（西部马华，100+门店）构建数据分析智脑平台，覆盖：
- **老板驾驶舱**：门店风险评级、营收概览、平台经济性
- **门店分级**：红/黄/绿三色风险评级与明细
- **态势感知**：健康度评分、自动化预警、跨模块关联分析、趋势预测
- **风险明细**：异常账单、零实收、收银员风险
- **智能排班**：客流热力图、排班匹配度、人效对标、考勤预警
- **成本分析**：理论成本vs实际成本、成本方差、菜品级分析
- **会员复购**：会员占比、复购率、营销方案效果
- **SKU分析**：ABC分类、菜品销售结构

## 2. 技术架构

```
┌─────────────────────────────────────────────────┐
│  前端 (React + TypeScript + Vite)                │
│  - Recharts 图表库                               │
│  - @tanstack/react-query 数据请求                │
│  - 自研组件: MetricCard / FilterableTable /      │
│    CollapsibleSection / MonthPicker              │
│  - 部署到 Nginx 静态文件                          │
├─────────────────────────────────────────────────┤
│  后端 (Express + TypeScript)                     │
│  - 路由按模块拆分: data.ts / situational-        │
│    awareness.ts / smart-scheduling.ts /          │
│    cost-analysis.ts / store-expense.ts           │
│  - pg 库直连 PostgreSQL                          │
│  - JWT 认证 + 数据权限 (getDataScope)             │
│  - PM2 进程管理                                   │
├─────────────────────────────────────────────────┤
│  数据库 (PostgreSQL 15)                          │
│  - bill_query: 业务数据 (原始表 + 物化视图)       │
│  - sbrain_admin: 平台管理 (租户/用户/配置)        │
│  - FRP 隧道: 本地5432 → 服务器15432              │
└─────────────────────────────────────────────────┘
```

## 3. 数据流

```
原始Excel/CSV → 导入脚本 → bill_records / salary_detail_records / attendance_records
                                    ↓
                          物化视图层 (mv_*)
                    ┌─────────────┼─────────────┐
                    ↓             ↓             ↓
              mv_bill_hourly  mv_risk_*   mv_store_*_monthly
                    ↓             ↓             ↓
                        后端API (SQL查询)
                              ↓
                        前端Dashboard
```

## 4. 部署拓扑

| 组件 | 位置 | 说明 |
|------|------|------|
| 前端 | 服务器 Nginx | `/var/www/dm.all8ai.top` 静态文件 |
| 后端 | 服务器 PM2 | `sbrain-server` 进程，端口9333 |
| 数据库 | 本地 PostgreSQL | 通过FRP隧道暴露到服务器15432 |
| 域名 | dm.all8ai.top | Nginx反向代理 `/api/` → 后端 |

## 5. 关键设计决策

1. **物化视图而非实时查询**：原始表千万级，物化视图预聚合保证API响应速度
2. **FRP隧道而非云数据库**：数据安全要求高，数据库留在本地，通过隧道供服务器访问
3. **多租户SaaS架构**：`sbrain_admin` 管理租户配置，`tenant_configs` 表驱动数据源连接
4. **数据权限分层**：总部看全部门店、区域经理看本区域、店长看本店
5. **默认月份参数**：前端统一使用 `DEFAULT_MONTH` 常量，避免新月份无数据时空白