TrelloX🎯
一个完整的看板板应用程序，用于学习和演示各种API范例（REST、GraphQL、gRPC和MCP）。
🚀 特性
- ✅ JWT身份验证 -安全的用户注册和登录
- 📋 板、列表、卡片 -完整的看板功能
- 🎯 拖放 -直观的卡片管理
- 🔍 可观测性 -带请求跟踪的结构化日志记录
- 🎨 现代用户界面 -具有流畅动画的Vanilla JavaScript前端
- ⚡ 异步/等待 -快速、无阻塞操作
📚 你将学到什么
这个项目是 学习之旅 通过现代API开发：
模块1：REST API✅ （完成）
- 带async/await的FastAPI
- JWT身份验证
- SQLAlchemy 对象关系映射
- 结构化日志记录
- 请求跟踪
模块2:GraphQL（计划中）
- GraphQL模式设计
- 解析子和突变
- 查询优化
- 批处理和缓存
模块3:gRPC（计划中）
- 协议缓冲区
- 双向流媒体
- 实时更新
模块4:MCP服务器（计划中）
- AI助手集成
- 自然语言板管理
🛠️ 技术栈
后端：
- FastAPI 0.115
- Sqlalchemy 2.0（异步）
- SQLite（与aiosqlite异步）
- Argon2密码哈希
- JWT代币
前端：
- 普通JavaScript（ES6+）
- HTML5和CSS3
- 拖放API
开发工具：
- Python 3.13+
- Uvicorn（ASGI服务器）
- 结构化日志记录
📦 安装
先决条件
- Python 3.13或更高版本
- 点
设置
- 克隆仓库
git clone https://github.com/YOUR_USERNAME/TrelloX.git
cd TrelloX- 创建虚拟环境
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate- 安装依赖项
pip install -r requirements.txt- 设置环境变量
# Copy example env file
cp .env.example .env
# Generate a secret key
python -c "import secrets; print(secrets.token_urlsafe(32))"
# Edit .env and add your SECRET_KEY- 运行后端
python -m uvicorn app.main:app --reload --port 8000- 服务前端 （在新航站楼）
python -m http.server 3000 --directory frontend- 打开浏览器
http://localhost:3000📖 文档
docs/architecture-decisions.md-我们为什么做出这些技术选择docs/frontend.md-前端架构和模式docs/step-1.4-authentication.md-身份验证系统说明docs/step-1.9-observability.md-记录和监控QUICKSTART.md-快速入门指南
学习笔记
每个实施步骤都有详细的学习笔记 docs/:
- 步骤1.2：数据库设置
- 步骤1.3：数据模型
- 步骤1.4：身份验证
- 第1.5步：API路线
- 步骤1.6：列表和卡片
- 步骤1.9：可观察性
🎯 API终点
认证
POST /auth/register # Create account
POST /auth/login # Get JWT token
GET /auth/me # Get current user板子
POST /boards # Create board
GET /boards # List user's boards
GET /boards/{id} # Get board details
PUT /boards/{id} # Update board
DELETE /boards/{id} # Delete board列表（嵌套在板下）
POST /boards/{id}/lists # Create list
GET /boards/{id}/lists # List all lists
GET /boards/{id}/lists/{list_id} # Get list details
PUT /boards/{id}/lists/{list_id} # Update list
DELETE /boards/{id}/lists/{list_id} # Delete list卡片（嵌套在列表下）
POST /lists/{id}/cards # Create card
GET /lists/{id}/cards # List all cards
GET /lists/{id}/cards/{card_id} # Get card details
PUT /lists/{id}/cards/{card_id} # Update card
DELETE /lists/{id}/cards/{card_id} # Delete card
POST /lists/{id}/cards/{card_id}/move # Move card (drag-drop)交互式API文档： http://localhost:8000/docs
🔐 安全特性
- ✅ Argon2密码哈希
- ✅ 具有可配置到期日的JWT令牌（默认30天）
- ✅ 所有者范围的数据访问
- ✅ 使用Pydantic进行输入验证
- ✅ XSS防御（HTML转义）
- ✅ CORS配置
📊 可观测性
内置结构化日志记录功能：
- 请求ID跟踪
- 响应时间测量
- 彩色控制台输出
- 文件旋转（最大10MB）
- 单独的错误日志
查看日志：
tail -f logs/trellox.log # All logs
tail -f logs/trellox_error.log # Errors only🧪 测试
# Run tests (when implemented)
pytest
# Run with coverage
pytest --cov=app🤝 贡献
这是一个学习项目，但欢迎投稿！
- 克隆该仓库
- 创建功能分支(
git checkout -b feature/AmazingFeature) - 提交您的更改(
git commit -m 'Add some AmazingFeature') - 推到分支(
git push origin feature/AmazingFeature) - 打开拉取请求
📝 许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
🙏 致谢
- 作为探索API范例的学习项目而构建
- 灵感来自Trello和现代看板
- FastAPI为惊人的框架
- 优秀工具的Python社区
🗺️ 路线图
- \[x\] 带有身份验证的REST API
- \[x\] 拖放看板UI
- \[x\] 结构化日志记录
- \[\]GraphQL层
- \[\]WebSocket实时更新
- \[\]gRPC实现
- \[\]用于AI集成的MCP服务器
- \[\]Docker部署
- \[\]PostgreSQL支持
- \[\]Redis缓存
- \[\]综合测试
📧 联系
项目链接：
______________________________________________________________________
⭐ 如果你觉得这个repo有用，请将其标记为星号！