【web应用】Excel 项目数据自动化分析系统（AI 驱动分析）详细设计与部署指南（附源代码）

本项目站内资源源代码下载地址

1. 概述

1.1 说明

Excel 项目数据自动化分析系统是一套面向企业项目数据处理场景的全栈 Web 应用。用户上传多个 Excel 文件后，系统自动完成数据合并、清洗、去重、类型转换与分组聚合，并支持 AI 驱动的深度数据洞察，最终一键导出格式化 Excel 报表。将数小时的手工处理工作压缩至数分钟。

1.2 核心能力

1.3 系统边界

• 输入: 用户上传的一个或多个 Excel 文件（.xlsx/.xls/.xlsm），或系统自动生成的示例数据
• 处理: 服务端通过 Python 子进程调用 pandas / openpyxl 执行数据管道
• 输出: 清洗后的数据预览、分组聚合图表、AI 分析报告、可下载的 Excel 报表
• 存储: SQLite 数据库（Prisma ORM），本地文件系统存储上传文件和导出结果

2. 架构设计

2.1 整体架构

┌──────────────────────────────────────────────────────────┐ │ 用户浏览器 │ │ ┌──────────┬──────────┬──────────┬──────────┬─────────┐ │ │ │ 上传页面 │ 配置编辑 │ AI 配置 │ 结果展示 │ 历史记录 │ │ │ └──────────┴──────────┴──────────┴──────────┴─────────┘ │ └───────────────────────┬──────────────────────────────────┘ │ HTTP / REST API ┌───────────────────────▼──────────────────────────────────┐ │ Caddy (反向代理 :81) │ │ reverse_proxy → localhost:3000 │ └───────────────────────┬──────────────────────────────────┘ │ ┌───────────────────────▼──────────────────────────────────┐ │ Next.js 16 Server (Bun Runtime) │ │ ┌────────────────────────────────────────────────────┐ │ │ │ API Routes │ │ │ │ /api/upload /api/process /api/config │ │ │ │ /api/jobs /api/export /api/ai/config │ │ │ │ /api/ai/analyze │ │ │ └────────────────────┬───────────────────────────────┘ │ │ │ │ │ ┌────────────────────▼───────────────────────────────┐ │ │ │ Python Processor │ │ │ │ scripts/processor.py (child_process.execFile) │ │ │ │ pandas + openpyxl 数据处理 │ │ │ └────────────────────┬───────────────────────────────┘ │ │ │ │ │ ┌────────────────────▼───────────────────────────────┐ │ │ │ Prisma Client + SQLite │ │ │ │ db/custom.db │ │ │ └────────────────────────────────────────────────────┘ │ └──────────────────────────────────────────────────────────┘

2.2 请求处理流程

用户上传 Excel 文件 → POST /api/upload → 保存至 upload/{uuid}/ 目录 → 前端跳转至「处理配置」页 用户配置处理规则，点击「开始处理」 → POST /api/process { uploadDir, configOverride } → 创建 ProcessingJob (status=processing) → 立即返回 jobId 后台异步执行 → child_process.execFile → python3 scripts/processor.py → 输出 JSON 结果 → 更新 ProcessingJob (status=completed/failed) → 写入 ProcessingResult 前端轮询 (2s 间隔) → GET /api/jobs?id={jobId} → 展示 stats、chart、data tables 用户触发 AI 分析 → POST /api/ai/analyze { jobId, analysisType } → LLM 生成分析报告 → 写入 ProcessingResult.aiAnalysis → 渲染 Markdown 用户点击导出 → GET /api/export/{jobId} → 返回 result_{jobId}.xlsx

3. 技术栈

3.1 前端

3.2 后端（API Routes）

3.3 数据处理管道

3.4 运行环境

4. 数据库设计

本系统使用 SQLite 数据库，通过 Prisma ORM 进行访问。数据库文件路径为db/custom.db。

4.1 ER 图

