freedak/SBrainCO
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d373fb5f0cbcc9d1e504ca064345ebba65b8ee79
SBrainCO/docs/智脑实施方法论/13-技术参考-通用方法论与避坑指南.md
T

5.2 KiB
Raw Blame History

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. 不要跳过数据库备份：部署前必须备份
Reference in New Issue View Git Blame Copy Permalink