Skip to content

LINGREN201/kanban-board-fullstack

BranchesTags

Repository files navigation

🎯 Kanban Board - 全栈任务管理系统

Status Docker License

基于 Prompt2Repo 准入考核题目 C 完成的商业级看板系统

功能特性 • 快速开始 • 技术架构 • API 文档 • 部署指南

📋 项目概述

这是一个全栈 Kanban 看板任务管理系统，实现了类似 Trello 的核心功能。项目采用现代化技术栈，支持任务的创建、编辑、删除，以及通过拖拽进行排序和状态变更，所有操作实时持久化到数据库。

项目亮点：

  • ✅ 商业级 UI 设计 - Glass Morphism 风格，渐变色彩系统，流畅动画
  • ✅ 完整的拖拽功能 - 支持同列排序和跨列移动，带乐观更新
  • ✅ Docker 一键部署 - 零配置启动，包含前端、后端、数据库
  • ✅ 工程化标准 - TypeScript 全覆盖，模块化设计，完善的错误处理
  • ✅ 生产就绪 - 健康检查、自动重启、数据持久化

✨ 功能特性

核心功能

  • 📝 任务管理 - 创建、编辑、删除任务，支持标题和描述
  • 🎯 三列看板 - Todo / Doing / Done 状态管理
  • 🔄 拖拽排序 - 同列内拖拽调整顺序
  • 🚀 跨列移动 - 拖拽到不同列自动更新状态
  • 💾 数据持久化 - 所有操作实时同步到 MySQL 数据库
  • ⚡ 乐观更新 - UI 立即响应，失败时自动回滚

用户体验

  • 🎨 现代化 UI - Tailwind CSS + Glass Morphism 设计
  • 🌈 渐变色彩 - 5 种色彩体系，每种 9 个色阶
  • 🎭 流畅动画 - 淡入、滑动、缩放、脉冲等 6 种动画效果
  • 📱 响应式设计 - 适配桌面、平板、手机
  • 🔔 视觉反馈 - Hover 效果、拖拽指示器、加载状态

技术特性

  • 🏗️ RESTful API - 6 个标准 REST 端点，自动生成 Swagger 文档
  • 🔒 类型安全 - 前后端 TypeScript/Pydantic 类型系统
  • 🐳 容器化部署 - 多阶段构建，镜像优化
  • 🏥 健康检查 - 数据库连接监控，自动重启
  • 🧪 自动化测试 - 包含完整的测试脚本

🚀 快速开始

前置要求

  • Docker 20.10+
  • Docker Compose 2.0+

一键启动

# 克隆仓库
git clone <repository-url>
cd agent-full-stack

# 启动所有服务（前端、后端、数据库）
docker compose up -d --build

等待 30 秒左右，访问以下地址：

验证部署

# 检查服务状态
docker compose ps

# 查看日志
docker compose logs -f

# 运行自动化测试
chmod +x test.sh
./test.sh

停止服务

# 停止但保留数据
docker compose down

# 停止并删除所有数据
docker compose down -v

🏗️ 技术架构

技术栈

层级 技术选型 版本
前端 React + TypeScript + Vite 18.2.0 / 5.3.3 / 5.0.11
样式 Tailwind CSS 3.4.1
拖拽 React DnD + HTML5 Backend 16.0.1
HTTP Axios 1.6.5
后端 FastAPI + Uvicorn 0.109.0 / 0.27.0
ORM SQLAlchemy 2.0.25
验证 Pydantic 2.5.3
数据库 MySQL 8.0
容器 Docker + Docker Compose 20.10+ / 2.0+

架构图

┌─────────────────────────────────────────────────────────┐
│                     用户浏览器                            │
└────────────────────┬────────────────────────────────────┘
                     │ HTTP
                     ▼