┌──────────────────┐ ┌──────────────────┐ │ ProcessingConfig │ │ AIConfig │ │──────────────────│ │──────────────────│ │ id (PK) │ │ id (PK) │ │ name │ │ name │ │ fillnaRules │ │ url │ │ dedupColumns │ │ apiKey │ │ typeMappings │ │ modelId │ │ groupbyColumn │ │ enabled │ │ groupbyAgg │ │ systemPrompt │ │ isDefault │ │ isDefault │ │ createdAt │ │ createdAt │ │ updatedAt │ │ updatedAt │ └───────┬──────────┘ └──────────────────┘ │ 1:N │ ┌───────▼──────────┐ │ ProcessingJob │ │──────────────────│ │ id (PK) │ │ configFileId (FK)│ │ status │ │ fileNames │ │ totalRows │ │ totalColumns │ │ cleanedRows │ │ dedupedRows │ │ resultSummary │ │ errorMessage │ │ createdAt │ │ updatedAt │ └───────┬──────────┘ │ 1:N │ ┌───────▼──────────┐ │ ProcessingResult │ │──────────────────│ │ id (PK) │ │ jobId (FK) │ │ sheetName │ │ rawData │ │ cleanedData │ │ aggData │ │ aiAnalysis │ │ createdAt │ └──────────────────┘

4.2 模型说明

ProcessingConfig（处理配置）

存储用户自定义的数据处理规则，支持多套配置并存，isDefault 标记默认配置。

ProcessingJob（处理任务）

记录每次数据处理任务的执行状态与统计信息。

ProcessingResult（处理结果）

保存单次处理的数据预览和 AI 分析内容，最多存储 200 行预览数据。

AIConfig（AI 配置）

存储 AI 服务的连接信息和行为参数。

JSON 字段采用 String 存储，在 API 层通过JSON.parse/JSON.stringify进行转换。这种设计兼容了 SQLite 对 JSON 的原生支持和 Prisma 的序列化需求。

5. API 接口设计

所有接口均位于 Next.js App Router 的/src/app/api/目录下，遵循 RESTful 风格。

5.1 文件上传

POST /api/upload

• Content-Type:multipart/form-data
• 参数:files(File[], 必填)，支持 .xlsx / .xls / .xlsm
• 逻辑: 生成 UUID 子目录 → 写入文件 → 返回目录路径
• 返回:{ success: true, uploadDir, fileNames, message }

POST /api/upload?generate-sample=true

• 参数: 无 Body
• 逻辑: 调用 Pythonprocessor.py --generate-sample生成演示数据
• 返回:{ success: true, uploadDir, fileNames, message }

5.2 数据处理

POST /api/process

• Content-Type:application/json
• 请求体:

{"uploadDir":"string (必填)","configId":"string?","configOverride":{"fillnaRules":{"列名":"填充值"},"dedupColumns":["列名"],"typeMappings":{"列名":"float64|int64|str"},"groupbyColumn":"分组列","groupbyAgg":{"列名":"sum|count|mean|max|min"}}}

• 逻辑:
  1. 解析配置（DB 配置 > configOverride > 内置默认值）
  2. 创建 ProcessingJob（status=processing）
  3. 异步启动 Python 子进程（timeout 120s, maxBuffer 10MB）
  4. 解析 Python 输出的 JSON 结果
  5. 更新 Job 状态和 Result
• 返回:{ success: true, jobId, status: "processing", message }

5.3 处理配置

GET /api/config— 获取所有配置列表，含jobCount

POST /api/config— 创建新配置（支持 isDefault 互斥）

PUT /api/config?id=xxx— 更新指定配置

DELETE /api/config?id=xxx— 删除指定配置

5.4 任务管理

GET /api/jobs— 获取最近任务列表（含结果和配置摘要）

GET /api/jobs?id=xxx— 获取单个任务详情（含完整数据和 AI 分析）

5.5 结果导出

GET /api/export/{jobId}

• 校验：任务存在且 status=completed
• 返回: Excel 二进制流，Content-Type:application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
• 文件名:分析结果_{原文件名}_{日期}.xlsx

5.6 AI 配置

GET /api/ai/config— 获取 AI 配置列表或指定配置（?id=xxx）

POST /api/ai/config— 创建 AI 配置

PUT /api/ai/config?id=xxx— 更新 AI 配置

DELETE /api/ai/config?id=xxx— 删除 AI 配置

5.7 AI 分析

POST /api/ai/analyze

• 请求体:

{"jobId":"string (必填)","analysisType":"comprehensive|quality|trend|risk|suggestion|custom","customQuestion":"string?"}

• 逻辑:
  1. 校验 job 状态（仅 completed 可分析）
  2. 读取启用的 AI 配置
  3. 构建分析上下文（数据概况 + 清洗结果 + 聚合摘要）
  4. 根据 analysisType 生成 system prompt + user prompt
  5. 调用z-ai-web-dev-sdk获取 LLM 响应
  6. 写入ProcessingResult.aiAnalysis
• 返回:{ success: true, analysis: "...", analysisType }

