# backend

**Repository Path**: qiuanshmily/backend

## Basic Information

- **Project Name**: backend
- **Description**: 民国知识学堂后端项目
项目概述
"民国知识学堂" 是一款以民国历史文化为主题的益智竞答类应用，支持微信小程序和抖音小程序双端运行。当前版本聚焦单人闯关功能，后续将迭代开发双人 PK 玩法，通过学分体系和成就系统增强用户粘性。

核心功能
用户注册与登录（支持微信 / 抖音快捷登录）
单人闯关答题（多关卡、多难度）
学分积累与记录
成就系统（达成条件与奖励）
学分排行榜
系统提示与功能预告（为双人 
- **Primary Language**: NodeJS
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 民国知识学堂 - 后端服务

## 📖 项目简介

"民国知识学堂" 是一款以民国历史文化为主题的益智竞答类应用，支持微信小程序和抖音小程序双端运行。项目采用DDD（领域驱动设计）架构，提供完整的用户管理、闯关答题、双人PK、测评系统等功能。

### 🎯 核心功能

- **用户系统** - 微信/抖音快捷登录、用户信息管理、学分统计
- **单人闯关** - 多关卡答题、学分奖励、成就解锁
- **双人PK** - 实时对战、WebSocket通信、胜负判定
- **测评系统** - 专业测评、结果分析、报告生成
- **成就系统** - 成就解锁、进度追踪、奖励发放
- **分享导出** - 结果分享、报告导出、数据统计

## 🛠️ 技术栈

### 后端框架
- **Node.js** - 运行时环境
- **Express 5.1.0** - Web应用框架
- **Socket.IO 4.8.1** - 实时通信

### 数据库
- **PostgreSQL** - 主数据库
- **Sequelize 6.37.3** - ORM框架
- **Redis 5.6.0** - 缓存服务

### 安全认证
- **JWT (jsonwebtoken 9.0.2)** - 身份认证
- **bcrypt 6.0.0** - 密码加密
- **crypto-js 4.2.0** - 数据加密

### 开发工具
- **Winston 3.17.0** - 日志管理
- **Axios 1.12.2** - HTTP客户端
- **Swagger UI** - API文档

### 部署运维
- **Docker** - 容器化部署
- **Docker Compose** - 服务编排

## 📁 项目结构

```
backend/
├── server/                    # 服务端核心代码
│   ├── app.js                # 应用入口
│   ├── config/               # 配置文件
│   ├── controllers/           # 控制器层
│   ├── domains/              # 领域模型 (DDD架构)
│   ├── models/               # 数据模型
│   ├── services/             # 业务服务层
│   │   ├── user.service.js           # 用户服务
│   │   ├── assessment.service.js     # 测评服务
│   │   ├── websocket.service.js      # WebSocket服务
│   │   ├── native-websocket.service.js # 原生WebSocket服务
│   │   ├── cache.service.js          # 缓存服务
│   │   ├── share.service.js          # 分享服务
│   │   └── export.service.js         # 导出服务
│   ├── routes/               # 路由定义
│   ├── middleware/           # 中间件
│   ├── database/            # 数据库配置
│   ├── utils/                # 工具函数
│   └── worker/               # 后台任务
├── package.json              # 依赖配置
├── .env                      # 环境变量
└── README.md                 # 项目说明
```

## 🚀 快速开始

### 环境要求
- Node.js >= 16.0.0
- PostgreSQL >= 12.0
- Redis >= 5.0

### 安装步骤

1. **克隆项目**
```bash
git clone <repository-url>
cd backend
```

2. **安装依赖**
```bash
npm install
```

3. **环境配置**
```bash
cp .env.example .env
# 编辑 .env 文件，配置数据库连接等信息
```

4. **数据库初始化**
```bash
# 创建数据库
createdb minguo_knowledge

# 执行初始化脚本
node execute_sql.js
```

5. **启动服务**
```bash
# 开发模式
npm run dev

# 生产模式
npm start
```

### Docker 部署

```bash
# 使用 Docker Compose 一键部署
docker-compose up -d
```

## 📊 数据库设计

### 核心数据表

| 表名 | 描述 | 主要字段 |
|------|------|----------|
| `users` | 用户表 | id, username, phone, total_credits, platform_openid |
| `questions` | 题目表 | id, content, type, options, correct_answer |
| `pass_levels` | 关卡表 | id, level_number, title, difficulty_level |
| `pk_rooms` | PK房间表 | id, room_code, creator_id, status, winner_id |
| `assessments` | 测评表 | id, title, description, question_count |
| `achievements` | 成就表 | id, name, description, credits_reward |

### 关系表
- `user_answers` - 用户答题记录
- `pass_records` - 闯关记录
- `pk_records` - PK对战记录
- `user_achievements` - 用户成就关联
- `credit_records` - 学分变动记录

## 🔌 API 接口

