# 数据集上传规范

BioData Agent 接受 UTF-8 编码的 JSON 数据集元数据。建议每条记录至少提供 `dataset_name`；缺名称的记录不会被拒收，但可能无法被展示或检索到。其余字段可按实际情况填写。

上传内容会写入 `database/external/`，不会写入或覆盖 `database/base/` 基础库。

## 上传方式

### 网页上传

1. 启动 BioData Agent。
2. 进入“数据集浏览”。
3. 在数据集列表上方的上传区，点击选择或拖入 `.json` 文件。
4. 可选填写来源名称。
5. 点击“上传”。

上传成功后，记录会立即出现在来源筛选、数据集浏览和智能查询中，无需重启服务。

### 手动放入目录

将 JSON 文件复制到项目的 `database/external/`，然后重启服务。适合批量维护或预先整理好的来源快照。

不要把外部数据放入 `database/base/`。

## 支持的 JSON 结构

### 记录数组

```json
[
  {
    "dataset_name": "Human lung single-cell atlas",
    "species": "Human",
    "tissue": "lung"
  },
  {
    "dataset_name": "Mouse brain scRNA-seq",
    "species": "Mouse",
    "tissue": "brain",
    "has_raw_data": true
  }
]
```

### 带来源名称的对象

```json
{
  "source": "Example Lab Catalog",
  "records": [
    {
      "dataset_name": "Human lung cancer atlas",
      "species": "Human",
      "tissue": "lung",
      "disease": "lung cancer"
    }
  ]
}
```

项目目录中提供了可直接复制的[数据集模板](数据集模板.json)。

## 推荐字段

| 字段 | 必填 | 类型 | 说明 | 示例 |
|---|---|---|---|---|
| `dataset_name` | 建议必填 | 字符串 | 数据集名称 | `"Human lung atlas"` |
| `species` | 建议填写 | 字符串 | 英文通用物种名 | `"Human"`、`"Mouse"` |
| `tissue` | 可选 | 字符串 | 组织或器官 | `"lung"` |
| `disease` | 可选 | 字符串 | 疾病或状态；健康样本可留空 | `"lung cancer"` |
| `chemistry` | 可选 | 字符串 | 实验技术或建库方法 | `"scRNA-seq"` |
| `platform` | 可选 | 字符串 | 平台名称 | `"Chromium"`、`"Visium"` |
| `count` | 可选 | 数字或字符串 | 细胞、细胞核、spot 或样本数量 | `12000` |
| `unit` | 可选 | 字符串 | `count` 的单位 | `"cells"` |
| `has_raw_data` | 可选 | 布尔值 | 是否明确提供 FASTQ 原始数据 | `true`、`false` |
| `published_date` | 可选 | 字符串 | ISO 日期，用于时间筛选 | `"2024-06-30"` |
| `url` | 可选 | 字符串 | 数据集页面或公开下载地址 | `"https://..."` |
| `description` | 可选 | 字符串 | 简要说明 | `"Tumor and adjacent tissue"` |
| `source` | 可选 | 字符串 | 单条记录的来源名称 | `"Example Lab Catalog"` |

为获得稳定筛选结果，物种、组织和疾病建议使用英文通用名。中文内容可以上传和浏览，但按物种或组织条件筛选时可能匹配不上。

## 字段兼容

推荐使用上表中的标准字段。为兼容常见来源，系统也能识别一部分别名，例如：

- 名称：`name`、`title`、`dataset_title`
- 物种：`organism`、`sample_species`
- 组织：`organ`、`tissue_type`、`anatomical_site`
- 疾病：`condition`、`diagnosis`、`phenotype`
- 技术：`technology`、`assay`、`library_prep`
- 数量：`sample_size`、`n_cells`、`n_spots`
- 链接：`download_url`、`link`、`dataset_url`

新文件仍建议使用标准字段，减少不同系统之间的歧义。

## 来源名称优先级

同一次网页上传中，来源名称按以下顺序确定：

1. 单条记录自己的 `source`
2. 网页上传表单填写的来源
3. JSON 外层对象的 `source`
4. 默认值“用户上传”

同一个文件里的不同记录可以各自标注不同来源。上传完成后会显示每个来源各有多少条。

## 上传结果与校验提示

上传完成后会显示：

- 保存后的文件名
- 解析出的记录数
- 各来源的记录数
- 缺少数据集名称或物种名不规范等提示

这些提示不会阻止其他有效记录入库。某个外部 JSON 文件损坏时，系统会跳过该文件，其他来源仍可正常使用。

每个上传文件都会被加上时间戳重命名，因此不会覆盖已有文件。

## 删除已上传数据

1. 停止服务，或确认当前没有其他人正在上传。
2. 在 `database/external/` 中找到对应 JSON 文件。
3. 核对文件内容和来源名称后删除。
4. 重启服务。

不要批量删除整个 `database/external/`，其中还可能包含随项目提供的公开来源快照。

## 数据与安全边界

- 只上传可以在当前环境中存储和使用的公开数据集元数据。
- 不要上传 API Key、账号凭据、私有临床数据、未公开研究材料或受限下载内容。
- URL 是元数据快照，不代表目标地址会永久可用。
- `has_raw_data=true` 应只在已确认存在 FASTQ 时填写；未知时建议省略，不要猜测。