第六部分：开发指南

---

InsightHub 项目始于个人创新，但它的未来在于团队智慧的融合。我们欢迎每一位对技术、对效率、对创造价值充满热情的同事，加入我们的开发者行列。

本章节提供清晰的开发指南，帮助你快速搭建开发环境，理解开发流程，并顺利地提交你的第一个贡献。我们相信，清晰的规范和开放的沟通，是愉快协作的基石。

6.1 开发环境配置

6.1.1 搭建本地开发环境

在贡献代码之前，你需要在本地电脑上搭建一个可以运行和修改项目的开发环境。请按照以下步骤操作：

1. 安装 Node.js:

   • Node.js 是项目后端运行和前端构建的基础环境。
   • 请访问 Node.js 官网 下载并安装最新的 LTS (Long Term Support) 版本。

2. 安装 Git:

   • Git 是目前全球最流行的代码版本控制工具，也是团队协作的基础工具。
   • 请访问 Git 官网 下载并安装适合你操作系统的版本。

3. 安装 VS Code (推荐):

   • VS Code 是一款由微软开发的免费、开源且功能强大的代码编辑器。本项目的所有代码都是使用 VS Code 编写的。
   • 请访问 VS Code 官网 下载并安装。

4. 克隆代码仓库:

   • 打开终端（或 Git Bash），使用 git clone 命令将项目的代码仓库克隆到本地。
   • git clone [项目的 Git 仓库地址]

5. 安装项目依赖:

   • 项目分为前端 (/) 和后端 (/server) 两个部分，你需要分别为它们安装所需的第三方库。
   • 安装前端依赖：

     cd [项目根目录]
     npm install

   • 安装后端依赖：

     cd server
     npm install

6. 配置环境变量:

   • 在项目根目录创建 .env 文件（参考 .env.example 文件）
   • 配置必需的环境变量（详见 环境变量配置指南）
   • 最小配置（用于本地开发测试）：

     # Google OAuth 2.0 配置（必需）
     VITE_GOOGLE_OAUTH_CLIENT_ID=your_client_id_here
     GOOGLE_CLIENT_SECRET=your_client_secret_here
     
     # Gemini API 配置（必需）
     GEMINI_API_KEY=your_gemini_api_key_here
     
     # 其他配置（可选，用于完整功能测试）
     VITE_GOOGLE_SLIDES_TEMPLATE_ID=your_template_id_here
     VITE_HELP_DOCUMENT_URL=https://your-help-doc-url.com
     AUDIT_LOG_SPREADSHEET_ID=your_audit_sheet_id_here
     APPS_SCRIPT_SLIDES_ID=your_slides_script_id_here

   • 注意：.env 文件包含敏感信息，不应提交到 Git 仓库

6.1.2 第一次运行项目

当所有依赖都安装成功后，你可以在本地运行项目。你需要同时启动前端开发服务器和后端服务。

1. 启动后端服务:

   • 打开一个新的终端窗口，进入 server 目录。
   • cd server
   • npm run dev
   • 当你看到类似 服务器启动成功 的日志时，表示后端服务已在本地 http://localhost:8080 成功运行。

2. 启动前端服务:

   • 打开另一个新的终端窗口，保持在项目根目录。
   • npm run dev
   • 当你看到类似 VITE vX.X.X ready in XXXms 的日志时，表示前端开发服务器已成功运行。
   • 在浏览器中打开日志中显示的本地地址（通常是 http://localhost:5173），你应该能看到项目的登录页面了。

开发环境已成功搭建。

6.1.3 Git 与 GitHub 基础

如果你对 Git 和 GitHub 还不熟悉，可以将其理解为带版本记录的代码仓库。

• 核心概念：

  • Repository (仓库)：项目代码存放在远程仓库中。
  • Clone (克隆)：通过 git clone 将远程仓库复制到本地电脑。
  • Commit (提交)：在本地修改代码后，通过 git commit 将改动保存，并附上说明。
  • Push (推送)：通过 git push 将本地保存的改动上传到远程仓库。
  • Pull (拉取)：通过 git pull 将其他同事推送到远程仓库的最新改动同步到本地。

• 推荐学习资源：建议花 1-2 个小时学习 Git 的基础知识，这将使团队协作更加顺畅。

  • 廖雪峰的 Git 教程 (中文，非常适合初学者)
  • GitHub's Official Guide (英文，官方入门)

