# 添加新作品数据指南

本文档详细介绍了如何为 Sparkle 项目添加新的文学作品数据。无论你是程序员还是非程序员，都可以通过不同方式为项目贡献新的文学作品人物关系数据。

## 目录

1. [对于非程序员](#对于非程序员)
2. [基本流程](#基本流程)
3. [数据结构详解](#数据结构详解)
4. [目录结构](#目录结构)
5. [数据文件格式](#数据文件格式)
6. [示例](#示例)
7. [数据准备工具](#数据准备工具)
8. [常见问题](#常见问题)

## 对于非程序员

如果你不熟悉 Git、GitHub 或编程，但希望为 Sparkle 添加新的文学作品数据，你可以通过以下方式：

### GitHub Issues 提需求

1. 访问 [GitHub Issues](https://github.com/DeadPoetSpoon/sparkle/issues) 页面
2. 点击 "New Issue" 按钮创建新 Issue
3. 在标题中明确说明你想要添加的作品名称
4. 在描述中提供以下信息：
   - 作品名称和作者
   - 主要人物列表（姓名、性别、别名）
   - 主要人物关系（父子、夫妻、师徒等）
   - 你使用的版本/译本信息
   - 任何其他相关信息
5. **重要**：记得添加 `book-wanted` 标签

符合要求的请求会被社区中的好心人或作者处理，将你的数据添加到项目中。

### Gitee Issues（国内用户）

对于国内用户，也可以通过 Gitee 提需求：

1. 访问 [Gitee Issues](https://gitee.com/DeadPoetSpoon/sparkle/issues)
2. 创建新的 Issue
3. 提供与上述相同的信息

**注意**：请不要在 Gitee 提交 Pull Request，所有代码贡献请通过 GitHub 进行。

### 你可以提供的数据形式

即使你不懂编程，你仍然可以提供有价值的信息：
- 小说人物列表（Excel、Word 或文本文件）
- 人物关系图（手绘、思维导图或任何图表）
- 人物关系描述（自然语言描述）
- 小说章节分析

## 基本流程

添加新作品数据的基本流程如下：

1. **创建书籍目录**：在 `data/` 目录下创建新的书籍目录
2. **创建版本索引**：在书籍目录下创建 `index-zh.js` 文件
3. **创建人物数据**：在书籍目录下创建版本数据文件（如 `default.js`）
4. **更新作者索引**：在 `data/index-zh.js` 中添加或更新作者和作品信息
5. **测试验证**：在本地运行项目，验证数据是否正确加载
6. **提交贡献**：通过 Pull Request 提交你的贡献

## 数据结构详解

Sparkle 使用三层数据结构来组织作品数据：

### 第一层：作者索引 (`data/index-zh.js`)
- 包含所有作者的基本信息
- 每个作者可以有多部作品
- 用于生成页面的作者和作品下拉菜单

### 第二层：版本索引 (`data/[book-id]/index-zh.js`)
- 包含特定作品的所有可用版本
- 每个版本可以有多个翻译或改编
- 用于生成版本选择菜单

### 第三层：人物关系数据 (`data/[book-id]/[version].js`)
- 包含具体的人物节点和关系边
- 使用 Cytoscape.js 的图数据结构
- 直接用于可视化渲染

## 目录结构

```
data/
├── index-zh.js                    # 作者和作品索引
└── [book-id]/                     # 书籍目录（使用唯一ID）
    ├── index-zh.js                # 版本索引
    └── [version].js               # 人物关系数据（如 default.js）
```

### 命名规范
- `book-id`：书籍唯一标识符，建议使用时间戳格式（如 `202603262212`）
- `version`：版本标识符，如 `default`、`version1` 等

## 数据文件格式

### 1. 作者索引文件格式 (`data/index-zh.js`)

```javascript
export default [
  {
    id: "202603262231",                    // 作者唯一ID
    name: "费奥多尔·米哈伊洛维奇·陀思妥耶夫斯基", // 作者姓名
    biography: "1821年11月11日—1881年2月9日", // 作者生平
    description: "到后来，他竟作为罪孽深重的罪人，同时也是残酷的拷问官而出现了...", // 作者介绍
    books: [                               // 作品列表
      {
        id: "202603262212",                // 作品唯一ID
        name: "卡拉马佐夫兄弟",             // 作品名称
      },
      {
        id: "202603262213",
        name: "群魔",
      }
    ]
  }
];
```

### 2. 版本索引文件格式 (`data/[book-id]/index-zh.js`)

```javascript
export default [
  {
    version: "default",                    // 版本标识符
    name: "荣如德-上海译文-2012",           // 版本显示名称
    description: "不错~不错~",              // 版本描述（可选）
  }
  // 可以添加更多版本
];
```

### 3. 人物关系数据格式 (`data/[book-id]/[version].js`)

```javascript
export default [
  // 节点（人物）
  {
    data: {
      id: "a1",                            // 人物唯一ID
      name: "费奥多尔·巴甫洛维奇·卡拉马佐夫", // 人物姓名
      gender: "男",                         // 性别（男/女）
      nickname: ["老卡拉马佐夫"],           // 别名列表（可选）
      // 其他自定义字段...
    }
  },
  
  // 边（关系）
  {
    data: {
      id: "e1",                            // 关系唯一ID
      source: "a1",                        // 源节点ID
      target: "a2",                        // 目标节点ID
      name: "父子关系",                     // 关系描述
      // 其他自定义字段...
    }
  }
];
```

## 示例

### 示例：为《红楼梦》添加数据

#### 1. 创建书籍目录
```
data/
└── 202501010001/          # 《红楼梦》目录
```

#### 2. 创建版本索引 (`data/202501010001/index-zh.js`)
```javascript
export default [
  {
    version: "default",
    name: "人民文学出版社-2008",
    description: "经典版本",
  }
];
```

#### 3. 创建人物数据 (`data/202501010001/default.js`)
```javascript
export default [
  // 人物节点
  {
    data: {
      id: "h1",
      name: "贾宝玉",
      gender: "男",
      nickname: ["宝玉", "怡红公子"],
    }
  },
  {
    data: {
      id: "h2",
      name: "林黛玉",
      gender: "女",
      nickname: ["黛玉", "潇湘妃子"],
    }
  },
  {
    data: {
      id: "h3",
      name: "薛宝钗",
      gender: "女",
      nickname: ["宝钗", "蘅芜君"],
    }
  },
  
  // 关系边
  {
    data: {
      id: "r1",
      source: "h1",
      target: "h2",
      name: "表兄妹",
    }
  },
  {
    data: {
      id: "r2",
      source: "h1",
      target: "h3",
      name: "表姐弟",
    }
  }
];
```

#### 4. 更新作者索引 (`data/index-zh.js`)
```javascript
export default [
  // 原有作者...
  {
    id: "202501010000",
    name: "曹雪芹",
    biography: "约1715年—约1763年",
    description: "清代小说家，《红楼梦》的作者...",
    books: [
      {
        id: "202501010001",
        name: "红楼梦",
      }
    ]
  }
];
```



## 数据准备工具

### 手动准备
对于小型作品，可以直接编辑 JSON 文件创建数据。

### 推荐工具
1. **表格工具**：使用 Excel 或 Google Sheets 整理数据后导出为 JSON
2. **可视化工具**：使用 draw.io 或 Lucidchart 绘制关系图后提取数据
3. **脚本工具**：使用 Python 或 JavaScript 脚本处理现有数据

### 数据转换示例（Python）
```python
import json

# 示例：从CSV转换
characters = [
    {"id": "c1", "name": "张三", "gender": "男"},
    {"id": "c2", "name": "李四", "gender": "女"}
]

relationships = [
    {"id": "r1", "source": "c1", "target": "c2", "name": "夫妻"}
]

# 组合数据
elements = []
for char in characters:
    elements.append({"data": char})
for rel in relationships:
    elements.append({"data": rel})

# 保存为JS文件
with open("default.js", "w", encoding="utf-8") as f:
    f.write("export default ")
    json.dump(elements, f, ensure_ascii=False, indent=2)
```

## 常见问题

### Q1: ID 命名有什么要求？
A: ID 应该：
- 在文件中保持唯一性
- 使用字母数字组合
- 避免特殊字符
- 建议使用有意义的缩写（如 `jby` 代表贾宝玉）

### Q2: 可以添加自定义字段吗？
A: 是的，你可以在 `data` 对象中添加任意字段，例如：
```javascript
{
  data: {
    id: "c1",
    name: "角色名",
    custom_field: "自定义值",  // 自定义字段
    age: 25,                   // 自定义字段
    role: "主角"               // 自定义字段
  }
}
```

### Q3: 如何处理复杂的人物关系？
A: 对于复杂关系：
1. 使用多种关系类型（父子、夫妻、师徒等）
2. 可以在关系名称中详细描述
3. 考虑添加关系强度属性
4. 使用 `group` 字段区分节点和边

### Q4: 如何测试添加的数据？
A: 测试步骤：
1. 启动本地服务器
2. 访问项目页面
3. 选择添加的作者和作品
4. 验证图谱是否正确显示
5. 点击节点查看详细信息

### Q5: 数据量很大怎么办？
A: 对于大型作品：
1. 分版本处理不同章节或部分
2. 使用脚本批量处理数据
3. 考虑数据分片加载
4. 确保性能优化

## 贡献准则

1. **数据准确性**：确保人物姓名和关系准确无误
2. **格式规范**：严格遵循上述数据格式
3. **代码质量**：保持代码整洁，添加适当的注释
4. **文档完整**：在 Pull Request 中描述添加的作品信息
5. **测试充分**：在提交前进行充分测试

## 获取帮助

如果在添加数据过程中遇到问题：
1. 查看现有数据文件作为参考
2. 在 GitHub Issues 中提问
3. 参考 Cytoscape.js 文档了解数据结构
4. 联系项目维护者

## 总结

### 本文新增内容

本文档在原有的技术性指南基础上，特别增加了针对**非程序员用户**的贡献方式：

1. **GitHub Issues 提需求**
   - 通过 GitHub Issues 页面提交作品数据需求
   - 需要提供作品名称、作者、人物列表、关系等基本信息
   - **重要**：记得添加 `book-wanted` 标签
   - 等待社区中的好心人或作者处理你的请求

2. **Gitee Issues（国内用户）**
   - 国内用户可通过 Gitee 提交需求
   - 提供与 GitHub Issues 相同的信息
   - **注意**：请不要在 Gitee 提交 Pull Request，所有代码贡献请通过 GitHub 进行

3. **非程序员可提供的数据形式**
   - 小说人物列表（Excel、Word 或文本文件）
   - 人物关系图（手绘、思维导图或任何图表）
   - 人物关系描述（自然语言描述）
   - 小说章节分析

### 贡献方式对比

| 用户类型 | 推荐方式 | 技术要求 | 处理速度 |
|---------|---------|---------|---------|
| 程序员 | Pull Request | 较高 | 快（直接添加） |
| 非程序员 | Issues 提需求 | 低 | 中（等待他人实现） |
| 国内用户 | Gitee Issues | 低 | 中（需要同步到 GitHub） |

### 核心要点

- **标签必加**：无论通过哪个平台提需求，都请加上 `book-wanted` 标签
- **信息完整**：提供尽可能完整和准确的作品信息
- **平台区分**：GitHub 用于代码贡献，Gitee 仅用于国内用户提需求
- **社区互助**：相信社区的力量，你的需求可能会被其他热心用户实现

### 愿景

我们希望 Sparkle 成为一个真正社区驱动的项目，让每个人都能参与进来：
- 程序员可以通过技术贡献实现数据
- 文学爱好者可以通过提需求和提供信息参与
- 研究者可以分享他们的分析成果
- 读者可以享受更丰富的文学作品可视化

**无论你是谁，都能为 Sparkle 的璀璨星空增添一颗星星！** ✨

---

**感谢你的贡献！** 每一份数据都能让 Sparkle 更加璀璨，帮助更多人探索文学作品的魅力。

> "那些星星点点的关系，构成了文学宇宙中最美的星辰。" 🌟