# DOC to Tables Skill

## 概述

将Word文档（.docx）转换为结构化Markdown表格，再生成专业HTML表格文件的完整工作流技能。适用于需要从非结构化文档中提取比赛获奖、考级成绩、荣誉证书等信息并转换为标准化表格格式的场景。

## 适用场景

- 钢琴/音乐比赛获奖名单整理
- 考级成绩汇总  
- 教师荣誉奖项统计
- 学生获奖情况整理
- 年度汇总报告制作
- 任何需要从Word文档提取结构化数据并生成表格的场景

## 输入要求

### 源文档格式
- Word文档（.docx）包含获奖/成绩/荣誉信息
- 文档中通常包含：
  - 比赛/考级名称作为标题
  - 学生姓名、奖项、指导教师等信息
  - 可能包含重复或不完整的指导教师信息

### 预期输出
- 结构化的Markdown文件（带正确表格格式）
- 专业的HTML文件（可直接用于海报制作）

## 工作流程

### 阶段1：文档分析与数据提取
1. **DOCX转Markdown**：使用pandoc保留原始标题层级结构
2. **数据模式识别**：分析文档中的信息模式（学生姓名、组别奖项、指导教师）
3. **重复数据去重**：识别相同奖项的多个获奖者，合并教师姓名

### 阶段2：Markdown表格整理
1. **统一表格结构**：
   - 三列表格：`|获奖学生|组别和奖项|指导老师|`
   - 两列表格：`|赛事/活动|奖项/荣誉|`
2. **智能标题适配**：
   - 简单奖项使用"奖项"列标题
   - 复杂奖项使用"组别和奖项"列标题
   - 考级项目保持完整信息（性别、级别、分数、评级）
3. **教师奖项优化**：
   - 相同奖项的教师合并到同一行
   - 使用逗号分隔多个教师姓名
   - 特殊奖项单独列出

### 阶段3：HTML表格生成
1. **响应式设计**：表格宽度100%自适应
2. **精确列宽控制**：
   - 三列表格：20% | 60% | 20%
   - 两列表格：70% | 30%
3. **专业样式**：
   - 表格边框和交替背景色
   - 教师奖项使用缩小字体
   - 支持打印和PDF导出

## 使用方法

### 基本用法
```bash
# 将Word文档转换为Markdown和HTML表格
python doc_to_tables.py "input.docx" "output"
```

### 高级选项
```bash
# 自定义列宽比例
python doc_to_tables.py "input.docx" "output" --three-col-widths "25,50,25" --two-col-widths "60,40"

# 包含教师奖项处理
python doc_to_tables.py "input.docx" "output" --process-teacher-awards

# 生成无表头HTML（适合海报制作）
python doc_to_tables.py "input.docx" "output" --no-headers
```

## 输出文件

- `{output}_md.md` - 结构化Markdown文件
- `{output}_html.html` - 专业HTML表格文件

## 技术特点

### 智能数据匹配
- 跨比赛匹配学生与指导教师
- 自动补全缺失的指导教师信息
- 处理双人/多人项目的指导教师合并

### 格式优化
- Markdown表格在Obsidian中完美显示
- HTML表格适合Photoshop导入和海报制作
- 支持中文字符和特殊符号

### 错误处理
- 自动检测和修复格式问题
- 缺失数据留空供后续补充
- 保留原始数据完整性

## 示例场景

### 音乐比赛获奖整理
**输入**：包含多个钢琴比赛获奖名单的Word文档
**输出**：
- Markdown表格按比赛分类，包含学生、奖项、指导教师
- HTML表格可直接用于制作年度喜报海报

### 考级成绩汇总  
**输入**：英皇、音协等考级成绩Word文档
**输出**：
- 结构化表格包含学生姓名、性别、级别、分数、评级、指导教师
- 专业HTML格式适合打印和展示

## 注意事项

1. **标题层级**：源文档应使用适当的标题层级（H1-H6）
2. **数据一致性**：学生姓名和教师姓名应保持一致拼写
3. **特殊字符**：支持中文、英文、数字和常见符号
4. **空值处理**：缺失的指导教师信息会留空，方便后续补充

## 依赖项

- pandoc (DOCX转Markdown)
- Python 3.6+
- fpdf2 (可选，用于PDF生成)

## 扩展性

此技能可轻松扩展以支持：
- Excel文件作为输入源
- 其他文档格式（PDF、PPT）
- 自定义表格样式和主题
- 多语言支持
- 自动化批量处理