# exer-web

**Repository Path**: linss813/exer-web

## Basic Information

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

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-04-24
- **Last Updated**: 2026-04-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 刷题应用 (ShuaTi App)

基于 React + TypeScript + Vite + Node.js 的本地刷题应用，支持 Excel 题库导入、多种刷题模式、错题管理、数据统计等功能。

## 技术栈

| 类别 | 技术 |
|------|------|
| 前端框架 | React 19 + TypeScript 6 |
| 构建工具 | Vite 8 |
| UI 组件库 | antd-mobile 5 |
| 状态管理 | Zustand 5 |
| 路由 | React Router 7 |
| 样式 | SCSS + CSS 变量（支持主题切换） |
| 后端 | Node.js + Express 5 |
| 数据存储 | 本地 JSON 文件 |
| Excel 解析 | SheetJS (xlsx) |
| 图表 | Recharts 3 |

## 功能特性

### 题库管理
- 从 Excel (.xlsx / .xls) 导入题库，支持多文件批量导入
- 每个 Sheet 自动作为独立模块/章节
- 高级导入：自定义列映射、选择工作表、设置默认题型、一键自动检测列名
- 题库重命名、删除（含关联答题记录/错题一并清除，二次确认）
- 题目编辑：修改题目内容、选项、答案、解析、所属模块，支持切换题型
- 题目搜索（关键词）+ 按题型筛选
- 删除单道题目
- 多题库勾选，可组合刷题；支持全选/取消全选

### 刷题模式
- **练习模式**：提交答案后即时显示对错和解析
- **背题模式**：直接展示答案，可标记已掌握 / 需复习，显示掌握进度
- 刷题范围选择：全部题目 / 按题型（单选/多选/判断）/ 按题库 / 按分表/章节
- 章节内支持进一步按题型细分启动
- 随机顺序、只刷未做题（实时显示剩余未做数量）
- 答题进度自动保存，下次进入从上次位置继续
- 单题计时 + 总用时实时显示
- 答题卡快速跳题，区分答对（绿）/ 答错（红）/ 未答
- 完成后展示总用时提示

### 错题本
- 答错自动记录，重复答错累计错误次数
- 未掌握 / 全部 两个 Tab 切换
- 错题复习模式：答对自动标记已掌握，答错累计次数
- 手动标记已掌握、删除单条错题

### 数据统计
- 总答题数、正确率、总题数（首页卡片）
- 近 7 天答题趋势折线图（答题数 + 正确数）
- 各题型正确率饼图
- 各题库正确率进度条
- 统计区域可折叠展开

### 其他
- 亮色 / 暗色 / 跟随系统 三档主题切换（首页及刷题页均可切换）
- 数据备份：一键打包 zip 到 `data/backups/`
- 刷题记录重置（二次确认，不影响错题本）
- 内置使用说明手册（帮助页面）
- 移动端适配

## 安装与运行

### 前置要求

- Node.js >= 18
- npm >= 9

### 安装依赖

```bash
cd exer-web
npm install
```

### 开发模式

```bash
npm run dev
```

- 前端：http://localhost:3000
- 后端 API：http://localhost:3033

### 单独启动

```bash
npm run client   # 仅前端（Vite dev server）
npm run server   # 仅后端（tsx watch）
```

## 生产部署

### 1. 构建

```bash
npm run build
```

构建产物：
- `dist/` — 前端静态文件
- `dist-server/` — 编译后的 Node 后端 + package.json

### 2. 部署到服务器

将以下目录复制到服务器：

```
dist/
dist-server/
```

### 3. 安装依赖并启动

```bash
cd dist-server
npm install --omit=dev
npm start
```

访问 `http://服务器IP:3033`，前后端均由此端口提供服务。

端口可通过环境变量覆盖：

```bash
PORT=8080 npm start
```

### 4. 使用 systemd 管理进程（推荐）

创建 `/etc/systemd/system/shuati.service`：

```ini
[Unit]
Description=Shuati Node.js App
After=network.target

[Service]
WorkingDirectory=/path/to/dist-server
ExecStart=/usr/bin/node index.js
Restart=always
Environment=PORT=3033

[Install]
WantedBy=multi-user.target
```

```bash
systemctl enable shuati
systemctl start shuati
```

### 数据目录

服务启动后自动在 `dist-server/` 同级创建 `data/` 目录，结构如下：

```
data/
├── banks/              # 每个题库一个 JSON 文件
├── records.json        # 答题记录
├── wrong_answers.json  # 错题本
├── progress.json       # 刷题进度
└── backups/            # 备份 zip 文件
```

迁移数据：直接复制 `data/` 目录到新机器即可。

## Excel 导入格式

### 支持题型

| 题型 | 答案格式 |
|------|---------|
| 单选题 | A / B / C / D |
| 多选题 | ABC 或 A,B,C |
| 判断题 | 对/错 或 T/F 或 正确/错误 |

### 必需列

- **题型**：单选题 / 多选题 / 判断题
- **题目**：题目内容
- **选项A～D**：各选项内容
- **正确答案**：对应上述格式

### 可选列

- **解析**：题目解析说明
- **模块/章节**：所属模块名称（不填则用 Sheet 名称）

### 多分表支持

Excel 中每个 Sheet 会自动作为独立模块，Sheet 名称即模块名。多个题库选中后，刷题页面按题库分组展示各自的模块。

### 高级导入

上传文件后可进行：
- 自定义列映射（适配任意列名的 Excel）
- 选择要导入的工作表
- 设置无法识别题型时的默认题型
- 一键自动检测常见列名

## 使用说明

应用内置使用说明手册，点击首页"📖 使用说明"查看，包含：

- 导入题库（快速导入 / 高级导入）
- 刷题模式详解
- 错题本使用
- 题库管理
- 主题切换
- 数据备份与恢复
- 数据统计说明

## 项目结构

```
exer-web/
├── server/
│   └── index.ts          # Express 后端（题库/记录/备份 API）
├── src/
│   ├── components/        # 公共组件（QuestionCard、AnswerSheet、ConfirmModal 等）
│   ├── hooks/             # 自定义 Hooks（useTheme、useQuestionData、useTouchOptimization）
│   ├── pages/             # 页面组件
│   │   ├── HomePage       # 首页（统计、菜单、备份）
│   │   ├── ModuleSelectPage  # 刷题范围选择
│   │   ├── QuizPage       # 刷题页（练习/背题模式）
│   │   ├── WrongAnswerPage   # 错题本
│   │   ├── BankManagePage    # 题库管理
│   │   ├── BankEditPage      # 题目编辑
│   │   ├── ImportPage        # 导入题库
│   │   └── HelpPage          # 使用说明
│   ├── stores/            # Zustand 状态管理（quizStore）
│   ├── styles/            # 全局样式 + CSS 变量（主题系统）
│   ├── types/             # TypeScript 类型定义
│   └── utils/             # 工具函数（Excel 解析、API 层、storage）
├── data/                  # 本地数据目录（运行时生成，已加入 .gitignore）
└── public/
```

## License

MIT