# 比赛备赛规划文档

## 一、赛题核心理解

### 1.1 赛题名称
**A23 - 基于大语言模型的文档理解与多源数据融合**
参赛院校：金陵科技学院

### 1.2 核心任务
1. **文档解析**：解析 docx/md/xlsx/txt 四种格式的源数据文档
2. **模板填写**：根据模板表格要求，从源文档中提取数据填写到 Word/Excel 模板
3. **准确率与速度**：准确率优先，速度作为辅助评分因素

### 1.3 评分规则
| 要素 | 说明 |
|------|------|
| 准确率 | 填写结果与样例表格对比的正确率 |
| 响应时间 | 从导入文档到得到结果的时间 ≤ 90s × 文档数量 |
| 评测方式 | 赛方提供空表格模板 + 样例表格（人工填写），系统自动填写后对比 |

### 1.4 关键Q&A摘录

| 问题 | 解答要点 |
|------|----------|
| Q2: 模板与文档的关系 | 前2个表格只涉及1份文档；第3-4个涉及多份文档；第5个涉及大部分文档（从易到难） |
| Q5: 响应时间定义 | 从导入文档到最终得到结果的时间 ≤ 90s × 文档数量 |
| Q7: 需要读取哪些文件 | 每个模板只读取指定的数据文件，不需要读取全部 |
| Q10: 部署方式 | 不要求部署到服务器，本地部署即可 |
| Q14: 模板匹配 | 模板已指定数据文件，不需要算法匹配 |
| Q16: 数据库存储 | 可跳过，不强制要求 |
| Q20: 创新点 | 不用管，随意发挥 |
| Q21: 填写依据 | 按照测试表格模板给的提示词进行填写 |

---

## 二、已完成功能清单

### 2.1 后端服务 (`backend/app/services/`)

| 服务文件 | 功能状态 | 说明 |
|----------|----------|------|
| `file_service.py` | ✅ 已完成 | 文件上传、保存、类型识别 |
| `excel_storage_service.py` | ✅ 已完成 | Excel 存储到 MySQL，支持 XML 回退解析 |
| `table_rag_service.py` | ⚠️ 已禁用 | RAG 索引构建（当前禁用，仅记录日志） |
| `llm_service.py` | ✅ 已完成 | LLM 调用、流式输出、多模型支持 |
| `markdown_ai_service.py` | ✅ 已完成 | Markdown AI 分析、分章节提取、流式输出、图表生成 |
| `excel_ai_service.py` | ✅ 已完成 | Excel AI 分析 |
| `visualization_service.py` | ✅ 已完成 | 图表生成（matplotlib） |
| `rag_service.py` | ⚠️ 已禁用 | FAISS 向量检索（当前禁用） |
| `prompt_service.py` | ✅ 已完成 | Prompt 模板管理 |
| `text_analysis_service.py` | ✅ 已完成 | 文本分析 |
| `chart_generator_service.py` | ✅ 已完成 | 图表生成服务 |
| `template_fill_service.py` | ✅ 已完成 | 模板填写服务，支持直接读取源文档进行填表 |

### 2.2 API 接口 (`backend/app/api/endpoints/`)

| 接口文件 | 路由 | 功能状态 |
|----------|------|----------|
| `upload.py` | `/api/v1/upload/excel` | ✅ Excel 文件上传与解析 |
| `documents.py` | `/api/v1/documents/*` | ✅ 文档管理（列表、删除、搜索） |
| `ai_analyze.py` | `/api/v1/analyze/*` | ✅ AI 分析（Excel、Markdown、流式） |
| `rag.py` | `/api/v1/rag/*` | ⚠️ RAG 检索（当前返回空） |
| `tasks.py` | `/api/v1/tasks/*` | ✅ 异步任务状态查询 |
| `templates.py` | `/api/v1/templates/*` | ✅ 模板管理 (含 Word 导出) |
| `visualization.py` | `/api/v1/visualization/*` | ✅ 可视化图表 |
| `health.py` | `/api/v1/health` | ✅ 健康检查 |

### 2.3 前端页面 (`frontend/src/pages/`)

