# qBase

**Repository Path**: M_Fisher/q-base

## Basic Information

- **Project Name**: qBase
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-04
- **Last Updated**: 2025-12-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Qoder 后台系统基础底座

> 高扩展性、模块化的后端基础框架，基于 Fastify + MongoDB + Vue 3 构建

## 📋 项目简介

Qoder 后台系统基础底座是一个企业级的后端框架，提供开箱即用的核心功能模块，包括：

- 🔐 **用户认证与权限管理** - 基于 JWT 的认证和 RBAC 权限体系
- 🌐 **静态资源服务** - 支持 SPA 路由、缓存优化、压缩传输
- 📡 **实时通信** - WebSocket 和 SSE 双协议支持（规划中）
- 📁 **文件上传** - 分片上传、断点续传、秒传（规划中）
- ⚡ **异步任务队列** - 优先级调度、状态追踪（规划中）

## 🛠️ 技术栈

### 后端
- **运行时**: Node.js 18+
- **框架**: Fastify 4.x
- **数据库**: MongoDB 7.x
- **ODM**: Mongoose 8.x
- **认证**: JWT (jsonwebtoken)
- **密码加密**: bcrypt
- **日志**: Pino

### 前端（可选）
- **框架**: Vue 3
- **状态管理**: Pinia
- **UI 组件库**: Ant Design Vue
- **构建工具**: Vite

## 📁 项目结构

```
qbase-backend/
├── src/
│   ├── config/          # 配置文件
│   ├── models/          # Mongoose 数据模型
│   ├── routes/          # API 路由
│   ├── services/        # 业务逻辑层
│   ├── middleware/      # 中间件
│   ├── plugins/         # Fastify 插件
│   ├── utils/           # 工具函数
│   ├── handlers/        # 任务处理器
│   ├── app.js           # Fastify 应用实例
│   └── server.js        # 服务启动入口
├── public/              # 静态资源（前端构建产物）
├── uploads/             # 文件上传目录
├── .env.example         # 环境变量示例
├── docker-compose.yml   # Docker Compose 配置
├── Dockerfile           # Docker 镜像构建文件
└── package.json         # 项目依赖

```

## 🚀 快速开始

### 前置要求

- Node.js >= 18.0.0
- MongoDB >= 7.0
- npm / yarn / pnpm

### 本地开发

1. **克隆项目**

```bash
git clone <repository-url>
cd qbase-backend
```

2. **安装依赖**

```bash
npm install
```

3. **配置环境变量**

```bash
cp .env.example .env
# 编辑 .env 文件，配置数据库连接和 JWT 密钥
```

4. **启动 MongoDB**

```bash
# 使用 Docker 快速启动
docker run -d -p 27017:27017 --name mongodb mongo:7-jammy

# 或使用系统安装的 MongoDB
mongod --dbpath /path/to/data
```

5. **启动开发服务器**

```bash
npm run dev
```

服务将在 `http://localhost:3000` 启动

### Docker 部署

使用 Docker Compose 一键启动所有服务：

```bash
# 生产环境部署
docker-compose up -d

# 开发环境（包含 MongoDB 管理界面）
docker-compose --profile dev up -d

# 停止服务
docker-compose down
```

访问服务：
- **应用**: http://localhost:3000
- **健康检查**: http://localhost:3000/health
- **Mongo Express** (dev): http://localhost:8081 (admin/admin123)

## 📖 API 文档

### 认证接口

#### 用户注册

```http
POST /api/auth/register
Content-Type: application/json

{
  "username": "johndoe",
  "email": "john@example.com",
  "password": "password123"
}
```

**响应**:
```json
{
  "success": true,
  "data": {
    "user_id": "507f1f77bcf86cd799439011",
    "username": "johndoe",
    "email": "john@example.com",
    "roles": ["viewer"]
  },
  "message": "注册成功"
}
```

#### 用户登录

```http
POST /api/auth/login
Content-Type: application/json

{
  "email": "john@example.com",
  "password": "password123"
}
```

