SBrainCO/docs/智脑实施方法论/10-技术参考-项目概述与架构.md

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 常量，避免新月份无数据时空白