系统架构详解

技术栈概览

"技术栈"这个词听起来很酷，它其实就是我们用来搭建这个项目所选择的一整套"工具组合"。就像建房子需要用到起重机、搅拌机、脚手架一样，开发软件也需要不同的工具来各司其职。

什么是前端和后端？

在介绍具体工具之前，我们先来理解一个最重要的概念：前端 (Frontend) 和 后端 (Backend)。

您可以把我们的整个应用想象成一家高级餐厅：

前端：就是您能直接看到的、与之互动的一切。它是餐厅的大堂、菜单、桌椅和为您服务的服务员。在我们的应用里，您在浏览器上看到的所有页面、按钮、图表，都属于前端。它的主要职责是呈现信息和与您交互。
后端：就是您看不到的、支撑餐厅运作的"心脏"——后厨。它负责处理订单（您的请求）、烹饪菜肴（数据分析和 AI 计算）、管理库存（数据库）。在我们的应用里，后端负责处理复杂的业务逻辑、调用 Gemini AI 模型、与 Google Sheets 等外部服务通信，并将最终结果返回给前端。

前端和后端通过一套严格的"点餐系统"（即 API）来沟通，确保服务员（前端）能准确地将您的需求传达给后厨（后端），并将烹饪好的菜肴（结果）完美地呈现给您。

我们项目的前后端代码是完全分离的，这是一种现代化的开发模式，叫做"前后端分离"。它的好处是，餐厅大堂的装修和后厨的设备升级可以独立进行，互不干扰，大大提高了开发和维护的效率。

React：像搭乐高一样构建用户界面

它是什么？ React 是一个由 Facebook (现在叫 Meta) 开发并开源的，目前全球最流行的前端"脚手架"。
它做什么？ 它的核心思想是"组件化"。您可以把整个网页想象成一个巨大的乐高模型，而这个模型是由一个个独立的、可复用的"乐高积木"拼搭而成的。在我们的项目中，一个按钮、一个下拉菜单、一个数据表格，甚至一整张幻灯片预览，都是一个独立的"组件"。
为什么用它？
- 高效开发：我们可以先精心设计好各种基础"积木"（组件），然后在需要的地方像拼乐高一样快速组装，而无需每次都从零开始。
- 轻松维护：如果发现某个按钮不好看，我们只需要修改这个"按钮组件"本身，所有用到它的地方都会自动更新，而不会影响到其他部分。AudienceSignalPage 和 GeoAnalysisPage 等页面能如此相似和统一，正是得益于组件化的高度复用。
- 强大的生态：作为最流行的框架，React 拥有极其丰富的社区和第三方库支持，我们能轻松地找到各种高质量的"乐高零件"（如图表库、UI 库）来丰富我们的应用。

Vite：让我们的开发和浏览飞起来的"引擎"

它是什么？ Vite (读音 /vit/，法语中"快"的意思) 是我们项目选用的前端构建工具和开发服务器。
它做什么？
1. 在开发时：当开发者在编写代码时，Vite 能像一个超高速的"同声传译"，在保存代码的瞬间，就立刻将改动反映在浏览器上，几乎无需等待。这极大地提升了开发体验和效率。
2. 在上线前：当我们需要将项目部署到服务器上时，Vite 会扮演"打包压缩机"的角色。它会将我们写的成百上千个前端代码文件（HTML, CSS, TypeScript）进行优化、压缩和打包，最终生成几个高度优化的静态文件，让用户在浏览器中能以最快的速度加载和访问。
为什么用它？ 就是为了一个字——快。相比传统的构建工具，Vite 在开发时的启动速度和热更新速度都有着数量级的提升，是目前前端开发领域的"当红明星"。

Node.js：让我们的服务器响应请求的"大脑"

它是什么？ Node.js 是一个让 JavaScript 这门语言可以脱离浏览器，直接在服务器上运行的"环境"。
它做什么？ 在我们的项目中，整个后端服务（餐厅的后厨）就是用 Node.js 来驱动的。它负责接收前端发来的请求（点餐）、执行 geminiService.ts 等核心逻辑（烹饪）、并将结果返回给前端。
为什么用它？
- 统一语言：使用 Node.js 意味着我们的前端和后端都使用同一种主要编程语言——JavaScript (及 TypeScript)。这大大降低了独立开发者的学习成本和心智负担，可以更专注于业务逻辑本身，而无需在两种完全不同的语言之间频繁切换。
- 高性能：Node.js 特别擅长处理大量的并发网络请求（同时接待很多桌客人点餐），非常适合构建我们这种与前端频繁交互的 API 服务。