分析类型

6. 前端设计

6.1 页面结构

系统采用单页应用（SPA）布局，顶部固定导航栏，通过 shadcn/ui Tabs 组件切换 5 个功能面板：

┌─────────────────────────────────────────────┐ │ Header: Logo + 系统标题 + 状态徽章 │ │ [上传] [处理配置] [AI配置] [分析结果] [历史]│ ├─────────────────────────────────────────────┤ │ │ │ Tab 内容区（max-w-6xl, 居中） │ │ │ ├─────────────────────────────────────────────┤ │ Footer: 系统信息 + 技术栈标识 │ └─────────────────────────────────────────────┘

6.2 组件树

page.tsx (主页面) ├── FileUpload (上传组件) │ ├── 拖拽上传区域 (Drag & Drop) │ ├── 待上传文件列表 (含大小/格式/删除) │ ├── 上传进度条 │ ├── 已上传文件列表 │ └── 操作按钮（上传/生成示例/开始分析） ├── ConfigEditor (处理配置编辑器) │ ├── 配置名称 + 保存/加载/开始处理 │ ├── 填充缺失值编辑器（动态 key-value） │ ├── 去重规则编辑器（动态列表） │ ├── 类型转换编辑器（列→类型下拉） │ └── 分组汇总编辑器（分组列 + 聚合规则） ├── AIConfigEditor (AI 配置编辑器) │ ├── 启用/禁用状态横幅 │ ├── 连接设置（URL + API Key + Model ID） │ ├── 系统提示词编辑 │ └── 默认配置开关 + 连接测试 ├── ResultsViewer (结果查看器) │ ├── 处理状态展示 │ │ ├── Loading 动画 (处理中) │ │ ├── Error 展示 (失败) │ │ └── Empty 状态 (未选择) │ ├── 统计卡片 (总行数/清洗后/去重/列数) │ ├── 柱状图 (Recharts BarChart) │ ├── AIAnalysisPanel (AI 分析面板) │ │ ├── 分析类型选择（6 种） │ │ ├── 自定义问题输入 │ │ ├── 分析结果 Markdown 渲染 │ │ └── 加载/重新分析状态 │ └── 数据表 Tabs (原始/清洗/汇总) └── HistoryList (历史记录列表) ├── 任务卡片列表 ├── 状态徽章 (pending/processing/completed/failed) ├── 时间戳（相对时间格式） └── 操作按钮（查看结果/导出）

6.3 状态管理（Zustand Store）

使用 Zustand 实现全局状态管理，/src/lib/store.ts包含以下核心状态：

6.4 UI 设计要点

• 配色: 以 Emerald（翠绿）为主色调，Teal 为 AI 相关辅色，各功能区使用差异化色系（Amber=清洗、Violet=转换、Blue=去重、Rose=导出）
• 响应式: 所有组件支持移动端，通过sm:/lg:断点适配
• 暗色模式: 全面支持 Tailwinddark:类
• 交互反馈: Sonner Toast 通知所有操作结果，处理中显示动画加载状态
• 轮询机制: 结果页 2s 间隔轮询，历史页 10s 间隔轮询（仅在有活跃任务时）

7. 数据处理管道

7.1 Python 脚本结构

scripts/processor.py是实现核心数据逻辑的独立 Python 脚本，通过child_process.execFile由 Node.js 端调用。脚本采用命令行参数驱动设计：

python3 processor.py --input-dir ./upload/{uuid}/ --output ./download/result_{jobId}.xlsx --config '{"fillnaRules":{"项目金额":0},"dedupColumns":["项目编号"],...}'

7.2 处理管道步骤

┌─────────────────────────────────────────────┐ │ Step 1: batch_read_excel(input_dir) │ │ - glob 扫描 *.xlsx, *.xls, *.xlsm │ │ - 逐文件读取所有 Sheet │ │ - 添加 __来源文件__, __来源Sheet__ 标记列 │ │ - pd.concat 合并 │ ├─────────────────────────────────────────────┤ │ Step 2: clean_data(df, config) │ │ - fillna: 按 fillnaRules 填充指定列缺失值 │ │ - drop_duplicates: 按 dedupColumns 去重 │ │ - astype: 按 typeMappings 转换列类型 │ │ - 返回 (cleaned_df, stats) │ ├─────────────────────────────────────────────┤ │ Step 3: aggregate_data(df, config) │ │ - groupby(groupbyColumn) │ │ - agg(groupbyAgg) │ │ - 生成分组摘要 │ ├─────────────────────────────────────────────┤ │ Step 4: export_to_excel(output_path, ...) │ │ - Sheet 1: 清洗后数据 │ │ - Sheet 2: 汇总分析 │ │ - Sheet 3: 处理统计 │ │ - openpyxl 美化：表头字体/颜色/边框/冻结/列宽 │ ├─────────────────────────────────────────────┤ │ 输出: JSON 结果到 stdout │ │ { success, stats, summary, preview, columns }│ └─────────────────────────────────────────────┘

