# 项目上下文文档

## 项目概述

**项目名称**: 基于Tauri的新闻文本类别分类系统设计与实现

**项目类型**: 毕业设计项目 - 工程型系统设计 + 算法对比验证

**项目定位**: 在真实工程约束下，设计并实现一个"能用、好用、轻量"的新闻文本自动分类系统，并对分类方案进行对比与验证。

**一句话总结**: 设计并实现了一个基于 Tauri 的新闻文本分类系统，在系统中对比了多种文本分类方案的效果与性能，验证了在桌面端环境下混合分类策略的实用性。

---

## 项目结构

```
D:\tmp\write\news-classifier\
├── backend/              # 后端 Spring Boot 服务
├── client/               # 前端 Tauri + Vue3 桌面应用
├── crawler-module/       # 新闻爬虫模块 (Python)
├── ml-module/            # 机器学习分类模块 (Python)
├── docs/                 # 文档和数据库脚本
└── docker/               # Docker 部署配置
```

---

## 技术栈

### 后端技术栈
- **核心框架**: Spring Boot 3.5.6
- **Java版本**: JDK 17
- **数据库**: MySQL 8.0
- **ORM**: Spring Data JPA
- **安全认证**: Spring Security 6.x + JWT (jjwt 0.11.5)
- **API文档**: Springdoc OpenAPI 2.2.0
- **工具库**: Lombok
- **HTML解析**: Jsoup 1.17.2
- **HTTP客户端**: Apache HttpClient 5

### 前端技术栈
- **桌面框架**: Tauri 2.x (基于 Rust)
- **UI框架**: Vue 3.5.21 + Composition API + TypeScript
- **状态管理**: Pinia 2.2.6
- **路由**: Vue Router 4.5.0
- **样式**: Tailwind CSS 4.1.13
- **UI组件**: Reka UI (shadcn-vue 风格)
- **图标**: Lucide Vue Next
- **HTTP客户端**: Axios 1.7.9
- **构建工具**: Vite 7.1.7
- **包管理器**: pnpm 10.17.1+

### 爬虫模块技术栈
- **语言**: Python 3.9+
- **HTTP请求**: requests 2.31.0
- **HTML解析**: BeautifulSoup4 4.12.3 + lxml 5.1.0
- **动态页面**: Selenium 4.16.0
- **数据库**: pymysql 1.1.0 + DBUtils 3.0.3
- **配置管理**: pyyaml 6.0.1

### 机器学习模块
- **语言**: Python 3.9+
- **传统ML**: Scikit-learn 1.4.0 (朴素贝叶斯、SVM)
- **深度学习**: PyTorch 2.0+ + Transformers 4.30+ + BERT-Chinese
- **NLP**: jieba 0.42.1 (中文分词)
- **数据处理**: NumPy 1.24.0+, Pandas 2.0.0+
- **模型保存**: joblib 1.3.0+
- **API服务**: FastAPI 0.100.0 + Uvicorn
- **数据可视化**: Matplotlib 3.7.0, Seaborn 0.12.0

---

## 数据库设计

### 数据库信息
- **数据库名**: `news_classifier`
- **字符集**: utf8mb4
- **排序规则**: utf8mb4_unicode_ci

### 核心表结构

| 表名 | 用途 | 关键字段 |
|-----|------|---------|
| `sys_user` | 用户表 | id, username, password, role (ADMIN/USER), status |
| `news_category` | 新闻分类表 | id, name, code, description, sort_order |
| `news` | 新闻表 | id, url, title, content, category_id, category_code, publish_time, source, author |
| `news_tag` | 标签表 | id, name, color, use_count |
| `news_tag_relation` | 新闻标签关联表 | news_id, tag_id |
| `user_collect` | 用户收藏表 | user_id, news_id |
| `user_history` | 用户浏览历史表 | user_id, news_id, view_time, duration |
| `sys_log` | 操作日志表 | user_id, operation, method, ip, status, execute_time |
| `sys_config` | 系统配置表 | config_key, config_value, group |

### 初始化数据
- 默认管理员: `admin` / `admin123`
- 默认分类: 娱乐、体育、财经、科技、军事、汽车、政务、健康、AI

---

## 构建和运行

### 环境要求
- Java 17+
- Node.js 18.x+
- Python 3.9+
- MySQL 8.0+
- Rust 1.70+ (Tauri需要)
- pnpm 10.17.1+

### 后端启动

