Files
goal-planner/frontend/README.md
T
2026-11-02 16:43:15 +08:00

216 lines
9.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Smart Task Planner
[![React](https://img.shields.io/badge/React-19-blue?style=for-the-badge&logo=react)](https://react.dev/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue?style=for-the-badge&logo=typescript)](https://www.typescriptlang.org/)
[![Vercel](https://img.shields.io/badge/Vercel-Edge-black?style=for-the-badge&logo=vercel)](https://vercel.com/docs/functions/edge-functions)
[![Tailwind CSS](https://img.shields.io/badge/Tailwind_CSS-3.x-38B2AC?style=for-the-badge&logo=tailwind-css)](https://tailwindcss.com/)
An intelligent web application that turns your ambitious goals into actionable, step-by-step plans using the power of Google's Gemini AI.
---
## Live & Demo
Experience the live application and see how your goals are transformed into a manageable project plan in seconds.
Live link:
**[https://goal-planner-liart.vercel.app/](https://goal-planner-liart.vercel.app/)**
Demo Video:
**[https://drive.google.com/file/d/1SefadZbCxVUL7FB8phFoG5xJ3eoPevrj/view?usp=drive_link](https://drive.google.com/file/d/1SefadZbCxVUL7FB8phFoG5xJ3eoPevrj/view?usp=drive_link)**
---
## About The Project
Smart Task Planner bridges the gap between vision and execution. It leverages Google's advanced Gemini API to analyze a user's high-level goal and intelligently generate a comprehensive roadmap. The result is a detailed list of tasks, complete with descriptions, time estimates, and dependencies, giving users a clear and actionable path to success.
This project was built to demonstrate a modern, secure, and performant full-stack application using a serverless backend architecture, ensuring both a great user experience and robust security.
---
## Application Screenshots
**Landing Page:**
<img width="1897" height="862" alt="image" src="https://github.com/user-attachments/assets/3bff2ddd-e60d-468e-abbf-781d2f04adcb" />
**Planner View:**
<img width="1905" height="847" alt="image" src="https://github.com/user-attachments/assets/d0d2a68b-7611-49c2-a205-43565582cc75" />
**Task Editing Modal:**
<img width="1919" height="863" alt="image" src="https://github.com/user-attachments/assets/fc167628-9d70-4200-8825-a5f32f0ec8b9" />
---
## Core Features & Application Logic
This application integrates several key technical features to deliver a seamless and powerful planning experience.
### AI-Powered Plan Generation
- **Logic**: The core of the application resides in the `/api/generate-plan.ts` Vercel Edge Function. When a user submits a goal, the frontend sends a request to this secure backend endpoint. The function then constructs a detailed prompt, instructing the Gemini AI to act as an expert project manager.
- **Structured Output**: To ensure a reliable and predictable response from the AI, the backend enforces a strict JSON schema via the `responseSchema` configuration. This forces the Gemini model to return a perfectly formatted JSON array of tasks, which the frontend can parse and render without requiring complex data manipulation.
### Dynamic Task Dependency System
- **Logic**: The AI generates a `dependencies` array for each task (e.g., `["task-1", "task-3"]`). On the frontend, the `TaskList` component maintains a `Set` of completed task IDs for efficient lookups.
- **User Experience**: Before rendering each task, the application checks if all of its prerequisite tasks have been completed. A task is visually "locked" (greyed out and non-interactive) if any of its dependencies are not yet met. Once all dependencies are finished, the task automatically unlocks, creating an intuitive and logical workflow for the user.
### Interactive Progress Tracking
- **Logic**: The `PlannerView` component uses React's `useMemo` hook to efficiently calculate progress metrics whenever the `tasks` array changes. It counts completed tasks versus the total and sums the `durationInHours` for all tasks to provide a total project estimate.
- **User Experience**: Users get immediate visual feedback via a dynamic progress bar, a "X / Y Tasks" counter, and a total estimated project duration, keeping them motivated and informed.
### Secure Serverless Architecture
- **Logic**: The frontend **never** communicates directly with the Gemini API. All API calls are proxied through the `/api/generate-plan` serverless function. The `API_KEY` is stored securely as an environment variable on Vercel's servers and is never exposed to the client's browser. This is a critical security best practice that prevents key leakage.
### Simulated Authentication Flow
- **Logic**: The application uses React state to manage a `currentUser` object, simulating a complete login/signup flow. Views are conditionally rendered based on whether a user object exists in the state, protecting the main planner view from unauthenticated access. This demonstrates state management for a typical user-gated application.
---
## Tech Stack
This project is built with a modern web development stack:
- **Frontend:**
- **React**: For building the component-based user interface.
- **TypeScript**: For static typing, improved code quality, and developer experience.
- **Tailwind CSS**: For rapid, utility-first styling and a responsive design.
- **Backend (Serverless):**
- **Vercel Edge Functions**: To create a secure, scalable backend proxy for API calls.
- **Core API:**
- **Google Gemini API**: The AI engine for intelligent plan generation.
- **Deployment:**
- **Vercel**: For seamless, Git-based deployment and hosting.
---
## Local Development Setup
To get a local copy up and running, follow these steps.
### Prerequisites
- Node.js (v18 or later recommended)
- npm, yarn, or pnpm
- A Google Gemini API Key. You can get one for free from [Google AI Studio](https://makersuite.google.com/).
### Installation & Configuration
1. **Clone the repository:**
```sh
git clone https://github.com/AbhinayManikanti/goal-planner.git
cd goal-planner
```
2. **Install the Vercel CLI:**
```sh
npm install -g vercel
```
3. **Create an environment file:**
Create a new file named `.env` in the root of your project and add your Gemini API key:
```
API_KEY="YOUR_GEMINI_API_KEY_HERE"
```
4. **Run the development server:**
Use the Vercel CLI to run the project. This is the best method as it correctly serves both the React frontend and the serverless function in the `/api` directory.
```sh
vercel dev
```
Your application should now be running at `http://localhost:3000`.
---
## Deployment
This application is optimized for deployment on [Vercel](https://vercel.com/).
1. Push your code to a Git repository (GitHub, GitLab, etc.).
2. Import the repository into Vercel.
3. **Configure the Environment Variable (Crucial Step):**
- In your Vercel project settings, navigate to **Settings > Environment Variables**.
- Add a variable with the name `API_KEY` and paste your Gemini API key as the value.
4. Deploy. Vercel will automatically handle the build process for both the frontend and the serverless function.
---
## Author
**Abhinay Manikanti**
- **GitHub**: [@AbhinayManikanti](https://github.com/abhinay-07)
- **LinkedIn**: [Abhinay Manikanti](https://www.linkedin.com/in/abhinay-manikanti)
- **Project Link**: [https://github.com/AbhinayManikanti/goal-planner](https://github.com/AbhinayManikanti/goal-planner)
这是前后端分开跑的项目:后端是 FastAPI(端口 8000),前端是 Vite(端口 3000)。项目根目录已经有 `.venv`,`backend\.env` 也已经写好了。
## 1. 准备 MySQL
用 phpStudy 把 MySQL 启动起来,然后建库(表会在后端第一次启动时自动创建):
```sql
CREATE DATABASE goal_planner CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```
确认 `backend\.env` 里的 `MYSQL_HOST`、`MYSQL_PORT`、`MYSQL_USER`、`MYSQL_PASSWORD` 和 phpStudy 里的 MySQL 一致。当前文件里数据库名是 `goal_planner`,用户是 `root`。
## 2. 启动后端
在 PowerShell 里执行。必须在 `backend` 目录启动,否则读不到 `.env`。
```powershell
cd d:\phpstudy_pro\WWW\python-projects\goal-planner
.\.venv\Scripts\python.exe -m pip install -r backend\requirements.txt
cd backend
..\.venv\Scripts\python.exe -m uvicorn main:app --host 127.0.0.1 --port 8000 --reload
```
看到 `Uvicorn running on http://127.0.0.1:8000` 后,浏览器打开 http://127.0.0.1:8000/api/health ,应返回 `{"status":"ok"}`。
如果提示无法运行脚本,不要用 `Activate.ps1`,直接用上面的 `python.exe` 完整路径即可。
## 3. 启动前端
另开一个 PowerShell:
```powershell
cd d:\phpstudy_pro\WWW\python-projects\goal-planner\frontend
npm install
npm run dev
```
浏览器打开 http://localhost:3000 。需要 Node.js 18 或更高版本。
## 4. 让前端能打到后端
前端请求走的是 `/api-proxy`(给 Nginx 反代用的)。Vite 目前没有这条代理,只开两个服务的话,页面能打开,但登录和生成计划会 404。
在 `frontend\vite.config.ts` 的 `server` 里加上:
```ts
server: {
port: 3000,
host: '0.0.0.0',
proxy: {
'/api-proxy': {
target: 'http://127.0.0.1:8000',
changeOrigin: true,
rewrite: (path) => path.replace(/^\/api-proxy/, ''),
},
},
},
```
改完后重启 `npm run dev`。请求 `/api-proxy/api/...` 会被转到 `http://127.0.0.1:8000/api/...`。