# doc_format_check

**Repository Path**: swxu_2005/doc_format_check

## Basic Information

- **Project Name**: doc_format_check
- **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-04-23
- **Last Updated**: 2026-04-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 毕业设计论文格式审查工具

针对温州职业技术学院人工智能学院毕业设计文档格式规范的自动检查工具。

## 功能

| 检查类别 | 说明 |
|----------|------|
| 文档结构 | 封面→前言→目录→摘要→章节→致谢→参考文献→附录，章节编号连续性，TOC域 |
| 标题格式 | 一/二/三级标题的字号、字体、粗体、对齐、段前段后、行距、编号规则 |
| 正文格式 | 字体（宋体/TNR）、字号（五号）、首行缩进2字符、行距1.5倍、段前段后0磅 |
| 摘要与关键字 | 摘要字数、关键字字体/字号/分隔符 |
| 特殊页面 | 前言/目录/致谢/参考文献标题格式、全角空格、参考文献条目字号 |
| 图表格式 | 图表编号规则（章号.序号）、居中、首行无缩进、正文引用检测 |
| 页眉页码 | 页眉文字一致性、分节符检测 |
| 标点符号 | 中英文标点混用、括号全半角（启发式，默认开启） |

## 安装

```bash
pip install -r requirements.txt
```

## 使用

### 方式 A：命令行（单机脚本）

```bash
python -m checker.cli <论文.docx>

# 指定输出路径
python -m checker.cli <论文.docx> -o report.html
```

运行后会在同目录生成 `<文件名>_report.html` 格式审查报告。

### 方式 B：批量检查 → Excel 报告

对一个目录下的多份论文一次性检查，把每份论文的错误信息按 17 个分类分列汇总到一份 Excel：

```bash
# 默认仅记录 ERROR
python -m checker.batch <论文目录>

# 自定义输出路径与严重级别
python -m checker.batch <论文目录> -o 批量检查结果.xlsx \
    --severity ERROR --severity WARNING

# 仅扫描当前目录、不递归
python -m checker.batch <论文目录> --no-recursive
```

输出 Excel 与 `批量检查结果模板.xlsx` 同结构：首列为文件名，其后 17 列对应 17 个分类，
单元格里每条形如 `中文错误提示：错误内容`，多条以换行分隔。

**配置文件**：默认行为由 `checker/batch_config.default.json` 控制（默认仅记录 `ERROR`）。
若要自定义可拷贝该文件，修改后通过 `-c <path>` 指定：

```bash
cp checker/batch_config.default.json my_batch.json
# 编辑 my_batch.json
python -m checker.batch <论文目录> -c my_batch.json
```

主要字段：

| 字段 | 说明 |
|------|------|
| `include_severities` | 默认要写入报告的严重级别，默认 `["ERROR"]` |
| `include_rule_ids` | 强制额外写入的 rule_id（即使其 severity 未在列表里） |
| `exclude_rule_ids` | 强制排除的 rule_id |
| `max_issues_per_cell` | 单元格最多记录条数，0 = 不限 |
| `max_chars_per_cell` | 单元格最大字符数，避免触达 Excel 32767 限制 |
| `issue_format` | 单条记录模板，可用 `{message} {detail} {rule_id} {severity}` |
| `pattern` / `recursive` | 输入目录扫描通配符与是否递归 |

### 方式 C：Web 界面（多人使用）

面向多人共享部署的网页版。用户在浏览器里上传 .docx，页面内嵌展示审查报告，可一键下载 HTML 报告。

**上传文件不落盘**：整个处理流程只把 docx 以字节形式存在于进程内存中，请求结束立即释放，服务器不保留任何上传文件或生成的报告。

开发启动：

```bash
uvicorn webapp.main:app --reload --host 127.0.0.1 --port 8000
```

生产启动（多进程应对并发，约 50 并发推荐 4 workers）：

```bash
gunicorn webapp.main:app \
    -k uvicorn.workers.UvicornWorker \
    -w 4 -b 0.0.0.0:8000 --timeout 60
```

访问 http://localhost:8000 即可。

**限制与安全**：

- 单文件最大 20 MB（由 `webapp/main.py` 中 `MAX_UPLOAD_SIZE` 控制）
- 仅接受 `.docx`（同时校验 ZIP 文件头）
- 单请求超时 60 秒
- 日志只记录文件名、大小、耗时；不记录文档文本内容

## 测试样本

项目根目录下的 `samples/` 用于存放测试 `.docx` 文件及生成的 `_report.html`，该目录已加入 `.gitignore`，不会纳入版本控制。示例：

```bash
python -m checker.cli samples/毕业论文11\(2\).docx \
    -o samples/毕业论文11\(2\)_report.html
```

## 项目结构

```
doc_format_check/
├── checker/
│   ├── __init__.py
│   ├── cli.py              # CLI 入口
│   ├── pipeline.py         # 核心审查流水线（CLI / Web / 批量共用）
│   ├── loader.py           # docx 加载与信息提取（支持路径或 BytesIO）
│   ├── issues.py           # Issue / CheckResult 数据模型
│   ├── zones.py            # 文档分区识别
│   ├── report.py           # HTML 报告生成（Jinja2）
│   ├── batch.py            # 批量检查 → Excel 报告
│   ├── batch_config.default.json  # 批量检查默认过滤配置
│   └── rules/
│       ├── structure.py     # 文档结构完整性
│       ├── headings.py      # 标题格式
│       ├── body.py          # 正文格式
│       ├── abstract.py      # 摘要与关键字
│       ├── special_pages.py # 特殊页面（前言/目录/致谢/参考文献）
│       ├── figure_table.py  # 图表编号与格式
│       ├── page.py          # 页眉/页码/分节
│       └── punctuation.py   # 中英文标点
├── webapp/                 # Web 界面（可选，不影响 CLI）
│   ├── main.py             # FastAPI 应用与路由
│   ├── service.py          # 上传校验 + 调用核心流水线
│   └── templates/index.html# 拖拽上传 + 内嵌报告展示
├── samples/                # 测试样本与生成报告（gitignore）
├── requirements.txt
├── 格式简要说明.md
└── README.md
```

## 依赖

- Python 3.10+
- python-docx
- lxml
- Jinja2
- click
- openpyxl（批量 Excel 报告）
- fastapi / uvicorn / python-multipart / gunicorn（仅 Web 模式）