TypeScript：给代码添加"智能提示"的"导航员"

它是什么？ TypeScript 是由微软开发并开源的，可以看作是 JavaScript 的一个"超集"（可以理解为"专业增强版"）。
它做什么？ 它最核心的功能是为 JavaScript 增加了静态类型系统。听起来很复杂，但您可以把它理解成一个极其严格和智能的"语法检查和代码导航员"。
- 提前发现错误：在传统的 JavaScript 中，很多错误（比如把一个数字当成了一段文字来处理）只有在程序实际运行时才会暴露出来。而 TypeScript 在我们写代码的时候，就会像一个严格的副驾一样，实时检查我们的代码，如果发现类型不匹配，会立刻划出红线提示错误。这大大减少了线上 Bug 的数量。
- 智能代码提示：由于 TypeScript 知道每一个变量、每一个函数的"类型"，当我们在写代码时，编辑器就能为我们提供极其精确的智能提示和自动补全。这不仅提升了开发效率，也使得阅读和理解他人的代码变得异常轻松。
为什么用它？ 对于一个需要长期维护和多人协作的项目来说，TypeScript 带来的代码健壮性和可维护性的提升是无价的。它就像是为项目代码建立了一套"活文档"，是保证我们未来能够顺利协作开发的关键基石。

设计语言：从 Semi Design 到 Ant Design

它们是什么？ Semi Design (由字节跳动出品) 和 Ant Design (由蚂蚁集团出品) 是我们项目中使用的两个前端 UI 组件库。
它们做什么？ 它们为我们提供了大量预先设计和开发好的、高质量的 UI 组件（就是我们前面提到的"乐高积木"），例如按钮、表单、表格、弹窗、菜单等。我们无需自己从零开始画按钮、写样式，可以直接使用这些现成的、设计精美且功能强大的组件。
项目现状：
- 根据项目规则，目前已有的三大核心功能（市场机会分析、人群信号分析、受众画像幻灯片）是使用 Semi Design 构建的。
- 为了技术栈的逐步统一和现代化，未来所有新开发的页面，将推荐使用 Ant Design。

这个技术栈的选择，兼顾了开发的效率、代码的健壮性、未来的可扩展性以及与 Google 生态的无缝集成。它是项目在开发过程中经过深思熟虑和不断打磨后的成果，也是我们项目能够稳定、高效运行的坚实地基。

系统架构设计

如果说上一节的"技术栈"是我们用来建房子的"工具和材料"，那么"系统架构"就是我们规划出的"建筑设计图纸"。它描述了各个功能模块是如何被组织和连接起来，共同支撑起整个应用的。

宏观架构图：一张图看懂数据流转

为了让您对项目有一个直观的整体认知，我们先来看一张从用户操作到结果生成的完整数据流转图：

sequenceDiagram
    participant U as 用户 (User)
    participant FE as 前端 (Browser/React)
    participant BE as 后端 (Node.js Server)
    participant GA as Google Apps Script
    participant GS as Google Gemini API
    participant GSuite as Google Workspace (Sheets/Slides)

    U->>FE: 1. 访问网页，使用Google账户登录
    FE->>BE: 2. 发起Google OAuth认证请求
    BE-->>FE: 3. 返回认证Token
    FE-->>U: 4. 登录成功，显示功能主页

    U->>FE: 5. 在页面上填写表单，上传数据文件
    FE->>BE: 6. 将数据和Prompt指令发送到后端API<br>(e.g., /api/gemini/generate)
    
    subgraph 后端处理核心逻辑
        BE->>GS: 7. (核心) 调用Gemini API进行AI分析<br>包含完善的重试和错误处理机制
        GS-->>BE: 8. 返回分析结果 (JSON文本)
    end

    BE-->>FE: 9. 将AI分析结果返回给前端
    FE->>U: 10. (部分功能) 在页面上展示结果<br>如图表、表格

    subgraph (可选) 与Google Workspace集成
        FE->>BE: 11. (部分功能) 发起生成幻灯片/记录日志请求
        BE->>GA: 12. 调用Apps Script API<br>传递数据和用户身份
        GA->>GSuite: 13. 在Google Slides/Sheets中<br>创建幻灯片、插入图片、写入日志
        GSuite-->>GA: 14. 返回操作结果
        GA-->>BE: 15. 返回操作结果
        BE-->>FE: 16. 返回最终结果
    end
    
    FE->>U: 17. 显示最终结果，提供下载/链接

这张图清晰地展示了我们系统的几大核心特点：

前后端分离：用户的浏览器（前端）和我们的服务器（后端）是两个独立的部分，通过 API 进行清晰的通信。
后端作为"智能中枢"：所有核心的 AI 计算和与 Google 服务的集成，都由后端统一处理。这保证了安全性（API 密钥不暴露在前端）和健壮性（后端实现了完善的重试和日志记录）。
深度集成 Google 生态：项目不仅仅是一个独立的网站，它深度整合了 Google 认证、Gemini AI、Google Sheets 和 Google Slides，形成了一个强大的、无缝衔接的 Google Workspace 解决方案。

项目文件结构

一个结构清晰的文件目录，就像一张好的藏宝图，能让开发者快速定位到想要寻找的代码。我们的项目遵循了行业内的最佳实践，将不同功能的代码分门别类地存放在指定的位置。

/
├── server/                 # 存放所有"后端"代码 (餐厅的后厨)
│   ├── index.ts            # 后端服务的"总开关"，定义了所有API接口
│   ├── geminiService.ts    # 封装了调用Gemini API的核心逻辑 (最重要的厨师)
│   └── ...                 # 其他辅助工具和配置
│
├── src/                    # 存放所有"前端"代码 (餐厅的大堂)
│   ├── pages/              # 存放应用的"页面"，每个文件对应一个你能看到的主页面
│   │   ├── GeoAnalysisPage.tsx     # "市场机会分析"页面
│   │   ├── AudienceSignalPage.tsx  # "人群信号分析"页面
│   │   └── PersonaSlidePage.tsx    # "受众画像幻灯片"页面
│   │
│   ├── components/         # 存放可复用的"UI积木"(按钮、表格、图表等)
│   │
│   ├── features/           # 存放三大核心功能的"业务逻辑"
│   │   ├── geo-analysis/
│   │   ├── audience-signal/
│   │   └── persona-slide/
│   │
│   ├── hooks/              # 存放自定义的"逻辑钩子"，用于封装复杂的状态管理
│   │   └── useGeoAnalysis.ts # "市场机会分析"页面的核心逻辑就封装在这里
│   │
│   ├── services/           # 存放与后端API或外部服务通信的代码
│   ├── routes/             # 定义了整个应用的"导航地图"，即页面路由
│   ├── contexts/           # 提供了全局共享数据的"共享空间"(如用户信息、语言配置)
│   ├── i18n/               # 存放多语言国际化相关的文件
│   └── ...                 # 其他前端相关文件
│
├── docs/                   # 存放所有项目文档的地方
│   └── project-white-paper/  # 您正在阅读的这份白皮书
│
├── public/                 # 存放静态资源 (图片、字体等，无需打包处理)
│
└── package.json            # 项目的"身份证"，记录了项目依赖的所有第三方库

理解这个结构后，即使是新加入的开发者，也能快速地根据需求找到需要修改或阅读的代码位置。例如：

想要修改"市场机会分析"页面的某个按钮样式？应该去 src/pages/GeoAnalysisPage.tsx 或者 src/components/ 找对应的组件。
想要调整调用 Gemini API 的某个参数？应该去 server/geminiService.ts。
想要增加一个新的分析功能页面？需要在 src/pages/ 新建页面文件，在 src/routes/ 中配置路由，并在 src/features/ 中编写新的业务逻辑。

API 接口设计

前端和后端之间通过 API (Application Programming Interface) 进行通信。您可以把它理解为餐厅服务员（前端）和后厨（后端）之间传递订单的"标准对话格式"。

我们的后端服务 (server/index.ts) 定义了一系列 API "端点" (Endpoints)，每一个端点都对应一个特定的功能。前端通过网络请求访问这些端点，并传递必要的参数。

核心 API 端点

以下是我们项目中最核心的几个 API 端点：

1. 文本生成 API

POST /api/gemini/generate
- 功能：执行核心的文本分析和内容生成。
- 前端需要传递：要使用的 Gemini 模型名称、精心构造的 Prompt (指令)、以及需要分析的数据。
- 后端会返回：由 Gemini 生成的文本结果（通常是结构化的 JSON）。

2. 图像生成 API

POST /api/gemini/generate-image
- 功能：执行图片生成任务。
- 前端需要传递：要使用的图片生成模型名称、描述图片的 Prompt。
- 后端会返回：生成图片的 Base64 编码数据。

3. Google Slides 集成 API

POST /api/slides/insert-image
- 功能：将一张图片插入到 Google Slides 的指定位置。
- 前端需要传递：Google Slides 的 ID、图片数据、以及图片要插入位置的"标记"。
- 后端会返回：Apps Script 的执行结果。

4. 审计日志 API

