> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://helpdesk.ggcircuit.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# 👥 ggLeap 用户导入

## 1. 🧭 介绍

将用户导入 ggLeap 需要配置 CSV 输入字段如何映射到 ggLeap 内部用户数据库。本指南说明支持的用户字段以及如何设置导入映射配置。

---

## 2. 📋 支持的用户字段

以下字段目前支持导入用户：

* `UniversityUserId`（仅限大学和 K–12 中心）
* `Email`
* `Username`
* `FirstName`
* `LastName`

---

## 3. 📦 导入流程

ggLeap 的导入功能支持用户的**创建**、**更新**和**归档**。

* 如果您的 CSV 使用自定义列名，请向 ggCircuit 支持团队提交示例以帮助配置映射。
* 或者，您可以使用 API 自己配置映射（目前没有 UI 配置可用）。

---

## 4. ⚙️ 映射配置

### 4.1 分隔符设置

默认分隔符是 `,`，但可以通过指定 `null` 将其设置为 `"auto-detect"`。

---

### 4.2 映射列：CSV → ggLeap 字段

示例映射配置：

```
{
"Config": {
"Mappings": {
"UniversityUserId": {
"TargetFieldName": "UniversityUserId",
"IgnoreField": false,
"RequireValue": false,
"SourceHeaderName": "UniversityIdNumber"
},
"MembershipPlaytime": {
"TargetFieldName": "MembershipPlaytime",
"IgnoreField": false,
"RequireValue": false,
"SourceHeaderName": "Playtime",
"IsCustomField": false
},
"Membership Start Date": {
"TargetFieldName": "Membership Start Date",
"IgnoreField": false,
"RequireValue": false,
"SourceHeaderName": "MembershipStartDate",
"IsCustomField": true
},
"Membership End Date": {
"TargetFieldName": "Membership End Date",
"IgnoreField": false,
"RequireValue": false,
"SourceHeaderName": "MembershipEndDate",
"IsCustomField": true
},
"Affiliation": {
"TargetFieldName": "Affiliation",
"IgnoreField": false,
"RequireValue": false,
"SourceHeaderName": null,
"IsCustomField": true
}
},
"Enabled": true,
"Delimiter": null,
"DateFormats": ["yyyy-MM-dd"],
"BooleanValues": {
"FalseValues": ["N", "F", "No", "False", "0"],
"TrueValues": ["Y", "T", "Yes", "True", "1"]
},
"NullValues": ["NULL"]
}
}
```

**字段参考：**

* `TargetFieldName`：ggLeap 中的目标字段。
* `IgnoreField`：设置为 true 可从导入中排除此字段。
* `RequireValue`：指示是否需要非空值。
* `SourceHeaderName`：源 CSV 中字段的名称。
* `IsCustomField`：对于 ggLeap 中本地不存在的字段，设置为 `true`（确保这些字段存在于用户详情配置中）。

---

### 4.3 已删除字段

* `true`：归档用户
* `false`：取消归档用户

---

### 4.4 MembershipPlaytime

定义为导入用户提供的 Gamepass 游戏时间。

---

### 4.5 会员日期

为每个用户配置 Gamepass `start` 和 `end` 日期。

---

### 4.6 更新 CSV 导入配置

使用**更新 CSV 导入配置 API** 来修改映射。

---

### 4.7 获取当前配置

使用**获取 CSV 导入配置 API** 来获取现有配置。

---

### 4.8 取消导入作业

要中止运行中的导入，使用**取消用户导入作业 API**。

---

## 5. ✅ 布尔值

true/false 字段的接受值：

* **True**：`Y`、`T`、`Yes`、`True`、`1`
* **False**：`N`、`F`、`No`、`False`、`0`

---

## 6. 📅 日期格式

CSV 中支持的日期格式：

* `yyyy-MM-dd`
* `dd/MM/yyyy`
* `MM/dd/yy`
* `dd.MM.yyyy`

---

## 7. 🗺️ CSV 列映射提示

使用示例格式将源 CSV 标头映射到预期的 ggLeap 字段。您可以根据中心的结构和数据自定义此映射。

---

## 🧠 额外的导入逻辑与说明

### 匹配现有用户

1. 尝试通过 `UniversityIdNumber`（映射到 `StudentId`）查找用户。
2. 如果未找到，尝试通过 `EmailAddress` 匹配。
3. 如果仍未找到：

* 如果另一个中心具有相同电子邮件：记录**冲突**，跳过该记录。
* 如果当前中心存在相同用户名：记录**冲突**，跳过该记录。
* 否则：**创建新用户**，可选择分配 Gamepass。

### 更新现有用户

* 更新 CSV 中的所有字段。
* 在更新 `Username` 之前，检查当前中心的唯一性。
* 在更新 `EmailAddress` 之前，检查全局 ggLeap 的唯一性。
* 如果用户已归档，设置为已删除。
* 如果会员值更改，更新或删除 Gamepass：

* 如果 `MembershipStartDate` 是 `NULL`：删除 Gamepass。
* 否则：替换为新的 `MembershipPlaytime`。

### 错误处理与日志

* 所有错误应在**导入日志**中记录。
* 如果发生 5+ 个内部错误，中止导入流程。
* 对于每个更新/添加的用户，记录操作。
* 每 2–5 秒更新**导入状态/摘要**。