重构智脑实施方法论：引入FDE模式，八步工作法，适配中国连锁经营企业国情

2026-08-12 11:32:51 +08:00
parent c2a9e27e49
commit 64d2cd8043
16 changed files with 5001 additions and 20 deletions
@@ -0,0 +1,71 @@
+# 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` 常量，避免新月份无数据时空白