# 模板格式规范

## 一、对用户（模板提供方）的要求

### 必须遵守
| 要求 | 说明 |
|------|------|
| 标题样式 | 需要 AI 生成的段落，其标题必须应用 Word 内置标题样式（Heading 1~3） |
| 段落独立性 | 每个标题段落的内容应当主题独立，方便 AI 分别生成 |

### 强烈建议
| 建议 | 说明 |
|------|------|
| 正文提供参考内容 | 标题下的现有文本可作为 AI 生成的上下文，建议保留 |
| 表格上方有说明文字 | 表格前最好有一段文字说明，方便定位表格归属 |
| 文件名中文 | 模板文件名建议用中文，方便识别 |

### 不约束
| 项 | 说明 |
|----|------|
| 字体/配色/布局 | 不限，导出时完全保留 |
| 页眉页脚 | 不限，导出时完全保留 |
| 图片 | 不限，解析时保留占位，导出时保持不动 |
| 封面/附录 | 不限，不作为段落处理，导出时保留 |

## 二、解析规则（面向开发）

### 2.1 段落检测算法
```
for each paragraph in document.paragraphs:
    style = paragraph.style.name
    
    if style starts with "Heading":
        → 新段落开始
        → style 等级 = heading level (1~6)
        → 该段落为「标题段落」
    elif style is "Normal" or None:
        → 属于上一个标题段落的「正文内容」
        → 追加到 paragraph.content
    elif paragraph is inside a table cell:
        → 属于表格内容，跳过段落检测
```

### 2.2 表格归属
```
当前检测到的表格 → 归属于最近的标题段落
if 无标题段落:
    → 独立成段，段名 = "表格_{序号}"
```

### 2.3 样式捕获字段
对每个标题段落，捕获以下样式信息：
```json
{
  "font": {
    "name": "等线",
    "eastAsia": "等线",
    "size": 16,
    "bold": true,
    "italic": false,
    "color": "000000"
  },
  "paragraph": {
    "alignment": "CENTER",
    "spaceBefore": 12,
    "spaceAfter": 6,
    "lineSpacing": 1.5,
    "firstLineIndent": 0
  },
  "headingLevel": 1
}
```

### 2.4 表格样式捕获
```json
{
  "rows": 5,
  "cols": 6,
  "gridSpan": {},
  "cellStyles": [
    {
      "font": {"name": "宋体", "size": 10.5, "bold": false},
      "shading": "D9E2F3",
      "alignment": "CENTER",
      "borders": {"top": "single", "bottom": "single", "left": "single", "right": "single"}
    }
  ],
  "tableWidth": 5000
}
```

## 三、AI 输出解析规则

### 3.1 强制输出 JSON
```
在 prompt 末尾附加：
请以 JSON 格式返回，不要包含任何其他说明文字。
{
  "content": [
    {"type": "text|table", ...}
  ]
}
```

### 3.2 JSON 解析
```
收到 AI 响应后：
1. 尝试解析为 JSON
2. 若解析失败，尝试从响应的 ```json ``` 代码块中提取
3. 若仍然失败，将整个响应作为纯文本处理（type=text）
```

### 3.3 表格插入
```
当 type=table:
1. 在原始 docx 中找到该段落后面的第一个表格占位
2. 删除占位表格的 XML 节点
3. 创建新表格（python-docx add_table）
4. 逐格填充数据
5. 应用模板中该位置的表格样式（边框、底纹、对齐）
```

## 四、段落编辑方式

### 人工编辑
- 段落内容完全由用户手动输入
- 不参与 AI 生成流程
- 导出时保留用户输入的内容

### AI 生成
- 参与 AI 生成流程
- 可配置：生成模型、提示词、参考文件、输出格式
- 生成后可在预览编辑页手动修改