Ourmind 项目 Beta 阶段 Postmortem 会议报告
项目名称：Ourmind 文档思维导图生成器
阶段：Beta 阶段
日期：2025-12-17
团队成员：任少杰、彭怀玉、李荣基
一、项目概述
Ourmind 是一个基于 AI 的文档分析工具，支持上传 PDF、DOCX、TXT 格式文档，使用大模型智能分析内容，并自动生成美观的思维导图。项目采用前后端分离架构，前端使用 React + Vite + Tailwind CSS，后端使用 FastAPI + Python。在 Beta 阶段，我们完成了核心功能的开发、优化和部署，实现了文档上传、AI 解析、思维导图生成、关键词高亮、双语支持等完整功能，并提供了多种部署方案。
二、团队贡献分排名
根据 Beta 阶段的工作量、代码贡献、文档编写、问题解决等多个维度综合评估，团队贡献分排名如下：
排名第1：任少杰
任少杰主要负责后端核心开发和系统性能优化。他完成了 FastAPI 后端服务器的开发，包括文件上传、文档解析（PDF、DOCX、TXT）、AI 模型集成等核心功能。在 AI 集成方面，他成功完成了 DeepSeek/OpenAI API 的接入，实现了智能文档分析和思维导图生成，并处理了 JSON 解析、错误处理等关键技术问题。此外，他还负责了系统性能优化和稳定性提升工作。代码贡献主要集中在backend/main.py，包括文档解析逻辑、AI Prompt 工程和 JSON 格式处理。
排名第2：彭怀玉
彭怀玉主要负责前端核心开发和项目管理。他负责 React 前端应用的开发，包括主应用组件和核心交互逻辑，并参与了智能结构解析模块的前端实现。在项目管理方面，他负责项目进度管理、任务分配和团队协调，编写了多份用户手册、开发者文档和部署文档（README.md、README_CN.md、README_DEEPSEEK.md 等）。他还完善了多种部署方案，包括 ngrok 和 Cloudflare Tunnel 的公网访问方案，并编写了多个启动脚本。代码贡献主要集中在src/App.jsx和src/components/FileUpload.jsx等前端组件。
排名第3：李荣基
李荣基主要负责双向关联与交互功能的实现。他完整实现了 M2 模块（双向关联与交互），包括节点点击后在原文档中高亮显示关键词的功能。在用户体验优化方面，他优化了前端交互体验，包括思维导图可视化、文档展示等，并开发了 MindMap、DocumentView、PDFViewer 等核心组件。代码贡献主要集中在src/components/MindMap.jsx（约290行）、src/components/DocumentView.jsx（约120行）等组件，实现了关键词高亮算法和双向关联逻辑。
评分说明：三人贡献分差距很小，说明团队协作良好，分工相对均衡。排名主要基于核心功能实现难度和工作量，所有成员都积极参与项目，贡献度较高。
三、Beta 阶段反思
做得好的地方
在技术架构方面，我们采用了前后端分离的现代化架构，使用 FastAPI + React 技术栈，代码组织良好，组件职责明确，便于协作开发和后续维护。在功能实现上，我们完成了文档上传、AI 解析、思维导图生成、关键词高亮等核心功能，并实现了中英文双语支持和多种文档格式支持。在用户体验方面，我们采用了统一的琥珀色主题，界面美观，交互流畅，对关键环节都有完善的错误提示。在部署方案上，我们提供了本地、局域网、公网（ngrok、Cloudflare）多种部署方案，并提供了便捷的启动脚本，降低了使用门槛。在团队协作方面，我们按照模块进行了明确分工（M1-M4），通过日报等方式及时同步进度和问题，团队成员能够互相支持。
做得不好的地方
在版本控制方面，Git 提交记录不够完整，只有部分成员的提交记录，提交信息也过于简单，缺少详细的变更说明，没有使用分支进行功能开发和代码审查，这导致难以追溯代码变更历史和评估个人代码贡献。在测试方面，我们没有编写单元测试，主要依靠手动测试，自动化测试覆盖不足，对异常情况、大文件、网络异常等场景测试不够充分，导致 Bug 发现较晚，修复成本高。在文档方面，部分文档在代码更新后没有及时更新，后端 API 接口缺少详细的文档说明，一些技术选型和设计决策没有记录，这增加了新成员上手难度和后续维护成本。在性能方面，大文档上传和解析耗时较长，缺少进度提示，相同文档重复上传会重复调用 AI API，增加成本，思维导图节点较多时渲染性能有待提升。在错误处理方面，部分错误提示过于技术化，用户难以理解，网络异常、API 失败等情况下缺少重试机制，缺少详细的日志记录，问题排查困难。
遇到的问题与解决方案
在开发过程中，我们遇到了几个主要问题。首先是 AI API 返回格式不稳定的问题，AI 返回的 JSON 格式有时不标准，导致解析失败，有时返回包含 markdown 代码块。我们通过实现多层次的 JSON 提取逻辑（代码块提取、正则匹配），添加 JSON 格式验证和修复机制，提供默认结构作为降级方案，显著提升了 JSON 解析成功率和系统稳定性。
其次是关键词高亮不准确的问题，点击节点后，原文档中的关键词高亮匹配不准确，中英文混合文档高亮效果不佳。我们通过改进关键词匹配算法，支持模糊匹配，优化正则表达式处理特殊字符，添加关键词清理和标准化处理，提升了关键词高亮准确率和用户体验。
第三是 PDF 文档显示问题，PDF 文档在浏览器中显示效果不佳，关键词高亮在 PDF 中实现困难。我们通过使用 react-pdf 库进行 PDF 渲染，实现 PDF 文本提取和高亮逻辑，优化 PDF 查看器交互体验，改善了 PDF 显示效果和功能完整性。
最后是部署环境差异问题，不同操作系统和环境下脚本行为不一致，依赖安装和配置在不同环境下有差异。我们通过提供多平台启动脚本（Linux/Mac/Windows），添加环境检查脚本，完善部署文档和故障排查指南，提升了部署成功率和降低了用户使用门槛。
学到的经验教训
通过这个项目，我们深刻认识到版本控制规范的重要性。规范的 Git 使用对于团队协作至关重要，后续项目应建立 Git 工作流规范，包括提交信息格式、分支策略、代码审查流程。我们也认识到测试驱动的价值，缺少测试导致 Bug 发现晚、修复成本高，应建立测试体系，包括单元测试、集成测试、E2E 测试。文档同步的必要性也很重要，文档与代码不同步会增加维护成本，应将文档更新纳入开发流程，使用自动化工具检查文档一致性。性能优化应该在开发过程中持续关注，而不是最后才优化，应建立性能监控机制，定期进行性能评估和优化。完善的错误处理能显著提升用户体验和系统可靠性，应建立统一的错误处理规范，包括错误分类、提示信息、恢复机制。
四、Alpha 阶段改进方案评估
由于项目文档中未找到 Alpha 阶段的 Postmortem 文档，我们基于 Beta 阶段的实际情况，推断 Alpha 阶段可能提出的改进方案，并评估其在 Beta 阶段的落实情况。
在错误处理和用户提示方面，Alpha 阶段可能存在的问题是错误提示不够友好、缺少加载状态提示、异常情况处理不完善。在 Beta 阶段，我们添加了加载状态提示（“正在生成思维导图…”），改进了错误提示信息，但错误恢复机制仍有不足（如 API 失败重试），错误信息仍可更加用户友好。整体完成度约 70%，用户体验有所改善，但仍有提升空间。
在性能和响应速度方面，Alpha 阶段可能存在的问题是大文件处理慢、API 调用耗时较长、前端渲染性能不足。在 Beta 阶段，我们优化了前端渲染逻辑（使用 useMemo），但大文件处理仍较慢，缺少进度提示，未实现 API 调用缓存机制，未实现流式响应。整体完成度约 40%，部分性能问题得到改善，但核心性能问题（大文件、缓存）仍未解决。
在文档和部署方案方面，Alpha 阶段可能存在的问题是文档不完整、部署困难、缺少使用说明。在 Beta 阶段，我们编写了多份用户文档（README、README_CN、README_DEEPSEEK），完善了部署方案（本地、局域网、公网），提供了多种启动脚本，添加了环境检查脚本。整体完成度约 90%，文档和部署方案基本完善，用户体验良好。
在功能完整性方面，Alpha 阶段可能存在的问题是功能不完整、交互体验不佳、缺少双语支持。在 Beta 阶段，我们实现了中英文双语支持，实现了关键词高亮和双向关联，优化了交互体验，支持多种文档格式。整体完成度约 85%，功能基本完整，用户体验良好。
在代码和版本控制方面，Alpha 阶段可能存在的问题是代码规范不统一、Git 使用不规范、缺少代码审查。在 Beta 阶段，Git 提交记录仍不完整，缺少代码审查流程，代码风格基本统一，但缺少规范文档。整体完成度约 30%，代码质量有所提升，但版本控制规范仍有不足。
总体评估：改进方案平均完成度约 63%，文档和部署方案、功能完整性方面取得显著进展，但性能和响应速度优化、代码和版本控制规范方面仍有较大提升空间。
五、后续改进建议
在短期（1-2周）内，我们建议建立 Git 工作流规范，制定提交信息格式规范，建立分支策略（main、develop、feature），引入代码审查流程。添加单元测试，为核心功能编写单元测试，建立测试覆盖率目标（>60%），集成 CI/CD 自动化测试。优化性能，实现 API 调用缓存机制，添加大文件上传进度提示，优化前端渲染性能（虚拟滚动）。完善错误处理，统一错误处理规范，添加错误重试机制，优化错误提示信息。
在中期（1-2月）内，我们建议建立监控体系，添加性能监控（响应时间、错误率），添加用户行为分析，建立告警机制。扩展功能，支持更多文档格式（Markdown、HTML），实现思维导图导出功能（PNG、SVG、PDF），添加用户账户和文档管理功能。优化 AI 集成，支持更多 AI 模型（Claude、Gemini），优化 Prompt 工程，提升解析质量，实现流式响应，提升用户体验。
在长期（3-6月）内，我们建议进行架构优化，引入微服务架构（如需要），实现数据库持久化，添加用户认证和授权。推进产品化，实现多租户支持，添加协作功能（多人编辑），实现版本管理。准备商业化，实现付费功能，添加使用量统计和限制，优化成本控制（API 调用优化）。
六、项目总结
Ourmind 项目在 Beta 阶段取得了良好的成果。我们实现了文档上传、AI 解析、思维导图生成、关键词高亮等核心功能，界面美观，交互流畅，错误处理完善，提供了多种部署方案，文档齐全。在技术方面，我们采用了前后端分离架构，成功集成了 DeepSeek/OpenAI API，实现了智能文档分析，支持中英文双语思维导图，支持多种文档格式。
通过这个项目，我们学到了很多经验教训。版本控制规范的重要性不言而喻，规范的 Git 使用对于团队协作至关重要。测试驱动的价值也很明显，缺少测试导致 Bug 发现晚、修复成本高。文档同步的必要性也很重要，文档与代码不同步会增加维护成本。性能优化应该在开发过程中持续关注，而不是最后才优化。完善的错误处理能显著提升用户体验和系统可靠性。
团队在 Beta 阶段表现良好，协作良好，分工明确，沟通及时，互相支持，执行力强，能够按时完成既定任务，学习能力强，能够快速掌握新技术并应用到项目中。但规范意识待提升，版本控制、测试等规范意识需要加强。
感谢所有团队成员在 Beta 阶段的辛勤付出和贡献。特别感谢任少杰在后端核心开发和性能优化方面的贡献，彭怀玉在前端开发和项目管理方面的贡献，李荣基在交互功能实现和用户体验优化方面的贡献。
文档版本：v1.0
最后更新：2025-12-17
文档维护：团队全体成员
