电商增长复盘系统

面向电商运营、店长、推广负责人和老板的经营复盘与增长诊断平台。系统覆盖数据上传、字段映射、清洗入库、指标计算、GMV/GSV 归因、异常诊断、行动清单和复盘报告。

技术栈

• Next.js App Router + React + TypeScript
• Tailwind CSS + Recharts + lucide-react
• Next.js Route Handlers
• Prisma ORM + PostgreSQL
• xlsx / csv 文件解析
• JWT Cookie 登录态

本地启动

1. 安装依赖

npm install

2. 配置环境变量

copy .env.example .env

修改 .env 中的 DATABASE_URL、JWT_SECRET、UPLOAD_DIR。

3. 初始化数据库

npm run prisma:generate
npm run prisma:migrate
npm run seed

默认管理员：

• email: admin@example.com
• password: 123456

4. 启动开发服务

npm run dev

访问 http://localhost:3001。

常用脚本

npm run dev
npm run build
npm run typecheck
npm run predeploy:check
npm run start
npm run prisma:generate
npm run prisma:migrate
npm run prisma:deploy
npm run prisma:studio
npm run seed

GitHub 同步

项目已配置 .gitignore，不会提交 .env、.next、node_modules、日志和上传文件。uploads/.gitkeep 会保留目录结构。

首次推送：

git init
git add .
git commit -m "init ecommerce review system"
git branch -M main
git remote add origin https://github.com/你的用户名/ecommerce-review-system.git
git push -u origin main

服务器更新：

git pull origin main
npm install
npm run prisma:generate
npm run prisma:deploy
npm run build
pm2 restart ecommerce-review-system

日常更新：

git pull origin main
npm run build
pm2 restart ecommerce-review-system --update-env

项目结构

• app：页面和 API Route Handlers
• components：布局、驾驶舱和通用组件
• lib/analysis：指标比较、归因、诊断、报告构建
• lib/upload：文件解析
• lib/auth：密码 hash 与 JWT session
• prisma：数据库 schema 和 seed
• uploads：本地上传目录占位

MVP 状态

当前版本已经包含可运行的工程骨架、核心页面、demo ReportSchema、主要 API、Prisma 数据模型和 seed。上传接口支持保存文件、解析 Excel / CSV、字段映射、确认入库，并可从数据库聚合生成复盘报告。

示例上传文件

sample-data 目录提供了几份可直接上传的 CSV：

• sample-data/shop-current.csv
• sample-data/shop-previous.csv
• sample-data/product-current.csv
• sample-data/promotion-current.csv

推荐验证顺序：先上传本期店铺数据，再上传同期店铺数据，随后上传商品和推广数据，最后到报告中心生成复盘报告。上传页支持按表头自动识别报表类型，也可以手动指定。

报告导出当前提供 HTML 和 ReportSchema JSON。HTML 可用浏览器打印为 PDF；服务端原生 PDF 渲染可在后续接入 Playwright。

MVP 验证流程

1. 使用 admin@example.com / 123456 登录。
2. 在系统设置中确认或新增店铺。
3. 到数据上传页上传 sample-data/shop-current.csv，上传模式选择“本期数据”，确认字段映射后入库。
4. 上传 sample-data/shop-previous.csv，上传模式选择“同期数据”，确认入库。
5. 上传 sample-data/product-current.csv 和 sample-data/promotion-current.csv。
6. 到报告中心生成复盘报告。
7. 在报告详情页查看归因、商品四象限、异常中心和行动清单，并可导出 HTML / JSON。
8. 在数据管理页查看上传批次详情，必要时重新清洗或删除错误批次。

部署前检查

部署前建议执行：

npm run typecheck
npm run predeploy:check
npm run build

启动后访问：

/api/health

健康检查会验证数据库连接，并返回上传目录路径。

登录后台后也可以访问：

/settings/deployment

该页面会展示环境变量状态、健康检查入口和部署测试清单。

PM2 部署可使用根目录的 ecosystem.config.js：

pm2 start ecosystem.config.js
pm2 save