┌─────────────────────────────────────────────────────────┐
│  Frontend (React + Vite) - Port 3000                     │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────┐     │
│  │ Components  │  │  Custom Hook │  │  API Layer │     │
│  │ Board       │→ │  useTasks    │→ │  Axios     │     │
│  │ TaskCard    │  │              │  │            │     │
│  │ Column      │  └──────────────┘  └────────────┘     │
│  └─────────────┘                                        │
└────────────────────┬────────────────────────────────────┘
                     │ REST API
                     ▼
┌─────────────────────────────────────────────────────────┐
│  Backend (FastAPI) - Port 8001                           │
│  ┌──────────┐  ┌────────┐  ┌──────┐  ┌──────────┐     │
│  │ Routers  │→ │  CRUD  │→ │ ORM  │→ │ Database │     │
│  │ /tasks   │  │ Logic  │  │ SA   │  │ Session  │     │
│  └──────────┘  └────────┘  └──────┘  └──────────┘     │
└────────────────────┬────────────────────────────────────┘
                     │ MySQL Protocol
                     ▼
┌─────────────────────────────────────────────────────────┐
│  Database (MySQL 8.0) - Port 3308                        │
│  ┌──────────────────────────────────────────────────┐   │
│  │  tasks 表                                         │   │
│  │  - id, title, description                        │   │
│  │  - status (todo/doing/done)                      │   │
│  │  - position (排序字段)                            │   │
│  │  - created_at, updated_at                        │   │
│  └──────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

目录结构

agent-full-stack/
├── frontend/                      # React 前端应用
│   ├── src/
│   │   ├── components/           # React 组件
│   │   │   ├── Board/           # 看板相关组件
│   │   │   │   ├── Board.tsx          # 主看板容器
│   │   │   │   ├── Column.tsx         # 状态列
│   │   │   │   ├── TaskCard.tsx       # 任务卡片
│   │   │   │   └── CreateTaskForm.tsx # 创建表单
│   │   │   ├── common/          # 通用组件
│   │   │   │   ├── Button.tsx         # 按钮（5种样式）
│   │   │   │   ├── Modal.tsx          # 模态框
│   │   │   │   └── Loading.tsx        # 加载动画
│   │   │   └── Layout/
│   │   │       └── Header.tsx         # 页面头部
│   │   ├── hooks/               # 自定义 Hooks
│   │   │   └── useTasks.ts           # 任务管理逻辑
│   │   ├── services/            # API 服务层
│   │   │   └── api.ts                # Axios 封装
│   │   ├── types/               # TypeScript 类型
│   │   │   └── task.ts
│   │   ├── utils/               # 工具函数
│   │   │   └── constants.ts
│   │   ├── App.tsx              # 应用根组件
│   │   ├── main.tsx             # 应用入口
│   │   └── index.css            # 全局样式
│   ├── Dockerfile               # 多阶段构建
│   ├── nginx.conf               # Nginx 配置
│   ├── vite.config.ts           # Vite 配置
│   ├── tailwind.config.js       # Tailwind 配置
│   └── package.json
│
├── backend/                       # FastAPI 后端应用
│   ├── app/
│   │   ├── main.py              # 应用入口
│   │   ├── database.py          # 数据库配置
│   │   ├── config.py            # 配置管理
│   │   ├── models/              # SQLAlchemy 模型
│   │   │   └── task.py
│   │   ├── schemas/             # Pydantic 模式
│   │   │   └── task.py
│   │   ├── routers/             # API 路由
│   │   │   └── tasks.py
│   │   └── crud/                # CRUD 操作
│   │       └── task.py
│   ├── Dockerfile
│   └── requirements.txt
│
├── .github/
│   └── workflows/
│       └── ci.yml               # GitHub Actions CI
│
├── docker-compose.yml           # Docker 编排配置
├── .gitignore
├── test.sh                      # 自动化测试脚本
├── README.md                    # 项目说明（本文件）
├── REQUIREMENTS.md              # 需求规格说明
├── TECHNICAL_DOCS.md            # 技术详细文档
├── PROJECT_SUMMARY.md           # 项目完成总结
├── GETTING_STARTED.md           # 用户使用指南
├── ACCEPTANCE_REPORT.md         # 验收测试报告
├── DELIVERY_CHECKLIST.md        # 交付清单
├── DRAG_DROP_FIX_REPORT.md      # 拖拽功能修复报告
└── UI_OPTIMIZATION_REPORT.md    # UI 优化详细报告

