# Requirements Document

## Introduction

医疗报告智能生成系统（Medical Report Generator）是一个自动化工具，用于从医疗检测PDF报告中提取数据，通过AI分析生成健康评估和建议，并填充到专业的Word模板中生成完整的功能医学健康报告。

系统支持OCR识别、DeepSeek AI分析、模板保护区域管理、自动分页符处理等功能。

## Glossary

- **Report_Generator**: 医疗报告生成系统的核心模块
- **OCR_Service**: 百度OCR服务，用于从PDF中提取文本和数据
- **DeepSeek_Service**: DeepSeek AI服务，用于分析异常指标并生成健康评估内容
- **Template_Service**: Word模板处理服务，负责填充数据和格式化
- **Protected_Region**: 保护区域，指模板前四页（客户健康方案之前）的内容，不应被修改
- **Health_Program_Boundary**: 保护边界，"客户健康方案/Client Health Program"在文档中的位置
- **Module_Title**: 模块标题，如"血液学检测"、"内分泌检测"等分类标题
- **ABB**: 检测项目的缩写标识符
- **Clinical_Significance**: 临床意义，对检测结果的医学解释

## Requirements

### Requirement 1: PDF数据提取

**User Story:** As a 医疗报告操作员, I want to 从PDF医疗检测报告中自动提取数据, so that 我可以快速获取检测结果而无需手动输入。

#### Acceptance Criteria

1. WHEN 用户提供PDF医疗报告文件 THEN THE OCR_Service SHALL 使用百度OCR识别并提取所有文本内容
2. WHEN PDF包含检测数据表格 THEN THE OCR_Service SHALL 提取项目名称、结果值、参考范围、单位和异常标记
3. WHEN 提取完成 THEN THE Report_Generator SHALL 将数据保存为JSON格式的缓存文件
4. IF 缓存文件已存在且未强制刷新 THEN THE Report_Generator SHALL 使用缓存数据而非重新提取

### Requirement 2: 数据匹配与映射

**User Story:** As a 系统管理员, I want to 将提取的数据与模板字段进行匹配, so that 数据可以正确填充到报告模板中。

#### Acceptance Criteria

1. WHEN 数据提取完成 THEN THE Report_Generator SHALL 根据ABB配置文件将检测项目映射到对应的模板字段
2. WHEN 检测项目有异常标记（↑、↓、H、L） THEN THE Report_Generator SHALL 正确识别并记录异常状态
3. WHEN 检测项目无法通过配置文件匹配 THEN THE DeepSeek_Service SHALL 分析并分类该项目所属模块
4. IF 定性结果与参考范围相同 THEN THE Report_Generator SHALL 不将其标记为异常

### Requirement 3: 保护区域管理

**User Story:** As a 报告设计师, I want to 保护模板前四页的内容不被修改, so that 公司品牌信息和固定内容保持完整。

#### Acceptance Criteria

1. WHEN 文档处理开始 THEN THE Report_Generator SHALL 动态查找"客户健康方案/Client Health Program"位置作为保护边界
2. WHILE 处理文档内容 THEN THE Report_Generator SHALL 不修改保护边界之前的任何元素
3. WHEN 文档处理完成 THEN THE Report_Generator SHALL 从原始模板复制保护区域到输出文件
4. WHEN 验证输出文件 THEN THE Report_Generator SHALL 确保保护区域的XML元素与模板逐字节匹配
5. WHEN 验证输出文件 THEN THE Report_Generator SHALL 确保保护区域的媒体文件MD5与模板完全相同

### Requirement 4: AI健康评估生成

**User Story:** As a 功能医学专家, I want to 根据异常指标自动生成健康评估内容, so that 报告包含专业的医学分析。

#### Acceptance Criteria

1. WHEN 存在异常检测指标 THEN THE DeepSeek_Service SHALL 收集所有异常项并生成"整体健康状况评估"内容
2. WHEN 生成健康评估 THEN THE DeepSeek_Service SHALL 根据异常类型自动分成合适的小节（血液学、内分泌、免疫、代谢等）
3. WHEN 生成内容 THEN THE DeepSeek_Service SHALL 先写英文内容，然后逐句翻译为中文
4. WHEN 存在异常检测指标 THEN THE DeepSeek_Service SHALL 生成"功能医学健康建议"内容
5. WHEN 生成健康建议 THEN THE DeepSeek_Service SHALL 包含营养干预、运动干预、睡眠与压力管理、生活方式调整、长期随访计划五个固定小节