| 页面文件 | 功能 | 状态 |
|----------|------|------|
| `Documents.tsx` | 主文档管理页面 | ✅ 已完成 |
| `ExcelParse.tsx` | Excel 解析页面 | ✅ 已完成 |

### 2.4 文档解析能力

| 格式 | 解析状态 | 说明 |
|------|----------|------|
| Excel (.xlsx/.xls) | ✅ 已完成 | pandas + XML 回退解析 |
| Markdown (.md) | ✅ 已完成 | 正则 + AI 分章节 |
| Word (.docx) | ✅ 已完成 | python-docx 解析，支持表格提取和字段识别 |
| Text (.txt) | ✅ 已完成 | chardet 编码检测，支持文本清洗和结构化提取 |

---

## 三、待完成功能（核心缺块）

### 3.1 模板填写模块（最优先）

**当前状态**：✅ 已完成

```
用户上传模板表格(Word/Excel)
         ↓
解析模板，提取需要填写的字段和提示词
         ↓
根据模板指定的源文档列表读取源数据
         ↓
AI 根据字段提示词从源数据中提取信息
         ↓
将提取的数据填入模板对应位置
         ↓
返回填写完成的表格
```

**已完成实现**：
- [x] `template_fill_service.py` - 模板填写核心服务
- [x] Word 模板解析 (`docx_parser.py` - parse_tables_for_template, extract_template_fields_from_docx)
- [x] Text 模板解析 (`txt_parser.py` - 已完成)
- [x] 模板字段识别与提示词提取
- [x] 多文档数据聚合与冲突处理
- [x] 结果导出为 Word/Excel

### 3.2 Word 文档解析

**当前状态**：✅ 已完成

**已实现功能**：
- [x] `docx_parser.py` - Word 文档解析器
- [x] 提取段落文本
- [x] 提取表格内容
- [x] 提取关键信息（标题、列表等）
- [x] 表格模板字段提取 (`parse_tables_for_template`, `extract_template_fields_from_docx`)
- [x] 字段类型推断 (`_infer_field_type_from_hint`)

### 3.3 Text 文档解析

**当前状态**：✅ 已完成

**已实现功能**：
- [x] `txt_parser.py` - 文本文件解析器
- [x] 编码自动检测 (chardet)
- [x] 文本清洗

### 3.4 文档模板匹配（已有框架）

根据 Q&A，模板已指定数据文件，不需要算法匹配。当前已有上传功能，需确认模板与数据文件的关联逻辑是否完善。

---

## 四、参赛材料准备

### 4.1 必交材料

| 材料 | 要求 | 当前状态 | 行动项 |
|------|------|----------|--------|
| 项目概要介绍 | PPT 格式 | ❌ 待制作 | 制作 PPT |
| 项目简介 PPT | - | ❌ 待制作 | 制作 PPT |
| 项目详细方案 | 文档 | ⚠️ 部分完成 | 完善文档 |
| 项目演示视频 | - | ❌ 待制作 | 录制演示视频 |
| 训练素材说明 | 来源说明 | ⚠️ 已有素材 | 整理素材文档 |
| 关键模块设计文档 | 概要设计 | ⚠️ 已有部分 | 完善文档 |
| 可运行 Demo | 核心代码 | ✅ 已完成 | 打包可运行版本 |

### 4.2 Demo 提交要求

根据 Q&A：
- 可以只提交核心代码，不需要完整运行环境
- 现场答辩可使用自带笔记本电脑
- 需要提供部署和运行说明（README）

---

## 五、测试验证计划

### 5.1 使用现有测试数据

```
docs/test/
├── 2023年文化和旅游发展统计公报.md
├── 2024年卫生健康事业发展统计公报.md
├── 第三次全国工业普查主要数据公报.md
```

### 5.2 模板填写测试流程

1. 准备一个 Word/Excel 模板表格
2. 指定源数据文档
3. 上传模板和文档
4. 执行模板填写
5. 检查填写结果准确率
6. 记录响应时间

### 5.3 性能目标

| 指标 | 目标 | 当前状态 |
|------|------|----------|
| 信息提取准确率 | ≥80% | 需测试验证 |
| 单次响应时间 | ≤90s × 文档数 | 需测试验证 |

