# 13 · 技术参考：通用方法论与避坑指南

> 从智脑项目实践中提炼的核心原则和可复制方法论，适用于类似的连锁企业数据产品建设。

## 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. **不要跳过数据库备份**：部署前必须备份