# ETF轮动项目文档创建规范

> 规范版本：v1.0
> 制定日期：2026-06-21

---

## 1. 文件命名规范

### 1.1 基本格式

```
YYYYMMDD_中文名称.md
```

- **日期来源**：文档首次创建的git提交日期
- **命名原则**：日期前缀 + 简洁中文描述
- **禁止字符**：空格、特殊符号（除 `_` 和 `-`）

### 1.2 命名示例

| 类型 | 示例 |
|------|------|
| 分析报告 | `20260607_select_num_1深度分析.md` |
| 调研报告 | `20260606_动量因子对比调研.md` |
| 实验记录 | `20260617_010_起始年份敏感性分析.md` |
| 架构设计 | `20260507_通用数据源架构.md` |
| 核心逻辑 | `20260430_轮动策略核心逻辑.md` |
| 版本迭代 | `20260519_轮动策略核心逻辑_v3.md` |

### 1.3 特殊场景

- **实验编号**：experiments目录下保留编号前缀，格式 `YYYYMMDD_编号_名称.md`
- **版本号**：迭代版本在末尾加 `_vN`，如 `_v2`、`_v3`
- **Git标识**：阶段性总结可带commit hash，如 `_ca933e4`

---

## 2. 文档分类与头部格式

### 2.1 分析报告类

**适用场景**：策略分析、回测分析、深度分析

**头部格式**：

```markdown
# [报告标题]

> 分析日期：YYYY-MM-DD
> 策略版本：[配置文件/代码版本说明]
> 回测区间：YYYY-MM-DD ~ YYYY-MM-DD（约 N 个交易日）

## 1. [章节标题]
...
```

**必填字段**：
- 分析日期：文档创建日期
- 策略版本：基于的配置文件或代码版本
- 回测区间：数据时间范围

---

### 2.2 调研报告类

**适用场景**：技术调研、因子调研、文献综述

**头部格式**：

```markdown
# [调研标题]

> 调研日期：YYYY-MM-DD
> 回测区间：YYYY-MM-DD ~ YYYY-MM-DD（可选）
> 当前结论：[核心发现摘要]

---

## 1. [章节标题]
...
```

**必填字段**：
- 调研日期：文档创建日期

**可选字段**：
- 回测区间：如有回测实验
- 当前结论：调研核心发现

---

### 2.3 实验记录类（experiments目录）

**适用场景**：对比实验、参数优化、敏感性分析

**头部格式**：

```markdown
# 实验记录 XXX: [实验名称]

## 实验信息

| 项目 | 内容 |
|------|------|
| 实验编号 | XXX |
| 实验日期 | YYYY-MM-DD |
| 实验类型 | [类型分类] |
| 研究问题 | [问题描述] |
| 配置文件 | `[配置路径]` |
| 实验脚本 | `[脚本路径]` |

---

## 1. 实验背景
...
```

**必填字段**：
- 实验编号：三位数字，如 001、010
- 实验日期：文档创建日期
- 实验类型：如"参数优化"、"对比实验"、"敏感性分析"
- 研究问题：一句话描述研究目标
- 配置文件：使用的配置文件路径
- 实验脚本：运行的脚本路径

---

### 2.4 技术架构类

**适用场景**：系统架构、模块设计、接口说明

**头部格式**：

```markdown
# [模块名称] - 架构设计

## 设计目标

[设计目标描述]

## 整体架构

[架构图或说明]
...
```

**说明**：架构类文档以设计目标开篇，无需元信息块

---

### 2.5 核心逻辑类

**适用场景**：策略核心逻辑、算法说明、版本迭代

**头部格式**：

```markdown
# [策略名称]核心逻辑 [版本号]

## 📊 策略概览

[策略概述]

---

## [章节标题]
...
```

**说明**：
- 使用emoji增强章节可读性
- 版本迭代文档需包含版本对比章节

---

### 2.6 阶段性总结类（strategy_summaries目录）

**适用场景**：策略阶段总结、版本快照

**头部格式**：

```markdown
# [策略名称]阶段总结

> **生成日期**：YYYY-MM-DD
> **Git Commit**：`commit_hash`
> **复现方式**：`git checkout xxx` 后运行 `[脚本路径]`

---

## 1. 策略概述
...
```

**必填字段**：
- 生成日期：快照生成日期
- Git Commit：代码版本hash
- 复现方式：如何复现该版本的完整命令

---

## 3. Git可复现性规范

### 3.1 核心原则

> **所有实验、分析结果必须可通过Git历史精确复现**

### 3.2 必须记录的信息

| 信息类型 | 记录位置 | 示例 |
|----------|----------|------|
| 配置文件 | 元信息块 | `config_simple.yaml` |
| 代码版本 | 元信息块或正文 | `ca933e4` |
| 实验脚本 | 实验信息表 | `rotation/simple_rotation.py` |
| 数据范围 | 元信息块 | `2020-01-10 ~ 2026-06-05` |

### 3.3 复现命令示例

```bash
# 切换到指定版本
git checkout ca933e4

# 运行实验脚本
python rotation/simple_rotation.py --config rotation/config_simple.yaml
```

---

## 4. 内容结构规范

### 4.1 章节编号

- 主章节：`## 1.`、`## 2.`、`## 3.`
- 子章节：`### 1.1`、`### 1.2`
- 段落要点：使用有序或无序列表

### 4.2 分隔线使用

- 元信息块与正文之间：使用 `---` 分隔
- 不同主题章节之间：可选使用 `---` 分隔

### 4.3 表格格式

```markdown
| 列名1 | 列名2 | 列名3 |
|------|------|------|
| 内容1 | 内容2 | 内容3 |
```

- 表头使用粗体或自然加粗
- 内容左对齐，数值列可右对齐

### 4.4 代码块格式

```markdown
```python
# 代码示例
def example():
    pass
\```
```

- 指定语言类型
- 关键代码需有注释说明

---

## 5. 文档存放目录

### 5.1 目录结构

```
docs/
├── YYYYMMDD_文档名称.md        # 通用文档
├── experiments/                 # 实验记录
│   └── YYYYMMDD_XXX_实验名称.md
├── strategy_summaries/          # 阶段性总结
│   └── YYYYMMDD_策略快照_hash.md
└── 文档创建规范.md              # 本规范文档（例外：无日期前缀）
```

### 5.2 目录选择原则

| 文档类型 | 存放目录 |
|----------|----------|
| 策略分析、调研报告 | docs/ |
| 实验记录、对比测试 | docs/experiments/ |
| 策略阶段总结、版本快照 | docs/strategy_summaries/ |

---

## 6. 例外情况

### 6.1 规范文档本身

- 规范文档不使用日期前缀
- 文件名：`文档创建规范.md`

### 6.2 README文件

- 目录说明文件命名为 `README.md`
- 无需日期前缀

### 6.3 从其他位置迁移的文档

- 如无法确定原始创建日期，使用迁移日期
- 在元信息中注明"迁移自[原位置]"

---

## 7. 检查清单

创建新文档时，确认以下事项：

- [ ] 文件名符合 `YYYYMMDD_中文名称.md` 格式
- [ ] 头部元信息完整（根据文档类型）
- [ ] Git可复现信息已记录（commit hash、配置文件、脚本路径）
- [ ] 存放在正确的目录
- [ ] 章节编号规范
- [ ] 代码块指定语言类型
- [ ] 分隔线使用恰当