📡 API 文档

端点列表

方法 路径 功能 请求体 响应
GET /api/health 健康检查 - {"status": "healthy"}
GET /api/tasks 获取所有任务 - Task[]
POST /api/tasks 创建任务 {title, description?, status?} Task
PATCH /api/tasks/{id} 更新任务 {title?, description?, status?} Task
DELETE /api/tasks/{id} 删除任务 - 204 No Content
POST /api/tasks/reorder 批量重排序 {tasks: [{id, status, position}]} 200 OK

数据模型

interface Task {
  id: number;
  title: string;
  description: string | null;
  status: 'todo' | 'doing' | 'done';
  position: number;
  created_at: string;
  updated_at: string | null;
}

交互式文档

启动服务后访问 http://localhost:8001/docs 可以使用 Swagger UI 测试所有 API。

API 调用示例

# 健康检查
curl http://localhost:8001/api/health

# 获取所有任务
curl http://localhost:8001/api/tasks

# 创建任务
curl -X POST http://localhost:8001/api/tasks \
  -H "Content-Type: application/json" \
  -d '{"title":"新任务","description":"任务描述","status":"todo"}'

# 更新任务
curl -X PATCH http://localhost:8001/api/tasks/1 \
  -H "Content-Type: application/json" \
  -d '{"title":"更新后的标题"}'

# 删除任务
curl -X DELETE http://localhost:8001/api/tasks/1

# 批量重排序
curl -X POST http://localhost:8001/api/tasks/reorder \
  -H "Content-Type: application/json" \
  -d '{"tasks":[{"id":1,"status":"doing","position":0}]}'

🐳 部署指南

Docker 部署（推荐）

生产环境部署

# 1. 克隆代码
git clone <repository-url>
cd agent-full-stack

# 2. 启动服务
docker compose up -d --build

# 3. 验证服务
docker compose ps
curl http://localhost:8001/api/health

# 4. 查看日志
docker compose logs -f

服务配置

端口映射：

  • Frontend: 3000:80 (主机:容器)
  • Backend: 8001:8000
  • Database: 3308:3306

数据持久化：

  • MySQL 数据存储在 Docker Volume mysql_data
  • 重启容器不会丢失数据
  • 使用 docker compose down -v 才会删除数据

健康检查：

  • MySQL: 每 10 秒检查一次，5 次失败后标记为 unhealthy
  • Backend: 依赖 MySQL 健康后才启动

环境变量配置

修改 docker-compose.yml 中的环境变量：

# 数据库配置
environment:
  MYSQL_DATABASE: kanban_db
  MYSQL_USER: kanban
  MYSQL_PASSWORD: kanban123  # 生产环境请修改

# 后端配置
environment:
  DATABASE_URL: mysql+pymysql://kanban:kanban123@db:3306/kanban_db

# 前端配置
build:
  args:
    VITE_API_URL: http://localhost:8001  # 修改为实际后端地址

本地开发部署

后端开发

# 1. 创建虚拟环境
cd backend
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 2. 安装依赖
pip install -r requirements.txt

# 3. 配置环境变量
export DATABASE_URL="mysql+pymysql://user:password@localhost:3308/kanban_db"

# 4. 启动开发服务器
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

前端开发

# 1. 安装依赖
cd frontend
npm install

# 2. 配置环境变量
echo "VITE_API_URL=http://localhost:8000" > .env

# 3. 启动开发服务器
npm run dev

访问 http://localhost:5173

🎨 设计系统

色彩体系