POST /api/audit-logs/*
- 功能：记录用户的各种行为日志（如登录、功能使用、导出结果等）。
- 前端需要传递：用户的身份信息、操作类型、以及相关的上下文数据。
- 后端会返回：记录成功的确认信息。

这套精心设计的 API 接口，构成了前后端协作的稳固桥梁，确保了数据和指令能够准确、高效地在系统内部流转。

应用页面概览

系统包含以下主要页面，每个页面都有其特定的功能和用途：

1. 登录页面 (`/login`)

功能：用户使用 Google 账户登录系统
主要组件：Google OAuth 登录按钮
访问权限：公开访问，已登录用户自动重定向到主页

2. 仪表盘页面 (`/`)

功能：系统主页，展示项目欢迎信息和核心功能入口
主要组件：
- 功能卡片（市场机会分析、人群信号分析、受众画像幻灯片）
- 快捷链接
- 工作流检测器（支持粘贴 Google Sheet 链接自动识别工作流类型）
访问权限：需要登录

3. 市场机会分析页面 (`/geo-analysis`)

功能：分析不同国家/地区的市场数据，识别市场机会
主要组件：
- 数据上传表单（支持 Excel 文件上传和 Google Sheet 链接）
- 分析参数配置（国家数量、提示词模板等）
- 进度显示组件
- 结果展示（气泡图、幻灯片预览）
访问权限：需要登录
详细文档：市场机会分析功能深度指南

4. 人群信号分析页面 (`/audience-signal`)

功能：深度分析用户搜索行为数据，进行意图归类和主题聚类
主要组件：
- 数据上传表单
- 分析参数配置
- 进度显示组件
- 结果展示（数据表格、幻灯片预览）
访问权限：需要登录
详细文档：人群信号分析功能深度指南

5. 受众画像幻灯片页面 (`/persona-slide`)

功能：自动生成精美的用户画像幻灯片报告
主要组件：
- 数据上传表单
- 分析参数配置
- 进度显示组件（包含图像生成进度）
- 结果展示（多张用户画像幻灯片预览）
访问权限：需要登录
详细文档：受众画像幻灯片功能深度指南

6. 工作流结果页面 (`/workflow/:workflowId`)

功能：统一的结果展示页面，支持所有三种工作流类型的结果展示
主要组件：
- 结果可视化组件（根据工作流类型动态渲染）
- 导出功能（ZIP、PPTX、图片等）
- 编辑功能（部分内容可编辑）
访问权限：需要登录
特点：支持从浏览器本地存储加载历史结果

7. 工作流对话页面 (`/c/:workflowId`)

功能：基于对话式界面的工作流执行和结果展示
主要组件：
- 对话界面
- 文件上传和 Google Sheet 链接处理
- 工作流类型自动识别
访问权限：需要登录

8. SlideCraft 相关页面

/slide-craft：SlideCraft 主页
/slide-craft/workflow/create：创建工作流
/slide-craft/workflow/result/:workflowId：工作流结果页面（旧版，已重定向到统一结果页）

总结

本章节详细介绍了项目的系统架构，包括：

技术栈概览：前端、后端、构建工具、UI 组件库等核心技术选型
系统架构设计：前后端分离架构、数据流转图、Google 生态集成
项目文件结构：代码组织方式、目录结构说明
API 接口设计：核心 API 端点及其功能说明
应用页面概览：所有主要页面的功能和组件说明

这些架构设计确保了系统能够稳定、高效地运行，并为未来的扩展和维护提供了坚实的基础。

相关文档：

目录​

技术栈概览​

什么是前端和后端？​

React：像搭乐高一样构建用户界面​

Vite：让我们的开发和浏览飞起来的"引擎"​

Node.js：让我们的服务器响应请求的"大脑"​

TypeScript：给代码添加"智能提示"的"导航员"​

设计语言：从 Semi Design 到 Ant Design​

系统架构设计​

宏观架构图：一张图看懂数据流转​

项目文件结构​

API 接口设计​

核心 API 端点​

1. 文本生成 API​

2. 图像生成 API​

3. Google Slides 集成 API​

4. 审计日志 API​

应用页面概览​

1. 登录页面 (/login)​

2. 仪表盘页面 (/)​

3. 市场机会分析页面 (/geo-analysis)​

4. 人群信号分析页面 (/audience-signal)​

5. 受众画像幻灯片页面 (/persona-slide)​

6. 工作流结果页面 (/workflow/:workflowId)​

7. 工作流对话页面 (/c/:workflowId)​

8. SlideCraft 相关页面​

总结​

目录