freedakgmail
c2a9e27e49
文档: - 01-项目概述与架构: 技术架构、数据流、部署拓扑 - 02-数据接入与治理: 原始数据导入、物化视图、门店名映射 - 03-指标体系与API开发: 指标分层、SQL模式、常见陷阱 - 04-前端页面开发: 组件规范、页面模板、月份参数管理 - 05-部署与运维: 部署脚本、FRP隧道、PM2、备份 - 06-调试排查手册: 问题分类、8个实际案例、工具速查 - 07-通用方法论: 核心原则、实施阶段、快速复制Checklist 修复: - situational-awareness.ts: salary_month→salary_period, 日期格式改中文 - 客流-人力匹配: 改用attendance_records打卡数据解析在岗人数 - 客流数据除以30天对齐日均
162 lines
5.1 KiB
Markdown
162 lines
5.1 KiB
Markdown
# 07 · 通用方法论
|
||
|
||
> 从智脑项目实践中提炼的核心原则和可复制方法论，适用于类似的连锁企业数据产品建设。
|
||
|
||
## 1. 核心原则
|
||
|
||
### 1.1 数据先行
|
||
|
||
- **先摸清数据再写代码**：在开发任何API前，先用psql直查数据库，了解表结构、数据范围、数据质量
|
||
- **物化视图是核心**：千万级原始表不要直接查，必须通过物化视图预聚合
|
||
- **验证闭环**：每个API开发完成后，必须用curl + psql双向验证数据一致性
|
||
|
||
### 1.2 渐进式修复
|
||
|
||
- **先跑通再优化**：遇到列名不存在，先用 `SELECT *` 跑通，再逐步修正
|
||
- **最小改动原则**：只改出问题的那行，不重构无关代码
|
||
- **保留容错**：不确定的查询用 try-catch 包裹，返回空数组而非报错
|
||
|
||
### 1.3 统一约定
|
||
|
||
- **默认参数集中管理**：`DEFAULT_MONTH` 一处定义，全局引用
|
||
- **日期格式统一**：后端用 `to_char` 适配各种格式，前端用 `substring(0,10)` 处理ISO日期
|
||
- **门店名映射集中管理**：维护 `store_name_mapping` 表，代码中统一查找模式
|
||
|
||
## 2. 项目实施阶段
|
||
|
||
### 阶段一：数据接入（1-2周）
|
||
|
||
```
|
||
1. 接收原始数据文件（Excel/CSV）
|
||
2. 设计导入脚本，写入原始表
|
||
3. 建立字段映射文档（c001~c200 → 业务含义）
|
||
4. 创建物化视图（预聚合）
|
||
5. 数据质量校验（范围、完整性、一致性）
|
||
6. 建立门店名映射表
|
||
```
|
||
|
||
**关键交付物**：
|
||
- 原始表 + 物化视图
|
||
- 字段映射文档
|
||
- 门店名映射表
|
||
- 数据质量报告
|
||
|
||
### 阶段二：后端API（2-3周）
|
||
|
||
```
|
||
1. 设计API路由结构（按业务模块拆分）
|
||
2. 实现核心查询（SELECT * 先跑通）
|
||
3. 添加分页、排序、筛选
|
||
4. 添加数据权限（getDataScope）
|
||
5. curl + psql 双向验证
|
||
6. 修复SQL陷阱（schema前缀、列名、日期格式）
|
||
```
|
||
|
||
**关键检查点**：
|
||
- [ ] 每个API的 success=true
|
||
- [ ] 返回数据条数与直查数据库一致
|
||
- [ ] 聚合金额与数据库一致
|
||
- [ ] 无数据时返回空数组而非报错
|
||
|
||
### 阶段三：前端页面（2-3周）
|
||
|
||
```
|
||
1. 确定页面结构（参考典型页面模板）
|
||
2. 实现 MetricCard 概览行
|
||
3. 实现图表区域（Recharts）
|
||
4. 实现 FilterableTable 明细
|
||
5. 联调API
|
||
6. 处理空状态和加载状态
|
||
```
|
||
|
||
**关键检查点**：
|
||
- [ ] 月份选择器工作正常
|
||
- [ ] 图表数据与API返回一致
|
||
- [ ] 表格筛选、排序正常
|
||
- [ ] 空状态显示"暂无数据"
|
||
|
||
### 阶段四：部署上线（1天）
|
||
|
||
```
|
||
1. 数据库备份
|
||
2. Git commit + push
|
||
3. 执行 deploy.sh
|
||
4. 验证线上API
|
||
5. 验证线上页面
|
||
6. 修复线上特有问题
|
||
```
|
||
|
||
## 3. 风险清单
|
||
|
||
| 风险 | 影响 | 预防措施 |
|
||
|------|------|---------|
|
||
| 物化视图stale | 数据不一致 | 定期刷新，重建后验证 |
|
||
| 门店名不一致 | 部分门店无数据 | 维护映射表，代码中统一查找 |
|
||
| 日期格式差异 | 查询返回0条 | 先查实际格式再写SQL |
|
||
| Schema前缀混用 | API报错 | 统一查pg_matviews确认 |
|
||
| 默认月份超出数据范围 | 页面空白 | DEFAULT_MONTH设为最新有数据月份 |
|
||
| FRP隧道断开 | 线上API不可用 | launchd自启 + 监控 |
|
||
| 月度vs日均未对齐 | 数值异常大 | 统一时间维度（都除以30天） |
|
||
|
||
## 4. 快速复制Checklist
|
||
|
||
### 4.1 新项目启动
|
||
|
||
- [ ] 确认数据源（Excel/CSV/API）
|
||
- [ ] 确认数据库环境（本地/云）
|
||
- [ ] 确认部署环境（服务器/域名）
|
||
- [ ] 确认用户角色和权限
|
||
|
||
### 4.2 数据层
|
||
|
||
- [ ] 原始表创建 + 导入脚本
|
||
- [ ] 字段映射文档
|
||
- [ ] 物化视图创建
|
||
- [ ] 门店名映射表
|
||
- [ ] 数据质量校验报告
|
||
|
||
### 4.3 API层
|
||
|
||
- [ ] 路由文件按模块拆分
|
||
- [ ] 通用工具函数（parseMonth, parsePagination, getDataScope）
|
||
- [ ] 每个API curl验证通过
|
||
- [ ] 错误处理（sendError返回明确信息）
|
||
|
||
### 4.4 前端层
|
||
|
||
- [ ] useMonthParam hook
|
||
- [ ] 典型页面模板
|
||
- [ ] 组件库（MetricCard, FilterableTable等）
|
||
- [ ] 空状态处理
|
||
|
||
### 4.5 部署
|
||
|
||
- [ ] deploy.sh 脚本
|
||
- [ ] FRP隧道配置（如需）
|
||
- [ ] PM2进程配置
|
||
- [ ] Nginx配置
|
||
- [ ] 数据库备份脚本
|
||
|
||
## 5. 技术选型建议
|
||
|
||
| 层面 | 推荐 | 理由 |
|
||
|------|------|------|
|
||
| 数据库 | PostgreSQL | 物化视图、窗口函数、丰富的数据类型 |
|
||
| 后端 | Express + TypeScript | 轻量、灵活、类型安全 |
|
||
| 前端 | React + Vite | 生态成熟、构建快 |
|
||
| 图表 | Recharts | React原生、API简洁 |
|
||
| 数据请求 | @tanstack/react-query | 缓存、重试、loading状态 |
|
||
| 进程管理 | PM2 | 自动重启、日志管理 |
|
||
| 隧道 | FRP | 穿透内网、稳定可靠 |
|
||
|
||
## 6. 避坑指南
|
||
|
||
1. **不要硬编码列名**：用 `SELECT *` 或先查 `information_schema.columns` 确认
|
||
2. **不要假设日期格式**：先 `SELECT DISTINCT` 看实际值
|
||
3. **不要假设schema**：先查 `pg_matviews` 确认
|
||
4. **不要用当前月份做默认值**：用有数据的最新月份
|
||
5. **不要忽略物化视图刷新**：数据更新后必须 `REFRESH MATERIALIZED VIEW`
|
||
6. **不要在代码中拼接SQL**：始终用参数化查询
|
||
7. **不要引入新UI库**：复用现有组件，保持一致性
|
||
8. **不要跳过数据库备份**：部署前必须备份
|