### Requirement 5: 临床意义解释生成

**User Story:** As a 医疗报告阅读者, I want to 看到每个检测项目的临床意义解释, so that 我可以理解检测结果的医学含义。

#### Acceptance Criteria

1. WHEN 添加新的检测项目表格 THEN THE DeepSeek_Service SHALL 为该项目生成Clinical Significance解释
2. WHEN 生成临床意义 THEN THE DeepSeek_Service SHALL 同时提供英文和中文版本
3. WHEN 填充临床意义 THEN THE Template_Service SHALL 使用正确的字体样式（英文Times New Roman 10.5pt，中文宋体12pt）

### Requirement 6: 文档格式化与分页

**User Story:** As a 报告阅读者, I want to 报告具有清晰的分页和格式, so that 内容易于阅读和打印。

#### Acceptance Criteria

1. WHEN 处理保护区域之后的图片 THEN THE Report_Generator SHALL 在每个图片前插入分页符
2. WHEN 处理模块标题 THEN THE Report_Generator SHALL 在模块标题前插入分页符（第一个模块除外）
3. WHEN 识别模块标题 THEN THE Report_Generator SHALL 排除长度超过50字符的文本
4. WHEN 识别模块标题 THEN THE Report_Generator SHALL 排除以"因此"、"所以"、"综上"开头的描述性文字
5. WHEN 识别模块标题 THEN THE Report_Generator SHALL 排除包含句号、逗号等标点的长句子

### Requirement 7: 表格创建与填充

**User Story:** As a 报告生成系统, I want to 为缺失的检测项目创建标准格式的表格, so that 所有检测数据都能正确显示。

#### Acceptance Criteria

1. WHEN 检测项目在模板中没有对应位置 THEN THE Template_Service SHALL 在对应模块内创建新表格
2. WHEN 创建表格 THEN THE Template_Service SHALL 包含ABB、项目名、结果、指标、参考范围、单位列
3. WHEN 创建表格 THEN THE Template_Service SHALL 包含Clinical Significance合并行
4. WHEN 设置表格边框 THEN THE Template_Service SHALL 使用顶部实线、其他虚线的样式

### Requirement 8: 空行清理与表格合并

**User Story:** As a 报告质量控制员, I want to 清理空白数据行并合并表格, so that 报告整洁无冗余。

#### Acceptance Criteria

1. WHEN 数据行的Result列为空 THEN THE Report_Generator SHALL 删除该空数据行
2. WHEN 表头下只有描述没有数据 THEN THE Report_Generator SHALL 删除描述并将下方数据表格内容移上来
3. WHILE 清理空行 THEN THE Report_Generator SHALL 不影响保护区域的内容

### Requirement 9: 报告输出与验证

**User Story:** As a 系统操作员, I want to 生成并验证最终报告, so that 我可以确保报告质量。

#### Acceptance Criteria

1. WHEN 报告生成完成 THEN THE Report_Generator SHALL 保存为带时间戳的DOCX文件
2. WHEN 验证报告 THEN THE Report_Generator SHALL 检查保护区域完整性
3. WHEN 验证报告 THEN THE Report_Generator SHALL 检查所有图片是否有分页符
4. WHEN 验证报告 THEN THE Report_Generator SHALL 检查模块标题是否有分页符

### Requirement 10: 命令行接口

**User Story:** As a 开发者, I want to 通过命令行参数控制报告生成, so that 我可以灵活配置运行选项。

#### Acceptance Criteria

1. WHEN 用户运行脚本 THEN THE Report_Generator SHALL 支持--method参数选择生成方法（extract或docxtpl）
2. WHEN 用户指定--force参数 THEN THE Report_Generator SHALL 强制重新提取数据而非使用缓存
3. WHEN 用户指定--deepseek参数 THEN THE Report_Generator SHALL 启用DeepSeek AI分析功能
4. WHEN 用户指定--api-key参数 THEN THE Report_Generator SHALL 使用指定的API密钥
5. IF 未指定API密钥但启用DeepSeek THEN THE Report_Generator SHALL 从环境变量DEEPSEEK_API_KEY获取