```bash
cd D:\tmp\write\news-classifier\backend

# 1. 配置数据库连接
# 编辑 src/main/resources/application.yml
# 修改数据库URL、用户名、密码

# 2. 初始化数据库
mysql -u root -p < D:\tmp\write\news-classifier\docs\schema.sql

# 3. 启动后端服务
mvn spring-boot:run
```

**后端服务地址**: http://localhost:8080
**API文档**: http://localhost:8080/swagger-ui.html

### 前端启动

```bash
cd D:\tmp\write\news-classifier\client

# 1. 安装依赖
pnpm install

# 2. 开发模式运行
pnpm run tauri:dev

# 3. 构建桌面应用
pnpm run tauri:build
```

### 爬虫模块启动

```bash
cd D:\tmp\write\news-classifier\crawler-module

# 1. 安装依赖
pip install -r requirements.txt

# 2. 配置数据库连接
# 编辑 config/config.yaml

# 3. 初始化数据库
# 执行 docs/database.md 中的SQL脚本

# 4. 运行爬虫
# 列出所有可用爬虫
python -m src.cli.main --list

# 运行单个爬虫
python -m src.cli.main netease:tech

# 运行所有爬虫
python -m src.cli.main --all

# 指定最大文章数
python -m src.cli.main netease:tech --max 5
```

### 机器学习模块启动

```bash
cd D:\tmp\write\news-classifier\ml-module

# 1. 创建虚拟环境
python -m venv venv
venv\Scripts\activate  # Windows

# 2. 安装依赖
pip install -r requirements.txt

# 3. 从MySQL拉取训练数据
python src/utils/data_loader.py

# 4. 训练BERT模型
python train_bert.py

# 5. 启动API服务
python src/api/server.py
```

### 使用 Docker

```bash
cd D:\tmp\write\news-classifier\docker

# 启动所有服务 (MySQL + Redis + Elasticsearch + Backend)
docker-compose up -d

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

---

## 开发规范

### 后端开发规范
- **架构模式**: 分层架构 (Controller -> Service -> Repository)
- **API设计**: RESTful 风格
- **统一响应**: 使用 `RestBean<T>` 包装返回结果
- **异常处理**: 全局异常处理器
- **日志记录**: 使用 SLF4J + Logback
- **代码生成**: 使用 Lombok 简化代码

### 前端开发规范
- **组件风格**: Composition API + `<script setup>`
- **类型安全**: 严格使用 TypeScript
- **状态管理**: Pinia stores (stores/news.ts, stores/user.ts)
- **路由**: Vue Router 4.x
- **样式**: Tailwind CSS 原子类
- **代码格式**: ESLint + Prettier

### 命名约定
- **Java**: 驼峰命名 (camelCase), 类名大驼峰 (PascalCase)
- **TypeScript**: 驼峰命名 (camelCase), 接口以 `I` 开头
- **数据库**: 下划线命名 (snake_case)
- **API路径**: kebab-case (如 `/api/v1/news/list`)

---

## 核心功能模块

### 1. 用户认证模块
- 用户注册/登录
- JWT令牌认证
- 权限控制 (ADMIN/USER)
- 刷新令牌

### 2. 新闻爬取模块 (Python)
- 多源新闻抓取 (网易、36氪等)
- 静态页面和动态页面(Selenium)支持
- HTML解析和内容提取
- 文本清洗和去重
- 批量存储到数据库
- 模块化设计，易于扩展

### 3. 文本分类模块
- **方案一**: TF-IDF + 朴素贝叶斯/SVM (传统机器学习)
- **方案二**: BERT-Chinese 微调 (深度学习)
- **方案三**: 混合策略 (规则 + 置信度阈值动态切换)
- GPU/CPU自动检测
- 动态参数调整

### 4. 新闻管理模块
- 新闻列表分页查询
- 新闻详情展示
- 全文搜索
- 按分类筛选
- 批量导入/导出

### 5. 数据可视化模块
- 分类统计图表
- 热门新闻排行
- 趋势分析
- ECharts 图表展示

### 6. 后台管理模块
- 用户管理
- 新闻审核
- 分类管理
- 系统配置
- 操作日志

---

## 文本分类算法

### 分类映射
```
娱乐 -> ENTERTAINMENT
体育 -> SPORTS
财经 -> FINANCE
科技 -> TECHNOLOGY
军事 -> MILITARY
汽车 -> AUTOMOTIVE
政务 -> GOVERNMENT
健康 -> HEALTH
AI -> ARTIFICIAL_INTELLIGENCE
```

### 分类器接口
- 传统机器学习分类器 (朴素贝叶斯、SVM)
- BERT深度学习分类器
- 混合策略分类器

### 分类结果
```json
{
  "categoryCode": "TECHNOLOGY",
  "categoryName": "科技",
  "confidence": 0.8756,
  "classifierType": "HYBRID",
  "probabilities": {...},
  "duration": 125
}
```

---

## 项目配置

### 后端配置文件
- **主配置**: `backend/src/main/resources/application.yml`

### 关键配置项
```yaml
server:
  port: 8080

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/news_classifier
    username: root
    password: root