7.3 数据转换规则

7.4 错误处理

• 文件读取异常: 打印警告至 stderr，跳过该文件继续处理
• 类型转换异常: 打印警告，继续执行
• 配置 JSON 解析失败: 退出并返回 error 信息
• 整体异常: 通过 traceback 捕获，以结构化 JSON 返回

8. AI 智能分析模块

8.1 集成架构

ResultsViewer (前端) → POST /api/ai/analyze { jobId, analysisType, customQuestion } → 读取 AIConfig (默认/enabled) → 构建分析上下文 (data_stats + config + preview_data) → 构建 Prompt (system + user) → ZAI SDK → LLM API ← Markdown 分析结果 → 写入 ProcessingResult.aiAnalysis → 前端 ReactMarkdown 渲染

8.2 Prompt 设计

System Prompt（用户可自定义覆盖）:

你是一位资深的项目数据分析师，专注于 Excel 项目数据的分析与优化建议。你需要基于提供的数据处理结果，给出专业、可操作的分析结论和调整建议。

分析应包含：

1. 数据质量评估
2. 关键发现
3. 趋势分析
4. 风险提示
5. 优化建议

分析上下文（由buildAnalysisContext构建）:

## 数据处理概况 - 分析文件: [文件名列表] - 原始数据总行数/列数/清洗后行数/删除重复行数 ## 处理配置 { fillnaRules, dedupColumns, typeMappings, groupbyColumn, groupbyAgg } ## 清洗后数据预览 (前10行) [JSON 数据] ## 汇总分析结果 [JSON 聚合数据] ## 处理统计摘要 [JSON 统计信息]

8.3 分析类型 Prompt 映射

9. 构建与部署

9.1 开发环境

前置要求:

• Bun >= 1.3.x
• Python 3.12 + venv
• 系统依赖: 无额外要求

启动步骤:

# 1. 安装 Node.js 依赖buninstall# 2. 生成 Prisma Client 并推送数据库bun run db:push bun run db:generate# 3. 安装 Python 依赖（如首次运行）python3-mvenv .venvsource.venv/bin/activate pipinstallpandas openpyxl --break-system-packages# 4. 启动开发服务器bun run dev# 访问 http://localhost:3000

9.2 生产构建

# 方式一：标准化构建脚本sh.zscripts/build.sh# 方式二：手动构建bun run build

构建脚本流程:

1. bun install— 安装依赖
2. bun run build— Next.js standalone 构建
3. 复制.next/standalone+.next/static+public→next-service-dist/
4. 复制并推送数据库至构建产物
5. 打包为.tar.gz

构建产物结构:

/tmp/build_fullstack_{BUILD_ID}/ ├── next-service-dist/ # Next.js standalone 输出 │ ├── server.js │ ├── .next/static/ │ └── public/ ├── db/ │ └── custom.db # 生产数据库 ├── Caddyfile # 反向代理配置 ├── start.sh # 启动脚本 └── mini-services-start.sh (可选)

9.3 生产部署

启动服务:

# 解压构建包tarxzf build_fullstack_{BUILD_ID}.tar.gz-C/app/cd/app# 启动所有服务（Next.js + Caddy）shstart.sh

start.sh行为:

1. 设置环境变量NODE_ENV=production,PORT=3000,DATABASE_URL
2. 后台启动bun server.js（Next.js standalone）
3. 前台启动caddy run --config Caddyfile（作为主进程）

9.4 反向代理配置（Caddyfile）

:81 { @transform_port_query { query XTransformPort=* } handle @transform_port_query { reverse_proxy localhost:{query.XTransformPort} } handle { reverse_proxy localhost:3000 } }

• 默认将 81 端口请求代理到 localhost:3000
• 支持通过?XTransformPort=xxxx动态转发至其他端口，便于与其他微服务共存

9.5 环境变量

9.6 目录权限与数据持久化