---

## 六、工作计划（建议）

### 第一优先级：模板填写核心功能
- 完成 Word 文档解析
- 完成模板填写服务
- 端到端测试验证

### 第二优先级：Demo 打包与文档
- 制作项目演示 PPT
- 录制演示视频
- 完善 README 部署文档

### 第三优先级：测试优化
- 使用真实测试数据进行准确率测试
- 优化响应时间
- 完善错误处理

---

## 七、注意事项

1. **创新点**：根据 Q&A，不必纠结创新点数量限制
2. **数据库**：不强制要求数据库存储，可跳过
3. **部署**：本地部署即可，不需要公网服务器
4. **评测数据**：初赛仅使用目前提供的数据
5. **RAG 功能**：当前已临时禁用，不影响核心评测功能

---

*文档版本: v1.1*
*最后更新: 2026-04-08*

---

## 八、技术实现细节

### 8.1 模板填表流程（已实现）

#### 流程图
```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│ 上传模板    │ ──► │ 选择数据源   │ ──► │ AI 智能填表  │
└─────────────┘     └─────────────┘     └─────────────┘
                                               │
                                               ▼
                                        ┌─────────────┐
                                        │ 导出结果    │
                                        └─────────────┘
```

#### 核心组件

| 组件 | 文件 | 说明 |
|------|------|------|
| 模板上传 | `templates.py` `/templates/upload` | 接收模板文件，提取字段 |
| 字段提取 | `template_fill_service.py` | 从 Word/Excel 表格提取字段定义 |
| 文档解析 | `docx_parser.py`, `xlsx_parser.py`, `txt_parser.py` | 解析源文档内容 |
| 智能填表 | `template_fill_service.py` `fill_template()` | 使用 LLM 从源文档提取信息 |
| 结果导出 | `templates.py` `/templates/export` | 导出为 Excel 或 Word |

### 8.2 源文档加载方式

模板填表服务支持两种方式加载源文档：

1. **通过 MongoDB 文档 ID**：`source_doc_ids`
   - 文档已上传并存入 MongoDB
   - 服务直接查询 MongoDB 获取文档内容

2. **通过文件路径**：`source_file_paths`
   - 直接读取本地文件
   - 使用对应的解析器解析内容

### 8.3 Word 表格模板解析

比赛评分表格通常是 Word 格式，`docx_parser.py` 提供了专门的解析方法：

```python
# 提取表格模板字段
fields = docx_parser.extract_template_fields_from_docx(file_path)

# 返回格式
# [
#   {
#     "cell": "T0R1",  # 表格0，行1
#     "name": "字段名",
#     "hint": "提示词",
#     "field_type": "text/number/date",
#     "required": True
#   },
#   ...
# ]
```

### 8.4 字段类型推断

系统支持从提示词自动推断字段类型：

| 关键词 | 推断类型 | 示例 |
|--------|----------|------|
| 年、月、日、日期、时间、出生 | date | 出生日期 |
| 数量、金额、比率、%、率、合计 | number | 增长比率 |
| 其他 | text | 姓名、地址 |

### 8.5 API 接口

#### POST `/api/v1/templates/fill`

填写请求：
```json
{
  "template_id": "模板ID",
  "template_fields": [
    {"cell": "A1", "name": "姓名", "field_type": "text", "required": true, "hint": "提取人员姓名"}
  ],
  "source_doc_ids": ["mongodb_doc_id_1", "mongodb_doc_id_2"],
  "source_file_paths": [],
  "user_hint": "请从合同文档中提取"
}
```

响应：
```json
{
  "success": true,
  "filled_data": {"姓名": "张三"},
  "fill_details": [
    {
      "field": "姓名",
      "cell": "A1",
      "value": "张三",
      "source": "来自：合同文档.docx",
      "confidence": 0.95
    }
  ],
  "source_doc_count": 2
}
```

#### POST `/api/v1/templates/export`

导出请求：
```json
{
  "template_id": "模板ID",
  "filled_data": {"姓名": "张三", "金额": "10000"},
  "format": "xlsx"  // 或 "docx"
}
```