**响应**:
```json
{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 86400,
    "user": {
      "id": "507f1f77bcf86cd799439011",
      "username": "johndoe",
      "email": "john@example.com",
      "roles": [{ "name": "viewer", "display_name": "查看者" }],
      "permissions": ["user:read", "file:read"]
    }
  },
  "message": "登录成功"
}
```

#### 获取当前用户信息

```http
GET /api/auth/me
Authorization: Bearer <access_token>
```

### 健康检查

```http
GET /health
```

**响应**:
```json
{
  "status": "ok",
  "timestamp": "2025-12-03T10:30:00.000Z",
  "uptime": 3600.5
}
```

## 🔐 权限系统

### 预定义角色

| 角色 | 权限 | 说明 |
|------|------|------|
| `admin` | `*:*` | 超级管理员，拥有所有权限 |
| `editor` | `user:read`, `file:*`, `task:*` | 编辑者，可管理文件和任务 |
| `viewer` | `user:read`, `file:read`, `task:read` | 查看者，仅可查看 |

### 权限格式

权限采用 `资源:操作` 格式，例如：
- `user:create` - 创建用户
- `user:read` - 查看用户
- `file:upload` - 上传文件
- `*:*` - 所有权限（超级管理员）

### 使用权限中间件

```javascript
const { requirePermissions, requireRoles } = require('./middleware/permission-check');

// 需要特定权限
fastify.get('/api/users', {
  preHandler: [fastify.authenticate, requirePermissions(['user:read'])]
}, handler);

// 需要特定角色
fastify.delete('/api/users/:id', {
  preHandler: [fastify.authenticate, requireRoles(['admin'])]
}, handler);
```

## ⚙️ 配置说明

### 环境变量

| 变量名 | 类型 | 默认值 | 说明 |
|-------|------|--------|------|
| `NODE_ENV` | String | development | 运行环境 |
| `PORT` | Number | 3000 | 服务端口 |
| `MONGODB_URI` | String | mongodb://localhost:27017/qbase | MongoDB 连接字符串 |
| `JWT_SECRET` | String | - | JWT 密钥（**必填**） |
| `JWT_EXPIRES_IN` | String | 24h | JWT 过期时间 |
| `LOG_LEVEL` | String | info | 日志级别 (fatal/error/warn/info/debug/trace) |

### 配置文件

配置文件位于 `src/config/` 目录：
- `default.js` - 默认配置
- `development.js` - 开发环境配置
- `production.js` - 生产环境配置

配置加载顺序：`default` → `environment-specific` → `.env` 环境变量

## 🧪 测试

```bash
# 运行测试
npm test

# 运行测试覆盖率
npm run test:coverage
```

## 📦 生产部署

### 使用 Docker（推荐）

```bash
# 1. 构建镜像
docker build -t qbase-backend .

# 2. 使用 Docker Compose 部署
docker-compose up -d

# 3. 查看日志
docker-compose logs -f app
```

### 直接部署

```bash
# 1. 安装生产依赖
npm ci --only=production

# 2. 设置环境变量
export NODE_ENV=production
export MONGODB_URI=mongodb://your-mongo-server:27017/qbase
export JWT_SECRET=your-super-secret-key

# 3. 启动服务
npm start

# 或使用 PM2
pm2 start src/server.js --name qbase-backend
```

## 🔧 开发指南

### 添加新的 API 路由

1. 在 `src/routes/` 创建路由文件
2. 在 `src/app.js` 中注册路由
3. 在 `src/services/` 实现业务逻辑

### 扩展数据模型

1. 在 `src/models/` 创建 Mongoose Schema
2. 定义字段、索引和实例方法
3. 导出模型供路由和服务使用

## 📝 待实现功能

- [ ] 实时通信服务（WebSocket + SSE）
- [ ] 文件上传系统（分片上传、断点续传）
- [ ] 异步任务队列系统
- [ ] 用户管理 CRUD 接口
- [ ] 前端 Vue 3 示例应用
- [ ] 单元测试和集成测试
- [ ] API 文档自动生成（Swagger）
- [ ] 日志持久化和分析

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

MIT License

## 👥 作者

Qoder Team

---

**注意**: 本项目处于活跃开发中，部分功能仍在实现中。生产环境使用前请充分测试。