• upload/: 上传文件临时存储，按 UUID 子目录隔离
• download/: 导出 Excel 结果存储，按 jobId 命名
• db/custom.db: SQLite 数据库，需确保读写权限
• 生产部署时upload/和download/建议挂载持久化存储或定期清理

10. 目录结构

project-root/ ├── .env # 环境变量（DATABASE_URL） ├── .gitignore # Git 忽略规则 ├── .zscripts/ # 构建与启动脚本 │ ├── build.sh # 生产构建脚本 │ ├── start.sh # 生产启动脚本 │ ├── dev.sh # 开发环境启动 │ ├── mini-services-build.sh # 微服务构建 │ ├── mini-services-install.sh # 微服务依赖安装 │ └── mini-services-start.sh # 微服务启动 ├── Caddyfile # Caddy 反向代理配置 ├── next.config.ts # Next.js 配置（standalone 输出） ├── package.json # 项目依赖与脚本 ├── tsconfig.json # TypeScript 配置 ├── tailwind.config.ts # Tailwind CSS 配置 ├── components.json # shadcn/ui 配置 ├── bun.lock # Bun 依赖锁文件 ├── eslint.config.mjs # ESLint 配置 ├── postcss.config.mjs # PostCSS 配置 ├── prisma/ │ └── schema.prisma # Prisma 数据模型定义 ├── scripts/ │ └── processor.py # Python 数据处理管道 ├── db/ │ └── custom.db # SQLite 数据库文件 ├── upload/ # 上传文件存储（按 UUID 子目录） ├── download/ # 导出 Excel 结果存储 ├── public/ # 静态资源 │ ├── logo.svg │ └── robots.txt ├── agent-ctx/ # AI Agent 上下文文件 │ ├── 5-backend-api-builder.md │ ├── 7-a-file-upload-component-builder.md │ ├── 7-c-results-viewer-builder.md │ ├── 7-d-history-list-builder.md │ └── 8-ai-config-editor-builder.md ├── src/ │ ├── app/ │ │ ├── layout.tsx # 根布局 │ │ ├── page.tsx # 主页面 │ │ ├── globals.css # 全局样式 │ │ └── api/ │ │ ├── route.ts # 健康检查 │ │ ├── upload/route.ts # 文件上传 API │ │ ├── process/route.ts # 数据处理 API │ │ ├── config/route.ts # 配置 CRUD API │ │ ├── jobs/route.ts # 任务查询 API │ │ ├── export/ │ │ │ └── [jobId]/ │ │ │ └── route.ts # 结果导出 API │ │ └── ai/ │ │ ├── config/ │ │ │ └── route.ts # AI 配置 CRUD API │ │ └── analyze/ │ │ └── route.ts # AI 分析 API │ ├── components/ │ │ ├── file-upload.tsx # 文件上传组件 │ │ ├── config-editor.tsx # 处理配置编辑器 │ │ ├── ai-config-editor.tsx # AI 配置编辑器 │ │ ├── results-viewer.tsx # 结果查看器（含 AI 面板） │ │ ├── history-list.tsx # 历史记录列表 │ │ └── ui/ # shadcn/ui 组件库 │ │ ├── button.tsx, card.tsx, table.tsx, tabs.tsx │ │ ├── input.tsx, select.tsx, textarea.tsx │ │ ├── badge.tsx, progress.tsx, separator.tsx │ │ ├── dialog.tsx, dropdown-menu.tsx │ │ ├── switch.tsx, toggle.tsx │ │ ├── chart.tsx, scroll-area.tsx, accordion.tsx │ │ └── ... (40+ 组件) │ ├── lib/ │ │ ├── db.ts # Prisma Client 单例 │ │ ├── store.ts # Zustand 全局状态 │ │ └── utils.ts # 工具函数 │ └── hooks/ │ ├── use-mobile.ts # 移动端检测 │ └── use-toast.ts # Toast Hook ├── examples/ │ └── websocket/ # WebSocket 示例 │ ├── frontend.tsx │ └── server.ts ├── tool-results/ # 构建工具输出 └── worklog.md # 开发工作记录

附录

A. Python 脚本命令行参考

# 生成示例数据python3 scripts/processor.py --generate-sample --sample-dir ./upload/demo/# 执行数据处理python3 scripts/processor.py\--input-dir ./upload/demo/\--output./download/result.xlsx\--config'{"fillnaRules":{"项目金额":0},"dedupColumns":["项目编号"],"typeMappings":{"项目金额":"float64"},"groupbyColumn":"项目类型","groupbyAgg":{"项目金额":"sum","项目编号":"count"}}'