# zhuangyuan-java

**Repository Path**: shisenlin/zhuangyuan-java

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-20
- **Last Updated**: 2026-06-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🎓 小状元 - 家庭智能出题批改系统（后端）

<p align="center">
  <img src="https://img.shields.io/badge/Spring%20Boot-3.2.5-green?logo=springboot" />
  <img src="https://img.shields.io/badge/Java-17-orange?logo=openjdk" />
  <img src="https://img.shields.io/badge/JWT-0.12.5-blue" />
  <img src="https://img.shields.io/badge/JPA-Hibernate-purple" />
  <img src="https://img.shields.io/badge/license-MIT-brightgreen" />
</p>

> 一款面向家庭的智能数学出题与批改系统后端，支持按年级自动生成数学题、自动批改、积分奖励、错题本、积分商城等功能。

---

## 📖 目录

- [功能特性](#-功能特性)
- [技术架构](#-技术架构)
- [项目结构](#-项目结构)
- [环境要求](#-环境要求)
- [依赖下载与国内镜像配置](#-依赖下载与国内镜像配置)
- [快速启动](#-快速启动)
- [Docker 部署](#-docker-部署)
- [API 接口文档](#-api-接口文档)
- [数据库设计](#-数据库设计)
- [配置说明](#-配置说明)
- [常见问题](#-常见问题)

---

## ✨ 功能特性

### 🔐 用户认证
- 家长注册 / 登录（用户名 + 密码）
- JWT Token 无状态鉴权
- BCrypt 密码加密存储
- 角色区分：家长（PARENT）/ 孩子（CHILD）

### 👶 孩子管理
- 添加多个孩子，设置姓名、年龄、年级
- 支持 Emoji 头像选择
- 7 种主题风格切换（学院风、库洛米、哪吒、公主、冰雪奇缘、自然、太空）
- 主题配置持久化存储

### 📝 智能出题
- **按年级自动生成**：覆盖一年级到四年级知识点
- **题型丰富**：加法、减法、乘法、除法、混合运算、括号运算、百分数
- **练习模式**：自选题量，随时练习
- **正式考试**：A4 正反面共 42 题（前 25 题 + 后 17 题），模拟真实考试

### ✅ 自动批改
- 提交答案后即时批改
- 逐题显示正确答案与对错
- 按知识点归类错题

### 🏆 积分系统
- 正式考试根据得分奖励积分（满分 10 分，≥90 分 8 分，≥80 分 6 分，≥70 分 4 分，≥60 分 2 分）
- 积分历史记录追踪
- 练习模式不计积分

### 📕 错题本
- 自动记录所有错题
- 按知识点统计错题分布
- 支持错题强化练习

### 🎁 积分商城
- 家长添加 / 管理礼品（名称、价格、图标、库存）
- 孩子用积分兑换礼品
- 家长审批流程（待审批 → 通过 / 拒绝）
- 拒绝自动退还积分

---

## 🏗 技术架构

```
┌─────────────────────────────────────────────────────┐
│                    Flutter App                       │
│              (Android / iOS / Web)                   │
└──────────────────────┬──────────────────────────────┘
                       │ HTTP / REST API
                       ▼
┌─────────────────────────────────────────────────────┐
│              Spring Boot Application                 │
│  ┌───────────────────────────────────────────────┐  │
│  │            Security Layer (JWT)                │  │
│  │  ┌─────────────────────────────────────────┐  │  │
│  │  │          Controller Layer                │  │  │
│  │  │  AuthController  ChildController         │  │  │
│  │  │  ExamController  GiftController          │  │  │
│  │  └──────────────┬──────────────────────────┘  │  │
│  │                 ▼                             │  │
│  │  ┌─────────────────────────────────────────┐  │  │
│  │  │          Service Layer                   │  │  │
│  │  │  AuthService  ExamService  GiftService   │  │  │
│  │  └──────────────┬──────────────────────────┘  │  │
│  │                 ▼                             │  │
│  │  ┌─────────────────────────────────────────┐  │  │
│  │  │       Repository Layer (JPA)             │  │  │
│  │  │  User  Child  Question  ExamRecord       │  │  │
│  │  │  WrongQuestion  Gift  RedeemRecord       │  │  │
│  │  │  PointsHistory                           │  │  │
│  │  └──────────────┬──────────────────────────┘  │  │
│  └─────────────────┼─────────────────────────────┘  │
└────────────────────┼────────────────────────────────┘
                     ▼
        ┌────────────────────────┐
        │     Database           │
        │  H2 (开发) / PostgreSQL │
        │          (生产)         │
        └────────────────────────┘
```

### 技术栈

| 组件 | 技术 | 版本 | 说明 |
|------|------|------|------|
| 框架 | Spring Boot | 3.2.5 | 应用框架 |
| 语言 | Java | 17 | LTS 版本 |
| ORM | Spring Data JPA + Hibernate | 6.4.4 | 数据持久化 |
| 安全 | Spring Security + JWT | 6.2.4 / 0.12.5 | 认证鉴权 |
| 数据库 | H2 / PostgreSQL | 2.2.224 / 15 | 开发 / 生产 |
| 工具 | Lombok | 内置 | 简化代码 |
| 映射 | ModelMapper | 3.1.1 | DTO 转换 |
| 容器 | Docker + Docker Compose | - | 容器化部署 |

---

## 📁 项目结构

```
zhuangyuan-java/
├── src/main/java/com/zhuangyuan/
│   ├── ZhuangYuanApplication.java          # 启动类
│   ├── config/
│   │   ├── SecurityConfig.java             # Spring Security + JWT 过滤器配置
│   │   ├── JwtUtil.java                    # JWT 工具类（生成/解析/验证）
│   │   └── GlobalExceptionHandler.java     # 全局异常处理器
│   ├── controller/
│   │   ├── AuthController.java             # 认证接口（注册/登录）
│   │   ├── ChildController.java            # 孩子管理接口
│   │   ├── ExamController.java             # 考试接口（出题/提交）
│   │   └── GiftController.java             # 礼品/兑换/错题/积分接口
│   ├── dto/
│   │   ├── AuthDto.java                    # 认证请求/响应 DTO
│   │   ├── ChildDto.java                   # 孩子相关 DTO
│   │   ├── ExamDto.java                    # 考试相关 DTO
│   │   └── GiftDto.java                    # 礼品相关 DTO
│   ├── entity/
│   │   ├── User.java                       # 用户实体
│   │   ├── Child.java                      # 孩子实体
│   │   ├── Question.java                   # 题目实体
│   │   ├── ExamRecord.java                 # 考试记录实体
│   │   ├── WrongQuestion.java              # 错题实体
│   │   ├── Gift.java                       # 礼品实体
│   │   ├── RedeemRecord.java               # 兑换记录实体
│   │   └── PointsHistory.java              # 积分历史实体
│   ├── repository/                         # JPA Repository 接口
│   └── service/
│       ├── AuthService.java                # 认证服务
│       ├── ExamService.java                # 考试服务（出题/批改）
│       └── GiftService.java                # 礼品/兑换服务
├── src/main/resources/
│   └── application.yml                     # 应用配置
├── Dockerfile                              # Docker 镜像构建
├── docker-compose.yml                      # Docker Compose 编排
├── check_compile.sh                        # 编译检查脚本
├── start.sh                                # 一键启动脚本
└── pom.xml                                 # Maven 配置
```

---

## 📋 环境要求

| 工具 | 最低版本 | 推荐版本 | 说明 |
|------|----------|----------|------|
| JDK | 17 | 17 LTS | [下载地址](#jdk-17) |
| Maven | 3.8 | 3.9+ | [下载地址](#maven) |
| Docker | 20.0+ | 最新 | 可选，用于容器化部署 |
| Docker Compose | 2.0+ | 最新 | 可选，用于编排 |

---

## 🔽 依赖下载与国内镜像配置

### JDK 17

**官方下载：**
- Adoptium (Eclipse Temurin): https://adoptium.net/temurin/releases/?version=17
- Azul Zulu: https://www.azul.com/downloads/?version=java-17-lts&os=linux&architecture=x86-64-bit&package=jdk

**国内镜像：**
- 华为镜像: https://repo.huaweicloud.com/java/jdk/
- 清华镜像: https://mirrors.tuna.tsinghua.edu.cn/Adoptium/

**快速安装（Ubuntu/Debian）：**
```bash
# Ubuntu/Debian
sudo apt install openjdk-17-jdk

# CentOS/RHEL
sudo yum install java-17-openjdk-devel

# macOS
brew install openjdk@17

# 验证
java -version
```

### Maven

**官方下载：**
- https://maven.apache.org/download.cgi

**国内镜像配置（重要！加速依赖下载）：**

创建或编辑 `~/.m2/settings.xml`：

```xml
<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.2.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.2.0
          https://maven.apache.org/xsd/settings-1.2.0.xsd">
  <mirrors>
    <!-- 阿里云 Maven 镜像 -->
    <mirror>
      <id>aliyunmaven</id>
      <mirrorOf>*</mirrorOf>
      <name>阿里云公共仓库</name>
      <url>https://maven.aliyun.com/repository/public</url>
    </mirror>
  </mirrors>
</settings>
```

**其他国内镜像源：**

| 名称 | 地址 | 说明 |
|------|------|------|
| 阿里云 | `https://maven.aliyun.com/repository/public` | 推荐，最稳定 |
| 腾讯云 | `https://mirrors.cloud.tencent.com/nexus/repository/maven-public/` | 备选 |
| 华为云 | `https://repo.huaweicloud.com/repository/maven/` | 备选 |
| 中央仓库 | `https://repo.maven.apache.org/maven2` | 官方源（慢） |

---

## 🚀 快速启动

### 方式一：直接运行（开发推荐）

```bash
# 1. 克隆项目
git clone https://gitee.com/shisenlin/zhuangyuan-java.git
cd zhuangyuan-java

# 2. 编译打包（跳过测试）
mvn clean package -DskipTests

# 3. 运行（默认使用 H2 内存数据库，无需额外安装数据库）
java -jar target/zhuangyuan-backend-1.0.0.jar

# 4. 访问
# API: http://localhost:8080
# H2 控制台: http://localhost:8080/h2-console
```

### 方式二：Maven 直接运行

```bash
mvn spring-boot:run
```

### 方式三：Docker Compose 一键部署（生产推荐）

```bash
# 启动（包含 PostgreSQL 数据库 + 后端服务）
bash start.sh start

# 或手动
docker compose up -d --build

# 查看日志
bash start.sh logs

# 停止
bash start.sh stop
```

---

## 🐳 Docker 部署

### Dockerfile

```dockerfile
# 构建阶段
FROM maven:3.9-eclipse-temurin-17-alpine AS build
WORKDIR /app
COPY pom.xml .
RUN mvn dependency:go-offline -B
COPY src ./src
RUN mvn package -DskipTests -B

# 运行阶段
FROM eclipse-temurin:17-jre-alpine
WORKDIR /app
COPY --from=build /app/target/*.jar app.jar
RUN mkdir -p data/uploads
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]
```

### docker-compose.yml

```yaml
services:
  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: zhuangyuan
      POSTGRES_USER: zhuangyuan
      POSTGRES_PASSWORD: zhuangyuan123
    volumes:
      - pgdata:/var/lib/postgresql/data
    ports:
      - "5432:5432"

  backend:
    build: .
    ports:
      - "8080:8080"
    environment:
      DB_HOST: db
      DB_PORT: 5432
      DB_NAME: zhuangyuan
      DB_USER: zhuangyuan
      DB_PASS: zhuangyuan123
      JWT_SECRET: your-very-long-secret-key-here
    depends_on:
      - db

volumes:
  pgdata:
```

### 切换到 PostgreSQL 生产数据库

设置环境变量或修改 `application-prod.yml`：

```yaml
spring:
  datasource:
    url: jdbc:postgresql://${DB_HOST}:${DB_PORT}/${DB_NAME}
    username: ${DB_USER}
    password: ${DB_PASS}
    driver-class-name: org.postgresql.Driver
  jpa:
    hibernate:
      ddl-auto: update
    properties:
      hibernate:
        dialect: org.hibernate.dialect.PostgreSQLDialect
```

---

## 📡 API 接口文档

### 认证接口（无需 Token）

| 方法 | 路径 | 说明 | 请求体 |
|------|------|------|--------|
| POST | `/api/auth/register` | 用户注册 | `{username, password, nickname}` |
| POST | `/api/auth/login` | 用户登录 | `{username, password}` |

### 孩子管理（需要 Token）

| 方法 | 路径 | 说明 | 请求体 |
|------|------|------|--------|
| GET | `/api/children` | 获取孩子列表 | - |
| POST | `/api/children` | 添加孩子 | `{name, age, grade, avatar}` |
| PUT | `/api/children/{id}/theme` | 更新主题 | `{theme}` |

### 考试接口（需要 Token）

| 方法 | 路径 | 说明 | 请求体 |
|------|------|------|--------|
| POST | `/api/exam/generate` | 生成练习题 | `{childId, count}` |
| POST | `/api/exam/generate-test` | 生成正式考试(42题) | `{childId}` |
| POST | `/api/exam/submit` | 提交答案 | `{examId, childId, examType, answers[]}` |

### 礼品 / 兑换 / 错题 / 积分（需要 Token）

| 方法 | 路径 | 说明 | 请求体 |
|------|------|------|--------|
| GET | `/api/gifts` | 获取礼品列表 | - |
| POST | `/api/gifts` | 添加礼品 | `{name, price, icon, stock}` |
| DELETE | `/api/gifts/{id}` | 删除礼品（下架） | - |
| POST | `/api/redeem` | 兑换礼品 | `{childId, giftId}` |
| GET | `/api/redeem/{childId}` | 获取兑换记录 | - |
| GET | `/api/redeem/pending/list` | 待审批列表 | - |
| POST | `/api/redeem/{id}/approve` | 审批通过 | - |
| POST | `/api/redeem/{id}/reject` | 审批拒绝 | - |
| GET | `/api/wrong/{childId}` | 错题列表 | - |
| GET | `/api/wrong/stats/{childId}` | 错题知识点统计 | - |
| GET | `/api/points/{childId}` | 积分历史 | - |
| GET | `/api/exam-records/{childId}` | 考试记录 | - |

### 请求示例

```bash
# 注册
curl -X POST http://localhost:8080/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username":"parent1","password":"123456","nickname":"家长"}'

# 登录获取 Token
curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"parent1","password":"123456"}'

# 使用 Token 访问
curl http://localhost:8080/api/children \
  -H "Authorization: Bearer <your-token>"
```

---

## 🗄 数据库设计

### ER 关系图

```
User (用户)
 ├── 1:N ── Child (孩子)
 │          ├── 1:N ── ExamRecord (考试记录)
 │          ├── 1:N ── WrongQuestion (错题)
 │          ├── 1:N ── PointsHistory (积分历史)
 │          └── 1:N ── RedeemRecord (兑换记录)
 └── 1:N ── Gift (礼品，创建者)

Question (题目库)
 └── 被 ExamRecord 引用
```

### 核心表结构

| 表名 | 说明 | 主要字段 |
|------|------|----------|
| `users` | 用户表 | id, username, password, nickname, role |
| `children` | 孩子表 | id, parent_id, name, age, grade, avatar, points, theme |
| `questions` | 题目表 | id, subject, grade_level, knowledge_point, content, answer |
| `exam_records` | 考试记录 | id, child_id, exam_type, question_ids, score, points_earned |
| `wrong_questions` | 错题表 | id, child_id, question_id, wrong_answer, correct_answer |
| `gifts` | 礼品表 | id, name, price, icon, stock, is_active |
| `redeem_records` | 兑换记录 | id, child_id, gift_id, points, status |
| `points_history` | 积分历史 | id, child_id, type, points, description |

---

## ⚙ 配置说明

### application.yml 核心配置

```yaml
server:
  port: 8080                    # 服务端口

spring:
  datasource:
    url: jdbc:h2:mem:testdb     # 开发用 H2 内存数据库
  jpa:
    hibernate:
      ddl-auto: update          # 自动建表（生产环境建议用 flyway）

jwt:
  secret: xxx                   # JWT 签名密钥（生产环境必须修改！）
  expiration: 604800000         # Token 有效期 7 天（毫秒）

baidu:
  ocr:
    api-key: ${BAIDU_OCR_API_KEY:}    # 百度 OCR API Key（可选）
    secret-key: ${BAIDU_OCR_SECRET_KEY:}

upload:
  dir: ${UPLOAD_DIR:./data/uploads}   # 文件上传目录
```

### 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `DB_HOST` | 数据库地址 | localhost |
| `DB_PORT` | 数据库端口 | 5432 |
| `DB_NAME` | 数据库名 | zhuangyuan |
| `DB_USER` | 数据库用户 | zhuangyuan |
| `DB_PASS` | 数据库密码 | zhuangyuan123 |
| `JWT_SECRET` | JWT 密钥 | 内置开发密钥 |
| `BAIDU_OCR_API_KEY` | 百度 OCR Key | 空 |
| `UPLOAD_DIR` | 上传目录 | ./data/uploads |

---

## ❓ 常见问题

### Q: Maven 下载依赖太慢？
配置国内镜像，参考 [Maven 镜像配置](#maven)。

### Q: 如何切换到 PostgreSQL？
设置环境变量 `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASS`，或创建 `application-prod.yml` 并激活 `prod` profile。

### Q: JWT Token 过期时间怎么改？
修改 `application.yml` 中的 `jwt.expiration`，单位毫秒。默认 604800000（7 天）。

### Q: 如何添加新的年级题型？
编辑 `ExamService.java` 中的 `TEMPLATES` Map，添加新的年级和题型模板。

### Q: 生产环境需要注意什么？
1. 修改 `jwt.secret` 为随机长字符串
2. 使用 PostgreSQL 替代 H2
3. 配置 HTTPS
4. 修改 `ddl-auto` 为 `validate` 或使用 Flyway
5. 配置日志级别

---

## 📄 License

MIT License