第一次个人项目

---

这个作业属于哪个课程	https://edu.cnblogs.com/campus/gdgy/Class56-Grade2024-CS
这个作业要求在哪里	https://edu.cnblogs.com/campus/gdgy/Class56-Grade2024-CS/homework/15693
这个作业的目标	熟悉软件开发的流程

GitHub链接为：https://github.com/kaddyyds/kaddyyds/tree/main/3124004147

个人项目：论文查重系统

一、需求分析

1.1 项目简介

本项目实现论文文本查重功能，输入原文文件与待比对抄袭文本文件，程序自动完成文本清洗、分词、词袋构建，将最终相似度结果写入输出文件。

1.2 功能需求

需要从命令行接收三个参数：原文路径、待比对文本路径、结果输出文件路径，对文本预处理：去除全角/半角标点、特殊符号，保留中文、英文、数字。对中英文混合文本做分词，并构建词袋与词向量，使用余弦相似度计算文本相似度。最终将相似度写入输出文件。

1.3 非功能需求

鲁棒性：可处理乱码、空文件、超长文本等边界输入；性能：针对长文本做缓存优化，减少重复计算开销；可测试性：核心业务模块独立封装，便于编写单元测试。

二、算法设计与类结构

2.1 UML类图

项目包含4个核心类：

• TextPreprocessor：文本预处理类，清洗特殊符号、过滤无效字符。
• WordSegmenter：分词类，实现中英文混合文本分词逻辑。
• SimilarityCalculator：相似度计算类，构建词袋、生成向量、计算余弦相似度。
• Main：程序入口类，解析命令行参数、文件读写、调用各业务类、异常捕获、输出结果。

UML类图

2.2 项目目录结构

3124004147/
├─ main.py          # 主程序，包含四个核心类
├─ test_main.py     # 单元测试代码文件
├─ orig.txt         # 原文测试样例
├─ orig_add.txt     # 改写抄袭文本样例
└─ ans.txt          # 输出相似度结果文件

github仓库截图：

2.3 核心算法原理

采用词袋模型 + 余弦相似度。
对两段文本分别预处理、分词，提取所有词汇，构建全局词袋，然后根据词袋，分别生成两段文本的词频向量，最后通过向量点积除以两个向量模长乘积，得到余弦值，即为文本相似度。

\[\cos(\theta)=\frac{\vec{a}\cdot\vec{b}}{||\vec{a}|| \times ||\vec{b}||} \]

值越接近1代表文本越相似，越接近0代表几乎无重合。

三、PSP 个人软件过程表

阶段	预估耗时(min)	实际耗时(min)
需求分析	60	70
系统设计	90	110
编码实现	180	160
单元测试	120	140
性能优化	60	80
博客撰写与截图整理	90	100
合计	600	660

PSP解读

本次预估与实际耗时存在偏差，分析如下：
预估时间偏少，UML类图设计、边界场景思考花费额外时间；而文本预处理、余弦计算实现比预期顺利；

四、版本控制（Git）

4.1 Git提交记录说明

项目采用增量迭代开发，每完成一个功能模块进行一次commit，提交历史如下：

1. commit 1：初始化项目仓库，创建文件夹，搭建基础类框架
2. commit 2：完成TextPreprocessor文本预处理模块，实现特殊字符清洗
3. commit 3：完成WordSegmenter分词模块，支持中英文混合文本分词
4. commit 4：完成SimilarityCalculator类，实现词袋与余弦相似度计算
5. commit 5：增加文件IO异常捕获，处理GBK/UTF8两种文本编码
6. commit 6：新增test_main.py单元测试代码，编写10组测试用例
7. commit 7：修复空文本除零bug，优化循环逻辑，提升计算性能
8. commit 8：添加5组作业测试数据集orig文本文件，用于程序测试验证

五、单元测试

5.1 测试用例设计

共设计10组测试用例，覆盖大部分场景：
是文本去除标点符号、过滤混杂特殊符号文本、中英文混合文本分词、纯中文文本分词、两段完全相同文本相似度、两段完全无关文本相似度、其中一段为空文本的相似度、部分重合文本相似度、UTF-8编码文件读取、GBK编码文件读取测试

5.2 单元测试执行结果

10组测试用例全部执行通过，验证核心模块逻辑正确性。

5.3 代码覆盖率

使用pytest-cov统计核心业务代码覆盖率。入口Main类为集成入口，遵循工程实践不纳入单元测试统计；TextPreprocessor、WordSegmenter、SimilarityCalculator核心工具类完成全覆盖测试，覆盖率达标。

六、程序运行演示

在终端执行命令，传入原文文件、待比对文件、输出文件路径，程序运行完成后自动将相似度写入ans.txt。

python main.py orig.txt orig_add.txt ans.txt

七、静态代码分析 Code Quality Analysis

使用 pylint 静态代码扫描工具对项目代码进行检测，自动检查语法、代码规范、潜在异常。修复全部高优先级警告，保证代码健壮性与规范性。

八、性能分析与优化

8.1 cProfile 性能剖析

使用 Python 内置cProfile性能剖析工具采样程序运行过程，定位热点函数，找到耗时最高的模块。

8.2 优化前后对比

优化前，每次相似度计算都重复执行文本预处理、分词，长文本场景开销大。通过预处理与分词结果缓存，避免重复计算，精简正则表达式，减少字符遍历次数，达到相同长文本样例，整体运行耗时明显下降，减少冗余计算，内存占用降低的效果。

九、缺陷清单（Bug 记录）

9.1 程序异常容错处理

异常场景	触发条件	处理方式	对应测试方式
文件不存在	命令行传入错误文件路径，文件丢失	捕获文件读取异常，打印提示信息，程序正常退出	传入不存在的txt文件名测试
命令行参数数量不对	运行时传入参数少于/多于3个	打印使用帮助用法：python main.py 原文.txt 待比对.txt 输出.txt直接退出	少输入参数进行测试

9.2 程序异常容错处理

异常场景	触发条件	处理方式	对应测试方式
文件不存在	命令行传入错误文件路径，文件丢失	捕获文件读取异常，打印提示信息，程序正常退出	传入不存在的txt文件名测试
空文本输入	文件为空，或者全部是标点符号	向量模为0，直接返回相似度0.0，程序不抛出崩溃	传入空内容文件测试

十、项目总结与复盘

10.1 项目收获

通过本次个人编程项目，掌握面向对象程序设计，学会使用 UML 类图进行前期系统设计；理解词袋模型与余弦相似度算法原理；学会使用 Git 进行版本迭代管理；掌握单元测试、代码覆盖率检测、性能剖析等软件工程实践方法。

10.2 开发过程遇到的问题

在线安装 pytest 与 pytest‑cov的时候，用网线连接校园网导致不能下载，后续连接手机热点才下载到；Windows 记事本文件编码不统一，GBK 与 UTF8 混在一起，文件读取容易抛出编码异常。

10.3 过程改进计划

1. 后续项目在开发前期统一约定文件编码，提前设计异常分支。
2. 优先使用 Python 标准库完成基础功能，降低第三方库依赖，减少环境配置带来的阻碍。