# 2314班课程设计（个人碳账户）

**Repository Path**: fire-wall/Personal-Carbon

## Basic Information

- **Project Name**: 2314班课程设计（个人碳账户）
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-06
- **Last Updated**: 2026-06-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 个人碳账户 - 低碳积分平台

---

## 一、项目概述

本项目是一个基于 **Spring Boot + Vue 3** 的个人碳账户积分平台，通过量化用户的低碳行为给予积分奖励，鼓励公众参与低碳环保行动。

---

## 二、工程构成

本项目采用**前后端分离架构**，包含以下目录结构：

```
├── README.md              # 项目总说明文档（本文件）
├── README.txt             # 文本版本说明
├── sql/                   # 数据库脚本（可选）
├── backend/               # 后端工程（Spring Boot 3.2.x）
│   ├── README.md          # 后端工程说明
│   ├── pom.xml            # Maven依赖配置
│   └── src/               # 源代码目录
└── frontend/              # 前端工程（Vue 3.4.x）
    ├── README.md          # 前端工程说明
    ├── package.json       # npm依赖配置
    ├── vite.config.js     # Vite构建配置
    └── src/               # 源代码目录
```

---

## 三、各工程用途

### 3.1 后端工程（backend/）

**核心职责**：
- 提供 RESTful API 接口服务
- 处理业务逻辑和数据持久化
- 实现用户认证与权限控制（JWT）
- 提供 WebSocket 实时通信（排行榜实时更新）
- 监听端口：**8080**

**技术栈**：
- Spring Boot 3.2.x
- Spring Security 6.2.x
- Spring Data JPA
- Spring WebSocket
- MySQL 8.0+
- JWT 0.12.x
- Lombok

**关键模块**：
| 模块 | 说明 |
| :--- | :--- |
| controller | REST API 控制层 |
| service | 业务逻辑层 |
| repository | 数据访问层 |
| entity | JPA 实体类 |
| dto | 数据传输对象 |
| filter | JWT 认证过滤器 |
| aspect | AOP 切面（操作日志） |
| config | 配置类 |

### 3.2 前端工程（frontend/）

**核心职责**：
- 提供用户界面和交互体验
- 实现页面路由和状态管理（Pinia）
- 调用后端 API 获取数据
- 使用 Element Plus 构建响应式界面
- 监听端口：**5173**（开发环境）

**技术栈**：
- Vue 3.4.x
- Vite 6.5.x
- Element Plus 2.5.x
- Vue Router 4.3.x
- Pinia 2.1.x
- Axios 1.6.x
- SockJS + STOMP（WebSocket）

**关键模块**：
| 模块 | 说明 |
| :--- | :--- |
| views | 页面组件（用户端/管理端） |
| components | 公共组件 |
| api | 后端接口封装 |
| router | 路由配置 |
| store | Pinia 状态管理 |
| utils | 工具函数 |

---

## 四、核心功能模块

### 4.1 用户端功能
- ✅ 用户注册、登录（手机号+密码）
- ✅ 低碳行为打卡（步行、骑行、公交、地铁、光盘、回收、无纸化）
- ✅ 打卡审核流程（需管理员审核）
- ✅ 积分明细查看和统计
- ✅ 积分商城兑换商品
- ✅ 用户等级体系（5个等级）
- ✅ 徽章系统
- ✅ 实时排行榜（WebSocket 推送）
- ✅ 每日任务系统
- ✅ 个人数据统计可视化

### 4.2 管理端功能
- ✅ 用户管理（查看、禁用）
- ✅ 打卡审核（通过、拒绝、查看图片）
- ✅ 碳行为规则配置
- ✅ 商品管理（增删改查、库存）
- ✅ 等级配置
- ✅ 徽章管理
- ✅ 操作日志查看
- ✅ 运营数据大盘

---

## 五、启动顺序

**必须按照以下顺序启动**：

```
1. 启动 MySQL 数据库服务
   → 端口：3306
   → 数据库名：carbon_account

2. 启动后端工程（backend）
   cd backend
   mvn spring-boot:run

3. 启动前端工程（frontend）
   cd frontend
   npm install（首次运行需要）
   npm run dev
```

---

## 六、运行环境配置

### 6.1 数据库配置