• 常用 Git 命令：

  # 查看当前状态
  git status
  
  # 查看修改内容
  git diff
  
  # 添加修改到暂存区
  git add .
  
  # 提交修改
  git commit -m "描述你的修改"
  
  # 推送到远程仓库
  git push origin your-branch-name
  
  # 拉取最新代码
  git pull origin main
  
  # 创建新分支
  git checkout -b feature/your-feature-name

6.1.4 运行测试

在提交代码之前，建议运行项目的测试套件，确保你的修改没有破坏现有功能。

1. 运行前端测试（如果存在）：

   npm run test

2. 运行代码检查：

   # 检查代码格式
   npm run lint
   
   # 自动修复格式问题
   npm run lint:fix

3. 手动功能测试：

   • 启动前端和后端服务
   • 在浏览器中测试核心功能（登录、文件上传、分析等）
   • 检查浏览器控制台是否有错误
   • 检查后端日志是否有错误

6.2 开发流程与规范

为了确保项目的代码质量、可维护性以及团队协作的顺畅，我们希望每一位贡献者都能共同遵守以下准则。

6.2.1 代码风格与注释规范

• 自动格式化：项目已配置 ESLint 和 Prettier 进行代码风格检查。在提交代码时，它们会自动检查并统一代码格式。请确保你的代码能通过这些检查。
• 注释是写给人看的：
  • 我们鼓励为核心或复杂的逻辑部分添加清晰的中文注释。
  • 注释的目的是解释"为什么"这么做，而不是"做了什么"。好的代码本身就能说明"做了什么"，而注释则应该用来阐述背后的设计思路、业务逻辑或需要注意的问题。
  • 目标读者：请想象你的注释是写给一位聪明但对这块业务不熟悉的同事看的，甚至是一位只懂一点代码的产品经理。清晰的注释是知识传承的最佳途径。

6.2.2 如何提出新想法（需求与功能建议）

我们非常欢迎各种能让项目变得更好的新想法。但为了避免需求不清晰和无效的投入，我们建议遵循以下流程：

1. 先思考，再提议：在提出一个新功能想法时，请不要只说"我想要一个XX功能"。请花一些时间深入思考：

   • 这个功能要解决的核心问题是什么？
   • 它的目标用户是谁？
   • 一个最小可行版本 (MVP) 应该包含哪些核心要素？
   • 你设想中的用户操作流程是怎样的？

2. 文档先行：我们强烈建议将你的想法写成一个简短的需求文档 (1-Page Doc)。可以用文字、草图、甚至流程图来清晰地表达你的设想。

3. 公开讨论：将你的需求文档在团队中进行公开讨论。这有助于收集反馈，发现潜在的问题，并确保这个想法得到了大家的认可。

4. 共同开发：我们鼓励提出想法的人，也成为实现想法的主力。项目的创始人和其他核心开发者会非常乐意为您提供技术指导和支持，但我们希望营造一种"人人都是建设者"的文化，而不是"一部分人提需求，另一部分人埋头实现"的模式。

6.2.3 提交你的贡献（代码提交流程）

我们采用行业标准的 Feature Branch -> Pull Request -> Code Review 协作流程。

1. 创建分支 (Branch)：请不要直接在 main 主分支上修改代码。每次开发一个新功能或修复一个 Bug，都请从最新的 main 分支创建一个新的分支，并给它起一个有意义的名字（如 feature/add-new-chart 或 fix/login-bug）。

2. 开发与提交：在你自己的分支上进行代码编写和修改。完成一部分功能后，随时进行 git commit。

3. 发起合并请求 (Pull Request)：当你的功能开发完成并通过本地测试后，将你的分支推送到远程仓库，并在 GitHub 上发起一个指向 main 分支的 Pull Request (PR)。

   • 在 PR 的描述中，请清晰地说明你完成了什么功能、解决了什么问题，以及希望代码审查者 (Reviewer) 关注哪些重点。

4. 代码审查 (Code Review)：至少需要一位其他核心开发者对你的代码进行审查。这是一个非常宝贵的相互学习和保证代码质量的环节。请虚心接受审查意见，并进行相应的修改。

5. 合并 (Merge)：当你的 PR 获得批准 (Approve) 并且通过了所有的自动化检查后，它将被合并到 main 主分支中。

恭喜你，你已经成功地为项目贡献了一份力量。