项目采用 5 种主题色彩，每种包含 9 个色阶（50-900）：

  • Primary (蓝紫色) - 主要操作按钮、链接
  • Secondary (靛蓝色) - 次要操作、信息展示
  • Success (绿色) - 成功状态、Done 列
  • Warning (黄色) - 警告状态、Doing 列
  • Danger (红色) - 删除操作、错误提示

排版系统

  • 标题字体: Poppins (Google Fonts)
  • 正文字体: Inter (Google Fonts)
  • 代码字体: JetBrains Mono

动画效果

  • fadeIn - 淡入效果（0.3s）
  • slideUp - 从下向上滑动（0.4s）
  • slideDown - 从上向下滑动（0.4s）
  • scaleIn - 缩放进入（0.3s）
  • pulse-slow - 慢速脉冲（3s）
  • shimmer - 光泽闪烁（2s）

🧪 测试

自动化测试

# 运行完整测试套件
./test.sh

# 测试内容包括：
# - 后端健康检查
# - 获取任务列表
# - 创建任务
# - 更新任务
# - 删除任务
# - 批量重排序
# - 前端可访问性

手动测试清单

  • 在 Todo 列创建任务
  • 在 Doing 列创建任务
  • 在 Done 列创建任务
  • 双击卡片编辑任务
  • 点击编辑按钮编辑任务
  • 点击删除按钮删除任务
  • 在同一列内上下拖拽排序
  • 从 Todo 拖拽到 Doing
  • 从 Doing 拖拽到 Done
  • 从 Done 拖拽回 Todo
  • 刷新页面验证数据保持
  • 重启 Docker 容器验证数据保持

🔧 配置选项

后端配置 (backend/app/config.py)

class Settings(BaseSettings):
    # 数据库配置
    DATABASE_URL: str = "mysql+pymysql://..."
    
    # API 配置
    API_V1_PREFIX: str = "/api"
    
    # CORS 配置
    CORS_ORIGINS: list = ["http://localhost:3000", ...]
    
    # 服务器配置
    HOST: str = "0.0.0.0"
    PORT: int = 8000

前端配置 (frontend/vite.config.ts)

export default defineConfig({
  server: {
    host: '0.0.0.0',
    port: 5173,
    proxy: {
      '/api': {
        target: 'http://localhost:8000',
        changeOrigin: true
      }
    }
  }
})

Tailwind 配置 (frontend/tailwind.config.js)

module.exports = {
  theme: {
    extend: {
      colors: {
        primary: { /* 自定义色阶 */ },
        secondary: { /* 自定义色阶 */ }
      },
      animation: {
        'fadeIn': 'fadeIn 0.3s ease-in',
        'slideUp': 'slideUp 0.4s ease-out'
      }
    }
  }
}

🤝 贡献方式

欢迎贡献代码、报告问题或提出建议！

贡献流程

  1. Fork 本仓库
  2. 创建特性分支 (git checkout -b feature/AmazingFeature)
  3. 提交更改 (git commit -m 'Add some AmazingFeature')
  4. 推送到分支 (git push origin feature/AmazingFeature)
  5. 开启 Pull Request

开发规范

  • 遵循现有代码风格
  • 添加必要的注释
  • 更新相关文档
  • 确保所有测试通过
  • 提交前运行 ./test.sh

报告问题

如果发现 Bug 或有功能建议，请创建 Issue，包含以下信息：

  • 问题描述
  • 复现步骤
  • 期望行为
  • 截图（如适用）
  • 环境信息（OS、Docker 版本等）

📄 许可证

本项目采用 MIT License 开源许可证。

MIT License

Copyright (c) 2026 Kanban Board Project

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

详见 LICENSE 文件。

📞 联系方式

🌟 致谢

感谢以下开源项目：

📚 相关文档

⭐ 如果这个项目对你有帮助，请给个 Star！⭐

Made with ❤️ by AI-Powered Development

回到顶部

About

全栈看板任务管理系统

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages