MCP Issue Tracker

问题跟踪器

一个采用React、Fastify和SQLite构建的现代化全栈问题跟踪应用。

特点/特性

• 🔐 表示“锁”或“保密”的意思，可以翻译为“🔒”或“保密”。 认证 - 使用 BetterAuth 实现安全的用户身份验证
• 📝（笔记/记录的图标，无具体文字含义，可理解为“记录”或“笔记”） 问题管理 - 创建、读取、更新和删除问题
• 🏷️（标签） 标签系统 - 使用可自定义标签整理问题
• 🔍（放大镜图标，通常表示搜索或查看细节） 高级过滤 - 按状态、优先级、负责人、标签和搜索条件进行筛选
• 👥（这个表情符号通常代表“人群”或“人们”，在中文中可以翻译为“人群”或根据上下文意译为“大家”、“众人”等） 用户管理 - 将问题分配给团队成员
• 📱 代表智能手机的符号 响应式设计 - 在桌面和移动设备上都能很好地工作
• ⚡（闪电符号，常用于表示速度、能量、惊喜或电击等概念） 快速且现代 - 采用现代网络技术构建

技术栈

后端

• Fastify（发音类似“法斯特菲”） - 高性能的Node.js网络框架
• SQLite - 轻量级，嵌入式数据库
• BetterAuth（可译为“更佳认证”或根据具体语境意译为“优化认证方案”等） - 现代认证库
• TypeScript - 类型安全的JavaScript

前端

• React 18 - 使用Hooks的现代React
• Vite（意大利语，意为“快”） - 快速构建工具和开发服务器
• Tailwind CSS - 实用性优先的CSS框架
• shadcn/ui（可翻译为“Shadcn UI”，但通常作为专有名词保留原样，不直接翻译） - 美观、易用的组件
• TypeScript - 类型安全的JavaScript

项目结构

├── backend/          # Fastify API server
│   ├── src/
│   │   └── index.ts  # Main server file
│   ├── package.json
│   └── tsconfig.json
├── frontend/         # React application
│   ├── src/
│   │   ├── App.tsx
│   │   ├── main.tsx
│   │   └── lib/
│   │       └── utils.ts
│   ├── package.json
│   └── tsconfig.json
└── package.json      # Root workspace configuration

入门指南

先决条件

• Node.js 18+ 和 npm
• Git（注：Git是一个分布式版本控制系统，用于跟踪在开发过程中对文件的修改）

安装

1. 克隆仓库

   git clone 
   cd issues

1. 设置后端

   cd backend
   npm install

   # Copy environment template and configure
   cp .env.template .env
   # Edit .env with your settings

   # Run database migrations
   npm run migrate

   # Seed with sample data (optional)
   npm run seed

1. 设置前端

   cd ../frontend
   npm install

   # Copy environment template and configure
   cp .env.template .env
   # Edit .env with your settings

1. 启动开发服务器

从项目根目录：

   npm run dev

或者各自开始：

   # Backend (in backend/ directory)
   npm run dev

   # Frontend (in frontend/ directory)
   npm run dev

1. 访问该应用程序

- 前端地址：http://localhost:5173 - 后端API：http://localhost:3000 - 健康检查：http://localhost:3000/health

环境配置

后端（.env）

DATABASE_PATH=database.sqlite
BETTER_AUTH_SECRET=your-super-secret-auth-key-change-this-in-production
BETTER_AUTH_BASE_URL=http://localhost:3000
PORT=3000
HOST=0.0.0.0
NODE_ENV=development
FRONTEND_URL=http://localhost:5173
LOG_LEVEL=info

前端（.env）

VITE_API_URL=http://localhost:3000/api
VITE_NODE_ENV=development

可用脚本

根脚本

• npm run dev - 以开发模式启动前端和后端
• npm run build - 为生产环境构建前端和后端
• npm run test - 运行所有测试（前端 + 后端）

后端脚本

• npm run dev - 启动带有热重载功能的开发服务器
• npm run build - 为生产环境构建
• npm run start - 启动生产服务器
• npm run test - 运行测试套件
• npm run test:watch - 在监听模式下运行测试
• npm run migrate - 运行数据库迁移
• npm run seed - 使用示例数据填充数据库

前端脚本

• npm run dev - 启动开发服务器
• npm run build - 为生产构建
• npm run preview - 预览生产构建
• npm run test - 运行测试套件
• npm run lint - 运行 ESLint

API 文档

认证端点

• POST /api/auth/sign-up/email - 用户注册
• POST /api/auth/sign-in/email - 用户登录
• POST /api/auth/sign-out - 用户登出
• GET /api/auth/get-session - 获取当前用户会话

问题API

• GET /api/issues - 列出过滤和分页方面的问题
• POST /api/issues - 创建新问题
• GET /api/issues/:id - 通过ID获取问题
• PUT /api/issues/:id - 更新问题
• DELETE /api/issues/:id - 删除问题

标签API

• GET /api/tags - 列出所有标签
• POST /api/tags - 创建新标签
• DELETE /api/tags/:id - 删除标签

用户API

• GET /api/users - 列出用户（用于分配）

健康检查

• GET /health - 应用程序健康状态
• GET /health/ready - 就绪性探测器
• GET /health/live - 活性探测器（或存活探针）

测试

运行综合测试套件：

# All tests
npm run test

# Backend tests only
cd backend && npm test

# Frontend tests only
cd frontend && npm test

# Watch mode
npm run test:watch

测试覆盖率

• 后端85项测试，涵盖CRUD操作、身份验证、过滤、错误场景
• 前端15项测试，涵盖响应式设计和组件行为

示例用户：

• john@example.com / password123
• jane@example.com / password123
• admin@example.com / admin123
• dev@example.com / dev123

贡献

1. 克隆该仓库
2. 创建一个特性分支（git checkout -b feature/amazing-feature)
3. 提交您的更改（git commit -m 'Add some amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 提交一个拉取请求

许可证

此项目遵循Apache 2.0许可证授权——详见 许可证 文件中有详细信息。

支持

如果您遇到任何问题或有任何疑问，请 提出一个问题 在GitHub上。