classifier:
  mode: hybrid  # traditional, deep_learning, hybrid
  confidence-threshold: 0.75

jwt:
  secret: news-classifier-secret-key-2024
  expiration: 86400000  # 24小时
```

### 前端配置文件
- **环境变量**: `client/.env.development`
- **Tauri配置**: `client/src-tauri/tauri.conf.json`
- **Vite配置**: `client/vite.config.ts`

### 爬虫配置文件
- **主配置**: `crawler-module/config/config.yaml`

### 机器学习配置文件
- **主配置**: `ml-module/config.yaml`

---

## API文档

### 认证接口
- `POST /api/v1/user/register` - 用户注册
- `POST /api/v1/user/login` - 用户登录
- `GET /api/v1/user/info` - 获取用户信息 (需要认证)

### 分类接口
- `GET /api/v1/categories` - 获取所有分类
- `GET /api/v1/categories/with-count` - 获取分类及新闻数量
- `GET /api/v1/categories/{id}` - 获取分类详情
- `POST /api/v1/categories` - 创建分类
- `PUT /api/v1/categories/{id}` - 更新分类
- `DELETE /api/v1/categories/{id}` - 删除分类

### 新闻接口
- `GET /api/v1/news/list` - 分页查询新闻
- `GET /api/v1/news/{id}` - 获取新闻详情
- `GET /api/v1/news/search` - 搜索新闻
- `GET /api/v1/news/category/{categoryId}` - 按分类获取新闻
- `GET /api/v1/news/latest` - 获取最新新闻
- `GET /api/v1/news/statistics` - 获取新闻统计数据
- `POST /api/v1/news` - 创建新闻
- `PUT /api/v1/news` - 更新新闻
- `DELETE /api/v1/news/{id}` - 删除新闻
- `DELETE /api/v1/news/batch` - 批量删除新闻

### ML模块API接口
- `POST /api/predict` - 单条预测
- `POST /api/batch-predict` - 批量预测

---

## 预期成果

### 系统能力
- ✅ 能稳定导入1000+条新闻
- ✅ 分类准确率达到75%以上 (目标 > 85%)
- ✅ 单条分类响应时间 < 2秒
- ✅ 支持至少9个新闻类别
- ✅ 界面友好，操作流畅

### 毕业设计要求
- 完整的系统设计章节
- 清晰的算法对比实验
- 充分的数据分析
- 规范的论文格式
- 不少于1.5万字

---

## 常见问题

### Q1: 如何启动完整系统?
```bash
# 1. 启动数据库
mysql -u root -p < docs/schema.sql

# 2. 启动后端
cd backend
mvn spring-boot:run

# 3. 启动前端
cd client
pnpm run tauri:dev

# 4. (可选) 启动爬虫
cd crawler-module
python -m src.cli.main --all

# 5. (可选) 启动ML模块
cd ml-module
python src/api/server.py
```

### Q2: 默认管理员账号是什么?
- 用户名: `admin`
- 密码: `admin123`

### Q3: 如何训练分类模型?
```bash
cd ml-module
python src/utils/data_loader.py  # 拉取训练数据
python train_bert.py             # 训练BERT模型
```

### Q4: 分类模式有哪些?
- `traditional`: 传统机器学习 (朴素贝叶斯/SVM)
- `deep_learning`: 深度学习 (BERT)
- `hybrid`: 混合策略 (推荐)

### Q5: 如何添加新的爬虫?
1. 在 `crawler-module/src/crawlers/` 下创建新的爬虫类
2. 继承 `StaticCrawler` 或 `DynamicCrawler`
3. 在 `config/config.yaml` 中添加配置
4. 在 `src/cli/main.py` 中注册爬虫

---

## 项目作者

**姓名**: 张俊恒
**学院**: 软件学院
**班级**: 22级11班
**学号**: 2210121328

---

## 许可证

MIT License