# Word / PPT 规则导入设计

## 1. 背景

当前自定义规则导入支持 YAML、Markdown、TXT、Excel（.xlsx/.xls）格式，用户需要补充 Word（.docx）和 PowerPoint（.pptx）文件导入能力。

## 2. 目标

- 支持 .docx 文件导入：通过 mammoth 提取 Markdown 文本，AI 转换为规则 YAML
- 支持 .pptx 文件导入：通过 officeparser 提取幻灯片文本，AI 转换为规则 YAML
- 沿用现有 Converter 架构（RuleConverter 接口 + ImportService 注册机制）

## 3. 架构

### 3.1 数据流

```
setupView.ts (addRule)
    │
    ▼
ImportService.convert(srcPath, context)
    │
    ├── path.extname → DocxConverter (.docx)
    │   └── mammoth.extractRawText() / convertToMarkdown()
    │       └── Markdown 文本 → convertContentWithAI() → YAML
    │
    ├── path.extname → PptxConverter (.pptx)
    │   └── officeparser.parsePptx()
    │       └── 纯文本（幻灯片逐页分隔）→ convertContentWithAI() → YAML
    │
    └── parseImportableYaml() → 预览 → 写入 .code-review/rules/<name>.yaml
```

### 3.2 现有架构映射

| 组件 | 文件 | 说明 |
|------|------|------|
| RuleConverter 接口 | `src/rules/converters/converter.ts` | 不变 |
| ImportService | `src/rules/import-service.ts` | 不变 |
| convertContentWithAI | `src/rules/import-service.ts` | 复用 |
| setupView 注册 | `src/views/setupView.ts` | 新增两个 converter 注册 + 更新文件过滤器 |

## 4. 文件变更清单

| 文件 | 操作 | 说明 |
|------|------|------|
| `src/rules/converters/docx-converter.ts` | **新建** | .docx → mammoth → AI → YAML |
| `src/rules/converters/pptx-converter.ts` | **新建** | .pptx → officeparser → AI → YAML |
| `src/views/setupView.ts` | **修改** | 注册两个新 converter + 更新文件过滤器 |
| `package.json` | **修改** | 添加 mammoth + officeparser 依赖 |

## 5. 关键实现

### 5.1 DocxConverter

```typescript
// src/rules/converters/docx-converter.ts
// 依赖：mammoth（将 .docx 提取为 Markdown/HTML）
//
// 行为：
// 1. mammoth.convertToMarkdown() 提取 Markdown（含表格→Markdown 表格）
// 2. 将 Markdown 文本传入 convertContentWithAI()
// 3. AI 按已有 prompt 生成 YAML 规则
//
// 复用现有 buildSystemPrompt() 模式
// systemPrompt 与 md-converter.ts 相同（自然语言规则描述 → YAML）
// 由于 mammoth 已产出 Markdown，AI 可识别表格/段落/列表结构
```

### 5.2 PptxConverter

```typescript
// src/rules/converters/pptx-converter.ts
// 依赖：officeparser（将 .pptx 提取为纯文本）
//
// 行为：
// 1. officeparser.parsePptx() 提取所有幻灯片文本
// 2. 幻灯片之间用 "\n\n--- Slide N ---\n\n" 分隔
// 3. 合并文本传入 convertContentWithAI()
// 4. AI 按已有 prompt 生成 YAML 规则
//
// systemPrompt 与 md-converter.ts 相同
```

### 5.3 setupView.ts 变更

```typescript
// 1. 导入新 converter
import { DocxConverter } from '../rules/converters/docx-converter';
import { PptxConverter } from '../rules/converters/pptx-converter';

// 2. 构造函数中注册
this.importService.registerConverter(new DocxConverter());
this.importService.registerConverter(new PptxConverter());

// 3. addRule() 文件过滤器增加扩展名
filters: { '规则文件': ['yaml', 'yml', 'md', 'txt', 'xlsx', 'xls', 'docx', 'pptx'] },
```

### 5.4 package.json 依赖

```json
"dependencies": {
  ...,
  "mammoth": "^1.8.0",
  "officeparser": "^4.2.0"
}
```

## 6. 错误处理

| 场景 | 处理方式 |
|------|----------|
| docx 文件损坏 | mammoth 抛出异常 → try/catch 弹错误提示 → return null |
| pptx 文件损坏 | officeparser 抛出异常 → try/catch 弹错误提示 → return null |
| docx 无内容 | mammoth 返回空字符串 → convertContentWithAI 检测到空内容 → 弹"所选文件为空" |
| pptx 无内容 | officeparser 返回空字符串 → 同上 |
| officeparser 未安装依赖 | 运行时缺 jszip 报错 → catch 弹提示 |

## 7. 不涉及变更

- `converter.ts`：RuleConverter 接口不变
- `import-service.ts`：ImportService、convertContentWithAI、parseImportableYaml 均不变
- `import-preview.ts`：预览 Webview 不变
- `yaml-parser.ts`：运行时加载不变
- `rule-filter.ts`：规则过滤不变
- 其他 converter：不受影响
- 前端 webview JS（`src/views/setupView.js`）：无变更

## 8. 测试

新增文件不涉及现有测试变更。可通过以下方式验证：
1. 准备一个含规则表格的 .docx 文件和一个含规则列表的 .pptx 文件
2. 在设置面板中点击"+ 添加"，分别选择 .docx 和 .pptx 文件
3. 检查预览是否正确解析规则，命中等
4. 确认 .code-review/rules/ 下生成正确的 .yaml 文件