```sql
-- 创建数据库
CREATE DATABASE IF NOT EXISTS carbon_account 
CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

### 6.2 后端配置

修改 `backend/src/main/resources/application.yml`：

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/carbon_account?useSSL=false&serverTimezone=Asia/Shanghai
    username: root
    password: your_password
```

### 6.3 前端配置

前端默认配置：
- API地址：`http://localhost:8080/api`
- WebSocket地址：`http://localhost:8080/ws`

---

## 七、测试账号

| 角色 | 用户名 | 密码 | 说明 |
| :--- | :--- | :--- | :--- |
| 管理员 | admin | admin123 | 拥有所有管理权限 |
| 普通用户 | user | user123 | 普通用户权限 |

---

## 八、访问地址

| 资源 | URL |
| :--- | :--- |
| 前端首页 | http://localhost:5173 |
| 管理后台 | http://localhost:5173/admin |
| 后端 API | http://localhost:8080/api |
| WebSocket | ws://localhost:8080/ws |

---

## 九、技术架构

### 9.1 后端架构

```
Controller层：接收请求，调用Service层
    ↓
Service层：业务逻辑处理，事务管理
    ↓
Repository层：数据访问（Spring Data JPA）
    ↓
数据库（MySQL）
```

**核心设计模式**：
- AOP 切面：操作日志记录
- Filter：JWT 认证过滤
- WebSocket：实时消息推送
- 观察者模式：用户等级提升事件监听

### 9.2 前端架构

```
路由层（Vue Router）
    ↓
视图层（Views/Pages）
    ↓
业务层（Components/API）
    ↓
状态层（Pinia Store）
    ↓
网络层（Axios/WebSocket）
```

**核心设计模式**：
- Composition API：Vue 3 组合式开发
- Pinia 状态管理：集中式状态管理
- Axios 封装：统一请求拦截和响应处理
- WebSocket 推送：实时排行榜更新

---

## 十、环境要求

### 10.1 后端环境
- JDK 21
- Maven 3.6+
- MySQL 8.0+

### 10.2 前端环境
- Node.js 18+
- npm 9+ 或 yarn 1.22+

---

## 十一、注意事项

1. **首次运行前必须先创建数据库**
2. **后端启动后会自动初始化默认数据**：
   - 管理员账号（admin/admin123）
   - 测试用户（user/user123）
   - 默认碳行为规则
   - 等级配置
   - 徽章配置
3. **前端首次运行需要执行 `npm install`**
4. **确保 MySQL 服务已启动且可连接**
5. **确保 JDK 21 和 Node.js 18+ 版本符合要求**
6. **打卡图片以 Base64 格式存储在数据库中**

---

## 十二、问题修复记录

| 问题描述 | 修复方案 | 状态 |
| :--- | :--- | :--- |
| 分页按钮始终请求第一页 | 将 `:current-page` 改为 `v-model:current-page` 双向绑定 | ✅ 已修复 |
| 打卡按钮不弹出表单 | 将 `:visible` 改为 `v-model` 控制对话框 | ✅ 已修复 |
| 审核列表已审核数据 500 错误 | 修复 ORDER BY 字段和类语法错误 | ✅ 已修复 |
| 图片不显示 | 添加 imageUrl 字段传递和 JSON 序列化注解 | ✅ 已修复 |
| 图片存储过长导致插入失败 | 将 image_url 字段改为 LONGTEXT 类型 | ✅ 已修复 |
| 审核接口 LocalDateTime 错误 | 添加缺失的 import 语句 | ✅ 已修复 |
| 审核后弹窗未关闭 | 添加 detailDialogVisible = false | ✅ 已修复 |
| 后台每日任务模块需隐藏 | 删除对应的菜单项 | ✅ 已修复 |
| Element Plus type=text 警告 | 将 type="text" 改为 type="link" | ✅ 已修复 |

---

## 十三、详细文档

各工程详细说明请查看对应文件：

- **后端工程**：`backend/README.md`
- **前端工程**：`frontend/README.md`
- **实验报告**：`docs/实验报告完整版.md`

---

**开发日期**：2026年6月  
**项目状态**：已完成核心功能开发与测试  
**总工程文件数**：README.md × 3（根目录/后端/前端）