MohammadSaqlain124/focusforge

# 🔥 FocusForge FocusForge 是一个全栈 MERN 应用程序，帮助用户追踪专注时段，分析他们的工作模式，并通过基于规则的智能引擎检测倦怠风险。该项目建于巴雷利 Invertis 大学，作为计算机科学与工程（CSE）专业三年级 B.Tech 项目的一部分。 ## ✨ 本项目的独特之处 大多数学生的生产力项目仅仅停留在 CRUD 阶段——保存和列出数据。FocusForge 则更进一步，通过**分析长期的行为模式**： - **连续打卡追踪** 记录连续保持专注的天数。 - **倦怠风险引擎** 采用 6 条规则的评分系统来检测过度工作模式，并展示*透明的推理过程*。 - **每周洞察** 通过 MongoDB 聚合管道进行计算——包括最高专注时段、每周最高产日、放弃率和每日数据明细。 系统告诉用户*为什么*它会发出警告，而不仅仅是*发出*了警告。所有的决策都是可解释的，绝非黑盒操作。 ## 🛠️ 技术栈 | 层级 | 技术 | |------------------|--------------------------------------| | 前端 | React 19, Vite, React Router, Axios | | 后端 | Node.js, Express | | 数据库 | MongoDB Atlas (云) + Mongoose ODM | | 身份验证 | JWT + bcrypt 密码哈希 | | 状态管理 | React Context + Hooks | | 样式 | Vanilla CSS (自定义设计系统) | ## 🏗️ 架构 ┌─────────────────────────────┐ │ React 前端 │ │ (Vite, 端口 5173) │ │ │ │ 页面 → 组件 │ │ ↓ │ │ 服务层 │ └─────────────┬───────────────┘ │ HTTP + JWT ▼ ┌─────────────────────────────┐ │ Express 后端 │ │ (端口 5000) │ │ │ │ 路由 → 中间件 │ │ ↓ │ │ 控制器 │ │ ↓ │ │ 服务 (业务逻辑) │ │ ↓ │ │ 模型 │ └─────────────┬───────────────┘ │ ▼ ┌─────────────────────────────┐ │ MongoDB Atlas │ │ (云数据库) │ └─────────────────────────────┘ 后端遵循**分层架构**： - **路由** 负责处理 HTTP 连接。 - **中间件** 处理横切关注点（如身份验证、错误处理）。 - **控制器** 解析请求并编排响应。 - **服务** 包含纯粹的业务逻辑（洞察引擎）。 - **模型** 定义模式和验证规则。 这种分离设计使代码库更易于测试、维护和扩展。 ## 📂 项目结构 focusforge/ ├── backend/ │ ├── config/ # 数据库连接 │ ├── controllers/ # 请求处理器 │ │ ├── authController.js │ │ ├── sessionController.js │ │ └── insightsController.js │ ├── middleware/ # 身份验证 + 错误处理 │ ├── models/ # Mongoose 模式 │ │ ├── User.js │ │ └── Session.js │ ├── routes/ # URL 到控制器的映射 │ ├── services/ # 纯粹的业务逻辑 │ │ └── insightsEngine.js │ ├── utils/ # JWT 辅助工具 │ ├── server.js # Express 入口文件 │ └── .env # 环境变量（未提交） │ └── frontend/ └── src/ ├── components/ # 可复用的 UI 组件 ├── context/ # AuthContext ├── pages/ # 登录、注册、仪表盘 ├── services/ # API 客户端 └── App.jsx # 路由配置 ## 🚀 设置说明 ### 前置条件 - Node.js v18+ 和 npm - MongoDB Atlas 账户（免费套餐即可） ### 1. 克隆仓库 git clone cd focusforge ### 2. 后端设置 cd backend npm install 在 `backend/` 目录下创建一个 `.env` 文件，内容如下： PORT=5000 MONGO_URI=mongodb+srv://:@.mongodb.net/focusforge?retryWrites=true&w=majority JWT_SECRET=your_secret_key_here JWT_EXPIRES_IN=7d NODE_ENV=development 启动后端： npm run dev 你应该会看到： 🔥 Server running on port 5000 in development mode ✅ MongoDB Connected: ... ### 3. 前端设置 打开**第二个终端**： cd frontend npm install npm run dev 在浏览器中打开 `http://localhost:5173`。 ## 📡 API 参考 所有端点都以 `/api` 为前缀。需要身份验证的路由要求在请求头中提供 `Bearer ` 授权信息。 ### 身份验证 | 方法 | 端点 | 描述 | 需认证 | |--------|------------------|---------------------------|------| | POST | `/auth/register` | 创建一个新用户账户 | 否 | | POST | `/auth/login` | 登录并获取 JWT | 否 | | GET | `/auth/me` | 获取当前用户信息 | 是 | ### 专注时段 | 方法 | 端点 | 描述 | 需认证 | |--------|-----------------------|---------------------------------------------|------| | POST | `/sessions/start` | 开始一个新的专注时段 | 是 | | GET | `/sessions` | 列出用户的专注时段（带筛选和分页） | 是 | | GET | `/sessions/:id` | 通过 ID 获取单个专注时段 | 是 | | PATCH | `/sessions/:id/end` | 结束一个进行中的专注时段 | 是 | | PATCH | `/sessions/:id/break` | 记录一次休息（原子递增） | 是 | ### 洞察 (智能引擎) | 方法 | 端点 | 描述 | 需认证 | |--------|---------------------------|---------------------------------------|------| | GET | `/insights/streak` | 当前的连续天数打卡 | 是 | | GET | `/insights/burnout-check` | 24小时倦怠风险分析 | 是 | | GET | `/insights/weekly` | 通过聚合管道获取7天统计数据 | 是 | ### 请求示例 — 开始一个专注时段 POST /api/sessions/start Authorization: Bearer Content-Type: application/json { "goal": "Study sorting algorithms", "plannedDuration": 45, "tags": ["DSA", "deep-work"] } ### 响应示例 — 倦怠检查 { "success": true, "data": { "riskLevel": "medium", "score": 5, "reasons": [ "You've focused for 280 minutes today (over 4 hours)", "Only 1 break in 4.7 hours of focus" ], "recommendation": "Consider a 15-minute break before your next session.", "sessionsAnalyzed": 6, "windowHours": 24 } } ## 🧠 智能引擎 倦怠检查器使用一个**基于规则的评分引擎**。每条规则都编码了一种行为预警。被触发的规则会增加风险得分，该得分随后会映射到对应的风险等级。 | 规则 | 触发条件 | 分数 | |---------------------|--------------------------------|-------| | 高强度专注日 | 今日专注时间 > 4 小时 | +3 | | 极限专注日 | 今日专注时间 > 6 小时 | +2 | | 休息不足 | 每小时休息次数 < 0.5 | +2 | | 最近有放弃行为 | 上一个专注时段被放弃 | +2 | | 深夜专注时段 | 专注时段开始于晚上 11 点 – 凌晨 5 点 | +2 | | 碎片化工作 | 3 个及以上专注时段的平均时长 < 15 分钟 | +2 | | 总得分 | 风险等级 | |-------------|------------| | 0–2 | 低 | | 3–5 | 中等 | | 6+ | 高 | 这种方法**在设计上就是可解释的** —— 系统总是会返回导致该得分的具体原因，使得 AI 的决策过程变得透明。 ## 📊 MongoDB 聚合管道 每周洞察端点使用了四个聚合管道： 1. **总计管道** — `$match` 筛选出最近的专注时段，通过 `$group` 以及 `$sum` 和条件累加器进行计算。 2. **每日明细** — `$dateToString` 格式化日期，然后按日期字符串进行 `$group` 分组。 3. **每小时明细** — `$hour` 操作符提取一天中的小时数，用于找出最高产出的专注时段。 4. **每周几明细** — `$dayOfWeek` 操作符用于找出一周中产量最高的一天。 聚合操作在数据库端运行，只返回汇总后的结果——这比在 JavaScript 中抓取文档并进行计算要快得多。 ## 🖼️ 截图 ### 登录与注册 ![登录]()  ### 仪表盘   ### 洞察与历史记录  ### API 测试  ## 🔐 安全性考量 - 使用 bcrypt 进行**密码哈希**（salt rounds: 10）。 - **基于 JWT 的无状态身份验证** —— 无需服务器端存储会话。 - **按用户划分数据范围** —— 每个受保护的端点在返回数据前都会验证数据所有权。 - 通过 Mongoose 的枚举和必填字段进行**模式级别验证**。 - **集中式的 401 错误处理** —— 过期的 token 会在前端触发自动登出。 - 使用**环境变量**管理敏感信息（`.env` 已通过 git 忽略）。 ## 🚧 未来改进计划 - 注册时的电子邮件验证 - 密码重置流程 - 用户可配置的时区（目前为 UTC） - 通过 WebSocket 在多设备间实现实时的专注时段同步 - 番茄钟模式 - 将每周报告导出为 PDF - 移动优先的重新设计 - **可靠的休息结束通知** —— 目前的实现在部分浏览器/环境中有效，但需要引入 Service Worker 以确保在后台时的完全可靠性。计划在 v1.3 版本中实现。 ## 👨‍💻 作者 **Mohd Saqlain Hussain** B.Tech 计算机科学与工程，第六学期 巴雷利 Invertis 大学 ## 📜 许可证 本项目作为 B.Tech 课程的一部分，出于学术目的而构建。代码可供学习和参考。

标签：Axios, B.Tech项目, CSE计算机工程, Express, Express.js, GNU通用公共许可证, JWT认证, MERN技术栈, MITM代理, MongoDB, Mongoose ODM, Node.js, NoSQL数据库, React, RESTful API, Syscalls, Vite, 个人效率管理, 习惯追踪, 云计算, 前后端分离, 大学生毕业设计, 工作模式分析, 提示词优化, 数据聚合分析, 时间管理, 注意力追踪, 状态管理, 生产力工具, 生产效率提升, 用户洞察, 职业倦怠检测, 自定义脚本, 规则引擎