docs:提交项目文档
This commit is contained in:
hailin
298
README.md
298
README.md
@@ -1,73 +1,249 @@
|
|||||||
# React + TypeScript + Vite
|
# 数据分析报告生成应用
|
||||||
|
|
||||||
This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
|
一个基于 React、TypeScript 和 Vite 的数据分析报告生成应用，用于导入 Excel 业务数据、渲染多页中文数据报告，并导出为 PDF 文件。项目包含前端报告页面、Excel 模板生成与解析、ECharts 数据可视化，以及基于 Puppeteer 的服务端 PDF 生成能力。
|
||||||
|
|
||||||
Currently, two official plugins are available:
|
## 功能概览
|
||||||
|
|
||||||
- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
|
- 多页中文数据报告展示
|
||||||
- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
|
- Excel 模板下载与数据导入
|
||||||
|
- 区域地图、漏斗图、旭日图、柱状对比图等数据可视化
|
||||||
|
- 浏览器端报告预览
|
||||||
|
- 服务端 PDF 导出
|
||||||
|
- 默认演示数据兜底
|
||||||
|
- 支持局域网访问与 Vite API 代理
|
||||||
|
|
||||||
## React Compiler
|
## 技术栈
|
||||||
|
|
||||||
The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
|
- React 19
|
||||||
|
- TypeScript
|
||||||
|
- Vite
|
||||||
|
- Tailwind CSS
|
||||||
|
- ECharts
|
||||||
|
- xlsx
|
||||||
|
- html2pdf.js
|
||||||
|
- Express
|
||||||
|
- Puppeteer
|
||||||
|
|
||||||
## Expanding the ESLint configuration
|
## 项目结构
|
||||||
|
|
||||||
If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
|
```text
|
||||||
|
.
|
||||||
```js
|
├── src/
|
||||||
export default defineConfig([
|
│ ├── App.tsx # 前端主应用入口，负责导入、预览和导出操作
|
||||||
globalIgnores(['dist']),
|
│ ├── main.tsx # React 挂载入口
|
||||||
{
|
│ ├── components/ # 报告页面与图表组件
|
||||||
files: ['**/*.{ts,tsx}'],
|
│ │ ├── CoverPage.tsx # 封面页
|
||||||
extends: [
|
│ │ ├── ContentPage.tsx # 通用内容页容器
|
||||||
// Other configs...
|
│ │ ├── Page02Industry.tsx # 地区采集与地图页
|
||||||
|
│ │ ├── Page03Duration.tsx # 采集时长与漏损页
|
||||||
// Remove tseslint.configs.recommended and replace with this
|
│ │ ├── Page04Portrait.tsx # 企业画像页
|
||||||
tseslint.configs.recommendedTypeChecked,
|
│ │ ├── Page05Risk.tsx # 风险指标页
|
||||||
// Alternatively, use this for stricter rules
|
│ │ ├── Page06ExportTax.tsx # 出口退税分布页
|
||||||
tseslint.configs.strictTypeChecked,
|
│ │ ├── Page07Association.tsx # 关联企业分布页
|
||||||
// Optionally, add this for stylistic rules
|
│ │ ├── BackCover.tsx # 风险扫描与封底页
|
||||||
tseslint.configs.stylisticTypeChecked,
|
│ │ └── ChinaMap.tsx # 中国地图组件
|
||||||
|
│ ├── data/
|
||||||
// Other configs...
|
│ │ └── defaultData.ts # 默认报告数据
|
||||||
],
|
│ ├── types/
|
||||||
languageOptions: {
|
│ │ └── data.ts # 报告数据类型定义
|
||||||
parserOptions: {
|
│ ├── utils/
|
||||||
project: ['./tsconfig.node.json', './tsconfig.app.json'],
|
│ │ └── excelUtils.ts # Excel 模板生成与导入解析
|
||||||
tsconfigRootDir: import.meta.dirname,
|
│ ├── assets/
|
||||||
},
|
│ │ ├── china.json # 中国地图 GeoJSON
|
||||||
// other options...
|
│ │ └── images/ # 报告使用的图片资源
|
||||||
},
|
│ ├── constants.ts # 静态资源与报告常量
|
||||||
},
|
│ └── index.css # 全局样式与打印样式
|
||||||
])
|
├── server/
|
||||||
|
│ ├── src/index.js # PDF 生成服务
|
||||||
|
│ ├── package.json # 服务端依赖
|
||||||
|
│ └── package-lock.json
|
||||||
|
├── public/ # Vite 静态资源目录
|
||||||
|
├── tools/ # 历史辅助工具页面
|
||||||
|
├── index.html # Vite HTML 入口
|
||||||
|
├── start.sh # 一键启动前端与 PDF 服务
|
||||||
|
├── vite.config.ts # Vite 配置与 API 代理
|
||||||
|
├── tailwind.config.js # Tailwind 配置
|
||||||
|
├── package.json # 前端依赖与脚本
|
||||||
|
└── README.md
|
||||||
```
|
```
|
||||||
|
|
||||||
You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
|
## 环境要求
|
||||||
|
|
||||||
```js
|
- Node.js 18 或更高版本
|
||||||
// eslint.config.js
|
- npm
|
||||||
import reactX from 'eslint-plugin-react-x'
|
- 本地需允许 Puppeteer 启动 Chromium
|
||||||
import reactDom from 'eslint-plugin-react-dom'
|
|
||||||
|
|
||||||
export default defineConfig([
|
## 安装依赖
|
||||||
globalIgnores(['dist']),
|
|
||||||
{
|
安装前端依赖：
|
||||||
files: ['**/*.{ts,tsx}'],
|
|
||||||
extends: [
|
```bash
|
||||||
// Other configs...
|
npm install
|
||||||
// Enable lint rules for React
|
|
||||||
reactX.configs['recommended-typescript'],
|
|
||||||
// Enable lint rules for React DOM
|
|
||||||
reactDom.configs.recommended,
|
|
||||||
],
|
|
||||||
languageOptions: {
|
|
||||||
parserOptions: {
|
|
||||||
project: ['./tsconfig.node.json', './tsconfig.app.json'],
|
|
||||||
tsconfigRootDir: import.meta.dirname,
|
|
||||||
},
|
|
||||||
// other options...
|
|
||||||
},
|
|
||||||
},
|
|
||||||
])
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
安装服务端依赖：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd server
|
||||||
|
npm install
|
||||||
|
cd ..
|
||||||
|
```
|
||||||
|
|
||||||
|
## 启动项目
|
||||||
|
|
||||||
|
推荐使用一键启动脚本：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
./start.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
脚本会执行以下操作：
|
||||||
|
|
||||||
|
- 清理 `3002` 和 `5173` 端口上的旧进程
|
||||||
|
- 检查并安装前端依赖
|
||||||
|
- 检查并安装服务端依赖
|
||||||
|
- 启动 PDF 生成服务
|
||||||
|
- 启动 Vite 开发服务器
|
||||||
|
|
||||||
|
启动后访问：
|
||||||
|
|
||||||
|
```text
|
||||||
|
前端应用：http://localhost:5173
|
||||||
|
PDF 服务：http://localhost:3002
|
||||||
|
```
|
||||||
|
|
||||||
|
## 手动启动
|
||||||
|
|
||||||
|
启动 PDF 服务：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd server
|
||||||
|
npm start
|
||||||
|
```
|
||||||
|
|
||||||
|
另开一个终端启动前端：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run dev
|
||||||
|
```
|
||||||
|
|
||||||
|
前端请求 `/api/generate-pdf` 会通过 Vite 代理转发到 `http://localhost:3002`。
|
||||||
|
|
||||||
|
## 数据导入流程
|
||||||
|
|
||||||
|
应用内点击“数据导入”后，可以下载标准 Excel 模板并上传填充后的文件。解析逻辑位于 `src/utils/excelUtils.ts`。
|
||||||
|
|
||||||
|
模板包含以下 Sheet：
|
||||||
|
|
||||||
|
| Sheet 名称 | 用途 |
|
||||||
|
| --- | --- |
|
||||||
|
| 基础信息 | 企业名称、核心指标、画像描述 |
|
||||||
|
| 地图展示 | 省份采集数据 |
|
||||||
|
| 地区统计 | 地区采集数量、转换率、成功率、采集时长 |
|
||||||
|
| 时长分布 | 各地区采集时长区间分布 |
|
||||||
|
| 页面漏损 | 采集流程漏斗数据 |
|
||||||
|
| 企业全景洞察 | 全量客户行业画像 |
|
||||||
|
| 劣质客户洞察 | 风险客户行业画像 |
|
||||||
|
| 优质客户洞察 | 优质客户行业画像 |
|
||||||
|
| 风险占比 | 发票风险、高新技术、进出口、预缴税款指标 |
|
||||||
|
| 出口退税分布 | 出口免抵退税与出口退税金额分布 |
|
||||||
|
| 关联企业分布 | 登录人和法定代表人关联企业数量分布 |
|
||||||
|
| 风险扫描分布 | 企业风险扫描结果分布 |
|
||||||
|
| 图表描述 | 图表说明文案 |
|
||||||
|
|
||||||
|
导入失败时，优先检查：
|
||||||
|
|
||||||
|
- Sheet 名称是否被修改
|
||||||
|
- 表头是否与模板一致
|
||||||
|
- 百分比字段是否使用模板格式
|
||||||
|
- 指标类型字段是否保留原值
|
||||||
|
|
||||||
|
## PDF 导出流程
|
||||||
|
|
||||||
|
当前主流程使用服务端导出：
|
||||||
|
|
||||||
|
1. 前端点击“导出 PDF”
|
||||||
|
2. 前端将当前 `reportData` POST 到 `/api/generate-pdf`
|
||||||
|
3. Vite 代理转发到 `server/src/index.js`
|
||||||
|
4. Puppeteer 打开前端页面并追加 `?print=true`
|
||||||
|
5. 前端通过 `window.loadServerData` 接收服务端注入的数据
|
||||||
|
6. 前端等待图表渲染完成并设置 `window.isReportReady = true`
|
||||||
|
7. Puppeteer 调用 `page.pdf()` 生成 PDF 并返回给浏览器下载
|
||||||
|
|
||||||
|
## 常用命令
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run dev
|
||||||
|
```
|
||||||
|
|
||||||
|
启动 Vite 开发服务器。
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run build
|
||||||
|
```
|
||||||
|
|
||||||
|
执行 TypeScript 编译检查并构建生产产物。
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run preview
|
||||||
|
```
|
||||||
|
|
||||||
|
预览生产构建结果。
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run lint
|
||||||
|
```
|
||||||
|
|
||||||
|
运行 ESLint。
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx tsc --noEmit
|
||||||
|
```
|
||||||
|
|
||||||
|
只执行 TypeScript 类型检查。
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd server && npm start
|
||||||
|
```
|
||||||
|
|
||||||
|
启动 PDF 生成服务。
|
||||||
|
|
||||||
|
## 开发说明
|
||||||
|
|
||||||
|
- 主入口是 `src/App.tsx`，不是 `src/App-fixed.tsx`
|
||||||
|
- 报告数据的完整结构定义在 `src/types/data.ts`
|
||||||
|
- 默认数据在 `src/data/defaultData.ts`
|
||||||
|
- Excel 导入和模板生成逻辑集中在 `src/utils/excelUtils.ts`
|
||||||
|
- PDF 服务依赖前端页面的 `window.loadServerData` 和 `window.isReportReady`
|
||||||
|
- 打印与 PDF 相关样式主要在 `src/index.css`
|
||||||
|
- 报告图片资源通过 `src/constants.ts` 统一导出
|
||||||
|
|
||||||
|
|
||||||
|
## 常见问题
|
||||||
|
|
||||||
|
### 点击导出 PDF 失败
|
||||||
|
|
||||||
|
确认 PDF 服务已启动：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl http://localhost:3002
|
||||||
|
```
|
||||||
|
|
||||||
|
如果服务未启动，执行：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd server
|
||||||
|
npm start
|
||||||
|
```
|
||||||
|
|
||||||
|
### Excel 上传后数据没有变化
|
||||||
|
|
||||||
|
确认使用的是应用内下载的模板，并检查 Sheet 名称和表头是否被修改。
|
||||||
|
|
||||||
|
### 局域网无法访问
|
||||||
|
|
||||||
|
确认防火墙允许访问 `5173` 和 `3002` 端口。Vite 已配置 `host: '0.0.0.0'`，服务端也监听 `0.0.0.0`。
|
||||||
|
|
||||||
|
### PDF 中图表显示异常
|
||||||
|
|
||||||
|
服务端导出会等待 `window.isReportReady`。如果新增图表，请确保数据变化后有足够的渲染等待时间，且图表容器尺寸稳定。
|
||||||
|
|||||||
Reference in New Issue
Block a user