6.2.4 代码提交规范

为了保持项目历史的清晰和可读性，我们建议遵循以下提交信息规范：

• 提交信息格式：

  <类型>: <简短描述>
  
  <详细描述（可选）>

• 类型说明：

  • feat: 新功能
  • fix: 修复 Bug
  • docs: 文档更新
  • style: 代码格式调整（不影响功能）
  • refactor: 代码重构
  • test: 测试相关
  • chore: 构建过程或辅助工具的变动

• 示例：

  feat: 添加市场机会分析功能
  
  实现了基于 Gemini AI 的市场机会分析功能，包括：
  - 数据上传和解析
  - AI 分析调用
  - 结果可视化展示

• 注意事项：

  • 提交信息使用中文或英文均可
  • 简短描述应清晰说明本次提交的目的
  • 如果修改涉及多个文件，建议在详细描述中说明

6.2.5 遇到问题怎么办？

在开发过程中，你可能会遇到各种问题。以下是一些建议：

1. 查阅文档：

   • 首先查阅本项目的文档（特别是技术实现部分）
   • 查阅相关技术栈的官方文档

2. 搜索问题：

   • 在项目 Issue 中搜索是否有类似问题
   • 在 Stack Overflow 等社区搜索

3. 寻求帮助：

   • 在团队沟通渠道（如 Slack、邮件）中提问
   • 在 GitHub Issue 中创建问题，详细描述问题现象和复现步骤

4. 代码审查时提问：

   • 代码审查是学习和交流的好机会
   • 如果对审查意见有疑问，请及时提问

---

6.3 故障排查

6.3.1 常见问题

问题 1：npm install 失败

可能原因：

• 网络问题导致依赖下载失败
• Node.js 版本不兼容
• 权限问题

解决方案：

# 清除 npm 缓存
npm cache clean --force

# 删除 node_modules 和 package-lock.json，重新安装
rm -rf node_modules package-lock.json
npm install

# 如果使用代理，配置 npm 代理
npm config set proxy http://proxy.example.com:8080

问题 2：后端服务启动失败

可能原因：

• 端口被占用
• 环境变量未配置
• 依赖未安装

解决方案：

# 检查端口占用（Windows）
netstat -ano | findstr :8080

# 检查端口占用（Mac/Linux）
lsof -i :8080

# 检查环境变量
cat .env

# 重新安装依赖
cd server
rm -rf node_modules package-lock.json
npm install

问题 3：前端页面无法访问

可能原因：

• 后端服务未启动
• 端口配置错误
• 浏览器缓存问题

解决方案：

• 确认后端服务已启动（http://localhost:8080）
• 清除浏览器缓存
• 检查浏览器控制台错误信息

问题 4：OAuth 登录失败

可能原因：

• OAuth Client ID 配置错误
• 重定向 URI 不匹配
• 网络问题

解决方案：

• 检查 .env 文件中的 VITE_GOOGLE_OAUTH_CLIENT_ID 是否正确
• 检查 Google Cloud Console 中的重定向 URI 配置
• 查看浏览器控制台和网络请求的错误信息

---

6.4 学习资源

6.4.1 技术栈学习

如果你对项目使用的技术栈还不熟悉，以下资源可以帮助你快速上手：

• React：

  • React 官方文档（推荐）
  • React 中文文档

• TypeScript：

  • TypeScript 官方文档
  • TypeScript 中文文档

• Node.js / Express：

  • Node.js 官方文档
  • Express 官方文档

• Vite：

  • Vite 官方文档

6.4.2 项目特定知识

• Google Gemini API：

  • Google AI Studio
  • Gemini API 文档

• Google Workspace APIs：

  • Google Sheets API
  • Google Slides API
  • Google Apps Script

---

总结

本章节提供了完整的开发指南，包括：

1. 开发环境配置：从零开始搭建本地开发环境
2. 项目运行：如何启动和测试项目
3. Git 基础：版本控制的基本概念和操作
4. 开发准则：代码风格、提交流程、提交规范
5. 故障排查：常见问题的解决方案
6. 学习资源：技术栈和项目相关知识的学习资源

我们相信，通过遵循这些指南，你能够顺利地参与到项目开发中，并为项目贡献你的智慧和力量。如果你有任何问题或建议，欢迎随时与团队沟通。

---

相关文档：

• 环境变量配置指南
• 技术架构与实现
• 用户使用手册