### 认证接口
- `POST /api/auth/login` - 平台登录
- `GET /api/users/me` - 获取当前用户信息

### 闯关接口
- `POST /api/passes/start` - 开始闯关
- `GET /api/passes/:passId/questions` - 获取题目
- `POST /api/passes/:passId/answer` - 提交答案
- `POST /api/passes/:passId/complete` - 完成闯关

### PK接口
- `POST /api/pk/rooms` - 创建房间
- `POST /api/pk/rooms/:roomCode/join` - 加入房间
- `GET /api/pk/rooms/:roomCode` - 获取房间信息

### 测评接口
- `GET /api/assessments` - 测评列表
- `POST /api/assessments/:assessmentId/start` - 开始测评
- `POST /api/assessments/:recordId/answer` - 提交答案
- `POST /api/assessments/:recordId/complete` - 完成测评

### WebSocket 事件
- `connection` - 连接建立
- `createRoom` - 创建房间
- `joinRoom` - 加入房间
- `startGame` - 开始游戏
- `answerQuestion` - 答题
- `gameOver` - 游戏结束
- `error` - 错误处理

## 🔒 安全设计

### 认证授权
- JWT Token 认证机制
- Token 过期自动刷新
- 权限验证中间件

### 数据安全
- 密码 bcrypt 加密存储
- 敏感数据加密传输
- SQL 注入防护
- XSS 攻击防护

### 接口安全
- 请求频率限制
- 参数验证过滤
- 错误信息脱敏

## ⚡ 性能优化

### 缓存策略
- Redis 缓存热门数据
- 排行榜定时缓存更新
- 题目数据预加载缓存

### 数据库优化
- 关键字段索引优化
- 查询语句性能优化
- 连接池管理

### 并发处理
- WebSocket 连接池管理
- 异步任务处理
- 消息队列机制

## 📈 监控日志

### 日志配置
```javascript
// 日志级别: error, warn, info, http, verbose, debug, silly
LOG_LEVEL=info

// 日志文件
logs/error.log    # 错误日志
logs/combined.log # 综合日志
```

### 监控指标
- 接口响应时间
- 数据库查询性能
- WebSocket 连接数
- 内存使用情况

## 🐛 错误处理

### 错误码规范
| 错误码 | 描述 | 解决方案 |
|--------|------|----------|
| 401 | 未授权 | 检查 Token 有效性 |
| 403 | 权限不足 | 验证用户权限 |
| 404 | 资源不存在 | 检查请求路径 |
| 500 | 服务器错误 | 查看服务日志 |
| 1001 | 闯关已结束 | 重新开始闯关 |
| 2001 | 房间不存在 | 检查房间代码 |
| 2002 | 房间已满 | 创建新房间 |

### 错误响应格式
```json
{
  "success": false,
  "error": {
    "code": 2001,
    "message": "房间不存在",
    "details": "请检查房间代码是否正确"
  }
}
```

## 🧪 测试

### 单元测试
```bash
# 运行所有测试
npm test

# 运行特定测试
npm run test:user
npm run test:auth
npm run test:pk
```

### 测试文件
- `test_login.js` - 登录功能测试
- `test_pass_flow.js` - 闯关流程测试
- `test_platform_login.js` - 平台登录测试
- `test_user_info.js` - 用户信息测试

## 📦 部署指南

### 生产环境部署

1. **环境准备**
```bash
# 安装 Node.js 和 PM2
npm install -g pm2

# 配置生产环境变量
cp .env.production .env
```

2. **构建部署**
```bash
# 安装依赖
npm install --production

# 启动服务
pm2 start ecosystem.config.js

# 查看服务状态
pm2 status
```

### Docker 部署
```yaml
# docker-compose.yml
version: '3.8'
services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
    depends_on:
      - postgres
      - redis

  postgres:
    image: postgres:13
    environment:
      - POSTGRES_DB=minguo_knowledge
      - POSTGRES_USER=admin
      - POSTGRES_PASSWORD=password

  redis:
    image: redis:6-alpine
```

## 🔄 开发规范

### 代码规范
- 使用 ESLint 进行代码检查
- 遵循 JavaScript Standard Style
- 函数注释使用 JSDoc 格式

### Git 提交规范
- feat: 新功能
- fix: 修复bug
- docs: 文档更新
- style: 代码格式调整
- refactor: 代码重构
- test: 测试相关

### 分支管理
- `main` - 主分支，生产环境
- `develop` - 开发分支
- `feature/*` - 功能分支
- `hotfix/*` - 热修复分支

## 🤝 贡献指南

1. Fork 本项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情

## 📞 联系方式

- 项目维护者: [维护者姓名]
- 邮箱: [邮箱地址]
- 项目地址: [GitHub 地址]

## 🙏 致谢

感谢所有为这个项目做出贡献的开发者！

---

**最后更新**: 2024年12月
**版本**: v1.0.0